@awebai/oats 0.63.0 → 0.65.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 (47) hide show
  1. package/README.md +14 -1
  2. package/bin/oats.mjs +158 -26
  3. package/docs/desktop-cli-api.md +127 -3
  4. package/docs/desktop.md +14 -5
  5. package/docs/execution-targets.md +9 -5
  6. package/docs/first-team.md +6 -0
  7. package/docs/implementation.md +17 -3
  8. package/docs/official-catalog.md +1 -1
  9. package/docs/packages.md +5 -5
  10. package/docs/release-notes/v0.64.0.md +105 -0
  11. package/docs/release-notes/v0.65.0.md +187 -0
  12. package/docs/souls-and-instances.md +26 -6
  13. package/docs/tui.md +416 -238
  14. package/docs/upgrading.md +2 -1
  15. package/docs/workspaces.md +125 -1
  16. package/lib/core.mjs +43 -11
  17. package/lib/deployments.mjs +325 -0
  18. package/lib/resolved-deployment.mjs +37 -0
  19. package/lib/session-input.mjs +12 -2
  20. package/lib/workspace.mjs +2 -0
  21. package/package-catalog.json +1 -1
  22. package/package.json +1 -1
  23. package/packages/client/cli-locator.mjs +2 -2
  24. package/packages/client/deployment-label.mjs +2 -2
  25. package/packages/client/deployment-list-cli.mjs +98 -0
  26. package/packages/client/deployment-list.mjs +91 -0
  27. package/packages/client/instance-tree.mjs +53 -3
  28. package/packages/client/keymap.mjs +106 -0
  29. package/packages/client/own-codes.mjs +2 -0
  30. package/packages/client/panel-views.mjs +1 -1
  31. package/packages/client/roster-sections.mjs +22 -6
  32. package/packages/client/workspace-admission.mjs +2 -1
  33. package/packages/tui/README.md +4 -4
  34. package/packages/tui/lib/actions.mjs +29 -5
  35. package/packages/tui/lib/client.mjs +3 -1
  36. package/packages/tui/lib/config.mjs +21 -14
  37. package/packages/tui/lib/main.mjs +108 -31
  38. package/packages/tui/lib/model.mjs +71 -41
  39. package/packages/tui/lib/read.mjs +15 -45
  40. package/packages/tui/lib/store.mjs +158 -39
  41. package/packages/tui/lib/term/through.mjs +40 -18
  42. package/packages/tui/lib/views/act.mjs +17 -13
  43. package/packages/tui/lib/views/frame.mjs +418 -421
  44. package/packages/tui/lib/views/help.mjs +41 -19
  45. package/packages/tui/lib/views/instances.mjs +38 -9
  46. package/packages/tui/lib/views/switcher.mjs +65 -21
  47. package/skills/oats-getting-started/SKILL.md +440 -170
@@ -5,6 +5,8 @@
5
5
  // An action that does one thing in the list of instances and another in the switcher (`open`)
6
6
  // says so in `views`: what it does in each, in the order the help lists them. An action of one
7
7
  // view only (the four acts) names that view, so the help says where it acts.
