@awebai/oats 0.66.0 → 0.67.1

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 (65) hide show
  1. package/bin/oats.mjs +66 -13
  2. package/docs/capabilities.md +4 -4
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/desktop-cli-api.md +217 -6
  5. package/docs/desktop.md +101 -22
  6. package/docs/implementation.md +6 -5
  7. package/docs/official-catalog.md +1 -1
  8. package/docs/packages.md +5 -5
  9. package/docs/release-lane.md +16 -0
  10. package/docs/release-notes/v0.67.0.md +366 -0
  11. package/docs/release-notes/v0.67.1.md +64 -0
  12. package/docs/servers.md +3 -2
  13. package/docs/souls-and-instances.md +20 -3
  14. package/docs/tui.md +570 -176
  15. package/docs/upgrading.md +107 -25
  16. package/docs/workspaces.md +1 -1
  17. package/lib/capability-contract.mjs +2 -2
  18. package/lib/core.mjs +126 -54
  19. package/lib/instance-color.mjs +58 -0
  20. package/lib/instance-inspect.mjs +107 -23
  21. package/lib/instance-lifecycle.mjs +21 -1
  22. package/lib/instance-naming.mjs +187 -0
  23. package/lib/instance-resolution.mjs +5 -1
  24. package/lib/materialize.mjs +62 -11
  25. package/lib/servers.mjs +15 -6
  26. package/lib/soul-composition.mjs +7 -3
  27. package/package-catalog.json +1 -1
  28. package/package.json +1 -1
  29. package/packages/client/cli-adapter.mjs +37 -5
  30. package/packages/client/cli-locator.mjs +2 -2
  31. package/packages/client/composed-gate.mjs +10 -2
  32. package/packages/client/deployment-data.mjs +5 -0
  33. package/packages/client/deployment-identity.mjs +40 -0
  34. package/packages/client/deployment-panel.mjs +3 -1
  35. package/packages/client/inspect-boundary.mjs +11 -7
  36. package/packages/client/inspect-cache.mjs +2 -2
  37. package/packages/client/instance-name.mjs +28 -0
  38. package/packages/client/instance-presentation.mjs +11 -0
  39. package/packages/client/keymap.mjs +85 -24
  40. package/packages/client/keys-file.mjs +122 -0
  41. package/packages/client/own-codes.mjs +4 -2
  42. package/packages/client/panel-views.mjs +62 -9
  43. package/packages/client/spawn-naming.mjs +31 -0
  44. package/packages/client/spawn-preview-cli.mjs +22 -7
  45. package/packages/client/spawn-preview-contract.mjs +24 -0
  46. package/packages/client/spawn-preview-facts.mjs +8 -4
  47. package/packages/client/spawn-preview.mjs +47 -2
  48. package/packages/tui/README.md +3 -3
  49. package/packages/tui/lib/actions.mjs +57 -14
  50. package/packages/tui/lib/client.mjs +8 -4
  51. package/packages/tui/lib/config.mjs +50 -9
  52. package/packages/tui/lib/main.mjs +40 -13
  53. package/packages/tui/lib/model.mjs +167 -63
  54. package/packages/tui/lib/read.mjs +53 -1
  55. package/packages/tui/lib/store.mjs +148 -54
  56. package/packages/tui/lib/term/keys.mjs +19 -5
  57. package/packages/tui/lib/term/kitty.mjs +36 -11
  58. package/packages/tui/lib/term/through.mjs +61 -28
  59. package/packages/tui/lib/views/frame.mjs +158 -79
  60. package/packages/tui/lib/views/help.mjs +109 -26
  61. package/packages/tui/lib/views/instances.mjs +59 -20
  62. package/packages/tui/lib/views/palette.mjs +14 -4
  63. package/packages/tui/lib/views/souls.mjs +2 -2
  64. package/packages/tui/lib/views/switcher.mjs +6 -1
  65. package/skills/oats-getting-started/SKILL.md +13 -8
@@ -7,16 +7,16 @@
7
7
  // in. What it adds is the TUI's: the window, the clock times, and which fact stands on which line.
