@awebai/oats 0.69.1 → 0.69.3

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 (71) hide show
  1. package/bin/oats.mjs +79 -15
  2. package/docs/capabilities.md +24 -5
  3. package/docs/capability-manifest.schema.json +1 -1
  4. package/docs/design/2026-09-23-workspace-module-contracts.md +6 -4
  5. package/docs/design/2026-10-22-module-upgrade.md +1 -1
  6. package/docs/desktop-cli-api.md +273 -66
  7. package/docs/desktop-instance-start.md +8 -37
  8. package/docs/desktop.md +76 -9
  9. package/docs/execution-targets.md +27 -5
  10. package/docs/implementation.md +6 -5
  11. package/docs/integrations.md +1 -1
  12. package/docs/knowledge.md +25 -16
  13. package/docs/official-catalog.md +4 -4
  14. package/docs/packages.md +12 -12
  15. package/docs/release-notes/v0.69.2.md +259 -0
  16. package/docs/release-notes/v0.69.3.md +43 -0
  17. package/docs/servers.md +7 -2
  18. package/docs/soul.schema.json +1 -0
  19. package/docs/souls-and-instances.md +35 -2
  20. package/docs/tui.md +112 -15
  21. package/docs/upgrading.md +9 -5
  22. package/docs/workspaces.md +2 -2
  23. package/injects/instance-boundary.md +19 -33
  24. package/injects/work-attached.md +8 -13
  25. package/injects/work-checkout.md +16 -30
  26. package/injects/work-directory.md +9 -15
  27. package/injects/work-workspace.md +8 -19
  28. package/injects/work-worktree.md +18 -33
  29. package/lib/capability-contract.mjs +2 -2
  30. package/lib/core.mjs +162 -49
  31. package/lib/instance-background.mjs +54 -0
  32. package/lib/instance-inspect.mjs +3 -0
  33. package/lib/instance-lifecycle.mjs +35 -0
  34. package/lib/instance-resolution.mjs +3 -2
  35. package/lib/instance-same-work.mjs +67 -0
  36. package/lib/instance-upgrade.mjs +18 -0
  37. package/lib/materialize.mjs +23 -2
  38. package/lib/resolve.mjs +32 -5
  39. package/lib/servers.mjs +19 -4
  40. package/lib/session-resume-contract.mjs +1 -0
  41. package/lib/session-resume.mjs +36 -9
  42. package/lib/soul-composition.mjs +13 -10
  43. package/lib/workspace.mjs +3 -2
  44. package/package-catalog.json +3 -3
  45. package/package.json +1 -1
  46. package/packages/client/cli-adapter.mjs +30 -8
  47. package/packages/client/deployment-data.mjs +9 -0
  48. package/packages/client/deployment-panel.mjs +4 -0
  49. package/packages/client/instance-tree.mjs +64 -14
  50. package/packages/client/launch-prompt-outcome.mjs +1 -1
  51. package/packages/client/panel-views.mjs +11 -3
  52. package/packages/client/remote-roster.mjs +5 -1
  53. package/packages/client/roster-sections.mjs +50 -6
  54. package/packages/client/same-work.mjs +49 -0
  55. package/packages/client/session-resume-trigger.mjs +15 -37
  56. package/packages/client/session-resume.mjs +22 -259
  57. package/packages/client/soul-rows.mjs +2 -0
  58. package/packages/client/spawn-apply-contract.mjs +2 -1
  59. package/packages/client/spawn-decision.mjs +4 -1
  60. package/packages/client/spawn-preview-contract.mjs +12 -1
  61. package/packages/client/spawn-preview.mjs +2 -0
  62. package/packages/tui/README.md +2 -2
  63. package/packages/tui/lib/client.mjs +6 -2
  64. package/packages/tui/lib/main.mjs +44 -11
  65. package/packages/tui/lib/model.mjs +101 -43
  66. package/packages/tui/lib/panel.mjs +23 -13
  67. package/packages/tui/lib/store.mjs +76 -20
  68. package/packages/tui/lib/views/frame.mjs +2 -0
  69. package/packages/tui/lib/views/help.mjs +2 -0
  70. package/packages/tui/lib/views/instances.mjs +38 -1
  71. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -1,133 +1,47 @@
1
- /** The machine sweep's answer (`oats session resume --json`, feature `session-resume`), read into a summary of
2
- * facts and put into the clients' words. session-resume-cli.mjs runs it; this module reads what came back.
3
- * Shared by the Desktop and the TUI: pure, no IO, no DOM, never throws on data (only resumeNotice throws, on
4
- * a caller's missing `label`). No sentence names a client's control, so no client terms are needed.
1
+ /** The machine sweep's answer (`oats session resume --json`, feature `session-resume`), read into one of four
2
+ * readings, and the trigger's settlement helpers (session-resume-trigger.mjs). session-resume-cli.mjs runs the
3
+ * sweep; this module reads what came back. Shared by the Desktop and the TUI: pure, no IO, no DOM, never throws
4
+ * on data.
5
5
  *
6
6
  * The answer: `{schemaVersion: 1, plan, deployments: [{deployment, state, swept, reason?, …}], rows:
7
- * [{deployment, instance, outcome, reason?, code?, message?, warnings?, …}], warnings?}`; the result's own
8
- * `warnings` are about the host, not one home. The summary:
9
- * { resumed: [{instance, deployment, warnings, omitted}],
10
- * fresh: [{instance, deployment, reason, warnings, omitted}], reason: FRESH_REASONS or null
11
- * waiting: [{instance, deployment, reason}], a `blocked` row; reason: WAITING_REASONS or null
12
- * refused: [{instance, deployment, reason, code, message}], reason: REFUSED_REASONS or null
13
- * unswept: [{deployment, reason}], not swept; reason: UNSWEPT_REASONS or null
14
- * host: {warnings, omitted}, the result's warnings, bounded as a row's
15
- * omitted, totals: {resumed, fresh, waiting, refused} }
16
- * `refused` carries `reason` beside the four fields the spec lists: the words say when a refusal was this
17
- * boot's, and when the home keeps losing its session. There is no opt-out: an older kernel's `opted-out`
18
- * deployment is unswept with reason null. Nothing is read from the kernel's words: no sentence, warning or
19
- * message is matched. Names, paths, warnings and messages are display lines (display-text.mjs): labels and
20
- * quotes, never used to address anything. A refused `message` is kernel prose, shown only after `OATS says:`,
21
- * never alone with its `code`.
22
- *
23
- * Tolerant per entry: a row or deployment that does not decode (not a record, a name or path that is not a
24
- * string, empty or withheld, an unknown outcome) is dropped alone; an unknown reason under a known outcome is
25
- * null and worded generically; a code not of the kernel's form is null. `already-running` and `skipped` rows
26
- * are counted nowhere and shown nowhere. The answer around them is closed: one that is not the document (no
27
- * schemaVersion 1, `plan` not a boolean, `deployments` or `rows` not an array, or either longer than
7
+ * [{deployment, instance, home, outcome, reason?, code?, message?, warnings?, …}], warnings?}`. Neither client
8
+ * shows anything of it (docs/desktop-instance-start.md, "Nothing is shown"): the reader says only whether it
9
+ * answered, and the trigger reads its rows' homes and outcomes to settle and release homes. Nothing is read from
10
+ * the kernel's words: no sentence, warning or message is matched. The answer is closed: one that is not the
11
+ * document (no schemaVersion 1, `plan` not a boolean, `deployments` or `rows` not an array, or either longer than
28
12
  * RESUME_ANSWER_ENTRIES) is a protocol failure, never read in part. */
