@awebai/oats 0.64.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 (36) hide show
  1. package/bin/oats.mjs +101 -4
  2. package/docs/desktop-cli-api.md +84 -2
  3. package/docs/desktop.md +14 -5
  4. package/docs/implementation.md +17 -3
  5. package/docs/release-notes/v0.65.0.md +187 -0
  6. package/docs/tui.md +416 -238
  7. package/docs/upgrading.md +1 -1
  8. package/docs/workspaces.md +124 -0
  9. package/lib/core.mjs +14 -4
  10. package/lib/deployments.mjs +325 -0
  11. package/lib/resolved-deployment.mjs +37 -0
  12. package/lib/workspace.mjs +2 -0
  13. package/package.json +1 -1
  14. package/packages/client/cli-locator.mjs +2 -2
  15. package/packages/client/deployment-label.mjs +2 -2
  16. package/packages/client/deployment-list-cli.mjs +98 -0
  17. package/packages/client/deployment-list.mjs +91 -0
  18. package/packages/client/keymap.mjs +106 -0
  19. package/packages/client/own-codes.mjs +2 -0
  20. package/packages/client/panel-views.mjs +1 -1
  21. package/packages/client/workspace-admission.mjs +2 -1
  22. package/packages/tui/README.md +4 -4
  23. package/packages/tui/lib/actions.mjs +29 -5
  24. package/packages/tui/lib/client.mjs +3 -1
  25. package/packages/tui/lib/config.mjs +21 -14
  26. package/packages/tui/lib/main.mjs +108 -31
  27. package/packages/tui/lib/model.mjs +71 -41
  28. package/packages/tui/lib/read.mjs +15 -45
  29. package/packages/tui/lib/store.mjs +158 -39
  30. package/packages/tui/lib/term/through.mjs +40 -18
  31. package/packages/tui/lib/views/act.mjs +17 -13
  32. package/packages/tui/lib/views/frame.mjs +418 -421
  33. package/packages/tui/lib/views/help.mjs +41 -19
  34. package/packages/tui/lib/views/instances.mjs +38 -9
  35. package/packages/tui/lib/views/switcher.mjs +65 -21
  36. package/skills/oats-getting-started/SKILL.md +6 -4
@@ -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;
@@ -21,6 +21,7 @@ import { ownEllipsis, shownLines } from "./term/text.mjs";
21
21
  import { textWidth } from "./term/width.mjs";
22
22
  import { windowOf } from "./views/scroll.mjs";
23
23
  import { SOUL_COLOURS } from "./views/souls.mjs";
24
+ import { leadRows } from "./views/switcher.mjs";
24
25
 
25
26
  /** The widest the word column of the list may be, in cells. */
26
27
  export const WORD_MAX = 20;
