@awebai/oats 0.56.0 → 0.57.1

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 (64) hide show
  1. package/bin/oats.mjs +18 -10
  2. package/docs/configuration.md +17 -27
  3. package/docs/desktop-cli-api.md +59 -3
  4. package/docs/desktop.md +25 -4
  5. package/docs/execution-targets.md +6 -1
  6. package/docs/implementation.md +106 -5
  7. package/docs/integrations.md +8 -4
  8. package/docs/knowledge.md +93 -38
  9. package/docs/official-catalog.md +3 -3
  10. package/docs/packages.md +12 -12
  11. package/docs/release-notes/v0.57.0.md +283 -0
  12. package/docs/release-notes/v0.57.1.md +275 -0
  13. package/docs/schedules.md +8 -3
  14. package/docs/servers.md +18 -0
  15. package/docs/souls-and-instances.md +126 -15
  16. package/docs/tui.md +333 -95
  17. package/docs/workspaces.md +2 -2
  18. package/lib/core.mjs +439 -126
  19. package/lib/instance-lifecycle.mjs +45 -9
  20. package/lib/session-viewer.mjs +29 -4
  21. package/lib/worktree.mjs +23 -2
  22. package/package-catalog.json +2 -2
  23. package/package.json +1 -1
  24. package/packages/client/cli-adapter.mjs +9 -7
  25. package/packages/client/cli-locator.mjs +2 -2
  26. package/packages/client/composed-gate.mjs +34 -0
  27. package/packages/client/inspect-boundary.mjs +157 -0
  28. package/packages/client/inspect-cache.mjs +86 -0
  29. package/packages/client/instance-lifecycle.mjs +10 -3
  30. package/packages/client/keyed-catalog.mjs +132 -0
  31. package/packages/client/launch-prompt-outcome.mjs +1 -1
  32. package/packages/client/launch-view.mjs +46 -0
  33. package/packages/client/session-attach.mjs +7 -5
  34. package/packages/client/soul-catalog.mjs +77 -0
  35. package/packages/client/soul-colors.mjs +31 -0
  36. package/packages/client/soul-facts.mjs +85 -0
  37. package/packages/client/soul-rows.mjs +48 -0
  38. package/packages/client/spawn-apply-cli.mjs +11 -6
  39. package/packages/client/spawn-apply.mjs +212 -0
  40. package/packages/client/spawn-messages.mjs +131 -85
  41. package/packages/client/spawn-preview-contract.mjs +3 -0
  42. package/packages/client/spawn-preview-facts.mjs +119 -0
  43. package/packages/client/spawn-preview.mjs +152 -0
  44. package/packages/client/spawn-transaction.mjs +136 -0
  45. package/packages/tui/README.md +43 -13
  46. package/packages/tui/lib/actions.mjs +18 -2
  47. package/packages/tui/lib/client.mjs +4 -0
  48. package/packages/tui/lib/config.mjs +9 -14
  49. package/packages/tui/lib/main.mjs +241 -55
  50. package/packages/tui/lib/model.mjs +230 -29
  51. package/packages/tui/lib/panel.mjs +955 -0
  52. package/packages/tui/lib/read.mjs +134 -24
  53. package/packages/tui/lib/store.mjs +184 -31
  54. package/packages/tui/lib/term/capture.mjs +260 -0
  55. package/packages/tui/lib/term/screen.mjs +44 -8
  56. package/packages/tui/lib/term/style.mjs +78 -6
  57. package/packages/tui/lib/term/text.mjs +24 -4
  58. package/packages/tui/lib/term/through.mjs +213 -0
  59. package/packages/tui/lib/term/tty.mjs +7 -60
  60. package/packages/tui/lib/views/act.mjs +85 -0
  61. package/packages/tui/lib/views/frame.mjs +153 -37
  62. package/packages/tui/lib/views/help.mjs +22 -14
  63. package/skills/oats-getting-started/SKILL.md +4 -3
  64. package/packages/tui/lib/open.mjs +0 -45