29
- import { displayLine, cleanLine, DETAIL_WITHHELD } from './display-text.mjs';
30
- import { boundedWarnings, boundedWarningsValid } from './launch-prompt-outcome.mjs';
31
13
 
32
- /** At most this many rows (over resumed, fresh, waiting and refused, in the answer's order) and, apart, this
33
- * many unswept deployment lines (in the answer's order) are kept. What is left out is counted in `omitted`;
34
- * `totals` keeps the real counts of the rows, which the headline uses. */
35
- export const RESUME_SUMMARY_ROWS = 100;
36
- export const RESUME_SUMMARY_DEPLOYMENTS = 100;
37
- /** The longest `rows` or `deployments` this reader reads: more is a protocol failure, not a summary. */
14
+ /** The longest `rows` or `deployments` this reader reads: more is a protocol failure, not an answer. */
38
15
  export const RESUME_ANSWER_ENTRIES = 100_000;
39
16
  /** A row's `outcome`, by name: the one place a client spells them. */
40
17
  export const RESUME_OUTCOMES = Object.freeze({ resumed: 'resumed', fresh: 'fresh', blocked: 'blocked', refused: 'refused',
41
18
  alreadyRunning: 'already-running', skipped: 'skipped' });
42
- /** A `skipped` row's reasons, by name. A skipped row is counted and shown nowhere, whatever its reason. */
19
+ /** A `skipped` row's reasons, by name. */
43
20
  export const SKIPPED_REASONS = Object.freeze({ notLost: 'not-lost', notSeenRecently: 'not-seen-recently', startBusy: 'start-busy',
44
21
  unknown: 'unknown' });
45
22
  /** The skipped reasons that settle a home (sweepSettlement): it is not lost, or the kernel did not recently see it
46
23
  * running (its status still reads lost, and every sweep would skip it again). */
47
24
  export const SETTLING_SKIPPED_REASONS = Object.freeze([SKIPPED_REASONS.notLost, SKIPPED_REASONS.notSeenRecently]);
48
- export const FRESH_REASONS = Object.freeze(['no-conversation', 'no-receipts', 'resume-unproven']);
49
- export const WAITING_REASONS = Object.freeze(['resume-confirmation', 'launch-prompt']);
50
- export const REFUSED_REASONS = Object.freeze(['start-refused', 'refused-this-boot', 'keeps-getting-lost']);
51
- export const UNSWEPT_REASONS = Object.freeze(['not-ok', 'unreadable']);
52
25
  /** The ok:false codes that mean nothing ran: no compatible CLI, or one without the feature. */
53
26
  const UNSUPPORTED = new Set(['E_CLI_UNAVAILABLE', 'E_RESUME_FEATURE']);
54
27
  const CODE = /^E_[A-Z0-9_]{1,64}$/;
55
- const KINDS = ['resumed', 'fresh', 'waiting', 'refused'];
56
- const SUMMARY_KEYS = [...KINDS, 'unswept', 'host', 'omitted', 'totals'];
57
28
 
58
29
  const record = v => v !== null && typeof v === 'object' && !Array.isArray(v);
59
- const exactKeys = (v, keys) => record(v) && Object.keys(v).length === keys.length && keys.every(k => Object.hasOwn(v, k));
60
- const known = (list, v) => list.includes(v) ? v : null;
61
30
  const code = v => typeof v === 'string' && CODE.test(v) ? v : null;
62
- /** A name or a path as a label: one display line, null when it is withheld or there is nothing to show. */
63
- const label = v => { const line = displayLine(v); return line === DETAIL_WITHHELD ? null : line; };
64
- const named = v => cleanLine(v) && v !== DETAIL_WITHHELD;
65
- const count = v => Number.isSafeInteger(v) && v >= 0;
66
- const sum = totals => KINDS.reduce((n, k) => n + totals[k], 0);
67
-
68
- /** One counted row as its kind and fact, or null (dropped, or counted nowhere). */
69
- function decodeRow(row) {
70
- if (!record(row)) return null;
71
- const instance = label(row.instance), deployment = label(row.deployment);
72
- if (instance === null || deployment === null) return null;
73
- switch (row.outcome) {
74
- case RESUME_OUTCOMES.resumed: return ['resumed', { instance, deployment, ...boundedWarnings(row.warnings) }];
75
- case RESUME_OUTCOMES.fresh: return ['fresh', { instance, deployment, reason: known(FRESH_REASONS, row.reason), ...boundedWarnings(row.warnings) }];
76
- case RESUME_OUTCOMES.blocked: return ['waiting', { instance, deployment, reason: known(WAITING_REASONS, row.reason) }];
77
- case RESUME_OUTCOMES.refused: return ['refused', { instance, deployment, reason: known(REFUSED_REASONS, row.reason), code: code(row.code), message: displayLine(row.message) }];
78
- default: return null;
79
- }
80
- }
81
31
 
82
- /** One unswept deployment line, `{deployment, reason}`, or null (swept, or dropped). */
83
- function decodeDeployment(d) {
84
- if (!record(d)) return null;
85
- const deployment = label(d.deployment);
86
- if (deployment === null) return null;
87
- return d.swept === true ? null : { deployment, reason: known(UNSWEPT_REASONS, d.reason) };
88
- }
89
-
90
- const empty = () => ({ resumed: [], fresh: [], waiting: [], refused: [], unswept: [], host: { warnings: [], omitted: 0 }, omitted: 0,
91
- totals: { resumed: 0, fresh: 0, waiting: 0, refused: 0 } });
92
-
93
- /** Whether `result` is the sweep's document: the one check the summary and the trigger's helpers share. */
32
+ /** Whether `result` is the sweep's document: the one check the reader and the trigger's helpers share. */
94
33
  const sweepDocument = result => record(result) && result.schemaVersion === 1 && typeof result.plan === 'boolean'
95
34
  && Array.isArray(result.deployments) && Array.isArray(result.rows)
96
35
  && result.deployments.length <= RESUME_ANSWER_ENTRIES && result.rows.length <= RESUME_ANSWER_ENTRIES;
97
36
 
