@awebai/oats 0.57.1 → 0.59.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 (61) hide show
  1. package/bin/oats.mjs +24 -11
  2. package/docs/configuration.md +2 -1
  3. package/docs/desktop-cli-api.md +105 -17
  4. package/docs/desktop.md +30 -3
  5. package/docs/execution-targets.md +15 -0
  6. package/docs/implementation.md +2 -0
  7. package/docs/integrations.md +2 -2
  8. package/docs/knowledge.md +4 -4
  9. package/docs/official-catalog.md +4 -4
  10. package/docs/packages.md +14 -14
  11. package/docs/release-notes/v0.58.0.md +107 -0
  12. package/docs/release-notes/v0.59.0.md +288 -0
  13. package/docs/servers.md +4 -1
  14. package/docs/souls-and-instances.md +30 -0
  15. package/docs/tui.md +653 -117
  16. package/docs/workspaces.md +2 -2
  17. package/lib/core.mjs +227 -46
  18. package/lib/read-ahead-worker.mjs +119 -0
  19. package/lib/read-ahead.mjs +115 -0
  20. package/lib/retire-state.mjs +33 -0
  21. package/lib/servers.mjs +9 -1
  22. package/lib/session-input.mjs +14 -4
  23. package/package-catalog.json +3 -3
  24. package/package.json +1 -1
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/deployment-data.mjs +4 -0
  27. package/packages/client/deployment-panel.mjs +3 -0
  28. package/packages/client/instance-acts.mjs +23 -8
  29. package/packages/client/instance-presentation.mjs +3 -2
  30. package/packages/client/instance-tree.mjs +84 -39
  31. package/packages/client/lifecycle-confirmation.mjs +9 -3
  32. package/packages/client/panel-views.mjs +1 -1
  33. package/packages/client/remote-roster.mjs +4 -1
  34. package/packages/client/retire-in-flight.mjs +65 -0
  35. package/packages/client/retire-state.mjs +30 -0
  36. package/packages/client/spawn-apply-cli.mjs +8 -2
  37. package/packages/client/spawn-apply.mjs +20 -7
  38. package/packages/client/spawn-preview-cli.mjs +2 -1
  39. package/packages/client/spawn-preview.mjs +30 -18
  40. package/packages/record/lib/directory-identity.mjs +14 -0
  41. package/packages/record/lib/native-history.mjs +6 -5
  42. package/packages/tui/README.md +23 -10
  43. package/packages/tui/lib/actions.mjs +63 -5
  44. package/packages/tui/lib/client.mjs +12 -1
  45. package/packages/tui/lib/config.mjs +7 -2
  46. package/packages/tui/lib/main.mjs +315 -82
  47. package/packages/tui/lib/model.mjs +523 -56
  48. package/packages/tui/lib/panel.mjs +519 -144
  49. package/packages/tui/lib/read.mjs +52 -26
  50. package/packages/tui/lib/store.mjs +908 -65
  51. package/packages/tui/lib/term/keys.mjs +9 -2
  52. package/packages/tui/lib/term/text.mjs +4 -0
  53. package/packages/tui/lib/term/through.mjs +12 -1
  54. package/packages/tui/lib/views/frame.mjs +394 -95
  55. package/packages/tui/lib/views/help.mjs +54 -13
  56. package/packages/tui/lib/views/instances.mjs +43 -25
  57. package/packages/tui/lib/views/palette.mjs +61 -0
  58. package/packages/tui/lib/views/souls.mjs +268 -0
  59. package/packages/tui/lib/views/spawn.mjs +299 -0
  60. package/packages/tui/lib/views/split.mjs +29 -0
  61. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -6,6 +6,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "nod
6
6
  import { isDeepStrictEqual } from "node:util";
7
7
  import { isUtf8 } from "node:buffer";
8
8
  import { nativeLaunchLocations } from "./session-roots.mjs";
9
+ import { sameDirectory } from "./directory-identity.mjs";
9
10
 