8
+ import { isBackKey } from "./term/through.mjs";
9
+
8
10
  export const ACTIONS = Object.freeze([
9
11
  { id: "up", keys: ["up", "k"], label: "up" },
10
12
  { id: "down", keys: ["down", "j"], label: "down" },
@@ -17,8 +19,8 @@ export const ACTIONS = Object.freeze([
17
19
  { id: "detail", keys: ["tab"], label: "detail" },
18
20
  { id: "filter", keys: ["/"], label: "filter" },
19
21
  { id: "refresh", keys: ["r"], label: "refresh" },
20
- // The views by their number. The header names the views and never draws a digit against a name
21
- // (docs/tui.md, "The header"): the digits are named here, so in the help and the footer.
22
+ // The views by their number. The sidebar names the views, each with its key at the right of its row
23
+ // (docs/tui.md, "What it shows"): the digits are named here, so in the help and the sidebar.
22
24
  { id: "instances", keys: ["1"], label: "instances" },
23
25
  { id: "souls", keys: ["2"], label: "souls" },
24
26
  { id: "capabilities", keys: ["3"], label: "capabilities" },
@@ -26,13 +28,19 @@ export const ACTIONS = Object.freeze([
26
28
  // The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
27
29
  { id: "palette", keys: ["ctrl+k"], label: "palette" },
28
30
  { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal as a tab beside the list, or show its tab when it has one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"], ["souls", "show the selected soul's detail, and from the detail its instances, in the Souls view"], ["capabilities", "show the selected capability's detail, and from the detail the marked soul that uses it, in the Capabilities view"]] },
31
+ // The switcher's Remove (docs/tui.md, "The switcher"; awebai/oats#1390): a row of this computer's
32
+ // deployments list, after a confirmation; nothing on disk is touched. Delete, and no letter: a new
33
+ // default key that a user's tui.json already gives to another action would make that file refused
34
+ // at the start (config.mjs claims every default first), and the free letters are the ones a
35
+ // tui.json is likeliest to use (`x` and `m` among them, see the split below).
36
+ { id: "remove", keys: ["delete"], label: "remove", views: [["switcher", "remove the selected row of this computer's list of deployments, after a confirmation; its folder stays"]] },
29
37
  // The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
30
38
  // Instances view, filtered by that soul.
31
39
  { id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
32
40
  // The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
33
41
  // has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
34
42
  // these is ever read there: the leader's table has its own (LEADER).
35
- { id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader twice brings the list back"]] },
43
+ { id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the shown terminal with the whole screen; the leader then Esc brings the list back"]] },
36
44
  { id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
37
45
  { id: "tab-previous", keys: ["["], label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
38
46
  { id: "tab-next", keys: ["]"], label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
@@ -67,8 +75,10 @@ export const ACTIONS = Object.freeze([
67
75
  * open.detachKey) and what each does, from every focus. Fixed: tui.json's `keys` rebinds the plain
68
76
  * keys of ACTIONS only. `does` is an action id of ACTIONS, or one of the leader's own: `previous`
69
77
  * and `next` (the instance before or after the shown terminal's, or the selection's: its tab
70
- * shown, or opened as a new one, with the focus in it) and `list` (the list's focus). The leader pressed again is `list` too: it is
71
- * the user's key, so it is not in this table. `terminal`: named in the hint only while a terminal
78
+ * shown, or opened as a new one, with the focus in it) and `list` (the list's focus, which
79
+ * Esc gives). The leader pressed again is not in this table either, as it is the user's key: from
80
+ * the open terminal's focus it types the leader's own bytes into the agent, the focus staying
81
+ * there, and from any other focus it only closes the hint (lib/store.mjs `twice`). `terminal`: named in the hint only while a terminal
72
82
  * is open, and nothing without one (the hint names the tab keys only with two tabs or more). */
73
83
  export const LEADER = Object.freeze([
74
84
  { keys: ["k", "space"], does: "palette", label: "palette" },
@@ -118,3 +128,17 @@ export function keyLabel(key) {
118
128
  const name = NAMES[last] ?? (/^f\d+$/.test(last) ? last.toUpperCase() : parts.length && last.length === 1 ? last.toUpperCase() : last);
119
129
  return [...parts.map((part) => NAMES[part] ?? part), name].join("+");
120
130
  }
131
+
132
+ /** The modifiers of the back key's grammar (term/through.mjs BACK_KEY) as a person reads them. */
133
+ const BACK_MODIFIERS = Object.freeze({ C: "Ctrl", M: "Alt", S: "Shift" });
134
+ /** A back key (tui.json's open.detachKey, the leader) as the cheat sheet and the help name it, spelt
135
+ * for people as keyLabel spells a key id: `C-\\` is `Ctrl+\\`, `C-x` is `Ctrl+X`, `M-o` is `Alt+O`,
136
+ * `M-5` is `Alt+5`, `F12` is `F12`, `S-F5` is `Shift+F5`. A letter is written as a capital, which
137
+ * never means Shift (the grammar has lowercase Meta letters only). Pure. A value outside the
138
+ * grammar is answered as it was given (tui.json refuses it; a view draws it as text from outside). */
139
+ export function backKeyLabel(key) {
140
+ if (!isBackKey(key)) return key;
141
+ const [, mod, rest] = /^(?:([CMS])-)?(.+)$/.exec(key);
142
+ const name = rest.length === 1 ? rest.toUpperCase() : rest;
143
+ return mod ? `${BACK_MODIFIERS[mod]}+${name}` : name;
144
+ }
@@ -9,6 +9,8 @@ import { clientTerms } from "../../client/client-terms.mjs";
9
9
  export { displayLine, DETAIL_WITHHELD } from "../../client/display-text.mjs";
10
10
  export { parseProbeStdout, acceptProbe, cliRecord } from "../../client/cli-locator.mjs";
11
11
  export { cliDeploymentRead } from "../../client/deployment-read-cli.mjs";
12
+ export { cliDeploymentList } from "../../client/deployment-list-cli.mjs";
13
+ export { deploymentsListSupported } from "../../client/deployment-list.mjs";
12
14
  export { cliRemoteRoster } from "../../client/cli-adapter.mjs";
13
15
  export { createDeploymentObserver, mapBounded, MAX_DEPLOYMENT_OBSERVATIONS } from "../../client/deployment-observer.mjs";
14
16
  export { createRefreshLoop } from "../../client/refresh-loop.mjs";
@@ -33,7 +35,7 @@ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flig
33
35
  export { startGate, startInstance } from "../../client/session-start.mjs";
34
36
  export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
35
37
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
36
- export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
38
+ export { validateWorkspace } from "../../client/workspace-admission.mjs";
37
39
  export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
38
40
  export { soulRows } from "../../client/soul-rows.mjs";
39
41
  export { soulFacts, spawnRefusal, soulMatches } from "../../client/soul-facts.mjs";
@@ -19,9 +19,12 @@ export const CONFIG_LIMIT = 64 * 1024;
19
19
  const TOO_LARGE = `it is larger than ${CONFIG_LIMIT / 1024} KiB`;
20
20
  const NOT_AN_OBJECT = 'it is not one JSON object, like {"keys": {"quit": ["q"]}}';
21
21
  const SETTINGS = "the settings are keys, ascii and open";
22
- /** The back key when tui.json names none: the key that takes the focus from an agent's terminal
23
- * back to the list (the setting keeps its name, `open.detachKey`, from when it left a viewer). */
24
- export const DETACH_KEY = "C-\\";
22
+ /** The back key when tui.json names none, on `platform` (a `process.platform` value): the key that
23
+ * takes the focus from an agent's terminal back to the list, the leader (the setting keeps its
24
+ * name, `open.detachKey`, from when it left a viewer). `C-\\` on macOS, whose terminals send
25
+ * Option as Meta only when told to; `M-o` (Alt+O) elsewhere. Both are read as keys no action of
26
+ * ACTIONS holds (`ctrl+\\`, `alt+o`), which the check of the leader below keeps true. */
27
+ export const defaultDetachKey = (platform = process.platform) => (platform === "darwin" ? "C-\\" : "M-o");
25
28
  /** An action id this program had and has no more, with what it is called now. */
26
29
  const RENAMED = Object.freeze({ "open-workspace": "open" });
27
30
  const KEY_IDS = "key ids look like q, ctrl+c, shift+tab, f5, space";
@@ -33,7 +36,7 @@ const ERROR_CODE = /^[A-Z][A-Z0-9_]{0,30}$/;
33
36
  export const MAX_PROBLEMS = 20;
34
37
 
35
38
  const plain = (name) => typeof name === "string" && PLAIN_NAME.test(name);
36
- /** Whether the footer and the help can name a key: its label is drawn as text from outside (the
39
+ /** Whether the cheat sheet and the help can name a key: its label is drawn as text from outside (the
37
40
  * shared display filter), and a label that filter would change would name another key, or none.
38
41
  * Such a key (a bidi override, a combining mark on a space) is refused here, with the file named,
39
42
  * where a key the views cannot draw would otherwise be bound and never said. */
@@ -49,9 +52,10 @@ export function configPath(env, home) {
49
52
  return join(typeof xdg === "string" && xdg !== "" && isAbsolute(xdg) ? xdg : join(home, ".config"), "oats", "tui.json");
50
53
  }
51
54
 
52
- /** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table.
53
- * Pure. Answers `{ ok: true, actions, ascii, detachKey }` or `{ ok: false, problems }`:
54
- * `detachKey` is `open.detachKey`, or DETACH_KEY when the file names none.
55
+ /** What tui.json says, checked: `value` is the file already parsed, `defaults` the action table,
56
+ * `platform` the one the TUI runs on (a `process.platform` value). Pure. Answers
57
+ * `{ ok: true, actions, ascii, detachKey }` or `{ ok: false, problems }`: `detachKey` is
58
+ * `open.detachKey`, or defaultDetachKey(platform) when the file names none.
55
59
  *
56
60
  * `actions` is a frozen table shaped exactly like `defaults` (same order, ids and labels, frozen
57
61
  * rows with frozen `keys`) in which the list of each action the file names REPLACES that action's
@@ -63,7 +67,7 @@ export function configPath(env, home) {
63
67
  * order. A key given to two actions is judged with the kept defaults included and names both. An
64
68
  * action whose list is refused takes no part in that judgement: what it was meant to hold is not
65
69
  * known. The ids of `defaults` are the program's own; one that is not plain is still never echoed. */
66
- export function effectiveConfig(value, defaults = ACTIONS) {
70
+ export function effectiveConfig(value, defaults = ACTIONS, platform = process.platform) {
67
71
  if (!isObject(value)) return { ok: false, problems: [NOT_AN_OBJECT] };
68
72
  for (const [setting, given] of Object.entries(value)) {
69
73
  if (setting === "keys") { if (!isObject(given)) return { ok: false, problems: ['keys must be an object, like {"quit": ["q"]}'] }; }
@@ -106,9 +110,11 @@ export function effectiveConfig(value, defaults = ACTIONS) {
106
110
  }
107
111
  // The leader is read as a key wherever the TUI reads keys (docs/tui.md, "The leader"), so no
108
112
  // action may hold the key it reads as: `C-l` would be redraw's Ctrl+L, `C-j` open's Enter.
109
- const detachKey = value.open?.detachKey ?? DETACH_KEY, leader = backKeyId(detachKey);
113
+ const detachKey = value.open?.detachKey ?? defaultDetachKey(platform), leader = backKeyId(detachKey);
110
114
  const taken = defaults.find((action) => (named.get(action.id) ?? action.keys).includes(leader));
111
- if (taken) problems.push(`open.detachKey ${detachKey} is read as ${keyLabel(leader)}, the key of ${say(taken.id)}; give the leader a key no action has, or give ${say(taken.id)} another`);
115
+ // A file that names no leader is told it is the default, which it did not write.
116
+ const which = value.open?.detachKey === undefined ? `the default leader ${detachKey}` : `open.detachKey ${detachKey}`;
117
+ if (taken) problems.push(`${which} is read as ${keyLabel(leader)}, the key of ${say(taken.id)}; give the leader a key no action has, or give ${say(taken.id)} another`);
112
118
  if (problems.length > 0) return { ok: false, problems };
113
119
 
114
120
  const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
@@ -158,24 +164,25 @@ const NODE_IO = Object.freeze({
158
164
  /** Read tui.json, once. Answers `{ ok: true, actions, ascii, detachKey, path }`, or
159
165
  * `{ ok: false, lines }`: the complete lines to print (no trailing newline), after which the TUI
160
166
  * must not start. No file is the defaults: `actions` is ACTIONS itself, `ascii` is false and
161
- * `detachKey` is DETACH_KEY.
167
+ * `detachKey` is defaultDetachKey(platform); `platform` is the one the TUI runs on (a
168
+ * `process.platform` value, given so the answer is known for each).
162
169
  *
163
170
  * `io` is the file system (node:fs when omitted): `io.stat(path)` answers `{ file, size }` after
164
171
  * following symbolic links, or null when the path does not exist, and throws for anything else;
165
172
  * `io.read(path)` answers the text. The size is checked before `read` is called, so a file over
166
173
  * CONFIG_LIMIT, a directory or a FIFO is never opened. A line holds the path only when it is
167
174
  * printable ASCII, and never the text of an error: only its code, when it is a plain one. */
168
- export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO } = {}) {
175
+ export function loadConfig({ env = process.env, home = homedir(), io = NODE_IO, platform = process.platform } = {}) {
169
176
  const path = configPath(env, home);
170
177
  const listed = (problems) => (problems.length > MAX_PROBLEMS ? [...problems.slice(0, MAX_PROBLEMS), problems.length - MAX_PROBLEMS === 1 ? "1 more problem is not listed" : `${problems.length - MAX_PROBLEMS} more problems are not listed`] : problems);
171
178
  const refused = (problems) => ({ ok: false, lines: listed(problems).map((problem) => `oats: \`oats tui\` cannot use ${PLAIN_PATH.test(path) ? path : "its configuration file"}: ${problem} (E_TUI_CONFIG)`) });
172
179
  let found, text, value;
173
180
  try { found = io.stat(path); } catch (error) { return refused([unreadable(error)]); }
174
- if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey: DETACH_KEY, path };
181
+ if (found === null) return { ok: true, actions: ACTIONS, ascii: false, detachKey: defaultDetachKey(platform), path };
175
182
  if (found.file !== true) return refused(["it is not a regular file"]);
176
183
  if (!(typeof found.size === "number" && found.size <= CONFIG_LIMIT)) return refused([TOO_LARGE]); // read only what is known to fit
177
184
  try { text = io.read(path); } catch (error) { return refused([error?.code === "EFBIG" ? TOO_LARGE : unreadable(error)]); }
178
185
  try { value = JSON.parse(text); } catch { return refused(["it is not valid JSON"]); }
179
- const checked = effectiveConfig(value);
186
+ const checked = effectiveConfig(value, ACTIONS, platform);
180
187
  return checked.ok ? { ...checked, path } : refused(checked.problems);
181
188
  }
@@ -12,11 +12,11 @@
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, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
15
+ import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
16
16
  import { loadConfig } from "./config.mjs";
17
- import { ACT_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
17
+ import { ACT_WORDS, LIST_WORDS, actContext, actCwd, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
19
- import { CHANGE_FILES, admitDeployment, createReader, findDeployment, leaveInstance, offeredDeployments, probeKernel, realpath, tellable } from "./read.mjs";
19
+ import { CHANGE_FILES, admitDeployment, createReader, findDeployment, leaveInstance, probeKernel, realpath, startExec, tellable } from "./read.mjs";
20
20
  import { initialState, reduce } from "./store.mjs";
21
21
  import { captureRows } from "./term/capture.mjs";
22
22
  import { createKeyParser, keyId } from "./term/keys.mjs";
@@ -24,7 +24,7 @@ import { createScreen, glyphs } from "./term/screen.mjs";
24
24
  import { colorEnabled } from "./term/style.mjs";
25
25
  import { backKeySequences, createThrough } from "./term/through.mjs";
26
26
  import { createGuard, isTerminal } from "./term/tty.mjs";
27
- import { frame, layout, panelPlace } from "./views/frame.mjs";
27
+ import { frame, layout, mainArea, panelPlace } from "./views/frame.mjs";
28
28
 
29
29
  export const USAGE = "oats tui [--dir <path>] [--ascii]";
30
30
  const HELP = `Usage:
@@ -45,6 +45,10 @@ export const NO_TERMINAL = "oats: `oats tui` needs a terminal on stdin and stdou
45
45
  /** A path is echoed only when it is plain: these lines go to a terminal. */
46
46
  const plainPath = (path) => (typeof path === "string" && /^[\x20-\x7e]{1,200}$/.test(path) ? path : "that directory");
47
47
  export const noDeployment = (dir) => `oats: no OATS deployment at or above ${plainPath(dir)} (E_NO_DEPLOYMENT); name one with \`oats tui --dir <path>\``;
48
+ /** A start outside every deployment, with no `--dir`, when this computer's deployments list holds none (awebai/oats#1390). */
49
+ export const noDeploymentListed = (dir) => `oats: no deployment at or above ${plainPath(dir)}, and this computer's list of deployments holds none (E_NO_DEPLOYMENT): \`oats tui --dir <path>\` opens one (and lists it), \`oats onboard <dir> --workspace <ref>\` creates one`;
50
+ /** The same start, when the list could not be read: the kernel's code and its message, which says what to do. */
51
+ export const noList = (reason) => `oats: \`oats tui\` could not read this computer's list of deployments (${/^E_[A-Z0-9_]{1,62}$/.test(reason?.code ?? "") ? reason.code : NOT_ASKED.code}): ${displayLine(reason?.message) ?? "it gave no reason"}`;
48
52
  export const noKernel = (reason) => `oats: \`oats tui\` could not use its own kernel (E_TUI_KERNEL): ${displayLine(reason) ?? "it gave no reason"}`;
49
53
 
50
54
  /** The arguments: `--ascii`, `--help`/`-h`, `--dir <path>` and `--dir=<path>`. Everything else is
@@ -65,6 +69,12 @@ export function parseArgs(argv) {
65
69
  return { options };
66
70
  }
67
71
 
72
+ /** The label of a change to this computer's deployments list (an add or a remove), for the line after leaving. */
73
+ const LIST_CHANGE = Object.freeze({ verb: "list" });
74
+ /** Why a call to this computer's deployments list has no answer at all: it threw before the kernel
75
+ * could answer. The shared adapter's own code for a kernel call that failed (deployment-list-cli.mjs). */
76
+ const NOT_ASKED = Object.freeze({ code: "E_CLI_FAILED", message: "the kernel could not be asked" });
77
+
68
78
  /** An error as lines fit for a terminal: its stack, each line through the display filter. */
69
79
  function errorLines(error) {
70
80
  const text = error instanceof Error ? error.stack || error.message : String(error);
@@ -80,8 +90,10 @@ function errorLines(error) {
80
90
  * catalog of a workspace's souls, and `createCapabilityCatalog` its table of capabilities, each
81
91
  * replaceable so a test can count its reads; the three spawn
82
92
  * factories are the shared home's preview, apply boundary and transaction, replaceable so a test
83
- * can answer them. */
84
- const EFFECTS = Object.freeze({ loadConfig, findDeployment, probeKernel, createReader, offeredDeployments, admitDeployment, prepareRemoteTerm, createPanel, sweep,
93
+ * can answer them. `deploymentList` is the shared cliDeploymentList (this computer's deployments
94
+ * list, through the kernel: awebai/oats#1390), and `startExec` the exec it is handed before the
95
+ * terminal is taken; replaceable so a test can answer the list. */
96
+ const EFFECTS = Object.freeze({ loadConfig, findDeployment, probeKernel, createReader, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
85
97
  runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
86
98
  createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
87
99
 
@@ -111,7 +123,9 @@ export function createRunTimers({ setTimer, clearTimer }) {
111
123
  * Before the alternate screen, in this order, each failure one line on stderr and status 1:
112
124
  * the arguments; the instance variables removed from the environment (a TUI started in an
113
125
  * agent's pane must read the deployment it was asked about, and so must every child it starts);
114
- * the terminal; the user's tui.json; the deployment; the kernel it shipped with. */
126
+ * the terminal; the user's tui.json; the deployment; the kernel it shipped with; and, for a start
127
+ * outside every deployment with no `--dir`, this computer's deployments list, read through that
128
+ * kernel. */
115
129
  export async function main({ argv, stdin, stdout, stderr, env, proc = process, now = Date.now, setTimer = setTimeout, clearTimer = clearTimeout, cwd = () => process.cwd(), home = homedir(), effects: given = EFFECTS }) {
116
130
  const effects = given === EFFECTS ? EFFECTS : { ...EFFECTS, ...given };
117
131
  const { options, error } = parseArgs(argv);
@@ -119,16 +133,23 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
119
133
  if (options.help) { stdout.write(HELP); return 0; }
120
134
  leaveInstance(env);
121
135
  if (!isTerminal({ stdin, stdout, env })) { stderr.write(`${NO_TERMINAL}\n`); return 1; }
122
- const config = effects.loadConfig({ env, home });
136
+ const config = effects.loadConfig({ env, home, platform: proc.platform });
123
137
  if (!config.ok) { stderr.write(config.lines.map((line) => `${line}\n`).join("")); return 1; }
124
138
  const found = effects.findDeployment(resolve(cwd(), options.dir ?? "."));
125
- // Outside every deployment, and with none named: the switcher, when ~/Agents holds a deployment
126
- // to offer. A `--dir` that is in no deployment is refused as it is: what was asked for is not there.
127
- const offered = found.ok || options.dir !== null ? null : effects.offeredDeployments(home, []);
128
- if (!found.ok && !offered?.offered.length) { stderr.write(`${noDeployment(found.dir)}\n`); return 1; }
139
+ // A `--dir` that is in no deployment is refused as it is: what was asked for is not there.
140
+ if (!found.ok && options.dir !== null) { stderr.write(`${noDeployment(found.dir)}\n`); return 1; }
129
141
  // The kernel is asked once: an upgrade under a running TUI is met by starting it again.
130
142
  const probe = await effects.probeKernel({ env });
131
143
  if (!probe.ok) { stderr.write(`${noKernel(probe.reason)}\n`); return 1; }
144
+ // Outside every deployment, and with none named: the switcher, when this computer's deployments
145
+ // list holds a row, read through the kernel just asked. A list that cannot be read is no empty one.
146
+ let listedAtStart = null;
147
+ if (!found.ok) {
148
+ const listed = await effects.deploymentList(probe.cli, { action: "list" }, { exec: effects.startExec, env });
149
+ if (!listed.ok) { stderr.write(`${noList(listed.reason)}\n`); return 1; }
150
+ if (!listed.value.rows.length) { stderr.write(`${noDeploymentListed(found.dir)}\n`); return 1; }
151
+ listedAtStart = listed.value.rows;
152
+ }
132
153
 
133
154
  const clock = () => new Date(now()).toISOString();
134
155
  const look = glyphs(env, { ascii: options.ascii || config.ascii });
@@ -141,16 +162,18 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
141
162
  // takes the focus, so nothing held from before is typed into it.
142
163
  const backKey = backKeySequences(state.detachKey);
143
164
  let through = createThrough({ sequences: backKey, now }), throughTimer = null;
144
- if (offered) state = reduce(state, { offered }, keymap).state;
165
+ if (listedAtStart) state = reduce(state, { listed: { rows: listedAtStart } }, keymap).state;
145
166
  // What the last frame drew, for the store: how tall the list pane is and how far the other
146
167
  // pane scrolls. The store holds no size of its own; the panel's room goes with each key as it
147
168
  // is when the key is read (placed), whatever the last frame drew.
148
- let drawn = { page: 1, extent: 0, room: 1, cols: 1 };
169
+ let drawn = { page: 1, extent: 0, room: 1, cols: 1, area: 1 };
149
170
  let full = true, escTimer = null, ended = false, reads = 0;
150
171
  /** The preflight of another machine's agent under way: `{ id, controller, prepared }`, where
151
172
  * `prepared` is what it answered (`{ binary, args }`) once it has; or null. */
152
173
  let preflight = null;
153
- /** The run's private directory, made at the first change or the first open (lib/read.mjs
174
+ /** The run's private directory, made at the first change (with a kernel that lists this
175
+ * computer's deployments, the add of the deployment the run started in, at the start) or the
176
+ * first open (lib/read.mjs
154
177
  * CHANGE_FILES): the reader writes a change's output there, and the panel keeps its tmux
155
178
  * server's socket there. */
156
179
  let dir = null;
@@ -379,8 +402,9 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
379
402
  });
380
403
  }
381
404
  /** One step of the reducer taken: the state, then what only the loop can do. True once the
382
- * TUI is leaving. Listing ~/Agents and asking whether a picked folder is a deployment read the
383
- * file system (lib/read.mjs); what they find is an event of its own. */
405
+ * TUI is leaving. Asking whether a picked row is a deployment reads the file system
406
+ * (lib/read.mjs), and reading or changing this computer's deployments list asks the kernel; what
407
+ * each finds is an event of its own. */
384
408
  function took(step) {
385
409
  state = step.state;
386
410
  const effect = step.effect;
@@ -388,7 +412,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
388
412
  if (effect === "suspend") guard.suspend();
389
413
  if (effect === "redraw") guard.reassert(); // the modes again, then the whole screen
390
414
  if (effect === null || typeof effect !== "object") return false;
391
- if (effect.offer) took(reduce(state, { offered: effects.offeredDeployments(home, state.ctxs) }, keymap));
415
+ if (effect.list) readList();
416
+ if (effect.remove) removeListed(effect.remove);
392
417
  if (effect.admit !== undefined) {
393
418
  const admitted = effects.admitDeployment(effect.admit);
394
419
  took(reduce(state, admitted.ok ? { admitted: admitted.deployment, at: clock() } : { refused: effect.admit }, keymap));
@@ -402,6 +427,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
402
427
  preflight = null;
403
428
  if (ready?.id === effect.panel && ready.prepared) view(effect.panel, ready.prepared.binary, ready.prepared.args);
404
429
  }
430
+ // The leader twice from the terminal's focus: its own bytes to the agent, as what is typed goes.
431
+ if (effect.input) { if (keysReady()) panel.input(effect.input); }
405
432
  if (effect.dismiss !== undefined) dismiss(effect.dismiss);
406
433
  if (effect.act) openConfirmation(effect.act);
407
434
  if (effect.call) callConfirmation(effect.call);
@@ -417,6 +444,49 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
417
444
  return false;
418
445
  }
419
446
 
447
+ // THIS COMPUTER'S DEPLOYMENTS LIST (docs/tui.md, "The switcher"; awebai/oats#1390), the kernel's,
448
+ // through the shared cliDeploymentList. A read of it is a read (the reader's exec, ended on every
449
+ // way out), and one runs at a time: a read asked for while one is on its way is one more, after
450
+ // it, however many times it was asked, and the answer of the one on its way is not taken, since
451
+ // it may be of the list as it was before what asked again (a Remove). An add or a remove is a
452
+ // change (the reader's changeExec: never ended by the TUI, only at the adapter's own deadline),
453
+ // labelled so the line after leaving names the list. The kernel this TUI shipped with lists
454
+ // this computer's deployments in every release; one that does not (a checkout between the
455
+ // kernel's change and this one) is asked nothing in the run, and its "Update oats" is not said
456
+ // of the TUI's own kernel.
457
+ const listing = deploymentsListSupported(probe.cli);
458
+ /** The read on its way: `{ again }`, `again` once another was asked for meanwhile; or null. */
459
+ let listRead = null;
460
+ const listChange = (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: LIST_CHANGE }, callback);
461
+ function readList() {
462
+ if (ended || !listing) return;
463
+ if (listRead !== null) { listRead.again = true; return; }
464
+ const mine = listRead = { again: false };
465
+ Promise.resolve()
466
+ .then(() => effects.deploymentList(probe.cli, { action: "list" }, { exec: reader.exec, env }))
467
+ .then((answer) => (answer.ok ? { rows: answer.value.rows } : { failure: answer.reason }), () => ({ failure: NOT_ASKED }))
468
+ .then((listed) => {
469
+ listRead = null;
470
+ if (mine.again) readList(); else heard({ listed });
471
+ });
472
+ }
473
+ /** Remove the row the store asked about (`{ path, name }`) from the list: nothing on disk is
474
+ * touched. Its answer goes to the store, which asks for the list again. */
475
+ function removeListed({ path, name }) {
476
+ Promise.resolve()
477
+ .then(() => effects.deploymentList(probe.cli, { action: "remove", path }, { exec: listChange, env }))
478
+ .then((answer) => heard({ removed: { path, name, ok: answer.ok, reason: answer.ok ? null : answer.reason } }), () => heard({ removed: { path, name, ok: false, reason: NOT_ASKED } }));
479
+ }
480
+ /** The deployment the run started in (from where it was started, or `--dir`), added to the list
481
+ * once, as the TUI's: best effort. A failure opens nothing less, and is said once, in the line
482
+ * under the sidebar's title. A row opened from the switcher is on the list already. */
483
+ function listStart(path) {
484
+ if (!listing) return;
485
+ Promise.resolve()
486
+ .then(() => effects.deploymentList(probe.cli, { action: "add", path, via: "tui" }, { exec: listChange, env }))
487
+ .then((answer) => { if (!answer.ok) heard({ notListed: answer.reason }); }, () => heard({ notListed: NOT_ASKED }));
488
+ }
489
+
420
490
  /** What the boundary admits a request of deployment `id` against, read at every admission. */
421
491
  const contextOf = (id) => actContext(state, id, clock());
422
492
  /** Open the shared confirmation of a stop or a retire the store decided on (`{ n, verb, row,
@@ -558,20 +628,26 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
558
628
  if (keys !== null && keys !== keysTo) { panel.focus(keys); keysTo = keys; }
559
629
  }
560
630
  /** The frame for the state now, with what the loop needs of it: the layout first, because the
561
- * model's window is as tall, and its sentences as wide, as the list pane it gives. The switcher
562
- * takes the whole body and has no notice of a deployment. The last captures of the displayed
563
- * tabs go with the model: they are the panel's, not the store's. */
631
+ * model's window is as tall, and its sentences as wide, as the sidebar's list it gives, and an
632
+ * overlay's window as tall as the area it gives (`body`). The open view of the sidebar is the
633
+ * one under the help or a confirmation; the switcher opens none and has no notice of a
634
+ * deployment. The last captures of the displayed tabs go with the model: they are the panel's,
635
+ * not the store's. */
564
636
  function composed() {
565
- const { size, g, m } = modelled();
566
- return { size, g, made: frame(m, size) };
637
+ const { size, g, m, area } = modelled();
638
+ return { size, g, area, made: frame(m, size) };
567
639
  }
640
+ /** The model for the state and the size now, and the width of the main area (`area`,
641
+ * views/frame.mjs mainArea), which the switcher stands in: the lines above its choices wrap to it. */
568
642
  function modelled() {
569
643
  const size = guard.size(), at = clock();
570
- const listing = (state.view === "help" ? state.back : state.view) === "switcher";
571
- const r = listing ? { notice: null, note: null, observed: true } : roster(state, at);
572
- const g = layout(r.notice, size, { observed: r.observed, note: r.note, ascii: state.ascii, outcome: listing ? null : outcomeOf(state), terminal: state.tabs.length > 0 });
573
- const m = { ...model(state, { page: g.page, now: now(), at, cols: g.listCols }), screen: screens.get(state.terminal?.id) ?? null, screens };
574
- return { size, g, m };
644
+ const under = state.view === "help" || state.view === "act" ? state.back : state.view;
645
+ const listing = under === "switcher";
646
+ const r = listing ? { notice: null, note: null } : roster(state, at);
647
+ const g = layout(r.notice, size, { note: r.note, ascii: state.ascii, outcome: listing ? null : outcomeOf(state), terminal: state.tabs.length > 0, open: listing ? null : under });
648
+ const area = mainArea(g, size.cols).cols;
649
+ const m = { ...model(state, { page: g.page, body: g.body, now: now(), at, cols: g.listCols, area }), screen: screens.get(state.terminal?.id) ?? null, screens };
650
+ return { size, g, m, area };
575
651
  }
576
652
  /** Where the panel stands for the state and the size now, as the Instances view gives it with
577
653
  * the terminal's focus (views/frame.mjs panelPlace): measured whatever is drawn over it, and
@@ -620,8 +696,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
620
696
  const guard = createGuard({
621
697
  stdin, stdout, proc, setTimer, clearTimer,
622
698
  frame() {
623
- const { size, g, made } = composed();
624
- drawn = { page: made.page, extent: made.extent, room: made.room, cols: g.listCols };
699
+ const { size, g, area, made } = composed();
700
+ drawn = { page: made.page, extent: made.extent, room: made.room, cols: g.listCols, area };
625
701
  fitPanel(made);
626
702
  const bytes = screen.render(made.rows, size, { full, cursor: made.cursor });
627
703
  full = false;
@@ -696,6 +772,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
696
772
 
697
773
  guard.start();
698
774
  guard.attempt(() => { if (!ended) Promise.resolve(reader.start()).catch(() => {}); });
775
+ if (found.ok) guard.attempt(() => { if (!ended) listStart(found.deployment); });
699
776
  guard.attempt(() => guard.draw());
700
777
  // Once a run, after the first frame: what runs that are gone left of their private servers
701
778
  // (lib/panel.mjs sweep, which signals nothing and removes only what it can prove is dead).
@@ -707,7 +784,7 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
707
784
  // One line per change still running, to a terminal or a file only; the status never depends on it.
708
785
  const running = reader.changes?.() ?? [];
709
786
  if (running.length && effects.tellable(stderr)) {
710
- try { stderr.write(running.map(({ label }) => `${ACT_WORDS.leaving(label?.verb ?? "change", displayLine(label?.name) ?? "an instance")}\n`).join("")); } catch { /* nothing to tell it to */ }
787
+ try { stderr.write(running.map(({ label }) => `${label === LIST_CHANGE ? LIST_WORDS.leaving : ACT_WORDS.leaving(label?.verb ?? "change", displayLine(label?.name) ?? "an instance")}\n`).join("")); } catch { /* nothing to tell it to */ }
711
788
  }
712
789
  if (end.error !== undefined) stderr.write(`oats: \`oats tui\` stopped on an internal error; the terminal was restored\n${errorLines(end.error).map((line) => ` ${line}\n`).join("")}`);
713
790
  return end.status;