98
- /** The sweep's `result` as a summary, or null when it is not the document. A plan (`plan: true`) started
99
- * nothing, so it is the empty summary: none of its rows, deployments or warnings is read. The result's own
100
- * `warnings` (about the host) are kept as a row's are (boundedWarnings): a host warning alone is no row, so
101
- * it never makes a notice. */
102
- function summarize(result) {
103
- if (!sweepDocument(result)) return null;
104
- const s = empty();
105
- if (result.plan) return s;
106
- let rows = 0, lines = 0;
107
- for (const row of result.rows) {
108
- const decoded = decodeRow(row);
109
- if (!decoded) continue;
110
- const [kind, fact] = decoded;
111
- s.totals[kind] += 1;
112
- if (rows < RESUME_SUMMARY_ROWS) { s[kind].push(fact); rows += 1; } else s.omitted += 1;
113
- }
114
- for (const d of result.deployments) {
115
- const decoded = decodeDeployment(d);
116
- if (!decoded) continue;
117
- if (lines < RESUME_SUMMARY_DEPLOYMENTS) { s.unswept.push(decoded); lines += 1; } else s.omitted += 1;
118
- }
119
- s.host = boundedWarnings(result.warnings);
120
- return s;
121
- }
122
-
123
37
  /**
124
38
  * @param {unknown} envelope what runResumeSweep resolved: the kernel's envelope or a client read error
125
- * @returns {{kind: 'unsupported'} | {kind: 'busy'} | {kind: 'failed', code: string}
126
- * | {kind: 'quiet', summary} | {kind: 'notice', summary}}
39
+ * @returns {{kind: 'unsupported'} | {kind: 'busy'} | {kind: 'failed', code: string} | {kind: 'answered'}}
127
40
  * `unsupported`: nothing ran (no compatible CLI, or no feature). `busy`: another sweep holds the machine's
128
41
  * lock and nothing started. `failed`: any other refusal, with its code when it has the kernel's form, else
129
- * E_CLI_PROTOCOL, as is an answer that does not decode. `notice` when a row was resumed, fresh, blocked
130
- * or refused; `quiet` otherwise, also when only unswept deployments are left to say.
42
+ * E_CLI_PROTOCOL, as is an `ok: true` answer whose result is not the sweep's document (sweepDocument).
43
+ * `answered`: an `ok: true` answer whose result is the document, a plan too (a plan completes nothing:
44
+ * sweepCompleted). No reading carries anything of the answer's rows or words.
131
45
  */
