@awebai/oats 0.69.1 → 0.69.3

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 (71) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +273 -66
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +4 -4
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/release-notes/v0.69.3.md +43 -0
  17. package/docs/servers.md +7 -2
  18. package/docs/soul.schema.json +1 -0
  19. package/docs/souls-and-instances.md +35 -2
  20. package/docs/tui.md +112 -15
  21. package/docs/upgrading.md +9 -5
  22. package/docs/workspaces.md +2 -2
  23. package/injects/instance-boundary.md +19 -33
  24. package/injects/work-attached.md +8 -13
  25. package/injects/work-checkout.md +16 -30
  26. package/injects/work-directory.md +9 -15
  27. package/injects/work-workspace.md +8 -19
  28. package/injects/work-worktree.md +18 -33
  29. package/lib/capability-contract.mjs +2 -2
  30. package/lib/core.mjs +162 -49
  31. package/lib/instance-background.mjs +54 -0
  32. package/lib/instance-inspect.mjs +3 -0
  33. package/lib/instance-lifecycle.mjs +35 -0
  34. package/lib/instance-resolution.mjs +3 -2
  35. package/lib/instance-same-work.mjs +67 -0
  36. package/lib/instance-upgrade.mjs +18 -0
  37. package/lib/materialize.mjs +23 -2
  38. package/lib/resolve.mjs +32 -5
  39. package/lib/servers.mjs +19 -4
  40. package/lib/session-resume-contract.mjs +1 -0
  41. package/lib/session-resume.mjs +36 -9
  42. package/lib/soul-composition.mjs +13 -10
  43. package/lib/workspace.mjs +3 -2
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +30 -8
  47. package/packages/client/deployment-data.mjs +9 -0
  48. package/packages/client/deployment-panel.mjs +4 -0
  49. package/packages/client/instance-tree.mjs +64 -14
  50. package/packages/client/launch-prompt-outcome.mjs +1 -1
  51. package/packages/client/panel-views.mjs +11 -3
  52. package/packages/client/remote-roster.mjs +5 -1
  53. package/packages/client/roster-sections.mjs +50 -6
  54. package/packages/client/same-work.mjs +49 -0
  55. package/packages/client/session-resume-trigger.mjs +15 -37
  56. package/packages/client/session-resume.mjs +22 -259
  57. package/packages/client/soul-rows.mjs +2 -0
  58. package/packages/client/spawn-apply-contract.mjs +2 -1
  59. package/packages/client/spawn-decision.mjs +4 -1
  60. package/packages/client/spawn-preview-contract.mjs +12 -1
  61. package/packages/client/spawn-preview.mjs +2 -0
  62. package/packages/tui/README.md +2 -2
  63. package/packages/tui/lib/client.mjs +6 -2
  64. package/packages/tui/lib/main.mjs +44 -11
  65. package/packages/tui/lib/model.mjs +101 -43
  66. package/packages/tui/lib/panel.mjs +23 -13
  67. package/packages/tui/lib/store.mjs +76 -20
  68. package/packages/tui/lib/views/frame.mjs +2 -0
  69. package/packages/tui/lib/views/help.mjs +2 -0
  70. package/packages/tui/lib/views/instances.mjs +38 -1
  71. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -223,12 +223,18 @@ export function deploymentStatusData(document, deployment) {
223
223
  // instanceColor, the one rule of which colour a row shows). Validated, never check()ed: anything
224
224
  // else is dropped and the row reads as one with no colour.
225
225
  if (own(instance, 'color') && instanceColor(instance) !== null) row.color = instanceColor(instance);
226
+ // Feature instance-background (#1579): the row is placed in the Background section. Exactly true only; any
227
+ // other value is dropped, never checked: the row stays in the main tree.
228
+ if (own(instance, 'background') && instance.background === true) row.background = true;
226
229
  // #802 (feature worktree-event): a spawn running its worktree hooks, verifiably alive. Boolean true only;
227
230
  // any other value is dropped, never checked: the row stays an ordinary one.
228
231
  if (own(instance, 'spawnInProgress') && instance.spawnInProgress === true) row.spawnInProgress = true;
229
232
  // Session resume: how the instance's last session ended, one of SESSION_ENDS exactly. Any other value is
230
233
  // dropped, never checked: the row reads as one that did not say.
231
234
  if (own(instance, 'sessionEnd') && SESSION_END_VALUES.includes(instance.sessionEnd)) row.sessionEnd = instance.sessionEnd;
235
+ // #1577 (feature instance-same-work): the child does its parent's work, so its parent line is drawn
236
+ // (same-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
237
+ if (own(instance, 'sameWork') && instance.sameWork === true) row.sameWork = true;
232
238
  if (own(instance, 'modules')) row.modules = modules(instance.modules);
233
239
  if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
234
240
  if (own(instance, 'workspace')) row.workspace = recordedWorkspace(instance.workspace);
@@ -372,6 +378,9 @@ export function soulsData(document) {
372
378
  out.key = out.kind === 'package' ? out.qualifiedName : out.name;
373
379
  if (own(row, 'key')) check(soulKey(row.key) && row.key === out.key);
374
380
  flags(row, ['private', 'spawnable'], out);
381
+ // Feature instance-background (#1579): the soul declares `background: true`, the default of the spawn dialog's
382
+ // Run in background switch. Exactly true only; any other value is dropped, never checked (as an instance row's).
383
+ if (own(row, 'background') && row.background === true) out.background = true;
375
384
  // desktop-facts: whether a spawn here would refuse, and the file. The row's flat harness/model/harnessFrom
376
385
  // are not kept: with launch-preference (0.30) the soul and this machine choose them, and the row's `launch`
377
386
  // (below) carries the kernel's report of that choice; before 0.30 they were always the kernel's default.
@@ -111,12 +111,16 @@ export function panelInstance(i) {
111
111
  // Session resume: how the last session ended, as deployment-data.mjs validated it (SESSION_ENDS); absent stays
112
112
  // absent. The resume trigger reads it (session-resume-trigger.mjs lostLocalHomes).
113
113
  ...(i.sessionEnd !== undefined ? { sessionEnd: i.sessionEnd } : {}),
114
+ // #1577: the kernel's same-work flag (deployment-data.mjs keeps it as true only); same-work.mjs reads it.
115
+ ...(i.sameWork === true ? { sameWork: true } : {}),
114
116
  ...(i.captured ? { captured: true } : {}),
115
117
  // Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
116
118
  // The client's liveness is merged before projection, so running/runtimeState beside it are the probe's.
117
119
  ...(i.waitingOnYou !== undefined ? { waitingOnYou: i.waitingOnYou } : {}),
118
120
  // Feature instance-color: the row's colour as instanceColor reads it, present only when it is one.
119
121
  ...(instanceColor(i) !== null ? { color: instanceColor(i) } : {}),
122
+ // Feature instance-background (#1579): exactly true, else absent (instance-tree.mjs backgroundPlacement).
123
+ ...(i.background === true ? { background: true } : {}),
120
124
  team: i.team || null,
121
125
  };
122
126
  }
@@ -6,6 +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
10
 
10
11
  export function collapseKey(workspace, instance) {
11
12
  return `${workspace || ""}\u0000${instance}`;
@@ -114,14 +115,21 @@ export function instanceSiblings(instances) {
114
115
  * cluster members related only by sibling links sit at depth 0.
115
116
  * Nodes are keyed by instanceId (composite identity), never bare name —
116
117
  * duplicate names across repos render as distinct nodes.
118
+ * Under one parent, the children that draw their parent line come first (same-work.mjs `drawingFirst`: on a
119
+ * host that declares instance-same-work, the flagged ones), each part in the roster's order (#1577). The product
120
+ * owner's contract (awebai/oats#1577, comment 6441606665) refines the name order (the Desktop expert's decision
121
+ * roster-name-order-preserves-recognition) inside one parent's children only: roots, clusters and groups keep it.
117
122
  * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
118
123
  * their first ROOT in the roster's order (`rosterOrder`), never by another member (#1262): a bundle sits where
119
124
  * its root sits, and gaining or losing a child, or a start or a stop, moves nothing. A cluster without a root
120
- * (a malformed cycle) ranks by its first member in that order. */
121
- export function clusterInstances(instances, { links = instanceLinks } = {}) {
125
+ * (a malformed cycle) ranks by its first member in that order.
126
+ * `roster` (optional): the full roster `instances` is a part of (#1579: one section of it). Names resolve over it,
127
+ * so a part never turns an ambiguous name into a false unique one, and a link that resolves to a row outside the
128
+ * part is no edge: such a row is a root of its part, as a row whose parent is gone. Without it, `instances`. */
129
+ export function clusterInstances(instances, { links = instanceLinks, roster = instances } = {}) {
122
130
  const byId = new Map(instances.map((i) => [instanceId(i), i]));
123
131
  const byName = new Map();
124
- for (const i of instances) {
132
+ for (const i of roster) {
125
133
  if (!byName.has(i.instance)) byName.set(i.instance, []);
126
134
  byName.get(i.instance).push(i);
127
135
  }
@@ -136,7 +144,7 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
136
144
  }
137
145
  for (const other of links(i)) {
138
146
  const oid = resolveLinkId(i, other, byName);
139
- if (!oid || oid === id) continue;
147
+ if (!oid || oid === id || !adj.has(oid)) continue; // a link out of these rows draws nothing
140
148
  adj.get(id).add(oid);
141
149
  adj.get(oid).add(id);
142
150
  }
@@ -170,7 +178,7 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
170
178
  if (placed.has(instanceId(i))) return;
171
179
  placed.add(instanceId(i));
172
180
  ordered.push({ ...i, depth });
173
- kids(i).sort(rank).forEach((k) => walk(k, depth + 1));
181
+ kids(i).sort((a, b) => drawingFirst(a, b) || rank(a, b)).forEach((k) => walk(k, depth + 1));
174
182
  };
175
183
  roots.forEach((r) => walk(r, 0));
176
184
  for (const i of [...members].sort(rank)) walk(i, 0); // malformed cycles must not hide members
@@ -191,7 +199,8 @@ export function clusterInstances(instances, { links = instanceLinks } = {}) {
191
199
  * recent first, and so is each set of nodes at one level of a cluster: its depth-0 roots, and the children of
192
200
  * each parent. Nodes without a key follow every node with one, in their input order (a stable sort), so an
193
201
  * empty record returns the input order. A child stays under its parent: each cluster is walked again in
194
- * pre-order, every depth unchanged. Parentage is read from the pre-order and the depths alone (a node's
202
+ * pre-order, every depth unchanged. A parent's children keep the roster's split (#1577): those that draw their
203
+ * 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
195
204
  * children are the following rows one level deeper, until a row at its depth or above), never from names: the
196
205
  * tree was built by identity, and a malformed cycle's depth-0 leftovers are roots like any other. Returns new
197
206
  * cluster objects over the same rows; the input is not mutated. */
@@ -219,12 +228,13 @@ export function recencyOrder(clusters, lastFocus) {
219
228
  return node.key;
220
229
  };
221
230
  const instances = [];
222
- const walk = (nodes) => {
223
- for (const node of [...nodes].sort(recentFirst)) { instances.push(node.inst); walk(node.kids); }
231
+ const childOrder = (a, b) => drawingFirst(a.inst, b.inst) || recentFirst(a, b);
232
+ const walk = (nodes, order) => {
233
+ for (const node of [...nodes].sort(order)) { instances.push(node.inst); walk(node.kids, childOrder); }
224
234
  };
225
235
  const top = { key: null, kids: roots };
226
236
  keyOf(top);
227
- walk(roots);
237
+ walk(roots, recentFirst);
228
238
  return { key: top.key, cluster: { ...cluster, instances } };
229
239
  });
230
240
  return ranked.sort(recentFirst).map(({ cluster }) => cluster);
@@ -381,7 +391,7 @@ export function rosterRank(sortBy) {
381
391
 
382
392
  /** Group a roster list repo → agent family (soul), each family's items in
383
393
  * lineage order (parents before children, depth annotated) with siblings
384
- * sorted by `sortBy`. Lineage links crossing family/repo boundaries are cut:
394
+ * sorted by `sortBy` (those that draw their parent line first, #1577). Lineage links crossing family/repo boundaries are cut:
385
395
  * such children render as roots of their own family group. Returns
386
396
  * Map<repoLabel, Map<familyName, item[]>> with deterministic group order:
387
397
  * repos and families alphabetical. */
@@ -412,7 +422,8 @@ export function groupRosterFamilies(list, sortBy = "status") {
412
422
  if (seen.has(i.instance)) return; // cycle-safe
413
423
  seen.add(i.instance);
414
424
  ordered.push({ ...i, depth });
415
- kids(i).sort(rank).forEach((k) => walk(k, depth + 1));
425
+ // #1577: children that draw their parent line first, as clusterInstances orders them.
426
+ kids(i).sort((a, b) => drawingFirst(a, b) || rank(a, b)).forEach((k) => walk(k, depth + 1));
416
427
  };
417
428
  roots.sort(rank).forEach((r) => walk(r, 0));
418
429
  for (const i of items) if (!seen.has(i.instance)) ordered.push({ ...i, depth: 0 });
@@ -498,12 +509,13 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
498
509
  * `lastFocus` (Map<instanceId, time>, optional; the command palette's, #1383): the full roster's clusters are
499
510
  * ordered by last focus (`recencyOrder`) before the groups form by the same rule, so a run is the consecutive
500
511
  * single clusters of that order, keyed by its first member there. What is visible still decides only which rows
501
- * are listed, never the order. Without it, the roster's own order (the sidebar's and the TUI's). */
502
- export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus } = {}) {
512
+ * are listed, never the order. Without it, the roster's own order (the sidebar's and the TUI's).
513
+ * `roster` (optional): the full roster `allInstances` is a part of, as for `clusterInstances`. */
514
+ export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus, roster = allInstances } = {}) {
503
515
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
504
516
  const groups = [];
505
517
  let place = 0, run = null;
506
- const clusters = clusterInstances(allInstances, { links });
518
+ const clusters = clusterInstances(allInstances, { links, roster });
507
519
  for (const c of lastFocus instanceof Map ? recencyOrder(clusters, lastFocus) : clusters) {
508
520
  const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
509
521
  if (c.instances.length > 1) {
@@ -518,6 +530,44 @@ export function rosterGroups(allInstances, visibleInstances, { links = instanceL
518
530
  return groups.filter((g) => g.clusters.length);
519
531
  }
520
532
 
533
+ /** The kernel feature that reports a row's `background` (#1579). */
534
+ export const BACKGROUND_FEATURE = "instance-background";
535
+
536
+ /** The rows the Background section holds (#1579; Pepe, 2026-10-27): a row whose own `background` is exactly
537
+ * `true`, or one with such an ancestor in its `parentInstance` chain among the rows present (resolved by
538
+ * identity, resolveLinkId over the FULL roster, cycle-safe; a parent that resolves to nothing ends the chain).
539
+ * So a background row's children stay under it whatever their own value. Placement only: a row's own flag is
540
+ * read, never changed (no inheritance). `enabled`: the CLI lists `instance-background`; without it the set is
541
+ * empty whatever a row carries (a stray field is ignored). Returns Set<instanceId>. */
542
+ export function backgroundPlacement(instances, enabled) {
543
+ const out = new Set();
544
+ if (!enabled) return out;
545
+ const byId = new Map(instances.map((i) => [instanceId(i), i]));
546
+ const byName = new Map();
547
+ for (const i of instances) {
548
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
549
+ byName.get(i.instance).push(i);
550
+ }
551
+ const known = new Map(); // instanceId -> placed in Background
552
+ for (const row of instances) {
553
+ // Walk up until a background row, a row already decided, the top, or a cycle; every row walked shares the answer.
554
+ const path = [], seen = new Set();
555
+ let cursor = row, placed = false;
556
+ while (cursor) {
557
+ const id = instanceId(cursor);
558
+ if (known.has(id)) { placed = known.get(id); break; }
559
+ if (seen.has(id)) break;
560
+ seen.add(id); path.push(id);
561
+ if (cursor.background === true) { placed = true; break; }
562
+ const pid = cursor.parentInstance ? resolveLinkId(cursor, cursor.parentInstance, byName) : null;
563
+ cursor = pid ? byId.get(pid) : null;
564
+ }
565
+ for (const id of path) known.set(id, placed);
566
+ }
567
+ for (const [id, placed] of known) if (placed) out.add(id);
568
+ return out;
569
+ }
570
+
521
571
  /** Whether an item remains visible under VS Code-style collapsed ancestors.
522
572
  * Filtering temporarily reveals matching paths without mutating the user's
523
573
  * persisted collapse state. Parent traversal is cycle-safe and
@@ -166,7 +166,7 @@ export function launchFlagIgnored(answer) {
166
166
  * units in total. The first line that does not fit and every line after it are left out, and no line is cut
167
167
  * inside; the first line always fits (a display line is at most MAX_DISPLAY_LINE units). `omitted` counts
168
168
  * the lines left out, 0 when none; an entry with nothing to show was never a line and is not counted. By
169
- * position only, never by words. Shared by launchFlagIgnored and the session-resume reader. */
169
+ * position only, never by words. Used by launchFlagIgnored. */
170
170
  export function boundedWarnings(raw) {
171
171
  const lines = Array.isArray(raw) ? raw.map(w => displayLine(w)).filter(line => line !== null) : [];
172
172
  const warnings = [];
@@ -46,6 +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
50
 
50
51
  /** Roots come ONLY from the kernel's observed `status.root`; before (or
51
52
  * without) an observation there is nothing to act on. No layout guess. */
@@ -309,13 +310,20 @@ export function deploymentEntry(info, primary) {
309
310
  ...(info.reason && info.fix?.length ? { fix: [...info.fix] } : {}), ...(info.note ? { note: info.note } : {}) };
310
311
  }
311
312
 
312
- /** One deployment's own panel, as served before views. */
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. */
313
316
  export function deploymentPanel(held, ws) {
314
317
  // Another machine's panel never says who made its `error`: the key is removed here whatever the panel carried.
315
318
  // A kept group's panel is made at the time it was read (#1124): a filtered read never makes it look newer.
316
- if (ws?.remote) { const { errorOrigin: _sent, ...panel } = remotePanel(ws.group, held.keptReadAt?.get?.(ws.group.id) ?? held.at); return { ...panel, observedAt: null, refreshing: held.remoteCollecting }; }
319
+ if (ws?.remote) {
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 };
323
+ }
317
324
  const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
318
- const instances = observed?.instances || [], kept = keptFailure(observed);
325
+ const declared = sameWorkDeclared(held.cli);
326
+ const instances = (observed?.instances || []).map((row) => withSameWorkGate(row, declared)), kept = keptFailure(observed);
319
327
  return {
320
328
  workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
321
329
  team: null,
@@ -44,7 +44,8 @@ export function remotePanel(group, at) {
44
44
  // A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
45
45
  const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
46
46
  // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
47
- const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, ...i }) => {
47
+ const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, sameWork: sentSameWork,
48
+ sameWorkKnown: _gate, ...i }) => {
48
49
  const unsupported = unsupportedSession(i);
49
50
  const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
50
51
  const row = {
@@ -61,6 +62,9 @@ export function remotePanel(group, at) {
61
62
  ...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
62
63
  // #1247: the host's retire state, relayed unchanged when it is in the contract (retire-state.mjs), else absent.
63
64
  ...(retireData(sentRetire) ? { retire: retireData(sentRetire) } : {}),
65
+ // #1577: the host's same-work flag, true only (anything else reads unflagged). `sameWorkKnown` is this
66
+ // client's own field (same-work.mjs), never a host's: whatever a host sent under it is dropped.
67
+ ...(sentSameWork === true ? { sameWork: true } : {}),
64
68
  ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
65
69
  };
66
70
  return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
@@ -6,6 +6,7 @@
6
6
  * and a row carries `deployment: { id }`. Nothing is derived from a host name or a path beyond the
7
7
  * display label. A view with one deployment has one section and no heading. */
8
8
  import { rosterGroups, instanceId } from './instance-tree.mjs';
9
+ import { waitingClaim } from './waiting-on-you.mjs';
9
10
  import { machineLabelParts } from './deployment-label.mjs';
10
11
  import { requireTerms } from './client-terms.mjs';
11
12
 
@@ -54,14 +55,17 @@ export const rowStale = (row, deployments) => {
54
55
  * `[{ deployment|null, label|null, groups }]`, a group being `{ key, label, clusters }` as before.
55
56
  * `lastFocus` (Map<instanceId, time>, optional; the command palette's, #1383): each section's groups follow
56
57
  * last focus (rosterGroups), and the sections are ordered by the latest focus over each one's full roster,
57
- * most recent first, then the panel's order. Without it, the panel's order (the sidebar's and the TUI's). */
58
- export function rosterSections(instances, visible, deployments, terms, { lastFocus } = {}) {
58
+ * most recent first, then the panel's order. Without it, the panel's order (the sidebar's and the TUI's).
59
+ * `roster` (optional; #1579): the full roster `instances` is a part of (the main tree's rows or the Background
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 } = {}) {
59
63
  requireTerms(terms, 'rosterSections');
60
64
  const recency = lastFocus instanceof Map ? { lastFocus } : {};
61
- const groupsOf = (all, shown) => rosterGroups(all, shown, recency); // the relation groups the palette lists too
62
- if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible) }];
65
+ const groupsOf = (all, shown, whole) => rosterGroups(all, shown, { ...recency, roster: whole }); // the relation groups the palette lists too
66
+ if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible, roster) }];
63
67
  const sectionOf = splitByDeployment(deployments);
64
- const all = sectionOf(instances), shown = sectionOf(visible), labels = machineLabelParts(deployments, terms);
68
+ const all = sectionOf(instances), shown = sectionOf(visible), whole = sectionOf(roster), labels = machineLabelParts(deployments, terms);
65
69
  const label = ({ machine, tail }) => (tail ? `${machine} · ${tail}` : machine);
66
70
  const sections = deployments.map(d => ({ deployment: d, parts: labels.get(d.id), all: all.get(d.id), shown: shown.get(d.id) }));
67
71
  if (recency.lastFocus) {
@@ -77,7 +81,47 @@ export function rosterSections(instances, visible, deployments, terms, { lastFoc
77
81
  });
78
82
  }
79
83
  return sections.filter(s => s.shown.length)
80
- .map(s => ({ deployment: s.deployment, label: label(s.parts), machine: s.parts.machine, tail: s.parts.tail, groups: groupsOf(s.all, s.shown) }));
84
+ .map(s => ({ deployment: s.deployment, label: label(s.parts), machine: s.parts.machine, tail: s.parts.tail, groups: groupsOf(s.all, s.shown, whole.get(s.deployment.id)) }));
85
+ }
86
+
87
+ /** The section a row is painted in (#482, #1579), as a key: its deployment's, in the main tree or in the
88
+ * Background section (`placement`: instance-tree.mjs `backgroundPlacement`). A collapse hides, and rolls up,
89
+ * only rows of its own section: give it as `section` to `instanceVisibleInTree` and `waitingRollup`. Two rows
90
+ * are in one section exactly when their keys are equal; the key says nothing else. */
91
+ export function rosterSectionKey(deployments, placement = new Set()) {
92
+ const ids = Array.isArray(deployments) ? new Set(deployments.map(d => d?.id)) : new Set();
93
+ const primary = primaryDeployment(deployments)?.id ?? null;
94
+ return row => {
95
+ const id = rowDeployment(row);
96
+ const deployment = isMultiDeployment(deployments) ? (id && ids.has(id) ? id : primary) : null;
97
+ return `${placement.has(instanceId(row)) ? 'background' : 'main'}\u0000${deployment ?? ''}`;
98
+ };
99
+ }
100
+
101
+ /** The sidebar's roster and the TUI's (#1579): the main tree's sections, then the Background section.
102
+ * `instances`: the full roster; `visible`: the rows a filter and a collapse leave (instanceVisibleInTree, given
103
+ * `rosterSectionKey` as its section); `placement`: instance-tree.mjs `backgroundPlacement`.
104
+ * Options: `open`, whether the Background section is drawn open (the client's stored state, or a filter that is
105
+ * on: a filter shows its matches without changing what is stored); `listed`, the rows the filter leaves (all rows
106
+ * when nothing is filtered), which the heading counts; `stale(row)`, the client's held-stale test.
107
+ * Returns `{ main, background }`. `main` is `rosterSections` over the rows outside the section. `background` is
108
+ * null when no listed row is in the section (no heading is drawn), else `{ count, open, waiting, sections }`:
109
+ * `count` the listed rows in it, `waiting` whether any row in it waits (waitingClaim; open or closed, a filtered
110
+ * one included), and `sections` its own tree, `rosterSections` over its rows (with the machine sub-headings in a
111
+ * 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
+ * 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
+ requireTerms(terms, 'sidebarSections');
116
+ 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 });
118
+ const rows = instances.filter(inside), count = listed.filter(inside).length;
119
+ if (!count) return { main, background: null };
120
+ return { main, background: {
121
+ count, open: !!open,
122
+ waiting: rows.some(row => waitingClaim(row, { stale: stale(row) }) !== null),
123
+ sections: open ? rosterSections(rows, visible.filter(inside), deployments, terms, { roster: instances }) : [],
124
+ } };
81
125
  }
82
126
 
83
127
  /** `rows → Map<deployment id, rows>` over the given deployments; an unknown or missing deployment
@@ -0,0 +1,49 @@
1
+ /** Which parent→child lines a roster draws, and so the order under one parent (awebai/oats#1577, the contract
2
+ * on comment 6441606665, item 7). The one rule, shared by the Desktop's sidebar and command palette and by the
3
+ * TUI; neither client keeps a copy.
4
+ *
5
+ * The kernel reports `sameWork: true` on a child row that does the same work as its current parent (feature
6
+ * instance-same-work), and leaves the key out otherwise. It has already bound the flag to the current parent:
7
+ * a client reads `sameWork === true` and nothing more, and never compares parents.
8
+ *
9
+ * The gate: whether a row's host declares the feature. A local row: this computer's CLI advertises it. A remote
10
+ * row: this CLI advertises it and relays the hosts' own lists (server-probe-features), and the row's group's
11
+ * host names it (composed-gate.mjs `hostAdvertises`). Unknown is not supported: an unread or failed probe keeps
12
+ * today's lines. panel-views.mjs `deploymentPanel` stamps the gate's answer on each row it serves as
13
+ * `sameWorkKnown: true` (`withSameWorkGate`), present only when the host declares the feature; it is the
14
+ * client's own field, never the kernel's.
15
+ *
16
+ * Pure: no DOM, no Node builtin, so a page loads it as it is. */
17
+ import { hostAdvertises, PROBE_FEATURES_FEATURE } from './composed-gate.mjs';
18
+
19
+ export const SAME_WORK_FEATURE = 'instance-same-work';
20
+
21
+ const advertises = (cli, feature) => !!cli?.ok && Array.isArray(cli.features) && cli.features.includes(feature);
22
+
23
+ /** Whether a host declares the feature: `group` null for this computer's rows, else the remote roster group the
24
+ * rows came from. */
25
+ export function sameWorkDeclared(cli, group = null) {
26
+ if (!advertises(cli, SAME_WORK_FEATURE)) return false;
27
+ return group === null || (advertises(cli, PROBE_FEATURES_FEATURE) && hostAdvertises(group, SAME_WORK_FEATURE));
28
+ }
29
+
30
+ /** A row with the gate's answer stamped: `sameWorkKnown: true` when `declared`, else no key. Whatever the row
31
+ * carried under that key is dropped first, so a host can never set it. */
32
+ export function withSameWorkGate(row, declared) {
33
+ const { sameWorkKnown: _carried, ...rest } = row;
34
+ return declared ? { ...rest, sameWorkKnown: true } : rest;
35
+ }
36
+
37
+ /** A row the client made itself (a pending spawn's) has no stamp: it takes its parent's, since a child is on its
38
+ * parent's host (instance-tree.mjs `resolveLinkId` never resolves across hosts). `parent` is the row its
39
+ * `parentInstance` resolves to, or null. */
40
+ export const withParentGate = (row, parent) => withSameWorkGate(row, parent?.sameWorkKnown === true);
41
+
42
+ /** Whether a row draws the line to its parent: always when its host does not declare the feature (today's
43
+ * lines), else only when the kernel flagged it. A root has no parent line to draw, whatever this says. */
44
+ export const drawsParentLine = (row) => row?.sameWorkKnown !== true || row.sameWork === true;
45
+
46
+ /** The order of one parent's children, a comparator for a stable sort or a first key before another: the
47
+ * children that draw their parent line first, then those that don't. So a parent's line ends at its last
48
+ * joined child and never passes a child it doesn't join. Within each part the caller's own order stands. */
49
+ export const drawingFirst = (a, b) => Number(!drawsParentLine(a)) - Number(!drawsParentLine(b));
@@ -15,30 +15,24 @@
15
15
  * resumeSupported) runs. Without one nothing runs, nothing is read, the floor does not move and the slot is let go.
16
16
  *
17
17
  * Settled homes keep a home that cannot be resumed from starting a sweep on every read. A sweep `observed()` started
18
- * keeps the lost homes it was started for (its snapshot); when it completes as a sweep (its reading is quiet or a
19
- * notice of an answer that ran: session-resume.mjs sweepCompleted), every one of them is settled, whatever the answer said of it (left out
18
+ * keeps the lost homes it was started for (its snapshot); when it completes as a sweep (its reading is `answered`,
19
+ * of an answer that ran: session-resume.mjs sweepCompleted), every one of them is settled, whatever the answer said of it (left out
20
20
  * because its deployment is not ready, or named busy or unknown), so a home that cannot be resumed costs at most
21
21
  * one observed sweep. Then the answer's rows settle and release homes (session-resume.mjs sweepSettlement: a
22
22
  * refusal, or a home skipped as not lost or not seen running recently, settles it; a session started or running
23
23
  * releases it; anything else changes nothing; the launch sweep has no snapshot, so a busy or unknown home there
24
24
  * stays news for one observed sweep). A later read also releases a local home it shows that lostLocalHomes does not
25
- * name: no longer lost, or running.
25
+ * name: no longer lost, or running. This module reads nothing of the answer itself: its shape is
26
+ * session-resume.mjs's alone.
26
27
  *
27
- * News, not repeats. The kernel reports a refusal again in every sweep: before `read`, the refusals an earlier
28
- * sweep of this trigger reported are left out of a copy of the envelope (session-resume.mjs withoutReported; the
29
- * run's own is never changed). Every other row is this sweep's event and kept. A home released (above) forgets the
30
- * refusals reported for it, so a refusal after it recovered is news again. A host warning (the result's own
31
- * `warnings`, about this computer) is left out the same way once a notice of this trigger showed it: once per run,
32
- * never forgotten (it is no home's); one a quiet sweep carried was never shown, so it stays news. This module reads
33
- * nothing of the answer itself: its shape is session-resume.mjs's alone.
34
- *
35
- * `onReading` gets the reading of every finished sweep, whatever its kind (the caller ignores what it does not
36
- * show). A run that rejects reads as failed, E_CLI_FAILED; a `read` that throws, as failed, E_CLI_PROTOCOL.
28
+ * `read` is given the run's envelope itself, and `onReading` gets the reading of every finished sweep, whatever its
29
+ * kind (the caller ignores what it does not act on). A run that rejects reads as failed, E_CLI_FAILED; a `read`
30
+ * that throws, as failed, E_CLI_PROTOCOL, and settles nothing.
37
31
  *
38
32
  * `dispose()` stops the trigger and never cancels a sweep: a sweep in flight runs on (a kernel change outlives
39
33
  * its client), and its reading is dropped. Nothing here throws out of `launch` or `observed`. */
40
34
  import { resumeSupported, runResumeSweep } from './session-resume-cli.mjs';
41
- import { readResumeSweep, shownHostKeys, sweepCompleted, sweepSettlement, withoutReported } from './session-resume.mjs';
35
+ import { readResumeSweep, sweepCompleted, sweepSettlement } from './session-resume.mjs';
42
36
  import { SESSION_ENDS } from './deployment-data.mjs';
43
37
 
44
38
  export const RESUME_MIN_INTERVAL_MS = 30_000;
@@ -84,35 +78,19 @@ export function lostLocalHomes(rows, localDeploymentIds) {
84
78
  */
85
79
  export function createResumeTrigger({ cli, run = runResumeSweep, read = readResumeSweep, now = Date.now, onReading }) {
86
80
  let launched = null, disposed = false, flying = false, lastStart = null;
87
- const settled = new Set(), reported = new Set(), reportedFor = new Map(); // reportedFor: home → its reported keys
88
- const reportedHost = new Set(); // host warnings a notice showed
81
+ const settled = new Set();
89
82
  let releasedDuring = null; // homes a read released while the sweep in flight ran: newer than its answer
90
83
 
91
- /** A home no longer settled, and the refusals reported for it forgotten. */
84
+ /** A home no longer settled. */
92
85
  function release(home) {
93
86
  releasedDuring?.add(home);
94
87
  settled.delete(home);
95
- for (const key of reportedFor.get(home) ?? []) reported.delete(key);
96
- reportedFor.delete(home);
97
- }
98
-
99
- /** The envelope `read` is given, without the refusals an earlier answer reported and the host warnings a
100
- * notice showed (withoutReported), with this answer's host keys and settlement (sweepSettlement) for after
101
- * the read. Its refusal keys are added at once. */
102
- function digest(envelope) {
103
- const news = { ...withoutReported(envelope, reported, reportedHost), settlement: sweepSettlement(envelope) };
104
- for (const { home, key } of news.keys) {
105
- reported.add(key);
106
- if (!reportedFor.has(home)) reportedFor.set(home, new Set());
107
- reportedFor.get(home).add(key);
108
- }
109
- return news;
110
88
  }
111
89
 
112
90
  /** After the read: a completed sweep settles every home of its snapshot; then the answer's own rows settle and
113
91
  * release (a home it resumed, started, left waiting or found running is released again). A home a read released
114
92
  * while the sweep ran is settled by neither: that read is newer than the sweep's answer. */
115
- function settle(envelope, reading, snapshot, { settlement: { settle: settles, release: released } }, newer) {
93
+ function settle(envelope, reading, snapshot, { settle: settles, release: released }, newer) {
116
94
  const settleIfNotNewer = home => { if (!newer.has(home)) settled.add(home); };
117
95
  if (sweepCompleted(envelope, reading)) for (const home of snapshot) settleIfNotNewer(home);
118
96
  for (const home of settles) settleIfNotNewer(home);
@@ -134,11 +112,11 @@ export function createResumeTrigger({ cli, run = runResumeSweep, read = readResu
134
112
  try {
135
113
  const envelope = await run(probe);
136
114
  try {
137
- const news = digest(envelope);
138
- reading = read(news.envelope);
115
+ // The settlement is taken before the read: a throw from either reads as failed and settles nothing.
116
+ const settlement = sweepSettlement(envelope);
117
+ reading = read(envelope);
139
118
  releasedDuring = null;
140
- settle(envelope, reading, snapshot, news, newer);
141
- for (const key of shownHostKeys(reading, news.hostKeys)) reportedHost.add(key);
119
+ settle(envelope, reading, snapshot, settlement, newer);
142
120
  } catch { reading = { kind: 'failed', code: 'E_CLI_PROTOCOL' }; }
143
121
  } catch { reading = { kind: 'failed', code: 'E_CLI_FAILED' }; }
144
122
  if (!disposed && typeof onReading === 'function') { try { onReading(reading); } catch { /* the caller's */ } }