@awebai/oats 0.51.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 (166) hide show
  1. package/README.md +3 -1
  2. package/bin/oats.mjs +407 -123
  3. package/docs/capabilities.md +75 -6
  4. package/docs/configuration.md +200 -91
  5. package/docs/desktop-cli-api.md +1563 -113
  6. package/docs/desktop-instance-start.md +69 -0
  7. package/docs/desktop.md +10 -7
  8. package/docs/execution-targets.md +145 -58
  9. package/docs/first-team.md +3 -1
  10. package/docs/harness-trust.md +50 -2
  11. package/docs/implementation.md +238 -17
  12. package/docs/integrations.md +13 -9
  13. package/docs/knowledge-reference/acceptance.md +1 -0
  14. package/docs/knowledge-reference/harvester.md +5 -3
  15. package/docs/knowledge-reference/model.md +5 -3
  16. package/docs/knowledge-theory.md +1 -1
  17. package/docs/knowledge.md +25 -2
  18. package/docs/launch-prompt-completion.md +50 -48
  19. package/docs/macos-test-runs.md +246 -0
  20. package/docs/oats-local.schema.json +4 -3
  21. package/docs/official-catalog.md +5 -5
  22. package/docs/packages.md +14 -14
  23. package/docs/release-lane.md +225 -11
  24. package/docs/release-notes/v0.44.0.md +1 -1
  25. package/docs/release-notes/v0.52.0.md +933 -0
  26. package/docs/release-notes/v0.53.0.md +1274 -0
  27. package/docs/schedules.md +97 -4
  28. package/docs/souls-and-instances.md +332 -40
  29. package/docs/tui.md +584 -0
  30. package/docs/upgrading.md +298 -0
  31. package/docs/workspaces.md +3 -3
  32. package/lib/automations.mjs +22 -22
  33. package/lib/claim.mjs +278 -49
  34. package/lib/config-data.mjs +4 -1
  35. package/lib/core.mjs +1282 -289
  36. package/lib/errors.mjs +170 -0
  37. package/lib/harness-trust-write.mjs +68 -27
  38. package/lib/harness-trust.mjs +34 -16
  39. package/lib/instance-events.mjs +19 -1
  40. package/lib/instance-git.mjs +39 -3
  41. package/lib/instance-inspect.mjs +45 -17
  42. package/lib/instance-lifecycle.mjs +306 -57
  43. package/lib/instance-resolution.mjs +59 -6
  44. package/lib/launch-preference.mjs +236 -9
  45. package/lib/launch-prompt-completion.mjs +7 -43
  46. package/lib/launch-prompt-evidence.mjs +14 -7
  47. package/lib/launch-prompt-fixtures/README.md +86 -152
  48. package/lib/launch-prompt-fixtures/dev-channel-confirmation.json +50 -0
  49. package/lib/launch-prompt-fixtures.mjs +122 -109
  50. package/lib/launch-prompt-transport.mjs +2 -56
  51. package/lib/launch-prompts.mjs +102 -100
  52. package/lib/local-edit.mjs +118 -0
  53. package/lib/packages.mjs +13 -4
  54. package/lib/pi-bridge.mjs +308 -0
  55. package/lib/refused-text.mjs +11 -0
  56. package/lib/remote.mjs +190 -25
  57. package/lib/resolve.mjs +2 -1
  58. package/lib/retained-after-retire.mjs +2 -2
  59. package/lib/retire-output.mjs +12 -1
  60. package/lib/schedule-host.mjs +125 -22
  61. package/lib/schedule.mjs +73 -24
  62. package/lib/shell-word.mjs +13 -0
  63. package/lib/soul-launch-verbs.mjs +153 -0
  64. package/lib/stable-node.mjs +62 -0
  65. package/lib/system-tools.mjs +39 -0
  66. package/lib/teams-verbs.mjs +18 -46
  67. package/lib/tmux-server-scope.mjs +62 -0
  68. package/lib/triggers.mjs +4 -4
  69. package/lib/workspace.mjs +54 -30
  70. package/lib/worktree-hooks.mjs +98 -20
  71. package/lib/worktree.mjs +83 -24
  72. package/package-catalog.json +4 -4
  73. package/package.json +8 -2
  74. package/packages/client/attach-exit.mjs +25 -0
  75. package/packages/client/capability-show-contract.mjs +230 -0
  76. package/packages/client/capability-warnings-contract.mjs +57 -0
  77. package/packages/client/cli-adapter.mjs +561 -0
  78. package/packages/client/cli-environment.mjs +53 -0
  79. package/packages/client/cli-locator.mjs +253 -0
  80. package/packages/client/cli-probe-contract.mjs +47 -0
  81. package/packages/client/client-terms.mjs +60 -0
  82. package/packages/client/deployment-contract.mjs +72 -0
  83. package/packages/client/deployment-data.mjs +483 -0
  84. package/packages/client/deployment-facts.mjs +95 -0
  85. package/packages/client/deployment-label.mjs +76 -0
  86. package/packages/client/deployment-observer.mjs +89 -0
  87. package/packages/client/deployment-panel.mjs +180 -0
  88. package/packages/client/deployment-read-cli.mjs +57 -0
  89. package/packages/client/display-text.mjs +50 -0
  90. package/packages/client/harness-names.mjs +30 -0
  91. package/packages/client/inspect-contract.mjs +62 -0
  92. package/packages/client/instance-acts.mjs +90 -0
  93. package/packages/client/instance-admission.mjs +45 -0
  94. package/packages/client/instance-events-contract.mjs +76 -0
  95. package/packages/client/instance-git-contract.mjs +80 -0
  96. package/packages/client/instance-presentation.mjs +86 -0
  97. package/packages/client/instance-tree.mjs +462 -0
  98. package/packages/client/kernel-environment.mjs +11 -0
  99. package/packages/client/kernel-lines.mjs +31 -0
  100. package/packages/client/kernel-made.mjs +23 -0
  101. package/packages/client/launch-contract.mjs +51 -0
  102. package/packages/client/launch-prompt-outcome.mjs +200 -0
  103. package/packages/client/lifecycle-cli.mjs +61 -0
  104. package/packages/client/lifecycle-contract.mjs +413 -0
  105. package/packages/client/liveness-main.mjs +10 -0
  106. package/packages/client/liveness.mjs +48 -0
  107. package/packages/client/machine-contract.mjs +123 -0
  108. package/packages/client/own-codes.mjs +31 -0
  109. package/packages/client/own-environment.mjs +22 -0
  110. package/packages/client/panel-views.mjs +293 -0
  111. package/packages/client/readiness-contract.mjs +174 -0
  112. package/packages/client/refresh-loop.mjs +52 -0
  113. package/packages/client/remote-address.mjs +151 -0
  114. package/packages/client/remote-identity-memory.mjs +94 -0
  115. package/packages/client/remote-roster.mjs +153 -0
  116. package/packages/client/roster-sections.mjs +80 -0
  117. package/packages/client/session-attach.mjs +175 -0
  118. package/packages/client/spawn-apply-cli.mjs +104 -0
  119. package/packages/client/spawn-apply-contract.mjs +195 -0
  120. package/packages/client/spawn-decision.mjs +46 -0
  121. package/packages/client/spawn-messages.mjs +142 -0
  122. package/packages/client/spawn-preview-cli.mjs +38 -0
  123. package/packages/client/spawn-preview-contract.mjs +318 -0
  124. package/packages/client/team-members.mjs +41 -0
  125. package/packages/client/team-rows.mjs +45 -0
  126. package/packages/client/terminal-contract.mjs +57 -0
  127. package/packages/client/terminal-exec.mjs +21 -0
  128. package/packages/client/tmux-status.mjs +66 -0
  129. package/packages/client/waiting-on-you.mjs +88 -0
  130. package/packages/client/workspace-admission.mjs +45 -0
  131. package/packages/client/workspace-choices.mjs +95 -0
  132. package/packages/client/workspace-cli.mjs +142 -0
  133. package/packages/client/workspace-views.mjs +183 -0
  134. package/packages/record/README.md +21 -0
  135. package/packages/record/bin/setup.mjs +108 -15
  136. package/packages/tui/README.md +64 -0
  137. package/packages/tui/bin/tui.mjs +7 -0
  138. package/packages/tui/lib/actions.mjs +44 -0
  139. package/packages/tui/lib/client.mjs +35 -0
  140. package/packages/tui/lib/config.mjs +151 -0
  141. package/packages/tui/lib/main.mjs +176 -0
  142. package/packages/tui/lib/model.mjs +392 -0
  143. package/packages/tui/lib/read.mjs +473 -0
  144. package/packages/tui/lib/store.mjs +364 -0
  145. package/packages/tui/lib/term/keys.mjs +367 -0
  146. package/packages/tui/lib/term/screen.mjs +134 -0
  147. package/packages/tui/lib/term/style.mjs +43 -0
  148. package/packages/tui/lib/term/text.mjs +109 -0
  149. package/packages/tui/lib/term/tty.mjs +178 -0
  150. package/packages/tui/lib/term/width.mjs +124 -0
  151. package/packages/tui/lib/views/detail.mjs +46 -0
  152. package/packages/tui/lib/views/frame.mjs +256 -0
  153. package/packages/tui/lib/views/help.mjs +140 -0
  154. package/packages/tui/lib/views/instances.mjs +137 -0
  155. package/packages/tui/lib/views/scroll.mjs +19 -0
  156. package/packages/tui/lib/views/switcher.mjs +97 -0
  157. package/packages/tui/package.json +8 -0
  158. package/skills/oats-getting-started/SKILL.md +30 -23
  159. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-05-channel-seeded.txt +0 -35
  160. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-06-first-after-channel.txt +0 -35
  161. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-07-after-channel-200ms.txt +0 -35
  162. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/frame-08-installed-after-channel-200ms.txt +0 -35
  163. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/manifest.json +0 -77
  164. package/lib/launch-prompt-fixtures/claude-2.1.289-darwin-arm64/max-bypass-source.json +0 -88
  165. package/lib/launch-prompt-fixtures/structural-completion.json +0 -205
  166. package/lib/launch-prompt-policy.mjs +0 -87