10
11
  function canonical(home) {
11
12
  try { return realpathSync(home); }
@@ -215,7 +216,7 @@ function validateReceipt(row, home, id) {
215
216
  function validateWitness(row, rows) {
216
217
  const witness = row.rootWitness, establishing = witness && rows.get(witness.establishedBy.nativeRecordId);
217
218
  if (!establishing || establishing.version !== 2 || !["root-established", "started"].includes(establishing.state) || establishing.home !== row.home || establishing.incarnationId !== row.incarnationId || establishing.rootWitness?.establishedBy.nativeRecordId !== establishing.id || !isDeepStrictEqual(establishing.intent, witness.establishedBy.intent) || !isDeepStrictEqual(establishing.rootWitness, witness)) custodyError("original establishing receipt is missing or contradictory");
218
- if (!isDeepStrictEqual(directoryIdentity(row.proposedRoot), witness.identity)) custodyError("original Pi session directory was replaced");
219
+ if (!sameDirectory(witness.identity, directoryIdentity(row.proposedRoot))) custodyError("original Pi session directory was replaced");
219
220
  }
220
221
  function selection(home, authority, withIntent = false, creating = false) {
221
222
  closed(authority, ["incarnationId", "sessionDir", ...(withIntent ? ["intent"] : []), ...(creating ? ["assertAuthority"] : [])]);
@@ -266,7 +267,7 @@ export function prepareCapturedPiStart(home, authority) {
266
267
  authority.assertAuthority();
267
268
  for (const [path, identity] of directories) if (!isDeepStrictEqual(directoryIdentity(path), identity)) custodyError("original native custody parent changed");
268
269
  for (const [id, row] of rows) if (!isDeepStrictEqual(privateJson(join(history, id + ".json")), row)) custodyError("original native receipt changed during preparation");
269
- if (witness && !isDeepStrictEqual(directoryIdentity(authority.sessionDir), witness.identity)) custodyError("original root changed during preparation");
270
+ if (witness && !sameDirectory(witness.identity, directoryIdentity(authority.sessionDir))) custodyError("original root changed during preparation");
270
271
  };
271
272
  const id = randomUUID(), pending = { version: 2, id, home, runtime: "pi", incarnationId: authority.incarnationId, intent: structuredClone(authority.intent), state: "pending", proposedRoot: authority.sessionDir, rootWitness: structuredClone(witness) };
272
273
  const claimed = validateManifest({ version: 2, home, completeHistory: header.completeHistory, capturedPi: { incarnationId: authority.incarnationId, nativeRecordIds: [...(header.capturedPi?.nativeRecordIds ?? []), id] } }, home);
@@ -282,7 +283,7 @@ export function prepareCapturedPiStart(home, authority) {
282
283
  const identity = directoryIdentity(authority.sessionDir); syncDirectory(dirname(authority.sessionDir)); claimCheck();
283
284
  established = { schemaVersion: 1, profile: "pi-zero-print-1", path: authority.sessionDir, identity, establishedBy: { nativeRecordId: id, intent: structuredClone(authority.intent) } };
284
285
  }
285
- const guard = () => { claimCheck(); if (!isDeepStrictEqual(directoryIdentity(authority.sessionDir), established.identity)) custodyError("captured root changed during establishment"); };
286
+ const guard = () => { claimCheck(); if (!sameDirectory(established.identity, directoryIdentity(authority.sessionDir))) custodyError("captured root changed during establishment"); };
286
287
  publishCaptured(home, { ...pending, state: "root-established", rootWitness: established }, pending, guard);
287
288
  inventory(home); // no unlisted/unfinished writes may be ignored before return
288
289
  return id;
@@ -310,7 +311,7 @@ function recordCapturedPiStart(home, id, runtime, args, env) {
310
311
  if (!isDeepStrictEqual(protectedManifest(home), header)) custodyError("expected-ID claim changed before execution");
311
312
  const current = privateJson(join(nativeHistoryPath(home), establish.id + ".json"));
312
313
  if (establish.id !== id && !isDeepStrictEqual(current, establish)) custodyError("establishing receipt changed");
313
- if (!isDeepStrictEqual(directoryIdentity(row.proposedRoot), row.rootWitness.identity)) custodyError("native root changed before execution");
314
+ if (!sameDirectory(row.rootWitness.identity, directoryIdentity(row.proposedRoot))) custodyError("native root changed before execution");
314
315
  };
315
316
  publishCaptured(home, { ...row, state: "started", startedAt: new Date().toISOString(), locations: [row.proposedRoot] }, row, check);
316
317
  }
@@ -344,7 +345,7 @@ export function assertCapturedPiProof(proof, path) {
344
345
  for (let current = path; ; current = dirname(current)) {
345
346
  const stat = physical(current, current !== path);
346
347
  if (current === row.proposedRoot) {
347
- if (!stat.isDirectory() || !isDeepStrictEqual({ dev: stat.dev, ino: stat.ino }, row.rootWitness.identity)) custodyError("native root changed during contained-path validation");
348
+ if (!stat.isDirectory() || !sameDirectory(row.rootWitness.identity, { dev: stat.dev, ino: stat.ino })) custodyError("native root changed during contained-path validation");
348
349
  break;
349
350
  }
350
351
  }
@@ -6,8 +6,8 @@ inside `@awebai/oats` and is never published on its own.
6
6
 
7
7
  **It is a preview.** This version shows a workspace's instances, on this
8
8
  machine and on the other machines registered on it, in one list, follows
9
- them, opens an agent's terminal in a panel beside the list, and stops, starts, restarts and retires an
10
- agent after a confirmation. While it is a preview its screens and its
9
+ them, opens agents' terminals as tabs in a panel beside the list, split in two groups when you want, stops, starts, restarts and retires an
10
+ agent after a confirmation, and spawns an agent on this machine. While it is a preview its screens and its
11
11
  configuration file may change without notice.
12
12
 
13
13
  [`docs/tui.md`](../../docs/tui.md) is the reference: how to start it, what the
@@ -24,9 +24,9 @@ never does.
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the footer and the help read the effective one |
25
25
  | `lib/config.mjs` | `tui.json`: read once, checked, and the effective action table |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
27
- | `lib/panel.mjs` | the open terminal: the run's private tmux server (one control client, one window per viewer), the kernel's `oats session attach` in a pane of it, captures when tmux says the pane changed, keys typed into it, and the sweep of what a dead run left; the only module that runs tmux |
27
+ | `lib/panel.mjs` | the open terminals, as tabs: the run's private tmux server (one control client, one window per tab, up to `MAX_TERMINALS`, each at the size its caller gives), the kernel's `oats session attach` in a pane of each, captures of the displayed tabs only (up to `MAX_SHOWN`, one per group of a split) when tmux says their pane changed, a hidden tab's output marking it, keys typed into the shown tab, and the sweep of what a dead run left; the only module that runs tmux (THE TABS in its header) |
28
28
  | `lib/read.mjs` | the effects of reading: the deployment, the kernel record, the observer of every deployment opened in the run, the roster of other machines (`oats server roster --json`), the refresh loop, the liveness collector, ending every read, the changes (a stop or retire apply, a start or restart: never ended, their output in files of the run's private directory), and the two looks at the file system the switcher needs (the entries of `~/Agents`, and whether a picked folder is a deployment) |
29
- | `lib/store.mjs` | the state and `reduce(state, event)`: pure |
29
+ | `lib/store.mjs` | the state and `reduce(state, event)`: pure. It holds the tabs' order, their groups, the shown one of each and the rule for the neighbour after a close (`TAB_LIMIT`, held to the panel's `MAX_TERMINALS` by a test) |
30
30
  | `lib/model.mjs` | from the state to the rows and the detail to draw, and to the switcher's rows, by calling the shared readers: pure, no cell position |
31
31
  | `lib/term/keys.mjs` | bytes to key events: a pure parser with an injected clock |
32
32
  | `lib/term/width.mjs` | the cells a grapheme takes |
@@ -36,7 +36,7 @@ never does.
36
36
  | `lib/term/through.mjs` | the bytes typed while a terminal has the focus: the back key's grammar and bytes, and the scanner that takes the back key and a bracketed paste out of them |
37
37
  | `lib/term/screen.mjs` | the cell buffer and the bytes of a frame |
38
38
  | `lib/term/tty.mjs` | the guard: enter, leave, signals, suspend, resize, one write per frame |
39
- | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`) |
39
+ | `lib/views/` | pure functions from the model and a size to rows of spans: the frame, the list, the detail, the switcher, the help, the confirmation of an act (`act.mjs`), the spawn prompt (`spawn.mjs`), the split's geometry (`split.mjs`) |
40
40
 
41
41
  Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
42
42
 
@@ -66,19 +66,32 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
66
66
  runs a process to make that FIFO, to ask tmux's version, to start the
67
67
  server, to make a window and to end the server, and the sweep one to ask
68
68
  whether a socket answers; every frame, key, resize and close goes through
69
- its one control client, and a capture runs only after tmux said the pane
70
- changed. A capture goes out of band: tmux saves it to the run's file
69
+ its one control client, and a capture runs only after tmux said a
70
+ displayed tab's pane changed (each group's shown tab, two at most); a
71
+ hidden tab's first output captures nothing, marks it and pauses its pane
72
+ for the control client until it is displayed again, when it is
73
+ continued before its capture (THE OUTPUT OF A TAB NOT DRAWN in
74
+ `lib/panel.mjs`). A capture goes out of band: tmux saves it to the run's file
71
75
  `capture`, so no pane's text is ever in the control client's stream, and
72
76
  a block that says what its command never says ends that client (THE
73
77
  CAPTURE in `lib/panel.mjs`). A
74
78
  change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
75
- start, a restart) is never signalled: on the way out it is let go, and its
76
- output goes to files, so it never meets a closed pipe.
79
+ start, a restart, a spawn's apply) is never signalled on the way out: it
80
+ is let go, and its output goes to files, so it never meets a closed pipe.
81
+ Only a spawn's apply has a deadline, the shared apply's, at which it is
82
+ sent its signal (`timeout`, `killSignal`), and only while the run lasts:
83
+ every timer the shared spawn arms is the run's (`lib/main.mjs`
84
+ `createRunTimers`), cleared as the run ends.
77
85
  - The acts decide nothing the shared home decides: which act a row offers is
78
86
  `instanceActs`, a stop or a retire is the shared confirmation over the
79
87
  run's one lifecycle boundary, a start or a restart is `startInstance`, and
80
88
  no lifecycle sentence is written in this package where the shared home
81
- has one.
89
+ has one. A retire this run sent is held by the shared retires-in-flight
90
+ tracker, one per run (`lib/main.mjs`): its row reads Retiring… from the
91
+ send until a read begun after its answer covers the row (a cycle's
92
+ entry marked `read` for this machine's rows, numbered against
93
+ `lib/read.mjs` `begun()`; a roster outcome that reached the row's
94
+ machine for another's), and at once again after a refusal.
82
95
  - The screen takes safe text only. Text the TUI did not write goes through
83
96
  `shown()`; `lit()` is for the TUI's own words and refuses anything the
84
97
  display filter would change, a run of spaces included, so a row is spans
@@ -23,18 +23,39 @@ export const ACTIONS = Object.freeze([
23
23
  { id: "souls", keys: ["2"], label: "souls" },
24
24
  { id: "capabilities", keys: ["3"], label: "capabilities" },
25
25
  { id: "workspaces", keys: ["w"], label: "workspaces" },
26
- { id: "open", keys: ["enter"], label: "open", views: [["instances", "open the selected agent's terminal beside the list, or go to it when it is the open one, in the list of instances"], ["switcher", "open the selected workspace, in the switcher"]] },
26
+ // The palette (docs/tui.md, "The palette"): from every focus it is the leader and then `k`.
27
+ { id: "palette", keys: ["ctrl+k"], label: "palette" },
28
+ { 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"]] },
29
+ // The Souls view (docs/tui.md, "The Souls view"): the selected soul's instances, in the
30
+ // Instances view, filtered by that soul.
31
+ { id: "soul-instances", keys: ["i"], label: "instances", views: [["souls", "the selected soul's instances, in the Instances view"]] },
27
32
  // The open terminal, from the list (docs/tui.md, "Open an agent's terminal"). While the terminal
28
- // has the focus the TUI takes no key but the back key (tui.json's open.detachKey), so neither of
29
- // these is ever read there.
30
- { id: "zoom", keys: ["z"], label: "zoom", views: [["instances", "go to the open terminal with the whole screen; the back key brings the list back"]] },
31
- { id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the open terminal; the agent keeps running"]] },
33
+ // has the focus the TUI takes no key but the leader (tui.json's open.detachKey), so neither of
34
+ // 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"]] },
36
+ { id: "close-terminal", keys: ["c"], label: "close terminal", views: [["instances", "close the shown terminal and show its neighbour; the agent keeps running"]] },
37
+ { id: "tab-previous", keys: ["["], label: "previous tab", views: [["instances", "show the terminal of the tab before the shown one"]] },
38
+ { id: "tab-next", keys: ["]"], label: "next tab", views: [["instances", "show the terminal of the tab after the shown one"]] },
39
+ // The split (docs/tui.md, "Splits"): two groups of tabs at most, side by side or one above the
40
+ // other. `group-next`, `tab-move` and `group-close` have no key of their own here by default
41
+ // (Tab is the detail's, and `m` and `x` are often a tui.json's): the leader's are.
42
+ { id: "split-right", keys: ["|"], label: "split right", views: [["instances", "split the panel side by side; the new group, on the right, is empty and focused"]] },
43
+ { id: "split-down", keys: ["-"], label: "split down", views: [["instances", "split the panel one above the other; the new group, below, is empty and focused"]] },
44
+ { id: "group-next", keys: [], label: "next group", views: [["instances", "go to the other group's terminal, or to the focused group's from the list"]] },
45
+ { id: "tab-move", keys: [], label: "move tab", views: [["instances", "move the shown tab to the other group, and go there"]] },
46
+ { id: "group-close", keys: [], label: "close group", views: [["instances", "close the focused group while it is empty"]] },
32
47
  // The four acts on an instance: each opens a confirmation, and nothing is done before a move and
33
48
  // a press in it. Capitals: a lower-case key is one slip away, a capital takes Shift.
34
49
  { id: "stop", keys: ["X"], label: "stop", views: [["instances", "stop the selected agent, after a confirmation"]] },
35
50
  { id: "retire", keys: ["D"], label: "retire", views: [["instances", "retire the selected agent, after a confirmation"]] },
36
51
  { id: "start", keys: ["S"], label: "start", views: [["instances", "start the selected agent as it was last launched, after a confirmation"]] },
37
52
  { id: "restart", keys: ["R"], label: "restart", views: [["instances", "restart the selected agent as it was last launched, after a confirmation"]] },
53
+ // A spawn (docs/tui.md, "Spawning an agent"): a prompt over the list, the soul picked, the
54
+ // shared preview, and one Enter. Only on this machine's workspace, one spawn at a time.
55
+ { id: "spawn", keys: ["n"], label: "spawn", views: [["instances", "spawn an agent: pick its soul, then the preview, and Enter spawns it"], ["souls", "spawn an agent of the selected soul: the preview, and Enter spawns it"]] },
56
+ { id: "spawn-another", keys: ["N"], label: "spawn another", views: [["instances", "spawn another agent of the selected agent's soul: the preview, and Enter spawns it"], ["souls", "the same as n"]] },
57
+ // Offered only while a spawn's outcome is not known: it asks the kernel once, never spawns again.
58
+ { id: "spawn-check", keys: ["C"], label: "check spawn", views: [["instances", "check the result of a spawn whose outcome is not known, while one is"]] },
38
59
  { id: "help", keys: ["?"], label: "help" },
39
60
  { id: "close", keys: ["escape"], label: "close" },
40
61
  { id: "quit", keys: ["q", "ctrl+c"], label: "quit" },
@@ -42,6 +63,43 @@ export const ACTIONS = Object.freeze([
42
63
  { id: "redraw", keys: ["ctrl+l"], label: "redraw" },
43
64
  ].map((action) => Object.freeze({ ...action, keys: Object.freeze([...action.keys]), ...(action.views ? { views: Object.freeze(action.views.map((view) => Object.freeze([...view]))) } : {}) })));
44
65
 
66
+ /** THE LEADER'S TABLE (docs/tui.md, "The leader"): the keys read after the leader (tui.json's
67
+ * open.detachKey) and what each does, from every focus. Fixed: tui.json's `keys` rebinds the plain
68
+ * keys of ACTIONS only. `does` is an action id of ACTIONS, or one of the leader's own: `previous`
69
+ * 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
72
+ * is open, and nothing without one (the hint names the tab keys only with two tabs or more). */
73
+ export const LEADER = Object.freeze([
74
+ { keys: ["k", "space"], does: "palette", label: "palette" },
75
+ { keys: ["1"], does: "instances", label: "instances" },
76
+ { keys: ["2"], does: "souls", label: "souls" },
77
+ { keys: ["3"], does: "capabilities", label: "capabilities" },
78
+ { keys: ["up"], does: "previous", label: "previous instance" },
79
+ { keys: ["down"], does: "next", label: "next instance" },
80
+ { keys: ["z"], does: "zoom", label: "zoom", terminal: true },
81
+ { keys: ["w"], does: "close-terminal", label: "close terminal", terminal: true },
82
+ { keys: ["left"], does: "tab-previous", label: "previous tab", terminal: true },
83
+ { keys: ["right"], does: "tab-next", label: "next tab", terminal: true },
84
+ { keys: ["|"], does: "split-right", label: "split right", terminal: true },
85
+ { keys: ["-"], does: "split-down", label: "split down", terminal: true },
86
+ { keys: ["tab"], does: "group-next", label: "next group", terminal: true },
87
+ { keys: ["m"], does: "tab-move", label: "move tab", terminal: true },
88
+ { keys: ["x"], does: "group-close", label: "close group", terminal: true },
89
+ { keys: ["X"], does: "stop", label: "stop" },
90
+ { keys: ["R"], does: "restart", label: "restart" },
91
+ { keys: ["S"], does: "start", label: "start" },
92
+ { keys: ["D"], does: "retire", label: "retire" },
93
+ { keys: ["n"], does: "spawn", label: "spawn" },
94
+ { keys: ["N"], does: "spawn-another", label: "spawn another" },
95
+ { keys: ["/"], does: "filter", label: "filter" },
96
+ { keys: ["o"], does: "workspaces", label: "workspaces" },
97
+ { keys: ["?"], does: "help", label: "help" },
98
+ { keys: ["escape"], does: "list", label: "the list" },
99
+ ].map((entry) => Object.freeze({ ...entry, keys: Object.freeze([...entry.keys]) })));
100
+ /** key id -> what the leader then does (LEADER's `does`). */
101
+ export const LEADER_KEYS = new Map(LEADER.flatMap((entry) => entry.keys.map((key) => [key, entry.does])));
102
+
45
103
  /** key id -> action id. A key bound twice is a defect of the table, refused when it is read. */
46
104
  export function bindings(actions = ACTIONS) {
47
105
  const map = new Map();
@@ -17,21 +17,32 @@ export { panelData, cliReadsRemotes, workspaceChoices, viewModel, deployments }
17
17
  export { remoteRosterState } from "../../client/remote-roster.mjs";
18
18
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
19
19
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
20
- export { shortPath } from "../../client/deployment-label.mjs";
20
+ export { shortPath, deploymentLabel } from "../../client/deployment-label.mjs";
21
21
  export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome } from "../../client/instance-tree.mjs";
22
22
  export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
23
23
  export { runtimeState, runtimeCounts, originLead } from "../../client/instance-presentation.mjs";
24
24
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
25
25
  export { instanceActs, openAct } from "../../client/instance-acts.mjs";
26
+ export { rowReason } from "../../client/remote-address.mjs";
26
27
  export { sessionAttachArgv, prepareRemoteTerm, detachKeySupported, hostDetachKeySupported, preflightFailure, DETACH_KEY_FEATURE } from "../../client/session-attach.mjs";
27
28
  export { attachExit } from "../../client/attach-exit.mjs";
28
29
  export { kernelLines } from "../../client/kernel-lines.mjs";
29
30
  export { createLifecycleBoundary } from "../../client/instance-lifecycle.mjs";
30
31
  export { createLifecycleConfirmation } from "../../client/lifecycle-confirmation.mjs";
32
+ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flight.mjs";
31
33
  export { startGate, startInstance } from "../../client/session-start.mjs";
32
34
  export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
33
35
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
34
36
  export { validateWorkspace, deploymentsInside } from "../../client/workspace-admission.mjs";
37
+ export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
38
+ export { soulRows } from "../../client/soul-rows.mjs";
39
+ export { soulFacts, spawnRefusal } from "../../client/soul-facts.mjs";
40
+ export { createSpawnPreview } from "../../client/spawn-preview.mjs";
41
+ export { defaultSpawnChoices } from "../../client/spawn-preview-contract.mjs";
42
+ export { createSpawnApplyBoundary } from "../../client/spawn-apply.mjs";
43
+ export { createSpawnTransaction } from "../../client/spawn-transaction.mjs";
44
+ export { spawnProblem, outcomeWords, SPAWN_NEXT } from "../../client/spawn-messages.mjs";
45
+ export { previewFacts } from "../../client/spawn-preview-facts.mjs";
35
46
 
36
47
  /** The words a shared sentence uses where it names the client that shows it (client-terms.mjs).
37
48
  * Made once, here: every shared function that takes `terms` is passed this constant, and refuses
@@ -11,7 +11,7 @@ import { isAbsolute, join } from "node:path";
11
11
  import { ACTIONS, bindings, keyLabel } from "./actions.mjs";
12
12
  import { displayLine } from "./client.mjs";
13
13
  import { isKeyId } from "./term/keys.mjs";
14
- import { BACK_KEY_RULE, isBackKey } from "./term/through.mjs";
14
+ import { BACK_KEY_RULE, backKeyId, isBackKey } from "./term/through.mjs";
15
15
 
16
16
  /** The largest tui.json that is read, in bytes. A larger file is refused by its size, unread. */
17
17
  export const CONFIG_LIMIT = 64 * 1024;
@@ -104,11 +104,16 @@ export function effectiveConfig(value, defaults = ACTIONS) {
104
104
  if (id === "quit" && list.length === 0) problems.push("quit has no key; give it one");
105
105
  }
106
106
  }
107
+ // The leader is read as a key wherever the TUI reads keys (docs/tui.md, "The leader"), so no
108
+ // 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);
110
+ 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`);
107
112
  if (problems.length > 0) return { ok: false, problems };
108
113
 
109
114
  const actions = Object.freeze(defaults.map((action) => Object.freeze({ ...action, keys: Object.freeze([...(named.get(action.id) ?? action.keys)]) })));
110
115
  try { bindings(actions); } catch { return { ok: false, problems: ["a key is given to two actions; a key does one thing"] }; }
111
- return { ok: true, actions, ascii: value.ascii === true, detachKey: value.open?.detachKey ?? DETACH_KEY };
116
+ return { ok: true, actions, ascii: value.ascii === true, detachKey };
112
117
  }
113
118
 
114
119
  /** What is wrong with the `open` setting, or null. It holds one member, `detachKey`: the back key,