132
46
  export function readResumeSweep(envelope) {
133
47
  if (record(envelope) && envelope.ok === false) {
@@ -136,14 +50,13 @@ export function readResumeSweep(envelope) {
136
50
  if (c === 'E_RESUME_BUSY') return { kind: 'busy' };
137
51
  return { kind: 'failed', code: code(c) ?? 'E_CLI_PROTOCOL' };
138
52
  }
139
- const summary = record(envelope) && envelope.ok === true ? summarize(envelope.result) : null;
140
- if (!summary) return { kind: 'failed', code: 'E_CLI_PROTOCOL' };
141
- return { kind: sum(summary.totals) > 0 ? 'notice' : 'quiet', summary };
53
+ if (record(envelope) && envelope.ok === true && sweepDocument(envelope.result)) return { kind: 'answered' };
54
+ return { kind: 'failed', code: 'E_CLI_PROTOCOL' };
142
55
  }
143
56
 
144
57
  /** The rows of an answer the trigger reads (session-resume-trigger.mjs): the rows of an `ok: true` envelope
145
58
  * whose result is the sweep's document (sweepDocument, as readResumeSweep reads it) and not a plan, else null:
146
- * an answer the reader fails or reads as nothing settles nothing and leaves nothing out. */
59
+ * an answer the reader fails, or a plan, settles nothing. */
147
60
  function answerRows(envelope) {
148
61
  const result = record(envelope) && envelope.ok === true ? envelope.result : undefined;
149
62
  return sweepDocument(result) && result.plan === false ? result.rows : null;
@@ -153,8 +66,6 @@ const homeOf = row => record(row) && typeof row.home === 'string' && row.home !=
153
66
  const settles = row => row.outcome === RESUME_OUTCOMES.refused
154
67
  || row.outcome === RESUME_OUTCOMES.skipped && SETTLING_SKIPPED_REASONS.includes(row.reason);
155
68
  const RELEASES = new Set([RESUME_OUTCOMES.resumed, RESUME_OUTCOMES.fresh, RESUME_OUTCOMES.blocked, RESUME_OUTCOMES.alreadyRunning]);
156
- /** A refused row's (home, reason, code), as one string; the format is this module's alone. */
157
- const reportedKey = (home, row) => JSON.stringify([home, row.reason ?? null, row.code ?? null]);
158
69
 
159
70
  /**
160
71
  * The homes a sweep's answer settles and releases, for the trigger's settled homes. A row `refused` (any
@@ -177,156 +88,8 @@ export function sweepSettlement(envelope) {
177
88
  return { settle, release };
178
89
  }
179
90
 
180
- /**
181
- * News, not repeats: the answer without what an earlier answer already reported, and this answer's keys.
182
- * `envelope` is a copy (the given one is never changed) that leaves out each `refused` row with a string home
183
- * whose (home, reason, code) key is in `reported`, and each host warning (the result's `warnings`) whose
184
- * exact string is in `reportedHost`; everything else is kept, in order (`warnings` absent when none is left).
185
- * `keys` are the keys of every such refused row of this answer, those left out too, each with its home, for
186
- * the caller to add to `reported` after (and to forget by home). `hostKeys` are the host warnings kept, each
187
- * that becomes a line, in order: shownHostKeys says which of them a reading showed. Keys are opaque outside
188
- * this module. An envelope that is not the sweep's document (answerRows) is given back as it came, with no keys.
189
- * @param {unknown} envelope
190
- * @param {Set<string>} reported refusal keys an earlier answer gave
191
- * @param {Set<string>} [reportedHost] host keys an earlier notice showed
192
- * @returns {{envelope: unknown, keys: {home: string, key: string}[], hostKeys: string[]}}
193
- */
194
- export function withoutReported(envelope, reported, reportedHost = new Set()) {
195
- const rows = answerRows(envelope);
196
- if (!rows) return { envelope, keys: [], hostKeys: [] };
197
- const keys = [];
198
- const kept = rows.filter(row => {
199
- const home = homeOf(row);
200
- if (home === null || row.outcome !== RESUME_OUTCOMES.refused) return true;
201
- const key = reportedKey(home, row);
202
- keys.push({ home, key });
203
- return !reported.has(key);
204
- });
205
- // Host warnings: a reported one left out by its exact string; a `warnings` that is not an array passes as it is.
206
- const { warnings: given, ...result } = envelope.result;
207
- if (!Array.isArray(given)) return { envelope: { ...envelope, result: { ...envelope.result, rows: kept } }, keys, hostKeys: [] };
208
- const host = given.filter(w => typeof w !== 'string' || !reportedHost.has(w));
209
- const hostKeys = host.filter(w => typeof w === 'string' && displayLine(w) !== null);
210
- return { envelope: { ...envelope, result: { ...result, rows: kept, ...(host.length ? { warnings: host } : {}) } }, keys, hostKeys };
211
- }
212
-
213
91
  /** Whether a sweep completed: its answer is the sweep's document and not a plan (answerRows: it ran), and its
214
- * reading is `quiet` or `notice`. Busy, failed, unsupported and a plan are not: nothing can be concluded about a
215
- * home from them. `envelope` is the run's answer, `reading` what was read of it. */
92
+ * reading is `answered`. Busy, failed, unsupported and a plan are not: nothing can be concluded about a home from
93
+ * them. `envelope` is the run's answer, `reading` what was read of it. */
216
94
  export const sweepCompleted = (envelope, reading) => answerRows(envelope) !== null
217
- && record(reading) && (reading.kind === 'quiet' || reading.kind === 'notice');
218
-
219
- /** The host keys of `hostKeys` (withoutReported's, for the envelope `reading` was read from) that the reading
220
- * showed: none unless it is a notice, else those its summary kept, in order (the cut is by position). A host
221
- * warning a quiet sweep carried was never shown, so it stays news. */
222
- export function shownHostKeys(reading, hostKeys) {
223
- if (!record(reading) || reading.kind !== 'notice' || !record(reading.summary) || !record(reading.summary.host)
224
- || !Array.isArray(reading.summary.host.warnings) || !Array.isArray(hostKeys)) return [];
225
- return hostKeys.slice(0, reading.summary.host.warnings.length);
226
- }
227
-
228
- /** Whether each kept fact has its kind's exact shape. */
229
- const rowShape = {
230
- resumed: r => exactKeys(r, ['instance', 'deployment', 'warnings', 'omitted']) && boundedWarningsValid(r.warnings, r.omitted),
231
- fresh: r => exactKeys(r, ['instance', 'deployment', 'reason', 'warnings', 'omitted']) && (r.reason === null || FRESH_REASONS.includes(r.reason))
232
- && boundedWarningsValid(r.warnings, r.omitted),
233
- waiting: r => exactKeys(r, ['instance', 'deployment', 'reason']) && (r.reason === null || WAITING_REASONS.includes(r.reason)),
234
- refused: r => exactKeys(r, ['instance', 'deployment', 'reason', 'code', 'message']) && (r.reason === null || REFUSED_REASONS.includes(r.reason))
235
- && (r.code === null || code(r.code) !== null) && (r.message === null || cleanLine(r.message)),
236
- };
237
- const copyRow = r => Object.hasOwn(r, 'warnings') ? { ...r, warnings: [...r.warnings] } : { ...r };
238
-
239
- /** The summary as it crossed a boundary (main to a renderer over IPC): the same summary, a fresh copy, or
240
- * undefined. Exactly the keys above, everywhere; names and paths display lines, never withheld or empty;
241
- * reasons one of their kind's or null; codes of the kernel's form or null; each row's warnings within both
242
- * bounds with `omitted` consistent (boundedWarningsValid); at most RESUME_SUMMARY_ROWS rows and
243
- * RESUME_SUMMARY_DEPLOYMENTS deployment lines; `host` the host warnings within both bounds (boundedWarningsValid);
244
- * `totals` non-negative safe integers, each at least its kind's
245
- * kept rows. `omitted` is the rows over the bound (the totals' sum less the kept rows: above 0 only beside
246
- * a full set of rows) plus the deployment lines over theirs (above 0 only beside a full set of lines).
247
- * Idempotent: readResumeSweep's summary decodes to itself, and so does this function's answer. */
248
- export function resumeSummaryFact(v) {
249
- if (!exactKeys(v, SUMMARY_KEYS) || !exactKeys(v.totals, KINDS) || !KINDS.every(k => count(v.totals[k]))
250
- || !count(v.omitted) || !Array.isArray(v.unswept)
251
- || !exactKeys(v.host, ['warnings', 'omitted']) || !boundedWarningsValid(v.host.warnings, v.host.omitted)) return undefined;
252
- let kept = 0;
253
- for (const k of KINDS) {
254
- const rows = v[k];
255
- if (!Array.isArray(rows) || rows.length > v.totals[k]
256
- || !rows.every(r => rowShape[k](r) && named(r.instance) && named(r.deployment))) return undefined;
257
- kept += rows.length;
258
- }
259
- const lines = v.unswept.length, total = sum(v.totals);
260
- if (kept > RESUME_SUMMARY_ROWS || lines > RESUME_SUMMARY_DEPLOYMENTS || !Number.isSafeInteger(total)
261
- || !v.unswept.every(u => exactKeys(u, ['deployment', 'reason']) && named(u.deployment) && (u.reason === null || UNSWEPT_REASONS.includes(u.reason)))) return undefined;
262
- const overRows = total - kept, overLines = v.omitted - overRows;
263
- if (overRows > 0 && kept < RESUME_SUMMARY_ROWS || overLines < 0 || overLines > 0 && lines < RESUME_SUMMARY_DEPLOYMENTS) return undefined;
264
- const out = {};
265
- for (const k of KINDS) out[k] = v[k].map(copyRow);
266
- return { ...out, unswept: v.unswept.map(u => ({ ...u })), host: { warnings: [...v.host.warnings], omitted: v.host.omitted },
267
- omitted: v.omitted, totals: { ...v.totals } };
268
- }
269
-
270
- const FRESH_WHY = {
271
- 'no-conversation': 'no saved conversation was found.',
272
- 'no-receipts': 'OATS has no record of where its conversations are kept.',
273
- 'resume-unproven': "resuming this harness's conversations isn't supported yet.",
274
- };
275
- const UNSWEPT_WHY = { 'not-ok': "its deployment isn't ready.", unreadable: 'it could not be read.' };
276
- const THIS_BOOT = ' It was refused earlier since this computer started, so OATS did not try again.';
277
- const KEEPS_LOST = "keeps losing its session, so OATS stopped resuming it: start it yourself once it's fixed.";
278
- /** A refused row's line: `keeps-getting-lost` says why in place of "could not be resumed.". */
279
- const refusedLine = r => r.reason === 'keeps-getting-lost' ? KEEPS_LOST
280
- : `could not be resumed.${r.reason === 'refused-this-boot' ? THIS_BOOT : ''}`;
281
-
282
- /** The headline's sentences, each only when its count is above 0. A blocked row's session runs, so it counts
283
- * among the resumed: N = resumed + fresh + waiting. "1 of them" takes "its"; "It" when the one is all of N. */
284
- function headline({ resumed, fresh: f, waiting: w, refused: r }) {
285
- const n = resumed + f + w, out = [];
286
- if (n > 0) out.push(n === 1 ? 'OATS resumed 1 instance whose session was lost.' : `OATS resumed ${n} instances whose sessions were lost.`);
287
- if (f > 0) out.push(f === n && n === 1 ? 'It started fresh from its briefing.'
288
- : f === 1 ? '1 of them started fresh from its briefing.' : `${f} of them started fresh from their briefing.`);
289
- if (w > 0) out.push(w === n && n === 1 ? 'It is waiting for you: open its terminal.'
290
- : w === 1 ? '1 of them is waiting for you: open its terminal.' : `${w} of them are waiting for you: open their terminals.`);
291
- if (r > 0) out.push(n > 0 ? `${r} could not be resumed.` : r === 1 ? 'OATS could not resume 1 lost session.' : `OATS could not resume ${r} lost sessions.`);
292
- return out.join(' ');
293
- }
294
-
295
- /** A row's warnings under `OATS says:`, in order, then how many more the cut left out; nothing without one. */
296
- const said = r => r.warnings.length ? ['OATS says:', ...r.warnings, ...(r.omitted > 0 ? [`${r.omitted} more not shown.`] : [])] : [];
297
-
298
- /**
299
- * The notice for a summary in the clients' words: `{headline, detail}`, or null when `summary` does not
300
- * decode (resumeSummaryFact) or has no row to tell of. Kernel text appears only after `OATS says:`.
301
- * @param {unknown} summary
302
- * @param {{label: (deployment: string) => string}} options `label` is the caller's display label for a
303
- * deployment path (required: a TypeError without it); a non-string or empty label shows the path itself.
304
- * Detail: a line per kept row, waiting, refused, fresh, resumed; then the unswept deployments; then the host
305
- * warnings under `OATS says about this computer:` (and how many more the cut left out); then
306
- * `M more not shown.` when anything was left out. A row line names its deployment (` in {d}`) only when the
307
- * kept rows name more than one; a deployment line always does. A refused row's kernel message follows it on
308
- * its own line, as `OATS says: …`. `detail` is the lines joined with '\n', absent when there are none.
309
- */
310
- export function resumeNotice(summary, options) {
311
- const labelOf = options?.label;
312
- if (typeof labelOf !== 'function') throw new TypeError('resumeNotice needs a label function');
313
- const s = resumeSummaryFact(summary);
314
- if (!s || sum(s.totals) === 0) return null;
315
- const shown = d => { const l = labelOf(d); return typeof l === 'string' && l ? l : d; };
316
- const several = new Set(KINDS.flatMap(k => s[k].map(r => r.deployment))).size > 1;
317
- const who = r => several ? `${r.instance} in ${shown(r.deployment)}` : r.instance;
318
- const lines = [
319
- ...s.waiting.map(r => r.reason === 'resume-confirmation'
320
- ? `${who(r)}: waiting for you to choose how to resume it. Open its terminal.`
321
- : `${who(r)}: waiting at a launch prompt. Open its terminal.`),
322
- ...s.refused.flatMap(r => [`${who(r)}: ${refusedLine(r)}`,
323
- ...(r.message !== null ? [`OATS says: ${r.message}`] : [])]),
324
- ...s.fresh.flatMap(r => [`${who(r)}: started fresh from its briefing, ${FRESH_WHY[r.reason] ?? 'its conversation could not be resumed.'}`, ...said(r)]),
325
- ...s.resumed.flatMap(r => [`${who(r)}: resumed in its own conversation.`, ...said(r)]),
326
- ...s.unswept.map(u => `Not checked in ${shown(u.deployment)}: ${UNSWEPT_WHY[u.reason] ?? 'it could not be checked.'}`),
327
- ...(s.host.warnings.length ? ['OATS says about this computer:', ...s.host.warnings,
328
- ...(s.host.omitted > 0 ? [`${s.host.omitted} more not shown.`] : [])] : []),
329
- ...(s.omitted > 0 ? [`${s.omitted} more not shown.`] : []),
330
- ];
331
- return lines.length ? { headline: headline(s.totals), detail: lines.join('\n') } : { headline: headline(s.totals) };
332
- }
95
+ && record(reading) && reading.kind === 'answered';
@@ -37,6 +37,8 @@ export function soulRows(deployment, catalog) {
37
37
  ...(Object.hasOwn(soul, "capabilities") ? { capabilities: soul.capabilities && soul.capabilities.map((c) => ({ ...c })) } : {}),
38
38
  // The kernel's soul key (`oats soul teams <key>`): the qualified name for a package soul, the bare name otherwise.
39
39
  ...(typeof soul.key === "string" ? { key: soul.key } : {}),
40
+ // Feature instance-background (#1579): the soul runs its instances in the background unless a spawn says otherwise.
41
+ ...(soul.background === true ? { background: true } : {}),
40
42
  ...(soul.kind === "package" ? { package: soul.package, version: soul.version, qualifiedName: soul.qualifiedName } : {}),
41
43
  origin: soul.origin || "", soulKind: soul.kind, repo: soul.repoKey || null, capability: null,
42
44
  soulSource: { repoKey: soul.repoKey ?? null, commit: soul.commit ?? null, path: soul.path ?? null },
@@ -32,7 +32,8 @@ export function spawnApplyChoicesSupported(cli, choices, wakeRequested = false)
32
32
  && (!choices.launchConfig || has(cli?.features, 'launch-config'))
33
33
  && (!wakeRequested || has(cli?.features, 'schedule'))
34
34
  && (choices.name === undefined || has(cli?.features, 'spawn-name'))
35
- && (choices.identity === undefined || has(cli?.features, 'spawn-provider-payload'));
35
+ && (choices.identity === undefined || has(cli?.features, 'spawn-provider-payload'))
36
+ && (choices.background === undefined || has(cli?.features, 'instance-background'));
36
37
  }
37
38
  export function spawnWake(v) {
38
39
  if (!exact(v, ['cron', 'tz', 'message', 'enabled']) || !text(v.cron, 256) || !v.cron.trim()
@@ -10,6 +10,9 @@ export function spawnEffective(v) {
10
10
  || !HARNESSES.includes(harnessOf(v)) || !nullable(v.model) || !nullable(v.launchConfig)
11
11
  || v.yolo !== null && typeof v.yolo !== 'boolean' || v.backend !== 'tmux'
12
12
  || typeof v.childSpawns !== 'boolean') return null;
13
+ // Feature instance-background (#1579): the decision binds `background: true` exactly when the instance runs in the
14
+ // background; it is absent otherwise (any other value is not the contract's).
15
+ if (Object.hasOwn(v, 'background') && v.background !== true) return null;
13
16
  let relation = null;
14
17
  if (v.relation !== null) {
15
18
  const r = v.relation, a = r?.anchor;
@@ -18,7 +21,7 @@ export function spawnEffective(v) {
18
21
  relation = { kind: r.kind, anchor: { instance: a.instance, agentsRoot: a.agentsRoot } };
19
22
  }
20
23
  return { repo: v.repo, work: v.work, harness: harnessOf(v), model: v.model, launchConfig: v.launchConfig,
21
- yolo: v.yolo, backend: v.backend, childSpawns: v.childSpawns, relation };
24
+ yolo: v.yolo, backend: v.backend, childSpawns: v.childSpawns, relation, ...(v.background === true ? { background: true } : {}) };
22
25
  }
23
26
  export function spawnDecision(v, { effectiveRequired = false } = {}) {
24
27
  if (!record(v) || !name(v.instance) || !absolute(v.home) || !nullable(v.branch)
@@ -185,7 +185,7 @@ export function previewSelector(v) {
185
185
  return exact(v, ['soul', 'agentsRoot']) && name(v.soul) && absolute(v.agentsRoot) ? { soul: v.soul, agentsRoot: v.agentsRoot } : null;
186
186
  }
187
187
  export function previewChoices(v) {
188
- if (!exact(v, ['purpose', 'name', 'work', 'branch', 'base', 'harness', 'model', 'launchConfig', 'backend', 'yolo', 'relation', 'identity', 'join'])) return null;
188
+ if (!exact(v, ['purpose', 'name', 'work', 'branch', 'base', 'harness', 'model', 'launchConfig', 'backend', 'yolo', 'background', 'relation', 'identity', 'join'])) return null;
189
189
  // --name (exact, unprefixed; feature spawn-name) and --purpose are mutually exclusive.
190
190
  if (Object.hasOwn(v, 'purpose') && Object.hasOwn(v, 'name')) return null;
191
191
  const out = {};
@@ -198,6 +198,9 @@ export function previewChoices(v) {
198
198
  // The only work override the Desktop offers: a checkout soul in a worktree.
199
199
  if (Object.hasOwn(v, 'work')) { if (v.work !== 'worktree') return null; out.work = 'worktree'; }
200
200
  if (Object.hasOwn(v, 'yolo')) { if (typeof v.yolo !== 'boolean') return null; out.yolo = v.yolo; }
201
+ // Run in background (feature instance-background, #1579): present only when the dialog's switch differs from the
202
+ // soul's declared default; the kernel then records the instance's own flag (--background / --no-background).
203
+ if (Object.hasOwn(v, 'background')) { if (typeof v.background !== 'boolean') return null; out.background = v.background; }
201
204
  // Messaging identity (decision 27; feature spawn-provider-payload): sent to
202
205
  // the soul's messaging provider as --provider <cap> identity.mode=… — there
203
206
  // is no kernel flag. `provider` is the capability the preview reported on
@@ -243,6 +246,7 @@ export function choiceArgv(choices, cli) {
243
246
  for (const [k, flag] of [['purpose', '--purpose'], ['name', '--name'], ['work', '--work'], ['branch', '--branch'], ['base', '--base'], ['harness', harnessFlag(cli)], ['launchConfig', '--launch-config'], ['backend', '--backend']]) if (choices[k] !== undefined) argv.push(flag, choices[k]);
244
247
  if (choices.model.kind !== 'inherit') argv.push('--model', choices.model.kind === 'native-default' ? '@native-default' : choices.model.value);
245
248
  if (choices.yolo !== undefined) argv.push(choices.yolo ? '--yolo' : '--no-yolo');
249
+ if (choices.background !== undefined) argv.push(choices.background ? '--background' : '--no-background');
246
250
  if (choices.relation.kind !== 'unrelated') argv.push('--relation', choices.relation.kind, '--relative-to', choices.relation.anchor.instance, '--relative-root', choices.relation.anchor.agentsRoot);
247
251
  if (choices.identity) {
248
252
  argv.push('--provider', choices.identity.provider, `identity.mode=${choices.identity.mode}`);
@@ -362,6 +366,12 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
362
366
  // name is then not known to be the one a `--name` preview would give.
363
367
  const naming = Object.hasOwn(v, 'naming') ? namingOf(v.naming) : undefined;
364
368
  if (naming === null) return null;
369
+ // Feature instance-background (#1579): `background`, always present on a kernel with the feature (absent: an older
370
+ // one, which offers no switch), agrees with the decision, which binds `effective.background: true` exactly when it
371
+ // is true; `backgroundFrom` ("flag" or "soul", absent when neither declared it) says who chose it.
372
+ const background = Object.hasOwn(v, 'background') ? v.background : undefined;
373
+ if (background !== undefined && typeof background !== 'boolean' || (background === true) !== (e.background === true)
374
+ || Object.hasOwn(v, 'backgroundFrom') && (background === undefined || !['flag', 'soul'].includes(v.backgroundFrom))) return null;
365
375
  // Only reports carry `problem`: a preview that would hit one refuses with the error instead.
366
376
  if (Object.hasOwn(v, 'launch') && (launch === undefined || launch.problem !== null || launch.effective.harness !== e.harness || launch.effective.model !== e.model
367
377
  || launch.effective.launchConfig !== e.launchConfig)) return null;
@@ -374,6 +384,7 @@ export function previewData(v, expected, { composedFrom = false } = {}) {
374
384
  ...(defaultTeam !== undefined ? { defaultTeam } : {}), ...(launch ? { launch } : {}),
375
385
  ...(launchPromptAnswers ? { launchPromptAnswers } : {}),
376
386
  ...(naming ? { naming } : {}),
387
+ ...(background !== undefined ? { background, ...(Object.hasOwn(v, 'backgroundFrom') ? { backgroundFrom: v.backgroundFrom } : {}) } : {}),
377
388
  // Capability warnings (0.49.0): the kernel's message strings, tolerant and idempotent (a malformed list reads as none,
378
389
  // never refuses the preview); absent on an older kernel. Shown only: the apply binds nothing on them.
379
390
  ...(Object.hasOwn(v, 'warnings') ? { warnings: previewWarningsOf(v.warnings) } : {}) };
@@ -78,6 +78,8 @@ export function admitSpawnSelection(selector, choices, { workspace: w, cli, agen
78
78
  // An exact (unprefixed) name only where the CLI advertises it.
79
79
  if (choices.name !== undefined && !cli.features.includes('spawn-name')) return fail('E_UNSUPPORTED_OPTION');
80
80
  if (choices.identity !== undefined && !cli.features.includes('spawn-provider-payload')) return fail('E_UNSUPPORTED_OPTION');
81
+ // Run in background (#1579): --background / --no-background only where the CLI lists instance-background.
82
+ if (choices.background !== undefined && !cli.features.includes('instance-background')) return fail('E_UNSUPPORTED_OPTION');
81
83
  // The one work override offered: a checkout soul asked for a worktree.
82
84
  if (choices.work !== undefined && soul.work !== 'checkout') return fail('E_UNSUPPORTED_OPTION');
83
85
  const work = choices.work ?? soul.work;
@@ -20,7 +20,7 @@ never does.
20
20
  | path | contents |
21
21
  |---|---|
22
22
  | `bin/tui.mjs` | the entry `bin/oats.mjs` loads: it imports the whole module graph, then runs `main()` |
23
- | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
23
+ | `lib/main.mjs` | the start (arguments, environment, terminal, `tui.json`, deployment, kernel, and outside every deployment this computer's list of deployments) and the loop: events through `reduce`, effects out, the frame drawn; the list's reads, the add of the deployment the run starts in and the switcher's Remove, through the shared `cliDeploymentList`; the kernel's machine sweep of lost sessions (`oats session resume --json`), when the shared resume trigger says (after that add has settled, and when a read shows a lost session), through `changeExec`; a resize and the keys typed to an agent told to the store (`passed`), which ends a line of one key |
24
24
  | `lib/actions.mjs` | the action table and its default keys: the reducer, the cheat sheet and the help read the effective one. The keys shared with the Desktop are not written here: the leader's table and the plain keys of the list come from `packages/client/keymap.mjs`, and `test/keymap.test.mjs` fails on a row of the shared table the TUI does not handle |
25
25
  | `lib/config.mjs` | `tui.json` (`~/.oats/config/tui.json`): moved once from where earlier versions read it, read once, checked, and the effective action table; the default leader is the shared one (`keymap.mjs` `leaderKey`, Ctrl+X on every platform) |
26
26
  | `lib/client.mjs` | the one module that imports the shared readers (`packages/client/`), and the client's terms |
@@ -77,7 +77,7 @@ Rules the tests pin (`test/tui-boundary.test.mjs` reads the files):
77
77
  a block that says what its command never says ends that client (THE
78
78
  CAPTURE in `lib/panel.mjs`). A
79
79
  change (`lib/read.mjs` `changeExec`: the apply of a stop or a retire, a
80
- start, a restart, a spawn's apply) is never signalled on the way out: it
80
+ start, a restart, a spawn's apply, the machine sweep) is never signalled on the way out: it
81
81
  is let go, and its output goes to files, so it never meets a closed pipe.
82
82
  Only a spawn's apply has a deadline, the shared apply's, at which it is
83
83
  sent its signal (`timeout`, `killSignal`), and only while the run lasts:
@@ -22,8 +22,8 @@ export { remoteRosterState } from "../../client/remote-roster.mjs";
22
22
  export { observeIdentities, identityMemory } from "../../client/remote-identity-memory.mjs";
23
23
  export { workspaceChoiceRows, choiceMatches, UNMATCHED_SECTION } from "../../client/workspace-choices.mjs";
24
24
  export { shortPath, deploymentLabel, machineLabels } from "../../client/deployment-label.mjs";
25
- export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings } from "../../client/instance-tree.mjs";
26
- export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment } from "../../client/roster-sections.mjs";
25
+ export { instanceId, instanceVisibleInTree, waitingRollup, collapseKey, filterInstanceTree, hasInstanceChildren, heldHome, instanceSiblings, backgroundPlacement, BACKGROUND_FEATURE } from "../../client/instance-tree.mjs";
26
+ export { rosterSections, deploymentState, rowStale, primaryDeployment, isMultiDeployment, rosterSectionKey, sidebarSections } from "../../client/roster-sections.mjs";
27
27
  export { runtimeState, runtimeCounts, originLead, siblingText, instanceColor } from "../../client/instance-presentation.mjs";
28
28
  export { instanceDisplayName } from "../../client/instance-display-name.mjs";
29
29
  export { waitingClaim, waitingLabel, waitedText, waitingClock, waitingBelowText } from "../../client/waiting-on-you.mjs";
@@ -38,6 +38,10 @@ export { createRetiresInFlight, retiringRows } from "../../client/retire-in-flig
38
38
  export { startGate, startInstance } from "../../client/session-start.mjs";
39
39
  export { retainedStartMessage, launchFlagIgnored, flagIgnoredNotice } from "../../client/launch-prompt-outcome.mjs";
40
40
  export { INSTANCE_VARIABLES } from "../../client/kernel-environment.mjs";
41
+ // #1559: the kernel's machine sweep, run when the TUI opens and when a read shows a lost session
42
+ // (lib/main.mjs): the shared trigger decides when, the runner runs it, and the reader words what it did.
43
+ export { runResumeSweep } from "../../client/session-resume-cli.mjs";
44
+ export { createResumeTrigger, localDeploymentIds } from "../../client/session-resume-trigger.mjs";
41
45
  export { validateWorkspace } from "../../client/workspace-admission.mjs";
42
46
  export { createSoulCatalog, soulCatalogKey } from "../../client/soul-catalog.mjs";
43
47
  export { soulRows } from "../../client/soul-rows.mjs";
@@ -12,9 +12,9 @@
12
12
  import { homedir } from "node:os";
13
13
  import { resolve } from "node:path";
14
14
  import { bindings } from "./actions.mjs";
15
- import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, displayLine, heldHome, pendingEntry, prepareRemoteTerm, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
15
+ import { TERMS, capabilityCatalogKey, cliDeploymentList, deploymentsListSupported, createCapabilityCatalog, createLifecycleBoundary, createLifecycleConfirmation, createRetiresInFlight, createSoulCatalog, createSpawnApplyBoundary, createSpawnPreview, createSpawnTransaction, createResumeTrigger, displayLine, heldHome, pendingEntry, prepareRemoteTerm, runResumeSweep, sessionAttachArgv, soulCatalogKey, startInstance } from "./client.mjs";
16
16
  import { loadConfig, loadKeys } from "./config.mjs";
17
- import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, roster, spawnContext } from "./model.mjs";
17
+ import { ACT_WORDS, LIST_WORDS, actContext, actCwd, listRowsOf, localDeployments, model, outcomeOf, reachedMachines, resumeObservation, roster, spawnContext } from "./model.mjs";
18
18
  import { createPanel, sweep } from "./panel.mjs";
19
19
  import { CHANGE_FILES, admitDeployment, createIdentityReads, createReader, findDeployment, leaveInstance, probeKernel, realpath, startExec, tellable } from "./read.mjs";
20
20
  import { initialState, reduce } from "./store.mjs";
@@ -72,6 +72,9 @@ export function parseArgs(argv) {
72
72
 
73
73
  /** The label of a change to this computer's deployments list (an add or a remove), for the line after leaving. */
74
74
  const LIST_CHANGE = Object.freeze({ verb: "list" });
75
+ /** The label of the kernel's machine sweep (`oats session resume --json`), every one the run starts: a
76
+ * change, never signalled, and never named after leaving (the TUI says nothing of a sweep). */
77
+ const RESUME_CHANGE = Object.freeze({ verb: "resume" });
75
78
  /** Why a call to this computer's deployments list has no answer at all: it threw before the kernel
76
79
  * could answer. The shared adapter's own code for a kernel call that failed (deployment-list-cli.mjs). */
77
80
  const NOT_ASKED = Object.freeze({ code: "E_CLI_FAILED", message: "the kernel could not be asked" });
@@ -94,10 +97,11 @@ function errorLines(error) {
94
97
  * can answer them. `deploymentList` is the shared cliDeploymentList (this computer's deployments
95
98
  * list, through the kernel: awebai/oats#1390), and `startExec` the exec it is handed before the
96
99
  * terminal is taken; replaceable so a test can answer the list. `loadKeys` reads keys.json, the
97
- * chord family (lib/config.mjs), replaceable so no test reads a user's file. */
100
+ * chord family (lib/config.mjs), replaceable so no test reads a user's file. `createResumeTrigger`
101
+ * is the shared trigger of the kernel's machine sweep (packages/client session-resume-trigger.mjs). */
98
102
  const EFFECTS = Object.freeze({ loadConfig, loadKeys, findDeployment, probeKernel, createReader, createIdentityReads, deploymentList: cliDeploymentList, startExec, admitDeployment, prepareRemoteTerm, createPanel, sweep,
99
103
  runDir: CHANGE_FILES.dir, removeDir: CHANGE_FILES.remove, realpath, tellable, startInstance, createLifecycleConfirmation, createLifecycleBoundary, createSoulCatalog,
100
- createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction });
104
+ createCapabilityCatalog, createSpawnPreview, createSpawnApplyBoundary, createSpawnTransaction, createResumeTrigger });
101
105
 
102
106
  /** The timers a run lends the shared spawn: the apply's deadline and its grace (the boundary's
103
107
  * `applyTimer`), the boundary's wait for an answer (`timer`) and the transaction's polls
@@ -214,7 +218,13 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
214
218
  * covers nothing, whatever entry it kept. */
215
219
  function entered(event) {
216
220
  heard(event);
217
- if (event.read === true && state.numbers.get(event.id) === event.number) retires.landed(event.number, (t) => !t.server && t.workspace === event.id);
221
+ if (event.read !== true || state.numbers.get(event.id) !== event.number) return;
222
+ retires.landed(event.number, (t) => !t.server && t.workspace === event.id);
223
+ // The rows of the view that holds it, with its deployments of this machine: a lost row of one of those
224
+ // sweeps again; another machine's row never does (the shared trigger's locality).
225
+ if (ended) return;
226
+ const { rows, localDeploymentIds } = resumeObservation(state, event.id, clock());
227
+ resume.observed(rows, { localDeploymentIds });
218
228
  }
219
229
  /** An event of the roster read: taken, then an outcome covers the rows of each machine it reached
220
230
  * (a read that failed marks every machine not reached, and covers none). */
@@ -235,6 +245,22 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
235
245
  onEntry: entered, onRoster: rostered,
236
246
  files: { ...CHANGE_FILES, dir: runDir },
237
247
  });
248
+ // LOST SESSIONS RESUMED (docs/tui.md, "Resuming lost sessions"; #1559): the kernel's machine sweep,
249
+ // `oats session resume --json`, which resumes every lost session of every local deployment of this
250
+ // computer. The shared trigger decides when: once the run has started (`launch`, after the add of the
251
+ // deployment it started in has settled, so the sweep's registry holds it), then whenever a read of a
252
+ // served deployment shows a row of a deployment of this machine whose session was lost (`observed`,
253
+ // given the view's rows and its local deployment ids: lib/model.mjs resumeObservation), never two at
254
+ // a time nor more often than its floor, and only with a kernel that has the sweep. The TUI decides nothing of what
255
+ // resumes. The sweep is a change of the run (the reader's changeExec: detached, its output in files,
256
+ // never signalled), which outlives the TUI and is let go in silence on the way out; what it read goes
257
+ // to the store as `{ resumed }`, which says nothing of it and at most reads the rows live.
258
+ const resume = effects.createResumeTrigger({
259
+ cli: () => probe.cli,
260
+ run: (cli) => runResumeSweep(cli, { exec: (bin, argv, options, callback) => reader.changeExec(bin, argv, { ...options, label: RESUME_CHANGE }, callback), env }),
261
+ now,
262
+ onReading: (reading) => heard({ resumed: reading }),
263
+ });
238
264
  // THE TABS AND THE SPLIT (docs/tui.md, "Tabs", "Splits"): the terminals open in the panel, at
239
265
  // most the store's TAB_LIMIT across its groups. `viewers` maps each tab's instanceId to its
240
266
  // viewer, `{ id, panel, cols, rows }` (the panel's own id once the window exists, null before,
@@ -521,10 +547,11 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
521
547
  }
522
548
  /** The deployment the run started in (from where it was started, or `--dir`), added to the list
523
549
  * once, as the TUI's: best effort. A failure opens nothing less, and is said once, in the line
524
- * under the sidebar's title. A row opened from the switcher is on the list already. */
550
+ * under the sidebar's title. A row opened from the switcher is on the list already. Settles once
551
+ * the add has, whatever it answered; at once without one. */
525
552
  function listStart(path) {
526
- if (!listing) return;
527
- Promise.resolve()
553
+ if (!listing) return Promise.resolve();
554
+ return Promise.resolve()
528
555
  .then(() => effects.deploymentList(probe.cli, { action: "add", path, via: "tui" }, { exec: listChange, env }))
529
556
  .then((answer) => { if (!answer.ok) heard({ notListed: answer.reason }); }, () => heard({ notListed: NOT_ASKED }));
530
557
  }
@@ -813,7 +840,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
813
840
  // The run's directory goes last, made for whichever of the two needed it first: the reader
814
841
  // removes it only when it wrote a change there, and one it cannot remove (a change still
815
842
  // writing) stays.
816
- onEnd() { ended = true; spawnTimers.end(); dismiss(confirmation?.n); panel.end(); identities.stop(); reader.stop(); if (dir !== null) { try { effects.removeDir(dir); } catch { /* not empty, or gone */ } } },
843
+ // The machine sweep in flight is let go with the other changes: its answer is no longer shown.
844
+ onEnd() { ended = true; resume.dispose(); spawnTimers.end(); dismiss(confirmation?.n); panel.end(); identities.stop(); reader.stop(); if (dir !== null) { try { effects.removeDir(dir); } catch { /* not empty, or gone */ } } },
817
845
  });
818
846
  function refresh(how) { Promise.resolve(reader.request(how)).catch(() => {}); }
819
847
  /** A preflight under way when the process stops: given up, and the store told. Its state alone is
@@ -855,7 +883,11 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
855
883
  // At the wait's end what the key parser kept as a possible beginning of the answer is read as typed.
856
884
  if (kb === "asking" && !ended) kbTimer = setTimer(() => { kbTimer = null; guard.attempt(() => { const released = parser.giveUp(); answered(null); if (released.length && !typing()) act(released); watchEscape(); }); }, Math.max(0, answerBy - now()));
857
885
  guard.attempt(() => { if (!ended) Promise.resolve(reader.start()).catch(() => {}); });
858
- if (found.ok) guard.attempt(() => { if (!ended) listStart(found.deployment); });
886
+ // The machine sweep, once the add of the deployment the run started in has settled (a start in the
887
+ // switcher has none): after the first frame and the first read cycle have begun, never before them.
888
+ let added = Promise.resolve();
889
+ if (found.ok) guard.attempt(() => { if (!ended) added = listStart(found.deployment); });
890
+ added.then(() => { if (!ended) guard.attempt(() => { resume.launch(); }); });
859
891
  // Once a run, at the start: the identities of this computer's listed deployments, the list read first
860
892
  // when the run did not read it before the terminal was taken.
861
893
  guard.attempt(() => { if (!ended) { if (listedAtStart) identify(); else readList({ identify: true }); } });
@@ -869,7 +901,8 @@ export async function main({ argv, stdin, stdout, stderr, env, proc = process, n
869
901
  if (kbTimer !== null) clearTimer(kbTimer);
870
902
  // After the alternate screen is left, so the message stays on the screen the user returns to.
871
903
  // One line per change still running, to a terminal or a file only; the status never depends on it.
872
- const running = reader.changes?.() ?? [];
904
+ // The machine sweep is no change of the person's: none for it.
905
+ const running = (reader.changes?.() ?? []).filter(({ label }) => label !== RESUME_CHANGE);
873
906
  if (running.length && effects.tellable(stderr)) {
874
907
  try { stderr.write(running.map(({ label }) => `${label === LIST_CHANGE ? LIST_WORDS.leaving : ACT_WORDS.leaving(label?.verb ?? "change", displayLine(label?.name) ?? "an instance")}\n`).join("")); } catch { /* nothing to tell it to */ }
875
908
  }