@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
package/lib/workspace.mjs CHANGED
@@ -41,6 +41,12 @@ function remoteOf(options) {
41
41
  /** The parsed cache (lib/remote.mjs memoAtCommit, optional on the remote contract): `compute()` is a pure
42
42
  * function of the bytes at (ref's key, commit) and this kernel. A remote without it — every in-memory fake —
43
43
  * just computes. */
44
+ /** Whether a member's enumeration may be missing a soul: it says so (`soulsSkipped`, enumerateRepo), or it
45
+ * carries no such record. What a read did not record, it did not establish: an enumeration that was not
46
+ * written by this build (whatever built it) says nothing about the souls it skipped, so it counts as one
47
+ * that skipped some. The parsed cache is not how that arises: its entries are kept per kernel fingerprint,
48
+ * and another build's are never read (lib/remote.mjs, test/parsed-cache.test.mjs). */
49
+ const skippedSome = (soulsSkipped) => !Array.isArray(soulsSkipped) || soulsSkipped.length > 0;
44
50
  function atCommit(remote, ref, commit, item, compute) {
45
51
  return typeof remote.memoAtCommit === "function" ? remote.memoAtCommit(ref, commit, item, compute) : compute();
46
52
  }
@@ -191,6 +197,15 @@ function* refFields(value) {
191
197
  for (const slot of ["knowledge", "messaging", "tasks", "capabilities"]) yield* froms(d[slot], `/defaults/${slot}`);
192
198
  }
193
199
  }
200
+ /** Only schema diagnostics for repository-reference fields pass the remote renderer. Provider
201
+ * payloads and unrelated invalid values keep their original diagnostics; admission uses raw values. */
202
+ function referenceProblems(problems, refs) {
203
+ const sources = new Map(refs);
204
+ return problems.map((problem) => sources.has(problem.path)
205
+ ? { ...problem, message: defaultRemote.redactUrl(problem.message, sources.get(problem.path), { known: false }) }
206
+ : problem);
207
+ }
208
+
194
209
  function refKey(remote, ref) {
195
210
  return remote.parseRepoRef(ref).key;
196
211
  }