@@ -0,0 +1,200 @@
1
+ /** Diagnostic projection only: neither a retained target nor an audit receipt
2
+ * grants terminal authority. Bad additive data must never erase a retained home. */
3
+ import { record, absolute } from './spawn-preview-contract.mjs';
4
+ import { eventsUnsafe } from './instance-events-contract.mjs';
5
+ import { displayLine, cleanLine, MAX_DISPLAY_LINE } from './display-text.mjs';
6
+ const safe = (v, max = 1024) => typeof v === 'string' && v.length <= max && !/[\x00-\x1f\x7f]/.test(v) && !eventsUnsafe.test(v);
7
+ /** The kernel's reasons, matched whole and shown as it wrote them: no prefix or suffix is matched, so the
8
+ * blocked reasons the kernel suffixes when its private evidence was not kept are entries of their own.
9
+ *
10
+ * Six no longer occur from OATS 0.52.0, which pins no pane geometry and reads no consent list: `blocked:
11
+ * launch geometry not pinned`, `blocked: prompt consent absent`, `launch prompt audit failed before geometry
12
+ * pin`, `launch prompt audit failed after geometry pin`, `launch prompt geometry pin failed` and `launch
13
+ * prompt geometry restoration incomplete`. They stay: kernels 0.44 to 0.51 are accepted, a routed host can
14
+ * run one, and a home keeps the outcome an older kernel recorded. */
15
+ const reasons = new Set([
16
+ 'blocked: unexpected prompt', 'blocked: observation timeout', 'blocked: launch observation failed',
17
+ 'blocked: invalid target', 'blocked: respawn ownership not proven', 'blocked: respawn geometry changed before fresh screen',
18
+ 'blocked: launch geometry not pinned', 'blocked: repeated or unsupported prompt', 'blocked: prompt consent absent',
19
+ 'blocked: prompt changed before input', 'blocked: launch authority already used',
20
+ 'launch prompt audit failed', 'launch prompt audit failed after possible input',
21
+ 'launch prompt audit failed before geometry pin', 'launch prompt audit failed after geometry pin',
22
+ 'launch prompt geometry pin failed', 'launch prompt geometry restoration incomplete',
23
+ 'launch prompt input failed', 'launch prompt input uncertain',
24
+ 'launch prompt dispatch or recording incomplete', 'launch prompt metadata recording incomplete',
25
+ 'launch prompt pending receipt incomplete', 'launch home identity changed; metadata retained at original home',
26
+ // The kernel's own evidence of the screen was not kept: alone when the launch had otherwise ended well,
27
+ // and as the suffix of each blocked reason whose screen the kernel keeps.
28
+ 'private launch evidence retention failed',
29
+ 'blocked: unexpected prompt; private launch evidence retention failed',
30
+ 'blocked: repeated or unsupported prompt; private launch evidence retention failed',
31
+ 'blocked: observation timeout; private launch evidence retention failed',
32
+ ]);
33
+ export const LAUNCH_INSPECTION = 'Launch requires inspection';
34
+ export const LAUNCH_DIAGNOSTIC_BYTES = 32768;
35
+ /** The kernel's bound on each side of a difference, in UTF-16 units. */
36
+ const DIFFERED_UNITS = 40;
37
+ /** What a blocked launch's screen differed in from the confirmation the kernel answers (0.52.0), as
38
+ * `{nearest, index, expected, found}`, or undefined. The kernel sends `{nearest, firstDifference: {index,
39
+ * expected, found}}`: `nearest` the id of the nearest tolerance entry, `index` the first differing position
40
+ * of the two normalized texts, `expected` and `found` at most 40 UTF-16 units of each from there (either
41
+ * can be empty: that text ended). `found` is what a terminal showed and `expected` the kernel's own text:
42
+ * each is kept as one display line, null when there is nothing to show. For display only: never compared,
43
+ * parsed or acted on.
44
+ *
45
+ * Tolerant, unlike the outcome around it: anything else, in any part, is undefined, so a malformed value
46
+ * drops this one fact and never the outcome, the retained home or the read. Idempotent: this module's own
47
+ * answer decodes to itself (the renderer reads again what the server projected). */
48
+ export function launchPromptDiffered(v) {
49
+ if (!record(v) || !safe(v.nearest, 256) || !v.nearest) return undefined;
50
+ const own = !Object.hasOwn(v, 'firstDifference'), d = own ? v : v.firstDifference;
51
+ if (!record(d) || !Number.isSafeInteger(d.index) || d.index < 0) return undefined;
52
+ const sides = [d.expected, d.found];
53
+ // Only this module's answer holds null for a side with nothing to show.
54
+ if (!sides.every(s => typeof s === 'string' ? s.length <= DIFFERED_UNITS : own && s === null)) return undefined;
55
+ return { nearest: v.nearest, index: d.index, expected: displayLine(d.expected), found: displayLine(d.found) };
56
+ }
57
+ /** What differed, as data for a view: the Desktop's lead-in, then the two texts, each under a lead-in of
58
+ * its own that names whose text it is. `found` is what a terminal showed, so it is shown as an attributed
59
+ * quote and never inside one of the Desktop's sentences; `expected` is the kernel's own text and gets the
60
+ * same line, so the two read as a pair. A side with nothing to show has a `note` instead of a `text`.
61
+ * `detail` (the nearest entry and the position) is for Details, never part of a sentence. Null when there is
62
+ * nothing decodable to say. Nothing is interpreted: no client decides from the two texts what the prompt
63
+ * was, whether a key is safe, or what to press. */
64
+ export const DIFFERED_LEAD_IN = 'Where the screen first differed from the confirmation OATS answers:';
65
+ export const DIFFERED_NO_TEXT = '(no visible text)';
66
+ /** The background notice cannot hold an attributed quote: it says where one is. True whenever it shows:
67
+ * the kernel writes `differed` to the `launch-prompt` event in the step that puts it on the result. */
68
+ export const DIFFERED_IN_ACTIVITY = 'Its Activity shows what OATS expected and what the terminal showed.';
69
+ export function differedLines(v) {
70
+ const d = launchPromptDiffered(v);
71
+ if (!d) return null;
72
+ const line = (leadIn, text) => ({ leadIn, text, note: text === null ? DIFFERED_NO_TEXT : null });
73
+ return { leadIn: DIFFERED_LEAD_IN, lines: [line('OATS expected:', d.expected), line('The terminal showed:', d.found)],
74
+ detail: `Nearest entry ${displayLine(d.nearest)}, first difference at ${d.index}` };
75
+ }
76
+ const unknown = () => ({ status: 'unknown', answers: [], reason: LAUNCH_INSPECTION, receipt: [] });
77
+ const within = v => new TextEncoder().encode(JSON.stringify(v)).length <= LAUNCH_DIAGNOSTIC_BYTES;
78
+ export function launchPromptOutcome(v) {
79
+ // A failed audit can follow a possible key even with answers: []. Never
80
+ // translate missing diagnostics into “no input” or a recoverable spawn retry.
81
+ try {
82
+ if (!record(v) || !within(v) || !['blocked', 'incomplete', 'unknown'].includes(v.status)) return unknown();
83
+ const answers = Array.isArray(v.answers) && v.answers.length <= 8 ? v.answers.flatMap(a =>
84
+ record(a) && a.class === 'awebDevelopmentChannel' && a.status === 'submitted' && safe(a.signatureId, 256)
85
+ ? [{ class: a.class, signatureId: a.signatureId, status: a.status }] : []) : [];
86
+ const receipt = Array.isArray(v.receipt) && v.receipt.length <= 16 ? v.receipt.flatMap(r => {
87
+ if (!record(r) || typeof r.ok !== 'boolean' || !Array.isArray(r.results) || r.results.length > 2) return [];
88
+ const results = r.results.flatMap(w => record(w) && typeof w.ok === 'boolean' && safe(w.path) && absolute(w.path)
89
+ ? [{ path: w.path, ok: w.ok }] : []);
90
+ // Keep write outcomes and actual paths; raw event/OS diagnostic text is
91
+ // deliberately excluded. The Activity reader owns event-row projection.
92
+ return [{ ok: r.ok, results }];
93
+ }) : [];
94
+ // Only a blocked result says what differed (0.52.0), and not every one (an invalid target has no screen).
95
+ const differed = v.status === 'blocked' ? launchPromptDiffered(v.differed) : undefined;
96
+ const out = { status: v.status, answers, reason: reasons.has(v.reason) ? v.reason : LAUNCH_INSPECTION, receipt };
97
+ // The answer is held to the bound it was read under, so reading it again (the renderer does) gives it
98
+ // back. It can be longer than what was read: a withheld side, the generic reason. What differed is the
99
+ // one fact that goes first; an answer still over the bound is unknown here, as the next read would say.
100
+ if (differed && within({ ...out, differed })) return { ...out, differed };
101
+ return within(out) ? out : unknown();
102
+ } catch { return unknown(); }
103
+ }
104
+ export function retainedSpawnDetails(d) {
105
+ if (!record(d) || typeof d.instance !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(d.instance)
106
+ || !absolute(d.home) || ![false, 'unknown'].includes(d.launched)) return null;
107
+ const out = { instance: d.instance, home: d.home, launched: d.launched };
108
+ if (Object.hasOwn(d, 'launchPrompts')) {
109
+ out.launchPrompts = launchPromptOutcome(d.launchPrompts);
110
+ if (typeof d.parentLineageCommitted === 'boolean') out.parentLineageCommitted = d.parentLineageCommitted;
111
+ if (record(d.target)) {
112
+ out.target = {};
113
+ for (const key of ['socket', 'session', 'window', 'windowId', 'paneId']) if (safe(d.target[key])) out.target[key] = d.target[key];
114
+ if (d.target.backend === 'tmux') out.target.backend = 'tmux';
115
+ if (Number.isSafeInteger(d.target.pid) && d.target.pid > 0 || safe(d.target.pid, 32) && /^\d+$/.test(d.target.pid)) out.target.pid = d.target.pid;
116
+ }
117
+ }
118
+ return out;
119
+ }
120
+ /** Whether input reached the pane, as far as the outcome says: a submitted answer, or an incomplete result
121
+ * (a failed audit can follow a possible key). One rule for a spawn and for a start. */
122
+ const inputNote = p => p.answers.length ? ' A launch-prompt answer was submitted; this does not confirm readiness.'
123
+ : p.status === 'incomplete' ? ' Input may already have been sent.' : '';
124
+ export function retainedSpawnMessage(d) {
125
+ if (!d.launchPrompts) return `${d.instance} was created but didn’t finish starting. Open it from the instance list instead of spawning again.`;
126
+ const p = launchPromptOutcome(d.launchPrompts);
127
+ return `${d.instance} was retained: ${p.reason}.${inputNote(p)} Inspect its existing pane, then use oats session start --home for this home. Do not spawn again.`;
128
+ }
129
+ /** A Start or Restart of an existing home that stopped at a launch prompt, in the Desktop's words: the
130
+ * kernel answers E_SPAWN_INCOMPLETE with the same retained details as a spawn. `instance` is the name the
131
+ * dialog started; `d` the decoded details. It claims the weaker thing for both statuses: a blocked start and
132
+ * one whose completion was not seen are both "not confirmed", never "failed" and never "started". */
133
+ export function retainedStartMessage(instance, d) {
134
+ const p = launchPromptOutcome(d?.launchPrompts);
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
+ }
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;
145
+ /** A launch that worked while Claude Code ignored the channel option (0.52.0). The kernel's successful
146
+ * answer then carries `launchPrompts: {status: "flag-ignored", reason, signatureId, startId, at}` and its own
147
+ * words as one string among `warnings`, never as a field. This reader takes those two fields of an answer
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.
151
+ * Tolerant: an answer that does not decode, or any other status, is null, and the launch reads as any
152
+ * launch that worked.
153
+ *
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. */
162
+ export function launchFlagIgnored(answer) {
163
+ if (!record(answer) || !record(answer.launchPrompts) || answer.launchPrompts.status !== 'flag-ignored') return null;
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 };
187
+ }
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);
194
+ if (!d) return null;
195
+ const headline = d.reason === 'channels-unavailable'
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.`
197
+ : `${instance} started. Claude Code ignored the channel option, so mail and chat will not wake this instance.`;
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') };
200
+ }
@@ -0,0 +1,61 @@
1
+ /** Fixed-argv installed-CLI K3 adapter. No kernel import, fallback or raw errors. */
2
+ import { execFile } from 'node:child_process';
3
+ import { isAbsolute } from 'node:path';
4
+ import { parseEnvelope, parseRetireEnvelope } from './cli-adapter.mjs';
5
+ import { object, lifecycleOptions, planRevision } from './lifecycle-contract.mjs';
6
+ const absolute = v => typeof v === 'string' && isAbsolute(v) && !v.includes('\0');
7
+ const key = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(v);
8
+ const failure = code => ({ schemaVersion: 1, ok: false, error: { code } });
9
+ const serverId = v => typeof v === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(v);
10
+ /** Remote reads and plans: ssh's ConnectTimeout (15 s) plus the command. */
11
+ export const REMOTE_READ_TIMEOUT = 45_000;
12
+ /** A routed command (`server`) is addressed by `--server S --home H` and never carries `--dir`:
13
+ * the kernel sends the registered workspace. `context` is then only this machine's cwd. */
14
+ export function lifecycleArgv(options) {
15
+ if (!object(options) || Object.keys(options).some(k => !['operation', 'phase', 'instance', 'home', 'context', 'server', 'choices', 'revision', 'key'].includes(k))) return null;
16
+ const o = options, choices = lifecycleOptions(o.operation, o.choices);
17
+ if (!choices || !['plan', 'apply'].includes(o.phase) || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(o.instance || '')
18
+ || !absolute(o.home) || !absolute(o.context) || (Object.hasOwn(o, 'server') && !serverId(o.server))) return null;
19
+ if (o.phase === 'plan' ? Object.hasOwn(o, 'revision') || Object.hasOwn(o, 'key') : !planRevision(o.revision) || !key(o.key)) return null;
20
+ const args = o.operation === 'stop' ? ['instance', 'stop', o.instance] : ['retire', o.instance];
21
+ if (o.phase === 'plan') args.push('--plan');
22
+ else {
23
+ if (o.operation === 'stop') args.push('--apply');
24
+ args.push('--plan-revision', o.revision, '--idempotency-key', o.key);
25
+ if (o.operation === 'retire' && choices.discardWorktree) args.push('--discard-worktree');
26
+ }
27
+ args.push('--home', o.home, ...(o.server ? ['--server', o.server] : ['--dir', o.context]));
28
+ if (o.operation === 'stop' && !choices.recursive) args.push('--no-recursive');
29
+ args.push('--json'); return args;
30
+ }
31
+ /** `exec` is a client's own `execFile` (the rule is at cli-adapter.mjs `runJson`). */
32
+ export function cliLifecycle(bin, options, { exec = execFile, timeout } = {}) {
33
+ const argv = lifecycleArgv(options);
34
+ if (!absolute(bin) || !argv) return Promise.resolve(failure('E_BAD_ARGS'));
35
+ const apply = options.phase === 'apply', limit = apply ? 600_000 : options.server ? REMOTE_READ_TIMEOUT : 30_000;
36
+ return new Promise(resolve => {
37
+ try {
38
+ exec(bin, argv, { cwd: options.context, encoding: 'utf8', shell: false,
39
+ timeout: Number.isFinite(timeout) && timeout > 0 ? Math.min(timeout, limit) : limit,
40
+ maxBuffer: (apply ? 4 : 1) * 1024 * 1024 }, (error, stdout) => {
41
+ if (error?.killed) return resolve(failure('E_CLI_TIMEOUT'));
42
+ if (error?.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') return resolve(failure('E_CLI_OUTPUT_LIMIT'));
43
+ const printed = parseEnvelope(stdout), value = apply && options.operation === 'retire' ? parseRetireEnvelope(stdout) : printed;
44
+ if (!value) return resolve(failure('E_CLI_PROTOCOL'));
45
+ if (error && value.ok !== false) return resolve(failure('E_CLI_FAILED'));
46
+ // Only internal consumers see result/details. They validate/project all
47
+ // data against their admitted target. An error envelope's message is kept, for a
48
+ // local command and a routed one: the boundary shows it only through the display
49
+ // filter, as the refusal's detail. Stderr and the process error never leave here.
50
+ // `origin: 'kernel'`: the error is the one the installed CLI printed in its envelope, so the
51
+ // kernel answered. The adapter's own failures (`failure`) and the error it writes for a raw
52
+ // retire receipt that reports incomplete cleanup (parseRetireEnvelope) carry no origin, and
53
+ // unmarked reads as not the kernel's: a reader decides by where an answer came from, never
54
+ // by its shape.
55
+ if (value.ok) resolve({ schemaVersion: 1, ok: true, result: value.result });
56
+ else resolve({ schemaVersion: 1, ok: false, ...(printed?.ok === false ? { origin: 'kernel' } : {}), ...(value.result ? { result: value.result } : {}),
57
+ error: { code: value.error?.code, message: value.error?.message, details: value.error?.details } });
58
+ });
59
+ } catch { resolve(failure('E_CLI_FAILED')); }
60
+ });
61
+ }