8
8
  import {
9
9
  TERMS, panelData, displayLine, DETAIL_WITHHELD, originLead, instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree,
10
- hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts,
10
+ hasInstanceChildren, heldHome, instanceSiblings, siblingText, rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, runtimeState, runtimeCounts, instanceColor,
11
11
  waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText, instanceActs, rowReason,
12
- identityMemory, viewModel, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath,
12
+ identityMemory, viewModel, listedViews, workspaceChoices, workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION, shortPath, machineLabels,
13
13
  openAct, deployments as heldDeployments, attachExit, preflightFailure, kernelLines,
14
14
  startGate, launchFlagIgnored, flagIgnoredNotice, retainedStartMessage, retiringRows, soulRows, soulFacts, spawnRefusal,
15
15
  defaultSpawnChoices, spawnProblem, outcomeWords, previewFacts, deploymentLabel, subsequenceScore, soulMatches, soulCatalogFailure, catalogFailure,
16
16
  memberNames, capabilitySource, groupCapabilities, hostKeyOf, capabilitySections, matchCapabilities, soulsComposition, rosterAgentName, layerLabel, capabilityUsers,
17
- capabilityFacts, CAPABILITY_COPY,
17
+ capabilityFacts, CAPABILITY_COPY, CHORD_FAMILY_LABELS, DEFAULT_CHORD_FAMILY, chordFamilyNote,
18
18
  } from "./client.mjs";
19
- import { LEADER, keyLabel } from "./actions.mjs";
19
+ import { LEADER, chordsRead, keyLabel } from "./actions.mjs";
20
20
  import { ownEllipsis, shownLines } from "./term/text.mjs";
21
21
  import { textWidth } from "./term/width.mjs";
22
22
  import { windowOf } from "./views/scroll.mjs";
@@ -44,6 +44,9 @@ export function heldOf(state, at) {
44
44
  remembered: identityMemory({ memory: state.memory, notes: state.notes }),
45
45
  rosterAnswered: state.remote.rosterAnswered, rosterFailure: state.remote.rosterFailure, cli: state.cli,
46
46
  observing: new Set(), remoteCollecting: state.collecting, home: state.home, at: state.rosterAt ?? at,
47
+ // What the identity reads learned of this computer's listed deployments (lib/main.mjs): a listed one is
48
+ // matched to its workspace in the switcher, and one opened from there is in its view before its first read.
49
+ learned: state.identities,
47
50
  };
48
51
  }
49
52
 
@@ -55,6 +58,14 @@ export function panelOf(state, at) {
55
58
  return state.open === null ? null : panelData(heldOf(state, at), state.open, TERMS);
56
59
  }
57
60
 
61
+ /** The workspace (the shared view's id: panel-views.mjs viewModel) that holds deployment `id` in `state`,
62
+ * or null: what the tabs belong to, so a change of `state.open` within one workspace (its deployment of
63
+ * this machine opened beside another machine's) is not taken for opening another. */
64
+ export function workspaceOf(state, id, at) {
65
+ if (id === null) return null;
66
+ return viewModel(heldOf(state, at), TERMS).views.find((v) => v.id === id || v.deployments.includes(id))?.id ?? null;
67
+ }
68
+
58
69
  const text = (value) => typeof value === "string" && value !== "";
59
70
  const pad = (n) => String(n).padStart(2, "0");
60
71
  /** An ISO time as a local clock time, `14:03:27`, or null. */
@@ -104,6 +115,10 @@ function markOf(row) {
104
115
  return word === "stopped" && row.runtimeState === "shell" ? "shell" : word;
105
116
  }
106
117
 
118
+ /** An instance row's colour (feature instance-color) as one of the terminal's sixteen, through the souls'
119
+ * map (views/souls.mjs SOUL_COLOURS), or null: which colour a row shows is the shared rule (instanceColor). */
120
+ const rowColour = (row) => SOUL_COLOURS[instanceColor(row)] ?? null;
121
+
107
122
  /** The key prefix of each run of instances related to no other, as the shared grouping names it
108
123
  * (`independent:<id>`). Read by key, not by label: a cluster whose root is named `independent` has that
109
124
  * label too, and its key is `cluster:<n>:independent`. */
