@awebai/oats 0.51.0 → 0.53.0

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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,462 @@
1
+ /** The roster as a tree, from the kernel's rows alone: who is who (instanceId), who relates to whom
2
+ * (the parent and sibling links, resolved by identity), which groups, in what order, what is visible
3
+ * under a filter or a collapse, who waits below a collapsed row, and what holds a home. No document,
4
+ * no element: a client draws from these answers with its own means. */
5
+ import { waitingClaim } from './waiting-on-you.mjs';
6
+
7
+ export function collapseKey(workspace, instance) {
8
+ return `${workspace || ""}\u0000${instance}`;
9
+ }
10
+
11
+ /** Names an instance is directly related to (undirected edge endpoints):
12
+ * its spawn parent plus its explicit sibling link. Kernel contract
13
+ * (feature/agent-relations, final): `parentInstance` and `siblingInstance`
14
+ * (string, only set when a sibling relation was declared against a ROOT
15
+ * instance — a sibling of a non-root simply shares the anchor's parent).
16
+ * Absent fields contribute no edges. */
17
+ export function instanceLinks(instance) {
18
+ const out = [];
19
+ if (instance.parentInstance) out.push(instance.parentInstance);
20
+ if (instance.siblingInstance) out.push(instance.siblingInstance);
21
+ return out.filter((name) => name && name !== instance.instance);
22
+ }
23
+
24
+ /** Stable identity for one roster instance. Instance NAMES are only unique
25
+ * within one agents root — the kernel permits duplicate names across agent
26
+ * dirs/team repos — so graph code must never key nodes by bare name (a
27
+ * duplicate would silently hide a live instance; merged-state review
28
+ * f7c5769). The canonical home path is unique per instance; agentsRoot+name
29
+ * is the fallback; bare name only when the roster carries neither. */
30
+ export function instanceId(instance) {
31
+ const local = instance.home ? String(instance.home)
32
+ : instance.agentsRoot ? `${instance.agentsRoot}\u0000${instance.instance}` : String(instance.instance);
33
+ // Canonical paths are unique only within a host. Preserve existing local keys.
34
+ return instance.server ? `server:${instance.server}\u0000${local}` : local;
35
+ }
36
+
37
+ /** Resolve one relation-edge NAME to the id of the instance it means.
38
+ * Relation names come from instance.json lineage, which is recorded within
39
+ * one deployment scope — so a name resolves to the same-agentsRoot instance
40
+ * first; a name that is globally unique resolves cross-root; an AMBIGUOUS
41
+ * name — no same-root candidate, or MORE THAN ONE same-root candidate
42
+ * (intra-root duplicates are legal and inherently ambiguous; merged-state
43
+ * review @7dd1e7b) — resolves to nothing (fail safe: two separate clusters,
44
+ * never a wrong merge, a false edge, or a hidden node).
45
+ * EXPORTED as the one shared resolver — the hierarchy and cluster maps
46
+ * must use the same semantics rather than re-implementing them.
47
+ * byName: Map<name, instance[]> over the same roster. */
48
+ export function resolveLinkId(fromInstance, name, byName) {
49
+ const candidates = byName.get(name)?.filter((i) => (i.server || "") === (fromInstance.server || ""));
50
+ if (!candidates || !candidates.length) return null;
51
+ if (candidates.length === 1) return instanceId(candidates[0]);
52
+ const sameRoot = candidates.filter((c) => c.agentsRoot && c.agentsRoot === fromInstance.agentsRoot);
53
+ return sameRoot.length === 1 ? instanceId(sameRoot[0]) : null;
54
+ }
55
+
56
+ /** Group instances into agent CLUSTERS — connected components of the
57
+ * undirected relation graph (parent/child spawn edges + sibling links).
58
+ * Unrelated instances are single-node clusters. Within a cluster the
59
+ * parent/child tree ordering is kept (parent-first walk with depth);
60
+ * cluster members related only by sibling links sit at depth 0.
61
+ * Nodes are keyed by instanceId (composite identity), never bare name —
62
+ * duplicate names across repos render as distinct nodes.
63
+ * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked
64
+ * running-first then by first member name, matching the roster sort. */
65
+ export function clusterInstances(instances, { links = instanceLinks } = {}) {
66
+ const byId = new Map(instances.map((i) => [instanceId(i), i]));
67
+ const byName = new Map();
68
+ for (const i of instances) {
69
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
70
+ byName.get(i.instance).push(i);
71
+ }
72
+ // undirected adjacency over IDs — unresolvable/ambiguous edges are ignored
73
+ const adj = new Map(instances.map((i) => [instanceId(i), new Set()]));
74
+ const parentIdOf = new Map(); // id -> resolved parent id (tree ordering)
75
+ for (const i of instances) {
76
+ const id = instanceId(i);
77
+ if (i.parentInstance) {
78
+ const pid = resolveLinkId(i, i.parentInstance, byName);
79
+ if (pid && pid !== id) parentIdOf.set(id, pid);
80
+ }
81
+ for (const other of links(i)) {
82
+ const oid = resolveLinkId(i, other, byName);
83
+ if (!oid || oid === id) continue;
84
+ adj.get(id).add(oid);
85
+ adj.get(oid).add(id);
86
+ }
87
+ }
88
+ const rank = (a, b) => (a.running === b.running ? a.instance.localeCompare(b.instance) : a.running ? -1 : 1);
89
+ const seen = new Set();
90
+ const clusters = [];
91
+ for (const start of [...instances].sort(rank)) {
92
+ if (seen.has(instanceId(start))) continue;
93
+ // collect the component
94
+ const members = [];
95
+ const queue = [instanceId(start)];
96
+ seen.add(instanceId(start));
97
+ while (queue.length) {
98
+ const id = queue.shift();
99
+ members.push(byId.get(id));
100
+ for (const next of adj.get(id) || []) if (!seen.has(next)) { seen.add(next); queue.push(next); }
101
+ }
102
+ // parent-first tree order INSIDE the component (cycle-safe: the walk
103
+ // visits each member once; leftovers append at depth 0)
104
+ const memberIds = new Set(members.map(instanceId));
105
+ const kids = (p) => members.filter((i) => parentIdOf.get(instanceId(i)) === instanceId(p));
106
+ const roots = members.filter((i) => {
107
+ const pid = parentIdOf.get(instanceId(i));
108
+ return !pid || !memberIds.has(pid);
109
+ });
110
+ roots.sort(rank);
111
+ const ordered = [];
112
+ const placed = new Set();
113
+ const walk = (i, depth) => {
114
+ if (placed.has(instanceId(i))) return;
115
+ placed.add(instanceId(i));
116
+ ordered.push({ ...i, depth });
117
+ kids(i).sort(rank).forEach((k) => walk(k, depth + 1));
118
+ };
119
+ roots.forEach((r) => walk(r, 0));
120
+ for (const i of [...members].sort(rank)) walk(i, 0); // malformed cycles must not hide members
121
+ // Deterministic cluster label: the lexically-smallest ROOT name —
122
+ // independent of liveness, so the visible cluster name does not flip
123
+ // when a different member starts/stops running (review f921f7d nit).
124
+ // Running-first `rank` still governs display ORDER within the cluster.
125
+ const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
126
+ clusters.push({ key: rootNames[0], instances: ordered });
127
+ }
128
+ return clusters;
129
+ }
130
+
131
+ /** Find the roster instance a UI reference means. References carry the
132
+ * display name plus whatever identity the caller knows (home/agentsRoot —
133
+ * sidebar rows know both; older callers pass a bare name). Identity match
134
+ * wins; bare names resolve only when unambiguous in the roster — an
135
+ * ambiguous bare name returns null rather than the first same-named match
136
+ * (which could open the WRONG agents root's tmux session; review 46f3fdc).
137
+ * Importable so the duplicate-name regression exercises this exact layer. */
138
+ export function findRosterInstance(instances, ref) {
139
+ const name = typeof ref === "string" ? ref : ref.instance;
140
+ const home = typeof ref === "string" ? undefined : ref.home;
141
+ const root = typeof ref === "string" ? undefined : ref.agentsRoot;
142
+ // An object reference names a host (absent server means local). A legacy
143
+ // bare name can still resolve across the roster, but only if unambiguous.
144
+ if (typeof ref !== "string") instances = instances.filter((i) => (i.server || "") === (ref.server || ""));
145
+ if (home) {
146
+ const byHome = instances.find((i) => i.home === home);
147
+ if (byHome) return byHome;
148
+ }
149
+ if (root) {
150
+ const byRoot = instances.find((i) => i.instance === name && i.agentsRoot === root);
151
+ if (byRoot) return byRoot;
152
+ }
153
+ const named = instances.filter((i) => i.instance === name);
154
+ return named.length === 1 ? named[0] : null;
155
+ }
156
+
157
+ /** Shortest DISTINGUISHING path suffixes for a set of agents roots.
158
+ * Duplicate instance names are told apart by where they home, but naive
159
+ * single-segment tags collide (/a/project/agents and /b/project/agents both
160
+ * render "project"). Grow each root's suffix segment-by-segment until it is
161
+ * unique within the set; fall back to the full root. Returns Map<root, tag>.
162
+ * (Review cbd5bb3: duplicate option labels must actually differ.) */
163
+ export function distinguishingRootTags(roots) {
164
+ const uniq = [...new Set(roots.filter(Boolean).map(String))];
165
+ const segs = new Map(uniq.map((r) => [r, r.split("/").filter(Boolean)]));
166
+ const tags = new Map();
167
+ for (const root of uniq) {
168
+ const mine = segs.get(root);
169
+ // skip the trailing "agents"-style leaf shared by every root: start the
170
+ // suffix ABOVE the leaf, then extend upward until unique
171
+ let take = 2; // leaf + one parent
172
+ let tag;
173
+ for (; take <= mine.length; take++) {
174
+ tag = mine.slice(-take, -1).join("/");
175
+ const clash = uniq.some((other) => other !== root
176
+ && segs.get(other).slice(-take, -1).join("/") === tag);
177
+ if (!clash) break;
178
+ }
179
+ tags.set(root, take > mine.length || !tag ? root : tag);
180
+ }
181
+ return tags;
182
+ }
183
+
184
+ /** Whether an instance has children IN ITS OWN identity — parent edges
185
+ * resolve through resolveLinkId, so a childless parent whose NAME is shared
186
+ * by a parent in another agents root gets no disclosure control (review
187
+ * 7d740f9). Accepts the full instance object; the legacy bare-name call
188
+ * shape (string) keeps name matching for rosters without identity fields. */
189
+ export function hasInstanceChildren(instances, instance) {
190
+ if (typeof instance === "string") {
191
+ return instances.some((candidate) => candidate.parentInstance === instance);
192
+ }
193
+ const byName = new Map();
194
+ for (const i of instances) {
195
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
196
+ byName.get(i.instance).push(i);
197
+ }
198
+ const id = instanceId(instance);
199
+ return instances.some((candidate) => candidate.parentInstance
200
+ && resolveLinkId(candidate, candidate.parentInstance, byName) === id);
201
+ }
202
+
203
+ export function instanceRepoLabel(instance) {
204
+ if (instance.repoName) return String(instance.repoName);
205
+ const path = instance.repo || instance.workspace || "";
206
+ return String(path).split("/").filter(Boolean).at(-1) || "workspace";
207
+ }
208
+
209
+ /* ── homes the kernel holds (#802) ── */
210
+
211
+ const HELD_HOMES = Object.freeze({
212
+ spawning: { state: "Setting up worktree…", status: "Spawning (setting up worktree)", retire: false,
213
+ sentence: name => `${name} is setting up its worktree. It can't be used until the spawn finishes.` },
214
+ "spawn-incomplete": { state: "Spawn didn't finish", hint: "Retire it to clean up", status: "Spawn didn't finish", retire: true,
215
+ sentence: name => `The spawn of ${name} didn't finish. Retire it to clean up.` },
216
+ "retire-incomplete": { state: "Retire didn't finish", hint: "Retire it again to complete", status: "Retire didn't finish", retire: true,
217
+ sentence: name => `The retire of ${name} didn't finish. Retire it again to complete.` },
218
+ });
219
+ /** What the kernel's roster row says holds this home, or null (#802): `spawning` while a spawn that
220
+ * runs its worktree hooks is verifiably alive (`spawnInProgress: true`), `spawn-incomplete` when a
221
+ * spawn left it for retire to clean up (`rollbackIncomplete`), `retire-incomplete` when a retire did
222
+ * (`retirePending`). rollbackIncomplete wins over spawnInProgress (the spawn is gone, not live), and a
223
+ * live spawn over retirePending (the kernel refuses to retire it). Every surface draws such a row from
224
+ * this: a spawning one starts, stops, retires and splits nothing; a quarantined one (`retire`) offers
225
+ * Retire only. `state` is the row's text, `hint` its muted line, `status` the hover card's Status.
226
+ * `sentence` is every client's, so it promises no act of one client: a spawning home "can't be used
227
+ * until the spawn finishes", whoever started the spawn and whether or not it ends finished. */
228
+ export function heldHome(instance) {
229
+ const kind = !instance ? null : instance.rollbackIncomplete ? "spawn-incomplete"
230
+ : instance.spawnInProgress === true ? "spawning" : instance.retirePending ? "retire-incomplete" : null;
231
+ return kind ? { kind, ...HELD_HOMES[kind] } : null;
232
+ }
233
+
234
+ /* ── roster grouping: repo → agent family (soul), with sort modes ── */
235
+
236
+ export const ROSTER_SORTS = Object.freeze([
237
+ Object.freeze({ id: "status", label: "Status (running first)" }),
238
+ Object.freeze({ id: "name", label: "Name" }),
239
+ ]);
240
+
241
+ /** Comparator for one sibling level. "status" ranks running instances first,
242
+ * then by name; "name" is purely alphabetical. Unknown ids fall back to
243
+ * "status" so a stale persisted choice can never break rendering. */
244
+ export function rosterRank(sortBy) {
245
+ const byName = (a, b) => String(a.instance).localeCompare(String(b.instance));
246
+ if (sortBy === "name") return byName;
247
+ return (a, b) => (!!a.running === !!b.running ? byName(a, b) : a.running ? -1 : 1);
248
+ }
249
+
250
+ /** Group a roster list repo → agent family (soul), each family's items in
251
+ * lineage order (parents before children, depth annotated) with siblings
252
+ * sorted by `sortBy`. Lineage links crossing family/repo boundaries are cut:
253
+ * such children render as roots of their own family group. Returns
254
+ * Map<repoLabel, Map<familyName, item[]>> with deterministic group order:
255
+ * repos and families alphabetical. */
256
+ export function groupRosterFamilies(list, sortBy = "status") {
257
+ const rank = rosterRank(sortBy);
258
+ const repos = new Map();
259
+ for (const i of list) {
260
+ // instance.json is workspace-controlled: agent/repoName may arrive as
261
+ // non-strings through the reader. Coerce grouping keys so one malformed
262
+ // instance cannot throw in localeCompare and blank the whole roster.
263
+ const rName = String(instanceRepoLabel(i));
264
+ if (!repos.has(rName)) repos.set(rName, new Map());
265
+ const families = repos.get(rName);
266
+ const fName = String(i.agent || "?");
267
+ if (!families.has(fName)) families.set(fName, []);
268
+ families.get(fName).push(i);
269
+ }
270
+ const sortedRepos = new Map([...repos.entries()].sort(([a], [b]) => a.localeCompare(b)));
271
+ for (const [rName, families] of sortedRepos) {
272
+ const sortedFamilies = new Map([...families.entries()].sort(([a], [b]) => a.localeCompare(b)));
273
+ for (const [fName, items] of sortedFamilies) {
274
+ const byName = new Map(items.map((i) => [i.instance, i]));
275
+ const roots = items.filter((i) => !i.parentInstance || !byName.has(i.parentInstance));
276
+ const kids = (p) => items.filter((i) => i.parentInstance === p.instance);
277
+ const ordered = [];
278
+ const seen = new Set();
279
+ const walk = (i, depth) => {
280
+ if (seen.has(i.instance)) return; // cycle-safe
281
+ seen.add(i.instance);
282
+ ordered.push({ ...i, depth });
283
+ kids(i).sort(rank).forEach((k) => walk(k, depth + 1));
284
+ };
285
+ roots.sort(rank).forEach((r) => walk(r, 0));
286
+ for (const i of items) if (!seen.has(i.instance)) ordered.push({ ...i, depth: 0 });
287
+ sortedFamilies.set(fName, ordered);
288
+ }
289
+ sortedRepos.set(rName, sortedFamilies);
290
+ }
291
+ return sortedRepos;
292
+ }
293
+
294
+ /** Stable collapse key for a roster GROUP header (repo or repo+family),
295
+ * workspace-scoped like instance collapse keys. */
296
+ export function rosterGroupKey(workspace, ...parts) {
297
+ return [`g:${workspace || ""}`, ...parts].join("\u0000");
298
+ }
299
+
300
+ /** Whether an instance itself matches the roster filter (its name, soul or repository) — as
301
+ * opposed to an ancestor shown only to keep a match's tree path. */
302
+ export function instanceMatchesFilter(item, query) {
303
+ const needle = String(query || "").trim().toLowerCase();
304
+ if (!needle) return true;
305
+ return [item.instance, item.agent, item.repoName]
306
+ .some((value) => String(value || "").toLowerCase().includes(needle));
307
+ }
308
+
309
+ /** Include matching instances plus their ancestor paths, in source order.
310
+ * IDENTITY-aware (merged-state review @3e76616): inclusion keys by
311
+ * instanceId and ancestors resolve through resolveLinkId over the FULL
312
+ * roster — a same-named instance in another root never leaks into this
313
+ * one's filter results, and an ambiguous parent edge includes nothing.
314
+ * `matches` decides what matches (default: the sidebar's instanceMatchesFilter);
315
+ * the command palette passes its fuzzy matcher and shares the tree path. */
316
+ export function filterInstanceTree(instances, query, matches = null) {
317
+ const needle = String(query || "").trim().toLowerCase();
318
+ if (!needle) return instances;
319
+ const isMatch = matches || ((item) => instanceMatchesFilter(item, needle));
320
+ const byId = new Map(instances.map((item) => [instanceId(item), item]));
321
+ const byName = new Map();
322
+ for (const item of instances) {
323
+ if (!byName.has(item.instance)) byName.set(item.instance, []);
324
+ byName.get(item.instance).push(item);
325
+ }
326
+ const included = new Set();
327
+ for (const item of instances) {
328
+ if (!isMatch(item)) continue;
329
+ let cursor = item;
330
+ const seen = new Set();
331
+ while (cursor) {
332
+ const id = instanceId(cursor);
333
+ if (seen.has(id)) break;
334
+ included.add(id);
335
+ seen.add(id);
336
+ const pid = cursor.parentInstance ? resolveLinkId(cursor, cursor.parentInstance, byName) : null;
337
+ cursor = pid ? byId.get(pid) : null;
338
+ }
339
+ }
340
+ return instances.filter((item) => included.has(instanceId(item)));
341
+ }
342
+
343
+ /** Cluster the FULL roster, then project each cluster to its visible
344
+ * members — never cluster a filtered subset: dropping roster rows can turn
345
+ * a globally AMBIGUOUS relation edge into a false unique edge, silently
346
+ * re-linking nodes while the user types (merged-state review @3e76616).
347
+ * Cluster order and member depths come from the full-roster computation;
348
+ * clusters with no visible member disappear. */
349
+ export function visibleClusters(allInstances, visibleInstances, { links = instanceLinks } = {}) {
350
+ const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
351
+ return clusterInstances(allInstances, { links })
352
+ .map((c) => ({ ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) }))
353
+ .filter((c) => c.instances.length);
354
+ }
355
+
356
+ /** The sidebar roster's groups (Redesign v3), shared with the command palette:
357
+ * each multi-member relation cluster under its deterministic name, then every
358
+ * unrelated instance under "independent". A cluster's group is decided on the
359
+ * FULL roster: more than one member there is a group under the cluster's name,
360
+ * exactly one goes under "independent". A filter or a collapse decides which
361
+ * rows are listed and never moves a row to another group; a group with no
362
+ * visible row is left out. Returns [{ key, label, clusters: [{ key, instances }] }]
363
+ * in the full roster's cluster order, each cluster projected to its visible
364
+ * members, which carry their tree depth. A group's key is unique even when two
365
+ * roots share a name (other agents roots or hosts), and does not depend on what
366
+ * is visible: the label is the name, the key adds the cluster's place among the
367
+ * multi-member clusters of the full roster. */
368
+ export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks } = {}) {
369
+ const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
370
+ const named = [], independent = [];
371
+ let place = 0;
372
+ for (const c of clusterInstances(allInstances, { links })) {
373
+ const at = c.instances.length > 1 ? place++ : -1;
374
+ const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
375
+ if (!shown.instances.length) continue;
376
+ if (at < 0) independent.push(shown);
377
+ else named.push({ key: `cluster:${at}:${c.key}`, label: c.key, clusters: [shown] });
378
+ }
379
+ return [...named, ...(independent.length ? [{ key: "independent", label: "independent", clusters: independent }] : [])];
380
+ }
381
+
382
+ /** Whether an item remains visible under VS Code-style collapsed ancestors.
383
+ * Filtering temporarily reveals matching paths without mutating the user's
384
+ * persisted collapse state. Parent traversal is cycle-safe and
385
+ * IDENTITY-aware: collapse keys are minted from instanceId, and parent
386
+ * names resolve through resolveLinkId so a collapsed duplicate name in
387
+ * another agents root can never hide this root's subtree (review 46f3fdc).
388
+ * `section(row)` (optional): the roster section (deployment) a row is painted in. A collapse hides only
389
+ * rows of its own section: the walk stops at the first ancestor painted in another section, which does
390
+ * not hide the row (#551's visible symptom: resolveLinkId accepts a unique name from another agents root,
391
+ * and that parent is painted, and collapsed, in another section). Without it, sections are ignored. */
392
+ export function instanceVisibleInTree(instance, allInstances, collapsed, workspace, filtering = false, { section } = {}) {
393
+ if (filtering) return true;
394
+ const byId = new Map(allInstances.map((item) => [instanceId(item), item]));
395
+ const byName = new Map();
396
+ for (const item of allInstances) {
397
+ if (!byName.has(item.instance)) byName.set(item.instance, []);
398
+ byName.get(item.instance).push(item);
399
+ }
400
+ const seen = new Set([instanceId(instance)]);
401
+ let cursor = instance;
402
+ while (cursor?.parentInstance) {
403
+ const pid = resolveLinkId(cursor, cursor.parentInstance, byName);
404
+ if (!pid || seen.has(pid)) break;
405
+ const parent = byId.get(pid);
406
+ if (section && parent && section(parent) !== section(instance)) break;
407
+ if (collapsed.has(collapseKey(workspace, pid))) return false;
408
+ seen.add(pid);
409
+ cursor = parent;
410
+ }
411
+ return true;
412
+ }
413
+
414
+ /** Needs input (Spec D): waiting instances hidden by a collapse, attributed to their nearest visible ancestor:
415
+ * Map(instanceId(ancestor) → [waiting rows]). Computed over the full roster (as clustering is) by the
416
+ * parent relation only (resolveLinkId: never across a remote server), cycle-safe; a missing or cyclic
417
+ * parent chain degrades to no roll-up. `section(row)`: the roster section (deployment) a row is painted
418
+ * in; a chain that leaves the waiting row's section rolls up nowhere (resolveLinkId accepts a unique name
419
+ * from another agents root), and a collapse in another section does not hide it (instanceVisibleInTree,
420
+ * given the same `section`). Filtering on → nothing is collapsed → empty. `stale(row)`: the caller's
421
+ * held-stale test; a stale row contributes nothing. */
422
+ export function waitingRollup(instances, collapsed, workspace, { filtering = false, stale = () => false, section = () => null } = {}) {
423
+ const out = new Map();
424
+ if (filtering || !collapsed?.size) return out;
425
+ const byId = new Map(instances.map(i => [instanceId(i), i]));
426
+ const byName = new Map();
427
+ for (const i of instances) { if (!byName.has(i.instance)) byName.set(i.instance, []); byName.get(i.instance).push(i); }
428
+ for (const i of instances) {
429
+ if (!waitingClaim(i, { stale: stale(i) }) || instanceVisibleInTree(i, instances, collapsed, workspace, false, { section })) continue;
430
+ const seen = new Set([instanceId(i)]);
431
+ let cursor = i, owner = null;
432
+ while (cursor?.parentInstance) {
433
+ const pid = resolveLinkId(cursor, cursor.parentInstance, byName);
434
+ if (!pid || seen.has(pid)) break;
435
+ seen.add(pid); cursor = byId.get(pid);
436
+ if (!cursor || section(cursor) !== section(i)) break;
437
+ if (instanceVisibleInTree(cursor, instances, collapsed, workspace, false, { section })) { owner = pid; break; }
438
+ }
439
+ if (owner === null) continue;
440
+ if (!out.has(owner)) out.set(owner, []);
441
+ out.get(owner).push(i);
442
+ }
443
+ return out;
444
+ }
445
+
446
+ /** Resolve the roster keyboard handler's ArrowLeft target: the parent
447
+ * instanceId of the row whose data-tree-instance is `id`, or null.
448
+ * Identity-aware end to end (review 96b037b): the current row is found by
449
+ * instanceId — rows carry composite ids, so a bare-name lookup never
450
+ * matches — and the parent edge resolves through resolveLinkId, so a
451
+ * duplicate parent name in another root (or intra-root) can never steal
452
+ * focus: ambiguity yields null and the key is a no-op. */
453
+ export function rosterParentId(instances, id) {
454
+ const me = instances.find((i) => instanceId(i) === id);
455
+ if (!me?.parentInstance) return null;
456
+ const byName = new Map();
457
+ for (const i of instances) {
458
+ if (!byName.has(i.instance)) byName.set(i.instance, []);
459
+ byName.get(i.instance).push(i);
460
+ }
461
+ return resolveLinkId(me, me.parentInstance, byName);
462
+ }
@@ -0,0 +1,11 @@
1
+ /** The variables an OATS instance session carries. A client started from inside one (a terminal in
2
+ * an agent's pane) inherits them, and a kernel command that runs with them answers for that instance
3
+ * instead of the directory it was asked about. The reads that name their own deployment remove them. */
4
+ export const INSTANCE_VARIABLES = Object.freeze(['PI_AGENTS_ROOT', 'PI_AGENT_HOME', 'PI_AGENT_INSTANCE', 'OATS_HOME', 'OATS_INSTANCE_HOME', 'OATS_INSTANCE', 'OATS_DEPLOYMENT', 'OATS_RESOLUTION']);
5
+
6
+ /** A copy of `env` without the instance variables. `env` is never changed. */
7
+ export function withoutInstanceVariables(env) {
8
+ const out = { ...env };
9
+ for (const name of INSTANCE_VARIABLES) delete out[name];
10
+ return out;
11
+ }
@@ -0,0 +1,31 @@
1
+ /** A kernel refusal's two texts as the lines a client shows, under the kernel's name in the words the
2
+ * shared home gives (instance-presentation.mjs `originLead`). Two clients quote a refusal the same way.
3
+ * Presentation only: a line is never evidence of identity nor authority for an action. A page loads this
4
+ * module, so it reaches no `node:` import. */
5
+ import { requireTerms } from './client-terms.mjs';
6
+ import { displayLine, DETAIL_WITHHELD } from "./display-text.mjs";
7
+ import { originLead } from "./instance-presentation.mjs";
8
+
9
+ /** The lines of a kernel refusal's two texts, its `message` and its `fix` (a launch problem of a soul, the
10
+ * spawn dialog's Details for an unmatched launch preference). Each text goes through the filter alone and
11
+ * is its own line, whole: nothing is joined, taken out or compared, so a remedy the kernel says in both is
12
+ * read in both. The kernel's name stands before the first of them that has a line to show, so no text of
13
+ * the kernel's stands without its speaker:
14
+ *
15
+ * message a line, fix a line ["OATS says: <message>", "<fix>"]
16
+ * message withheld, fix a line ["[Detail withheld]", "OATS says: <fix>"]
17
+ * message nothing, fix a line ["OATS says: <fix>"]
18
+ * message a line, fix withheld ["OATS says: <message>", "[Detail withheld]"]
19
+ * message a line, fix nothing ["OATS says: <message>"]
20
+ * neither has a line what is there ("[Detail withheld]" for a withheld text), no lead
21
+ *
22
+ * `terms` are the client's own (client-terms.mjs), required on every call under this function's name:
23
+ * also where no line is led, so a caller that leaves them out fails at once and not only on the day a
24
+ * text has something to show.
25
+ */
26
+ export function kernelLines(message, fix, terms) {
27
+ requireTerms(terms, "kernelLines");
28
+ const lines = [displayLine(message), displayLine(fix)].filter(line => line !== null);
29
+ const first = lines.findIndex(line => line !== DETAIL_WITHHELD);
30
+ return lines.map((line, index) => (index === first ? `${originLead('kernel', terms)} ${line}` : line));
31
+ }
@@ -0,0 +1,23 @@
1
+ /** The mark of an error object the installed CLI printed: who reads the kernel's answer says so on the
2
+ * object, where it parses it, and who shows the error's message asks. Not on the stable surface.
3
+ *
4
+ * kernelMade(error) -> the same object, marked the reader's, where an answer is parsed
5
+ * madeByKernel(error) -> boolean the shower's
6
+ *
7
+ * The mark is a property under a symbol this module does not export, and not enumerable. So it cannot
8
+ * arrive in an answer (JSON carries no symbol key), it is in nothing a client serves (`JSON.stringify`
9
+ * skips it), and a comparison of the object's fields does not see it. It is on the object, not in a list
10
+ * of objects: this home keeps no state.
11
+ *
12
+ * Unmarked reads as not the kernel's (the rule of deployment-read-cli.mjs `origin: 'kernel'`). A copy of
13
+ * the object (a spread, a JSON round trip, `structuredClone`) has no mark, so a lost mark never puts
14
+ * words under the kernel's name: the error then reads as the client's own. An error the client writes
15
+ * itself (a timeout, an answer that is not the contract's, a read that threw) needs nothing. */
16
+ const KERNEL = Symbol('the installed CLI printed this');
17
+
18
+ export function kernelMade(error) {
19
+ if (error !== null && typeof error === 'object' && Object.isExtensible(error)) Object.defineProperty(error, KERNEL, { value: true });
20
+ return error;
21
+ }
22
+
23
+ export const madeByKernel = (error) => error !== null && typeof error === 'object' && Object.hasOwn(error, KERNEL);
@@ -0,0 +1,51 @@
1
+ /** Soul launch preferences (feature `launch-preference`, OATS 0.30; docs/desktop-cli-api.md
2
+ * "Soul launch preferences"). The kernel's closed Launch object, decoded once for every reader:
3
+ * `oats souls` rows and `inspect --soul` (what a spawn with no flags would decide), `spawn --preview`
4
+ * (flags applied) and `inspect --home` (the record, plus `launchCurrent`). A kernel without the
5
+ * feature emits none of these fields, so every reader treats `launch` as optional. */
6
+ import { HARNESSES } from './harness-names.mjs';
7
+
8
+ const record = v => v !== null && typeof v === 'object' && !Array.isArray(v);
9
+ const exact = (v, keys) => record(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
10
+ const text = (v, max) => typeof v === 'string' && v.length > 0 && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
11
+ const model = v => v === null || text(v, 256);
12
+ const LAUNCH_CONFIG = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
13
+ const CODE = /^E_[A-Z0-9_]{1,62}$/;
14
+
15
+ /** Where the effective launch came from, per document: a report never says `flag`; only a home's
16
+ * record says `recorded` (a home from before 0.30). */
17
+ export const REPORT_FROM = Object.freeze(['local', 'local-default', 'soul', 'host']);
18
+ export const PREVIEW_FROM = Object.freeze(['flag', ...REPORT_FROM]);
19
+ export const RECORD_FROM = Object.freeze([...PREVIEW_FROM, 'recorded']);
20
+
21
+ /** LaunchPreference `{harness, model}` (model a string or null), or null (none declared). */
22
+ function preference(v) {
23
+ if (v === null) return null;
24
+ if (!exact(v, ['harness', 'model']) || !HARNESSES.includes(v.harness) || !model(v.model)) return undefined;
25
+ return { harness: v.harness, model: v.model };
26
+ }
27
+
28
+ /** An effective launch `{harness, model|null, launchConfig|null}` (also readiness `launch-changed`'s
29
+ * `recorded`/`current`), or `undefined` when malformed. */
30
+ export function effectiveOf(e) {
31
+ if (!exact(e, ['harness', 'model', 'launchConfig']) || !HARNESSES.includes(e.harness) || !model(e.model)
32
+ || !(e.launchConfig === null || (typeof e.launchConfig === 'string' && LAUNCH_CONFIG.test(e.launchConfig)))) return undefined;
33
+ return { harness: e.harness, model: e.model, launchConfig: e.launchConfig };
34
+ }
35
+
36
+ /** The Launch object, closed, or `undefined` when malformed (the reader then refuses its document). */
37
+ export function launchOf(v, from = REPORT_FROM) {
38
+ if (!exact(v, ['declared', 'effective', 'from', 'at', 'problem'])) return undefined;
39
+ const declared = preference(v.declared);
40
+ const e = v.effective;
41
+ if (declared === undefined || !exact(e, ['harness', 'model', 'launchConfig']) || !HARNESSES.includes(e.harness) || !model(e.model)
42
+ || !(e.launchConfig === null || (typeof e.launchConfig === 'string' && LAUNCH_CONFIG.test(e.launchConfig)))) return undefined;
43
+ if (!from.includes(v.from) || !(v.at === null || text(v.at, 1024))) return undefined;
44
+ let problem = null;
45
+ if (v.problem !== null) {
46
+ const p = v.problem;
47
+ if (!exact(p, ['code', 'message', 'fix']) || !CODE.test(p.code) || !text(p.message, 1024) || !text(p.fix, 1024)) return undefined;
48
+ problem = { code: p.code, message: p.message, fix: p.fix };
49
+ }
50
+ return { declared, effective: { harness: e.harness, model: e.model, launchConfig: e.launchConfig }, from: v.from, at: v.at, problem };
51
+ }