@awebai/oats 0.69.20 → 0.69.22

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 (53) hide show
  1. package/bin/oats.mjs +26 -3
  2. package/docs/capabilities.md +1 -1
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/container.md +311 -4
  5. package/docs/design/2026-11-18-kernel-test-ownership.md +82 -0
  6. package/docs/design/2026-11-19-aweb-suite-retirement.md +123 -0
  7. package/docs/desktop-cli-api.md +80 -0
  8. package/docs/desktop.md +404 -177
  9. package/docs/implementation.md +15 -2
  10. package/docs/integrations.md +2 -2
  11. package/docs/knowledge-capability-authoring.md +1 -1
  12. package/docs/official-catalog.md +44 -1
  13. package/docs/packages.md +2 -2
  14. package/docs/release-lane.md +8 -6
  15. package/docs/release-notes/v0.69.21.md +155 -0
  16. package/docs/release-notes/v0.69.22.md +221 -0
  17. package/docs/servers.md +5 -1
  18. package/docs/souls-and-instances.md +11 -0
  19. package/docs/tui.md +44 -4
  20. package/docs/upgrading.md +16 -5
  21. package/lib/capability-contract.mjs +2 -2
  22. package/lib/command-flags.mjs +1 -0
  23. package/lib/core.mjs +5 -3
  24. package/lib/instance-inspect.mjs +3 -0
  25. package/lib/instance-lifecycle.mjs +16 -0
  26. package/lib/instance-listing.mjs +8 -4
  27. package/lib/instance-pin.mjs +59 -0
  28. package/lib/kernel-features.mjs +1 -1
  29. package/lib/servers.mjs +8 -3
  30. package/package-catalog.json +1 -1
  31. package/package.json +1 -1
  32. package/packages/client/above-tested.mjs +3 -2
  33. package/packages/client/capability-list.mjs +69 -0
  34. package/packages/client/capability-origin.mjs +54 -0
  35. package/packages/client/cli-adapter.mjs +9 -1
  36. package/packages/client/deployment-data.mjs +3 -0
  37. package/packages/client/deployment-panel.mjs +2 -0
  38. package/packages/client/home-board.mjs +50 -0
  39. package/packages/client/instance-pin.mjs +28 -0
  40. package/packages/client/instance-record-outcome.mjs +31 -0
  41. package/packages/client/instance-tree.mjs +62 -20
  42. package/packages/client/keymap.mjs +11 -3
  43. package/packages/client/remote-roster.mjs +8 -1
  44. package/packages/client/roster-row-facts.mjs +50 -0
  45. package/packages/client/roster-sections.mjs +10 -7
  46. package/packages/client/soul-role.mjs +44 -0
  47. package/packages/client/waiting-on-you.mjs +10 -0
  48. package/packages/tui/lib/actions.mjs +11 -4
  49. package/packages/tui/lib/client.mjs +3 -1
  50. package/packages/tui/lib/main.mjs +16 -2
  51. package/packages/tui/lib/model.mjs +48 -5
  52. package/packages/tui/lib/store.mjs +28 -2
  53. package/skills/oats-getting-started/SKILL.md +283 -30
