@awebai/oats 0.52.0 → 0.53.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 (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -11,6 +11,10 @@
11
11
  * observed is in deployment-facts.mjs (`deploymentUnavailableText`), and the Desktop's
12
12
  * test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
13
13
  import { dirname } from 'node:path';
14
+ import { livenessOrigin } from './liveness.mjs';
15
+ import { knownOrigin, hasRuntimeError } from './instance-presentation.mjs';
16
+
17
+ const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
14
18
 
15
19
  /** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
16
20
  * with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster.
@@ -35,14 +39,27 @@ export function livenessInput(rows) {
35
39
 
36
40
  /** The collector's answers, one per row. `stdout` is what the collector printed, or `null` when it
37
41
  * failed, timed out or could not start. Anything that is not JSON for an array of exactly
38
- * `rows.length` answers gives every row the unknown answer; no rows give `[]`, whatever was printed. */
42
+ * `rows.length` answers gives every row the unknown answer; no rows give `[]`, whatever was printed.
43
+ *
44
+ * An answer with a `runtimeError` says who made it, in `runtimeErrorOrigin` (instance-presentation.mjs
45
+ * names the speakers). The speaker is decided here, in this process, and never read from what the
46
+ * collector printed: a `runtimeErrorOrigin` in its output is dropped, and the key is set from the row
47
+ * that was sent (liveness.mjs `livenessOrigin`: which answer `observeLiveness` gives is a function of
48
+ * the row alone). So `rows` are the rows whose `livenessInput` the collector was given. The unknown
49
+ * answer written here is the terminal check's own. */
39
50
  export function livenessAnswers(rows, stdout) {
40
51
  if (!rows.length) return [];
41
- const unknown = () => rows.map(() => ({ running: null, runtimeState: "unreachable", runtimeError: "Terminal status is unavailable" }));
52
+ const unknown = () => rows.map(() => ({ running: null, runtimeState: "unreachable", runtimeError: "Terminal status is unavailable", runtimeErrorOrigin: "terminal-probe" }));
42
53
  if (typeof stdout !== "string") return unknown();
43
54
  try {
44
55
  const parsed = JSON.parse(stdout);
45
- return Array.isArray(parsed) && parsed.length === rows.length ? parsed : unknown();
56
+ if (!Array.isArray(parsed) || parsed.length !== rows.length) return unknown();
57
+ return parsed.map((printed, index) => {
58
+ if (!record(printed)) return printed;
59
+ const { runtimeErrorOrigin: _printed, ...answer } = printed;
60
+ const origin = hasRuntimeError(answer) ? livenessOrigin(rows[index]) : null;
61
+ return origin ? { ...answer, runtimeErrorOrigin: origin } : answer;
62
+ });
46
63
  } catch { return unknown(); }
47
64
  }
48
65
 
@@ -66,6 +83,8 @@ export function panelInstance(i) {
66
83
  relativeTo: i.relativeTo || null,
67
84
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}),
68
85
  runtimeState: i.runtimeState, runtimeError: i.runtimeError,
86
+ // Who made that text: only beside a `runtimeError`, and only one of the three speakers.
87
+ ...(hasRuntimeError(i) && knownOrigin(i.runtimeErrorOrigin) ? { runtimeErrorOrigin: i.runtimeErrorOrigin } : {}),
69
88
  tmux: i.tmux, git: null,
70
89
  // Workspace-model v2 facts exactly as `oats status --json` reported them:
71
90
  // module drift rows (or the recorded map when the workspace is
@@ -90,10 +109,18 @@ export function panelInstance(i) {
90
109
  };
91
110
  }
92
111
 
93
- /** The panel's rows: each row merged with its liveness answer and projected, running first, then by name. */
112
+ /** The panel's rows: each row merged with its liveness answer and projected, running first, then by name.
113
+ * `answers` are `livenessAnswers`'.
114
+ *
115
+ * The merged row's `runtimeErrorOrigin` is set here or removed, whatever the row carried: when the
116
+ * answer holds the `runtimeError`, the answer's speaker; when the answer has none and the kernel's row
117
+ * had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel". */
94
118
  export function panelInstances(rows, answers) {
95
- return rows.map((row, index) => panelInstance({ ...row, ...answers[index] }))
96
- .sort((a, b) => (a.running === b.running ? String(a.instance).localeCompare(b.instance) : a.running ? -1 : 1));
119
+ return rows.map((row, index) => {
120
+ const answer = answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
121
+ const origin = record(answer) && Object.hasOwn(answer, "runtimeError") ? answer.runtimeErrorOrigin : "kernel";
122
+ return panelInstance(hasRuntimeError(merged) ? { ...merged, runtimeErrorOrigin: origin } : merged);
123
+ }).sort((a, b) => (a.running === b.running ? String(a.instance).localeCompare(b.instance) : a.running ? -1 : 1));
97
124
  }
98
125
 
