@awebai/oats 0.52.0 → 0.54.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +314 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/design/2026-09-23-workspace-module-contracts.md +3 -0
  6. package/docs/desktop-cli-api.md +696 -60
  7. package/docs/desktop-instance-start.md +25 -12
  8. package/docs/execution-targets.md +1 -0
  9. package/docs/implementation.md +184 -12
  10. package/docs/integrations.md +6 -3
  11. package/docs/knowledge.md +2 -2
  12. package/docs/macos-test-runs.md +246 -0
  13. package/docs/official-catalog.md +5 -5
  14. package/docs/packages.md +14 -14
  15. package/docs/release-lane.md +210 -6
  16. package/docs/release-notes/v0.53.0.md +1288 -0
  17. package/docs/release-notes/v0.54.0.md +142 -0
  18. package/docs/schedules.md +7 -1
  19. package/docs/souls-and-instances.md +239 -16
  20. package/docs/tui.md +453 -21
  21. package/docs/upgrading.md +310 -0
  22. package/docs/workspaces.md +123 -3
  23. package/lib/automations.mjs +22 -22
  24. package/lib/claim.mjs +93 -4
  25. package/lib/config-data.mjs +4 -1
  26. package/lib/core.mjs +569 -121
  27. package/lib/instance-events.mjs +19 -1
  28. package/lib/instance-git.mjs +39 -3
  29. package/lib/instance-inspect.mjs +5 -6
  30. package/lib/instance-lifecycle.mjs +145 -18
  31. package/lib/instance-resolution.mjs +59 -6
  32. package/lib/launch-preference.mjs +226 -15
  33. package/lib/local-edit.mjs +118 -0
  34. package/lib/packages.mjs +18 -5
  35. package/lib/pi-bridge.mjs +308 -0
  36. package/lib/refused-text.mjs +11 -0
  37. package/lib/remote.mjs +404 -60
  38. package/lib/resolve.mjs +2 -1
  39. package/lib/retained-after-retire.mjs +2 -2
  40. package/lib/retire-output.mjs +12 -1
  41. package/lib/schedule-host.mjs +6 -35
  42. package/lib/shell-word.mjs +13 -0
  43. package/lib/soul-launch-verbs.mjs +153 -0
  44. package/lib/stable-node.mjs +62 -0
  45. package/lib/teams-verbs.mjs +18 -46
  46. package/lib/workspace.mjs +75 -27
  47. package/package-catalog.json +4 -4
  48. package/package.json +2 -1
  49. package/packages/client/attach-exit.mjs +25 -0
  50. package/packages/client/cli-adapter.mjs +16 -3
  51. package/packages/client/cli-locator.mjs +2 -2
  52. package/packages/client/deployment-contract.mjs +4 -0
  53. package/packages/client/deployment-facts.mjs +71 -10
  54. package/packages/client/deployment-panel.mjs +49 -11
  55. package/packages/client/deployment-read-cli.mjs +7 -3
  56. package/packages/client/display-text.mjs +8 -2
  57. package/packages/client/instance-acts.mjs +46 -10
  58. package/packages/client/instance-events-contract.mjs +4 -2
  59. package/packages/client/instance-presentation.mjs +66 -2
  60. package/packages/client/instance-tree.mjs +23 -14
  61. package/packages/client/kernel-lines.mjs +31 -0
  62. package/packages/client/kernel-made.mjs +23 -0
  63. package/packages/client/launch-prompt-outcome.mjs +51 -16
  64. package/packages/client/lifecycle-contract.mjs +45 -4
  65. package/packages/client/liveness.mjs +14 -1
  66. package/packages/client/own-codes.mjs +31 -0
  67. package/packages/client/panel-views.mjs +18 -11
  68. package/packages/client/readiness-contract.mjs +3 -1
  69. package/packages/client/remote-address.mjs +34 -9
  70. package/packages/client/remote-identity-memory.mjs +94 -0
  71. package/packages/client/remote-roster.mjs +92 -6
  72. package/packages/client/session-attach.mjs +175 -0
  73. package/packages/client/spawn-apply-contract.mjs +16 -4
  74. package/packages/client/spawn-messages.mjs +26 -3
  75. package/packages/client/spawn-preview-cli.mjs +8 -2
  76. package/packages/client/spawn-preview-contract.mjs +5 -1
  77. package/packages/client/terminal-exec.mjs +21 -0
  78. package/packages/client/workspace-choices.mjs +95 -0
  79. package/packages/client/workspace-views.mjs +39 -3
  80. package/packages/record/README.md +21 -0
  81. package/packages/record/bin/setup.mjs +108 -15
  82. package/packages/tui/README.md +30 -12
  83. package/packages/tui/lib/actions.mjs +16 -1
  84. package/packages/tui/lib/client.mjs +32 -1
  85. package/packages/tui/lib/config.mjs +151 -0
  86. package/packages/tui/lib/main.mjs +117 -46
  87. package/packages/tui/lib/model.mjs +392 -0
  88. package/packages/tui/lib/read.mjs +473 -0
  89. package/packages/tui/lib/store.mjs +364 -0
  90. package/packages/tui/lib/term/keys.mjs +44 -0
  91. package/packages/tui/lib/term/screen.mjs +16 -4
  92. package/packages/tui/lib/term/text.mjs +60 -0
  93. package/packages/tui/lib/term/tty.mjs +13 -3
  94. package/packages/tui/lib/views/detail.mjs +46 -0
  95. package/packages/tui/lib/views/frame.mjs +230 -36
  96. package/packages/tui/lib/views/help.mjs +125 -13
  97. package/packages/tui/lib/views/instances.mjs +137 -0
  98. package/packages/tui/lib/views/scroll.mjs +19 -0
  99. package/packages/tui/lib/views/switcher.mjs +97 -0
  100. package/skills/oats-getting-started/SKILL.md +8 -2
@@ -22,7 +22,8 @@
22
22
  *
23
23
  * These functions read no clock: the one time they stamp is `held.at`, and the same `held` gives the
24
24
  * same answer. A remote deployment's panel is remote-roster.mjs `remotePanel`, made at `held.at`; what
25
- * a remote roster's answer becomes is that module's.
25
+ * a remote roster's answer becomes is that module's `remoteRosterState`, whose answer is the three
26
+ * roster values of `held`.
26
27
  *
27
28
  * `remembered` is the client's own store, passed in: this module calls its three reading methods and
28
29
  * keeps nothing. `note(id)` answers the sentence left for a machine that moved to another workspace,
@@ -36,7 +37,7 @@ import { basename } from 'node:path';
36
37
  import { remoteWorkspace, remotePanel } from './remote-roster.mjs';
