@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
@@ -0,0 +1,130 @@
1
+ /** An agent's own mail, read without acknowledging anything: the messaging layer's `messaging:mail` view operation
2
+ * (docs/desktop-cli-api.md, "Mail", `mailApi: 1`), run as `oats operation run messaging:mail --home <abs> [--arg
3
+ * limit=…] [--arg cursor=…] [--arg conversation=…] [--server <id>] --json`. Any messaging provider may answer it;
4
+ * oats.aweb is the first. The provider's values are opaque strings here: identity, message and conversation ids,
5
+ * team labels. Nothing in this module parses a provider-specific shape.
6
+ *
7
+ * The run's `result` is `{documents, mail}`: `documents` is the plain rendering every view carries, `mail` the
8
+ * structured field this module decodes, exactly as the contract states it (shapes are closed: an unknown key, a
9
+ * value outside its set or a bound passed is the whole answer unreadable, never a partial guess). An answer that
10
+ * says it acknowledged (`acknowledges` other than false) is unreadable too: a client never shows mail read by
11
+ * marking it read.
12
+ *
13
+ * Pure: no DOM, no IO, never throws. Shared by both clients (the Terminal UI renders the same sheet later). */
14
+ import { NOT_NOTE_TEXT } from './display-text.mjs';
15
+
16
+ export const MAIL_OPERATION = 'messaging:mail';
17
+ /** What a client asks for at a time (the contract's default) and at most. */
18
+ export const MAIL_PAGE = 50, MAIL_MAX_LIMIT = 200;
19
+ /** A body's bound, in UTF-8 bytes: past it the provider cuts and says `truncated: true`. */
20
+ export const MAIL_BODY_BYTES = 16 * 1024;
21
+ export const VERIFICATIONS = Object.freeze(['verified', 'unverified', 'failed', 'unknown']);
22
+ export const PRIORITIES = Object.freeze(['normal', 'high', 'unknown']);
23
+ export const DIRECTIONS = Object.freeze(['received', 'sent']);
24
+ export const PARTIAL_OLDEST_FIRST = 'oldest-first-only';
25
+
26
+ const MAIL_KEYS = ['mailApi', 'acknowledges', 'observedAt', 'identities', 'messages', 'conversations', 'hasMore', 'nextCursor'];
27
+ const IDENTITY_KEYS = ['team', 'alias', 'identity', 'primary', 'error'];
28
+ const MESSAGE_KEYS = ['id', 'conversationId', 'threadTitle', 'direction', 'team', 'from', 'to', 'subject', 'body', 'truncated',
29
+ 'createdAt', 'readByAgent', 'encrypted', 'verification', 'priority'];
30
+ const PARTY_KEYS = ['alias', 'address', 'identity'];
31
+ const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}(?::\d{2}(?:\.\d{1,9})?)?(?:Z|[+-]\d{2}:\d{2})$/;
32
+
33
+ const record = v => !!v && typeof v === 'object' && !Array.isArray(v) && Object.getPrototypeOf(v) === Object.prototype;
34
+ const exact = (v, keys) => record(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
35
+ /** Text: the contract bounds a body (16 KiB), a page (200 messages) and the whole result (256 KiB, which the transport
36
+ * bounds again), never a subject, a title, an alias or an id: those are any string, and only their display is cut. */
37
+ const text = (v, empty = false) => typeof v === 'string' && (empty || v.length > 0);
38
+ /** An opaque provider value (an id, a label, an alias): any non-empty string, never parsed. */
39
+ const opaque = v => text(v);
40
+ const iso = v => typeof v === 'string' && v.length <= 40 && ISO.test(v) && !Number.isNaN(Date.parse(v));
41
+ const utf8Bytes = s => {
42
+ let n = 0;
43
+ for (const ch of s) { const c = ch.codePointAt(0); n += c < 0x80 ? 1 : c < 0x800 ? 2 : c < 0x10000 ? 3 : 4; }
44
+ return n;
45
+ };
46
+
47
+ function party(p) {
48
+ return exact(p, PARTY_KEYS) && opaque(p.alias) && (p.address === null || opaque(p.address)) && opaque(p.identity);
49
+ }
50
+ /** The conversations of one identity that couldn't be read (contract v2's details, Juan's side's ask): present only with
51
+ * the error `conversation-unreadable`, absent otherwise; opaque ids in the order the read met them. It may be empty (a
52
+ * message with no conversation isn't named) and may list fewer than failed (its tail goes first under the 256 KiB bound). */
53
+ const UNREADABLE = 'unreadableConversations';
54
+ function identity(i) {
55
+ const listed = record(i) && Object.hasOwn(i, UNREADABLE);
56
+ if (listed && !(i.error === 'conversation-unreadable' && Array.isArray(i[UNREADABLE]) && i[UNREADABLE].every(opaque))) return false;
57
+ return exact(i, listed ? [...IDENTITY_KEYS, UNREADABLE] : IDENTITY_KEYS) && opaque(i.team) && opaque(i.alias) && opaque(i.identity) && typeof i.primary === 'boolean'
58
+ // An identity's error: the provider's word for it (oats.aweb: identity-missing, identity-unreadable, no-mail-read,
59
+ // threads-unreadable, conversation-unreadable, too-many-threads), opaque: a client words the ones it knows.
60
+ && (i.error === null || opaque(i.error));
61
+ }
62
+ function message(m) {
63
+ return exact(m, MESSAGE_KEYS) && opaque(m.id) && (m.conversationId === null || opaque(m.conversationId)) && text(m.threadTitle, true)
64
+ && DIRECTIONS.includes(m.direction) && opaque(m.team) && party(m.from) && party(m.to) && text(m.subject, true)
65
+ && typeof m.body === 'string' && utf8Bytes(m.body) <= MAIL_BODY_BYTES && typeof m.truncated === 'boolean' && iso(m.createdAt)
66
+ && typeof m.readByAgent === 'boolean' && typeof m.encrypted === 'boolean' && VERIFICATIONS.includes(m.verification)
67
+ && PRIORITIES.includes(m.priority);
68
+ }
69
+
70
+ /** The `mail` field of a `messaging:mail` run, decoded; null when the answer is not the contract's. The run is the
71
+ * `oats operation run --json` result (`{operationsApi: 2, operation, result, …}`).
72
+ * Returns `{ observedAt, identities, messages, partial: Set<conversationId>, hasMore, nextCursor }`. */
73
+ export function mailAnswer(run) {
74
+ if (!record(run) || run.operationsApi !== 2 || run.operation !== MAIL_OPERATION) return null;
75
+ const r = run.result;
76
+ if (!exact(r, ['documents', 'mail']) || !Array.isArray(r.documents)) return null;
77
+ const d = r.mail;
78
+ if (!exact(d, MAIL_KEYS) || d.mailApi !== 1 || d.acknowledges !== false || !iso(d.observedAt)) return null;
79
+ if (!Array.isArray(d.identities) || !d.identities.every(identity)) return null;
80
+ if (!Array.isArray(d.messages) || d.messages.length > MAIL_MAX_LIMIT || !d.messages.every(message)) return null;
81
+ if (!Array.isArray(d.conversations) || !d.conversations.every(c => exact(c, ['id', 'partial']) && opaque(c.id) && (c.partial === null || c.partial === PARTIAL_OLDEST_FIRST))) return null;
82
+ if (typeof d.hasMore !== 'boolean' || !(d.nextCursor === null || opaque(d.nextCursor))) return null;
83
+ // More to read needs the cursor that reads it; a cursor with nothing more is the provider's slip, and dropped.
84
+ if (d.hasMore && d.nextCursor === null) return null;
85
+ const keys = d.messages.map(messageKey);
86
+ if (new Set(keys).size !== keys.length) return null;
87
+ return {
88
+ observedAt: d.observedAt,
89
+ identities: structuredClone(d.identities),
90
+ messages: structuredClone(d.messages),
91
+ partial: new Set(d.conversations.filter(c => c.partial === PARTIAL_OLDEST_FIRST).map(c => c.id)),
92
+ hasMore: d.hasMore,
93
+ nextCursor: d.hasMore ? d.nextCursor : null,
94
+ };
95
+ }
96
+
97
+ /** A message's identity across pages: its team and its id (ids are the provider's, per identity). */
98
+ export const messageKey = m => JSON.stringify([m.team, m.id]);
99
+
100
+ /** Whether a cursor can travel as an operation argument (cli-adapter.mjs operationArgs: one line of at most 1024
101
+ * characters). One that can't is no way to the next page from this client: the sheet offers none. */
102
+ export const cursorUsable = c => typeof c === 'string' && c.length > 0 && c.length <= 1024 && !/[\x00-\x1f\x7f]/.test(c);
103
+
104
+ /** The arguments of one read: the first page (no cursor) or the page after `cursor`. Only declared arguments. */
105
+ export function mailArgs({ cursor = null, limit = MAIL_PAGE } = {}) {
106
+ const n = Number.isInteger(limit) ? Math.min(Math.max(limit, 1), MAIL_MAX_LIMIT) : MAIL_PAGE;
107
+ return { limit: String(n), ...(cursorUsable(cursor) ? { cursor } : {}) };
108
+ }
109
+
110
+ /** A body as display lines: line breaks kept (CRLF and lone CR as one), tabs as spaces, every other character a note
111
+ * may not hold (control characters, bidi overrides and isolates, zero-width and tag characters) replaced with U+FFFD,
112
+ * so the reader sees something was there. For display only: never evidence of who wrote it. Trailing blank lines go. */
113
+ export function mailBodyLines(body) {
114
+ if (typeof body !== 'string') return [];
115
+ const every = new RegExp(NOT_NOTE_TEXT.source, 'gu');
116
+ const lines = body.replace(/\r\n?/g, '\n').split('\n').map(line => line.replace(/\t/g, ' ').replace(every, '\uFFFD'));
117
+ while (lines.length && !lines[lines.length - 1].trim()) lines.pop();
118
+ return lines;
119
+ }
120
+
121
+ /** How much of one line of provider text is shown: the rest is cut, with an ellipsis. */
122
+ export const MAIL_LINE_SHOWN = 512;
123
+ /** One line of provider text (a subject, an alias, a title, an identity's error) as shown: line breaks as spaces, the
124
+ * rest as mailBodyLines does, cut past MAIL_LINE_SHOWN characters (never inside a surrogate pair). */
125
+ export function mailLine(value) {
126
+ const line = mailBodyLines(typeof value === 'string' ? value.replace(/[\r\n]+/g, ' ') : '').join(' ').trim();
127
+ if (line.length <= MAIL_LINE_SHOWN) return line;
128
+ const cut = /[\uD800-\uDBFF]/.test(line[MAIL_LINE_SHOWN - 1]) ? MAIL_LINE_SHOWN - 1 : MAIL_LINE_SHOWN;
129
+ return `${line.slice(0, cut)}…`;
130
+ }
@@ -22,6 +22,9 @@ export const CLIENT_OWN_CODES = Object.freeze([
22
22
  'E_APPLY_UNAVAILABLE', 'E_BACKEND_UNAVAILABLE', 'E_BUSY', 'E_FORBIDDEN_FRAME', 'E_INPUT_PREPARATION', 'E_INSTANCE_GONE',
23
23
  'E_INTENT_EXPIRED', 'E_OUTCOME_UNKNOWN', 'E_PREFLIGHT_INCOMPLETE', 'E_PREVIEW_UNAVAILABLE', 'E_SUPERSEDED', 'E_TARGET_CHANGED',
24
24
  'E_UNSUPPORTED_OPTION', 'E_WAKE_OUTCOME_UNKNOWN', 'E_WAKE_SAVE_FAILED',
25
+ // The kernel's code for a confirmed spawn into a sandbox (feature sandboxes, D-S1-4), listed only until
26
+ // this tree's kernel writes it: the sandboxes kernel change (S1) writes it and removes it from here.
27
+ 'E_SANDBOX_PLACEMENT',
25
28
  // Stop, start, restart and remove, and the plan a person confirms (a spawn's plan too).
26
29
  'E_LIFECYCLE_UNAVAILABLE', 'E_OPTION_UNAVAILABLE', 'E_PLAN_CHANGED', 'E_PLAN_EXPIRED', 'E_PLAN_LIMIT', 'E_PLAN_REQUIRED',
27
30
  'E_HOME_UNVERIFIED', 'E_START_UNCONFIRMED',
@@ -35,7 +38,8 @@ export const CLIENT_OWN_CODES = Object.freeze([
35
38
  // A terminal.
36
39
  'E_TERM_ATTACHMENT_FAILED', 'E_TERM_ATTACHMENT_INTERRUPTED', 'E_TERM_BAD_ARGS', 'E_TERM_BUSY', 'E_TERM_CAP',
37
40
  'E_TERM_CLOSE_PENDING', 'E_TERM_CLOSING', 'E_TERM_CONTEXT_CHANGED', 'E_TERM_FORBIDDEN_FRAME', 'E_TERM_INPUT_LIMIT',
38
- 'E_TERM_LEASE', 'E_TERM_NOT_READY', 'E_TERM_OPEN_FAILED', 'E_TERM_OUTPUT_LIMIT', 'E_TERM_PREPARE_TIMEOUT',
41
+ // The agent view's answer refused for the pane's mode (terminal-owner answer): in tmux's copy mode, or not readable.
42
+ 'E_TERM_IN_MODE', 'E_TERM_LEASE', 'E_TERM_MODE_UNKNOWN', 'E_TERM_NOT_READY', 'E_TERM_OPEN_FAILED', 'E_TERM_OUTPUT_LIMIT', 'E_TERM_PREPARE_TIMEOUT',
39
43
  'E_TERM_READY_TIMEOUT', 'E_TERM_REMOTE_GONE', 'E_TERM_REMOTE_NO_ANSWER', 'E_TERM_REMOTE_NO_SSH',
40
44
  'E_TERM_REMOTE_UNREACHABLE', 'E_TERM_REUSED', 'E_TERM_TRANSPORT',
41
45
  ].sort());
@@ -46,7 +46,7 @@ import { teamMembers } from './team-members.mjs';
46
46
  import { requireTerms } from './client-terms.mjs';
47
47
  import { ROSTER_WORKSPACE_KEY } from './cli-adapter.mjs';
48
48
  import { waitingClaim } from './waiting-on-you.mjs';
49
- import { sameWorkDeclared, withSameWorkGate } from './same-work.mjs';
49
+ import { relatedWorkDeclared, withRelatedWorkGate } from './related-work.mjs';
50
50
 
51
51
  /** Roots come ONLY from the kernel's observed `status.root`; before (or
52
52
  * without) an observation there is nothing to act on. No layout guess. */
@@ -311,19 +311,19 @@ export function deploymentEntry(info, primary) {
311
311
  }
312
312
 
313
313
  /** One deployment's own panel, as served before views. Each row carries whether its host declares
314
- * instance-same-work (#1577), stamped here and nowhere else (same-work.mjs `withSameWorkGate`): `held.cli` for
315
- * this computer's rows, and the group's host too for another machine's. */
314
+ * instance-related-work or instance-same-work, stamped here and nowhere else (related-work.mjs `withRelatedWorkGate`):
315
+ * `held.cli` for this computer's rows, and the group's host too for another machine's. */
316
316
  export function deploymentPanel(held, ws) {
317
317
  // Another machine's panel never says who made its `error`: the key is removed here whatever the panel carried.
318
318
  // A kept group's panel is made at the time it was read (#1124): a filtered read never makes it look newer.
319
319
  if (ws?.remote) {
320
320
  const { errorOrigin: _sent, ...panel } = remotePanel(ws.group, held.keptReadAt?.get?.(ws.group.id) ?? held.at);
321
- const declared = sameWorkDeclared(held.cli, ws.group);
322
- return { ...panel, instances: panel.instances.map((row) => withSameWorkGate(row, declared)), observedAt: null, refreshing: held.remoteCollecting };
321
+ const declared = relatedWorkDeclared(held.cli, ws.group);
322
+ return { ...panel, instances: panel.instances.map((row) => withRelatedWorkGate(row, declared)), observedAt: null, refreshing: held.remoteCollecting };
323
323
  }
324
324
  const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
325
- const declared = sameWorkDeclared(held.cli);
326
- const instances = (observed?.instances || []).map((row) => withSameWorkGate(row, declared)), kept = keptFailure(observed);
325
+ const declared = relatedWorkDeclared(held.cli);
326
+ const instances = (observed?.instances || []).map((row) => withRelatedWorkGate(row, declared)), kept = keptFailure(observed);
327
327
  return {
328
328
  workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
329
329
  team: null,
@@ -0,0 +1,84 @@
1
+ /** Which lines a roster draws: a child's line to its parent, and the dotted link between two top-level siblings
2
+ * (awebai/oats#1577 for the child's line; the related-work lines for both). The one rule, shared by the Desktop's
3
+ * sidebar and command palette and by the TUI; no client keeps a copy. No flag, no line.
4
+ *
5
+ * What a host reports (docs/desktop-cli-api.md):
6
+ * - A host that declares `instance-related-work` puts `relatedWork: true` on a row whose related work is bound to
7
+ * its current parent (a row with a `parentInstance`), or, for a row with no parent, to its current
8
+ * `siblingInstance` (the root the sibling was spawned relative to, itself possibly a sibling of another root). It
9
+ * leaves the key out otherwise, and puts no `sameWork` on any row.
10
+ * - An older host, which declares only `instance-same-work`, puts `sameWork: true` on a child bound to its parent,
11
+ * and nothing on a sibling. Relayed through a CLI that declares `instance-related-work` (`--server`), such a
12
+ * host's `sameWork` arrives as `relatedWork` instead; the host's own feature list still lacks the new feature.
13
+ * - A host with neither feature reports no flag.
14
+ * The kernel has already bound the flag to the current parent or sibling: a client reads `=== true` and nothing
15
+ * more, and never compares names.
16
+ *
17
+ * The gate: which of the two features a row's host declares. A local row: this computer's CLI. A remote row: what
18
+ * this CLI relays and what the host itself lists (composed-gate.mjs `hostAdvertises`, through
19
+ * server-probe-features), the lesser of the two: a CLI relays only the flag it knows. Unknown is not supported: an
20
+ * unread or failed probe declares nothing. panel-views.mjs `deploymentPanel` stamps the gate's answer on each row
21
+ * it serves as `relatedWorkKnown` (`withRelatedWorkGate`), the feature's name, present only when the host declares
22
+ * one; it is the client's own field, never the kernel's.
23
+ *
24
+ * Pure: no DOM, no Node builtin, so a page loads it as it is. */
25
+ import { hostAdvertises, PROBE_FEATURES_FEATURE } from './composed-gate.mjs';
26
+
27
+ export const RELATED_WORK_FEATURE = 'instance-related-work';
28
+ export const SAME_WORK_FEATURE = 'instance-same-work';
29
+
30
+ const advertises = (list, feature) => Array.isArray(list) && list.includes(feature);
31
+ /** The feature a feature list declares, the newer first, or null. */
32
+ const levelOf = (has) => (has(RELATED_WORK_FEATURE) ? RELATED_WORK_FEATURE : has(SAME_WORK_FEATURE) ? SAME_WORK_FEATURE : null);
33
+
34
+ /** Which related-work feature a row's host declares: `RELATED_WORK_FEATURE`, `SAME_WORK_FEATURE` or null. `group` is
35
+ * null for this computer's rows, else the remote roster group the rows came from. A remote host's answer is the
36
+ * lesser of this CLI's (which flag it relays) and the host's own list; this CLI must also relay the hosts' lists. */
37
+ export function relatedWorkDeclared(cli, group = null) {
38
+ if (!cli?.ok || !Array.isArray(cli.features)) return null;
39
+ const local = levelOf((feature) => advertises(cli.features, feature));
40
+ if (group === null || local === null) return local;
41
+ if (!advertises(cli.features, PROBE_FEATURES_FEATURE)) return null;
42
+ const host = levelOf((feature) => hostAdvertises(group, feature));
43
+ return host === null ? null : local === RELATED_WORK_FEATURE ? host : SAME_WORK_FEATURE;
44
+ }
45
+
46
+ /** A row with the gate's answer stamped: `relatedWorkKnown: <feature>` when `declared` names one of the two
47
+ * features, else no key. Whatever the row carried under that key is dropped first, so a host can never set it. */
48
+ export function withRelatedWorkGate(row, declared) {
49
+ const { relatedWorkKnown: _carried, ...rest } = row;
50
+ return declared === RELATED_WORK_FEATURE || declared === SAME_WORK_FEATURE ? { ...rest, relatedWorkKnown: declared } : rest;
51
+ }
52
+
53
+ /** A row the client made itself (a pending spawn's) has no stamp: it takes its parent's, since a child is on its
54
+ * parent's host (instance-tree.mjs `resolveLinkId` never resolves across hosts). `parent` is the row its
55
+ * `parentInstance` resolves to, or null. Such a row carries no flag, so it draws no line. */
56
+ export const withParentGate = (row, parent) => withRelatedWorkGate(row, parent?.relatedWorkKnown);
57
+
58
+ const hasParent = (row) => typeof row?.parentInstance === 'string' && row.parentInstance !== '';
59
+
60
+ /** Whether a child draws the line to its parent: its host reports it related to its parent. On a host that
61
+ * declares `instance-related-work`, `relatedWork === true`; on one that declares only `instance-same-work`,
62
+ * `sameWork === true` (or `relatedWork === true`, as a relaying CLI turns it). Any other host: never. A root has no
63
+ * parent line to draw: a row without a `parentInstance` answers false. */
64
+ export function drawsParentLine(row) {
65
+ if (!hasParent(row)) return false;
66
+ if (row.relatedWorkKnown === RELATED_WORK_FEATURE) return row.relatedWork === true;
67
+ if (row.relatedWorkKnown === SAME_WORK_FEATURE) return row.sameWork === true || row.relatedWork === true;
68
+ return false;
69
+ }
70
+
71
+ /** Whether a top-level row joins the sibling its `siblingInstance` names: its host declares
72
+ * `instance-related-work` and reports `relatedWork: true` on a row with no parent. An older host joins no sibling.
73
+ * Which row the link reaches, and whether it is drawn, is the tree's (instance-tree-view.mjs `treeConnectors`). */
74
+ export function drawsSiblingLink(row) {
75
+ return !hasParent(row) && row?.relatedWorkKnown === RELATED_WORK_FEATURE && row.relatedWork === true;
76
+ }
77
+
78
+ /** Whether a row reports related work at all, to its parent or to its sibling: the words a screen reader hears. */
79
+ export const relatedWork = (row) => drawsParentLine(row) || drawsSiblingLink(row);
80
+
81
+ /** The order of one parent's children, a comparator for a stable sort or a first key before another: the
82
+ * children that draw their parent line first, then those that don't. So a parent's line ends at its last
83
+ * joined child and never passes a child it doesn't join. Within each part the caller's own order stands. */
84
+ export const drawingFirst = (a, b) => Number(!drawsParentLine(a)) - Number(!drawsParentLine(b));
@@ -8,6 +8,7 @@ import { readIdentity } from "./workspace-views.mjs";
8
8
  import { sameRepo } from "./repo-moves.mjs";
9
9
  import { hostAdvertises } from "./composed-gate.mjs";
10
10
  import { PIN_FEATURE } from "./instance-tree.mjs";
11
+ import { BOARD_FEATURE, boardData } from "./instance-board.mjs";
11
12
  /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
12
13
  export function remoteWorkspace(group) {
13
14
  return {
@@ -49,7 +50,7 @@ export function remotePanel(group, at) {
49
50
  const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
50
51
  // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
51
52
  const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, sameWork: sentSameWork,
52
- sameWorkKnown: _gate, pinned: sentPinned, ...i }) => {
53
+ relatedWork: sentRelatedWork, relatedWorkKnown: _gate, pinned: sentPinned, board: sentBoard, ...i }) => {
53
54
  const unsupported = unsupportedSession(i);
54
55
  const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
55
56
  const row = {
@@ -69,14 +70,19 @@ export function remotePanel(group, at) {
69
70
  ...(Object.hasOwn(i, "attributedHuman") ? { attributedHuman: attributedHumanData(i.attributedHuman) } : {}),
70
71
  // #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
71
72
  ...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
72
- // #1577: the host's same-work flag, true only (anything else reads unflagged). `sameWorkKnown` is this
73
- // client's own field (same-work.mjs), never a host's: whatever a host sent under it is dropped.
73
+ // The host's related-work flags, each true only (anything else reads unflagged). `relatedWorkKnown` is this
74
+ // client's own field (related-work.mjs), never a host's: whatever a host sent under it is dropped.
75
+ ...(sentRelatedWork === true ? { relatedWork: true } : {}),
74
76
  ...(sentSameWork === true ? { sameWork: true } : {}),
75
77
  // Feature instance-pin: the host's pin, true only (anything else reads unpinned; instance-tree.mjs rowPinned),
76
78
  // and only from a host whose own feature list names it (composed-gate.mjs hostAdvertises: the group's
77
79
  // probe.features, which a CLI with server-probe-features relays). The kernel relays a row's pinned whatever
78
80
  // its host lists, so a stray field from an older host, or an unknown list, never pins a row here.
79
81
  ...(sentPinned === true && hostAdvertises(group, PIN_FEATURE) ? { pinned: true } : {}),
82
+ // Feature instance-board: the agent's facts and questions (instance-board.mjs), validated again here, and only
83
+ // from a host whose own feature list names it, as the pin is; anything else leaves the row with no board field,
84
+ // so its tab is today's terminal. `null`: the host has the feature and the home has no board.
85
+ ...(sentBoard !== undefined && hostAdvertises(group, BOARD_FEATURE) ? { board: boardData(sentBoard) } : {}),
80
86
  ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
81
87
  };
82
88
  return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
@@ -0,0 +1,31 @@
1
+ /** The session backends a spawn or a schedule may name, as the kernel lists them. Two lists, one meaning each:
2
+ *
3
+ * `sessionBackends` of `oats version --json` the kernel's own: `["tmux"]` (an older kernel may still say
4
+ * "herdr", which OATS removed: never offered, never sent)
5
+ * `sessionProviders` of `oats inspect --json` the session providers a home or a soul can use, each supplied
6
+ * by one of its capabilities (feature session-providers)
7
+ *
8
+ * A client offers and accepts these names and no other: a `--backend` value (cli-adapter.mjs `spawnArgv`) and a
9
+ * schedule's `backend` it reads back into a form are held to them. Pure: no I/O, never throws. */
10
+ import { sessionProviderName } from './instance-presentation.mjs';
11
+
12
+ const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
13
+
14
+ /** The provider names an inspection lists, in its order, each once: the `name` of each row of its top-level
15
+ * `sessionProviders` (`[{ name, capability }]`). Only a name the contract allows (instance-presentation.mjs
16
+ * `sessionProviderName`) and never "herdr", which OATS removed; anything else, and an inspection without the
17
+ * list, lists none. */
18
+ export function sessionProviderNames(inspection) {
19
+ const listed = record(inspection) && Array.isArray(inspection.sessionProviders) ? inspection.sessionProviders : [];
20
+ return [...new Set(listed.map((row) => (record(row) ? row.name : undefined)).filter((name) => sessionProviderName(name) && name !== 'herdr'))];
21
+ }
22
+
23
+ /** A list of backend names as a client may offer or send them: its strings, never empty, never "herdr". */
24
+ export const listedBackends = (names) => (Array.isArray(names) ? names.filter((name) => typeof name === 'string' && name && name !== 'herdr') : []);
25
+
26
+ /** Every backend name the kernel lists: its own (`cli.sessionBackends`; "tmux" alone for a probe record without the
27
+ * list, as before the probe reported it) and then the providers of `inspection`, when one is given. */
28
+ export function sessionBackendNames(cli, inspection = null) {
29
+ const own = Array.isArray(cli?.sessionBackends) ? listedBackends(cli.sessionBackends) : ['tmux'];
30
+ return [...new Set([...own, ...sessionProviderNames(inspection)])];
31
+ }
@@ -21,6 +21,7 @@ import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
21
21
  import { answeringFeatures, busyHolder } from './lifecycle-contract.mjs';
22
22
  import { displayLine } from './display-text.mjs';
23
23
  import { requireTerms } from './client-terms.mjs';
24
+ import { sessionProviderName } from './instance-presentation.mjs';
24
25
 
25
26
  /** The gate is page-safe and lives apart (start-gate.mjs); a client takes it from here, with the rest of the rule. */
26
27
  export { startGate };
@@ -93,16 +94,27 @@ const START_REUSED = Object.freeze(['new', 'pane', 'adopted']);
93
94
  /** Whether `v` is the receipt of a completed start or restart of `row`, as the kernel answers one
94
95
  * (docs/desktop-cli-api.md, `oats session start`: `{instance, agent, home, harness, backend, model, launchConfig,
95
96
  * yolo, target, startedAt, restartCount, reused, warnings}`): the row's instance, in the row's home (the kernel
96
- * answers with its real path: `canonical`, the verified local home), on the one backend there is, tmux, with its
97
- * target (`{backend, session, window, socket}`, more keys allowed) and the other fields a start always carries.
98
- * Read where the CLI is newer than this client was tested with, so a format it does not know is not taken for one. */
97
+ * answers with its real path: `canonical`, the verified local home), on the backend the receipt itself names, and
98
+ * the other fields a start always carries. What was started is what the receipt says, not what the row read before
99
+ * the start said: a home's backend can move at a start. The receipt's `backend` picks its shape:
100
+ * "tmux" with its target (`{backend, session, window, socket}`, more keys allowed)
101
+ * a session provider (instance-presentation.mjs `sessionProviderName`) with `session: {provider, endpoint?}` and
102
+ * no terminal target (`target` null or absent).
103
+ * A start on this machine carries the endpoint, an object; a routed one (`--server`) carries the
104
+ * provider alone, the endpoint never leaving its host: required here, refused there
105
+ * A receipt that names no backend, or anything else, is no receipt this client knows. Read where the CLI is newer
106
+ * than this client was tested with, so a format it does not know is not taken for one. */
99
107
  function startReceipt(v, row, canonical) {
100
108
  const record = (x) => x !== null && typeof x === 'object' && !Array.isArray(x);
101
109
  const text = (x) => typeof x === 'string' && x.length > 0;
110
+ const routed = !!row.server;
111
+ const session = (x) => (x.backend === 'tmux'
112
+ ? record(x.target) && x.target.backend === 'tmux' && text(x.target.session) && text(x.target.window)
113
+ && text(x.target.socket) && x.target.socket.startsWith('/')
114
+ : sessionProviderName(x.backend) && (x.target === null || x.target === undefined) && record(x.session) && text(x.session.provider)
115
+ && (routed ? x.session.endpoint === undefined : record(x.session.endpoint)));
102
116
  return record(v) && v.instance === row.instance && text(v.home) && (v.home === row.home || (canonical !== null && v.home === canonical))
103
- && text(v.agent) && text(v.harness) && v.backend === 'tmux' && text(v.startedAt)
104
- && record(v.target) && v.target.backend === 'tmux' && text(v.target.session) && text(v.target.window)
105
- && text(v.target.socket) && v.target.socket.startsWith('/')
117
+ && text(v.agent) && text(v.harness) && text(v.startedAt) && session(v)
106
118
  && Number.isSafeInteger(v.restartCount) && v.restartCount >= 0 && START_REUSED.includes(v.reused)
107
119
  && Array.isArray(v.warnings) && v.warnings.every((w) => typeof w === 'string');
108
120
  }
@@ -6,7 +6,7 @@ import { parseEnvelope, writeTaskFile, execFileInSession } from './cli-adapter.m
6
6
  import { absolute, record, previewTarget, choiceArgv } from './spawn-preview-contract.mjs';
7
7
  import { spawnDecision } from './spawn-decision.mjs';
8
8
  import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnReference, spawnApplyReason, spawnApplyDeadline,
9
- SPAWN_APPLY_MS, ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
9
+ SPAWN_APPLY_MS, ROLLED_BACK_CODES, KERNEL_WORDED_CODES, kernelWordedDetails } from './spawn-apply-contract.mjs';
10
10
  const failure = (code, started = false) => ({ started, envelope: { schemaVersion: 1, ok: false, error: spawnApplyReason(code) } });
11
11
  const named = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
12
12
  const worktreeEvent = cli => Array.isArray(cli?.features) && cli.features.includes('worktree-event');
@@ -17,9 +17,11 @@ function refusal(doc, cli) {
17
17
  // worktree-event: the three rolled-back codes keep the kernel's own message (it names the
18
18
  // capability and its log), and whether its compensation was confirmed.
19
19
  const rolledBack = worktreeEvent(cli) && ROLLED_BACK_CODES.includes(doc.error?.code);
20
- const error = spawnApplyReason(doc.error?.code, rolledBack ? doc.error?.message : undefined);
20
+ const worded = KERNEL_WORDED_CODES.includes(doc.error?.code);
21
+ const error = spawnApplyReason(doc.error?.code, rolledBack || worded ? doc.error?.message : undefined);
21
22
  let details;
22
- if (rolledBack) {
23
+ if (worded) details = kernelWordedDetails(doc.error?.details) ?? undefined;
24
+ else if (rolledBack) {
23
25
  if (doc.error?.details?.unconfirmed === true) details = { unconfirmed: true };
24
26
  } else if (error.code === 'E_DECISION_STALE') {
25
27
  const decision = spawnDecision(doc.error?.details?.decision, { effectiveRequired: true });
@@ -173,18 +173,41 @@ const errors = {
173
173
  E_INTERRUPTED: 'The spawn was interrupted while its worktree hooks ran.',
174
174
  E_REQUIRED_HOOK_FAILED: 'A required worktree hook failed.',
175
175
  E_HOOK_ENVIRONMENT_CONTRACT: 'A worktree hook broke the hook environment contract.',
176
+ // Feature sandboxes (D-S1-4): a spawn into a sandbox is bound and keyed by the kernel itself, never by a
177
+ // confirmed apply. Shown only when the kernel's own message cannot travel.
178
+ E_SANDBOX_PLACEMENT: 'This soul runs in a sandbox, which a confirmed spawn cannot reach. Spawn it with `oats spawn <soul>` (OATS binds it to the sandbox itself) or from a schedule.',
176
179
  };
180
+ /** Refusals whose kernel message and `details: {reason, remedy}` travel: the kernel says why and what a
181
+ * person does next (feature sandboxes, E_SANDBOX_PLACEMENT). Nothing else of their details is kept. */
182
+ export const KERNEL_WORDED_CODES = ['E_SANDBOX_PLACEMENT'];
183
+ const MESSAGE_MAX = 2048, REMEDY_MAX = 1024;
184
+ const REASON = /^[a-z][a-z0-9-]{0,63}$/;
185
+ // As previewFailure bounds a kernel message: at most `max` characters, no control character but a
186
+ // newline, no credential-shaped text.
187
+ const boundedText = (v, max) => typeof v === 'string' && !!v.trim() && v.length <= max && !v.includes('\0')
188
+ && !/[\x00-\x09\x0b-\x1f\x7f]|https?:\/\/[^/\s]*@|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/.test(v);
189
+ /** A kernel-worded refusal's details as they travel: `reason` (a slug) and `remedy` (bounded text), each
190
+ * only when valid; null when neither is. */
191
+ export function kernelWordedDetails(details) {
192
+ if (!record(details)) return null;
193
+ const out = {
194
+ ...(typeof details.reason === 'string' && REASON.test(details.reason) ? { reason: details.reason } : {}),
195
+ ...(boundedText(details.remedy, REMEDY_MAX) ? { remedy: details.remedy } : {}),
196
+ };
197
+ return Object.keys(out).length ? out : null;
198
+ }
177
199
  /** Feature worktree-event: a dispatched spawn failure with one of these codes and no
178
200
  * `details.unconfirmed: true` was rolled back by the kernel (confirmed compensation): nothing
179
201
  * was created. With the marker its cleanup is owed. Only these three; every other code keeps
180
202
  * the unknown-unless-proven rule. */
181
203
  export const ROLLED_BACK_CODES = ['E_INTERRUPTED', 'E_REQUIRED_HOOK_FAILED', 'E_HOOK_ENVIRONMENT_CONTRACT'];
182
- /** The kernel's message travels only for ROLLED_BACK_CODES (it names the capability and its log);
183
- * bounded here, and shown through displayLine. */
204
+ /** The kernel's message travels for ROLLED_BACK_CODES (it names the capability and its log) and
205
+ * KERNEL_WORDED_CODES; bounded here, and shown through displayLine. */
184
206
  const kernelText = v => typeof v === 'string' && !!v.trim() && v.length <= 4096 && !v.includes('\0');
185
207
  export function spawnApplyReason(code, kernelMessage) {
186
208
  if (typeof code !== 'string') code = 'E_CLI_FAILED';
187
209
  if (ROLLED_BACK_CODES.includes(code)) return { code, message: kernelText(kernelMessage) ? kernelMessage : errors[code] };
210
+ if (KERNEL_WORDED_CODES.includes(code)) return { code, message: boundedText(kernelMessage, MESSAGE_MAX) ? kernelMessage : errors[code] };
188
211
  if (Object.hasOwn(errors, code)) return { code, message: errors[code] };
189
212
  const reason = previewFailure(code).reason;
190
213
  return reason.code === code && code !== 'E_CLI_FAILED' ? reason : { code: 'E_CLI_FAILED', message: errors.E_CLI_FAILED };
@@ -15,7 +15,7 @@ import { cliSpawnApply } from './spawn-apply-cli.mjs';
15
15
  import { admitSpawnSelection, PREVIEW_MAX_AGE_S } from './spawn-preview.mjs';
16
16
  import { record } from './spawn-preview-contract.mjs';
17
17
  import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnRefInput, spawnPreparedData, spawnReference,
18
- spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
18
+ spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, KERNEL_WORDED_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
19
19
  /** The apply request answers within this; the proxy's own 65 s timeout then never fires on a healthy spawn. */
20
20
  export const ANSWER_WITHIN_MS = 50000;
21
21
  export const MAX_APPLIES = 4;
@@ -145,6 +145,10 @@ export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec, a
145
145
  if (envelope.error.details?.unconfirmed === true) { entry.final = true; return denied(code, entry, 'unknown', message); }
146
146
  return denied(code, entry, 'refused', message);
147
147
  }
148
+ // Feature sandboxes (D-S1-4): a spawn into a sandbox is refused before anything is minted, kept or
149
+ // created (docs/desktop-cli-api.md, Sandbox refusals): refused, in the kernel's words, which end with
150
+ // what a person does next.
151
+ if (KERNEL_WORDED_CODES.includes(code)) return denied(code, entry, 'refused', envelope.error.message);
148
152
  // A taken explicit name (spawn-name) refuses before any home is kept: the
149
153
  // confirmation is consumed and a fresh preview reports the taken name.
150
154
  if (['E_DECISION_STALE', 'E_IDEMPOTENCY_CONFLICT', 'E_PLACEMENT_TAKEN', 'E_INSTANCE_NAME_TAKEN'].includes(code)) return denied(code, entry, 'stale');
@@ -89,6 +89,9 @@ const SPAWN_FACTS = {
89
89
  E_CLI_OUTPUT_LIMIT: said('OATS couldn’t confirm the spawn.', 'check-result'),
90
90
  E_CLI_PROTOCOL: said('OATS couldn’t complete the spawn.', 'details'),
91
91
  E_CLI_FAILED: said('OATS couldn’t complete the spawn.', 'details'),
92
+ // Feature sandboxes (D-S1-4): the kernel binds a spawn into a sandbox itself; its own remedy is the detail
93
+ // (`details`: a client shows it). Trying again cannot work: a client's words for this next say so per code.
94
+ E_SANDBOX_PLACEMENT: said('This soul runs in a sandbox, which a confirmed spawn can’t reach yet. Nothing was created. Spawn it with oats spawn in a terminal, or from a schedule.', 'details'),
92
95
  // Wherever nothing is above the sentence and Details hold no kernel text: the whole of it is shared.
93
96
  [UNMATCHED]: said('This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.'),
94
97
  };
@@ -37,6 +37,10 @@ const messages = {
37
37
  E_TERM_ATTACHMENT_FAILED: 'Could not prepare these attachments.',
38
38
  E_TERM_ATTACHMENT_INTERRUPTED: 'Attachment interrupted; some file copies may already exist. No input was inserted.',
39
39
  E_TERM_INPUT_LIMIT: 'Terminal input exceeds the safe write limit. Nothing was sent.',
40
+ // An answer (the agent view) refused because the terminal is in tmux's scrollback (copy mode): nothing was typed.
41
+ E_TERM_IN_MODE: 'The terminal is in its scrollback. Nothing was typed.',
42
+ // An answer refused because the pane's mode could not be read (or there is no local pane to read): nothing was typed.
43
+ E_TERM_MODE_UNKNOWN: 'The terminal could not be checked for its scrollback. Nothing was typed.',
40
44
  E_TERM_TRANSPORT: 'The terminal service did not confirm the operation.',
41
45
  E_HERDR_REMOVED: HERDR_REMOVED,
42
46
  E_TERM_REMOTE_UNREACHABLE: serverMessages.E_TERM_REMOTE_UNREACHABLE('the server'),
@@ -7,6 +7,7 @@
7
7
  import { record } from './readiness-contract.mjs';
8
8
  import { eventsTimestamp, eventsId, eventsUnsafe, EVENTS_WITHHELD } from './instance-events-contract.mjs';
9
9
  import { NOT_NOTE_TEXT } from './display-text.mjs';
10
+ import { sessionProvider } from './instance-presentation.mjs';
10
11
 
11
12
  /** A claim's note: a non-empty string of at most 200 code points (not UTF-16 units: 101 emoji is a valid
12
13
  * note), with none of NOT_NOTE_TEXT (the set's one definition is in display-text.mjs); unsafe text is
@@ -36,9 +37,18 @@ export function waitingOnYouData(v) {
36
37
  * or a row the roster holds stale (`stale`: its last re-read failed), carries a last-known claim, which is
37
38
  * unknown. A null or absent `runtimeState` is "not reported", never "not running" (#582): the kernel's
38
39
  * remote roster sends null on every row, so a remote row is gated on the `running` its host reported; a
39
- * local row always carries the concrete state Desktop liveness observed. */
40
+ * local row always carries the concrete state Desktop liveness observed.
41
+ *
42
+ * A row on a session provider (instance-presentation.mjs `sessionProvider`: "bb", say) has another liveness
43
+ * gate, under the same two rules of currency: it shows the claim the kernel's row carries unless the row is
44
+ * stopped (`running === false`). Its `runtimeState` is never "running" (a provider's states are `unknown`,
45
+ * `shell`, `stopped`, `unreachable`), and an agent that waits on a person is idle there, which the kernel
46
+ * reports as `running: null`: the kernel is such a row's only reader, and it decides whether the row carries
47
+ * a claim at all. A home OATS stopped reads `running: false` and shows none. */
40
48
  export function waitingClaim(row, { stale = false } = {}) {
41
- if (stale || !record(row) || row.running !== true || row.serverUnreached === true) return null;
49
+ if (stale || !record(row) || row.serverUnreached === true) return null;
50
+ if (sessionProvider(row)) return row.running === false ? null : waitingOnYouData(row.waitingOnYou);
51
+ if (row.running !== true) return null;
42
52
  if (row.runtimeState != null && row.runtimeState !== 'running') return null;
43
53
  return waitingOnYouData(row.waitingOnYou);
44
54
  }
@@ -10,7 +10,8 @@
10
10
  * sync → `oats sync --dir D --json` (syncApi 1)
11
11
  * onboard → `oats onboard DIR --workspace REF --json` (onboardApi 2)
12
12
  * There is no package approval (packages-no-approval): declaring a package
13
- * is the trust decision, so every success exits 0. `--max-age` (feature
13
+ * is the trust decision, so every success exits 0, but one: a sync whose
14
+ * sandbox failed exits 1 with its report (sandboxFailureReport). `--max-age` (feature
14
15
  * observe-max-age) belongs to the three reads only and reaches argv only when
15
16
  * the probe declares the feature; cliWorkspace drops it otherwise. */
16
17
  import { execFile } from 'node:child_process';
@@ -97,6 +98,13 @@ export function workspaceArgv(options) {
97
98
  return { argv: ['sync', '--dir', options.context, '--json'], cwd: options.context, timeout: WORKSPACE_WRITE_TIMEOUT };
98
99
  }
99
100
 
101
+ /** Whether a sync's exit is its one non-zero success: exit 1 exactly, an `ok: true` answer, and a
102
+ * `result.sandboxes` entry whose `problems` is not empty (a failed sandbox; the lock is written). */
103
+ function sandboxFailureReport(options, error, document) {
104
+ if (options.action !== 'sync' || error?.code !== 1 || error.killed || error.signal) return false;
105
+ const sandboxes = document?.result?.sandboxes;
106
+ return Array.isArray(sandboxes) && sandboxes.some(entry => record(entry) && Array.isArray(entry.problems) && entry.problems.length > 0);
107
+ }
100
108
  /** `io.exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
101
109
  export function cliWorkspace(cli, options, terms, io = {}) {
102
110
  requireTerms(terms, 'cliWorkspace');
@@ -138,7 +146,10 @@ export function cliWorkspace(cli, options, terms, io = {}) {
138
146
  if (options.action === 'sync' && typeof reason.details?.why === 'string' && WHY_RE.test(reason.details.why)) out.why = reason.details.why;
139
147
  return done({ ok: false, reason: out });
140
148
  }
141
- if (error) return fail('E_CLI_FAILED'); // success is exit 0 only
149
+ // Success is exit 0, with one exception: a sync whose sandbox failed (feature sandboxes) wrote the lock
150
+ // and answers its report with `ok: true` and exit 1, the failure in a sandbox entry's `problems`
151
+ // (docs/desktop-cli-api.md, `oats sync`). That one answer is a report; any other exit is a failure.
152
+ if (error && !sandboxFailureReport(options, error, document)) return fail('E_CLI_FAILED');
142
153
  done({ ok: true, document });
143
154
  });
144
155
  } catch { fail('E_CLI_FAILED'); }
@@ -108,7 +108,11 @@ export function reachedMachines(state, at) {
108
108
  * that was not reached (the shared home marks it) still carries the word of its last report,
109
109
  * which is not its state now: it gets the shared word, so nothing reads as stopped, or as
110
110
  * running, that is only not reached. */
111
- const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true ? row.runtimeState : runtimeState(row));
111
+ const stateWord = (row) => (text(row.runtimeState) && row.serverUnreached !== true && !providerKnown(row) ? row.runtimeState : runtimeState(row));
112
+ /** A row on a session provider (the shared openAct's `no-terminal`) whose `running` the kernel answered: its
113
+ * `runtimeState` is the provider's word (`unknown` while it runs), which would contradict its mark, so its
114
+ * state is the shared word for its `running`. One the kernel answered `running: null` keeps the kernel's word. */
115
+ const providerKnown = (row) => typeof row.running === "boolean" && openAct(row)?.reason?.code === "no-terminal";
112
116
  /** The word a list row shows beside its name, or null: only what its mark cannot say. That is a
113
117
  * held home's state (Retiring… while a retire runs, or this run's own is in flight), else the
114
118
  * shared label of the reason the row can't be reached or opened (remote-address.mjs rowReason:
@@ -528,7 +532,8 @@ const elsewhere = (row) => typeof row.server === "string" && row.server !== "";
528
532
  * for a row of another machine (its preflight runs first)
529
533
  * { open: false, said: { said, under } } opens nothing, and this says why
530
534
  * Whether a row can be opened is the shared openAct's, switched on its reason's code, never on a
531
- * sentence. The viewer is started with no key of its own (the TUI takes the back key before the
535
+ * sentence. A row on a session provider is never opened, from the list, the palette, the steps or a
536
+ * workspace's remembered tabs (they all ask here); its reason's link is printed under its sentence. The viewer is started with no key of its own (the TUI takes the back key before the
532
537
  * pane sees it), so a kernel or a host of any version is opened alike. */
533
538
  export function openDecision(state, row, acts) {
534
539
  const name = row.instance, id = instanceId(row);
@@ -542,7 +547,13 @@ export function openDecision(state, row, acts) {
542
547
  if (!act.enabled) {
543
548
  if (act.reason.code === "not-running") return no(OPEN_WORDS.notRunning(name));
544
549
  if (act.reason.code === "state-unknown") return no(OPEN_WORDS.stateUnknown(name));
545
- return no([], outside(reasonSpoken(act.reason)));
550
+ // A row on a session provider (code `no-terminal`) has no terminal: the shared home's sentence says where
551
+ // the agent runs, and under it the link the provider offers (its label and its url, one text from outside),
552
+ // for the person to open themselves. The link carries no mark of who made it, and the TUI names no speaker
553
+ // of its own (test/tui-boundary.test.mjs): it stands in quotation marks, as any text nobody vouches for.
554
+ // Nothing is attached or started.
555
+ const link = act.reason.link ? spoken(`${act.reason.link.label}: ${act.reason.link.url}`, undefined, false) : null;
556
+ return no([], [...outside(reasonSpoken(act.reason)), ...outside(link)]);
546
557
  }
547
558
  if (!elsewhere(row)) return { open: true, id, name, machine, target: { home: row.home }, routed: false };
548
559
  return { open: true, id, name, machine, target: { serverId: row.server, instance: row.instance, home: row.home }, routed: true };