@awebai/oats 0.69.21 → 0.69.23

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (73) hide show
  1. package/bin/oats.mjs +131 -23
  2. package/docs/capabilities.md +12 -2
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +290 -5
  5. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  6. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  7. package/docs/design/2026-11-19-sandboxes.md +878 -0
  8. package/docs/design/README.md +3 -0
  9. package/docs/desktop-cli-api.md +416 -72
  10. package/docs/desktop.md +377 -148
  11. package/docs/implementation.md +15 -2
  12. package/docs/integrations.md +3 -3
  13. package/docs/knowledge-capability-authoring.md +10 -7
  14. package/docs/knowledge-reference/acceptance.md +21 -19
  15. package/docs/knowledge-reference/adoption.md +18 -4
  16. package/docs/knowledge-reference/model.md +11 -9
  17. package/docs/knowledge-reference/package-craft.md +2 -2
  18. package/docs/knowledge-reference/proposal.md +117 -0
  19. package/docs/knowledge-reference/provider-mapping.md +10 -10
  20. package/docs/knowledge-reference/reader-capture.md +26 -22
  21. package/docs/knowledge-theory.md +1 -1
  22. package/docs/knowledge.md +5 -5
  23. package/docs/official-catalog.md +47 -4
  24. package/docs/packages.md +13 -13
  25. package/docs/release-lane.md +8 -6
  26. package/docs/release-notes/v0.69.22.md +221 -0
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/servers.md +10 -6
  29. package/docs/souls-and-instances.md +51 -22
  30. package/docs/tui.md +48 -7
  31. package/docs/upgrading.md +17 -5
  32. package/docs/workspaces.md +2 -2
  33. package/lib/argv.mjs +6 -2
  34. package/lib/capability-contract.mjs +2 -2
  35. package/lib/command-flags.mjs +39 -2
  36. package/lib/core.mjs +25 -14
  37. package/lib/instance-board.mjs +337 -0
  38. package/lib/instance-events.mjs +48 -10
  39. package/lib/instance-lifecycle.mjs +19 -15
  40. package/lib/instance-listing.mjs +18 -10
  41. package/lib/instance-related-work.mjs +143 -0
  42. package/lib/kernel-features.mjs +4 -1
  43. package/lib/servers.mjs +123 -13
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/above-tested.mjs +3 -2
  47. package/packages/client/capability-list.mjs +69 -0
  48. package/packages/client/capability-origin.mjs +54 -0
  49. package/packages/client/cli-adapter.mjs +9 -1
  50. package/packages/client/deployment-data.mjs +7 -2
  51. package/packages/client/deployment-panel.mjs +4 -1
  52. package/packages/client/home-board.mjs +50 -0
  53. package/packages/client/instance-pin.mjs +28 -0
  54. package/packages/client/instance-record-outcome.mjs +31 -0
  55. package/packages/client/instance-tree.mjs +96 -24
  56. package/packages/client/keymap.mjs +16 -3
  57. package/packages/client/mail-contract.mjs +130 -0
  58. package/packages/client/panel-views.mjs +7 -7
  59. package/packages/client/related-work.mjs +84 -0
  60. package/packages/client/remote-roster.mjs +11 -3
  61. package/packages/client/roster-sections.mjs +10 -7
  62. package/packages/client/soul-role.mjs +44 -0
  63. package/packages/client/waiting-on-you.mjs +10 -0
  64. package/packages/client/workspace-cli.mjs +13 -2
  65. package/packages/tui/lib/actions.mjs +11 -4
  66. package/packages/tui/lib/client.mjs +3 -1
  67. package/packages/tui/lib/main.mjs +16 -2
  68. package/packages/tui/lib/model.mjs +48 -5
  69. package/packages/tui/lib/store.mjs +28 -2
  70. package/skills/oats-getting-started/SKILL.md +97 -24
  71. package/docs/knowledge-reference/harvester.md +0 -109
  72. package/lib/instance-same-work.mjs +0 -67
  73. package/packages/client/same-work.mjs +0 -49