@@ -208,7 +223,7 @@ function keyOrProblem(remote, ref, path, problems) {
208
223
  export function validateWorkspace(value, { remote = defaultRemote } = {}) {
209
224
  const problems = validateAgainst(schemaFor("workspace"), value);
210
225
  if (!isObject(value)) return problems;
211
- if (value.schemaVersion !== 2) return problems;
226
+ if (value.schemaVersion !== 2) return referenceProblems(problems, refFields(value));
212
227
  // Absolute-path refusal applies to REF/PATH fields only (L2): never to descriptions or the provider payload.
213
228
  for (const [path, s] of refFields(value)) {
214
229
  if (ABSOLUTE_PATH.test(s)) problems.push({ path, message: `absolute paths are refused in the workspace file (${show(s)}); host paths belong in oats-local.yaml (a local remote is a repo ref: file:///… or git:/abs/bare.git@<ref>)` });
@@ -245,7 +260,7 @@ export function validateWorkspace(value, { remote = defaultRemote } = {}) {
245
260
  for (const slot of ["knowledge", "messaging", "tasks", "capabilities"]) fromProblems(remote, d[slot], `/defaults/${slot}`, problems, { here: false });
246
261
  }
247
262
  sharedLabelProblems(value, problems);
248
- return withRemovedKeys(problems, value, REMOVED_KEYS.workspace);
263
+ return referenceProblems(withRemovedKeys(problems, value, REMOVED_KEYS.workspace), refFields(value));
249
264
  }
250
265
  /** Team model 3: every label `defaultTeam` and `souls:` name is a shared team of this same file, so an
251
266
  * unknown label is refused when the file is read, never at a spawn on someone else's machine. */
@@ -266,7 +281,9 @@ export function teamLabelProblem(label) {
266
281
  const problems = validateAgainst(schemaFor("workspace").$defs.label, label);
267
282
  return problems.length ? problems.map((x) => x.message).join("; ") : null;
268
283
  }
269
- export function validateMembership(value) { return withRemovedKeys(validateAgainst(schemaFor("membership"), value), value, REMOVED_KEYS.membership); }
284
+ export function validateMembership(value) {
285
+ return referenceProblems(withRemovedKeys(validateAgainst(schemaFor("membership"), value), value, REMOVED_KEYS.membership), [["/workspace", value?.workspace]]);
286
+ }
270
287
 
271
288
  /** Keys 0.30 (team model v2) and 0.38.0 (team model 3) removed: each is a schema problem naming its replacement, in place of
272
289
  * the schema's generic "unexpected property". `at(value)` → the JSON pointers where it appears. */
@@ -302,7 +319,11 @@ export function validateSoul(value, { remote = defaultRemote } = {}) {
302
319
  fromProblems(remote, value.capabilities, "/capabilities", problems, { here: true });
303
320
  for (const slot of ["knowledge", "messaging", "tasks"]) if (isObject(value[slot])) reservedKeyProblems(value[slot], `/${slot}`, problems);
304
321
  }
305
- return problems;
322
+ const refs = [];
323
+ if (isObject(value?.capabilities)) for (const [name, choice] of Object.entries(value.capabilities)) {
324
+ if (isObject(choice) && typeof choice.from === "string") refs.push([`/capabilities/${pointerKey(name)}/from`, choice.from]);
325
+ }
326
+ return referenceProblems(problems, refs);
306
327
  }
307
328
 
308
329
  /** `byTeam` was removed in 0.30 (team model v2): a per-team payload no longer exists — a team's
@@ -343,7 +364,7 @@ export function validateLocal(value) {
343
364
  problems.push({ path: `/launch-configs/${pointerKey(name)}/runtime`, reason: "harness-conflict", message: `harness ${show(entry.harness)} and runtime ${show(entry.runtime)} disagree: \`runtime\` is the pre-0.27 name of \`harness\` — keep one` });
344
365
  }
345
366
  }
346
- return problems;
367
+ return referenceProblems(problems, [["/workspace", value?.workspace], ["/standalone", value?.standalone]]);
347
368
  }
348
369
 
349
370
  /* ───────────────────────────── file decoding ──────────────────────────── */
@@ -488,11 +509,14 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
488
509
  let key;
489
510
  try { key = refKey(remote, memberRef); }
490
511
  catch (e) {
491
- if (e?.code === "E_REPO_REF") return unconfirmed(typeof memberRef === "string" ? memberRef : String(memberRef), "not-listed", `${show(memberRef)} is not a repo ref: ${e.message}`);
512
+ if (e?.code === "E_REPO_REF") return unconfirmed(defaultRemote.redactUrl(typeof memberRef === "string" ? memberRef : String(memberRef), null, { reference: true }), "not-listed", `${show(defaultRemote.redactUrl(memberRef, null, { reference: true }))} is not a repo ref: ${e.message}`);
492
513
  throw e;
493
514
  }
494
515
  if (!checked.keys.has(key)) return unconfirmed(key, "not-listed", `${key} is not in members of workspace ${workspaceObs.key}`);
495
- const cannotRead = (e) => unconfirmed(key, "cannot-read", `cannot read ${e.details?.url ?? e.provenance?.url ?? memberRef}${e.details?.reason ? ` (${e.details.reason})` : ""}`, { url: e.details?.url ?? e.provenance?.url ?? null });
516
+ const cannotRead = (e) => {
517
+ const url = defaultRemote.redactUrl(e.details?.url ?? e.provenance?.url ?? null, null, { reference: true });
518
+ return unconfirmed(key, "cannot-read", `cannot read ${url ?? defaultRemote.redactUrl(memberRef, null, { reference: true })}${e.details?.reason ? ` (${e.details.reason})` : ""}`, { url });
519
+ };
496
520
  let obs;
497
521
  try { obs = await remote.observeRemote(memberRef); }
498
522
  catch (e) {
@@ -514,7 +538,7 @@ export async function confirmMembership(workspaceObs, memberRef, { remote: injec
514
538
  let backlinkKey;
515
539
  try { backlinkKey = refKey(remote, read.value.workspace); }
516
540
  catch (e) {
517
- if (e?.code === "E_REPO_REF") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml names an unparseable workspace ${show(read.value.workspace)}`, { commit: obs.commit });
541
+ if (e?.code === "E_REPO_REF") return unconfirmed(key, "no-backlink", `${key}@${obs.commit.slice(0, 12)} oats-membership.yaml names an unparseable workspace ${show(defaultRemote.redactUrl(read.value.workspace, null, { reference: true }))}`, { commit: obs.commit });
518
542
  throw e;
519
543
  }
520
544
  if (backlinkKey !== workspaceObs.key) {
@@ -532,18 +556,21 @@ const CAP_FILE = /^([^/]+)\/oats\.json$/;
532
556
  /**
533
557
  * Enumerate souls/*\/soul.yaml and capabilities/*\/oats.json of one repo at one commit.
534
558
  * Validates each item; collects problems instead of aborting.
535
- * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }] }
559
+ * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }],
560
+ * soulsSkipped: [path] }: where a soul may exist and is not in `souls` (the souls/ listing failed, or
561
+ * a soul.yaml could not be read or is invalid). `problems` says why; this says that a soul is missing.
536
562
  */
537
563
  async function enumerateRepo(remote, ref, key, commit) {
538
564
  const souls = [];
539
565
  const capabilities = [];
540
566
  const problems = [];
567
+ const soulsSkipped = [];
541
568
  const problem = (code, path, message) => problems.push({ code, repoKey: key, path, message });
542
569
  // A listing failure on one directory is a problem of THIS repo, never an abort of the whole picture.
543
570
  const list = async (dir) => {
544
571
  try { return await remote.listRemoteTree(ref, commit, dir, { depth: 2 }); }
545
572
  catch (e) {
546
- if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); return []; }
573
+ if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); if (dir === "souls") soulsSkipped.push(dir); return []; }
547
574
  throw e;
548
575
  }
549
576
  };
@@ -555,11 +582,12 @@ async function enumerateRepo(remote, ref, key, commit) {
555
582
  const file = `${path}/soul.yaml`;
556
583
  let bytes;
557
584
  try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
558
- catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); continue; }
585
+ catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); soulsSkipped.push(file); continue; }
559
586
  const read = readDeclaration("soul", bytes, { kind: "soul", repoKey: key, commit, path: file });
560
- if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
587
+ if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); soulsSkipped.push(file); continue; }
561
588
  const definition = read.value;
562
589
  if (definition.name !== m[1]) problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(m[1])}`);
590
+ // (A second declaration of a name is not a missing soul: the first one is listed under that name.)
563
591
  if (soulNames.has(definition.name)) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} is already declared by ${soulNames.get(definition.name)}; the second declaration is not listed`); continue; }
564
592
  soulNames.set(definition.name, file);
565
593
  // Souls have no private mode since 0.26.0: `private` is accepted, warned (soul-private-ignored) and never hides a soul.
@@ -612,7 +640,7 @@ async function enumerateRepo(remote, ref, key, commit) {
612
640
  else throw e;
613
641
  }
614
642
  }
615
- return { souls, capabilities, publishes, problems };
643
+ return { souls, capabilities, publishes, problems, soulsSkipped };
616
644
  }
617
645
 
618
646
  /**
@@ -649,11 +677,12 @@ export function packageSoulAgentName(id, soul) { return `${String(id).replace(/[
649
677
  * (`package`, `version`) and its qualified name `<package>/<soul>`. A package soul.yaml still carrying
650
678
  * `team:` (removed in 0.30: team membership is local) is invalid and not listed.
651
679
  * Nothing here trusts the lock's digests — a spawn verifies the fetched soul against them.
652
- * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems }
680
+ * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems, skipped: [package id] }:
681
+ * `skipped` names each package with a soul the lock records and this read does not list.
653
682
  */
654
683
  export async function discoverPackageSouls(workspace, lock, { remote: injected, remoteOptions } = {}) {
655
- const souls = [], problems = [];
656
- if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems };
684
+ const souls = [], problems = [], skipped = new Set();
685
+ if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems, skipped: [] };
657
686
  const remote = remoteOf({ remote: injected, remoteOptions });
658
687
  const declared = isObject(workspace.packages) ? workspace.packages : {};
659
688
  for (const id of Object.keys(lock.packages).sort()) {
@@ -662,10 +691,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
662
691
  const at = (rel) => `package:${id}:${rel}`;
663
692
  const problem = (code, path, message) => problems.push({ code, repoKey: null, package: id, path: at(path), message });
664
693
  const ref = lockedPackageRef(entry);
665
- if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); continue; }
694
+ if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); skipped.add(id); continue; }
666
695
  let key;