@@ -310,7 +325,7 @@ function listRow(state, r, item) {
310
325
  const closed = disclosure(state, r, item) === "closed";
311
326
  return {
312
327
  id: item.id, name: item.row.instance, depth: item.depth, selected: item.id === state.selected,
313
- mark: markOf(item.row), word: wordOf(item.row, state.ascii),
328
+ mark: markOf(item.row), color: rowColour(item.row), word: wordOf(item.row, state.ascii),
314
329
  waiting: waitingClaim(item.row, { stale: r.stale(item.row) }) !== null,
315
330
  folded: closed ? r.folded.get(item.id) ?? 0 : 0,
316
331
  below: closed ? r.below.get(item.id)?.length ?? 0 : 0,
@@ -526,43 +541,90 @@ export function switcherLead(state, cols) {
526
541
  return leadRows(leadOf(state), Number.isInteger(cols) && cols > 0 ? cols : 80, { ascii: state.ascii }).length;
527
542
  }
528
543
 
529
- /** The switcher's rows for a state, top to bottom: the workspaces this run can show, as the
530
- * shared home lists and words them; then the ones matched to no workspace under the shared
531
- * heading; then the rows of this computer's deployments list that this run does not serve, in
532
- * the kernel's order, under the TUI's own. A served deployment's id and a row's path are both
533
- * canonical, so a deployment opened in this run is never offered again.
534
- * An item is `{ heading, shared }`, or a choice: `{ key, label, place, notLiveText, open,
535
- * primary }` for a view (`primary` is the deployment Enter opens) and `{ key, label, place,
536
- * path, state, refused }` for a row of the list (`state` the kernel's: views/switcher.mjs says a
537
- * stale one in words). `keys` are the choices in order; `selected` is the key the selection
538
- * stands on (the first choice when the state's own is not listed). */
544
+ /** The word an indicator line says of a deployment of a workspace in the switcher, or null for a live
545
+ * one: "not opened" for a deployment of this computer's list that this run does not serve (the TUI's
546
+ * own), else the shared word for its state (roster-sections.mjs deploymentState: not observed, not
547
+ * reached, stale, remembered). */
548
+ export const NOT_OPENED = "not opened";
549
+ function indicatorState(info) {
550
+ if (info.listed) return NOT_OPENED;
551
+ const said = deploymentState(info);
552
+ return said.key === "live" ? null : said.text;
553
+ }
554
+
555
+ /** The switcher's rows for a state, top to bottom: the workspaces, each a choice followed by one
556
+ * indicator line per deployment of it; then the views matched to no workspace under the shared
557
+ * heading; then the rows of this computer's deployments list that this run does not serve and that
558
+ * no workspace took, in the kernel's order, under the TUI's own.
559
+ * A workspace is what the shared rule (panel-views.mjs listedViews, buildViews underneath) makes of
560
+ * the deployments this run serves, the machines' groups and the listed deployments whose identity a
561
+ * read learned (`state.identities`, lib/main.mjs): a listed deployment that reports the same
562
+ * workspace as another is in its row. A served deployment's id and a row's path are both canonical,
563
+ * so a deployment opened in this run is never offered again.
564
+ * An item is `{ heading, shared }`; `{ indicator }`, a line under a workspace (its deployment's
565
+ * machine label, with a path tail where the shared label adds one, then its state word when it is
566
+ * not live: indicatorState), never a choice; or a choice: `{ key, label, open, primary, join, opens }`
567
+ * for a workspace (`primary` the deployment Enter opens when every local one is served; `join` the
568
+ * listed deployments Enter opens first, and `opens` the deployments it may then open, in order),
569
+ * `{ key, label, place, notLiveText, open, primary }` for a view matched to no workspace, and
570
+ * `{ key, label, place, path, state, refused }` for a row of the list (`state` the kernel's:
571
+ * views/switcher.mjs says a stale one in words; `place` why no workspace took it, when a read said, then its path: the reason first, so a narrow row
572
+ * cuts the path and keeps it).
573
+ * `keys` are the choices in order; `selected` is the key the selection stands on (the first choice
574
+ * when the state's own is not listed). */
539
575
  export function switcher(state, at = new Date(0).toISOString()) {
540
- const held = heldOf(state, at), views = viewModel(held, TERMS);
576
+ const held = heldOf(state, at);
577
+ const unserved = state.listed.rows.filter((row) => !state.ctxs.includes(row.path));
578
+ // Only a row the kernel says is a deployment is matched: a stale one (missing, not one any more) says so instead.
579
+ const views = listedViews(held, unserved.filter((row) => row.state === "ok"), TERMS);
541
580
  const rows = workspaceChoiceRows(workspaceChoices(held, TERMS, views));
542
581
  const query = state.switcher.query;
582
+ const viewOf = (id) => views.views.find((v) => v.id === id);
543
583
  const openView = state.open === null ? null : views.views.find((v) => v.id === state.open || v.deployments.includes(state.open))?.id ?? null;
544
- const choice = (row) => ({
545
- key: `view\u0000${row.id}`, label: row.label, place: row.place, notLiveText: row.notLiveText, open: row.id === openView,
546
- primary: views.views.find((v) => v.id === row.id)?.primary ?? null,
547
- });
548
- const shown = rows.filter((row) => choiceMatches(row, query));
549
- const matched = shown.filter((row) => !row.unattached).map(choice), unmatched = shown.filter((row) => row.unattached).map(choice);
550
- const unserved = state.listed.rows.filter((row) => !state.ctxs.includes(row.path));
551
- const offered = unserved
552
- .map(({ path, name, state: listedState }) => ({ key: `path\u0000${path}`, label: name, place: shortPath(path, { home: state.home }), path, state: listedState, refused: state.switcher.refused === path }))
584
+ const items = [];
585
+ for (const row of rows.filter((each) => !each.unattached)) {
586
+ // This machine's deployments first (the served, then the listed), then the other machines', each in the shared order.
587
+ const all = viewOf(row.id).deployments.map((id) => views.infos.get(id)).filter(Boolean);
588
+ const infos = [...all.filter((info) => info.local), ...all.filter((info) => !info.local)], view = viewOf(row.id);
589
+ const labels = machineLabels(infos, TERMS);
590
+ const lines = infos.map((info) => [labels.get(info.id), indicatorState(info)].filter(Boolean).join(" · "));
591
+ if (!choiceMatches({ label: row.label, place: lines.join(" ") }, query)) continue;
592
+ const join = infos.filter((info) => info.listed).map((info) => info.id);
593
+ items.push({ key: `view\u0000${row.id}`, label: row.label, open: row.id === openView, primary: view.primary, join,
594
+ opens: infos.map((info) => info.id) });
595
+ for (const line of lines) items.push({ indicator: line });
596
+ }
597
+ const unmatched = rows.filter((row) => row.unattached && choiceMatches(row, query)).map((row) => ({
598
+ key: `view\u0000${row.id}`, label: row.label, place: row.place, notLiveText: row.notLiveText, open: row.id === openView, primary: viewOf(row.id)?.primary ?? null,
599
+ }));
600
+ const why = new Map(views.unmatched.map((info) => [info.id, info.short]));
601
+ const taken = new Set([...views.infos.keys()]);
602
+ const offered = unserved.filter((row) => !taken.has(row.path))
603
+ .map(({ path, name, state: listedState }) => ({
604
+ key: `path\u0000${path}`, label: name, place: [why.get(path), shortPath(path, { home: state.home })].filter(Boolean).join(" · "), path, state: listedState, refused: state.switcher.refused === path,
605
+ }))
553
606
  .filter((item) => choiceMatches(item, query));
554
- const items = [
555
- ...matched,
607
+ items.push(
556
608
  ...(unmatched.length ? [{ heading: UNMATCHED_SECTION, shared: true }, ...unmatched] : []),
557
609
  ...(offered.length ? [{ heading: OFFERED_SECTION, shared: false }, ...offered] : []),
558
- ];
610
+ );
559
611
  const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
560
- const total = rows.length + unserved.length;
612
+ const total = rows.length + unserved.filter((row) => !taken.has(row.path)).length;
561
613
  return {
562
614
  items, keys, selected: keys.includes(state.switcher.selected) ? state.switcher.selected : keys[0] ?? null,
563
615
  empty: keys.length ? null : total ? "nomatch" : "none",
564
616
  };
565
617
  }
618
+ /** The window of the switcher's `items` in a pane `height` rows tall, from `top`, that holds the choice
619
+ * `key` and, while they fit, the indicator lines under it (scroll.mjs windowOf, asked to keep the last
620
+ * of them and then the choice). No key (-1 kept): the window as `top` gives it. */
621
+ export function switcherWindow(items, key, { top, height }) {
622
+ const at = key === null ? -1 : items.findIndex((item) => item.key === key);
623
+ let last = at;
624
+ while (last >= 0 && items[last + 1]?.indicator !== undefined) last++;
625
+ const after = windowOf({ top, count: items.length, height, keep: last });
626
+ return windowOf({ top: after.top, count: items.length, height, keep: at });
627
+ }
566
628
 
567
629
  /** The palette's views and commands, each a row's label and the action it runs. */
568
630
  const PALETTE_VIEWS = Object.freeze([["instances", "Instances"], ["souls", "Souls"], ["capabilities", "Capabilities"]]);
@@ -574,51 +636,75 @@ const PALETTE_SPLIT = Object.freeze({
574
636
  });
575
637
  const PALETTE_ACTS = Object.freeze({ stop: "Stop", restart: "Restart", retire: "Retire", start: "Start" });
576
638
 
639
+ /** Which way each of the palette's own keys (its `does`, lib/actions.mjs paletteKeys) moves the
640
+ * selection among the palette's runs: to the next, or to the one before. */
641
+ const PALETTE_STEPS = Object.freeze({ "palette-next-group": 1, "palette-previous-group": -1 });
642
+
577
643
  /** THE PALETTE'S ROWS (docs/tui.md, "The palette"), in this order: the instances that can be
578
- * opened (the most recently opened in this run first, then the shared order), the souls of the
579
- * open workspace once its catalog was read, its capabilities once theirs was, the views, the acts
580
- * the palette's instance offers (the open terminal's, when the palette came from its focus; else
581
- * the selected one) and, once the catalog lists its soul, another of that soul, then spawning an
582
- * agent, workspaces, refresh and help, and the split's that apply. With a query, each group keeps the rows the
583
- * Desktop's subsequence score matches, the best first (a prefix first); a tie keeps that order.
584
- * A row: `{ key, kind, label, does?, id?, name?, machine?, mark?, sibling?, capability?, source? }`; `selected` is the key the
585
- * selection stands on (the first row when the palette's own is not listed). */
644
+ * opened, grouped and ordered as the sidebar's tree but by recency (the shared rosterSections
645
+ * with `lastFocus`, the Desktop's palette's: the group, the cluster, the root and the child opened
646
+ * most recently in this run first, then the shared order; one section per deployment where the
647
+ * view has several, as the sidebar's), each group led by a row of its label (`kind: "group"`: its
648
+ * name, the deployment's before it where there are several, never selected), then the souls of
649
+ * the open workspace once its catalog was read, its capabilities once theirs was, the views, the
650
+ * acts the palette's instance offers (the open terminal's, when the palette came from its focus;
651
+ * else the selected one) and, once the catalog lists its soul, another of that soul, then
652
+ * spawning an agent, workspaces, refresh and help, and the split's that apply. With a query, an
653
+ * instance group keeps the rows the Desktop's subsequence score matches, in its own order, and a
654
+ * group with none has no label row; each kind after them keeps its matches the best first (a
655
+ * prefix first), a tie in that order. A row: `{ key, kind, label, does?, id?, name?, machine?, mark?, sibling?, capability?, source? }`.
656
+ * `runs`: the keys of the rows that can be selected, run by run (each instance group, then each
657
+ * kind), which the palette's own keys move between (paletteStep). `selected` is the key the
658
+ * selection stands on (the first row that can be selected when the palette's own is not listed). */
586
659
  export function paletteItems(state, at = new Date(0).toISOString()) {
587
660
  const p = state.palette;
588
- if (p === null) return { items: [], selected: null };
589
- const groups = [];
661
+ if (p === null) return { items: [], runs: [], selected: null };
662
+ const query = p.query.trim();
663
+ // An instance group keeps its order under a query; a kind is ranked by the score.
664
+ const matched = (item) => query === "" || subsequenceScore(item.text, query) !== null;
665
+ const ranked = (group) => (query === "" ? group
666
+ : group.map((item, i) => ({ item, i, score: subsequenceScore(item.text, query) })).filter((each) => each.score !== null).sort((a, b) => a.score - b.score || a.i - b.i).map(({ item }) => item));
667
+ const runs = [];
590
668
  if (state.open !== null) {
591
669
  const r = roster(state, at);
592
- const recent = new Map(state.recent.map((id, i) => [id, i]));
593
- const rank = (row) => recent.get(instanceId(row)) ?? Infinity;
594
- const openable = r.ordered.filter((row) => openDecision(state, row, instanceActs(row)).open);
595
- groups.push(openable.map((row, i) => ({ row, i })).sort((a, b) => rank(a.row) - rank(b.row) || a.i - b.i).map(({ row }) => {
670
+ const openable = r.instances.filter((row) => openDecision(state, row, instanceActs(row)).open);
671
+ // The record of focus the shared order reads: larger is more recent, `recent` is the latest first.
672
+ const lastFocus = new Map(state.recent.map((id, i) => [id, state.recent.length - i]));
673
+ const item = (row) => {
596
674
  const machine = elsewhere(row) ? row.deployment?.machine ?? row.server : null;
597
675
  // `sibling`: the shared words for its siblings, or null; never part of what a query matches.
598
676
  return {
599
677
  key: `instance\u0000${instanceId(row)}`, kind: "instance", label: row.instance, id: instanceId(row), name: row.instance, machine, mark: markOf(row),
600
678
  sibling: siblingText(r.siblings.get(instanceId(row))), text: `${row.instance} ${machine ?? ""}`,
601
679
  };
602
- }));
680
+ };
681
+ for (const section of rosterSections(r.instances, openable, r.deployments, TERMS, { lastFocus })) for (const group of section.groups) {
682
+ const rows = group.clusters.flatMap((cluster) => cluster.instances).map(item).filter(matched);
683
+ if (!rows.length) continue;
684
+ // A group is named, and kept apart, by its deployment where there are several (the Desktop's palette.mjs).
685
+ const key = section.deployment ? `${section.deployment.id}|${group.key}` : group.key;
686
+ runs.push([{ key: `group\u0000${key}`, kind: "group", label: section.deployment ? `${section.label} · ${group.label}` : group.label }, ...rows]);
687
+ }
603
688
  }
689
+ const kinds = [];
604
690
  // The souls of the open workspace, once its catalog was read (the Souls view opened): choosing
605
691
  // one shows the Souls view with it selected. A palette never reads the catalog.
606
- groups.push(soulsOf(state).all.map((row) => ({ key: `soul\u0000${row.name}`, kind: "soul", label: row.name, name: row.name, text: row.name })));
692
+ kinds.push(soulsOf(state).all.map((row) => ({ key: `soul\u0000${row.name}`, kind: "soul", label: row.name, name: row.name, text: row.name })));
607
693
  // The capabilities of the open workspace, once its catalog was read (the Capabilities view opened):
608
694
  // choosing one shows that view with it selected. Each says where it comes from (a package's and a
609
695
  // member's may share a name).
610
696
  const c = capabilitiesOf(state), names = memberNames(c.status);
611
- groups.push(c.all.map((row) => {
697
+ kinds.push(c.all.map((row) => {
612
698
  const capability = capabilityKey(row, names);
613
699
  return { key: `capability\u0000${capability}`, kind: "capability", label: row.name, name: row.name, capability, source: capabilitySource(row, names).label, text: row.name };
614
700
  }));
615
- groups.push(PALETTE_VIEWS.map(([does, label]) => ({ key: `view\u0000${does}`, kind: "view", label, does, text: label })));
701
+ kinds.push(PALETTE_VIEWS.map(([does, label]) => ({ key: `view\u0000${does}`, kind: "view", label, does, text: label })));
616
702
  const id = p.from === "terminal" && state.terminal !== null ? state.terminal.id : state.selected;
617
703
  const row = id === null || state.open === null ? null : roster(state, at).instances.find((each) => instanceId(each) === id) ?? null;
618
704
  if (row !== null && state.opening === null) {
619
705
  const acts = instanceActs(row);
620
706
  const another = !elsewhere(row) && state.ctxs.includes(state.open) ? soulOfAgent(state, state.open, row.agent) : null;
621
- groups.push([
707
+ kinds.push([
622
708
  ...ACT_VERBS.filter((verb) => actDecision(state, row, acts, verb).open)
623
709
  .map((verb) => ({ key: `act\u0000${verb}`, kind: "act", label: PALETTE_ACTS[verb], does: verb, id: instanceId(row), name: row.instance, text: `${PALETTE_ACTS[verb]} ${row.instance}` })),
624
710
  // Another of its soul (N), once the catalog lists that soul: the row names the soul.
@@ -630,16 +716,28 @@ export function paletteItems(state, at = new Date(0).toISOString()) {
630
716
  // empty. A split there is no room for says so when it is run.
631
717
  const splitting = state.tabs.length > 0 && state.opening === null && !state.tabs.some((tab) => tab.status === "starting");
632
718
  const SPLIT = splitting ? (state.split === null ? PALETTE_SPLIT.one : state.terminal !== null ? PALETTE_SPLIT.shown : PALETTE_SPLIT.empty) : [];
633
- groups.push([...PALETTE_COMMANDS, ...SPLIT].map(([does, label]) => ({ key: `command\u0000${does}`, kind: "command", label, does, text: label })));
634
- const query = p.query.trim();
635
- const items = groups.flatMap((group) => (query === ""
636
- ? group
637
- : group.map((item, i) => ({ item, i, score: subsequenceScore(item.text, query) })).filter((each) => each.score !== null).sort((a, b) => a.score - b.score || a.i - b.i).map(({ item }) => item)));
638
- // With nothing chosen yet, the first row; but in the palette as it opens (no query), when the
639
- // first row is the shown tab's instance (the most recent), the second instance: the palette and
640
- // Enter go back to the terminal before it, as the Desktop's recent group does.
641
- const first = p.query === "" && items[0]?.kind === "instance" && items[0].id === state.terminal?.id && items[1]?.kind === "instance" ? items[1] : items[0];
642
- return { items, selected: items.some((item) => item.key === p.selected) ? p.selected : first?.key ?? null };
719
+ kinds.push([...PALETTE_COMMANDS, ...SPLIT].map(([does, label]) => ({ key: `command\u0000${does}`, kind: "command", label, does, text: label })));
720
+ for (const kind of kinds) { const rows = ranked(kind); if (rows.length) runs.push(rows); }
721
+ const items = runs.flat(), selectable = items.filter((each) => each.kind !== "group"), instances = selectable.filter((each) => each.kind === "instance");
722
+ // With nothing chosen yet, the first row that can be selected; but in the palette as it opens (no
723
+ // query), when that is the shown tab's instance (the most recent), the instance shown before it
724
+ // (`recent`'s second, wherever its group puts it), else the second instance: the palette and Enter
725
+ // go back to the terminal before it, as the Desktop's recent group did.
726
+ const before = instances.find((each) => each.id === state.recent[1]) ?? instances[1];
727
+ const first = p.query === "" && instances.length > 1 && selectable[0] === instances[0] && instances[0].id === state.terminal?.id ? before : selectable[0];
728
+ return {
729
+ items, runs: runs.map((run) => run.filter((each) => each.kind !== "group").map((each) => each.key)),
730
+ selected: selectable.some((each) => each.key === p.selected) ? p.selected : first?.key ?? null,
731
+ };
732
+ }
733
+ /** Where the palette's own key `does` (lib/actions.mjs paletteKeys) takes the selection of `list`
734
+ * (paletteItems): the first row of the next run, or of the one before, wrapping past either end;
735
+ * with one run, its first row. Null with no row, or for a `does` that is not the palette's. */
736
+ export function paletteStep(list, does) {
737
+ const step = PALETTE_STEPS[does], n = list.runs.length;
738
+ if (step === undefined || n === 0) return null;
739
+ const at = list.runs.findIndex((run) => run.includes(list.selected));
740
+ return list.runs[(((at < 0 ? 0 : at + step) % n) + n) % n][0];
643
741
  }
644
742
  /** The palette as the view draws it, in a body `page` rows tall: its query on the first row, and
645
743
  * under it the window of its rows that holds the selection (whose last row says what is cut off,
@@ -678,8 +776,15 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
678
776
  workspace: r.workspace, machines: r.machines, here: r.here, machine: r.machine, counts: r.counts, readAt: r.readAt, notice: r.notice, note: r.note, empty: r.empty, observed: r.observed,
679
777
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
680
778
  detachKey: state.detachKey, opening: state.opening, openable: false,
681
- // The chords, `[key id, does]`, while the terminal confirms the kitty keyboard protocol; else null.
682
- chords: state.keyboard === null ? null : [...state.chords],
779
+ // The chords read now, `[key id, does]` (actions.mjs chordsRead), and whether the terminal
780
+ // confirms the kitty keyboard protocol: then the help and a terminal's cheat sheet lead with them.
781
+ chords: [...chordsRead(state.chords, state.keyboard !== null)], kitty: state.keyboard !== null,
782
+ // The family the chords are bound in (keys.json, lib/config.mjs loadKeys), its name, and the line that says
783
+ // why the file was not taken, or null (the shared chordFamilyNote): the help's chords section names both.
784
+ keys: state.keysRead ? Object.freeze({ family: state.keysRead.family, label: CHORD_FAMILY_LABELS[state.keysRead.family] ?? CHORD_FAMILY_LABELS[DEFAULT_CHORD_FAMILY], note: chordFamilyNote(state.keysRead) }) : null,
785
+ // The palette's own keys, `[key id, does]` (actions.mjs paletteKeys; none on macOS): its cheat
786
+ // sheet and the help name them.
787
+ paletteKeys: [...state.paletteKeys],
683
788
  terminal: state.terminal, onTerminal: false,
684
789
  // The panel's groups (views/frame.mjs), the split and the focused group; the panel stands while
685
790
  // any tab is open. `tabs` is the focused group's strip: each tab in order, the shown one marked,
@@ -697,10 +802,9 @@ export function model(state, { page, body = page, now, at, cols, area = cols })
697
802
  };
698
803
  if (under === "switcher") {
699
804
  const s = switcher(state, at);
700
- const at_ = s.selected === null ? -1 : s.items.findIndex((item) => item.key === s.selected);
701
805
  // The lines above the rows take the pane's rows, and so does the filter field while it is
702
806
  // typed or kept: the window is that much shorter, so no choice is hidden for them (switcherHeight).
703
- const win = windowOf({ top: state.switcher.top, count: s.items.length, height: switcherHeight(state, body, area), keep: state.switcher.loose ? -1 : at_ });
807
+ const win = switcherWindow(s.items, state.switcher.loose ? null : s.selected, { top: state.switcher.top, height: switcherHeight(state, body, area) });
704
808
  return {
705
809
  ...common, under, list: [], above: 0, below: 0, wordWidth: 0, detail: null,
706
810
  // Nothing of a workspace stands in the sidebar while the switcher is shown.
@@ -983,7 +1087,7 @@ function soulDetail(state, at, row) {
983
1087
  name: row.name, description: row.description ?? "", from: soulFrom(row), works: facts.work, refusal: facts.refusalLine,
984
1088
  harness: { rows: facts.rows, notes: facts.notes, problem: facts.problem },
985
1089
  teams, capabilities,
986
- instances: { shown: here.slice(0, INSTANCES_NAMED).map((each) => ({ name: each.instance, mark: markOf(each) })), more: Math.max(0, here.length - INSTANCES_NAMED) },
1090
+ instances: { shown: here.slice(0, INSTANCES_NAMED).map((each) => ({ name: each.instance, mark: markOf(each), color: rowColour(each) })), more: Math.max(0, here.length - INSTANCES_NAMED) },
987
1091
  };
988
1092
  }
989
1093
 
@@ -15,7 +15,7 @@ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realp
15
15
  import { tmpdir } from "node:os";
16
16
  import { dirname, join } from "node:path";
17
17
  import { fileURLToPath } from "node:url";
18
- import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
18
+ import { COLLECTOR, INSTANCE_VARIABLES, MAX_DEPLOYMENT_OBSERVATIONS, acceptProbe, cliDeploymentIdentity, cliDeploymentRead, cliReadsRemotes, cliRecord, cliRemoteRoster, createDeploymentObserver, createRefreshLoop, failedEntry, identityReadable, identityTimedOut, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
19
19
 
20
20
  /** A path made canonical: what the shared start rule checks a local home with (session-start.mjs
21
21
  * verifiedLocalHome). Throws for a path that cannot be resolved; the rule answers that as no home. */
@@ -613,3 +613,55 @@ export function createReader({ cli, getServed, getEntry, getRoster, onEntry, onR
613
613
  children() { return [...remembered.keys()].map((child) => child.pid).filter((pid) => Number.isInteger(pid)); },
614
614
  };
615
615
  }
616
+
617
+ /** The most time the identity reads of one run take together, in ms: two reads at their own limit
618
+ * (packages/client deployment-read-cli.mjs DEPLOYMENT_READ_TIMEOUT, 30 s each). */
619
+ export const IDENTITY_BUDGET_MS = 60_000;
620
+
621
+ /** THE IDENTITY READS (docs/tui.md, "The switcher"): what the switcher learns of the deployments of this
622
+ * computer's list that the run does not serve, so that one of them is matched to its workspace before it
623
+ * is opened (#482). -> { start(paths), stop() }
624
+ * `start(paths)` reads each path's identity through the shared cliDeploymentIdentity (`oats status --dir
625
+ * <path> --json`, the read an opened deployment gets, with its own time limit, `--max-age` as a background
626
+ * cycle's), ONE AT A TIME, in order, and calls `onRead({ path, read })` with each answer as it comes:
627
+ * nothing waits for them, and the screen is drawn before the first. They take IDENTITY_BUDGET_MS at most
628
+ * together: when it runs out the read in flight is ended, and it and every read not begun answer the
629
+ * shared timed-out failure (identityTimedOut). A new `start` ends the run before it, whose answers are
630
+ * then dropped, and so does `stop()`. With a kernel that reports no workspace identities
631
+ * (identityReadable), or no path, nothing is read.
632
+ * Nothing here runs on a timer: a run starts only when its caller says, and the caller says so at the
633
+ * start and when the switcher is opened or refreshed (lib/main.mjs), never from the refresh loop.
634
+ * `exec` is the reader's asked exec (createReader `exec`): every read is a child of kind "read" in a
635
+ * session of its own, ended on every way out, and ended through the run's signal here. */
636
+ export function createIdentityReads({ cli, exec, env, onRead, timers = globalThis, budgetMs = IDENTITY_BUDGET_MS, read = cliDeploymentIdentity }) {
637
+ let run = null;
638
+ function stop() {
639
+ if (run === null) return;
640
+ run.gone = true;
641
+ run.controller.abort();
642
+ run = null;
643
+ }
644
+ async function start(paths) {
645
+ stop();
646
+ // No exec of the reader's, nothing is read: the shared reader would start its own child otherwise.
647
+ if (typeof exec !== "function" || !identityReadable(cli) || !Array.isArray(paths) || !paths.length) return;
648
+ const mine = run = { controller: new AbortController(), gone: false, spent: false };
649
+ const timer = timers.setTimeout(() => { mine.spent = true; mine.controller.abort(); }, budgetMs);
650
+ timer?.unref?.();
651
+ const own = (bin, argv, options, callback) => exec(bin, argv, { ...options, signal: mine.controller.signal }, callback);
652
+ try {
653
+ for (const path of paths) {
654
+ if (mine.gone) return;
655
+ let answer = mine.spent ? identityTimedOut() : await read(cli, path, { maxAge: BACKGROUND_MAX_AGE }, { exec: own, env });
656
+ if (mine.gone) return;
657
+ // A read the budget ended answers whatever its ending made of it: it timed out.
658
+ if (mine.spent && !answer?.ok) answer = identityTimedOut();
659
+ onRead({ path, read: answer });
660
+ }
661
+ } finally {
662
+ timers.clearTimeout(timer);
663
+ if (run === mine) run = null;
664
+ }
665
+ }
666
+ return { start: (paths) => start(paths).catch(() => {}), stop };
667
+ }