@@ -0,0 +1,212 @@
1
+ /** One client's confirmed-spawn broker across all workspaces: a client makes its own (createSpawnApplyBoundary)
2
+ * and owns it, and two share nothing (references, keys, the active applies, byte reservations).
3
+ * RAM custody only. No kernel imports, placement logic, persistent instructions,
4
+ * implicit retry, name-based recovery, or mutation from result/prepare.
5
+ *
6
+ * Long spawns (#802): an apply runs the CLI for the deadline its confirmed preview implies
7
+ * (spawnApplyDeadlineMs: 60 s, or 60 s + n × 30 min + 60 s for n `worktree` hooks). The apply
8
+ * request answers within ANSWER_WITHIN_MS: with the outcome if the CLI settled, else `pending`;
9
+ * the CLI keeps running here and `result` reads its outcome. Up to MAX_APPLIES applies run at
10
+ * once per boundary, one per workspace and soul. */
11
+ import { retainedSpawnDetails, LAUNCH_DIAGNOSTIC_BYTES, FLAG_IGNORED_BYTES } from './launch-prompt-outcome.mjs';
12
+ import { randomBytes } from 'node:crypto';
13
+ import { performance } from 'node:perf_hooks';
14
+ import { cliSpawnApply } from './spawn-apply-cli.mjs';
15
+ import { admitSpawnSelection } from './spawn-preview.mjs';
16
+ import { record } from './spawn-preview-contract.mjs';
17
+ import { spawnApplySupported, spawnApplyChoicesSupported, spawnPrepareInput, spawnRefInput, spawnPreparedData, spawnReference,
18
+ spawnCreationReceipt, spawnApplyFailure, spawnApplyDeadlineMs, ROLLED_BACK_CODES, WAKE_OUTCOME_UNKNOWN } from './spawn-apply-contract.mjs';
19
+ /** The apply request answers within this; the proxy's own 65 s timeout then never fires on a healthy spawn. */
20
+ export const ANSWER_WITHIN_MS = 50000;
21
+ export const MAX_APPLIES = 4;
22
+ const clone = v => structuredClone(v);
23
+ const byteSize = v => Buffer.byteLength(JSON.stringify(v));
24
+ const scopeKey = c => JSON.stringify([c?.workspace?.id, c?.workspace?.scope, c?.workspace?.remote, c?.workspace?.server,
25
+ c?.cli?.bin, c?.cli?.version, c?.cli?.spawnPreviewApi, c?.cli?.spawnApplyApi, c?.cli?.features, c?.cli?.harnesses, c?.cli?.sessionBackends, c?.cli?.launchOptions]);
26
+ /** `read` is required: the client's own preview's `prepareRead` (spawn-preview.mjs createSpawnPreview). Prepare
27
+ * reads through the dialog's cache: a fresh held answer for exactly these choices is the decision (no second
28
+ * CLI read); apply's --expect-decision is the drift guard. No held answer: a fresh read.
29
+ * exec optional: the client's own execFile, passed to `invoke` as `invoke(cli, options, { exec })` for every
30
+ * apply (cli-adapter.mjs `runJson` has the rule); without it `invoke` is given no third argument and
31
+ * cliSpawnApply's own default runs. An apply is a change: its options carry `detached: true`
32
+ * whatever exec is given, which runs it in a session of its own (as execFileInSession does). On a
33
+ * worktree-event kernel cliSpawnApply ends the child at the deadline through what exec returns
34
+ * (`child.kill`): a given exec must return the child. One that returns nothing leaves that apply
35
+ * unended at its deadline; there is no fallback here. On a kernel without worktree-event the options'
36
+ * `timeout` is the apply's only deadline: exec must honour it as execFileInSession does, killing the
37
+ * child when it passes and reporting `killed` even if the child then exits cleanly. */
38
+ export function createSpawnApplyBoundary({ read, invoke = cliSpawnApply, exec,
39
+ now = () => performance.now(), mint = () => randomBytes(32).toString('hex'), answerWithinMs = ANSWER_WITHIN_MS,
40
+ timer = (fn, ms) => { const t = setTimeout(fn, ms); return () => clearTimeout(t); } } = {}) {
41
+ if (typeof read !== 'function') throw new TypeError('createSpawnApplyBoundary: read (the client\'s prepareRead) is required');
42
+ const prepared = new Map(), submitted = new Map(), active = new Set(), io = exec ? [{ exec }] : [];
43
+ let preparing = 0, reservedBytes = 0;
44
+ const denied = (code, entry = null, status = 'unavailable', message) => spawnApplyFailure(code, { target: entry?.target, spawnRef: entry?.ref, status, message });
45
+ const sweep = () => { for (const map of [prepared, submitted]) for (const [ref, entry] of map) if (!entry.pending && entry.expires <= now()) map.delete(ref); };
46
+ const usedBytes = () => reservedBytes + [...prepared.values(), ...submitted.values()].reduce((sum, e) => sum + e.bytes, 0);
47
+ const freshId = () => {
48
+ const id = mint();
49
+ return spawnReference(id) && !prepared.has(id) && !submitted.has(id) && ![...submitted.values()].some(e => e.key === id) ? id : null;
50
+ };
51
+ function select(input, getContext) {
52
+ const c = getContext();
53
+ if (!spawnApplySupported(c?.cli)) return { error: 'E_APPLY_UNAVAILABLE' };
54
+ if (!spawnApplyChoicesSupported(c.cli, input.choices, !!input.wake)) return { error: 'E_UNSUPPORTED_OPTION' };
55
+ const s = admitSpawnSelection(input.selector, input.choices, c);
56
+ if (s.error) return s;
57
+ const soul = c.agents.find(a => a.name === input.selector.soul && a.agentsRoot === input.selector.agentsRoot);
58
+ const anchor = input.choices.relation.anchor;
59
+ if (soul?.captured || anchor && c.instances?.some(i => i.instance === anchor.instance && i.agentsRoot === anchor.agentsRoot && i.captured)) return { error: 'E_UNSUPPORTED_MODE' };
60
+ return { ...s, scope: scopeKey(c) };
61
+ }
62
+ const same = (a, b) => !b.error && a.identity === b.identity && a.scope === b.scope;
63
+ const ownsScope = (e, getContext) => { try { const c = getContext(); return spawnApplySupported(c?.cli) && !c.workspace?.remote && !c.workspace?.server && scopeKey(c) === e.scope; } catch { return false; } };
64
+ const display = (entry, status, receipt = null, reason = null, extra = {}) => ({ spawnApplyViewApi: 1, status, target: entry.target, spawnRef: entry.ref,
65
+ preview: entry.preview, wakeRequested: !!entry.input.wake, receipt, reason, applyWithinMs: entry.deadlineMs, ...extra });
66
+ async function prepare(input, getContext) {
67
+ const selection = select(input, getContext);
68
+ if (selection.error) return denied(selection.error);
69
+ const reservation = byteSize(input);
70
+ if (prepared.size + preparing >= 32 || usedBytes() + reservation > 8 * 1024 * 1024) return denied('E_BUSY');
71
+ preparing++; reservedBytes += reservation;
72
+ let observed;
73
+ try { observed = await read({ action: 'preview', selector: clone(input.selector), choices: clone(input.choices) }, getContext); }
74
+ catch { observed = { status: 'unavailable', reason: { code: 'E_CLI_FAILED' } }; }
75
+ finally { preparing--; reservedBytes -= reservation; }
76
+ const current = select(input, getContext);
77
+ if (!same(selection, current)) return denied('E_PLAN_CHANGED', { target: selection.target });
78
+ if (observed?.status !== 'available') return denied(observed?.reason?.code, { target: selection.target });
79
+ if (observed.data?.preflight?.status !== 'complete') return denied('E_PREFLIGHT_INCOMPLETE', { target: selection.target });
80
+ const preview = spawnPreparedData(observed.data, selection.target);
81
+ if (!preview) return denied('E_CLI_PROTOCOL', { target: selection.target });
82
+ if (!preview.backendStatus.installed) return denied('E_BACKEND_UNAVAILABLE', { target: selection.target });
83
+ const entry = { ...selection, input: clone(input), preview, ref: freshId(), key: null, expires: now() + 300000,
84
+ pending: false, reply: null, final: false, seenHome: false, seenBirth: null, bytes: 0, deadlineMs: spawnApplyDeadlineMs(selection.cli, preview) };
85
+ if (!entry.ref) return denied('E_BUSY', entry);
86
+ // Reserve bounded outcome storage before dispatch. A settled reply shares
87
+ // this immutable preview internally; public responses are always cloned.
88
+ // A reply keeps one of two bounded texts, never both: a retained launch's diagnostics, or the
89
+ // fact a receipt carries when Claude Code ignored the channel option. The larger bound covers either.
90
+ entry.bytes = byteSize(entry) + 3 * byteSize(preview.decision) + 2 * byteSize(entry.target) + 4096 + Math.max(LAUNCH_DIAGNOSTIC_BYTES, FLAG_IGNORED_BYTES);
91
+ if (usedBytes() + entry.bytes > 8 * 1024 * 1024) return denied('E_BUSY', entry);
92
+ prepared.set(entry.ref, entry);
93
+ return display(entry, 'prepared');
94
+ }
95
+ function observedGone(entry, getContext) {
96
+ // A prior positive observation can block retry after disappearance/replacement.
97
+ // Absence alone is NOT success/retirement proof and does not close a concurrent
98
+ // retire race. The kernel key's documented lifetime is only its surviving home.
99
+ const rows = getContext().instances || [];
100
+ const matches = rows.filter(i => i.instance === entry.preview.decision.instance && i.home === entry.preview.decision.home
101
+ && i.agent === entry.input.selector.soul && i.agentsRoot === entry.input.selector.agentsRoot && !i.server && !i.remote);
102
+ const own = matches.length === 1 && matches[0].spawnIdempotencyKey === entry.key ? matches[0] : null;
103
+ if (own) {
104
+ const birth = typeof own.createdAt === 'string' && own.createdAt.length <= 128 ? own.createdAt : null;
105
+ if (entry.seenBirth !== null && entry.seenBirth !== birth) return true;
106
+ entry.seenHome = true; entry.seenBirth = birth; return false;
107
+ }
108
+ return entry.seenHome || matches.some(i => typeof i.spawnIdempotencyKey === 'string' && i.spawnIdempotencyKey !== entry.key);
109
+ }
110
+ function interpret(result, entry, cli) {
111
+ const envelope = result?.envelope;
112
+ if (typeof result?.started !== 'boolean' || envelope?.schemaVersion !== 1 || typeof envelope.ok !== 'boolean') return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
113
+ if (envelope.ok) {
114
+ if (!result.started) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
115
+ const receipt = spawnCreationReceipt(envelope.result, { target: entry.target, preview: entry.preview, wakeRequested: !!entry.input.wake });
116
+ if (!receipt) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
117
+ const partial = !!entry.input.wake && receipt.wake.saved !== true;
118
+ const reason = !partial ? null : receipt.wake.error ?? { code: 'E_WAKE_OUTCOME_UNKNOWN', message: WAKE_OUTCOME_UNKNOWN };
119
+ return display(entry, partial ? 'partial' : 'complete', receipt, reason);
120
+ }
121
+ const code = envelope.error?.code;
122
+ if (!result.started) return denied(code, entry, 'refused');
123
+ if (code === 'E_SPAWN_INCOMPLETE') {
124
+ const d = retainedSpawnDetails(envelope.error.details);
125
+ if (!d || d.instance !== entry.preview.decision.instance || d.home !== entry.preview.decision.home) return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
126
+ return { ...denied(code, entry, 'incomplete'), incomplete: d };
127
+ }
128
+ // worktree-event: the kernel rolled these back. Without the unconfirmed marker its compensation
129
+ // was confirmed: refused, nothing created. With it, cleanup is owed: unknown, and final (a
130
+ // re-apply of the same key would not finish it; retiring the quarantined home does).
131
+ if (ROLLED_BACK_CODES.includes(code) && cli?.features?.includes('worktree-event')) {
132
+ const message = envelope.error.message;
133
+ if (envelope.error.details?.unconfirmed === true) { entry.final = true; return denied(code, entry, 'unknown', message); }
134
+ return denied(code, entry, 'refused', message);
135
+ }
136
+ // A taken explicit name (spawn-name) refuses before any home is kept: the
137
+ // confirmation is consumed and a fresh preview reports the taken name.
138
+ if (['E_DECISION_STALE', 'E_IDEMPOTENCY_CONFLICT', 'E_PLACEMENT_TAKEN', 'E_INSTANCE_NAME_TAKEN'].includes(code)) return denied(code, entry, 'stale');
139
+ // Do not infer rollback from arbitrary kernel/hook failures. Only the
140
+ // explicit binding/reservation/incomplete contracts above establish scope.
141
+ return denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
142
+ }
143
+ function get(ref, getContext) {
144
+ const e = submitted.get(ref) || prepared.get(ref);
145
+ if (!e) return { failure: denied('E_INTENT_EXPIRED') };
146
+ if (!ownsScope(e, getContext)) return { failure: denied('E_PLAN_CHANGED', e) };
147
+ return { entry: e };
148
+ }
149
+ const sameSoul = (a, b) => a.target.workspace === b.target.workspace && a.input.selector.soul === b.input.selector.soul
150
+ && a.input.selector.agentsRoot === b.input.selector.agentsRoot;
151
+ async function apply(entry, getContext, settled) {
152
+ if (entry.pending) return display(entry, 'pending');
153
+ if (entry.reply && (entry.reply.status !== 'unknown' || entry.final)) return { ...entry.reply, repeated: true };
154
+ if (active.size >= MAX_APPLIES || [...active].some(e => sameSoul(e, entry)) || !submitted.has(entry.ref) && submitted.size >= 32) return denied('E_BUSY', entry);
155
+ const current = select(entry.input, getContext);
156
+ if (!same(entry, current)) return denied('E_PLAN_CHANGED', entry);
157
+ if (entry.key && observedGone(entry, getContext)) {
158
+ entry.reply = denied('E_INSTANCE_GONE', entry, 'refused'); return entry.reply;
159
+ }
160
+ const key = entry.key || freshId();
161
+ if (!key) return denied('E_BUSY', entry);
162
+ // Reserve key, slot and submitted record BEFORE any await. Key persists on
163
+ // this intent through unknown results; neither result nor retry can mint one.
164
+ entry.key = key; entry.pending = true; entry.expires = Infinity; active.add(entry);
165
+ prepared.delete(entry.ref); submitted.set(entry.ref, entry);
166
+ const run = (async () => {
167
+ let reply;
168
+ try {
169
+ const latest = select(entry.input, getContext);
170
+ if (!same(entry, latest)) reply = denied('E_PLAN_CHANGED', entry, 'refused');
171
+ else {
172
+ const result = await invoke(latest.cli, { target: clone(entry.target), choices: clone(entry.input.choices), task: entry.input.task,
173
+ ...(entry.input.wake ? { wake: clone(entry.input.wake) } : {}), decision: clone(entry.preview.decision), key: entry.key, deadlineMs: entry.deadlineMs }, ...io);
174
+ reply = interpret(result, entry, latest.cli);
175
+ }
176
+ } catch { reply = denied('E_OUTCOME_UNKNOWN', entry, 'unknown'); }
177
+ // This result belongs to its original entry even if a view/workspace changed.
178
+ // The caller's current context is checked separately on both settlement paths.
179
+ entry.reply = reply; // internal preview sharing; every outward response is cloned
180
+ entry.pending = false; entry.expires = now() + 30 * 60000; active.delete(entry);
181
+ return reply;
182
+ })();
183
+ // Answer within answerWithinMs: the outcome, or `pending` while the CLI keeps running here.
184
+ let cancel = () => {};
185
+ const late = new Promise(resolve => { cancel = timer(() => resolve(null), answerWithinMs); });
186
+ const reply = await Promise.race([run, late]);
187
+ cancel();
188
+ if (!reply) {
189
+ void run.then(() => { try { settled?.(); } catch { /* a refresh must not lose an outcome */ } });
190
+ return display(entry, 'pending');
191
+ }
192
+ return ownsScope(entry, getContext) ? reply : denied('E_OUTCOME_UNKNOWN', entry, 'unknown');
193
+ }
194
+ /** `settled()` is called when an apply answered `pending` settles later (the route refreshes then). */
195
+ return async function spawnApplyRequest(request, getContext, { settled } = {}) {
196
+ try {
197
+ sweep();
198
+ if (!record(request)) return denied('E_BAD_ARGS');
199
+ if (request.action === 'prepare') {
200
+ const input = spawnPrepareInput(request);
201
+ return clone(input ? await prepare(input, getContext) : denied('E_BAD_ARGS'));
202
+ }
203
+ const r = spawnRefInput(request);
204
+ if (!r) return denied('E_BAD_ARGS');
205
+ const found = get(r.spawnRef, getContext);
206
+ if (found.failure) return clone(found.failure);
207
+ const e = found.entry;
208
+ if (r.action === 'result') return clone(e.pending ? display(e, 'pending') : e.reply || display(e, 'prepared'));
209
+ return clone(await apply(e, getContext, settled));
210
+ } catch { return denied('E_CLI_FAILED'); }
211
+ };
212
+ }
@@ -1,113 +1,128 @@
1
- /** Plain-language wording for the Spawn dialog's problems.
1
+ /** Plain-language wording for a spawn's problems and outcomes, shared by every client (#855, 6b-2).
2
2
  *
3
3
  * The preview/apply contracts carry a stable code and a technical message
4
- * (the kernel's own text for kernel refusals — paths, hashes, commands). The
5
- * dialog shows the operator one sentence about what happened and what to do;
6
- * the code and the technical message stay available behind "Details" for
7
- * troubleshooting. Wording only: no decision here depends on the text. */
4
+ * (the kernel's own text for kernel refusals — paths, hashes, commands). A
5
+ * client shows the operator what happened (`fact`) and, in its own words, what
6
+ * to do (`next`); the code and the technical message stay available as
7
+ * `detail` for troubleshooting. The Desktop's sentences are composed in
8
+ * packages/desktop/renderer/spawn-words.mjs. Wording only: no decision here
9
+ * depends on the text. */
8
10
  import { displayLine } from './display-text.mjs';
9
11
  import { ROLLED_BACK_CODES } from './spawn-apply-contract.mjs';
12
+ import { retainedSpawnMessage } from './launch-prompt-outcome.mjs';
10
13
 
11
14
  const UNMATCHED = 'E_LAUNCH_PREFERENCE_UNMATCHED';
12
15
 
13
- const COMMON = {
14
- E_BAD_ARGS: 'Some of these values can’t be used. Check the name and Developer settings.',
15
- E_BUSY: 'Another spawn is in progress. Try again in a moment.',
16
- E_FORBIDDEN_FRAME: 'This window can’t start a spawn.',
17
- E_PREVIEW_UNAVAILABLE: 'Spawning needs a newer OATS. Update OATS, then open this dialog again.',
18
- E_APPLY_UNAVAILABLE: 'Spawning needs a newer OATS. Update OATS, then open this dialog again.',
19
- E_WORKSPACE_UNKNOWN: 'This workspace isn’t available anymore. Choose it again from the workspace menu.',
20
- E_SOUL_UNKNOWN: 'This soul isn’t in the workspace anymore. Sync the workspace and try again.',
21
- E_SOUL_AMBIGUOUS: 'Two repositories declare a soul with this name, so it can’t be spawned until one is renamed.',
22
- E_UNSUPPORTED_MODE: 'This soul can’t be started on its own from here.',
23
- 'unsupported-remote-operation': 'The execution server decides this soul’s defaults.',
24
- E_UNSUPPORTED_OPTION: 'One of the options you chose isn’t supported here. Set it back to the default and try again.',
25
- E_RELATIVE_AMBIGUOUS: 'The instance you picked for the relationship can’t be told apart from another one. Pick it again.',
26
- E_SESSION_UNKNOWN: 'The instance you picked for the relationship isn’t available anymore. Pick another one.',
27
- E_HOME_MISMATCH: 'The instance you picked for the relationship isn’t available anymore. Pick another one.',
28
- E_CHILD_SPAWNS_DISABLED: 'The parent you picked doesn’t allow child instances. Pick another one, or choose None.',
29
- E_BRANCH_EXISTS: 'That branch already exists. Choose another branch in Developer settings.',
30
- E_BASE_UNKNOWN: 'That base isn’t a branch, tag or commit in this soul’s repository. Check it in Developer settings.',
31
- E_CLONE_MISSING: 'This soul’s repository isn’t cloned on this machine yet. Clone it, then try again — Details shows how.',
32
- E_LAUNCH_ENV_MISSING: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
33
- E_LAUNCH_EXECUTABLE: 'The chosen launch configuration can’t start on this machine. Choose another in Developer settings.',
34
- E_LAUNCH_PROBE_UNSUPPORTED: 'The chosen launch configuration can’t be checked safely. Choose another in Developer settings.',
35
- E_LAUNCH_CONFIG_UNKNOWN: 'That launch configuration no longer exists. Choose another in Developer settings.',
36
- // 0.52.0: the kernel refuses a spawn that names no launch configuration where the harness has several and
37
- // none is the default. The sentence names the dialog's own control; the kernel's message, which ends with
38
- // its command-line fix, stays in Details.
39
- E_LAUNCH_CONFIG_AMBIGUOUS: 'This machine has more than one launch configuration for this soul’s harness, and none is the default. Choose one under Launch configuration in Developer settings.',
40
- // 0.30 launch preferences: shown in the kernel's own words when it sends them (spawnProblem: the
41
- // message, then the reason's flat `fix`), which name the harness and where it was chosen; this is the fallback.
42
- E_HARNESS_UNAVAILABLE: 'The harness this soul would run isn’t installed on this machine. Install it, or pick another harness above.',
43
- // 0.53.0: the kernel refuses a spawn that names no launch while `souls.launch` holds a key that names no
44
- // soul. This sentence points at the controls above it and at Details, so it is read only where both are
45
- // there: at the preview, with the kernel's message and fix quoted under Details (spawnProblem's `kernel`
46
- // parts). Everywhere else the shorter one of SPAWN is read.
47
- [UNMATCHED]: 'This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness above, or a launch configuration in Developer settings. To fix it for every spawn, correct the preference (Details).',
48
- E_MODEL_UNKNOWN: 'That model isn’t available for this harness. Pick another model, or keep the default.',
49
- E_INSTANCE_NAME_INVALID: 'Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.',
50
- E_INSTANCE_NAME_TAKEN: 'An instance with this name already exists. Choose another name.',
51
- E_PACKAGE_MISSING: 'A package this soul uses isn’t installed yet. Run Sync in the Workspace view.',
52
- E_PACKAGE_INTEGRITY: 'A package this soul uses no longer matches the lock. Run Sync in the Workspace view.',
53
- E_TARGET_CHANGED: 'The workspace changed while this was loading. Reading it again…',
54
- E_PLAN_CHANGED: 'The workspace changed while this was loading. Check the values and press Spawn again.',
55
- };
16
+ /** The act that follows a problem or an outcome, where the sentence a client shows names one (#855, 6b-2): the
17
+ * client says it in its own words, naming its own controls. Closed and frozen: a new code is a SURFACE change,
18
+ * with the TUI's lead told.
19
+ * change-options change an option of this spawn
20
+ * review-again look at the values again and confirm again
21
+ * check-result read the outcome again before spawning again
22
+ * update-oats update OATS, then try again
23
+ * choose-workspace choose the workspace again
24
+ * sync-workspace sync the workspace
25
+ * details the kernel's detail says more
26
+ * retire retire the instance to finish its cleanup
27
+ * view-schedules open the schedules
28
+ * open-from-list open the instance from the instance list */
29
+ export const SPAWN_NEXT = Object.freeze(['change-options', 'review-again', 'check-result', 'update-oats', 'choose-workspace',
30
+ 'sync-workspace', 'details', 'retire', 'view-schedules', 'open-from-list']);
56
31
 
57
- const PREVIEW = {
58
- E_CLI_TIMEOUT: 'OATS took too long to work out this soul’s defaults. Try again.',
59
- E_CLI_OUTPUT_LIMIT: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
60
- E_CLI_PROTOCOL: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
61
- E_CLI_FAILED: 'OATS couldn’t work out this soul’s defaults. Try again, or see Details.',
32
+ /** The shared fact of each code, and its `next` where the sentence goes on to name an act. What every client
33
+ * says alike stays in the fact: the instance list, syncing the workspace, "Try again.", "Pick it again.". */
34
+ const said = (fact, next = null) => Object.freeze({ fact, next });
35
+ const COMMON_FACTS = {
36
+ E_BAD_ARGS: said('Some of these values can’t be used.', 'change-options'),
37
+ E_BUSY: said('Another spawn is in progress. Try again in a moment.'),
38
+ E_PREVIEW_UNAVAILABLE: said('Spawning needs a newer OATS.', 'update-oats'),
39
+ E_APPLY_UNAVAILABLE: said('Spawning needs a newer OATS.', 'update-oats'),
40
+ E_WORKSPACE_UNKNOWN: said('This workspace isn’t available anymore.', 'choose-workspace'),
41
+ E_SOUL_UNKNOWN: said('This soul isn’t in the workspace anymore. Sync the workspace and try again.'),
42
+ E_SOUL_AMBIGUOUS: said('Two repositories declare a soul with this name, so it can’t be spawned until one is renamed.'),
43
+ E_UNSUPPORTED_MODE: said('This soul can’t be started on its own from here.'),
44
+ 'unsupported-remote-operation': said('The execution server decides this soul’s defaults.'),
45
+ E_UNSUPPORTED_OPTION: said('One of the options you chose isn’t supported here. Set it back to the default and try again.'),
46
+ E_RELATIVE_AMBIGUOUS: said('The instance you picked for the relationship can’t be told apart from another one. Pick it again.'),
47
+ E_SESSION_UNKNOWN: said('The instance you picked for the relationship isn’t available anymore. Pick another one.'),
48
+ E_HOME_MISMATCH: said('The instance you picked for the relationship isn’t available anymore. Pick another one.'),
49
+ E_CHILD_SPAWNS_DISABLED: said('The parent you picked doesn’t allow child instances.', 'change-options'),
50
+ E_BRANCH_EXISTS: said('That branch already exists.', 'change-options'),
51
+ E_BASE_UNKNOWN: said('That base isn’t a branch, tag or commit in this soul’s repository.', 'change-options'),
52
+ E_CLONE_MISSING: said('This soul’s repository isn’t cloned on this machine yet. Clone it, then try again.', 'details'),
53
+ E_LAUNCH_ENV_MISSING: said('The chosen launch configuration can’t start on this machine.', 'change-options'),
54
+ E_LAUNCH_EXECUTABLE: said('The chosen launch configuration can’t start on this machine.', 'change-options'),
55
+ E_LAUNCH_PROBE_UNSUPPORTED: said('The chosen launch configuration can’t be checked safely.', 'change-options'),
56
+ E_LAUNCH_CONFIG_UNKNOWN: said('That launch configuration no longer exists.', 'change-options'),
57
+ E_LAUNCH_CONFIG_AMBIGUOUS: said('This machine has more than one launch configuration for this soul’s harness, and none is the default.', 'change-options'),
58
+ // The fallback, where the kernel sent no words of its own (spawnProblem quotes them, with no `next`).
59
+ E_HARNESS_UNAVAILABLE: said('The harness this soul would run isn’t installed on this machine.', 'change-options'),
60
+ // At the preview, with the kernel's message and fix as `kernel` parts: the client names its own controls.
61
+ [UNMATCHED]: said('This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul.', 'change-options'),
62
+ E_MODEL_UNKNOWN: said('That model isn’t available for this harness. Pick another model, or keep the default.'),
63
+ E_INSTANCE_NAME_INVALID: said('Use lowercase letters, numbers and dashes, at most 64 characters, and don’t reuse a soul’s name.'),
64
+ E_INSTANCE_NAME_TAKEN: said('An instance with this name already exists. Choose another name.'),
65
+ E_PACKAGE_MISSING: said('A package this soul uses isn’t installed yet.', 'sync-workspace'),
66
+ E_PACKAGE_INTEGRITY: said('A package this soul uses no longer matches the lock.', 'sync-workspace'),
67
+ E_TARGET_CHANGED: said('The workspace changed while this was loading. Reading it again…'),
68
+ E_PLAN_CHANGED: said('The workspace changed while this was loading.', 'review-again'),
62
69
  };
63
-
64
- const SPAWN = {
65
- E_PLAN_REQUIRED: 'Check the values and press Spawn to confirm.',
66
- E_DECISION_STALE: 'Something changed before the spawn went through. Nothing was created — check the updated values and press Spawn again.',
67
- E_IDEMPOTENCY_CONFLICT: 'Something changed before the spawn went through. Nothing was created — check the updated values and press Spawn again.',
68
- E_PLACEMENT_TAKEN: 'Another spawn just took this name. Nothing was created — check the new name and press Spawn again.',
69
- E_INTENT_EXPIRED: 'This spawn request expired. Check the instance list before spawning again.',
70
- E_PREFLIGHT_INCOMPLETE: 'OATS couldn’t finish checking this spawn. Try again.',
71
- E_BACKEND_UNAVAILABLE: 'That session backend isn’t installed on this machine. Choose another in Developer settings.',
72
- E_INSTANCE_GONE: 'The instance that was created isn’t there anymore. Check the instance list.',
73
- E_OUTCOME_UNKNOWN: 'We couldn’t confirm whether the instance was created. Use Check result before spawning again.',
74
- E_SPAWN_INCOMPLETE: 'The instance was created but didn’t finish starting. Open it from the instance list instead of spawning again.',
75
- E_INPUT_PREPARATION: 'The opening instruction couldn’t be prepared, so nothing was started. Try again.',
76
- E_CLI_TIMEOUT: 'OATS took too long to answer. The instance may already exist — use Check result before spawning again.',
77
- E_CLI_OUTPUT_LIMIT: 'OATS couldn’t confirm the spawn. Use Check result before spawning again.',
78
- E_CLI_PROTOCOL: 'OATS couldn’t complete the spawn. Try again, or see Details.',
79
- E_CLI_FAILED: 'OATS couldn’t complete the spawn. Try again, or see Details.',
80
- // An unmatched launch preference where nothing is above the sentence and Details hold no kernel text: the
81
- // notice after a press has left the dialog, and a preview whose reason carries no `fix`.
82
- [UNMATCHED]: 'This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.',
70
+ const PREVIEW_FACTS = {
71
+ E_CLI_TIMEOUT: said('OATS took too long to work out this soul’s defaults. Try again.'),
72
+ E_CLI_OUTPUT_LIMIT: said('OATS couldn’t work out this soul’s defaults.', 'details'),
73
+ E_CLI_PROTOCOL: said('OATS couldn’t work out this soul’s defaults.', 'details'),
74
+ E_CLI_FAILED: said('OATS couldn’t work out this soul’s defaults.', 'details'),
75
+ };
76
+ const SPAWN_FACTS = {
77
+ E_DECISION_STALE: said('Something changed before the spawn went through. Nothing was created.', 'review-again'),
78
+ E_IDEMPOTENCY_CONFLICT: said('Something changed before the spawn went through. Nothing was created.', 'review-again'),
79
+ E_PLACEMENT_TAKEN: said('Another spawn just took this name. Nothing was created.', 'review-again'),
80
+ E_INTENT_EXPIRED: said('This spawn request expired. Check the instance list before spawning again.'),
81
+ E_PREFLIGHT_INCOMPLETE: said('OATS couldn’t finish checking this spawn. Try again.'),
82
+ E_BACKEND_UNAVAILABLE: said('That session backend isn’t installed on this machine.', 'change-options'),
83
+ E_INSTANCE_GONE: said('The instance that was created isn’t there anymore. Check the instance list.'),
84
+ E_OUTCOME_UNKNOWN: said('We couldn’t confirm whether the instance was created.', 'check-result'),
85
+ E_SPAWN_INCOMPLETE: said('The instance was created but didn’t finish starting. Open it from the instance list instead of spawning again.'),
86
+ E_INPUT_PREPARATION: said('The opening instruction couldn’t be prepared, so nothing was started. Try again.'),
87
+ E_CLI_TIMEOUT: said('OATS took too long to answer. The instance may already exist.', 'check-result'),
88
+ E_CLI_OUTPUT_LIMIT: said('OATS couldn’t confirm the spawn.', 'check-result'),
89
+ E_CLI_PROTOCOL: said('OATS couldn’t complete the spawn.', 'details'),
90
+ E_CLI_FAILED: said('OATS couldn’t complete the spawn.', 'details'),
91
+ // Wherever nothing is above the sentence and Details hold no kernel text: the whole of it is shared.
92
+ [UNMATCHED]: said('This machine’s launch preferences name a soul this workspace doesn’t offer, so OATS won’t choose a launch for this soul. To spawn now, pick a harness or a launch configuration for this spawn. To fix it for every spawn, correct the preference.'),
83
93
  };
84
94
 
85
- /** { text, code, detail } for a { code, message } reason. `stage` is 'preview'
95
+ /** { fact, next, code, detail } for a { code, message } reason. `stage` is 'preview'
86
96
  * (reading defaults) or 'spawn' (after the operator pressed Spawn).
87
97
  *
88
98
  * For an unmatched launch preference whose reason carries the kernel's `fix`, the answer also has
89
99
  * `kernel: { message, fix }`: the kernel's two texts, the strings as they came, for the client to quote
90
- * under the kernel's name (the lead is the client's, `originLead` with its terms). `detail` is then the
100
+ * under the kernel's name (the lead is the client's, `originLead` with its terms), and the fact is the
101
+ * sentence's lead, with the client's controls as `next`. `detail` is then the
91
102
  * code alone, so that no reader of `detail` shows a kernel text without its speaker. A `fix` decides it
92
103
  * because `previewFailure` keeps one only beside the kernel's own message, never beside a table's sentence:
93
104
  * a reason without one (a press, a kernel that sent none, a message that did not travel) reads
94
- * `code · message` as every other code does. */
105
+ * `code · message` as every other code does.
106
+ *
107
+ * `fact` is what happened, in words every client shows alike, and `next` the act that follows (SPAWN_NEXT),
108
+ * or null where the fact says all: the client puts its own words for `next` after the fact. A code the
109
+ * tables do not know reads the stage's E_CLI_FAILED fact, with its own code. */
95
110
  export function spawnProblem(reason, stage = 'preview') {
96
111
  const code = typeof reason?.code === 'string' ? reason.code : 'E_CLI_FAILED';
97
- const own = stage === 'spawn' ? SPAWN : PREVIEW;
98
112
  const message = typeof reason?.message === 'string' ? reason.message.trim() : '';
99
113
  // A missing harness is said as the kernel words it, with its fix (launch preferences, 0.30).
100
114
  const fix = typeof reason?.fix === 'string' ? reason.fix.trim() : '';
101
115
  if (code === UNMATCHED) {
102
116
  const kernel = fix ? { message: typeof reason.message === 'string' ? reason.message : '', fix: reason.fix } : null;
103
- // The sentence that says "above" and "(Details)" is read only where Details hold the kernel's texts.
104
- if (kernel) return { text: stage === 'preview' ? COMMON[UNMATCHED] : SPAWN[UNMATCHED], code, detail: code, kernel };
105
- return { text: SPAWN[UNMATCHED], code, detail: message ? `${code} · ${message}` : code };
117
+ // The client's controls are named only where Details hold the kernel's texts.
118
+ if (kernel) return { ...(stage === 'preview' ? COMMON_FACTS : SPAWN_FACTS)[UNMATCHED], code, detail: code, kernel };
119
+ return { ...SPAWN_FACTS[UNMATCHED], code, detail: message ? `${code} · ${message}` : code };
106
120
  }
107
121
  // The kernel's message usually already ends with its fix: said once.
108
122
  const kernelWords = code === 'E_HARNESS_UNAVAILABLE' && message ? (fix && !message.includes(fix) ? `${message.replace(/[.\s]+$/, '')}: ${fix}` : message) : null;
109
- const text = kernelWords ?? own[code] ?? COMMON[code] ?? (stage === 'spawn' ? SPAWN.E_CLI_FAILED : PREVIEW.E_CLI_FAILED);
110
- return { text, code, detail: message ? `${code} · ${message}` : code };
123
+ const facts = stage === 'spawn' ? SPAWN_FACTS : PREVIEW_FACTS;
124
+ const words = kernelWords ? said(kernelWords) : facts[code] ?? COMMON_FACTS[code] ?? facts.E_CLI_FAILED;
125
+ return { fact: words.fact, next: words.next, code, detail: message ? `${code} · ${message}` : code };
111
126
  }
112
127
 
113
128
  /** The spawn catalog's state, for the soul chooser. */
@@ -126,16 +141,47 @@ export function catalogProblem(catalog) {
126
141
  export function rolledBackProblem(reason, instance) {
127
142
  const code = reason?.code;
128
143
  if (!ROLLED_BACK_CODES.includes(code)) return null;
129
- const text = code === 'E_INTERRUPTED'
144
+ const fact = code === 'E_INTERRUPTED'
130
145
  ? `The spawn of ${instance} was interrupted while its worktree was being set up, and was rolled back. Nothing was created.`
131
146
  : `A capability couldn’t set up the worktree for ${instance}, so the spawn was rolled back. Nothing was created.`;
132
- return { text, code, detail: kernelDetail(code, reason.message) };
147
+ return { fact, next: null, code, detail: kernelDetail(code, reason.message) };
133
148
  }
149
+ /** `instance` travels with the answer: the client names it in its words for `next` (retire). */
134
150
  export function cleanupOwedProblem(reason, instance) {
135
151
  if (!ROLLED_BACK_CODES.includes(reason?.code)) return null;
136
- return { text: `The spawn of ${instance} was stopped, but its cleanup didn’t finish. Retire ${instance} from the roster to complete it.`,
152
+ return { fact: `The spawn of ${instance} was stopped, but its cleanup didn’t finish.`, next: 'retire', instance,
137
153
  code: reason.code, detail: kernelDetail(reason.code, reason.message) };
138
154
  }
155
+
156
+ /** A spawn transaction's outcome in shared words (spawn-transaction.mjs `kind`), as { fact, next } for the
157
+ * client to say with its own words for `next`; `instance` is the name the spawn was given. null for a kind whose
158
+ * words are its reason's (unknown, refused: spawnProblem(outcome.reason, 'spawn')).
159
+ * created complete: "Created <i>." (launched), "Created <i> — not launched." (open-from-list);
160
+ * partial: the reason's message (view-schedules), or, for a wake whose outcome is unknown,
161
+ * "Agent created; wake outcome unavailable." (the boundary's message names the Desktop's
162
+ * Schedules: that act is view-schedules); incomplete: the retained spawn's sentence
163
+ * not-yet-visible created, and not in the instance list as a running session in time (open-from-list)
164
+ * pending-expired still running at the deadline (check-result)
165
+ * cleanup-owed cleanupOwedProblem's (retire); rolled-back: rolledBackProblem's
166
+ * never-submitted prepared, never applied (review-again)
167
+ * drifted the values changed since they were confirmed (review-again) */
168
+ export function outcomeWords(kind, view, instance) {
169
+ if (kind === 'created') {
170
+ if (view?.status === 'incomplete') return said(retainedSpawnMessage(view.incomplete));
171
+ if (view?.status === 'partial' && view.reason?.code === 'E_WAKE_OUTCOME_UNKNOWN') return said('Agent created; wake outcome unavailable.', 'view-schedules');
172
+ if (view?.status === 'partial') return said(view.reason?.message || `Created ${instance}.`, 'view-schedules');
173
+ return view?.receipt?.launched === false ? said(`Created ${instance} — not launched.`, 'open-from-list') : said(`Created ${instance}.`);
174
+ }
175
+ if (kind === 'not-yet-visible') return said(`Created ${instance} — not yet visible as a running session.`, 'open-from-list');
176
+ if (kind === 'pending-expired') return said('The spawn is still running.', 'check-result');
177
+ if (kind === 'cleanup-owed' || kind === 'rolled-back') {
178
+ const problem = (kind === 'cleanup-owed' ? cleanupOwedProblem : rolledBackProblem)(view?.reason, instance);
179
+ return problem ? said(problem.fact, problem.next) : null;
180
+ }
181
+ if (kind === 'never-submitted') return said('That spawn was never submitted.', 'review-again');
182
+ if (kind === 'drifted') return said('These values changed since you last looked.', 'review-again');
183
+ return null;
184
+ }
139
185
  function kernelDetail(code, message) {
140
186
  const line = displayLine(message);
141
187
  return line ? `${code} · ${line}` : code;
@@ -180,6 +180,9 @@ export function previewChoices(v) {
180
180
  }
181
181
  return out;
182
182
  }
183
+ /** The choices of a spawn with no field touched (#855, 6b-2): what a client sends before the operator changes
184
+ * anything (the soul's own model, no relation). A fresh object each call, for the client to change. */
185
+ export const defaultSpawnChoices = () => previewChoices({});
183
186
  /** The spawn flags for admitted choices — shared by preview and apply. The
184
187
  * harness flag is the kernel's (feature harness: --harness; a released kernel: --runtime). */
185
188
  export function choiceArgv(choices, cli) {