667
696
  try { key = remote.parseRepoRef(ref).key; }
668
- catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); continue; } throw e; }
697
+ catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); skipped.add(id); continue; } throw e; }
669
698
  for (const locked of entry.souls) {
670
699
  const path = `${entry.path}/${locked.path}`;
671
700
  const file = `${path}/soul.yaml`;
@@ -675,10 +704,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
675
704
  try { return readDeclaration("soul", (await remote.readRemoteFile(ref, entry.commit, file)).bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file }); }
676
705
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { remoteError: { code: e.code, message: e.message } }; throw e; }
677
706
  });
678
- if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); continue; }
679
- if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); continue; }
707
+ if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); skipped.add(id); continue; }
708
+ if (read.problems) { for (const p of read.problems) problem("E_WORKSPACE_SCHEMA", `${file}#${p.path}`, `${p.message}${schemaHint("soul", read.value)}`); skipped.add(id); continue; }
680
709
  const definition = read.value;
681
- if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); continue; }
710
+ if (definition.name !== locked.name) { problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(locked.name)}`); skipped.add(id); continue; }
682
711
  souls.push({
683
712
  name: locked.name, path, repoKey: key, ref, commit: entry.commit, private: false, definition,
684
713
  package: id, version: entry.version, qualifiedName: `${id}/${locked.name}`, agentName: packageSoulAgentName(id, locked.name), digest: locked.digest,
@@ -697,7 +726,13 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
697
726
  problems.push({ code: "E_SOUL_AMBIGUOUS", repoKey: null, package: s.package, path: `package:${s.package}:${s.path}/soul.yaml`, message: `package souls ${qualified.join(" and ")} would share the agent directory agents/${dir}/ — keep one of the packages in packages:` });
698
727
  }
699
728
  }
700
- return { souls, problems };
729
+ return { souls, problems, skipped: [...skipped] };
730
+ }
731
+
732
+ /** The packages the workspace declares and `lock` does not hold (declared, and `oats sync` not run since), by id. */
733
+ export function unlockedPackages(workspace, lock) {
734
+ const locked = isObject(lock?.packages) ? lock.packages : {};
735
+ return Object.keys(isObject(workspace?.packages) ? workspace.packages : {}).filter((id) => !Object.hasOwn(locked, id)).sort();
701
736
  }
702
737
 
703
738
  /** Members discovered at once (a fixed bound: the laptop's git and network, not the workspace's size). */
@@ -724,7 +759,13 @@ async function boundedMap(items, limit, task) {
724
759
  /**
725
760
  * The whole picture in one access context.
726
761
  * → { workspace, members: [{ key, commit, confirmed, reason?, souls, capabilities, publishes }], external: [...],
727
- * problems: [{ code, path, message, repoKey? }] }
762
+ * problems: [{ code, path, message, repoKey? }], soulsUnread }
763
+ * `soulsUnread` is where this read may be missing a soul, for the readers of oats-local.yaml souls.launch
764
+ * (lib/instance-resolution.mjs soulsOffered): { members: [repo key] (a confirmed member with a soul skipped,
765
+ * or whose enumeration carries no record of what it skipped: skippedSome),
766
+ * external: [source] (an external soul skipped), packages: [id] (a locked package with a soul skipped),
767
+ * unlocked: [id] (a package the workspace declares and `lock` does not hold) }. It is no part of any
768
+ * JSON answer: `problems` rows keep their fields.
728
769
  * `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