99
126
  /** A deployment's entry before the first CLI probe has settled, when there is no verdict to report:
@@ -105,16 +132,27 @@ export function pendingEntry(previous, at) {
105
132
  /** A deployment's entry after a read that failed with `reason` (deployment-contract.mjs).
106
133
  * A transient busy or stale read keeps the entry held, as it is. A remote the kernel could not read
107
134
  * (a cache problem, the network, a timeout) does not erase what was observed: the last observation
108
- * stays, marked with the failure, the kernel's message and its bounded cause (Spec D); an `error` and
109
- * an `errorCause` it already carried are replaced, the cause removed when this reason has none.
135
+ * stays, marked with the failure, the kernel's message and its bounded cause (Spec D); an `error`, an
136
+ * `errorOrigin` and an `errorCause` it already carried are replaced, the origin and the cause removed
137
+ * when this reason has none.
110
138
  * Every other failure, and each of those without an entry to keep, is shown as unavailable with the
111
- * reason, never as an empty roster. */
139
+ * reason, never as an empty roster.
140
+ *
141
+ * The kept entry's `error` is always a string: the reason's message, or "" when it carries none. That
142
+ * `error` is a string is the fact "a failure is kept" (deployment-facts.mjs `keptFailure`, the one place
143
+ * that reads it); what the string holds decides nothing.
144
+ * `errorOrigin: "kernel"` stands beside it when the reason is one the installed CLI printed (the reader's
145
+ * `origin: 'kernel'`, deployment-read-cli.mjs), and is absent for any other reason: who shows `error`
146
+ * names its speaker from this key (instance-presentation.mjs `originLead`), and shows a message with no
147
+ * origin as its own, never under the kernel's name. The key is written here only, from the reason given:
148
+ * one the entry already carried never survives. */
112
149
  export function failedEntry(previous, reason, at) {
113
150
  if (previous && ["E_DEPLOYMENT_BUSY", "E_DEPLOYMENT_STALE"].includes(reason?.code)) return previous;
114
151
  if (previous?.deployment?.status === "observed" && reason?.code === "E_REMOTE_UNREADABLE") {
115
- const { error: _error, errorCause: _cause, ...kept } = previous;
152
+ const { error: _error, errorCause: _cause, errorOrigin: _origin, ...kept } = previous;
116
153
  const cause = reason.cause;
117
- return { ...kept, error: reason.message, ...(cause ? { errorCause: { code: reason.code, ...cause } } : {}) };
154
+ return { ...kept, error: typeof reason.message === "string" ? reason.message : "", ...(reason.origin === "kernel" ? { errorOrigin: "kernel" } : {}),
155
+ ...(cause ? { errorCause: { code: reason.code, ...cause } } : {}) };
118
156
  }
119
157
  return { deployment: { status: "unavailable", reason }, instances: [], generatedAt: at };
120
158
  }
@@ -2,7 +2,7 @@
2
2
  * projected by the owning observer, never forwarded wholesale to a renderer. */
3
3
  import { execFile } from 'node:child_process';
4
4
  import { isAbsolute, resolve } from 'node:path';
5
- import { deploymentReadGate, deploymentFailure, deploymentRecord, validMaxAge, maxAgeArgv, remoteFailureCause } from './deployment-contract.mjs';
5
+ import { deploymentReadGate, deploymentFailure, deploymentRecord, deploymentErrorCode, validMaxAge, maxAgeArgv, remoteFailureCause } from './deployment-contract.mjs';
6
6
  import { withoutInstanceVariables } from './kernel-environment.mjs';
7
7
 
8
8
  export const DEPLOYMENT_READ_TIMEOUT = 30_000;
