@awebai/oats 0.69.1 → 0.69.2

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 (67) 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 +260 -28
  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 +3 -3
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/servers.md +7 -2
  17. package/docs/soul.schema.json +1 -0
  18. package/docs/souls-and-instances.md +35 -2
  19. package/docs/tui.md +100 -9
  20. package/docs/upgrading.md +9 -5
  21. package/docs/workspaces.md +2 -2
  22. package/injects/instance-boundary.md +19 -33
  23. package/injects/work-attached.md +8 -13
  24. package/injects/work-checkout.md +16 -30
  25. package/injects/work-directory.md +9 -15
  26. package/injects/work-workspace.md +8 -19
  27. package/injects/work-worktree.md +18 -33
  28. package/lib/capability-contract.mjs +2 -2
  29. package/lib/core.mjs +162 -49
  30. package/lib/instance-background.mjs +54 -0
  31. package/lib/instance-inspect.mjs +3 -0
  32. package/lib/instance-lifecycle.mjs +35 -0
  33. package/lib/instance-resolution.mjs +3 -2
  34. package/lib/instance-same-work.mjs +67 -0
  35. package/lib/instance-upgrade.mjs +18 -0
  36. package/lib/materialize.mjs +23 -2
  37. package/lib/resolve.mjs +32 -5
  38. package/lib/servers.mjs +19 -4
  39. package/lib/session-resume-contract.mjs +1 -0
  40. package/lib/session-resume.mjs +36 -9
  41. package/lib/soul-composition.mjs +13 -10
  42. package/lib/workspace.mjs +3 -2
  43. package/package-catalog.json +2 -2
  44. package/package.json +1 -1
  45. package/packages/client/cli-adapter.mjs +30 -8
  46. package/packages/client/deployment-data.mjs +9 -0
  47. package/packages/client/deployment-panel.mjs +4 -0
  48. package/packages/client/instance-tree.mjs +64 -14
  49. package/packages/client/panel-views.mjs +11 -3
  50. package/packages/client/remote-roster.mjs +5 -1
  51. package/packages/client/roster-sections.mjs +50 -6
  52. package/packages/client/same-work.mjs +49 -0
  53. package/packages/client/session-resume.mjs +1 -1
  54. package/packages/client/soul-rows.mjs +2 -0
  55. package/packages/client/spawn-apply-contract.mjs +2 -1
  56. package/packages/client/spawn-decision.mjs +4 -1
  57. package/packages/client/spawn-preview-contract.mjs +12 -1
  58. package/packages/client/spawn-preview.mjs +2 -0
  59. package/packages/tui/README.md +2 -2
  60. package/packages/tui/lib/client.mjs +6 -2
  61. package/packages/tui/lib/main.mjs +44 -11
  62. package/packages/tui/lib/model.mjs +101 -43
  63. package/packages/tui/lib/store.mjs +76 -20
  64. package/packages/tui/lib/views/frame.mjs +2 -0
  65. package/packages/tui/lib/views/help.mjs +2 -0
  66. package/packages/tui/lib/views/instances.mjs +38 -1
  67. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -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
@@ -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));
@@ -236,7 +236,7 @@ const rowShape = {
236
236
  };
237
237
  const copyRow = r => Object.hasOwn(r, 'warnings') ? { ...r, warnings: [...r.warnings] } : { ...r };
238
238
 