729
770
  * the package's capabilities are NOT member capabilities — non-collapse rule), else null.
730
771
  * Members are read DISCOVERY_CONCURRENCY at a time; rows and problems are assembled in declaration order.
@@ -754,21 +795,23 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
754
795
  row.souls = items.souls;
755
796
  row.capabilities = items.capabilities;
756
797
  row.publishes = items.publishes;
757
- return { row, problems: items.problems };
798
+ return { row, problems: items.problems, skipped: skippedSome(items.soulsSkipped) };
758
799
  });
759
800
  } finally {
760
801
  // Every member listed now has adopted its prefetch (or the discovery failed): the rest, members dropped
761
802
  // since the host's last observed commit, are given up.
762
803
  remote.abandonPrefetches?.();
763
804
  }
764
- for (const d of discovered) { members.push(d.row); problems.push(...d.problems); }
805
+ const soulsUnread = { members: [], external: [], packages: [], unlocked: [] };
806
+ // An unconfirmed member carries no enumeration at all: its row says so, and it is not "skipped" here.
807
+ for (const d of discovered) { members.push(d.row); problems.push(...d.problems); if (d.skipped) soulsUnread.members.push(d.row.key); }
765
808
  const externalRows = [];
766
809
  for (const [index, entry] of (workspace.external || []).entries()) {
767
810
  const pin = entry.source.lastIndexOf("@");
768
811
  const sourceRef = entry.source.slice(0, pin);
769
812
  const commit = entry.source.slice(pin + 1);
770
813
  const file = `${entry.soul.replace(/\/+$/, "")}/soul.yaml`;
771
- const pushProblem = (code, path, message) => problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source });
814
+ const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: defaultRemote.redactUrl(entry.source, null, { pinned: { ref: sourceRef, commit } }) }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
772
815
  let key;
773
816
  try { key = refKey(remote, sourceRef); }
774
817
  catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
@@ -784,7 +827,9 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
784
827
  }
785
828
  const pkg = await discoverPackageSouls(workspace, lock, { remote });
786
829
  problems.push(...pkg.problems);
787
- return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
830
+ soulsUnread.packages = pkg.skipped;
831
+ soulsUnread.unlocked = unlockedPackages(workspace, lock);
832
+ return { workspace, key: wsObs.key, url: wsObs.url, commit: wsObs.commit, observedAt: wsObs.observedAt, local: local ?? null, members, external: externalRows, packageSouls: pkg.souls, problems, soulsUnread, warnings: workspaceWarnings(workspace, members, externalRows, pkg.souls) };
788
833
  }
789
834
 
790
835
  /**
@@ -905,5 +950,8 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
905
950
  standalone: true, key, commit: source.commit ?? commit ?? null, workspace: null,
906
951
  members: [{ key, commit: source.commit ?? commit ?? null, confirmed: false, reason: "cannot-read", detail: `workspace of ${key} cannot be read; standalone view`, souls, capabilities, publishes: source.publishes ?? null }],
907
952
  external: [], problems, warnings: [...privateSoulWarnings(souls), ...capabilityContractWarnings(capabilities)],
953
+ // As discoverWorkspace's: the repo's own souls are all this view offers, so only they can be missing.
954
+ // A discovery or an enumeration with no record of it counts as one with a soul skipped (skippedSome).
955
+ soulsUnread: { members: (Array.isArray(discovery.members) ? (!Array.isArray(discovery.soulsUnread?.members) || discovery.soulsUnread.members.includes(key)) : skippedSome(source.soulsSkipped)) ? [key] : [], external: [], packages: [], unlocked: [] },
908
956
  };
909
957
  }
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v5.0.2",
6
+ "ref": "v5.0.3",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.27.0",
11
+ "ref": "v1.27.1",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -28,7 +28,7 @@
28
28
  },
29
29
  "oats.engineering": {
30
30
  "url": "https://github.com/awebai/oats-engineering.git",
31
- "ref": "v1.9.0",
31
+ "ref": "v1.9.1",
32
32
  "path": "oats-package"
33
33
  },
34
34
  "oats.cloning": {
@@ -43,7 +43,7 @@
43
43
  },
44
44
  "oats.framework": {
45
45
  "url": "https://github.com/awebai/oats.git",
46
- "ref": "oats-framework/v1.9.3",
46
+ "ref": "oats-framework/v1.10.0",
47
47
  "path": "oats-package"
48
48
  }
49
49
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.52.0",
3
+ "version": "0.54.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -15,6 +15,7 @@
15
15
  "type": "module",
16
16
  "scripts": {
17
17
  "test": "node scripts/run-tests.mjs",
18
+ "test:session": "node scripts/test-session-inheritance.mjs",
18
19
  "check": "node scripts/check-package-dry-runs.mjs --syntax-only",
19
20
  "check:pi": "node --experimental-strip-types --check packages/pi/extension/index.ts",
20
21
  "validate": "node scripts/validate-project.mjs",
@@ -0,0 +1,25 @@
1
+ /** What an attach's exit status says, as a word. A client compares no number: the kernel's table is
2
+ * read here and nowhere else (docs/execution-targets.md, "Exit status"; docs/servers.md, "Run there",
3
+ * for the routed form).
4
+ *
5
+ * attachExit(status, { keyed, routed }) -> "left" | "ended" | "failed" | "link" | "unknown"
6
+ *
7
+ * left 20, for an attach given a detach key: left by the key. The agent keeps running.
8
+ * ended 0: the viewer ended without the key. It says nothing of the agent.
9
+ * failed 1: a refusal, or tmux failing under the viewer. Routed: also a refusal on this side,
10
+ * and an ssh that could not be run here.
11
+ * link 255, for a routed attach: ssh's own failure, before the viewer or under it.
12
+ * unknown anything else: 20 without a key, 255 on this machine, any other number, null (the
13
+ * child was ended by a signal), any value that is not a number.
14
+ *
15
+ * `status` is the child's exit status as Node reports it. `keyed`: the attach was started with
16
+ * `--detach-key`. `routed`: it was started with `--server`. Each counts only when it is `true`.
17
+ * No sentence is here: the words a person reads are each client's. This module imports nothing, so
18
+ * a page can load it. */
19
+ export function attachExit(status, options) {
20
+ if (status === 20 && options?.keyed === true) return "left";
21
+ if (status === 0) return "ended";
22
+ if (status === 1) return "failed";
23
+ if (status === 255 && options?.routed === true) return "link";
24
+ return "unknown";
25
+ }
@@ -30,16 +30,20 @@ import { isAbsolute, join } from "node:path";
30
30
  import { gitFileId, gitRevision, gitIndexRevision, gitObservation } from './instance-git-contract.mjs';