@@ -0,0 +1,50 @@
1
+ /** Home's board and its flat list of agents (Desktop UI rework, slice 2): the groupings both clients draw, so the
2
+ * TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows as
3
+ * the roster holds them; nothing here reorders the roster (needs-input-preserves-liveness-and-recognition: the
4
+ * urgency order lives on Home only).
5
+ *
6
+ * homeBoard(rows, { stale }) -> { needsYou: [{ row, claim }], running: [row] }
7
+ * needsYou: every row with a claim it may show (waiting-on-you.mjs `waitingClaim`, the one liveness gate,
8
+ * `stale(row)` the roster's held-stale rule), newest claim first (its `since`), then the roster's
9
+ * order. running: every other live row (`running === true`, no reported state but `running`, a
10
+ * reached server), newest spawn first (instance-tree.mjs `rosterOrder`). There is no working/idle
11
+ * fact yet (the activity contract is not built), and none is inferred
12
+ * (instance-activity-is-reported-not-inferred): a live row is "running". Stopped and unknown rows
13
+ * aren't on the board (D11). The "New" group (stopped or finished since you last looked) has no
14
+ * fact to read, so it isn't here.
15
+ * homeAgents(rows) -> rows: every agent, running or stopped, in the roster's order (newest spawn first).
16
+ * startedBy(row) -> string | null: who started it, the row's attributed human (attributed-human.mjs), else
17
+ * its parent's name (`parentInstance`), else null. */
18
+ import { waitingClaim } from './waiting-on-you.mjs';
19
+ import { rosterOrder } from './instance-tree.mjs';
20
+ import { attributedHumanData } from './attributed-human.mjs';
21
+ import { instanceDisplayName } from './instance-display-name.mjs';
22
+
23
+ const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
24
+ const rowsOf = (rows) => (Array.isArray(rows) ? rows.filter((row) => record(row) && typeof row.instance === 'string' && row.instance) : []);
25
+ const since = (claim) => { const t = Date.parse(claim.since); return Number.isFinite(t) ? t : -Infinity; };
26
+ const live = (row) => row.running === true && row.serverUnreached !== true && (row.runtimeState == null || row.runtimeState === 'running');
27
+
28
+ export function homeBoard(rows, { stale = () => false } = {}) {
29
+ const needsYou = [], running = [];
30
+ for (const row of rowsOf(rows)) {
31
+ const claim = waitingClaim(row, { stale: stale(row) === true });
32
+ if (claim) needsYou.push({ row, claim });
33
+ else if (live(row)) running.push(row);
34
+ }
35
+ needsYou.sort((a, b) => since(b.claim) - since(a.claim) || rosterOrder(a.row, b.row));
36
+ running.sort(rosterOrder);
37
+ return { needsYou, running };
38
+ }
39
+
40
+ export function homeAgents(rows) {
41
+ return rowsOf(rows).sort(rosterOrder);
42
+ }
43
+
44
+ export function startedBy(row) {
45
+ const human = attributedHumanData(row?.attributedHuman);
46
+ if (human) return human;
47
+ const parent = typeof row?.parentInstance === 'string' && row.parentInstance ? row.parentInstance : null;
48
+ if (!parent) return null;
49
+ return instanceDisplayName(parent) || parent;
50
+ }
@@ -0,0 +1,28 @@
1
+ /** Pinned instances (feature instance-pin; docs/desktop-cli-api.md "Pinned instances"): the one reading of the
2
+ * kernel's answer to `oats instance pin`, for both clients. The Desktop's backend route reads it through its record
3
+ * boundary (packages/desktop/server/instance-pin.mjs); the TUI's pin key runs the verb here (`pinInstance`).
4
+ *
5
+ * The kernel's answer is `{ instancePinApi: 1, instance, home, pinned, changed }`: one for another instance or
6
+ * another home, or of another shape, is an unknown outcome, never a success. */
7
+ import { cliInstancePin } from './cli-adapter.mjs';
8
+ import { recordOutcome } from './instance-record-outcome.mjs';
9
+
10
+ /** The kernel's success for exactly the asked instance and home, as `{ status: 'ok', instance, pinned, changed }`;
11
+ * else null. `asked`: `{ instance, home }`. */
12
+ export const pinAnswer = (r, asked) => r?.instancePinApi === 1 && r.instance === asked.instance && r.home === asked.home
13
+ && typeof r.pinned === 'boolean' && typeof r.changed === 'boolean'
14
+ ? { status: 'ok', instance: r.instance, pinned: r.pinned, changed: r.changed } : null;
15
+
16
+ /** What the command answered (instance-record-outcome.mjs): ok (pinAnswer), refused (an error the CLI printed) or
17
+ * unknown. */
18
+ export const pinOutcome = (envelope, asked) => recordOutcome(envelope, result => pinAnswer(result, asked));
19
+
20
+ /** Pin or unpin one instance and read the answer: `oats instance pin <instance> on|off --home <home> (--dir <context>
21
+ * | --server <server>) --json` (cli-adapter.mjs cliInstancePin, which refuses anything out of shape and runs
22
+ * nothing). `args`: `{ instance, home, pinned, context | server }`; `io` as cliInstancePin's (`exec`, `cwd`). A call
23
+ * that throws is an unknown outcome. */
24
+ export async function pinInstance(bin, args, io = {}) {
25
+ let envelope;
26
+ try { envelope = await cliInstancePin(bin, args, io); } catch { return { status: 'unknown', reason: { code: 'E_OUTCOME_UNKNOWN' } }; }
27
+ return pinOutcome(envelope, args);
28
+ }
@@ -0,0 +1,31 @@
1
+ /** What a kernel verb that writes one field of an instance's own record answered (`oats instance color`,
2
+ * `oats instance background`, `oats instance pin`), as a client reads it: the Desktop's backend boundary
3
+ * (packages/desktop/server/instance-record.mjs) and the TUI's pin key (instance-pin.mjs) read it here, once. Only
4
+ * an error the installed CLI printed is a refusal (kernel-made.mjs); one the adapter wrote (a timeout, no envelope,
5
+ * a nonzero exit) is an unknown outcome, as is a success the verb's `answer(result)` does not read as the
6
+ * contract's (it returns the ok answer, or null).
7
+ *
8
+ * Answers: `{ status: 'ok', … }` (the verb's own), `{ status: 'refused', reason: { code, message } }`, or
9
+ * `{ status: 'unknown', reason: { code } }` (the record may have changed: read the roster again). */
10
+ import { madeByKernel } from './kernel-made.mjs';
11
+
12
+ const CODE = /^E_[A-Z0-9_]{1,62}$/;
13
+ const record = v => v !== null && typeof v === 'object' && !Array.isArray(v);
14
+ const text = (v, max) => typeof v === 'string' && v.length > 0 && v.length <= max && !/[\x00-\x1f\x7f]/.test(v);
15
+
16
+ /** The codes this client's CLI runner gives a run that ended without an answer (own-codes.mjs): such a run's outcome
17
+ * is unknown, and its code says why. Any other code there reads as E_OUTCOME_UNKNOWN. */
18
+ const CLI_RUN_CODES = new Set(['E_CLI_FAILED', 'E_CLI_OUTPUT_LIMIT', 'E_CLI_PROTOCOL', 'E_CLI_TIMEOUT', 'E_CLI_UNAVAILABLE']);
19
+
20
+ export function recordOutcome(envelope, answer) {
21
+ if (envelope?.ok === true) {
22
+ let ok = null;
23
+ try { ok = record(envelope.result) ? answer(envelope.result) : null; } catch { ok = null; }
24
+ return ok ?? { status: 'unknown', reason: { code: 'E_OUTCOME_UNKNOWN' } };
25
+ }
26
+ const error = envelope?.ok === false ? envelope.error : null;
27
+ if (madeByKernel(error) && typeof error.code === 'string' && CODE.test(error.code)) {
28
+ return { status: 'refused', reason: { code: error.code, message: text(error.message, 512) ? error.message : '' } };
29
+ }
30
+ return { status: 'unknown', reason: { code: CLI_RUN_CODES.has(error?.code) ? error.code : 'E_OUTCOME_UNKNOWN' } };
31
+ }
@@ -79,14 +79,31 @@ function spawnTime(instance) {
79
79
  * and so clusters (by their first root: a bundle sits where its newest root sits, so a new child never moves it).
80
80
  * A spawn time never changes, so a start or a stop moves no row; only adding or removing one does (#1262's
81
81
  * recognition rule, whose name order this replaces; #1083's running-first order stays out of the roster). The one
82
- * place the roster's order is decided. */
83
- function rosterOrder(a, b) {
82
+ * place the roster's order is decided; a pin ranks before it at every level (`pinnedFirst`, `clusterInstances`,
83
+ * `instanceSiblings`), and pinning or unpinning is the one act besides adding or removing a row that moves one. */
84
+ export function rosterOrder(a, b) {
84
85
  const ta = spawnTime(a), tb = spawnTime(b);
85
86
  if (ta !== tb) return ta === null ? 1 : tb === null ? -1 : tb - ta;
86
87
  const ia = instanceId(a), ib = instanceId(b);
87
88
  return String(a.instance).localeCompare(String(b.instance)) || (ia < ib ? -1 : ia > ib ? 1 : 0);
88
89
  }
89
90
 
91
+ /** The kernel feature that reports a row's `pinned` (oats instance pin; docs/desktop-cli-api.md "Pinned instances"). */
92
+ export const PIN_FEATURE = "instance-pin";
93
+
94
+ /** Whether a row is pinned: its own `pinned` is exactly `true`, read only where this computer's CLI lists
95
+ * `PIN_FEATURE` (`pins`). A remote row carries `pinned` only when its host's own feature list names it too
96
+ * (remote-roster.mjs remotePanel drops it otherwise). Any other value, and every value without the feature, is no
97
+ * pin: a stray field from an older host is ignored, as `backgroundPlacement` reads `background`. */
98
+ export function rowPinned(instance, pins) {
99
+ return pins === true && instance?.pinned === true;
100
+ }
101
+
102
+ /** Pinned first (Pepe, 2026-11-19), a comparator for one level of the roster: a node that `lifted(node)` says holds
103
+ * a pin (itself, or a descendant in its tree) before one that does not; 0 between two of the same kind, for the
104
+ * roster's order (`rosterOrder`) to decide. So several pinned nodes keep that order among themselves. */
105
+ const pinnedFirst = (lifted) => (a, b) => (lifted(b) ? 1 : 0) - (lifted(a) ? 1 : 0);
106
+
90
107
  /** Each instance's siblings by EXPLICIT link (#1312): Y is X's sibling when X's sibling link
91
108
  * (`siblingLinksOf`) resolves to Y (`resolveLinkId` over `instances`), or Y's resolves to X. So both
92
109
  * ends of a link name each other. Direct links only (a chain C→B→A gives B [A, C], A [B], C [B]; A and
@@ -95,8 +112,9 @@ function rosterOrder(a, b) {
95
112
  * <parent>"), and `relation`/`relativeTo` are not read: they record how an instance was spawned, not a
96
113
  * current relation. Pass one deployment's FULL roster, never a filtered list: dropping rows can turn an
97
114
  * ambiguous name into a false unique one. Returns Map<instanceId, instance[]>; an instance with no
98
- * sibling is absent from the map. */
99
- export function instanceSiblings(instances) {
115
+ * sibling is absent from the map. `pins`: the CLI lists `PIN_FEATURE`; then a pinned sibling comes first, by its
116
+ * own `pinned` (`rowPinned`: siblings are no subtree). */
117
+ export function instanceSiblings(instances, { pins = false } = {}) {
100
118
  const byId = new Map(instances.map((i) => [instanceId(i), i]));
101
119
  const byName = new Map();
102
120
  for (const i of instances) {
@@ -117,7 +135,8 @@ export function instanceSiblings(instances) {
117
135
  add(other, id);
118
136
  }
119
137
  }
120
- return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(rosterOrder)]));
138
+ const order = (a, b) => pinnedFirst((i) => rowPinned(i, pins))(a, b) || rosterOrder(a, b);
139
+ return new Map([...ids].map(([id, set]) => [id, [...set].map((s) => byId.get(s)).sort(order)]));
121
140
  }