37
38
  import { readIdentity, attachment, buildViews, deploymentReason, deploymentReasonParts } from './workspace-views.mjs';
38
39
  import { shortPath, deploymentLabel } from './deployment-label.mjs';
39
- import { deploymentUnavailableText } from './deployment-facts.mjs';
40
+ import { deploymentUnavailableText, keptFailure } from './deployment-facts.mjs';
40
41
  import { publicDeployment } from './deployment-panel.mjs';
41
42
  import { teamMembers } from './team-members.mjs';
42
43
  import { requireTerms } from './client-terms.mjs';
@@ -67,7 +68,9 @@ export function rememberedGroups(held) {
67
68
  agentsRoot: undefined, workspace: null, souls: [], instances: [], retireFailures: [],
68
69
  }));
69
70
  }
70
- const cliReadsRemotes = (held) => !!held.cli.ok && !!held.cli.remote?.includes("roster");
71
+ /** Whether a kernel record (cli-locator.mjs) reads other machines: an accepted CLI whose `remote` lists
72
+ * `roster`. Without it a client makes no roster read (remote-roster.mjs `remoteRosterState`: "gated"). */
73
+ export const cliReadsRemotes = (cli) => !!cli.ok && !!cli.remote?.includes("roster");
71
74
  const identityFeature = (held) => !!held.cli.features?.includes("workspace-identity");
72
75
  /** One deployment's identity, attachment, machine label and reason. */
73
76
  export function deploymentInfo(held, d, terms) {
@@ -77,7 +80,8 @@ export function deploymentInfo(held, d, terms) {
77
80
  const live = observed?.status === "observed";
78
81
  // A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): its identity still places
79
82
  // it in its view, but it is stale, not live, and says why. Still reachable: this computer's own deployment.
80
- const readError = live && typeof entry.error === "string" ? entry.error : null;
83
+ // Whether one is kept is deployment-facts.mjs `keptFailure`'s to say, never a test of the message.
84
+ const kept = live ? keptFailure(entry) : null;
81
85
  const read = !live ? { status: "none" } : !identityFeature(held) ? { status: "feature" }
82
86
  : observed.reachable?.identityInvalid ? { status: "invalid" } : readIdentity(observed.reachable);
83
87
  const identity = read.status === "identity" ? read.identity : null;
@@ -85,9 +89,10 @@ export function deploymentInfo(held, d, terms) {
85
89
  // Not observed (yet): the reading or unavailable sentence, never a silent empty.
86
90
  const unavailable = live ? null : deploymentUnavailableText(observed || { status: "pending" }, terms);
87
91
  return { id: d.id, local: true, machine: terms.thisMachine, path: d.id, label: shortPath(d.id, { home: held.home }), name: d.name,
88
- live: live && !readError, reachable: live, ...(readError ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
92
+ live: live && !kept, reachable: live, ...(kept ? { stale: true } : {}), identityFrom: identity ? "reported" : null, identity, attach,
89
93
  teamLabel: identity?.defaultTeam?.label ?? null,
90
- ...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable, readError }, terms)),
94
+ ...reasonFields(deploymentReasonParts({ local: true, identityStatus: read.status, attach, ref: identity?.ref, unavailable,
95
+ ...(kept ? { readError: kept.message, readErrorOrigin: kept.origin } : {}) }, terms)),
91
96
  note: attach.note === "standalone" ? deploymentReason({ local: true, attach: { unattached: "standalone" } }, terms) : null };
92
97
  }
93
98
  const g = d.group, machine = g.label || g.server;
@@ -101,7 +106,7 @@ export function deploymentInfo(held, d, terms) {
101
106
  const identity = read.status === "identity" ? read.identity : null;
102
107
  const attach = attachment(identity);
103
108
  const reason = reasonFields(deploymentReasonParts({ local: false, machine, sshHost: g.target?.sshHost, probe: g.probe, identityStatus: read.status, attach,
104
- ref: identity?.ref, cliReadsRemotes: cliReadsRemotes(held), rosterError: g.remembered ? held.rosterFailure : null }, terms));
109
+ ref: identity?.ref, cliReadsRemotes: cliReadsRemotes(held.cli), rosterError: g.remembered ? held.rosterFailure : null }, terms));
105
110
  const moved = held.remembered.note(g.id);
106
111
  const standalone = attach.note === "standalone" ? deploymentReason({ local: false, attach: { unattached: "standalone" } }, terms) : null;