31
31
  import { validMaxAge, maxAgeArgv } from './deployment-contract.mjs';
32
32
  import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
33
+ import { kernelMade } from './kernel-made.mjs';
33
34
 
34
35
  const ENVELOPE_TIMEOUT_MS = 60_000;
35
36
 
36
- /** Parse the single-JSON-object stdout contract; null when contaminated. */
37
+ /** Parse the single-JSON-object stdout contract; null when contaminated.
38
+ * The error of an `ok: false` envelope is marked the kernel's here (kernel-made.mjs), where the CLI's
39
+ * answer is parsed and nowhere else: an envelope a reader writes itself (a timeout, a protocol failure,
40
+ * `parseRetireEnvelope`'s incomplete cleanup) is never parsed, so its error carries no mark. */
37
41
  export function parseEnvelope(stdout) {
38
42
  try {
39
43
  const doc = JSON.parse(String(stdout));
40
44
  if (!doc || typeof doc !== "object" || doc.schemaVersion !== 1) return null;
41
45
  if (doc.ok === true && doc.result && typeof doc.result === "object") return doc;
42
- if (doc.ok === false && doc.error && typeof doc.error === "object") return doc;
46
+ if (doc.ok === false && doc.error && typeof doc.error === "object") { kernelMade(doc.error); return doc; }
43
47
  return null;
44
48
  } catch { return null; }
45
49
  }