@@ -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}`;
@@ -79,14 +79,31 @@ function spawnTime(instance) {
79
79
  * and so clusters (by their first root: a bundle sits where its newest root sits, so a new child never moves it).
80
80
  * A spawn time never changes, so a start or a stop moves no row; only adding or removing one does (#1262's
81
81
  * recognition rule, whose name order this replaces; #1083's running-first order stays out of the roster). The one
82
- * place the roster's order is decided. */
83
- function rosterOrder(a, b) {
82
+ * place the roster's order is decided; a pin ranks before it at every level (`pinnedFirst`, `clusterInstances`,
83
+ * `instanceSiblings`), and pinning or unpinning is the one act besides adding or removing a row that moves one. */
84
+ export function rosterOrder(a, b) {
84
85
  const ta = spawnTime(a), tb = spawnTime(b);
85
86
  if (ta !== tb) return ta === null ? 1 : tb === null ? -1 : tb - ta;
86
87
  const ia = instanceId(a), ib = instanceId(b);
87
88
  return String(a.instance).localeCompare(String(b.instance)) || (ia < ib ? -1 : ia > ib ? 1 : 0);
88
89
  }
89
90
 
91
+ /** The kernel feature that reports a row's `pinned` (oats instance pin; docs/desktop-cli-api.md "Pinned instances"). */
92
+ export const PIN_FEATURE = "instance-pin";
93
+
94
+ /** Whether a row is pinned: its own `pinned` is exactly `true`, read only where this computer's CLI lists
95
+ * `PIN_FEATURE` (`pins`). A remote row carries `pinned` only when its host's own feature list names it too
96
+ * (remote-roster.mjs remotePanel drops it otherwise). Any other value, and every value without the feature, is no
97
+ * pin: a stray field from an older host is ignored, as `backgroundPlacement` reads `background`. */
98
+ export function rowPinned(instance, pins) {
99
+ return pins === true && instance?.pinned === true;
100
+ }
101
+
102
+ /** Pinned first (Pepe, 2026-11-19), a comparator for one level of the roster: a node that `lifted(node)` says holds
103
+ * a pin (itself, or a descendant in its tree) before one that does not; 0 between two of the same kind, for the
104
+ * roster's order (`rosterOrder`) to decide. So several pinned nodes keep that order among themselves. */
105
+ const pinnedFirst = (lifted) => (a, b) => (lifted(b) ? 1 : 0) - (lifted(a) ? 1 : 0);
106
+
90
107
  /** Each instance's siblings by EXPLICIT link (#1312): Y is X's sibling when X's sibling link
91
108
  * (`siblingLinksOf`) resolves to Y (`resolveLinkId` over `instances`), or Y's resolves to X. So both
92
109
  * ends of a link name each other. Direct links only (a chain C→B→A gives B [A, C], A [B], C [B]; A and
@@ -95,8 +112,9 @@ function rosterOrder(a, b) {
95
112
  * <parent>"), and `relation`/`relativeTo` are not read: they record how an instance was spawned, not a
96
113
  * current relation. Pass one deployment's FULL roster, never a filtered list: dropping rows can turn an
97
114
  * ambiguous name into a false unique one. Returns Map<instanceId, instance[]>; an instance with no
98
- * sibling is absent from the map. */
99
- export function instanceSiblings(instances) {
115
+ * sibling is absent from the map. `pins`: the CLI lists `PIN_FEATURE`; then a pinned sibling comes first, by its
116
+ * own `pinned` (`rowPinned`: siblings are no subtree). */
117
+ export function instanceSiblings(instances, { pins = false } = {}) {
100
118
  const byId = new Map(instances.map((i) => [instanceId(i), i]));
101
119
  const byName = new Map();
102
120
  for (const i of instances) {
@@ -117,7 +135,37 @@ export function instanceSiblings(instances) {
117
135
  add(other, id);
118
136
  }
119
137
  }
120
- return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(rosterOrder)]));
138
+ const order = (a, b) => pinnedFirst((i) => rowPinned(i, pins))(a, b) || rosterOrder(a, b);
139
+ return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(order)]));
140
+ }
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;
121
169
  }
122
170
 
123
171
  /** Group instances into agent CLUSTERS — connected components of the
@@ -127,17 +175,24 @@ export function instanceSiblings(instances) {
127
175
  * cluster members related only by sibling links sit at depth 0.
128
176
  * Nodes are keyed by instanceId (composite identity), never bare name —
129
177
  * duplicate names across repos render as distinct nodes.
130
- * Under one parent, the children that draw their parent line come first (same-work.mjs `drawingFirst`: on a
131
- * 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
132
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.
133
182
  * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
134
- * their first ROOT in the roster's order (`rosterOrder`), never by another member (#1262): a bundle sits where
183
+ * their first ROOT in the roster's order (`rosterOrder`; pinned clusters first, `pins` below), never by another member (#1262): a bundle sits where
135
184
  * its root sits, and gaining or losing a child, or a start or a stop, moves nothing. A cluster without a root
136
185
  * (a malformed cycle) ranks by its first member in that order.
137
186
  * `roster` (optional): the full roster `instances` is a part of (#1579: one section of it). Names resolve over it,
138
187
  * so a part never turns an ambiguous name into a false unique one, and a link that resolves to a row outside the
139
- * part is no edge: such a row is a root of its part, as a row whose parent is gone. Without it, `instances`. */
140
- export function clusterInstances(instances, { links = instanceLinks, roster = instances } = {}) {
188
+ * part is no edge: such a row is a root of its part, as a row whose parent is gone. Without it, `instances`.
189
+ * `pins` (the CLI lists `PIN_FEATURE`; Pepe, 2026-11-19): pinned first at every level, ahead of the roster's order.
190
+ * A node ranks pinned when it or a descendant in its cluster's tree is pinned (`rowPinned`), so a pinned child
191
+ * lifts its group to the top and the path down to it rises among its siblings; a cluster ranks pinned when any
192
+ * member is pinned (its head's subtree, and the members a sibling link puts in the group). Under one parent,
193
+ * `drawingFirst` stays first (structural), then the pin, then the roster's order. Pinned nodes at one level keep
194
+ * the roster's order among themselves. Without it (an older CLI), `pinned` is ignored. */
195
+ export function clusterInstances(instances, { links = instanceLinks, roster = instances, pins = false } = {}) {
141
196
  const byId = new Map(instances.map((i) => [instanceId(i), i]));
142
197
  const byName = new Map();
143
198
  for (const i of roster) {
@@ -177,31 +232,46 @@ export function clusterInstances(instances, { links = instanceLinks, roster = in
177
232
  // parent-first tree order INSIDE the component (cycle-safe: the walk
178
233
  // visits each member once; leftovers append at depth 0)
179
234
  const memberIds = new Set(members.map(instanceId));
235
+ // The members whose subtree holds a pin: each pinned member and its ancestors in this cluster, walked up the
236
+ // resolved parent relation once (cycle-safe: a member already lifted ends the walk).
237
+ const lifted = new Set();
238
+ for (const i of members) {
239
+ if (!rowPinned(i, pins)) continue;
240
+ for (let id = instanceId(i); id && memberIds.has(id) && !lifted.has(id); id = parentIdOf.get(id)) lifted.add(id);
241
+ }
242
+ const first = pinnedFirst((i) => lifted.has(instanceId(i)));
243
+ const order = (a, b) => first(a, b) || rank(a, b);
180
244
  const kids = (p) => members.filter((i) => parentIdOf.get(instanceId(i)) === instanceId(p));
181
245
  const roots = members.filter((i) => {
182
246
  const pid = parentIdOf.get(instanceId(i));
183
247
  return !pid || !memberIds.has(pid);
184
248
  });
185
- roots.sort(rank);
249
+ // The cluster's rank among the others is its head's as it was without pins: its first root by the roster's
250
+ // order (with no root, its first member). A pin decides only whether the cluster leads (`pinned`); among
251
+ // clusters that do, and among those that don't, the existing rule stands (done-when 2), whichever root is pinned.
252
+ const head = [...(roots.length ? roots : members)].sort(rank)[0];
253
+ roots.sort(order);
186
254
  const ordered = [];
187
255
  const placed = new Set();
188
256
  const walk = (i, depth) => {
189
257
  if (placed.has(instanceId(i))) return;
190
258
  placed.add(instanceId(i));
191
259
  ordered.push({ ...i, depth });
192
- kids(i).sort((a, b) => drawingFirst(a, b) || rank(a, b)).forEach((k) => walk(k, depth + 1));
260
+ kids(i).sort((a, b) => drawingFirst(a, b) || order(a, b)).forEach((k) => walk(k, depth + 1));
193
261
  };
194
262
  roots.forEach((r) => walk(r, 0));
195
- for (const i of [...members].sort(rank)) walk(i, 0); // malformed cycles must not hide members
263
+ for (const i of [...members].sort(order)) walk(i, 0); // malformed cycles must not hide members
196
264
  // Deterministic cluster label: the lexically-smallest ROOT name —
197
265
  // independent of liveness, so the visible cluster name does not flip
198
266
  // when a different member starts/stops running (review f921f7d nit).
199
- // `rank` (rosterOrder: by spawn time, newest first) governs display ORDER within the cluster.
267
+ // `order` (pinned first, then rosterOrder: by spawn time, newest first) governs display ORDER within the cluster.
200
268
  const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
201
- clusters.push({ key: rootNames[0], instances: ordered, head: roots[0] ?? [...members].sort(rank)[0] });
269
+ clusters.push({ key: rootNames[0], instances: ordered, head, pinned: lifted.size > 0 });
202
270
  }
203
- // Stable: clusters whose heads rank equal keep the order they were found in (the roster's order of members).
204
- return clusters.sort((a, b) => rank(a.head, b.head)).map(({ head: _head, ...c }) => c);
271
+ // Pinned clusters first, then by head (its rank without pins). Stable: clusters whose heads rank equal keep the
272
+ // order they were found in.
273
+ const clusterFirst = pinnedFirst((c) => c.pinned);
274
+ return clusters.sort((a, b) => clusterFirst(a, b) || rank(a.head, b.head)).map(({ head: _head, pinned: _pinned, ...c }) => c);
205
275
  }
206
276
 
207
277
  /** `clusterInstances` output ordered by last focus (#1383; the command palette's order, never the sidebar's).
@@ -211,7 +281,7 @@ export function clusterInstances(instances, { links = instanceLinks, roster = in
211
281
  * each parent. Nodes without a key follow every node with one, in their input order (a stable sort), so an
212
282
  * empty record returns the input order. A child stays under its parent: each cluster is walked again in
213
283
  * pre-order, every depth unchanged. A parent's children keep the roster's split (#1577): those that draw their
214
- * 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
215
285
  * children are the following rows one level deeper, until a row at its depth or above), never from names: the
216
286
  * tree was built by identity, and a malformed cycle's depth-0 leftovers are roots like any other. Returns new
217
287
  * cluster objects over the same rows; the input is not mutated. */
@@ -500,9 +570,9 @@ export function filterInstanceTree(instances, query, matches = null) {
500
570
  * re-linking nodes while the user types (merged-state review @3e76616).
501
571
  * Cluster order and member depths come from the full-roster computation;
502
572
  * clusters with no visible member disappear. */
503
- export function visibleClusters(allInstances, visibleInstances, { links = instanceLinks } = {}) {
573
+ export function visibleClusters(allInstances, visibleInstances, { links = instanceLinks, pins = false } = {}) {
504
574
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
505
- return clusterInstances(allInstances, { links })
575
+ return clusterInstances(allInstances, { links, pins })
506
576
  .map((c) => ({ ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) }))
507
577
  .filter((c) => c.instances.length);
508
578
  }
@@ -521,12 +591,14 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
521
591
  * ordered by last focus (`recencyOrder`) before the groups form by the same rule, so a run is the consecutive
522
592
  * single clusters of that order, keyed by its first member there. What is visible still decides only which rows
523
593
  * are listed, never the order. Without it, the roster's own order (the sidebar's and the TUI's).
524
- * `roster` (optional): the full roster `allInstances` is a part of, as for `clusterInstances`. */
525
- export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus, roster = allInstances } = {}) {
594
+ * `roster` (optional): the full roster `allInstances` is a part of, as for `clusterInstances`.
595
+ * `pins` (optional): the CLI lists `PIN_FEATURE`, as for `clusterInstances`. Pinned single clusters rank first, so
596
+ * they form the leading run, keyed by its first member as any run is. */
597
+ export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus, roster = allInstances, pins = false } = {}) {
526
598
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
527
599
  const groups = [];
528
600
  let place = 0, run = null;
529
- const clusters = clusterInstances(allInstances, { links, roster });
601
+ const clusters = clusterInstances(allInstances, { links, roster, pins });
530
602
  for (const c of lastFocus instanceof Map ? recencyOrder(clusters, lastFocus) : clusters) {
531
603
  const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
532
604
  if (c.instances.length > 1) {
@@ -29,7 +29,10 @@
29
29
  /** The leader per platform: Ctrl+X on both, as Emacs has it (#1433). Without the kitty keyboard
30
30
  * protocol it is one byte, 0x18, in every terminal; pressed twice it sends that byte to the program
31
31
  * (the shell's Ctrl+X Ctrl+E, nano's exit). The Desktop leaves it to Cut in an editable field on
32
- * Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader"). */
32
+ * Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader").
33
+ * D18 (decided 2026-11-19, Joan): the Desktop's default leader is Ctrl+Space, with Ctrl+X a choice; the TUI keeps
34
+ * Ctrl+X here until it reads Ctrl+Space, which a terminal sends as NUL (0x00), a byte its key decoder reads as no
35
+ * key today (packages/tui/lib/term/keys.mjs c0Key). This shared default moves to `ctrl+space` with that change. */
33
36
  export const LEADER = Object.freeze({ mac: "ctrl+x", other: "ctrl+x" });
34
37
 
35
38
  /** The keys read after the leader, in the TUI's order, and what each does. `terminal`: named in
@@ -47,11 +50,16 @@ export const LEADER_TABLE = Object.freeze([
47
50
  { keys: ["up"], does: "workspace-previous", label: "previous workspace" },
48
51
  { keys: ["down"], does: "workspace-next", label: "next workspace" },
49
52
  { keys: ["z"], does: "zoom", label: "zoom", terminal: true },
53
+ // `b`, Herdr's (the Desktop UI rework, decided 2026-11-19): the sidebar hidden or shown in the Desktop; in the TUI,
54
+ // whose list is its sidebar, the shown terminal takes the whole screen or gives the list back.
55
+ { keys: ["b"], does: "sidebar", label: "hide or show the list" },
50
56
  { keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
51
57
  { keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
52
58
  { keys: ["right"], does: "tab-next", label: "next tab", terminal: true },
53
- { keys: ["|"], does: "split-right", label: "split right", terminal: true },
54
- { keys: ["-"], does: "split-down", label: "split down", terminal: true },
59
+ // `h` and `v` beside `|` and `-` (the Desktop UI rework, decided 2026-11-19): Herdr's letters, h a pane to the
60
+ // right and v one below, as its split_horizontal and split_vertical are.
61
+ { keys: ["|", "h"], does: "split-right", label: "split right", terminal: true },
62
+ { keys: ["-", "v"], does: "split-down", label: "split down", terminal: true },
55
63
  { keys: ["tab"], does: "group-next", label: "next group", terminal: true },
56
64
  { keys: ["shift+tab"], does: "group-previous", label: "previous group", terminal: true },
57
65
  { keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
@@ -167,6 +175,11 @@ export const CHORDS = Object.freeze([
167
175
  // such action, so it binds no key for it (chordKeys skips a `does` it does not handle). Not one of
168
176
  // the seven the Ctrl+Shift family moves: Ctrl+Alt+R in both of those (the maintainer's ruling).
169
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" },
170
183
  ].map((entry) => Object.freeze({ ...entry, alt: entry.alt ?? entry.other, shift: entry.shift ?? entry.other })));
171
184
 
172
185
  /** The palette's own keys, read only while the palette is open: there they win over every binding
@@ -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
+ }
@@ -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));
@@ -6,6 +6,8 @@ import { attributedHumanData } from "./attributed-human.mjs";
6
6
  import { retireData } from "./retire-state.mjs";
7
7
  import { readIdentity } from "./workspace-views.mjs";
8
8
  import { sameRepo } from "./repo-moves.mjs";
9
+ import { hostAdvertises } from "./composed-gate.mjs";
10
+ import { PIN_FEATURE } from "./instance-tree.mjs";
9
11
  /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
10
12
  export function remoteWorkspace(group) {
11
13
  return {
@@ -47,7 +49,7 @@ export function remotePanel(group, at) {
47
49
  const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
48
50
  // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
49
51
  const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, sameWork: sentSameWork,
50
- sameWorkKnown: _gate, ...i }) => {
52
+ relatedWork: sentRelatedWork, relatedWorkKnown: _gate, pinned: sentPinned, ...i }) => {
51
53
  const unsupported = unsupportedSession(i);
52
54
  const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
53
55
  const row = {
@@ -67,9 +69,15 @@ export function remotePanel(group, at) {
67
69
  ...(Object.hasOwn(i, "attributedHuman") ? { attributedHuman: attributedHumanData(i.attributedHuman) } : {}),
68
70
  // #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
69
71
  ...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
70
- // #1577: the host's same-work flag, true only (anything else reads unflagged). `sameWorkKnown` is this
71
- // client's own field (same-work.mjs), never a host's: whatever a host sent under it is dropped.
72
+ // The host's related-work flags, each true only (anything else reads unflagged). `relatedWorkKnown` is this
73
+ // client's own field (related-work.mjs), never a host's: whatever a host sent under it is dropped.
74
+ ...(sentRelatedWork === true ? { relatedWork: true } : {}),
72
75
  ...(sentSameWork === true ? { sameWork: true } : {}),
76
+ // Feature instance-pin: the host's pin, true only (anything else reads unpinned; instance-tree.mjs rowPinned),
77
+ // and only from a host whose own feature list names it (composed-gate.mjs hostAdvertises: the group's
78
+ // probe.features, which a CLI with server-probe-features relays). The kernel relays a row's pinned whatever
79
+ // its host lists, so a stray field from an older host, or an unknown list, never pins a row here.
80
+ ...(sentPinned === true && hostAdvertises(group, PIN_FEATURE) ? { pinned: true } : {}),
73
81
  ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
74
82
  };
75
83
  return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
@@ -58,11 +58,13 @@ export const rowStale = (row, deployments) => {
58
58
  * most recent first, then the panel's order. Without it, the panel's order (the sidebar's and the TUI's).
59
59
  * `roster` (optional; #1579): the full roster `instances` is a part of (the main tree's rows or the Background
60
60
  * section's, `sidebarSections`). Names resolve over its rows of the same deployment, and a relation to a row outside
61
- * `instances` is none: that row's relatives are roots here. Without it, `instances`. */
62
- export function rosterSections(instances, visible, deployments, terms, { lastFocus, roster = instances } = {}) {
61
+ * `instances` is none: that row's relatives are roots here. Without it, `instances`.
62
+ * `pins` (optional): this computer's CLI lists instance-tree.mjs `PIN_FEATURE`: pinned rows lead each section's
63
+ * order (`clusterInstances`). The section split comes first, so a pin ranks only within its own section. */
64
+ export function rosterSections(instances, visible, deployments, terms, { lastFocus, roster = instances, pins = false } = {}) {
63
65
  requireTerms(terms, 'rosterSections');
64
66
  const recency = lastFocus instanceof Map ? { lastFocus } : {};
65
- const groupsOf = (all, shown, whole) => rosterGroups(all, shown, { ...recency, roster: whole }); // the relation groups the palette lists too
67
+ const groupsOf = (all, shown, whole) => rosterGroups(all, shown, { ...recency, roster: whole, pins }); // the relation groups the palette lists too
66
68
  if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible, roster) }];
67
69
  const sectionOf = splitByDeployment(deployments);
68
70
  const all = sectionOf(instances), shown = sectionOf(visible), whole = sectionOf(roster), labels = machineLabelParts(deployments, terms);
@@ -110,17 +112,18 @@ export function rosterSectionKey(deployments, placement = new Set()) {
110
112
  * one included), and `sections` its own tree, `rosterSections` over its rows (with the machine sub-headings in a
111
113
  * view of two or more deployments), empty while closed. Each part is a tree of its own: a relation to a row of the
112
114
  * other part is none (a background row whose parent is in the main tree is a root of the Background section), and
113
- * names still resolve over the full roster. The palette never asks this: it lists every row. */
114
- export function sidebarSections(instances, visible, deployments, terms, { placement = new Set(), open = false, listed = instances, stale = () => false } = {}) {
115
+ * names still resolve over the full roster. The palette never asks this: it lists every row.
116
+ * `pins`: as for `rosterSections`; a pinned row in the Background section leads that section's own tree. */
117
+ export function sidebarSections(instances, visible, deployments, terms, { placement = new Set(), open = false, listed = instances, stale = () => false, pins = false } = {}) {
115
118
  requireTerms(terms, 'sidebarSections');
116
119
  const inside = row => placement.has(instanceId(row));
117
- const main = rosterSections(instances.filter(r => !inside(r)), visible.filter(r => !inside(r)), deployments, terms, { roster: instances });
120
+ const main = rosterSections(instances.filter(r => !inside(r)), visible.filter(r => !inside(r)), deployments, terms, { roster: instances, pins });
118
121
  const rows = instances.filter(inside), count = listed.filter(inside).length;
119
122
  if (!count) return { main, background: null };
120
123
  return { main, background: {
121
124
  count, open: !!open,
122
125
  waiting: rows.some(row => waitingClaim(row, { stale: stale(row) }) !== null),
123
- sections: open ? rosterSections(rows, visible.filter(inside), deployments, terms, { roster: instances }) : [],
126
+ sections: open ? rosterSections(rows, visible.filter(inside), deployments, terms, { roster: instances, pins }) : [],
124
127
  } };
125
128
  }
126
129