@@ -165,7 +166,7 @@ function build(state, at) {
165
166
  const heading = (deployment, label, path = null) => {
166
167
  const its = deploymentState(deployment), up = its.key === "live";
167
168
  // A machine's rows are what it reported at the last roster read: that time stands on its
168
- // heading only when the header's time is another, so the heading of a machine read with
169
+ // heading only when the time of this read (the help's top row) is another, so the heading of a machine read with
169
170
  // this one is its name alone. A deployment that is not live has its state and short reason
170
171
  // in the shared words instead, and no time.
171
172
  const read = up && deployment.local === false ? clockTime(state.rosterAt) : null;
@@ -215,7 +216,7 @@ function build(state, at) {
215
216
  // machine is in it: both read from the shared entries (`local`), never decided here.
216
217
  const away = [...new Set(deployments.filter((d) => d.local === false && text(d.machine)).map((d) => d.machine))];
217
218
  const machines = away.length, here = deployments.some((d) => d.local === true);
218
- // Whether a list stands under the header: not for a deployment of this machine that was never
219
+ // Whether a list stands in the sidebar: not for a deployment of this machine that was never
219
220
  // observed, nor for a machine that is not live and has no row kept. Each has only its reason.
220
221
  const observed = panel !== null && !gone && (local ? status === "observed" : live || instances.length > 0);
221
222
  return {
@@ -283,7 +284,7 @@ function flatten(base, cols, ascii) {
283
284
  * they changed. The flattening for the last width asked is kept beside it. */
284
285
  const MADE_FROM = ["entries", "remote", "memory", "notes", "rosterAt", "collecting", "ctxs", "open", "collapsed", "cli", "home", "retiring", "ascii"];
285
286
  let kept = null;
286
- /** The roster of a state: the rows in drawn order and what the header says, for a list pane
287
+ /** The roster of a state: the rows in drawn order and what the sidebar's title says, for a list pane
287
288
  * `cols` wide. Only `items` and `index` depend on the width; `rows`, the instances in drawn
288
289
  * order, do not. `at` stamps a machine's panel before any roster outcome was taken, which
289
290
  * never shows; it is passed on. */
@@ -502,17 +503,39 @@ function detailOf(state, r, item, now, acts) {
502
503
  return { title: row.instance, facts };
503
504
  }
504
505
 
505
- /** The heading of the deployments in `~/Agents` that are not served yet: the TUI's own. */
506
+ /** The heading of the rows of this computer's deployments list that this run does not serve: the TUI's own. */
506
507
  export const OFFERED_SECTION = "On this machine, not opened";
507
- export const MORE_FOLDERS = "More folders than are listed here.";
508
+
509
+ /** The words of this computer's deployments list (awebai/oats#1390) where they are a line of their
510
+ * own: the add of the deployment the run started in, when it failed (the line under the sidebar's title,
511
+ * once; the kernel's message says what to do, and is shown as it came), and a change to the list
512
+ * still running as the TUI leaves. */
513
+ export const LIST_WORDS = Object.freeze({
514
+ notAdded: (message) => Object.freeze([{ own: "This deployment was not added to this computer's list: " }, { shown: message }]),
515
+ /** An add or a remove still running as the TUI leaves: one line, after the screen is left. */
516
+ leaving: "oats: a change to this computer's list of deployments is still running; `oats deployments` shows the list.",
517
+ });
518
+
519
+ /** What the switcher says above its rows, as views/switcher.mjs leadRows reads it. */
520
+ const leadOf = (state) => ({ said: state.switcher.line, failure: state.listed.failure?.message ?? null, removing: state.switcher.removing !== null });
521
+ /** How many rows stand above the switcher's choices in an area `cols` wide (the switcher's is the
522
+ * whole width): what happened (`line`), that the last read of the list failed, and a Remove
523
+ * asked, as views/switcher.mjs leadRows draws them. The window of the choices is that much
524
+ * shorter, so none is hidden for them. */
525
+ export function switcherLead(state, cols) {
526
+ return leadRows(leadOf(state), Number.isInteger(cols) && cols > 0 ? cols : 80, { ascii: state.ascii }).length;
527
+ }
508
528
 
509
529
  /** The switcher's rows for a state, top to bottom: the workspaces this run can show, as the
510
530
  * shared home lists and words them; then the ones matched to no workspace under the shared
511
- * heading; then the deployments of `~/Agents` that are not served, under the TUI's own.
512
- * An item is `{ heading, shared }`, `{ own }`, or a choice: `{ key, label, place, notLiveText,
513
- * open, primary }` for a view (`primary` is the deployment Enter opens) and `{ key, label, place,
514
- * path, refused }` for an offered folder. `keys` are the choices in order; `selected` is the
515
- * key the selection stands on (the first choice when the state's own is not listed). */
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). */
516
539
  export function switcher(state, at = new Date(0).toISOString()) {
517
540
  const held = heldOf(state, at), views = viewModel(held, TERMS);
518
541
  const rows = workspaceChoiceRows(workspaceChoices(held, TERMS, views));
@@ -524,17 +547,17 @@ export function switcher(state, at = new Date(0).toISOString()) {
524
547
  });
525
548
  const shown = rows.filter((row) => choiceMatches(row, query));
526
549
  const matched = shown.filter((row) => !row.unattached).map(choice), unmatched = shown.filter((row) => row.unattached).map(choice);
527
- const offered = state.offered.offered
528
- .map(({ path, name }) => ({ key: `path\u0000${path}`, label: name, place: shortPath(path, { home: state.home }), path, refused: state.switcher.refused === path }))
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 }))
529
553
  .filter((item) => choiceMatches(item, query));
530
554
  const items = [
531
555
  ...matched,
532
556
  ...(unmatched.length ? [{ heading: UNMATCHED_SECTION, shared: true }, ...unmatched] : []),
533
557
  ...(offered.length ? [{ heading: OFFERED_SECTION, shared: false }, ...offered] : []),
534
- ...(state.offered.limited ? [{ own: MORE_FOLDERS }] : []),
535
558
  ];
536
559
  const keys = items.filter((item) => item.key !== undefined).map((item) => item.key);
537
- const total = rows.length + state.offered.offered.length;
560
+ const total = rows.length + unserved.length;
538
561
  return {
539
562
  items, keys, selected: keys.includes(state.switcher.selected) ? state.switcher.selected : keys[0] ?? null,
540
563
  empty: keys.length ? null : total ? "nomatch" : "none",
@@ -632,19 +655,29 @@ function paletteView(state, page, at) {
632
655
  };
633
656
  }
634
657
 
658
+ /** The rows the switcher's window has in an area `body` rows tall and `cols` wide: the lines above
659
+ * the choices take theirs (switcherLead), and the filter field one while it is typed or kept
660
+ * (views/frame.mjs). */
661
+ export const switcherHeight = (state, body, cols) => Math.max(1, body - switcherLead(state, cols) - (state.switcher.editing || state.switcher.query ? 1 : 0));
662
+
635
663
  /** What the views draw for a state. For the Instances view, in a list pane `page` rows tall and
636
- * `cols` wide: the header's facts, the rows of the window with their marks, and the selected
637
- * instance's detail. For the switcher, in a pane `page` rows tall: the window of its rows. Only
638
- * the rows in the pane are worked out. */
639
- export function model(state, { page, now, at, cols }) {
664
+ * `cols` wide: the title's facts, the rows of the window with their marks, and the selected
665
+ * instance's detail; the Souls and the Capabilities views' lists in the same pane, also under the
666
+ * help, which leaves the sidebar beside it (views/frame.mjs). For the switcher, the palette and
667
+ * the spawn prompt, in an area `body` rows tall (`page` when none is given): the window of their
668
+ * rows; `area` is the main area's width (`cols` when none is given), which the lines above the
669
+ * switcher's choices wrap to (views/frame.mjs mainArea). Only the rows in the pane are worked out. */
670
+ export function model(state, { page, body = page, now, at, cols, area = cols }) {
640
671
  const r = roster(state, at, cols);
672
+ // The view under the help, or under a confirmation, decides what the sidebar says.
673
+ const under = state.view === "help" || state.view === "act" ? state.back : state.view;
641
674
  const common = {
642
675
  view: state.view, focus: state.focus, ascii: state.ascii, actions: state.actions,
643
676
  // The filter of the view shown: the Souls view has one of its own.
644
677
  filter: state.view === "souls" ? state.souls.filter : state.view === "capabilities" ? state.capabilities.filter : state.filter,
645
678
  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,
646
679
  detailTop: state.detailTop, helpTop: state.helpTop, open: state.open !== null,
647
- detachKey: state.detachKey, opening: state.opening, openable: false, actable: [],
680
+ detachKey: state.detachKey, opening: state.opening, openable: false,
648
681
  terminal: state.terminal, onTerminal: false,
649
682
  // The panel's groups (views/frame.mjs), the split and the focused group; the panel stands while
650
683
  // any tab is open. `tabs` is the focused group's strip: each tab in order, the shown one marked,
@@ -652,35 +685,35 @@ export function model(state, { page, now, at, cols }) {
652
685
  split: state.split, group: state.group, panelOpen: state.tabs.length > 0, groups: groupsOf(state),
653
686
  tabs: groupsOf(state)[state.group].tabs,
654
687
  act: state.view === "act" && state.act ? actView(state) : null,
655
- // The leader waits for its key (the footer is its hint), and the palette, while it is open.
656
- leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, page, at),
657
- souls: state.view === "souls" ? soulsView(state, page, at) : null,
658
- capabilities: state.view === "capabilities" ? capabilitiesView(state, page, at) : null,
659
- spawn: state.spawn === null ? null : spawnView(state, page, at),
660
- // The line above the panes: the last outcome, else a spawn under way (outcomeOf).
688
+ // The leader waits for its key (the cheat sheet is its hint), and the palette, while it is open.
689
+ leader: state.leader?.waiting === true, palette: state.palette === null ? null : paletteView(state, body, at),
690
+ souls: under === "souls" ? soulsView(state, page, at) : null,
691
+ capabilities: under === "capabilities" ? capabilitiesView(state, page, at) : null,
692
+ spawn: state.spawn === null ? null : spawnView(state, body, at),
693
+ // The line under the sidebar's title: the last outcome, else a spawn under way (outcomeOf).
661
694
  outcome: outcomeOf(state),
662
695
  };
663
- // The view under the help, or under a confirmation, decides what the header says.
664
- const under = state.view === "help" || state.view === "act" ? state.back : state.view;
665
696
  if (under === "switcher") {
666
697
  const s = switcher(state, at);
667
698
  const at_ = s.selected === null ? -1 : s.items.findIndex((item) => item.key === s.selected);
668
- // The line that says what happened to the open workspace stands above the rows and takes one
669
- // of the pane's: the window is that much shorter, so no choice is hidden for it.
670
- const win = windowOf({ top: state.switcher.top, count: s.items.length, height: Math.max(1, page - (state.switcher.line ? 1 : 0)), keep: state.switcher.loose ? -1 : at_ });
699
+ // The lines above the rows take the pane's rows, and so does the filter field while it is
700
+ // typed or kept: the window is that much shorter, so no choice is hidden for them (switcherHeight).
701
+ const win = windowOf({ top: state.switcher.top, count: s.items.length, height: switcherHeight(state, body, area), keep: state.switcher.loose ? -1 : at_ });
671
702
  return {
672
703
  ...common, under, list: [], above: 0, below: 0, wordWidth: 0, detail: null,
673
- // Nothing of a workspace stands in the header while the switcher is shown.
704
+ // Nothing of a workspace stands in the sidebar while the switcher is shown.
674
705
  workspace: "", machines: 0, here: false, machine: null, counts: [], readAt: null, notice: null, note: null, empty: null, observed: true, outcome: null,
675
706
  filter: Object.freeze({ editing: state.switcher.editing, query: state.switcher.query }),
676
707
  switcher: {
677
708
  rows: s.items.slice(win.top, win.top + win.size).map((item) => (item.key === undefined ? item : { ...item, selected: item.key === s.selected })),
678
- above: win.above, below: win.below, empty: s.empty, said: state.switcher.line,
709
+ above: win.above, below: win.below, empty: s.empty, ...leadOf(state),
710
+ // Whether the remove key acts on the selected row: a row of the list (the cheat sheet names it then).
711
+ removable: s.items.some((item) => item.key === s.selected && item.path !== undefined),
679
712
  },
680
713
  };
681
714
  }
682
715
  const selected = state.selected === null ? -1 : r.index.get(state.selected) ?? -1;
683
- // What the detail, the footer and Enter read of the selected row is worked out once per paint.
716
+ // What the detail and Enter read of the selected row is worked out once per paint.
684
717
  const row = selected >= 0 ? r.items[selected].row : null, acts = row ? instanceActs(row) : null;
685
718
  const decision = row ? openDecision(state, row, acts) : null;
686
719
  // The window holds the selection, unless the list was scrolled away from it on purpose.
@@ -693,10 +726,6 @@ export function model(state, { page, now, at, cols }) {
693
726
  // Enter opens the selected agent's terminal now, or (`onTerminal`) goes to the one open on it.
694
727
  openable: decision?.open === true && state.opening === null,
695
728
  onTerminal: row !== null && state.terminal !== null && state.terminal.id === instanceId(row),
696
- // The acts whose key opens a confirmation now, read from the same instanceActs answer: the
697
- // footer names them. A key not named still answers, with the line that says why. A secondary
698
- // act (Retire while a retire runs) opens on its key and is not named.
699
- actable: row && state.opening === null ? ACT_VERBS.filter((verb) => !acts.acts.some((each) => each.verb === verb && each.secondary) && actDecision(state, row, acts, verb).open) : [],
700
729
  switcher: null,
701
730
  };
702
731
  }
@@ -722,7 +751,7 @@ export function localDeployments(state, at) {
722
751
  return heldDeployments(held).filter((w) => !w.remote).map((w) => ({ id: w.id, remote: false, instances: rowsOf(held, w.id) }));
723
752
  }
724
753
 
725
- /** The four acts on an instance, in the order the help, the footer and the keys know them. */
754
+ /** The four acts on an instance, in the order the help, the palette and the keys know them. */
726
755
  export const ACT_VERBS = Object.freeze(["stop", "retire", "start", "restart"]);
727
756
  const DONE = Object.freeze({ stop: "stopped", retire: "retired", start: "started", restart: "restarted" });
728
757
  /** The TUI's own words around the acts (docs/tui.md, "Stopping, starting, restarting and
@@ -763,7 +792,7 @@ export function buttonLabel(offer, verb, phase) {
763
792
  export const BUTTON_ORDER = Object.freeze(["close", "refresh", "check-again", "apply"]);
764
793
 
765
794
  /** Whether an act key on `row` opens a confirmation, and what the line says when it does not.
766
- * `acts` is the row's instanceActs answer, read once per paint (the footer) or per key, as
795
+ * `acts` is the row's instanceActs answer, read once per paint (the palette) or per key, as
767
796
  * openDecision reads it; nothing here decides which acts a row has.
768
797
  * { open: true, verb, id, name, kind, machine, label, home } a confirmation opens: `kind`
769
798
  * "lifecycle" for stop and retire (the shared confirmation), "start" for the TUI's own
@@ -968,7 +997,8 @@ function soulsView(state, page, at) {
968
997
  // Nothing held: the first read is in flight (or the deployment not read yet), or it failed.
969
998
  return reason && !s.held.reading ? { ...base, state: "failed", failure: soulCatalogFailure(reason) } : { ...base, state: "reading" };
970
999
  }
971
- const heading = reason ? { label: "Souls", path: null, state: null, short: soulCatalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
1000
+ // A failed re-read's heading: the accordion's row above it names the view, so it has no word of its own.
1001
+ const heading = reason ? { label: "", path: null, state: null, short: soulCatalogFailure(reason), readAt: clockTime(entry.observedAt) } : null;
972
1002
  const state_ = !s.all.length ? "none" : !s.rows.length ? "nomatch" : "rows";
973
1003
  const height = Math.max(1, page - (heading ? 1 : 0));
974
1004
  const at_ = s.selected ? s.rows.indexOf(s.selected) : -1;
@@ -1080,7 +1110,7 @@ function capabilitiesView(state, page, at) {
1080
1110
  if (!c.local) return { ...base, state: "none" };
1081
1111
  const entry = c.held?.entry ?? null, reason = entry?.reason ?? null;
1082
1112
  if (!c.listed) return reason && !c.held.reading ? { ...base, state: "failed", failure: catalogFailure("capabilities", reason) } : { ...base, state: "reading" };
1083
- const heading = c.heading ? { label: "Capabilities", path: null, state: null, short: catalogFailure("capabilities", reason), readAt: clockTime(entry.observedAt) } : null;
1113
+ const heading = c.heading ? { label: "", path: null, state: null, short: catalogFailure("capabilities", reason), readAt: clockTime(entry.observedAt) } : null;
1084
1114
  const state_ = !c.all.length ? "none" : !c.keys.length ? "nomatch" : "rows";
1085
1115
  const at_ = c.items.findIndex((item) => item.key !== undefined && item.key === c.selected);
1086
1116
  const win = windowOf({ top: v.top, count: c.items.length, height: capabilitiesHeight(c, page), keep: v.loose ? -1 : at_ });
@@ -11,11 +11,11 @@
11
11
  // functions (client.mjs), which decide what a roster, a row and a failed read are, once, for both
12
12
  // clients: the TUI never writes "stopped" for a row and never builds the collector's input by hand.
13
13
  import { execFile as nodeExecFile, spawn as nodeSpawn } from "node:child_process";
14
- import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, opendirSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
14
+ import { closeSync, fstatSync, lstatSync, mkdtempSync, openSync, readSync, realpathSync, rmdirSync, statSync, unlinkSync } from "node:fs";
15
15
  import { tmpdir } from "node:os";
16
- import { basename, dirname, join } from "node:path";
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, deploymentsInside, failedEntry, livenessAnswers, livenessInput, mapBounded, observeIdentities, observedEntry, panelInstances, parseProbeStdout, remoteRosterState, rosterRows, validateWorkspace } from "./client.mjs";
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";
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. */
@@ -61,26 +61,13 @@ export function leaveInstance(env) {
61
61
  /** A step that must not stop the ones after it: a child, a stream or a directory that is already gone. */
62
62
  const quietly = (act) => { try { return act(); } catch { return undefined; } };
63
63
 
64
- /** The filesystem the three functions below read when they are given none. findDeployment: one
64
+ /** The filesystem the two functions below read when they are given none. findDeployment: one
65
65
  * realpath and one stat of the start, then one lstat per directory. A symbolic link named
66
- * oats-local.yaml is not a deployment's file (lstat does not follow it).
67
- * `list(dir, limit)` is the look inside a folder the shared deploymentsInside asks for:
68
- * -> { entries: [{ name, isDirectory }], limited }. It reads at most `limit` entries, and one more
69
- * only to say whether the folder holds more (`limited`), so a folder of any size costs a bounded
70
- * read. `isDirectory` is the entry's own type: a link to a directory is not a directory, and
71
- * nothing is followed. It throws for a folder that cannot be opened; the shared function answers
72
- * that as a folder that holds nothing. */
66
+ * oats-local.yaml is not a deployment's file (lstat does not follow it). */
73
67
  const DEPLOYMENT_IO = Object.freeze({
74
68
  realpath: (path) => realpathSync(path),
75
69
  isDirectory: (path) => statSync(path).isDirectory(),
76
70
  isDeployment: (dir) => lstatSync(join(dir, "oats-local.yaml")).isFile(),
77
- list: (dir, limit) => {
78
- const handle = opendirSync(dir), entries = [];
79
- try {
80
- for (let entry; entries.length < limit && (entry = handle.readSync());) entries.push({ name: entry.name, isDirectory: entry.isDirectory() });
81
- return { entries, limited: entries.length >= limit && handle.readSync() !== null };
82
- } finally { quietly(() => handle.closeSync()); }
83
- },
84
71
  });
85
72
 
86
73
  /** The deployment `start` is in: (start directory, io?) -> { ok: true, deployment } | { ok: false, dir }.
@@ -102,34 +89,9 @@ export function findDeployment(start, io = {}) {
102
89
  }
103
90
  }
104
91
 
105
- /** The deployments the switcher offers unasked: those directly inside `<home>/Agents` that this run
106
- * does not serve. (home, served, io?) -> { offered: [{ path, name }], limited }.
107
- * Which folders are deployments, their order and the limit of the look are the shared
108
- * deploymentsInside's; this adds only what a run knows. Each path is made canonical (io.realpath)
109
- * BEFORE it is compared with `served`, whose ids are canonical: a `~/Agents` reached through a
110
- * link would otherwise offer a deployment the run already shows. One that cannot be resolved (it
111
- * went away since the look) is left out, and so is a second folder that leads to the same place.
112
- * `name` is the folder's name as it was listed, `path` the canonical one to admit. `limited` says
113
- * the folder holds more entries than were read. Nothing is read from any deployment: an offered
114
- * one is read when it is picked. Never throws: a missing or unreadable `~/Agents` offers nothing. */
115
- export function offeredDeployments(home, served, io = {}) {
116
- try {
117
- const { realpath, isDeployment, list } = { ...DEPLOYMENT_IO, ...io };
118
- const inside = deploymentsInside(join(home, "Agents"), { list, isDeployment });
119
- const taken = new Set(served), offered = [];
120
- for (const listed of inside.paths) {
121
- const path = quietly(() => realpath(listed));
122
- if (typeof path !== "string" || taken.has(path)) continue;
123
- taken.add(path);
124
- offered.push({ path, name: basename(listed) });
125
- }
126
- return { offered, limited: inside.limited };
127
- } catch { return { offered: [], limited: false }; }
128
- }
129
-
130
92
  /** Whether `path` is a deployment NOW: (path, io?) -> { ok: true, deployment } | { ok: false }.
131
- * Asked when an offered deployment is picked: the offer is as old as the last look, and the
132
- * folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
93
+ * Asked when a row of this computer's deployments list is picked: the row is as old as the last
94
+ * read of the list, and the folder may have stopped being a deployment since. The path is made canonical (io.realpath) and
133
95
  * the shared validateWorkspace is asked about that directory itself. Unlike findDeployment it
134
96
  * walks nowhere: a folder that is no longer a deployment must not open the one above it in its
135
97
  * place. `deployment` is the canonical path, the id a served deployment has. Never throws. */
@@ -167,6 +129,14 @@ export function probeKernel({ bin = KERNEL_BIN, env = process.env, execFile = no
167
129
  });
168
130
  }
169
131
 
132
+ /** The exec of the one kernel call made before the terminal is taken but the probe: the read of
133
+ * this computer's deployments list at a start outside every deployment (the shared
134
+ * cliDeploymentList's `io.exec`). execFile's signature for `node <bin> <argv…>`, as the probe
135
+ * runs the kernel, and NOT detached, as the probe is not: a Ctrl+C then ends it with the TUI. */
136
+ export function startExec(bin, argv, options, callback) {
137
+ return nodeExecFile(process.execPath, [bin, ...argv], options, callback);
138
+ }
139
+
170
140
  /** Where a change's output goes (createReader `files`). `dir()` makes the run's private directory
171
141
  * (mkdtemp: mode 0700, under the OS temp dir); `open` makes one file in it for the child alone
172
142
  * (0600, refused if it is there); `read(path, max)` reads back at most `max` bytes and one more,