122
141
 
123
142
  /** Group instances into agent CLUSTERS — connected components of the
@@ -131,13 +150,19 @@ export function instanceSiblings(instances) {
131
150
  * host that declares instance-same-work, the flagged ones), each part in the roster's order (#1577). The product
132
151
  * owner's contract (awebai/oats#1577, comment 6441606665) refines the roster's order inside one parent's children only: roots, clusters and groups keep it.
133
152
  * Returns [{ key, instances: [{...instance, depth}] }] with clusters ranked by
134
- * their first ROOT in the roster's order (`rosterOrder`), never by another member (#1262): a bundle sits where
153
+ * their first ROOT in the roster's order (`rosterOrder`; pinned clusters first, `pins` below), never by another member (#1262): a bundle sits where
135
154
  * its root sits, and gaining or losing a child, or a start or a stop, moves nothing. A cluster without a root
136
155
  * (a malformed cycle) ranks by its first member in that order.
137
156
  * `roster` (optional): the full roster `instances` is a part of (#1579: one section of it). Names resolve over it,
138
157
  * so a part never turns an ambiguous name into a false unique one, and a link that resolves to a row outside the
139
- * part is no edge: such a row is a root of its part, as a row whose parent is gone. Without it, `instances`. */
140
- export function clusterInstances(instances, { links = instanceLinks, roster = instances } = {}) {
158
+ * part is no edge: such a row is a root of its part, as a row whose parent is gone. Without it, `instances`.
159
+ * `pins` (the CLI lists `PIN_FEATURE`; Pepe, 2026-11-19): pinned first at every level, ahead of the roster's order.
160
+ * A node ranks pinned when it or a descendant in its cluster's tree is pinned (`rowPinned`), so a pinned child
161
+ * lifts its group to the top and the path down to it rises among its siblings; a cluster ranks pinned when any
162
+ * member is pinned (its head's subtree, and the members a sibling link puts in the group). Under one parent,
163
+ * `drawingFirst` stays first (structural), then the pin, then the roster's order. Pinned nodes at one level keep
164
+ * the roster's order among themselves. Without it (an older CLI), `pinned` is ignored. */
165
+ export function clusterInstances(instances, { links = instanceLinks, roster = instances, pins = false } = {}) {
141
166
  const byId = new Map(instances.map((i) => [instanceId(i), i]));
142
167
  const byName = new Map();
143
168
  for (const i of roster) {
@@ -177,31 +202,46 @@ export function clusterInstances(instances, { links = instanceLinks, roster = in
177
202
  // parent-first tree order INSIDE the component (cycle-safe: the walk
178
203
  // visits each member once; leftovers append at depth 0)
179
204
  const memberIds = new Set(members.map(instanceId));
205
+ // The members whose subtree holds a pin: each pinned member and its ancestors in this cluster, walked up the
206
+ // resolved parent relation once (cycle-safe: a member already lifted ends the walk).
207
+ const lifted = new Set();
208
+ for (const i of members) {
209
+ if (!rowPinned(i, pins)) continue;
210
+ for (let id = instanceId(i); id && memberIds.has(id) && !lifted.has(id); id = parentIdOf.get(id)) lifted.add(id);
211
+ }
212
+ const first = pinnedFirst((i) => lifted.has(instanceId(i)));
213
+ const order = (a, b) => first(a, b) || rank(a, b);
180
214
  const kids = (p) => members.filter((i) => parentIdOf.get(instanceId(i)) === instanceId(p));
181
215
  const roots = members.filter((i) => {
182
216
  const pid = parentIdOf.get(instanceId(i));
183
217
  return !pid || !memberIds.has(pid);
184
218
  });
185
- roots.sort(rank);
219
+ // The cluster's rank among the others is its head's as it was without pins: its first root by the roster's
220
+ // order (with no root, its first member). A pin decides only whether the cluster leads (`pinned`); among
221
+ // clusters that do, and among those that don't, the existing rule stands (done-when 2), whichever root is pinned.
222
+ const head = [...(roots.length ? roots : members)].sort(rank)[0];
223
+ roots.sort(order);
186
224
  const ordered = [];
187
225
  const placed = new Set();
188
226
  const walk = (i, depth) => {
189
227
  if (placed.has(instanceId(i))) return;
190
228
  placed.add(instanceId(i));
191
229
  ordered.push({ ...i, depth });
192
- kids(i).sort((a, b) => drawingFirst(a, b) || rank(a, b)).forEach((k) => walk(k, depth + 1));
230
+ kids(i).sort((a, b) => drawingFirst(a, b) || order(a, b)).forEach((k) => walk(k, depth + 1));
193
231
  };
194
232
  roots.forEach((r) => walk(r, 0));
195
- for (const i of [...members].sort(rank)) walk(i, 0); // malformed cycles must not hide members
233
+ for (const i of [...members].sort(order)) walk(i, 0); // malformed cycles must not hide members
196
234
  // Deterministic cluster label: the lexically-smallest ROOT name —
197
235
  // independent of liveness, so the visible cluster name does not flip
198
236
  // when a different member starts/stops running (review f921f7d nit).
199
- // `rank` (rosterOrder: by spawn time, newest first) governs display ORDER within the cluster.
237
+ // `order` (pinned first, then rosterOrder: by spawn time, newest first) governs display ORDER within the cluster.
200
238
  const rootNames = (roots.length ? roots : members).map((i) => i.instance).sort();
201
- clusters.push({ key: rootNames[0], instances: ordered, head: roots[0] ?? [...members].sort(rank)[0] });
239
+ clusters.push({ key: rootNames[0], instances: ordered, head, pinned: lifted.size > 0 });
202
240
  }
203
- // Stable: clusters whose heads rank equal keep the order they were found in (the roster's order of members).
204
- return clusters.sort((a, b) => rank(a.head, b.head)).map(({ head: _head, ...c }) => c);
241
+ // Pinned clusters first, then by head (its rank without pins). Stable: clusters whose heads rank equal keep the
242
+ // order they were found in.
243
+ const clusterFirst = pinnedFirst((c) => c.pinned);
244
+ return clusters.sort((a, b) => clusterFirst(a, b) || rank(a.head, b.head)).map(({ head: _head, pinned: _pinned, ...c }) => c);
205
245
  }
206
246
 
207
247
  /** `clusterInstances` output ordered by last focus (#1383; the command palette's order, never the sidebar's).
@@ -500,9 +540,9 @@ export function filterInstanceTree(instances, query, matches = null) {
500
540
  * re-linking nodes while the user types (merged-state review @3e76616).
501
541
  * Cluster order and member depths come from the full-roster computation;
502
542
  * clusters with no visible member disappear. */
503
- export function visibleClusters(allInstances, visibleInstances, { links = instanceLinks } = {}) {
543
+ export function visibleClusters(allInstances, visibleInstances, { links = instanceLinks, pins = false } = {}) {
504
544
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
505
- return clusterInstances(allInstances, { links })
545
+ return clusterInstances(allInstances, { links, pins })
506
546
  .map((c) => ({ ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) }))
507
547
  .filter((c) => c.instances.length);
508
548
  }
@@ -521,12 +561,14 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
521
561
  * ordered by last focus (`recencyOrder`) before the groups form by the same rule, so a run is the consecutive
522
562
  * single clusters of that order, keyed by its first member there. What is visible still decides only which rows
523
563
  * are listed, never the order. Without it, the roster's own order (the sidebar's and the TUI's).
524
- * `roster` (optional): the full roster `allInstances` is a part of, as for `clusterInstances`. */
525
- export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus, roster = allInstances } = {}) {
564
+ * `roster` (optional): the full roster `allInstances` is a part of, as for `clusterInstances`.
565
+ * `pins` (optional): the CLI lists `PIN_FEATURE`, as for `clusterInstances`. Pinned single clusters rank first, so
566
+ * they form the leading run, keyed by its first member as any run is. */
567
+ export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks, lastFocus, roster = allInstances, pins = false } = {}) {
526
568
  const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
527
569
  const groups = [];
528
570
  let place = 0, run = null;
529
- const clusters = clusterInstances(allInstances, { links, roster });
571
+ const clusters = clusterInstances(allInstances, { links, roster, pins });
530
572
  for (const c of lastFocus instanceof Map ? recencyOrder(clusters, lastFocus) : clusters) {
531
573
  const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
532
574
  if (c.instances.length > 1) {
@@ -29,7 +29,10 @@
29
29
  /** The leader per platform: Ctrl+X on both, as Emacs has it (#1433). Without the kitty keyboard
30
30
  * protocol it is one byte, 0x18, in every terminal; pressed twice it sends that byte to the program
31
31
  * (the shell's Ctrl+X Ctrl+E, nano's exit). The Desktop leaves it to Cut in an editable field on
32
- * Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader"). */
32
+ * Linux and Windows (packages/desktop/docs/desktop-keyboard.md, "The leader").
33
+ * D18 (decided 2026-11-19, Joan): the Desktop's default leader is Ctrl+Space, with Ctrl+X a choice; the TUI keeps
34
+ * Ctrl+X here until it reads Ctrl+Space, which a terminal sends as NUL (0x00), a byte its key decoder reads as no
35
+ * key today (packages/tui/lib/term/keys.mjs c0Key). This shared default moves to `ctrl+space` with that change. */
33
36
  export const LEADER = Object.freeze({ mac: "ctrl+x", other: "ctrl+x" });
34
37
 
35
38
  /** The keys read after the leader, in the TUI's order, and what each does. `terminal`: named in
@@ -47,11 +50,16 @@ export const LEADER_TABLE = Object.freeze([
47
50
  { keys: ["up"], does: "workspace-previous", label: "previous workspace" },
48
51
  { keys: ["down"], does: "workspace-next", label: "next workspace" },
49
52
  { keys: ["z"], does: "zoom", label: "zoom", terminal: true },
53
+ // `b`, Herdr's (the Desktop UI rework, decided 2026-11-19): the sidebar hidden or shown in the Desktop; in the TUI,
54
+ // whose list is its sidebar, the shown terminal takes the whole screen or gives the list back.
55
+ { keys: ["b"], does: "sidebar", label: "hide or show the list" },
50
56
  { keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
51
57
  { keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
52
58
  { keys: ["right"], does: "tab-next", label: "next tab", terminal: true },
53
- { keys: ["|"], does: "split-right", label: "split right", terminal: true },
54
- { keys: ["-"], does: "split-down", label: "split down", terminal: true },
59
+ // `h` and `v` beside `|` and `-` (the Desktop UI rework, decided 2026-11-19): Herdr's letters, h a pane to the
60
+ // right and v one below, as its split_horizontal and split_vertical are.
61
+ { keys: ["|", "h"], does: "split-right", label: "split right", terminal: true },
62
+ { keys: ["-", "v"], does: "split-down", label: "split down", terminal: true },
55
63
  { keys: ["tab"], does: "group-next", label: "next group", terminal: true },
56
64
  { keys: ["shift+tab"], does: "group-previous", label: "previous group", terminal: true },
57
65
  { keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
@@ -6,6 +6,8 @@ import { attributedHumanData } from "./attributed-human.mjs";
6
6
  import { retireData } from "./retire-state.mjs";
7
7
  import { readIdentity } from "./workspace-views.mjs";
8
8
  import { sameRepo } from "./repo-moves.mjs";
9
+ import { hostAdvertises } from "./composed-gate.mjs";
10
+ import { PIN_FEATURE } from "./instance-tree.mjs";
9
11
  /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
10
12
  export function remoteWorkspace(group) {
11
13
  return {
@@ -47,7 +49,7 @@ export function remotePanel(group, at) {
47
49
  const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
48
50
  // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
49
51
  const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, retire: sentRetire, sameWork: sentSameWork,
50
- sameWorkKnown: _gate, ...i }) => {
52
+ sameWorkKnown: _gate, pinned: sentPinned, ...i }) => {
51
53
  const unsupported = unsupportedSession(i);
52
54
  const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
53
55
  const row = {
@@ -70,6 +72,11 @@ export function remotePanel(group, at) {
70
72
  // #1577: the host's same-work flag, true only (anything else reads unflagged). `sameWorkKnown` is this
71
73
  // client's own field (same-work.mjs), never a host's: whatever a host sent under it is dropped.
72
74
  ...(sentSameWork === true ? { sameWork: true } : {}),
75
+ // Feature instance-pin: the host's pin, true only (anything else reads unpinned; instance-tree.mjs rowPinned),
76
+ // and only from a host whose own feature list names it (composed-gate.mjs hostAdvertises: the group's
77
+ // probe.features, which a CLI with server-probe-features relays). The kernel relays a row's pinned whatever
78
+ // its host lists, so a stray field from an older host, or an unknown list, never pins a row here.
79
+ ...(sentPinned === true && hostAdvertises(group, PIN_FEATURE) ? { pinned: true } : {}),
73
80
  ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
74
81
  };
75
82
  return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
@@ -0,0 +1,50 @@
1
+ /** The two text facts of an instance row in a sidebar roster (the Desktop UI rework, slice 1), shared so the
2
+ * Terminal UI can draw the same row: line 1 the display name, line 2 `<soul> · <machine>`.
3
+ *
4
+ * rosterRowFacts(row, terms, { deployments, here }) -> { name, detail, soul, machine }
5
+ *
6
+ * name the instance name as words (instance-display-name.mjs), else the name as reported, else ''
7
+ * soul the row's soul (`agent`), one display line, else null (a forgotten or malformed row)
8
+ * machine where the row runs: the machine of the deployment the row is tagged with (`deployment.id` among
9
+ * `deployments`, a view's), else a remote server row's label (remote-address.mjs `serverLabel`), else
10
+ * this machine: its own name when the caller knows it (`here`, the host name the kernel reports for this
11
+ * machine), else `terms.thisMachine` (client-terms.mjs). A row of this machine's own deployment is this
12
+ * machine's too, whatever label the deployment carries. A view's row may carry `server` and a repository
13
+ * in `repoName`, so its deployment's machine comes first. Always a label: a row that names no machine is
14
+ * this machine's
15
+ * detail `soul · machine`, or the machine alone when no soul is known
16
+ *
17
+ * The facts only: no state, no reason, no repository, no harness. A row whose machine didn't answer keeps both
18
+ * lines; its state is the dot's and its reason the row's description. Display only, never an identity: the real
19
+ * name stays wherever it identifies the instance. Pure: no DOM, no IO. */
20
+ import { instanceDisplayName } from './instance-display-name.mjs';
21
+ import { serverLabel } from './remote-address.mjs';
22
+ import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
23
+ import { requireTerms } from './client-terms.mjs';
24
+
25
+ /** One display line, or null for nothing to show (absent, not text, withheld). */
26
+ const shown = (value) => {
27
+ const line = typeof value === 'string' ? displayLine(value) : null;
28
+ return line && line !== DETAIL_WITHHELD ? line : null;
29
+ };
30
+
31
+ /** The machine label of `row`, in `terms` (see the module's comment). */
32
+ export function rowMachine(row, terms, { deployments = [], here = null } = {}) {
33
+ requireTerms(terms, 'rowMachine');
34
+ const id = typeof row?.deployment?.id === 'string' ? row.deployment.id : null;
35
+ const deployment = id && Array.isArray(deployments) ? deployments.find((d) => d?.id === id) : null;
36
+ const server = typeof row?.server === 'string' && row.server ? shown(serverLabel(row)) ?? shown(row.server) : null;
37
+ const thisMachine = shown(here) ?? terms.thisMachine;
38
+ if (deployment?.local === true) return thisMachine;
39
+ return shown(deployment?.machine) ?? server ?? thisMachine;
40
+ }
41
+
42
+ /** The row's two lines and their parts. */
43
+ export function rosterRowFacts(row, terms, { deployments = [], here = null } = {}) {
44
+ requireTerms(terms, 'rosterRowFacts');
45
+ const instance = typeof row?.instance === 'string' ? row.instance : '';
46
+ const name = instanceDisplayName(instance) || instance;
47
+ const soul = shown(row?.agent);
48
+ const machine = rowMachine(row, terms, { deployments, here });
49
+ return { name, detail: [soul, machine].filter(Boolean).join(' · '), soul, machine };
50
+ }
@@ -58,11 +58,13 @@ export const rowStale = (row, deployments) => {
58
58
  * most recent first, then the panel's order. Without it, the panel's order (the sidebar's and the TUI's).
59
59
  * `roster` (optional; #1579): the full roster `instances` is a part of (the main tree's rows or the Background
60
60
  * section's, `sidebarSections`). Names resolve over its rows of the same deployment, and a relation to a row outside
61
- * `instances` is none: that row's relatives are roots here. Without it, `instances`. */
62
- export function rosterSections(instances, visible, deployments, terms, { lastFocus, roster = instances } = {}) {
61
+ * `instances` is none: that row's relatives are roots here. Without it, `instances`.
62
+ * `pins` (optional): this computer's CLI lists instance-tree.mjs `PIN_FEATURE`: pinned rows lead each section's
63
+ * order (`clusterInstances`). The section split comes first, so a pin ranks only within its own section. */
64
+ export function rosterSections(instances, visible, deployments, terms, { lastFocus, roster = instances, pins = false } = {}) {
63
65
  requireTerms(terms, 'rosterSections');
64
66
  const recency = lastFocus instanceof Map ? { lastFocus } : {};
65
- const groupsOf = (all, shown, whole) => rosterGroups(all, shown, { ...recency, roster: whole }); // the relation groups the palette lists too
67
+ const groupsOf = (all, shown, whole) => rosterGroups(all, shown, { ...recency, roster: whole, pins }); // the relation groups the palette lists too
66
68
  if (!isMultiDeployment(deployments)) return [{ deployment: null, label: null, groups: groupsOf(instances, visible, roster) }];
67
69
  const sectionOf = splitByDeployment(deployments);
68
70
  const all = sectionOf(instances), shown = sectionOf(visible), whole = sectionOf(roster), labels = machineLabelParts(deployments, terms);
@@ -110,17 +112,18 @@ export function rosterSectionKey(deployments, placement = new Set()) {
110
112
  * one included), and `sections` its own tree, `rosterSections` over its rows (with the machine sub-headings in a
111
113
  * view of two or more deployments), empty while closed. Each part is a tree of its own: a relation to a row of the
112
114
  * other part is none (a background row whose parent is in the main tree is a root of the Background section), and
113
- * names still resolve over the full roster. The palette never asks this: it lists every row. */
114
- export function sidebarSections(instances, visible, deployments, terms, { placement = new Set(), open = false, listed = instances, stale = () => false } = {}) {
115
+ * names still resolve over the full roster. The palette never asks this: it lists every row.
116
+ * `pins`: as for `rosterSections`; a pinned row in the Background section leads that section's own tree. */
117
+ export function sidebarSections(instances, visible, deployments, terms, { placement = new Set(), open = false, listed = instances, stale = () => false, pins = false } = {}) {
115
118
  requireTerms(terms, 'sidebarSections');
116
119
  const inside = row => placement.has(instanceId(row));
117
- const main = rosterSections(instances.filter(r => !inside(r)), visible.filter(r => !inside(r)), deployments, terms, { roster: instances });
120
+ const main = rosterSections(instances.filter(r => !inside(r)), visible.filter(r => !inside(r)), deployments, terms, { roster: instances, pins });
118
121
  const rows = instances.filter(inside), count = listed.filter(inside).length;
119
122
  if (!count) return { main, background: null };
120
123
  return { main, background: {
121
124
  count, open: !!open,
122
125
  waiting: rows.some(row => waitingClaim(row, { stale: stale(row) }) !== null),
123
- sections: open ? rosterSections(rows, visible.filter(inside), deployments, terms, { roster: instances }) : [],
126
+ sections: open ? rosterSections(rows, visible.filter(inside), deployments, terms, { roster: instances, pins }) : [],
124
127
  } };
125
128
  }
126
129
 
@@ -0,0 +1,44 @@
1
+ /** A soul's role, and the order souls are listed in, for every client (the Desktop's Souls grid and table, and
2
+ * the Terminal UI later): maintainers, experts, developers, operations, then the rest, each alphabetical. (Not the
3
+ * row's `soulKind`, which is where the soul comes from: member, package or external.)
4
+ *
5
+ * The kernel reports no role for a soul (oats-project/oats#1980 asks for one), so the role is read from the soul's
6
+ * name, one rule:
7
+ * 1. operations: any word of the name is setup, operator, operators, admin, ops or operations
8
+ * (`acme-oats-setup-expert`, `ops-admin`): a setup soul is operations even when it ends in -expert;
9
+ * 2. else the last word: maintainer → maintainer, expert → expert, developer → developer;
10
+ * 3. else other.
11
+ * A word is a run of the name between `-`, `_`, `.` and `/`, case aside, so a package soul's qualified name
12
+ * (`oats.engineering/code-reviewer`) reads the same as its bare one. The description is not read: a sentence
13
+ * that says a soul "operates" something would misfile it, and the name is what the soul's author chose.
14
+ *
15
+ * A kernel `role` fact on the soul row would replace this rule (#1980): then `soulRole` reads it, and every client
16
+ * keeps calling the same two functions.
17
+ *
18
+ * soulRole(row) -> 'maintainer' | 'expert' | 'developer' | 'operations' | 'other'
19
+ * SOUL_ROLES the roles, in list order
20
+ * SOUL_ROLE_WORDS a role in words, singular ("developer"); the Desktop's Souls call it the soul's kind
21
+ * compareSoulsByRole(a, b) list order: role, then name; for Array.prototype.sort
22
+ *
23
+ * No state, no DOM. */
24
+
25
+ export const SOUL_ROLES = Object.freeze(['maintainer', 'expert', 'developer', 'operations', 'other']);
26
+ export const SOUL_ROLE_WORDS = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer', operations: 'operations', other: 'other' });
27
+ const OPERATIONS = new Set(['setup', 'operator', 'operators', 'admin', 'ops', 'operations']);
28
+ const LAST = Object.freeze({ maintainer: 'maintainer', expert: 'expert', developer: 'developer' });
29
+
30
+ const nameOf = row => typeof row === 'string' ? row : typeof row?.name === 'string' ? row.name : '';
31
+ const words = name => name.toLowerCase().split(/[-_./]+/).filter(Boolean);
32
+
33
+ /** The soul's role, from its name (a row with a `name`, or the name itself). */
34
+ export function soulRole(row) {
35
+ const parts = words(nameOf(row));
36
+ if (parts.some(part => OPERATIONS.has(part))) return 'operations';
37
+ const last = parts.at(-1);
38
+ return last !== undefined && Object.hasOwn(LAST, last) ? LAST[last] : 'other';
39
+ }
40
+
41
+ /** List order inside a group: the role's place in SOUL_ROLES, then the name. */
42
+ export function compareSoulsByRole(a, b) {
43
+ return SOUL_ROLES.indexOf(soulRole(a)) - SOUL_ROLES.indexOf(soulRole(b)) || nameOf(a).localeCompare(nameOf(b));
44
+ }
@@ -43,6 +43,16 @@ export function waitingClaim(row, { stale = false } = {}) {
43
43
  return waitingOnYouData(row.waitingOnYou);
44
44
  }
45
45
 
46
+ /** The rows that need you, newest claim first (the Desktop's palette and Home, the TUI's list later: one order for
47
+ * both clients, the Desktop UI rework, slice 4): each row's claim through the one gate (waitingClaim; `stale(row)`
48
+ * says a row is held stale), as `{ row, claim }`. Equal times keep the rows' own order. */
49
+ export function needsYouRows(rows, { stale = () => false } = {}) {
50
+ return (Array.isArray(rows) ? rows : []).map((row, at) => ({ row, at, claim: waitingClaim(row, { stale: stale(row) }) }))
51
+ .filter(({ claim }) => claim)
52
+ .sort((a, b) => Date.parse(b.claim.since) - Date.parse(a.claim.since) || a.at - b.at)
53
+ .map(({ row, claim }) => ({ row, claim }));
54
+ }
55
+
46
56
  const LABELS = Object.freeze({ permission: 'Waiting for a tool approval', question: 'Asked you a question', attention: 'Asked for your attention' });
47
57
  /** The reason in words. The raw reason is never rendered: an unknown one reads "Needs input". */
48
58
  export const waitingLabel = claim => Object.hasOwn(LABELS, claim?.reason ?? '') ? LABELS[claim.reason] : 'Needs input';
@@ -8,7 +8,7 @@
8
8
  // The keys the TUI shares with the Desktop are not written here: an action with no `keys` of its own
9
9
  // takes its default keys from the shared keymap (packages/client/keymap.mjs PLAIN_KEYS), and the
10
10
  // leader's table is the shared one (LEADER, below). What only the TUI has (q, Ctrl+C, Ctrl+Z, Ctrl+L,
11
- // Ctrl+K, Tab, Esc, Delete, C, i) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
11
+ // Ctrl+K, Tab, Esc, Delete, C, i, p) keeps its keys here. packages/tui/test/keymap.test.mjs pins both.
12
12
  import { CHORDS, DEFAULT_CHORD_FAMILY, LEADER_TABLE, PALETTE_KEYS, chordKeyOf, plainKeys } from "./client.mjs";
13
13
  // An action's words, for the help (views/help.mjs): a view takes the shared home's keymap through this module only.
14
14
  export { doesLabel } from "./client.mjs";
@@ -75,6 +75,12 @@ export const ACTIONS = Object.freeze([
75
75
  { id: "spawn-another", label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
76
76
  // Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
77
77
  { id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
78
+ // Pinned instances (feature instance-pin; docs/tui.md, "Pinning"): at once, no confirmation (a pin only orders the
79
+ // list, and the same key undoes it). `p` is a new default key: a tui.json that gives it to another action is
80
+ // refused at the start with the line that says so (config.mjs), until that action moves or pin gets another key.
81
+ // Lower-case, unlike the four acts above: it opens no confirmation and changes nothing but the order. Its help
82
+ // line fits one row of the help: the shared pin and the feature's line are in docs/tui.md and on the status line.
83
+ { id: "pin", keys: ["p"], label: "pin", views: [["instances", "pin the selected agent at the top of its list or unpin it, as oats instance pin <name> on|off; needs instance-pin"]] },
78
84
  { id: "help", label: "help" },
79
85
  { id: "close", keys: ["escape"], label: "close" },
80
86
  { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
@@ -93,9 +99,10 @@ export const ACTIONS = Object.freeze([
93
99
  * and from any other focus it only cancels the leader (lib/store.mjs `twice`). */
94
100
  export const LEADER = LEADER_TABLE;
95
101
  /** What the leader does that no action of ACTIONS does (lib/store.mjs `led`): `workspace-previous`
96
- * and `workspace-next` (the workspace before or after the open one in the list of workspaces) and
97
- * `list` (the list's focus, which Esc gives). */
98
- export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list"]);
102
+ * and `workspace-next` (the workspace before or after the open one in the list of workspaces),
103
+ * `list` (the list's focus, which Esc gives), and `sidebar` (the shared table's `b`, the Desktop's
104
+ * sidebar: here the list, hidden by the shown terminal taking the whole screen, or given back). */
105
+ export const LEADER_OWN = Object.freeze(["workspace-previous", "workspace-next", "list", "sidebar"]);
99
106
  /** What a chord does that neither the leader's table nor an action does (lib/store.mjs `led`):
100
107
  * `tab-1` to `tab-8`, the focused group's Nth tab shown, and `tab-9`, its last (as the Desktop and
101
108
  * the browsers do). No key after the leader does them: LEADER has no row for them. */
@@ -12,6 +12,8 @@ export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
12
12
  export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
13
13
  export { deploymentsListSupported } from "../../client/deployment-list.mjs";
14
14
  export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
15
+ // Pinned instances (feature instance-pin): the pin key runs the kernel's verb, read by the shared home.
16
+ export { pinInstance } from "../../client/instance-pin.mjs";
15
17
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
16
18
  export { createWarmReader } from "../../client/warm-reader.mjs";
17
19
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
@@ -23,7 +25,7 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
23
25
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
24
26
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
25
27
  export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
26
- export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE } from "../../client/instance-tree.mjs";
28
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE, PIN_FEATURE } from "../../client/instance-tree.mjs";
27
29
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, rosterSectionKey, sidebarSections } from "../../client/roster-sections.mjs";
28
30
  export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
29
31
  export { instanceDisplayName } from "../../client/instance-display-name.mjs";
@@ -12,7 +12,7 @@
12
12
  import { homedir } from "node:os";
13
13
  import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
- import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
15
+ import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance, pinInstance } from "./client.mjs";
16
16
  import { loadConfig, loadKeys } from "./config.mjs";
17
17
  import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, resumeObservation, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
@@ -100,7 +100,7 @@ function errorLines(error) {
100
100
  * chord family (lib/config.mjs), replaceable so no test reads a user's file. `createResumeTrigger`
101
101
  * is the shared trigger of the kernel's machine sweep (packages/client session-resume-trigger.mjs). */
102
102
  const EFFECTS = Object.freeze({ loadConfig, loadKeys, findDeployment, probeKernel, createReader, createIdentityReads, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
103
- runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
103
+ runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, pinInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
104
104
  createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction, createResumeTrigger });
105
105
 
106
106
  /** The timers a run lends the shared spawn: the apply's deadline and its grace (the boundary's
@@ -487,6 +487,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
487
487
  if (effect.act) openConfirmation(effect.act);
488
488
  if (effect.call) callConfirmation(effect.call);
489
489
  if (effect.start) startAct(effect.start);
490
+ if (effect.pin) pinAct(effect.pin);
490
491
  if (effect.refresh) refresh(effect.refresh);
491
492
  if (effect.souls === "settle" && state.open !== null) settleSouls(state.open);
492
493
  if (effect.souls === "reread" && state.open !== null) rereadSouls(state.open);
@@ -601,6 +602,19 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
601
602
  .then(() => effects.startInstance(probe.cli, row, {}, { restart: verb === "restart", deployments: localDeployments(state, clock()), realpath: effects.realpath, localCwd: actCwd(state), exec, terms: TERMS, group: contextOf(row?.deployment?.id).workspace?.group }))
602
603
  .then((answer) => heard({ acted: { n, answer } }), () => heard({ acted: { n, answer: null } }));
603
604
  }
605
+ /** Pin or unpin the row the store decided on (feature instance-pin; lib/model.mjs pinDecision): the kernel's verb,
606
+ * through the shared pinInstance, on this machine with `--dir` its deployment, on another routed with `--server`,
607
+ * as a stop is. It is a change (reader.changeExec): never ended by the TUI, and named on the way out while it
608
+ * runs. Its answer goes to the store as `{ pinned }`, which reads the rows again. */
609
+ function pinAct({ id, row, pinned }) {
610
+ const name = row.instance, workspace = contextOf(row.deployment?.id).workspace;
611
+ const remote = !!(workspace?.remote || workspace?.server);
612
+ const args = { instance: name, home: row.home, pinned, ...(remote ? { server: workspace?.server } : { context: workspace?.scope }) };
613
+ const exec = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: { verb: "pin", name } }, callback);
614
+ Promise.resolve()
615
+ .then(() => effects.pinInstance(probe.cli.bin, args, { exec, ...(remote ? { cwd: actCwd(state) } : {}) }))
616
+ .then((answer) => heard({ pinned: { id, name, pinned, answer } }), () => heard({ pinned: { id, name, pinned, answer: null } }));
617
+ }
604
618
 
605
619
  /** Open the agent the store decided on (lib/model.mjs openDecision). On this machine the viewer
606
620
  * starts in the panel at once. On another, the shared preflight runs first over the reader's