239
- /** The summary as it crossed a boundary (main to a renderer over IPC): the same summary, a fresh copy, or
239
+ /** The summary as given to resumeNotice, decoded again at that boundary: the same summary, a fresh copy, or
240
240
  * undefined. Exactly the keys above, everywhere; names and paths display lines, never withheld or empty;
241
241
  * reasons one of their kind's or null; codes of the kernel's form or null; each row's warnings within both
242
242
  * bounds with `omitted` consistent (boundedWarningsValid); at most RESUME_SUMMARY_ROWS rows and
@@ -37,6 +37,8 @@ export function soulRows(deployment, catalog) {
37
37
  ...(Object.hasOwn(soul, "capabilities") ? { capabilities: soul.capabilities && soul.capabilities.map((c) => ({ ...c })) } : {}),
38
38
  // The kernel's soul key (`oats soul teams <key>`): the qualified name for a package soul, the bare name otherwise.
39
39
  ...(typeof soul.key === "string" ? { key: soul.key } : {}),
40
+ // Feature instance-background (#1579): the soul runs its instances in the background unless a spawn says otherwise.
41
+ ...(soul.background === true ? { background: true } : {}),
40
42
  ...(soul.kind === "package" ? { package: soul.package, version: soul.version, qualifiedName: soul.qualifiedName } : {}),
41
43
  origin: soul.origin || "", soulKind: soul.kind, repo: soul.repoKey || null, capability: null,
42
44
  soulSource: { repoKey: soul.repoKey ?? null, commit: soul.commit ?? null, path: soul.path ?? null },
@@ -32,7 +32,8 @@ export function spawnApplyChoicesSupported(cli, choices, wakeRequested = false)
32
32
  && (!choices.launchConfig || has(cli?.features, 'launch-config'))
33
33
  && (!wakeRequested || has(cli?.features, 'schedule'))
34
34
  && (choices.name === undefined || has(cli?.features, 'spawn-name'))
35
- && (choices.identity === undefined || has(cli?.features, 'spawn-provider-payload'));
35
+ && (choices.identity === undefined || has(cli?.features, 'spawn-provider-payload'))
36
+ && (choices.background === undefined || has(cli?.features, 'instance-background'));
36
37
  }
37
38
  export function spawnWake(v) {
38
39
  if (!exact(v, ['cron', 'tz', 'message', 'enabled']) || !text(v.cron, 256) || !v.cron.trim()
@@ -10,6 +10,9 @@ export function spawnEffective(v) {
10
10
  || !HARNESSES.includes(harnessOf(v)) || !nullable(v.model) || !nullable(v.launchConfig)
11
11
  || v.yolo !== null && typeof v.yolo !== 'boolean' || v.backend !== 'tmux'
12
12
  || typeof v.childSpawns !== 'boolean') return null;
13
+ // Feature instance-background (#1579): the decision binds `background: true` exactly when the instance runs in the
14
+ // background; it is absent otherwise (any other value is not the contract's).
15
+ if (Object.hasOwn(v, 'background') && v.background !== true) return null;
13
16
  let relation = null;
14
17
  if (v.relation !== null) {
15
18
  const r = v.relation, a = r?.anchor;
@@ -18,7 +21,7 @@ export function spawnEffective(v) {
18
21
  relation = { kind: r.kind, anchor: { instance: a.instance, agentsRoot: a.agentsRoot } };
19
22
  }
20
23
  return { repo: v.repo, work: v.work, harness: harnessOf(v), model: v.model, launchConfig: v.launchConfig,
21
- yolo: v.yolo, backend: v.backend, childSpawns: v.childSpawns, relation };
24
+ yolo: v.yolo, backend: v.backend, childSpawns: v.childSpawns, relation, ...(v.background === true ? { background: true } : {}) };
22
25
  }
23
26
  export function spawnDecision(v, { effectiveRequired = false } = {}) {
24
27
  if (!record(v) || !name(v.instance) || !absolute(v.home) || !nullable(v.branch)
@@ -185,7 +185,7 @@ export function previewSelector(v) {
185
185
  return exact(v, ['soul', 'agentsRoot']) && name(v.soul) && absolute(v.agentsRoot) ? { soul: v.soul, agentsRoot: v.agentsRoot } : null;
186
186
  }
187
187
  export function previewChoices(v) {
188
- if (!exact(v, ['purpose', 'name', 'work', 'branch', 'base', 'harness', 'model', 'launchConfig', 'backend', 'yolo', 'relation', 'identity', 'join'])) return null;
188
+ if (!exact(v, ['purpose', 'name', 'work', 'branch', 'base', 'harness', 'model', 'launchConfig', 'backend', 'yolo', 'background', 'relation', 'identity', 'join'])) return null;
189
189
  // --name (exact, unprefixed; feature spawn-name) and --purpose are mutually exclusive.
190
190
  if (Object.hasOwn(v, 'purpose') && Object.hasOwn(v, 'name')) return null;
191
191
  const out = {};
@@ -198,6 +198,9 @@ export function previewChoices(v) {
198
198
  // The only work override the Desktop offers: a checkout soul in a worktree.
199
199
  if (Object.hasOwn(v, 'work')) { if (v.work !== 'worktree') return null; out.work = 'worktree'; }
200
200
  if (Object.hasOwn(v, 'yolo')) { if (typeof v.yolo !== 'boolean') return null; out.yolo = v.yolo; }
201
+ // Run in background (feature instance-background, #1579): present only when the dialog's switch differs from the
202
+ // soul's declared default; the kernel then records the instance's own flag (--background / --no-background).
203
+ if (Object.hasOwn(v, 'background')) { if (typeof v.background !== 'boolean') return null; out.background = v.background; }
201
204
  // Messaging identity (decision 27; feature spawn-provider-payload): sent to
202
205
  // the soul's messaging provider as --provider <cap> identity.mode=… — there
203
206
  // is no kernel flag. `provider` is the capability the preview reported on
@@ -243,6 +246,7 @@ export function choiceArgv(choices, cli) {
243
246
  for (const [k, flag] of [['purpose', '--purpose'], ['name', '--name'], ['work', '--work'], ['branch', '--branch'], ['base', '--base'], ['harness', harnessFlag(cli)], ['launchConfig', '--launch-config'], ['backend', '--backend']]) if (choices[k] !== undefined) argv.push(flag, choices[k]);
244
247
  if (choices.model.kind !== 'inherit') argv.push('--model', choices.model.kind === 'native-default' ? '@native-default' : choices.model.value);
245
248
  if (choices.yolo !== undefined) argv.push(choices.yolo ? '--yolo' : '--no-yolo');
249
+ if (choices.background !== undefined) argv.push(choices.background ? '--background' : '--no-background');
246
250
  if (choices.relation.kind !== 'unrelated') argv.push('--relation', choices.relation.kind, '--relative-to', choices.relation.anchor.instance, '--relative-root', choices.relation.anchor.agentsRoot);
247
251
  if (choices.identity) {
248
252
  argv.push('--provider', choices.identity.provider, `identity.mode=${choices.identity.mode}`);
@@ -362,6 +366,12 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
362
366
  // name is then not known to be the one a `--name` preview would give.
363
367
  const naming = Object.hasOwn(v, 'naming') ? namingOf(v.naming) : undefined;
364
368
  if (naming === null) return null;
369
+ // Feature instance-background (#1579): `background`, always present on a kernel with the feature (absent: an older
370
+ // one, which offers no switch), agrees with the decision, which binds `effective.background: true` exactly when it
371
+ // is true; `backgroundFrom` ("flag" or "soul", absent when neither declared it) says who chose it.
372
+ const background = Object.hasOwn(v, 'background') ? v.background : undefined;
373
+ if (background !== undefined && typeof background !== 'boolean' || (background === true) !== (e.background === true)
374
+ || Object.hasOwn(v, 'backgroundFrom') && (background === undefined || !['flag', 'soul'].includes(v.backgroundFrom))) return null;
365
375
  // Only reports carry `problem`: a preview that would hit one refuses with the error instead.
366
376
  if (Object.hasOwn(v, 'launch') && (launch === undefined || launch.problem !== null || launch.effective.harness !== e.harness || launch.effective.model !== e.model
367
377
  || launch.effective.launchConfig !== e.launchConfig)) return null;
@@ -374,6 +384,7 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
374
384
  ...(defaultTeam !== undefined ? { defaultTeam } : {}), ...(launch ? { launch } : {}),
375
385
  ...(launchPromptAnswers ? { launchPromptAnswers } : {}),
376
386
  ...(naming ? { naming } : {}),
387
+ ...(background !== undefined ? { background, ...(Object.hasOwn(v, 'backgroundFrom') ? { backgroundFrom: v.backgroundFrom } : {}) } : {}),
377
388
  // Capability warnings (0.49.0): the kernel's message strings, tolerant and idempotent (a malformed list reads as none,
378
389
  // never refuses the preview); absent on an older kernel. Shown only: the apply binds nothing on them.
379
390
  ...(Object.hasOwn(v, 'warnings') ? { warnings: previewWarningsOf(v.warnings) } : {}) };
@@ -78,6 +78,8 @@ export function admitSpawnSelection(selector, choices, { workspace: w, cli, agen
78
78
  // An exact (unprefixed) name only where the CLI advertises it.
79
79
  if (choices.name !== undefined && !cli.features.includes('spawn-name')) return fail('E_UNSUPPORTED_OPTION');
80
80
  if (choices.identity !== undefined && !cli.features.includes('spawn-provider-payload')) return fail('E_UNSUPPORTED_OPTION');
81
+ // Run in background (#1579): --background / --no-background only where the CLI lists instance-background.
82
+ if (choices.background !== undefined && !cli.features.includes('instance-background')) return fail('E_UNSUPPORTED_OPTION');
81
83
  // The one work override offered: a checkout soul asked for a worktree.
82
84
  if (choices.work !== undefined && soul.work !== 'checkout') return fail('E_UNSUPPORTED_OPTION');
83
85
  const work = choices.work ?? soul.work;
@@ -20,7 +20,7 @@ never does.
20
20
  | path | contents |
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
- | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
23
+ | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; the kernel's machine sweep of lost sessions (`oats session resume --json`), when the shared resume trigger says (after that add has settled, and when a read shows a lost session), through `changeExec`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
25
  | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
@@ -77,7 +77,7 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
77
77
  a block that says what its command never says ends that client (THE
78
78
  CAPTURE in `lib/panel.mjs`). A
79
79
  change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
80
- start, a restart, a spawn's apply) is never signalled on the way out: it
80
+ start, a restart, a spawn's apply, the machine sweep) is never signalled on the way out: it
81
81
  is let go, and its output goes to files, so it never meets a closed pipe.
82
82
  Only a spawn's apply has a deadline, the shared apply's, at which it is
83
83
  sent its signal (`timeout`, `killSignal`), and only while the run lasts:
@@ -22,8 +22,8 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
22
22
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
23
23
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
24
24
  export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
25
- export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings } from "../../client/instance-tree.mjs";
26
- export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
25
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE } from "../../client/instance-tree.mjs";
26
+ export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, rosterSectionKey, sidebarSections } from "../../client/roster-sections.mjs";
27
27
  export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
28
28
  export { instanceDisplayName } from "../../client/instance-display-name.mjs";
29
29
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
@@ -38,6 +38,10 @@ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flig
38
38
  export { startGate, startInstance } from "../../client/session-start.mjs";
39
39
  export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
40
40
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
41
+ // #1559: the kernel's machine sweep, run when the TUI opens and when a read shows a lost session
42
+ // (lib/main.mjs): the shared trigger decides when, the runner runs it, and the reader words what it did.
43
+ export { runResumeSweep } from "../../client/session-resume-cli.mjs";
44
+ export { createResumeTrigger, localDeploymentIds } from "../../client/session-resume-trigger.mjs";
41
45
  export { validateWorkspace } from "../../client/workspace-admission.mjs";
42
46
  export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
43
47
  export { soulRows } from "../../client/soul-rows.mjs";