107
112
  return { id: d.id, local: false, machine, path: g.target?.workspace || "", label: shortPath(g.target?.workspace || ""), name: d.name,
@@ -216,9 +221,10 @@ export function deploymentEntry(info, primary) {
216
221
 
217
222
  /** One deployment's own panel, as served before views. */
218
223
  export function deploymentPanel(held, ws) {
219
- if (ws?.remote) return { ...remotePanel(ws.group, held.at), observedAt: null, refreshing: held.remoteCollecting };
224
+ // Another machine's panel never says who made its `error`: the key is removed here whatever the panel carried.
225
+ if (ws?.remote) { const { errorOrigin: _sent, ...panel } = remotePanel(ws.group, held.at); return { ...panel, observedAt: null, refreshing: held.remoteCollecting }; }
220
226
  const observed = ws ? held.snapshot.byWs.get(ws.id) : null;
221
- const instances = observed?.instances || [];
227
+ const instances = observed?.instances || [], kept = keptFailure(observed);
222
228
  return {
223
229
  workspace: ws ? { id: ws.id, name: ws.name, team: null } : null,
224
230
  team: null,
@@ -230,8 +236,9 @@ export function deploymentPanel(held, ws) {
230
236
  refreshing: !!ws && held.observing.has(ws.id),
231
237
  running: instances.filter((i) => i.running).length,
232
238
  instances,
233
- // A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): the kernel's message and its bounded cause.
234
- ...(typeof observed?.error === "string" ? { error: observed.error } : {}),
239
+ // A failed re-read kept the last observation (deployment-panel.mjs `failedEntry`): its message, who made it
240
+ // (`errorOrigin`, "kernel" or absent) and its bounded cause. `error` is a string exactly when one is kept.
241
+ ...(kept ? { error: kept.message, ...(kept.origin ? { errorOrigin: kept.origin } : {}) } : {}),
235
242
  ...(observed?.errorCause ? { errorCause: observed.errorCause } : {}),
236
243
  };
237
244
  }
@@ -14,7 +14,9 @@ export const absolute = v => typeof v === 'string' && v.startsWith('/') && v.len
14
14
  const name = v => typeof v === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]{0,255}$/.test(v);
15
15
  const exact = (v, keys) => record(v) && Object.keys(v).every(k => keys.includes(k));
16
16
  const states = ['pass', 'fail', 'unknown', 'not-applicable'];
17
- const unsafe = /[\x00-\x08\x0b-\x1f\x7f]|[a-z][a-z0-9+.-]*:\/\/[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
17
+ // The URL alternative finds `://` first and looks behind it for the scheme, as display-text.mjs `UNSAFE`
18
+ // does and for its reason: time that grows with the length of the text, not with the square of a run.
19
+ const unsafe = /[\x00-\x08\x0b-\x1f\x7f]|:\/\/(?<=[a-z][a-z0-9+.-]*:\/\/)[^\s/]*@|(?:token|authorization|password|secret|api[_ -]?key)\s*[:=]\s*\S+/i;
18
20
  function text(v, max = 1024) { if (typeof v !== 'string' || v.length > max) throw Error(); return unsafe.test(v) ? '[Detail withheld]' : v; }
19
21
  const nullable = v => v == null ? null : text(v);
20
22
  export function readinessSelector(v) {
@@ -1,6 +1,6 @@
1
1
  /** Which roster rows can be addressed, why a row can't, and the copy for a remote read or plan
2
2
  * that the host (or this machine's router) refused. Shared by the renderer and the server. */
3
- import { unsupportedSession } from './instance-presentation.mjs';
3
+ import { unsupportedSession, runtimeErrorSpeaker, HERDR_STAND_IN } from './instance-presentation.mjs';
4
4
  import { displayLine, cleanLine, DETAIL_WITHHELD } from './display-text.mjs';
5
5
 
6
6
  /** A local row, or a remote row the kernel reports addressable (routed by `--server <id> --home <abs>`).
@@ -28,18 +28,43 @@ export function unaddressableSentence(row) {
28
28
  : `${shownLabel(label, true)} did not report this instance as reachable.`;
29
29
  }
30
30
 
31
- /** Why a row can't be opened, as `{key, label, sentence}`, or null when nothing stands in the way.
31
+ /** The `origin` of a reason whose sentence is a row's text that reached `rowReason` beside no speaker (no
32
+ * `runtimeErrorOrigin`, or a value that is none of the three; a text that is not a string). It stands
33
+ * for a text nobody attributed: it names no speaker, and instance-presentation.mjs `originLead` has no
34
+ * words for it. Written here and nowhere else, never read from a row or an answer. */
35
+ const UNATTRIBUTED = 'unattributed';
36
+
37
+ /** Why a row can't be opened, as `{key, label, sentence, origin?}`, or null when nothing stands in the way.
32
38
  * `label` is the roster meta line's state segment; `sentence` is the row's title, accessible
33
- * description and actions-menu reason. */
39
+ * description and actions-menu reason.
40
+ *
41
+ * **`origin` is there exactly when the sentence is not this home's own, and whoever writes such a
42
+ * sentence sets it in the same expression.** Here that is `quoted()`, the one expression that puts the
43
+ * row's `runtimeError` in a reason: it answers the text and its `origin` together, the row's
44
+ * `runtimeErrorOrigin` when that names one of the three speakers (instance-presentation.mjs), else
45
+ * "unattributed". That can be so for the keys `herdr`, `unreached` and `unknown`. A sentence written
46
+ * here (`own(…)`: `missing`, `unaddressable`, a row with no text of its own) has no `origin`.
47
+ *
48
+ * A client hangs its display filter on the key: a sentence with an `origin` is text from outside, shown
49
+ * through display-text.mjs `displayLine` and after the speaker's words when the value names one; a
50
+ * sentence with none is this home's own, shown as written, never under a speaker's name. So a missing
51
+ * `origin` can never hide a text from outside: no path here picks the row's text without one.
52
+ *
53
+ * The Herdr stand-in (instance-presentation.mjs `HERDR_STAND_IN`) is the one text of a row with no
54
+ * `origin`: it is this home's sentence also where a panel's row holds it as its `runtimeError`
55
+ * (remote-roster.mjs `remotePanel` writes it there), beside no speaker. */
34
56
  export function rowReason(row) {
35
57
  const label = serverLabel(row);
58
+ const quoted = () => ({ sentence: row.runtimeError, origin: runtimeErrorSpeaker(row) ?? UNATTRIBUTED });
59
+ const own = (sentence) => ({ sentence });
60
+ // What unsupportedSession answers is the row's own text or the stand-in. The stand-in's bytes beside no
61
+ // speaker are this home's sentence; any other text the row holds is quoted, with or without a speaker.
36
62
  const herdr = unsupportedSession(row);
37
- if (herdr) return { key: 'herdr', label: 'Herdr no longer supported', sentence: herdr };
38
- if (row.server && row.serverUnreached) return { key: 'unreached', label: `${label} not reached`,
39
- sentence: row.runtimeError || `${label} was not reached.` };
40
- if (row.server && row.missingRemotely === true) return { key: 'missing', label: `gone from ${label}`, sentence: unaddressableSentence(row) };
41
- if (!canAddressRemote(row)) return { key: 'unaddressable', label: `not reachable on ${label}`, sentence: unaddressableSentence(row) };
42
- if (row.running == null) return { key: 'unknown', label: 'state unknown', sentence: row.runtimeError || `${row.instance}: status unknown` };
63
+ if (herdr) return { key: 'herdr', label: 'Herdr no longer supported', ...(herdr === row.runtimeError && (herdr !== HERDR_STAND_IN || runtimeErrorSpeaker(row)) ? quoted() : own(herdr)) };
64
+ if (row.server && row.serverUnreached) return { key: 'unreached', label: `${label} not reached`, ...(row.runtimeError ? quoted() : own(`${label} was not reached.`)) };
65
+ if (row.server && row.missingRemotely === true) return { key: 'missing', label: `gone from ${label}`, ...own(unaddressableSentence(row)) };
66
+ if (!canAddressRemote(row)) return { key: 'unaddressable', label: `not reachable on ${label}`, ...own(unaddressableSentence(row)) };
67
+ if (row.running == null) return { key: 'unknown', label: 'state unknown', ...(row.runtimeError ? quoted() : own(`${row.instance}: status unknown`)) };
43
68
  return null;
44
69
  }
45
70
 
@@ -0,0 +1,94 @@
1
+ /** What a client remembers of the machines its roster answers reported (#482; #855, 3a): the last
2
+ * workspace identity each remote roster group reported, keyed by the group id (`<server>:<targetKey>`,
3
+ * the kernel's own group key), and the sentence left for a machine that moved to another workspace.
4
+ * A machine that stops answering keeps its place in its workspace through it ("not reached",
5
+ * identityFrom "remembered": panel-views.mjs `deploymentInfo`). A fresh report always wins. Only
6
+ * remote groups are remembered: memory never attaches a local deployment.
7
+ *
8
+ * No state. The memory and the notes are two Maps the client holds and passes in:
9
+ *
10
+ * memory: Map<group id, { server, label, targetKey, path, workspace, reportedAt }>
11
+ * notes: Map<group id, string> the sentence for a machine that moved to another workspace
12
+ *
13
+ * `observeIdentities` answers new Maps and changes neither. Where a client keeps them between calls,
14
+ * and whether on disk, is its own: the Desktop's file is packages/desktop/server/remote-identity.mjs.
15
+ * Nothing here caps the memory: an answer drops every group it no longer lists, so the memory is
16
+ * never larger than the roster answer. */
17
+ import { readIdentity, attachment, viewId } from './workspace-views.mjs';
18
+
19
+ const GROUP_ID = /^[a-z0-9][a-z0-9-]{0,63}:[A-Za-z0-9._-]{1,128}$/;
20
+ const SERVER = /^[a-z0-9][a-z0-9-]{0,63}$/;
21
+ const text = v => typeof v === 'string' && v.length > 0 && v.length <= 2048 && !v.includes('\0');
22
+
23
+ /** A remembered entry read from outside the client (a file): the entry as the memory keeps it, or null
24
+ * when the id or any field of `raw` is not what `observeIdentities` would have stored. */
25
+ export function entryOf(id, raw) {
26
+ if (!GROUP_ID.test(id) || !raw || typeof raw !== 'object') return null;
27
+ const { server, label, targetKey, path, workspace, reportedAt } = raw;
28
+ if (!SERVER.test(server ?? '') || !text(label) || !text(targetKey) || id !== `${server}:${targetKey}` || !text(path) || !path.startsWith('/')
29
+ || !text(reportedAt) || Number.isNaN(Date.parse(reportedAt))) return null;
30
+ const read = readIdentity(workspace);
31
+ if (read.status !== 'identity') return null;
32
+ return { server, label, targetKey, path, workspace: read.identity, reportedAt };
33
+ }
34
+
35
+ const sameIdentity = (a, b) => JSON.stringify(a) === JSON.stringify(b);
36
+ /** The view an identity attaches to, or null (an unattached identity has no workspace view). */
37
+ const viewOf = identity => { const a = attachment(identity); return a.unattached ? null : viewId(a.key, a.team); };
38
+ /** The name the move note gives the new workspace: the last segment of its key. */
39
+ const workspaceName = identity => identity?.key ? String(identity.key).split('/').filter(Boolean).pop() : null;
40
+
41
+ /**
42
+ * One roster answer: remember each fresh report, note a move, and drop the memory (and the note) of
43
+ * every group the answer no longer lists. Only a group that was reached (`probe.ok === true`), whose id
44
+ * and server have the kernel's form, whose path is absolute and whose workspace reads as an identity
45
+ * (a `key` field) is a report; a failed probe changes nothing, and its group is kept while listed. A
46
+ * report equal to what is remembered (identity, label, path) changes nothing. A report that moves the
47
+ * group to another view leaves its note.
48
+ *
49
+ * A group whose id or server is not in the kernel's form (GROUP_ID and SERVER above: a lower-case server
50
+ * name, and `<server>:<targetKey>`) is never remembered, and says nothing of it: a client's fixture
51
+ * needs the real forms, or its machine leaves its view the first time it does not answer.
52
+ *
53
+ * `groups` is what remote-roster.mjs `remoteRosterState` answers as `reported`; `at` is the caller's
54
+ * time, kept as each new entry's `reportedAt`.
55
+ * @param {{ memory: Map, notes: Map }} held
56
+ * @param {Array<{id, server, label, target:{workspace}, probe, workspace}>} groups
57
+ * @returns {{ memory: Map, notes: Map, changed: boolean }} new Maps; `changed` says the memory changed
58
+ * (a client that keeps it on disk writes then).
59
+ */
60
+ export function observeIdentities({ memory, notes }, groups, at) {
61
+ if (typeof at !== 'string' || !at) throw new TypeError('observeIdentities: at must be the time of the call, a non-empty string');
62
+ const next = new Map(memory), nextNotes = new Map(notes);
63
+ let changed = false;
64
+ const listed = new Set(groups.map(g => g.id));
65
+ for (const id of [...next.keys()]) if (!listed.has(id)) { next.delete(id); nextNotes.delete(id); changed = true; }
66
+ for (const g of groups) {
67
+ if (g?.probe?.ok !== true || !GROUP_ID.test(g.id ?? '') || !SERVER.test(g.server ?? '')) continue;
68
+ const read = readIdentity(g.workspace);
69
+ if (read.status !== 'identity') continue;
70
+ const targetKey = g.id.slice(g.server.length + 1);
71
+ const path = g.target?.workspace;
72
+ if (!text(path) || !path.startsWith('/')) continue;
73
+ const previous = next.get(g.id);
74
+ if (previous && sameIdentity(previous.workspace, read.identity) && previous.label === (g.label || g.server) && previous.path === path) continue;
75
+ if (previous && !sameIdentity(previous.workspace, read.identity) && viewOf(previous.workspace) !== viewOf(read.identity)) {
76
+ const name = workspaceName(read.identity);
77
+ nextNotes.set(g.id, name ? `${g.label || g.server} now reports workspace ${name}.` : `${g.label || g.server} now reports another workspace.`);
78
+ }
79
+ next.set(g.id, { server: g.server, label: text(g.label) ? g.label : g.server, targetKey, path, workspace: read.identity, reportedAt: at });
80
+ changed = true;
81
+ }
82
+ return { memory: next, notes: nextNotes, changed };
83
+ }
84
+
85
+ /** The three readers panel-views.mjs takes as `held.remembered`, over one memory and its notes. They
86
+ * read and change nothing: `get(id)` is the remembered entry of a group, or null; `note(id)` the move
87
+ * sentence of a group, or null; `all()` every remembered entry, each with its `id`. */
88
+ export function identityMemory({ memory, notes }) {
89
+ return {
90
+ get: id => memory.get(id) ?? null,
91
+ note: id => notes.get(id) ?? null,
92
+ all: () => [...memory.entries()].map(([id, e]) => ({ id, ...e })),
93
+ };
94
+ }
@@ -1,5 +1,6 @@
1
1
  import { harnessOf } from "./harness-names.mjs";
2
- import { unsupportedSession } from "./instance-presentation.mjs";
2
+ import { unsupportedSession, unsupportedSessionOrigin, hasRuntimeError } from "./instance-presentation.mjs";
3
+ import { madeByKernel } from "./kernel-made.mjs";
3
4
  import { waitingOnYouData } from "./waiting-on-you.mjs";
4
5
  /** Projection of the installed CLI's remote roster. Never reads remote paths locally. */
5
6
  export function remoteWorkspace(group) {
@@ -10,16 +11,41 @@ export function remoteWorkspace(group) {
10
11
  };
11
12
  }
12
13
 
13
- /** A remote deployment's panel. `at` is the time the panel is made, an ISO string: a caller that holds
14
- * the time of its call passes it (panel-views.mjs passes `held.at`); without it the clock is read. */
15
- export function remotePanel(group, at = new Date().toISOString()) {
14
+ /** The time a caller gives, or a TypeError when it gave none: this module reads no clock. `table` names
15
+ * the function that was called without it (as client-terms.mjs `requireTerms` does for terms). */
16
+ function requireTime(at, table) {
17
+ if (typeof at !== "string" || !at) throw new TypeError(`${table}: at must be the time of the call, a non-empty string`);
18
+ return at;
19
+ }
20
+
21
+ /** A remote deployment's panel. `at` is the time the panel is made, an ISO string, and is required: the
22
+ * caller holds the time of its call (panel-views.mjs passes `held.at`) and no clock is read here.
23
+ *
24
+ * A row is the host's row, spread whole, so a row with a `runtimeError` gets its speaker here
25
+ * (`runtimeErrorOrigin`; instance-presentation.mjs names the three) and any other row gets none: a
26
+ * `runtimeErrorOrigin` a host sent never survives, on any path. Which text it is decides:
27
+ *
28
+ * a Herdr row "kernel" for the host's own reason, no key for the stand-in
29
+ * a reached server the host's row text: "kernel" (a host's OATS, relayed)
30
+ * a server not reached, an error the "kernel": the mark of kernel-made.mjs, set where the roster's
31
+ * installed CLI printed answer is parsed (cli-adapter.mjs `cliRemoteRoster`)
32
+ * a server not reached, any other "roster-read": written while the roster was read (a read
33
+ * error, or none ("Server is that threw, a timeout, an answer that is not the contract's)
34
+ * unreachable")
35
+ *
36
+ * No code and no message is read to decide it. The mark is on the error object: a group is held and
37
+ * passed back as it was answered (`remoteRosterState`), and a copy of its `probe.error` reads as
38
+ * "roster-read", never as the kernel's. */
39
+ export function remotePanel(group, at) {
40
+ requireTime(at, "remotePanel");
16
41
  const ws = remoteWorkspace(group);
17
42
  // A row's soul subtitle: its own group's soul list only, a string as the host reported it, never synthesized.
18
43
  const described = name => { const soul = (group.souls || []).find((a) => a?.name === name); return typeof soul?.description === "string" ? soul.description : null; };
19
44
  // A Herdr-recorded row is unsupported whatever the host's probe said: it cannot open or start.
20
- const instances = (group.instances || []).map(({ runtime: _released, ...i }) => {
45
+ const instances = (group.instances || []).map(({ runtime: _released, runtimeErrorOrigin: _sent, ...i }) => {
21
46
  const unsupported = unsupportedSession(i);
22
- return {
47
+ const origin = unsupported ? unsupportedSessionOrigin(i) : group.probe.ok || (group.probe.error?.message && madeByKernel(group.probe.error)) ? "kernel" : "roster-read";
48
+ const row = {
23
49
  ...i, server: group.server, savedRoute: i.savedRoute === true,
24
50
  // The last roster read of this server failed: its rows are last-known, their state unknown.
25
51
  serverUnreached: !group.probe.ok,
@@ -33,6 +59,7 @@ export function remotePanel(group, at = new Date().toISOString()) {
33
59
  ...(Object.hasOwn(i, "waitingOnYou") ? { waitingOnYou: waitingOnYouData(i.waitingOnYou) } : {}),
34
60
  ...(unsupported ? { running: null, runtimeState: "unsupported", runtimeError: unsupported } : {}),
35
61
  };
62
+ return hasRuntimeError(row) && origin ? { ...row, runtimeErrorOrigin: origin } : row;
36
63
  });
37
64
  return {
38
65
  workspace: { id: ws.id, name: ws.name, scope: ws.scope, team: null, server: ws.server,
@@ -59,6 +86,65 @@ export function unavailableGroups(groups, error) {
59
86
  return groups.map((g) => ({ ...g, probe: { ok: false, error }, instances: (g.instances || []).map((i) => ({ ...i, running: null })) }));
60
87
  }
61
88
 
89
+ /** The roster read's failure in words, and as the error an unavailable group carries. */
90
+ const ROSTER_UNAVAILABLE = "Remote roster unavailable";
91
+ const rosterError = (message) => ({ code: "E_REMOTE_ROSTER", message });
92
+
93
+ /**
94
+ * What one outcome of `oats server roster --json` makes of the roster a client holds. No state: the
95
+ * client keeps the three values between reads and passes them back as `previous`.
96
+ *
97
+ * previous: { remoteGroups, rosterAnswered, rosterFailure }
98
+ * outcome: { gated: true } no accepted CLI, or one that does not read other machines
99
+ * (panel-views.mjs `cliReadsRemotes`): the read was not made
100
+ * | { envelope } what the CLI answered (cli-adapter.mjs `cliRemoteRoster`)
101
+ * | { thrown: string } the read failed: the message of what was thrown
102
+ * at: the caller's time, the one `remotePanel` stamps
103
+ * -> { remoteGroups, rosterAnswered, rosterFailure, reported }
104
+ *
105
+ * `remoteGroups` is the last readable roster: an answer replaces it only when every group of it can be
106
+ * projected (`remotePanel`), and a failed read keeps the groups held, each marked not reached
107
+ * (`unavailableGroups`). `rosterAnswered` says an answer arrived; `rosterFailure` is the failure's
108
+ * sentence, kept only while none has. `reported` is what the client hands to its memory of identities
109
+ * (remote-identity-memory.mjs `observeIdentities`): the groups of an `ok` envelope, else null.
110
+ *
111
+ * The sentence of a thrown read carries the message of an error from outside the client: a client
112
+ * shows it through `displayLine` (display-text.mjs) only.
113
+ *
114
+ * What stays the caller's: one read at a time, when it runs, and dropping an answer that was read
115
+ * with a kernel record that is no longer the accepted one. And its own `try`/`catch` around the read
116
+ * and around what it does with `reported`: if that step throws after the caller took the new state, the
117
+ * caller takes `{ thrown: <message> }` next, so the groups it just took are marked not reached.
118
+ */
119
+ export function remoteRosterState(previous, outcome, at) {
120
+ requireTime(at, "remoteRosterState");
121
+ if (outcome.gated) return { remoteGroups: [], rosterAnswered: false, rosterFailure: previous.rosterFailure, reported: null };
122
+ /** A read with no answer to keep: the groups held, marked; the sentence only while no answer has ever arrived. */
123
+ const failed = (message) => ({
124
+ remoteGroups: unavailableGroups(previous.remoteGroups, rosterError(message)), rosterAnswered: previous.rosterAnswered,
125
+ rosterFailure: previous.rosterAnswered ? previous.rosterFailure : message, reported: null,
126
+ });
127
+ if (!Object.hasOwn(outcome, "envelope")) return failed(`${ROSTER_UNAVAILABLE}: ${outcome.thrown}`);
128
+ try {
129
+ const env = outcome.envelope;
130
+ const incoming = env.ok && Array.isArray(env.result?.groups)
131
+ ? env.result.groups : unavailableGroups(previous.remoteGroups, env.error || rosterError(ROSTER_UNAVAILABLE));
132
+ for (const group of incoming) remotePanel(group, at); // validate before replacing the last readable roster
133
+ if (env.ok) return { remoteGroups: incoming, rosterAnswered: true, rosterFailure: null, reported: incoming };
134
+ return { remoteGroups: incoming, rosterAnswered: previous.rosterAnswered,
135
+ rosterFailure: previous.rosterAnswered ? previous.rosterFailure : env.error?.message || ROSTER_UNAVAILABLE, reported: null };
136
+ } catch (e) {
137
+ // An answer that cannot be read, or a group of it that cannot be projected: as a read that threw.
138
+ return failed(`${ROSTER_UNAVAILABLE}: ${e.message}`);
139
+ }
140
+ }
141
+
142
+ /** The panel of each group, keyed as a client's snapshot keys it: [[`remote:<group id>`, panel], …], every one made at `at`. */
143
+ export function remotePanelEntries(remoteGroups, at) {
144
+ requireTime(at, "remotePanelEntries");
145
+ return remoteGroups.map((group) => { const panel = remotePanel(group, at); return [panel.workspace.id, panel]; });
146
+ }
147
+
62
148
  export function spawnedWorkspace(groups, result) {
63
149
  if (!result.server || !result.target) return undefined;
64
150
  const group = groups.find((g) => g.server === result.server && g.registrationPresent
@@ -0,0 +1,175 @@
1
+ // Remote terminal addressing is an installed-CLI operation, never a renderer
2
+ // supplied SSH command, executable path, socket or server registration.
3
+ //
4
+ // Opening an agent's terminal with the kernel's own viewer (`oats session attach`): the arguments
5
+ // of the viewer for this machine and for another, whether its detach key can be used, and, for
6
+ // another machine, the preflight (`oats session inspect`) that runs before the viewer starts.
7
+ //
8
+ // A failed `prepareRemoteTerm` throws one of these, and `preflightFailure` reads any of them:
9
+ //
10
+ // code E_TERM_CONTEXT_CHANGED the caller's `signal` aborted or its `current()` turned false
11
+ // code E_TERM_REMOTE_NO_SSH, the preflight's own outcomes: terminal-contract.mjs has a
12
+ // E_TERM_REMOTE_UNREACHABLE, sentence for each
13
+ // E_TERM_PREPARE_TIMEOUT,
14
+ // E_TERM_REMOTE_NO_ANSWER,
15
+ // E_TERM_REMOTE_GONE, E_HERDR_REMOVED
16
+ // any other refusal envelope the kernel's refusal, or a host's relayed by it, with its
17
+ // `code` and `message` as given (E_TERM_OPEN_FAILED and a
18
+ // fixed message where it gave none)
19
+ // code unsupported-remote-operation, the installed CLI cannot do it: decided before any process
20
+ // unsupported-detach-key
21
+ // no code, or one that is not a string the target was invalid, the CLI did not start, or it
22
+ // answered no envelope
23
+ //
24
+ // Not loadable by a page: it reaches `node:` builtins through its runner.
25
+ import { requireRemoteSupport } from "./cli-locator.mjs";
26
+ import { runTerminalCommand } from './terminal-exec.mjs';
27
+ import { HERDR_REMOVED, terminalFailure, terminalMessage } from './terminal-contract.mjs';
28
+
29
+ /** The kernel feature of `session attach --detach-key` (docs/desktop-cli-api.md). */
30
+ export const DETACH_KEY_FEATURE = "session-attach-detach-key";
31
+ /** The kernel feature under which a roster group's `probe.features` is the host's own list
32
+ * (docs/desktop-cli-api.md, `probe.features`). Without it that key says nothing. */
33
+ const PROBE_FEATURES_FEATURE = "server-probe-features";
34
+ // Array.isArray, as in requireRemoteSupport: a string must not pass a gate that exists to fail closed.
35
+ const lists = (cli, feature) => cli?.ok === true && Array.isArray(cli.features) && cli.features.includes(feature);
36
+
37
+ /** This machine's CLI takes the key: an accepted probe (`cli.ok === true`) whose `features` is an
38
+ * array naming the feature. */
39
+ export function detachKeySupported(cli) {
40
+ return lists(cli, DETACH_KEY_FEATURE);
41
+ }
42
+ /** The key can be offered for a row on another machine: this machine's CLI takes it and relays what
43
+ * each host lists about itself, the group's last roster read succeeded, and the host's own list
44
+ * names the feature. `group` is a group of `oats server roster --json` as read. `features: null`,
45
+ * a missing key and a failed read are unknown, and unknown is not supported; nothing is decided
46
+ * from a refusal and nothing probes. For what a client offers only: `sessionAttachArgv` does not
47
+ * ask it, because the kernel refuses a host without the feature and starts no viewer. */
48
+ export function hostDetachKeySupported(cli, group) {
49
+ const probe = group?.probe;
50
+ return detachKeySupported(cli) && lists(cli, PROBE_FEATURES_FEATURE)
51
+ && probe?.ok === true && Array.isArray(probe.features) && probe.features.includes(DETACH_KEY_FEATURE);
52
+ }
53
+
54
+ const coded = (code, message) => Object.assign(new Error(message), { code });
55
+ const herdrRemoved = message => coded('E_HERDR_REMOVED', message);
56
+ const unreachable = () => coded('E_TERM_REMOTE_UNREACHABLE', 'the remote server could not be reached');
57
+ /** The CLI's JSON envelope, or null when it printed none. */
58
+ function envelopeOf(stdout) {
59
+ let envelope;
60
+ try { envelope = JSON.parse(stdout); } catch { return null; }
61
+ return envelope?.schemaVersion === 1 && typeof envelope.ok === 'boolean' ? envelope : null;
62
+ }
63
+ /** What a refusal said, for each error `refusal` returns from its last line: the envelope's own
64
+ * `code`, `message` and `details.fix`, each null where it gave no string. Kept beside the error and
65
+ * not on it, so the error thrown has the properties it always had; read by `preflightFailure` only. */
66
+ const keptRefusals = new WeakMap();
67
+ const stringOrNull = value => (typeof value === 'string' ? value : null);
68
+ /** A refusal envelope as a coded error. The CLI reports ssh's own failure as E_SSH: a transport
69
+ * failure, unless its details say ssh never started on this computer (nothing to retry); a 0.31
70
+ * kernel's E_HERDR_REMOVED keeps its message; any other refusal keeps the host's code. */
71
+ function refusal(envelope) {
72
+ const { code, message, details } = envelope.error || {};
73
+ if (code === 'E_SSH' && details?.sshStarted === false) return coded('E_TERM_REMOTE_NO_SSH', 'ssh is not available on this computer');
74
+ if (code === 'E_SSH') return unreachable();
75
+ if (code === 'E_HERDR_REMOVED') return herdrRemoved(typeof message === 'string' && message ? message : HERDR_REMOVED);
76
+ const error = coded(typeof code === 'string' && code ? code : 'E_TERM_OPEN_FAILED', message || 'remote session inspection failed');
77
+ keptRefusals.set(error, { code: stringOrNull(code), message: stringOrNull(message), fix: stringOrNull(details?.fix) });
78
+ return error;
79
+ }
80
+ /** What a failed preflight says. `error` is what `prepareRemoteTerm` threw; `server` is the label a
81
+ * sentence names.
82
+ *
83
+ * code the terminal table's code for it (E_TERM_OPEN_FAILED for anything the table does not know)
84
+ * sentence the table's sentence, naming `server` where it has a place for one
85
+ * said null, or { code, message, fix }: what the kernel said (this machine's, or another
86
+ * host's relayed by it), only for a refusal kept as it came for which the table has no
87
+ * sentence of its own. Each is the envelope's own string or null, and `said` is null
88
+ * when all three are. Text from outside: a client draws `message` and `fix` with
89
+ * kernel-lines.mjs `kernelLines` and nothing else.
90
+ *
91
+ * Any other error has `said: null`, also one made by hand with a refusal's code and message: the
92
+ * message of a CLI that did not start holds a path and is never shown. */
93
+ export function preflightFailure(error, server) {
94
+ const code = terminalFailure(error?.code).code;
95
+ const kept = code === 'E_TERM_OPEN_FAILED' ? keptRefusals.get(error) : undefined;
96
+ const said = kept && (kept.code !== null || kept.message !== null || kept.fix !== null) ? { ...kept } : null;
97
+ return { code, sentence: terminalMessage(error?.code, server), said };
98
+ }
99
+
100
+ /** A remote terminal is its server and its absolute home: routed as `--server S --home H`, never by a bare name. */
101
+ export function remoteTargetKey(remote) {
102
+ if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(remote?.serverId || "")
103
+ || !/^[a-z0-9][a-z0-9-]*$/.test(remote?.instance || "")) throw new Error("invalid remote terminal target");
104
+ if (typeof remote.home !== "string" || !remote.home.startsWith("/") || remote.home.includes("\0")) throw new Error("invalid remote terminal home");
105
+ return JSON.stringify(["remote", remote.serverId, remote.home]);
106
+ }
107
+ /** The arguments of the kernel's viewer (the binary is `cli.bin`), a new array each call.
108
+ *
109
+ * target { home } on this machine; { serverId, instance, home } on another (what
110
+ * `remoteTargetKey` admits, and it refuses as it always did)
111
+ * detachKey undefined for none; else a non-empty string, appended as `--detach-key <key>`
112
+ *
113
+ * The client holds no copy of the kernel's key grammar: a key the kernel does not accept is the
114
+ * kernel's refusal. A key for a CLI that does not take one throws `unsupported-detach-key`: a
115
+ * kernel without the feature ignores the flag and opens a viewer with no exit, so the flag is
116
+ * never tried (docs/desktop-cli-api.md). Its message is for a developer; a client decides what it
117
+ * offers with `detachKeySupported`. */
118
+ export function sessionAttachArgv(cli, target, { detachKey } = {}) {
119
+ let address;
120
+ if (target?.serverId !== undefined) {
121
+ remoteTargetKey(target);
122
+ address = ["--server", target.serverId, "--home", target.home];
123
+ } else {
124
+ if (typeof target?.home !== "string" || !target.home.startsWith("/") || target.home.includes("\0")) throw new Error("invalid session home");
125
+ address = ["--home", target.home];
126
+ }
127
+ if (detachKey === undefined) return ["session", "attach", ...address];
128
+ if (typeof detachKey !== "string" || !detachKey) throw new TypeError("a detach key is a non-empty string");
129
+ if (!detachKeySupported(cli)) throw Object.assign(new Error(`installed oats ${cli?.version || "unknown"} does not support session attach --detach-key; update the CLI`), { code: "unsupported-detach-key" });
130
+ return ["session", "attach", ...address, "--detach-key", detachKey];
131
+ }
132
+ /** The preflight of an attach on another machine, and the viewer to start after it: { binary, args }.
133
+ *
134
+ * run the whole run of the CLI, in the shape of terminal-exec.mjs `runTerminalCommand`; a
135
+ * caller that passes it owns the run, and `exec` is then not used
136
+ * exec what the default runner starts the CLI with, in `execFile`'s signature
137
+ * detachKey as `sessionAttachArgv` takes it. The viewer's arguments are built before the
138
+ * inspect runs, so a key that cannot be used starts no process; the inspect never
139
+ * carries the key. */
140
+ export async function prepareRemoteTerm(cli, remote, { exec, run = (binary, args, options) => runTerminalCommand(binary, args, options, exec), signal, current = () => true, detachKey } = {}) {
141
+ const check = () => { if (signal?.aborted || !current()) throw Object.assign(new Error('Terminal context changed'), { code: 'E_TERM_CONTEXT_CHANGED' }); };
142
+ check();
143
+ requireRemoteSupport(cli, "session");
144
+ const bin = cli.bin;
145
+ remoteTargetKey(remote);
146
+ const address = ["--server", remote.serverId, "--home", remote.home];
147
+ const args = sessionAttachArgv(cli, remote, { detachKey });
148
+ check(); // actual execution owner, not only IPC admission
149
+ let stdout;
150
+ try {
151
+ ({ stdout } = await run(bin, ["session", "inspect", ...address, "--json"], {
152
+ encoding: "utf8", timeout: 20000, maxBuffer: 1024 * 1024, shell: false, ...(signal ? { signal } : {}),
153
+ }));
154
+ } catch (error) {
155
+ check();
156
+ const envelope = typeof error?.stdout === 'string' ? envelopeOf(error.stdout) : null;
157
+ if (envelope && !envelope.ok) throw refusal(envelope);
158
+ // Killed by execFile at the deadline: a stalled link outlives ssh's keepalives (about 45 s),
159
+ // so it is a timeout. A CLI that ended without a refusal, by a nonzero exit (255 included) or
160
+ // a signal of its own, gave no answer: ssh's own failures arrive as E_SSH, so this is more
161
+ // likely the local CLI. A CLI that never started keeps its own error.
162
+ if (error?.killed) throw coded('E_TERM_PREPARE_TIMEOUT', 'remote session inspection timed out');
163
+ if (Number.isInteger(error?.code) || error?.signal) throw coded('E_TERM_REMOTE_NO_ANSWER', 'the local oats gave no answer');
164
+ throw error;
165
+ }
166
+ check();
167
+ const envelope = envelopeOf(stdout);
168
+ if (!envelope) throw new Error("remote session inspection answered no envelope");
169
+ if (!envelope.ok) throw refusal(envelope);
170
+ // A 0.31 kernel refuses a Herdr-recorded instance; an older one still reports its live Herdr
171
+ // session. Neither is attached: the refusal keeps its code so the broker reports it.
172
+ if (envelope.result?.backend === 'herdr') throw herdrRemoved(HERDR_REMOVED);
173
+ if (envelope.result?.present !== true) throw coded('E_TERM_REMOTE_GONE', "remote terminal no longer exists");
174
+ return { binary: bin, args };
175
+ }
@@ -1,5 +1,5 @@
1
1
  /** Confirmed K6d input/data boundary. No kernel resolution or renderer key authority. */
2
- import { retainedSpawnDetails } from './launch-prompt-outcome.mjs';
2
+ import { retainedSpawnDetails, launchFlagIgnored, flagIgnoredFact } from './launch-prompt-outcome.mjs';
3
3
  import { harnessOf } from './harness-names.mjs';
4
4
  import { record, previewSupported, previewSelector, previewChoices, previewTarget, previewData, previewFailure, MAX_HOOKS } from './spawn-preview-contract.mjs';
5
5
  import { spawnDecision, sameSpawnDecision } from './spawn-decision.mjs';
@@ -74,7 +74,13 @@ export function spawnWakeOutcome(value, requested) {
74
74
  if (value.saved === false && !error) return null;
75
75
  return { requested: value.requested, saved: value.saved, error };
76
76
  }
77
- /** A qualified creation receipt, not executable terminal/session instructions. */
77
+ /** A qualified creation receipt, not executable terminal/session instructions.
78
+ *
79
+ * `flagIgnored` (optional) is the one fact of the kernel's answer the receipt carries as text: a launched
80
+ * spawn where Claude Code ignored the channel option (launchFlagIgnored: `launchPrompts.status`
81
+ * "flag-ignored", with the answer's warnings as bounded display lines). Absent for any other status, for
82
+ * an answer without `launchPrompts`, and for a spawn that was not launched. It holds facts and no sentence.
83
+ * Every other warning of an apply stays a count (`warningCount`). */
78
84
  export function spawnCreationReceipt(v, { target, preview, wakeRequested = false } = {}) {
79
85
  const selected = previewTarget(target), expected = spawnDecision(preview?.decision, { effectiveRequired: true });
80
86
  const decision = spawnDecision(v?.decision, { effectiveRequired: true });
@@ -93,10 +99,11 @@ export function spawnCreationReceipt(v, { target, preview, wakeRequested = false
93
99
  wake = spawnWakeOutcome({ requested: true, saved: false, error: v.wakeScheduleError }, true);
94
100
  }
95
101
  if (!wake) return null;
102
+ const flagIgnored = v.launched ? launchFlagIgnored(v) : null;
96
103
  return { instance: v.instance, agent: v.agent, home: v.home, agentsRoot: selected.selector.agentsRoot,
97
104
  workspace: selected.workspace, server: null, repo: v.repo, work: v.work, branch: v.branch,
98
105
  harness: harnessOf(v), model: v.model, launched: v.launched, replayed: v.replayed, decision,
99
- warningCount: v.warnings.length, wake };
106
+ warningCount: v.warnings.length, wake, ...(flagIgnored ? { flagIgnored } : {}) };
100
107
  }
101
108
  /** Project the Desktop HTTP view again at the main/renderer trust boundaries. */
102
109
  export function spawnApplyView(v, expected = {}) {
@@ -122,8 +129,13 @@ export function spawnApplyView(v, expected = {}) {
122
129
  if (['complete', 'partial'].includes(v.status)) {
123
130
  if (!record(v.receipt) || !Number.isInteger(v.receipt.warningCount) || v.receipt.warningCount < 0 || v.receipt.warningCount > 512
124
131
  || v.receipt.workspace !== target.workspace || v.receipt.agentsRoot !== target.selector.agentsRoot || v.receipt.server !== null) return null;
125
- receipt = spawnCreationReceipt({ ...v.receipt, warnings: Array(v.receipt.warningCount).fill('') }, { target, preview, wakeRequested: v.wakeRequested });
132
+ // The receipt is rebuilt from its own keys: the warnings are a count here, so `flagIgnored` is read from
133
+ // the receipt's key through the reader's decoder, never composed again. Tolerant: a value that does not
134
+ // decode is dropped, and the receipt stands.
135
+ receipt = spawnCreationReceipt({ ...v.receipt, warnings: Array(v.receipt.warningCount).fill(''), launchPrompts: undefined }, { target, preview, wakeRequested: v.wakeRequested });
126
136
  if (!receipt) return null;
137
+ const flagIgnored = receipt.launched ? flagIgnoredFact(v.receipt.flagIgnored) : undefined;
138
+ if (flagIgnored) receipt.flagIgnored = flagIgnored;
127
139
  const partial = v.wakeRequested && receipt.wake.saved !== true;
128
140
  if ((v.status === 'partial') !== partial) return null;
129
141
  if (partial) reason = receipt.wake.error ?? { code: 'E_WAKE_OUTCOME_UNKNOWN', message: WAKE_OUTCOME_UNKNOWN };