@@ -404,9 +408,18 @@ export function cliSoulTeams(bin, { soul, add, remove, defaultLabel, clearDefaul
404
408
  return runJson(bin, argv, { cwd: workspaceDir, exec: io.exec, timeout: io.timeout || 15_000 });
405
409
  }
406
410
 
411
+ /** The roster's envelope as the CLI printed it. A group the kernel could not reach carries the kernel's
412
+ * own error in `probe.error`: each is marked the kernel's here (kernel-made.mjs), as `parseEnvelope` marks
413
+ * the envelope's own. remote-roster.mjs `remotePanel` reads the mark to say who made a row's text. */
414
+ function parseRosterEnvelope(stdout) {
415
+ const doc = parseEnvelope(stdout);
416
+ if (doc?.ok === true && Array.isArray(doc.result.groups)) for (const group of doc.result.groups) kernelMade(group?.probe?.error);
417
+ return doc;
418
+ }
419
+
407
420
  /** One bounded aggregate read; the CLI owns registry and saved-route resolution. */
408
421
  export function cliRemoteRoster(bin, io = {}) {
409
- return runJson(bin, ["server", "roster", "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000 });
422
+ return runJson(bin, ["server", "roster", "--json"], { cwd: io.cwd || process.cwd(), exec: io.exec, timeout: io.timeout || 60_000, parse: parseRosterEnvelope });
410
423
  }
411
424
 
412
425
  /** Local retire predates the envelope; preserve its incomplete-cleanup result. */
@@ -13,7 +13,7 @@
13
13
  // Every candidate is canonicalized to an absolute executable and accepted
14
14
  // ONLY if executable and `<bin> version --json` returns the v1 probe:
15
15
  // {"schemaVersion":1,"name":"@awebai/oats","version":"0.24.x","desktopApi":1}
16
- // Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.53.0 (the band is
16
+ // Desktop accepts desktopApi === 1 and semver >=0.25.8 <0.55.0 (the band is
17
17
  // spelled ONCE, in ACCEPT_RANGE below — this line only paraphrases it).
18
18
  // API version — not source adjacency — is authoritative.
19
19
  //
@@ -54,7 +54,7 @@ export const DESKTOP_API = 1;
54
54
  // carry a `description` for every kind and `<kind> update <id> --description`
55
55
  // sets one (feature `automation-descriptions`, which gates the Desktop's
56
56
  // summary writes). The Desktop v1 surface is otherwise unchanged.
57
- export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 53, 0] };
57
+ export const ACCEPT_RANGE = { min: [0, 25, 8], maxExclusive: [0, 55, 0] };
58
58
  /** The band as humans read it — derived, never hand-spelled, so the probe
59
59
  * rejection reason, the backend's /api status and the degradation card can
60
60
  * never disagree with the numbers actually enforced above. */
@@ -1,6 +1,10 @@
1
1
  /** Native workspace-v2 read contract. No filesystem discovery or generation adapters. */
2
2
  export const DEPLOYMENT_FEATURES = Object.freeze(['workspace-v2', 'instance-modules', 'served-identity', 'packages-no-approval']);
3
3
  export const deploymentRecord = value => value !== null && typeof value === 'object' && !Array.isArray(value);
4
+ /** The code of a kernel error envelope, as the deployment reader admits one (deployment-read-cli.mjs): the one
5
+ * test of its shape. A reason the reader marks `origin: 'kernel'` always carries such a code, and the sentence
6
+ * that attributes a reason to the kernel (deployment-facts.mjs) asks for both. */
7
+ export const deploymentErrorCode = value => typeof value === 'string' && /^[A-Z][A-Z0-9_]{0,63}$/.test(value);
4
8
 
5
9
  /* Spec D: why a remote read failed (kernel E_REMOTE_UNREADABLE `details.reason`, e.g. "cache", "network",
6
10
  * "timeout"), bounded. Only the reason and the host of `details.url` cross; never paths, pids, locks or the
@@ -5,6 +5,8 @@
5
5
  * A page loads this module: it imports no Node builtin, and must not (the
6
6
  * panel's own functions, which do, are in deployment-panel.mjs). */
7
7
  import { requireTerms } from './client-terms.mjs';
8
+ import { displayLine, DETAIL_WITHHELD } from './display-text.mjs';
9
+ import { deploymentErrorCode } from './deployment-contract.mjs';
8
10
 
9
11
  const text = value => typeof value === 'string' && value ? value : null;
10
12
  /** A member's display label from its repo key (the kernel's `memberLabel`). */
@@ -19,16 +21,75 @@ export function servedIdentityText(identity) {
19
21
  return `alias ${text(identity.alias) || '?'} on ${text(identity.team) || '?'}`;
20
22
  }
21
23
 
22
- /** The message for a deployment the kernel could not observe (workspace model v2): the sentence a
23
- * client shows in place of its rows. Still reading (no deployment yet, or `pending`) says so; an
24
- * observed deployment has none (''). A missing advertised feature is named, in the client's terms
25
- * (client-terms.mjs: the client that needs it); a kernel refusal keeps its code and message. */
26
- export function deploymentUnavailableText(deployment, terms) {
27
- requireTerms(terms, 'deploymentUnavailableText');
28
- if (!deployment || deployment.status === 'pending') return 'Reading the deployment through the installed OATS CLI…';
29
- if (deployment.status === 'observed') return '';
24
+ /**
25
+ * The parts of what a client shows for a deployment the kernel could not observe (workspace model v2), in the
26
+ * order they are shown: `{ headline, lead, sentence }`, each one line or null. A fresh object at every call.
27
+ *
28
+ * still reading (no deployment yet, or `pending`) headline: that it is being read
29
+ * observed every part null
30
+ * a missing advertised feature (`reason.feature`) headline: the feature, in the client's terms
31
+ * (client-terms.mjs: the client that needs it)
32
+ * the kernel refused (`reason.origin === 'kernel'` headline: "OATS answered with an error (<code>)."
33
+ * and a code the reader admits) lead: "It says:"; sentence: the kernel's message
34
+ * any other reason headline: `<code>: <message>`, or the message, as one
35
+ * display line; or that the deployment could not be observed
36
+ *
37
+ * `sentence` is the only part that can carry words the client did not write: the kernel's message through
38
+ * the display filter (display-text.mjs `displayLine`), one line, whole or DETAIL_WITHHELD, never cut by its
39
+ * words, parsed or matched. A message the filter withholds, or one with nothing to show, is not introduced:
40
+ * no lead (the rule of lifecycle-contract.mjs `busyRefusal`). The reason is attributed to the kernel only by
41
+ * its mark, which the reader gives to the error the installed CLI printed (deployment-read-cli.mjs); any other
42
+ * value of `origin`, or the mark with a code the reader would not have admitted, reads as none. A reason
43
+ * without the mark is one the client made itself (deployment-contract.mjs `deploymentFailure`): its message is
44
+ * the client's own sentence, and each of those reads through the filter byte for byte as it is written. The
45
+ * line goes through the filter all the same, whole: a reason of that shape that holds anything else is one
46
+ * line too, or DETAIL_WITHHELD alone, or (with nothing to show) that the deployment could not be observed.
47
+ *
48
+ * A client that sets the kernel's words apart from its own (a quote, another style) calls this; one that
49
+ * shows one line calls `deploymentUnavailableText`.
50
+ */
51
+ export function deploymentUnavailableParts(deployment, terms) {
52
+ requireTerms(terms, 'deploymentUnavailableParts');
53
+ const own = headline => ({ headline, lead: null, sentence: null });
54
+ if (!deployment || deployment.status === 'pending') return own('Reading the deployment through the installed OATS CLI…');
55
+ if (deployment.status === 'observed') return own(null);
30
56
  const reason = deployment.reason || {};
31
- if (reason.feature) return `The installed OATS CLI does not advertise ${reason.feature}, which the ${terms.name} needs to show this deployment. Update OATS and retry.`;
57
+ if (reason.feature) return own(`The installed OATS CLI does not advertise ${reason.feature}, which the ${terms.name} needs to show this deployment. Update OATS and retry.`);
58
+ if (reason.origin === 'kernel' && deploymentErrorCode(reason.code)) {
59
+ const sentence = displayLine(reason.message);
60
+ return { headline: `OATS answered with an error (${reason.code}).`, lead: sentence !== null && sentence !== DETAIL_WITHHELD ? 'It says:' : null, sentence };
61
+ }
62
+ // The reader's own reason, through the display filter like every other form: the whole line at once, so
63
+ // the guarantee does not rest on where the callers are (a hand-made reason, a code that is not a code).
32
64
  const code = text(reason.code), message = text(reason.message);
33
- return code && message ? `${code}: ${message}` : message || 'The deployment could not be observed.';
65
+ return own(displayLine(code && message ? `${code}: ${message}` : message) ?? 'The deployment could not be observed.');
66
+ }
67
+
68
+ /** Whether what a client holds for a deployment is a kept failure: its last read failed and what was
69
+ * observed before is still shown (deployment-panel.mjs `failedEntry`). `held` is a deployment's entry or
70
+ * a panel made from one (panel-views.mjs `deploymentPanel`, `panelData`); the answer is null, or
71
+ *
72
+ * { message, origin } message: the failure's text, a string, possibly empty
73
+ * origin: "kernel" when the installed CLI printed it, else null
74
+ *
75
+ * **The fact does not depend on the text.** `error` is a string exactly when a failure is kept, and an
76
+ * empty, blank or withheld message is as much a kept failure as any other: a kernel that fails with no
77
+ * words has still failed. This is the one place that decides it. A client asks here whether a deployment
78
+ * is stale and never tests `error` for truth, so the shared reason and each of a client's notices agree.
79
+ *
80
+ * `origin` is `errorOrigin` read strictly: the one value `failedEntry` writes, anything else null. A
81
+ * panel of another machine (remote-roster.mjs `remotePanel`) never carries the key; its `error` is a
82
+ * string while that machine was not reached, and reads here as a failure with no speaker.
83
+ * Not on the stable surface. */
84
+ export function keptFailure(held) {
85
+ if (held === null || typeof held !== 'object' || typeof held.error !== 'string') return null;
86
+ return { message: held.error, origin: held.errorOrigin === 'kernel' ? 'kernel' : null };
87
+ }
88
+
89
+ /** The sentence a client shows in place of a deployment's rows when the kernel could not observe it: the parts
90
+ * that are there (`deploymentUnavailableParts`), joined by one space. '' for an observed deployment. */
91
+ export function deploymentUnavailableText(deployment, terms) {
92
+ requireTerms(terms, 'deploymentUnavailableText');
93
+ const { headline, lead, sentence } = deploymentUnavailableParts(deployment, terms);
94
+ return [headline, lead, sentence].filter(part => part !== null).join(' ');
34
95
  }
@@ -11,6 +11,10 @@
11
11
  * observed is in deployment-facts.mjs (`deploymentUnavailableText`), and the Desktop's
12
12
  * test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
13
13
  import { dirname } from 'node:path';
14
+ import { livenessOrigin } from './liveness.mjs';
15
+ import { knownOrigin, hasRuntimeError } from './instance-presentation.mjs';
16
+
17
+ const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
14
18
 
15
19
  /** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
16
20
  * with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster.
@@ -35,14 +39,27 @@ export function livenessInput(rows) {
35
39
 
36
40
  /** The collector's answers, one per row. `stdout` is what the collector printed, or `null` when it
37
41
  * failed, timed out or could not start. Anything that is not JSON for an array of exactly
38
- * `rows.length` answers gives every row the unknown answer; no rows give `[]`, whatever was printed. */
42
+ * `rows.length` answers gives every row the unknown answer; no rows give `[]`, whatever was printed.
43
+ *
44
+ * An answer with a `runtimeError` says who made it, in `runtimeErrorOrigin` (instance-presentation.mjs
45
+ * names the speakers). The speaker is decided here, in this process, and never read from what the
46
+ * collector printed: a `runtimeErrorOrigin` in its output is dropped, and the key is set from the row
47
+ * that was sent (liveness.mjs `livenessOrigin`: which answer `observeLiveness` gives is a function of
48
+ * the row alone). So `rows` are the rows whose `livenessInput` the collector was given. The unknown
49
+ * answer written here is the terminal check's own. */
39
50
  export function livenessAnswers(rows, stdout) {
40
51
  if (!rows.length) return [];
41
- const unknown = () => rows.map(() => ({ running: null, runtimeState: "unreachable", runtimeError: "Terminal status is unavailable" }));
52
+ const unknown = () => rows.map(() => ({ running: null, runtimeState: "unreachable", runtimeError: "Terminal status is unavailable", runtimeErrorOrigin: "terminal-probe" }));
42
53
  if (typeof stdout !== "string") return unknown();
43
54
  try {
44
55
  const parsed = JSON.parse(stdout);
45
- return Array.isArray(parsed) && parsed.length === rows.length ? parsed : unknown();
56
+ if (!Array.isArray(parsed) || parsed.length !== rows.length) return unknown();
57
+ return parsed.map((printed, index) => {
58
+ if (!record(printed)) return printed;
59
+ const { runtimeErrorOrigin: _printed, ...answer } = printed;
60
+ const origin = hasRuntimeError(answer) ? livenessOrigin(rows[index]) : null;
61
+ return origin ? { ...answer, runtimeErrorOrigin: origin } : answer;
62
+ });
46
63
  } catch { return unknown(); }
47
64
  }
48
65
 
@@ -66,6 +83,8 @@ export function panelInstance(i) {
66
83
  relativeTo: i.relativeTo || null,
67
84
  ...(i.sessionTarget ? { sessionTarget: i.sessionTarget } : {}),
68
85
  runtimeState: i.runtimeState, runtimeError: i.runtimeError,
86
+ // Who made that text: only beside a `runtimeError`, and only one of the three speakers.
87
+ ...(hasRuntimeError(i) && knownOrigin(i.runtimeErrorOrigin) ? { runtimeErrorOrigin: i.runtimeErrorOrigin } : {}),
69
88
  tmux: i.tmux, git: null,
70
89
  // Workspace-model v2 facts exactly as `oats status --json` reported them:
71
90
  // module drift rows (or the recorded map when the workspace is
@@ -90,10 +109,18 @@ export function panelInstance(i) {
90
109
  };
91
110
  }
92
111
 
93
- /** The panel's rows: each row merged with its liveness answer and projected, running first, then by name. */
112
+ /** The panel's rows: each row merged with its liveness answer and projected, running first, then by name.
113
+ * `answers` are `livenessAnswers`'.
114
+ *
115
+ * The merged row's `runtimeErrorOrigin` is set here or removed, whatever the row carried: when the
116
+ * answer holds the `runtimeError`, the answer's speaker; when the answer has none and the kernel's row
117
+ * had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel". */
94
118
  export function panelInstances(rows, answers) {
95
- return rows.map((row, index) => panelInstance({ ...row, ...answers[index] }))
96
- .sort((a, b) => (a.running === b.running ? String(a.instance).localeCompare(b.instance) : a.running ? -1 : 1));
119
+ return rows.map((row, index) => {
120
+ const answer = answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
121
+ const origin = record(answer) && Object.hasOwn(answer, "runtimeError") ? answer.runtimeErrorOrigin : "kernel";
122
+ return panelInstance(hasRuntimeError(merged) ? { ...merged, runtimeErrorOrigin: origin } : merged);
123
+ }).sort((a, b) => (a.running === b.running ? String(a.instance).localeCompare(b.instance) : a.running ? -1 : 1));
97
124
  }
98
125
 
99
126
  /** A deployment's entry before the first CLI probe has settled, when there is no verdict to report:
@@ -105,16 +132,27 @@ export function pendingEntry(previous, at) {
105
132
  /** A deployment's entry after a read that failed with `reason` (deployment-contract.mjs).
106
133
  * A transient busy or stale read keeps the entry held, as it is. A remote the kernel could not read
107
134
  * (a cache problem, the network, a timeout) does not erase what was observed: the last observation
108
- * stays, marked with the failure, the kernel's message and its bounded cause (Spec D); an `error` and
109
- * an `errorCause` it already carried are replaced, the cause removed when this reason has none.
135
+ * stays, marked with the failure, the kernel's message and its bounded cause (Spec D); an `error`, an
136
+ * `errorOrigin` and an `errorCause` it already carried are replaced, the origin and the cause removed
137
+ * when this reason has none.
110
138
  * Every other failure, and each of those without an entry to keep, is shown as unavailable with the
111
- * reason, never as an empty roster. */
139
+ * reason, never as an empty roster.
140
+ *
141
+ * The kept entry's `error` is always a string: the reason's message, or "" when it carries none. That
142
+ * `error` is a string is the fact "a failure is kept" (deployment-facts.mjs `keptFailure`, the one place
143
+ * that reads it); what the string holds decides nothing.
144
+ * `errorOrigin: "kernel"` stands beside it when the reason is one the installed CLI printed (the reader's
145
+ * `origin: 'kernel'`, deployment-read-cli.mjs), and is absent for any other reason: who shows `error`
146
+ * names its speaker from this key (instance-presentation.mjs `originLead`), and shows a message with no
147
+ * origin as its own, never under the kernel's name. The key is written here only, from the reason given:
148
+ * one the entry already carried never survives. */
112
149
  export function failedEntry(previous, reason, at) {
113
150
  if (previous && ["E_DEPLOYMENT_BUSY", "E_DEPLOYMENT_STALE"].includes(reason?.code)) return previous;
114
151
  if (previous?.deployment?.status === "observed" && reason?.code === "E_REMOTE_UNREADABLE") {
115
- const { error: _error, errorCause: _cause, ...kept } = previous;
152
+ const { error: _error, errorCause: _cause, errorOrigin: _origin, ...kept } = previous;
116
153
  const cause = reason.cause;
117
- return { ...kept, error: reason.message, ...(cause ? { errorCause: { code: reason.code, ...cause } } : {}) };
154
+ return { ...kept, error: typeof reason.message === "string" ? reason.message : "", ...(reason.origin === "kernel" ? { errorOrigin: "kernel" } : {}),
155
+ ...(cause ? { errorCause: { code: reason.code, ...cause } } : {}) };
118
156
  }
119
157
  return { deployment: { status: "unavailable", reason }, instances: [], generatedAt: at };
120
158
  }