@@ -35,12 +35,16 @@ export function cliDeploymentRead(cli, options, io = {}) {
35
35
  if (!deploymentRecord(document)) return fail('E_CLI_PROTOCOL');
36
36
  if (document.schemaVersion === 1 && document.ok === false) {
37
37
  const reason = document.error;
38
- if (!deploymentRecord(reason) || typeof reason.code !== 'string' || !/^[A-Z][A-Z0-9_]{0,63}$/.test(reason.code)
38
+ if (!deploymentRecord(reason) || !deploymentErrorCode(reason.code)
39
39
  || typeof reason.message !== 'string' || reason.message.length > 8192) return fail('E_CLI_PROTOCOL');
40
40
  // Only the bounded kernel error envelope, never stderr, argv, stacks or an exec error's message;
41
41
  // of `details`, only an unreadable remote's bounded cause (Spec D). A refusal cannot become success.
42
+ // `origin: 'kernel'`: this reason is the one the installed CLI printed in its envelope, so the
43
+ // kernel answered, in its own words. The reader's own failures (`deploymentFailure`: the gate, a
44
+ // timeout, the output limit, a protocol failure, a failed run) carry no origin, and unmarked
45
+ // reads as not the kernel's: who shows a reason decides by where it came from, never by its shape.
42
46
  const cause = reason.code === 'E_REMOTE_UNREADABLE' ? remoteFailureCause(reason.details) : null;
43
- return done({ ok: false, reason: { code: reason.code, message: reason.message, ...(cause ? { cause } : {}) } });
47
+ return done({ ok: false, reason: { code: reason.code, message: reason.message, origin: 'kernel', ...(cause ? { cause } : {}) } });
44
48
  }
45
49
  if (error) return fail('E_CLI_FAILED');
46
50
  if (action === 'status') {
@@ -11,8 +11,14 @@
11
11
  export const NOT_NOTE_TEXT = /[\p{Cc}\u2028\u2029\u202A-\u202E\u2066-\u2069\u200B\u2060\uFEFF\u{E0000}-\u{E007F}]/u;
12
12
  const EVERY_NOT_NOTE_TEXT = new RegExp(NOT_NOTE_TEXT.source, 'gu');
13
13
 
14
- /** Text withheld whole: secrets, credentialed URLs, C0 controls other than tab and line feed, DEL. */
15
- export const UNSAFE = /[\x00-\x08\x0b-\x1f\x7f]|[a-z][a-z0-9+.-]*:\/\/[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/i;
14
+ /** Text withheld whole: secrets, credentialed URLs, C0 controls other than tab and line feed, DEL.
15
+ * Its time grows with the length of the text, which is tested as given and may be long (#976). So the URL
16
+ * alternative finds `://` first and looks behind it for the scheme: written scheme first, it read a run of
17
+ * letters to its end from each letter of the run, and its time grew with the square of the run. The
18
+ * look-behind reads only scheme characters and `://` holds none, so each `://` reads its own run once;
19
+ * what follows stops at the next `/`, and every `://` holds one. Asked only whether it matches: this form
20
+ * and the scheme-first one match the same texts, not the same part of them. */
21
+ export const UNSAFE = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}/i;
16
22
  export const DETAIL_WITHHELD = '[Detail withheld]';
17
23
  export const MAX_DISPLAY_LINE = 2048;
18
24
 
@@ -4,14 +4,24 @@
4
4
  * instanceActs(instance) -> { blocked: Reason | null, limited: Reason | null, acts: Act[] }
5
5
  * Act = { verb, enabled, reason: Reason | null }
6
6
  * Reason = { code, sentence } and, by code:
7
- * { code: 'unaddressable', key, sentence } key: the row reason's own (remote-address.mjs rowReason)
8
- * { code: 'held', kind, sentence } kind: 'spawning' | 'spawn-incomplete' | 'retire-incomplete'
9
- * { code: 'unsupported-session', sentence }
7
+ * { code: 'unaddressable', key, sentence, origin? } key: the row reason's own (remote-address.mjs rowReason)
8
+ * { code: 'held', kind, sentence } kind: 'spawning' | 'spawn-incomplete' | 'retire-incomplete'
9
+ * { code: 'unsupported-session', sentence, origin? }
10
+ * { code: 'not-running', sentence } an `open` act's only (`openAct`)
11
+ * { code: 'state-unknown', sentence } an `open` act's only
10
12
  *
11
13
  * A client may switch on `code`, and on `key` or `kind` when it needs to; never on the sentence.
12
- * The sentences are the ones the shared tables already produce. Two of them can be kernel text (an
13
- * unaddressable row's `runtimeError`, the kernel's reason for a removed session backend): a client
14
- * shows a sentence only through display-text.mjs `displayLine`.
14
+ * The sentences are the ones the shared tables already produce. Two of them can be text this home did
15
+ * not write (an unaddressable row's `runtimeError`, the kernel's reason for a removed session backend): a
16
+ * client shows a sentence only through display-text.mjs `displayLine`.
17
+ *
18
+ * `origin` is there exactly when the sentence is not this home's own (the rule of `rowReason`, whose
19
+ * answer's `origin` is passed on as it is, never decided again here): "kernel", "terminal-probe" or
20
+ * "roster-read" when the row names the speaker of its `runtimeError`, "unattributed" when the row's text
21
+ * stands beside no speaker. It is absent on a sentence this home wrote and on the stand-in for an older
22
+ * kernel's Herdr row, and a `held` reason never has one. A client shows a sentence with an `origin`
23
+ * through its display filter, after instance-presentation.mjs `originLead`'s words when the value names
24
+ * a speaker, and a sentence with none as written, as this home's own.
15
25
  *
16
26
  * `blocked`: the row offers nothing, and this is why; `acts` is then empty.
17
27
  * `limited`: the row offers fewer acts than a home normally does, and this is why. It is about the
@@ -27,17 +37,32 @@
27
37
  * running === true inspect, restart, stop, retire
28
38
  * running === false inspect, start, stop, retire
29
39
  * running unknown inspect, stop, retire
40
+ *
41
+ * openAct(instance) -> { verb: 'open', enabled, reason: Reason | null } | null
42
+ *
43
+ * Whether the row's terminal can be opened, and why not. It is not one of `acts`: it is read from
44
+ * `instanceActs`'s answer and from nothing else of the row, so the order above is written once.
45
+ * blocked or limited is set null: the row's own reason says why, and a client adds no act
46
+ * restart is listed, enabled enabled: the row runs
47
+ * start is listed, enabled not enabled (not-running)
48
+ * start is listed, not enabled not enabled, with that act's own reason (unsupported-session)
49
+ * neither is listed not enabled (state-unknown)
50
+ * A client's own condition for opening a terminal (a recorded session on this machine, say) is the
51
+ * client's, and is not here.
30
52
  */
31
53
  import { heldHome } from './instance-tree.mjs';
32
54
  import { unsupportedSession } from './instance-presentation.mjs';
33
55
  import { canAddressRemote, rowReason } from './remote-address.mjs';
34
56
 
35
57
  const act = (verb, reason = null) => ({ verb, enabled: !reason, reason });
58
+ // An `open` act's own two codes, and the one sentence both carry.
59
+ const NOT_RUNNING = 'not-running', STATE_UNKNOWN = 'state-unknown';
60
+ const NO_LIVE_TERMINAL = 'No live terminal is reported.';
36
61
 
37
62
  export function instanceActs(instance) {
38
63
  if (!canAddressRemote(instance)) {
39
- const { key, sentence } = rowReason(instance);
40
- return { blocked: { code: 'unaddressable', key, sentence }, limited: null, acts: [] };
64
+ const { key, sentence, origin } = rowReason(instance);
65
+ return { blocked: { code: 'unaddressable', key, sentence, ...(origin !== undefined ? { origin } : {}) }, limited: null, acts: [] };
41
66
  }
42
67
  // #802: a home the kernel holds starts, stops and opens nothing. Retire only when a spawn or a retire left it
43
68
  // half cleaned (the kernel's retire completes it), nothing while its spawn sets up the worktree.
@@ -47,8 +72,19 @@ export function instanceActs(instance) {
47
72
  return held.retire ? { blocked: null, limited: reason, acts: [act('retire')] } : { blocked: reason, limited: null, acts: [] };
48
73
  }
49
74
  // A Herdr-recorded row cannot start or restart: Start stays listed, not enabled, with the kernel's reason.
50
- const unsupported = unsupportedSession(instance);
51
- const launch = unsupported ? [act('start', { code: 'unsupported-session', sentence: unsupported })]
75
+ // Its sentence and its `origin` are the row reason's own (rowReason answers this reason first for such a row).
76
+ const herdr = unsupportedSession(instance) ? rowReason(instance) : null;
77
+ const launch = herdr ? [act('start', { code: 'unsupported-session', sentence: herdr.sentence, ...(herdr.origin !== undefined ? { origin: herdr.origin } : {}) })]
52
78
  : instance.running === true ? [act('restart')] : instance.running === false ? [act('start')] : [];
53
79
  return { blocked: null, limited: null, acts: [act('inspect'), ...launch, act('stop'), act('retire')] };
54
80
  }
81
+
82
+ export function openAct(instance) {
83
+ const { blocked, limited, acts } = instanceActs(instance);
84
+ if (blocked || limited) return null;
85
+ const restart = acts.find(({ verb }) => verb === 'restart'), start = acts.find(({ verb }) => verb === 'start');
86
+ if (restart?.enabled) return act('open');
87
+ if (start?.enabled) return act('open', { code: NOT_RUNNING, sentence: NO_LIVE_TERMINAL });
88
+ if (start) return act('open', start.reason);
89
+ return act('open', { code: STATE_UNKNOWN, sentence: NO_LIVE_TERMINAL });
90
+ }
@@ -9,8 +9,10 @@ export const EVENTS_DEFAULT_LIMIT = 100;
9
9
  export const eventsTimestamp = v => typeof v === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(v)
10
10
  && Number.isFinite(Date.parse(v)) && new Date(v).toISOString() === v;
11
11
  /** Text the activity view and the roster may show: no control characters, no URL, no token-looking
12
- * assignment. Shared by packages/desktop/renderer/instance-events-data.mjs and waiting-on-you.mjs. */
13
- export const eventsUnsafe = /[\x00-\x08\x0b-\x1f\x7f]|[a-z][a-z0-9+.-]*:\/\/\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
12
+ * assignment. Shared by packages/desktop/renderer/instance-events-data.mjs and waiting-on-you.mjs. The URL
13
+ * alternative finds `://` first and looks behind it for the scheme, as display-text.mjs `UNSAFE` does and
14
+ * for its reason: time that grows with the length of the text, not with the square of a run. */
15
+ export const eventsUnsafe = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)\S+|(?:gh[pousr]_|github_pat_)[A-Za-z0-9_]{16,}|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
14
16
  /** A producer or kind id: non-empty, ≤ 256, no control characters, nothing unsafe. */
15
17
  export const eventsId = v => typeof v === 'string' && !!v && v.length <= 256 && !/[\x00-\x1f\x7f]/.test(v) && !eventsUnsafe.test(v);
16
18
  /** What stands in for text eventsUnsafe refuses. The one literal: eventsDetail and waitingMessage return it,
@@ -1,20 +1,84 @@
1
1
  import { HERDR_REMOVED } from "./terminal-contract.mjs";
2
+ import { requireTerms } from './client-terms.mjs';
2
3
 
3
4
  export function runtimeState(instance) {
4
5
  return instance.running === true ? "running" : instance.running === false ? "stopped" : "unknown";
5
6
  }
6
7
 
8
+ /** The stand-in `unsupportedSession` writes for an older kernel's Herdr row: the one text of a row that is
9
+ * this home's own sentence. Not on the stable surface. */
10
+ export const HERDR_STAND_IN = `E_HERDR_REMOVED: ${HERDR_REMOVED}`;
11
+
12
+ /** The row carries the kernel's own reason for a removed session backend, which `unsupportedSession` answers as it is. */
13
+ const kernelsOwnReason = (instance) => instance?.runtimeState === "unsupported" && typeof instance.runtimeError === "string" && !!instance.runtimeError;
14
+
7
15
  /** Why a kernel-reported row has no usable session, or null. A Herdr-recorded
8
16
  * instance cannot open, start or restart; it can still retire. A 0.31 kernel
9
17
  * reports it as runtimeState "unsupported" with its E_HERDR_REMOVED text; an
10
18
  * older kernel only records a sessionTarget (local) or a herdr backend
11
19
  * (remote), and its runtimeError is a Herdr probe's, so the stem stands in. */
12
20
  export function unsupportedSession(instance) {
13
- const stem = `E_HERDR_REMOVED: ${HERDR_REMOVED}`;
14
- if (instance?.runtimeState === "unsupported") return typeof instance.runtimeError === "string" && instance.runtimeError ? instance.runtimeError : stem;
21
+ const stem = HERDR_STAND_IN;
22
+ if (instance?.runtimeState === "unsupported") return kernelsOwnReason(instance) ? instance.runtimeError : stem;
15
23
  return (instance?.sessionTarget !== undefined && instance?.sessionTarget !== null) || instance?.backend === "herdr" ? stem : null;
16
24
  }
17
25
 
26
+ /** Who wrote what `unsupportedSession` answers for a row as the kernel or a host reported it: "kernel"
27
+ * for the row's own text, null for the stand-in written here (and for a row it answers null for). Asked
28
+ * where the text is chosen (liveness.mjs, remote-roster.mjs), of the reported row: a panel's row already
29
+ * holds the chosen text as its `runtimeError`, stand-in included, and its speaker in `runtimeErrorOrigin`.
30
+ * Not on the stable surface. */
31
+ export const unsupportedSessionOrigin = (instance) => (kernelsOwnReason(instance) ? "kernel" : null);
32
+
33
+ /** The speakers a text of a row can have, as `runtimeErrorOrigin` and a reason's `origin` name them, each
34
+ * with the words a client puts in front of the text (`originLead`):
35
+ *
36
+ * kernel read from a kernel answer: this machine's OATS, or another host's OATS relayed by it.
37
+ * A client names both the same; a row's `serverUnreached` says which read the text is about.
38
+ * terminal-probe made by the client's terminal check (liveness.mjs, tmux-status.mjs): a sentence of
39
+ * its own, or the message of a failed `tmux` or `ps` run
40
+ * roster-read made by the client while it read the roster of other machines (remote-roster.mjs)
41
+ *
42
+ * A text with no speaker (the stand-in above) has no key. The marks are written here, in the shared home,
43
+ * at the place that chooses the text, and never taken from an answer: a key a kernel, a host or the
44
+ * liveness collector sent is dropped on every path.
45
+ *
46
+ * A reason's `origin` has one more value, "unattributed", with no words: remote-address.mjs `rowReason`
47
+ * writes it for a row's text that reached it beside no speaker. It names nobody, so it is not in this
48
+ * table, `originLead` answers null for it, and it is never a row's `runtimeErrorOrigin` nor a kept
49
+ * failure's `errorOrigin`. */
50
+ const LEADS = Object.freeze({
51
+ kernel: () => "OATS says:",
52
+ "terminal-probe": (terms) => `${terms.name}'s terminal check says:`,
53
+ "roster-read": (terms) => `${terms.name}'s read of other machines says:`,
54
+ });
55
+ /** Whether a value is one of the three speakers. Not on the stable surface. */
56
+ export const knownOrigin = (value) => typeof value === "string" && Object.hasOwn(LEADS, value);
57
+
58
+ /** The words a client puts in front of a text to name who made it, or null when `origin` is not one of
59
+ * the three speakers (absent, or any other value). It takes a row's `runtimeErrorOrigin`, a reason's
60
+ * `origin` (remote-address.mjs `rowReason`, instance-acts.mjs) or a kept failure's `errorOrigin`: all hold
61
+ * the same values. A client writes nothing of its own there, so two clients name a speaker the same way.
62
+ *
63
+ * kernel "OATS says:" no term: the word the other sentences use
64
+ * terminal-probe "<name>'s terminal check says:" `terms.name` (client-terms.mjs)
65
+ * roster-read "<name>'s read of other machines says:"
66
+ *
67
+ * The two checks name the client: the kernel's own text can be about a terminal server too, so "the
68
+ * terminal check" alone would not say whose check it was. A text with no lead is shown as the client's
69
+ * own words always were: never under "OATS says:". A reason's "unattributed" is such a value: no words.
70
+ * `terms` is required, also where no term is used. */
71
+ export function originLead(origin, terms) {
72
+ requireTerms(terms, "originLead");
73
+ return knownOrigin(origin) ? LEADS[origin](terms) : null;
74
+ }
75
+ /** Whether a row has a `runtimeError`: a string that is not empty. Only such a row carries `runtimeErrorOrigin`. */
76
+ export const hasRuntimeError = (row) => typeof row?.runtimeError === "string" && !!row.runtimeError;
77
+ /** The speaker of a row's own `runtimeError`, or null: the row's `runtimeErrorOrigin` when the row has a
78
+ * text and the key names one of the three. The key is a panel row's, set by the shared home
79
+ * (deployment-panel.mjs, remote-roster.mjs). Not on the stable surface. */
80
+ export const runtimeErrorSpeaker = (row) => (hasRuntimeError(row) && knownOrigin(row.runtimeErrorOrigin) ? row.runtimeErrorOrigin : null);
81
+
18
82
  export function runtimeCounts(instances) {
19
83
  const counts = { running: 0, stopped: 0, unknown: 0 };
20
84
  for (const instance of instances) counts[runtimeState(instance)]++;
@@ -297,12 +297,12 @@ export function rosterGroupKey(workspace, ...parts) {
297
297
  return [`g:${workspace || ""}`, ...parts].join("\u0000");
298
298
  }
299
299
 
300
- /** Whether an instance itself matches the roster filter (its name, soul, repo or task) — as
300
+ /** Whether an instance itself matches the roster filter (its name, soul or repository) — as
301
301
  * opposed to an ancestor shown only to keep a match's tree path. */
302
302
  export function instanceMatchesFilter(item, query) {
303
303
  const needle = String(query || "").trim().toLowerCase();
304
304
  if (!needle) return true;
305
- return [item.instance, item.agent, item.repoName, item.task]
305
+ return [item.instance, item.agent, item.repoName]
306
306
  .some((value) => String(value || "").toLowerCase().includes(needle));
307
307
  }
308
308
 
@@ -355,19 +355,28 @@ export function visibleClusters(allInstances, visibleInstances, { links = instan
355
355
 
356
356
  /** The sidebar roster's groups (Redesign v3), shared with the command palette:
357
357
  * each multi-member relation cluster under its deterministic name, then every
358
- * unrelated instance under "independent". Clusters come from the FULL roster,
359
- * projected to the visible members (visibleClusters), so a group's size is
360
- * what is shown. Returns [{ key, label, clusters: [{ key, instances }] }] in
361
- * display order, members carrying their tree depth. A group's key is unique
362
- * even when two roots share a name (other agents roots or hosts): the label is
363
- * the name, the key adds its place in the order. */
358
+ * unrelated instance under "independent". A cluster's group is decided on the
359
+ * FULL roster: more than one member there is a group under the cluster's name,
360
+ * exactly one goes under "independent". A filter or a collapse decides which
361
+ * rows are listed and never moves a row to another group; a group with no
362
+ * visible row is left out. Returns [{ key, label, clusters: [{ key, instances }] }]
363
+ * in the full roster's cluster order, each cluster projected to its visible
364
+ * members, which carry their tree depth. A group's key is unique even when two
365
+ * roots share a name (other agents roots or hosts), and does not depend on what
366
+ * is visible: the label is the name, the key adds the cluster's place among the
367
+ * multi-member clusters of the full roster. */
364
368
  export function rosterGroups(allInstances, visibleInstances, { links = instanceLinks } = {}) {
365
- const clusters = visibleClusters(allInstances, visibleInstances, { links });
366
- return [
367
- ...clusters.filter((c) => c.instances.length > 1).map((c, i) => ({ key: `cluster:${i}:${c.key}`, label: c.key, clusters: [c] })),
368
- ...(clusters.some((c) => c.instances.length === 1)
369
- ? [{ key: "independent", label: "independent", clusters: clusters.filter((c) => c.instances.length === 1) }] : []),
370
- ];
369
+ const visibleIds = new Set(visibleInstances.map((i) => instanceId(i)));
370
+ const named = [], independent = [];
371
+ let place = 0;
372
+ for (const c of clusterInstances(allInstances, { links })) {
373
+ const at = c.instances.length > 1 ? place++ : -1;
374
+ const shown = { ...c, instances: c.instances.filter((i) => visibleIds.has(instanceId(i))) };
375
+ if (!shown.instances.length) continue;
376
+ if (at < 0) independent.push(shown);
377
+ else named.push({ key: `cluster:${at}:${c.key}`, label: c.key, clusters: [shown] });
378
+ }
379
+ return [...named, ...(independent.length ? [{ key: "independent", label: "independent", clusters: independent }] : [])];
371
380
  }
372
381
 
373
382
  /** Whether an item remains visible under VS Code-style collapsed ancestors.
@@ -0,0 +1,31 @@
1
+ /** A kernel refusal's two texts as the lines a client shows, under the kernel's name in the words the
2
+ * shared home gives (instance-presentation.mjs `originLead`). Two clients quote a refusal the same way.
3
+ * Presentation only: a line is never evidence of identity nor authority for an action. A page loads this
4
+ * module, so it reaches no `node:` import. */
5
+ import { requireTerms } from './client-terms.mjs';
6
+ import { displayLine, DETAIL_WITHHELD } from "./display-text.mjs";
7
+ import { originLead } from "./instance-presentation.mjs";
8
+
9
+ /** The lines of a kernel refusal's two texts, its `message` and its `fix` (a launch problem of a soul, the
10
+ * spawn dialog's Details for an unmatched launch preference). Each text goes through the filter alone and
11
+ * is its own line, whole: nothing is joined, taken out or compared, so a remedy the kernel says in both is
12
+ * read in both. The kernel's name stands before the first of them that has a line to show, so no text of
13
+ * the kernel's stands without its speaker:
14
+ *
15
+ * message a line, fix a line ["OATS says: <message>", "<fix>"]
16
+ * message withheld, fix a line ["[Detail withheld]", "OATS says: <fix>"]
17
+ * message nothing, fix a line ["OATS says: <fix>"]
18
+ * message a line, fix withheld ["OATS says: <message>", "[Detail withheld]"]
19
+ * message a line, fix nothing ["OATS says: <message>"]
20
+ * neither has a line what is there ("[Detail withheld]" for a withheld text), no lead
21
+ *
22
+ * `terms` are the client's own (client-terms.mjs), required on every call under this function's name:
23
+ * also where no line is led, so a caller that leaves them out fails at once and not only on the day a
24
+ * text has something to show.
25
+ */
26
+ export function kernelLines(message, fix, terms) {
27
+ requireTerms(terms, "kernelLines");
28
+ const lines = [displayLine(message), displayLine(fix)].filter(line => line !== null);
29
+ const first = lines.findIndex(line => line !== DETAIL_WITHHELD);
30
+ return lines.map((line, index) => (index === first ? `${originLead('kernel', terms)} ${line}` : line));
31
+ }
@@ -0,0 +1,23 @@
1
+ /** The mark of an error object the installed CLI printed: who reads the kernel's answer says so on the
2
+ * object, where it parses it, and who shows the error's message asks. Not on the stable surface.
3
+ *
4
+ * kernelMade(error) -> the same object, marked the reader's, where an answer is parsed
5
+ * madeByKernel(error) -> boolean the shower's
6
+ *
7
+ * The mark is a property under a symbol this module does not export, and not enumerable. So it cannot
8
+ * arrive in an answer (JSON carries no symbol key), it is in nothing a client serves (`JSON.stringify`
9
+ * skips it), and a comparison of the object's fields does not see it. It is on the object, not in a list
10
+ * of objects: this home keeps no state.
11
+ *
12
+ * Unmarked reads as not the kernel's (the rule of deployment-read-cli.mjs `origin: 'kernel'`). A copy of
13
+ * the object (a spread, a JSON round trip, `structuredClone`) has no mark, so a lost mark never puts
14
+ * words under the kernel's name: the error then reads as the client's own. An error the client writes
15
+ * itself (a timeout, an answer that is not the contract's, a read that threw) needs nothing. */
16
+ const KERNEL = Symbol('the installed CLI printed this');
17
+
18
+ export function kernelMade(error) {
19
+ if (error !== null && typeof error === 'object' && Object.isExtensible(error)) Object.defineProperty(error, KERNEL, { value: true });
20
+ return error;
21
+ }
22
+
23
+ export const madeByKernel = (error) => error !== null && typeof error === 'object' && Object.hasOwn(error, KERNEL);
@@ -2,7 +2,7 @@
2
2
  * grants terminal authority. Bad additive data must never erase a retained home. */
3
3
  import { record, absolute } from './spawn-preview-contract.mjs';
4
4
  import { eventsUnsafe } from './instance-events-contract.mjs';
5
- import { displayLine } from './display-text.mjs';
5
+ import { displayLine, cleanLine, MAX_DISPLAY_LINE } from './display-text.mjs';
6
6
  const safe = (v, max = 1024) => typeof v === 'string' && v.length <= max && !/[\x00-\x1f\x7f]/.test(v) && !eventsUnsafe.test(v);
7
7
  /** The kernel's reasons, matched whole and shown as it wrote them: no prefix or suffix is matched, so the
8
8
  * blocked reasons the kernel suffixes when its private evidence was not kept are entries of their own.
@@ -134,32 +134,67 @@ export function retainedStartMessage(instance, d) {
134
134
  const p = launchPromptOutcome(d?.launchPrompts);
135
135
  return `OATS could not confirm that ${instance} finished starting: ${p.reason}.${inputNote(p)} Its session was kept. Refresh status, then open its terminal to read what it shows. Do not start it again before that.`;
136
136
  }
137
+ /** How much of an answer's warnings the notice below shows: at most this many display lines, and at most
138
+ * this many UTF-16 units of them in total. Each cut is by position: never by a warning's words. */
139
+ export const FLAG_IGNORED_WARNINGS = 16;
140
+ export const FLAG_IGNORED_UNITS = 4096;
141
+ /** No fact below is larger than this, as JSON in UTF-8 bytes: what a store that keeps one reserves for it.
142
+ * A UTF-16 unit of a display line is at most six bytes there (a lone surrogate, which JSON writes as an
143
+ * escape); the rest is the keys, the punctuation and the count. */
144
+ export const FLAG_IGNORED_BYTES = FLAG_IGNORED_UNITS * 6 + 256;
137
145
  /** A launch that worked while Claude Code ignored the channel option (0.52.0). The kernel's successful
138
146
  * answer then carries `launchPrompts: {status: "flag-ignored", reason, signatureId, startId, at}` and its own
139
147
  * words as one string among `warnings`, never as a field. This reader takes those two fields of an answer
140
- * and knows nothing of the act that was answered. Its one caller is the start dialog, for a start's and a
141
- * restart's answer; a spawn's answer carries `launchPrompts` too (0.52.0) and is not read yet. It stands
142
- * beside the kept-session reader above, which reads a refusal's details and knows no such status.
148
+ * and knows nothing of the act that was answered. It has two callers: the start dialog, for a start's and
149
+ * a restart's answer, and the spawn's creation receipt (spawn-apply-contract.mjs), for a launched spawn's.
150
+ * It stands beside the kept-session reader above, which reads a refusal's details and knows no such status.
143
151
  * Tolerant: an answer that does not decode, or any other status, is null, and the launch reads as any
144
152
  * launch that worked.
145
153
  *
146
- * `reason` is the one value the notice has a clause for, else null. `warnings` is every warning of that
147
- * answer in the order given, each as one display line: the withheld marker for one the filter withholds,
148
- * and no line for an entry with nothing to show. None is picked, matched or dropped by its words: no
149
- * client looks for the kernel's sentence among them. */
154
+ * The fact is `{reason, warnings, omitted}`. `reason` is the one value the notice has a clause for, else
155
+ * null. `warnings` is the answer's warnings in the order given, each as one display line: the withheld
156
+ * marker for one the filter withholds, and no line for an entry with nothing to show. None is picked,
157
+ * matched or dropped by its words: no client looks for the kernel's sentence among them. Lines are kept in
158
+ * order while both bounds hold: FLAG_IGNORED_WARNINGS lines, FLAG_IGNORED_UNITS units in total. The first
159
+ * line that does not fit and every line after it are left out, and no line is cut inside; the first line
160
+ * always fits (a display line is at most MAX_DISPLAY_LINE units). `omitted` counts the lines left out, 0
161
+ * when none. An entry with nothing to show was never a line and is not counted. */
150
162
  export function launchFlagIgnored(answer) {
151
163
  if (!record(answer) || !record(answer.launchPrompts) || answer.launchPrompts.status !== 'flag-ignored') return null;
152
- const warnings = Array.isArray(answer.warnings) ? answer.warnings.map(w => displayLine(w)).filter(line => line !== null) : [];
153
- return { reason: answer.launchPrompts.reason === 'channels-unavailable' ? 'channels-unavailable' : null, warnings };
164
+ const lines = Array.isArray(answer.warnings) ? answer.warnings.map(w => displayLine(w)).filter(line => line !== null) : [];
165
+ const warnings = [];
166
+ let units = 0;
167
+ for (const line of lines) {
168
+ if (warnings.length === FLAG_IGNORED_WARNINGS || units + line.length > FLAG_IGNORED_UNITS) break;
169
+ warnings.push(line); units += line.length;
170
+ }
171
+ return { reason: answer.launchPrompts.reason === 'channels-unavailable' ? 'channels-unavailable' : null, warnings, omitted: lines.length - warnings.length };
172
+ }
173
+ /** The fact above as it crossed a boundary: the same fact, or undefined. Exactly the three keys; `reason`
174
+ * the one known value or null; `warnings` display lines within both bounds; `omitted` a non-negative safe
175
+ * integer, above 0 only where a cut can have happened: beside a full list, or beside lines that leave no
176
+ * room for another of MAX_DISPLAY_LINE units. Anything else is undefined, so a malformed value drops this
177
+ * one fact and never what carried it. Idempotent: the reader's own answer decodes to itself. */
178
+ export function flagIgnoredFact(v) {
179
+ if (!record(v) || Object.keys(v).length !== 3 || !['reason', 'warnings', 'omitted'].every(k => Object.hasOwn(v, k))
180
+ || v.reason !== null && v.reason !== 'channels-unavailable'
181
+ || !Array.isArray(v.warnings) || v.warnings.length > FLAG_IGNORED_WARNINGS || !v.warnings.every(cleanLine)
182
+ || !Number.isSafeInteger(v.omitted) || v.omitted < 0) return undefined;
183
+ const units = v.warnings.reduce((sum, line) => sum + line.length, 0);
184
+ if (units > FLAG_IGNORED_UNITS
185
+ || v.omitted > 0 && v.warnings.length < FLAG_IGNORED_WARNINGS && units <= FLAG_IGNORED_UNITS - MAX_DISPLAY_LINE) return undefined;
186
+ return { reason: v.reason, warnings: [...v.warnings], omitted: v.omitted };
154
187
  }
155
- /** The notice for it, `{headline, detail?}`, or null. `instance` is the name the caller launched. The launch
156
- * worked: the headline never says "failed" or "could not confirm". The detail is the warnings under the
157
- * Desktop's lead-in, one per line; there is none without a warning. */
158
- export function flagIgnoredNotice(instance, answer) {
159
- const d = launchFlagIgnored(answer);
188
+ /** The notice for the fact, `{headline, detail?}`, or null when `fact` is not one. `instance` is the name
189
+ * the caller launched. The launch worked: the headline never says "failed" or "could not confirm". The
190
+ * detail is the warnings under the Desktop's lead-in, one per line, and after them, in the Desktop's words,
191
+ * how many more the cut left out; there is none without a warning. */
192
+ export function flagIgnoredNotice(instance, fact) {
193
+ const d = flagIgnoredFact(fact);
160
194
  if (!d) return null;
161
195
  const headline = d.reason === 'channels-unavailable'
162
196
  ? `${instance} started. Claude Code reported that channels are not available and ignored the channel option, so mail and chat will not wake this instance.`
163
197
  : `${instance} started. Claude Code ignored the channel option, so mail and chat will not wake this instance.`;
164
- return d.warnings.length ? { headline, detail: ['OATS says:', ...d.warnings].join('\n') } : { headline };
198
+ if (!d.warnings.length) return { headline };
199
+ return { headline, detail: ['OATS says:', ...d.warnings, ...(d.omitted > 0 ? [`${d.omitted} more not shown.`] : [])].join('\n') };
165
200
  }