@awebai/oats 0.52.0 → 0.53.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (98) hide show
  1. package/README.md +2 -1
  2. package/bin/oats.mjs +304 -92
  3. package/docs/capabilities.md +66 -4
  4. package/docs/configuration.md +66 -3
  5. package/docs/desktop-cli-api.md +673 -58
  6. package/docs/desktop-instance-start.md +25 -12
  7. package/docs/execution-targets.md +1 -0
  8. package/docs/implementation.md +175 -11
  9. package/docs/integrations.md +6 -3
  10. package/docs/knowledge.md +2 -2
  11. package/docs/macos-test-runs.md +246 -0
  12. package/docs/official-catalog.md +5 -5
  13. package/docs/packages.md +14 -14
  14. package/docs/release-lane.md +210 -6
  15. package/docs/release-notes/v0.53.0.md +1274 -0
  16. package/docs/schedules.md +7 -1
  17. package/docs/souls-and-instances.md +237 -15
  18. package/docs/tui.md +453 -21
  19. package/docs/upgrading.md +298 -0
  20. package/docs/workspaces.md +3 -3
  21. package/lib/automations.mjs +22 -22
  22. package/lib/claim.mjs +93 -4
  23. package/lib/config-data.mjs +4 -1
  24. package/lib/core.mjs +569 -121
  25. package/lib/instance-events.mjs +19 -1
  26. package/lib/instance-git.mjs +39 -3
  27. package/lib/instance-inspect.mjs +5 -6
  28. package/lib/instance-lifecycle.mjs +145 -18
  29. package/lib/instance-resolution.mjs +59 -6
  30. package/lib/launch-preference.mjs +226 -15
  31. package/lib/local-edit.mjs +118 -0
  32. package/lib/packages.mjs +13 -4
  33. package/lib/pi-bridge.mjs +308 -0
  34. package/lib/refused-text.mjs +11 -0
  35. package/lib/remote.mjs +190 -25
  36. package/lib/resolve.mjs +2 -1
  37. package/lib/retained-after-retire.mjs +2 -2
  38. package/lib/retire-output.mjs +12 -1
  39. package/lib/schedule-host.mjs +6 -35
  40. package/lib/shell-word.mjs +13 -0
  41. package/lib/soul-launch-verbs.mjs +153 -0
  42. package/lib/stable-node.mjs +62 -0
  43. package/lib/teams-verbs.mjs +18 -46
  44. package/lib/workspace.mjs +49 -19
  45. package/package-catalog.json +4 -4
  46. package/package.json +2 -1
  47. package/packages/client/attach-exit.mjs +25 -0
  48. package/packages/client/cli-adapter.mjs +16 -3
  49. package/packages/client/cli-locator.mjs +2 -2
  50. package/packages/client/deployment-contract.mjs +4 -0
  51. package/packages/client/deployment-facts.mjs +71 -10
  52. package/packages/client/deployment-panel.mjs +49 -11
  53. package/packages/client/deployment-read-cli.mjs +7 -3
  54. package/packages/client/display-text.mjs +8 -2
  55. package/packages/client/instance-acts.mjs +46 -10
  56. package/packages/client/instance-events-contract.mjs +4 -2
  57. package/packages/client/instance-presentation.mjs +66 -2
  58. package/packages/client/instance-tree.mjs +23 -14
  59. package/packages/client/kernel-lines.mjs +31 -0
  60. package/packages/client/kernel-made.mjs +23 -0
  61. package/packages/client/launch-prompt-outcome.mjs +51 -16
  62. package/packages/client/lifecycle-contract.mjs +45 -4
  63. package/packages/client/liveness.mjs +14 -1
  64. package/packages/client/own-codes.mjs +31 -0
  65. package/packages/client/panel-views.mjs +18 -11
  66. package/packages/client/readiness-contract.mjs +3 -1
  67. package/packages/client/remote-address.mjs +34 -9
  68. package/packages/client/remote-identity-memory.mjs +94 -0
  69. package/packages/client/remote-roster.mjs +92 -6
  70. package/packages/client/session-attach.mjs +175 -0
  71. package/packages/client/spawn-apply-contract.mjs +16 -4
  72. package/packages/client/spawn-messages.mjs +26 -3
  73. package/packages/client/spawn-preview-cli.mjs +8 -2
  74. package/packages/client/spawn-preview-contract.mjs +5 -1
  75. package/packages/client/terminal-exec.mjs +21 -0
  76. package/packages/client/workspace-choices.mjs +95 -0
  77. package/packages/client/workspace-views.mjs +39 -3
  78. package/packages/record/README.md +21 -0
  79. package/packages/record/bin/setup.mjs +108 -15
  80. package/packages/tui/README.md +30 -12
  81. package/packages/tui/lib/actions.mjs +16 -1
  82. package/packages/tui/lib/client.mjs +32 -1
  83. package/packages/tui/lib/config.mjs +151 -0
  84. package/packages/tui/lib/main.mjs +117 -46
  85. package/packages/tui/lib/model.mjs +392 -0
  86. package/packages/tui/lib/read.mjs +473 -0
  87. package/packages/tui/lib/store.mjs +364 -0
  88. package/packages/tui/lib/term/keys.mjs +44 -0
  89. package/packages/tui/lib/term/screen.mjs +16 -4
  90. package/packages/tui/lib/term/text.mjs +60 -0
  91. package/packages/tui/lib/term/tty.mjs +13 -3
  92. package/packages/tui/lib/views/detail.mjs +46 -0
  93. package/packages/tui/lib/views/frame.mjs +230 -36
  94. package/packages/tui/lib/views/help.mjs +125 -13
  95. package/packages/tui/lib/views/instances.mjs +137 -0
  96. package/packages/tui/lib/views/scroll.mjs +19 -0
  97. package/packages/tui/lib/views/switcher.mjs +97 -0
  98. package/skills/oats-getting-started/SKILL.md +2 -2
@@ -0,0 +1,62 @@
1
+ /** The one rule for a node path that is written into something that outlives
2
+ * the process (a unit, a harness's settings): a path that survives an upgrade
3
+ * of Node. The host timer's unit (lib/schedule-host.mjs) and OATS_NODE_BIN,
4
+ * which every hook, provider check and dispatched command receives, are both
5
+ * this rule's answer. It imports nothing of the kernel, so any module can. */
6
+ import { realpathSync } from "node:fs";
7
+ import { isAbsolute, join, resolve, sep } from "node:path";
8
+
9
+ /** A versioned Homebrew keg: <prefix>/Cellar/<formula>/<version>/…, gone at the next upgrade. */
10
+ const KEG = /^(.*)\/Cellar\/([^/]+)\/([^/]+)\//;
11
+
12
+ /** The installer's PATH entries a unit may carry. Dropped: entries inside an
13
+ * OATS instance home (an instance's `.oats/bin`, anything under
14
+ * `instanceHome`), entries inside a versioned Homebrew keg, and relative or
15
+ * empty entries. An entry missing today is kept: it may exist when the tick
16
+ * runs, and status reports it while it does not. */
17
+ export function unitPathEntries(envPath, { instanceHome = process.env.OATS_INSTANCE_HOME } = {}) {
18
+ const home = instanceHome && isAbsolute(instanceHome) ? resolve(instanceHome) : null;
19
+ const hazard = (entry) => {
20
+ if (!entry || !isAbsolute(entry)) return true;
21
+ const segments = entry.split(sep);
22
+ if (segments.some((s, i) => s === ".oats" && segments[i + 1] === "bin")) return true;
23
+ if (home && (resolve(entry) === home || resolve(entry).startsWith(home + sep))) return true;
24
+ return KEG.test(entry.endsWith("/") ? entry : `${entry}/`);
25
+ };
26
+ return String(envPath || "").split(":").filter((entry) => !hazard(entry));
27
+ }
28
+
29
+ function realpathOrNull(p) { try { return realpathSync(p); } catch { return null; } }
30
+ /** A node path that survives a Homebrew upgrade. A keg's
31
+ * `<prefix>/opt/<formula>/bin/node` when it is this node, else the first
32
+ * `node` on the filtered PATH that is this node, else `execPath` with a
33
+ * warning that the path is not stable. The warning states the fact; the
34
+ * caller words what it loses (`consequence`) and what to do after installing
35
+ * a stable node (`remedy`). */
36
+ export function stableNode({ execPath = process.execPath, envPath = process.env.PATH || "", instanceHome = process.env.OATS_INSTANCE_HOME, consequence, remedy } = {}) {
37
+ const real = realpathOrNull(execPath);
38
+ const keg = real && KEG.exec(real);
39
+ if (keg) {
40
+ const opt = join(keg[1], "opt", keg[2], "bin", "node");
41
+ if (realpathOrNull(opt) === real) return { node: opt };
42
+ }
43
+ for (const entry of unitPathEntries(envPath, { instanceHome })) {
44
+ const candidate = join(entry, "node");
45
+ if (real && realpathOrNull(candidate) === real) return { node: candidate };
46
+ }
47
+ return { node: execPath, warning: `the node path ${execPath} is not stable (no Homebrew opt link and no node on PATH resolves to it)${consequence ? `: ${consequence}` : ""}${remedy ? `; install a node with a stable path and ${remedy}` : ""}` };
48
+ }
49
+
50
+ let kernel = null;
51
+ /** The rule's answer for the node running this kernel, on the kernel's own
52
+ * PATH: `node` is OATS_NODE_BIN, and `warning` (the third case only) is what a
53
+ * spawn and a start say, worded for a home's hooks. The rule reads the file
54
+ * system, so it is computed once for the node, PATH and instance home this
55
+ * process runs with, not once per hook. */
56
+ export function kernelNode() {
57
+ const key = [process.execPath, process.env.PATH || "", process.env.OATS_INSTANCE_HOME || ""].join("\0");
58
+ if (kernel?.key !== key) {
59
+ kernel = { key, answer: stableNode({ consequence: "what this home's hooks record with it stops working when it goes away", remedy: "restart the instance" }) };
60
+ }
61
+ return kernel.answer;
62
+ }
@@ -7,15 +7,11 @@
7
7
  * schema, and no label reference the write would leave unknown. A soul's teams are the workspace's
8
8
  * `souls:`, edited by a PR to that file: `oats soul teams` only reads them.
9
9
  */
10
- import { readFileSync } from "node:fs";
11
- import { join } from "node:path";
12
10
  import YAML from "yaml";
13
- import { parseConfigData } from "./config-data.mjs";
14
11
  import { oatsError } from "./errors.mjs";
15
- import { teamLabelProblem, validateLocal } from "./workspace.mjs";
12
+ import { teamLabelProblem } from "./workspace.mjs";
16
13
  import { TEAM_ID_RE, localTeamsClosed, soulTeams, teamModel, teamProblems, teamReferences } from "./teams.mjs";
17
- import { writeFileAtomic } from "./packages.mjs";
18
- import { withDirLock } from "./dir-lock.mjs";
14
+ import { editLocal } from "./local-edit.mjs";
19
15
 
20
16
  export const TEAMS_API = 2, SOUL_TEAMS_API = 2;
21
17
  const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
@@ -66,13 +62,6 @@ const modelOf = (ctx, local) => teamModel(ctx.workspace, local, { workspaceKey:
66
62
  const refusals = (ctx, local) => new Map(teamProblems(modelOf(ctx, local))
67
63
  .filter((p) => p.code === "E_TEAM_UNKNOWN").map((p) => [`${p.code} ${p.at}`, p]));
68
64
  const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
69
- const readLocal = (ctx) => {
70
- const text = readFileSync(ctx.localPath, "utf8");
71
- const doc = YAML.parseDocument(text, { keepSourceTokens: true });
72
- if (doc.errors?.length) throw fail("E_WORKSPACE_SCHEMA", `${ctx.localPath}: ${doc.errors[0].message}`, { path: ctx.localPath });
73
- return { text, doc, local: parseConfigData(text, { origin: { kind: "local", path: ctx.localPath } }).value };
74
- };
75
-
76
65
  /**
77
66
  * Edit `doc` from `before` to `next` SURGICALLY: only the entries that change are touched, so comments and
78
67
  * styles on everything else (inline comments on sibling entries) are kept. A map left empty is removed.
@@ -94,46 +83,29 @@ function applyState(doc, before, next) {
94
83
  }
95
84
 
96
85
  /**
97
- * Rewrite oats-local.yaml. `mutate(state, model)` edits the plain `state` (teamState) and may throw a
98
- * refusal; both come from the file AS IT IS NOW (re-read here, never the command's startup snapshot), so
99
- * two verbs running together cannot drop each other's change: the write is compare-and-swap — when the
100
- * file changed after this read, the edit is redone on the new content (a few times, then E_LOCAL_CHANGED).
86
+ * Rewrite oats-local.yaml through the shared edit path (lib/local-edit.mjs editLocal: the file as it is
87
+ * NOW, the deployment's local lock, compare-and-swap, the local schema). `mutate(state, model)` edits the
88
+ * plain `state` (teamState) and may throw a refusal; both come from the file as that path read it, so two
89
+ * verbs running together cannot drop each other's change, and a conditional write sees every earlier one.
101
90
  * `verb` names the command and `writes` the keys it adds, for the refusal where the workspace does not
102
91
  * allow local teams (local-teams-closed); a verb that only takes local teams away (`writes: null`) runs
103
92
  * there too, since it moves the file toward what the workspace allows. → { changed, local } (the value now).
104
- * The whole read-compare-write runs under the deployment's local lock (localLock), so among `oats teams`
105
- * writers the compare and the rename are one step: a conditional write sees every earlier one.
93
+ * A write is also refused when it would leave a label reference unknown that the file did not have.
106
94
  */
107
- function editLocal(ctx, { verb, writes }, mutate) {
108
- const lock = localLock(ctx);
109
- return withDirLock(lock, `${verb} on ${ctx.localPath}`, () => editLocalLocked(ctx, { verb, writes }, mutate), {
110
- retryMs: 5000,
111
- busy: (why) => fail("E_LOCAL_BUSY", `${ctx.localPath} is being edited by another oats process (the lock ${lock}: ${why}); if no oats teams command is running, remove ${lock} and retry; nothing was written`, { path: ctx.localPath, lock }),
112
- });
113
- }
114
- /** The lock every `oats teams` mutation holds: in the deployment's kernel state tree, never beside the files. */
115
- const localLock = (ctx) => join(ctx.deployment, ".agents", "locks", "local.lock");
116
- function editLocalLocked(ctx, { verb, writes }, mutate) {
117
- for (let attempt = 0; attempt < 5; attempt++) {
118
- const { text, doc, local: current } = readLocal(ctx);
95
+ function editTeams(ctx, { verb, writes }, mutate) {
96
+ return editLocal(ctx, { verb }, ({ doc, local: current }) => {
119
97
  const model = modelOf(ctx, current);
120
98
  if (model.localTeams === false && writes !== null) throw localTeamsClosed(writes, { verb });
121
99
  const before = teamState(current);
122
100
  const next = teamState(current);
123
101
  mutate(next, model);
124
- if (same(next, before)) return { changed: false, local: current };
102
+ if (same(next, before)) return null;
125
103
  applyState(doc, before, next);
126
- const out = doc.toString();
127
- const local = parseConfigData(out, { origin: { kind: "local", path: ctx.localPath } }).value;
128
- const problems = validateLocal(local);
129
- if (problems.length) throw fail("E_WORKSPACE_SCHEMA", `the rewritten oats-local.yaml would be invalid (${problems.map((p) => `${p.path || "/"}: ${p.message}`).join("; ")}); nothing was written`, { problems });
130
- const had = refusals(ctx, current);
131
- for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
132
- if (readFileSync(ctx.localPath, "utf8") !== text) continue; // changed under us: redo on the new content
133
- writeFileAtomic(ctx.localPath, out);
134
- return { changed: true, local };
135
- }
136
- throw fail("E_LOCAL_CHANGED", `${ctx.localPath} kept changing while this edit ran; nothing was written — run it again`, { path: ctx.localPath });
104
+ return { check: (local) => {
105
+ const had = refusals(ctx, current);
106
+ for (const [k, p] of refusals(ctx, local)) if (!had.has(k)) throw fail(p.code, `${p.message}; nothing was written`, Object.fromEntries(Object.entries(p).filter(([key]) => !["code", "severity", "message", "fix"].includes(key))));
107
+ } };
108
+ });
137
109
  }
138
110
 
139
111
  const assertLabel = (label) => {
@@ -149,7 +121,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
149
121
  if (typeof team !== "string" || !team.trim()) throw fail("E_BAD_ARGS", "oats teams add needs --team <provider team id>", { label });
150
122
  if (!TEAM_ID_RE.test(team.trim())) throw fail("E_BAD_ARGS", `${JSON.stringify(team)} is not a team id: it must match ${TEAM_ID_RE.source} (a letter or digit first; no whitespace or control characters; at most 256 characters)`, { label, team });
151
123
  let reused = false;
152
- const result = editLocal(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
124
+ const result = editTeams(ctx, { verb: "oats teams add", writes: ["teams"] }, (s, model) => {
153
125
  if (model.labels.has(label)) {
154
126
  const { from, team: existing } = model.labels.get(label);
155
127
  if (noDefault && existing === team.trim()) { reused = true; return; }
@@ -165,7 +137,7 @@ export function teamsAdd(ctx, label, { team, description, noDefault = false } =
165
137
  /** `oats teams remove <label>`: a LOCAL team nothing references (no cascade). Allowed where the workspace
166
138
  * does not allow local teams: removing them is the last step of committing them there. */
167
139
  export function teamsRemove(ctx, label) {
168
- return editLocal(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
140
+ return editTeams(ctx, { verb: "oats teams remove", writes: null }, (s, model) => {
169
141
  if (!model.local.has(label)) {
170
142
  if (model.shared.has(label)) throw fail("E_TEAM_SHARED", `team ${label} is shared (declared in oats-workspace.yaml): it is edited by a PR to that file, never removed here`, { label, at: model.shared.get(label).at });
171
143
  throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared`, { label });
@@ -192,7 +164,7 @@ function assertDefaultPrecondition(model, { ifAbsent, expect }) {
192
164
  * judged inside the edit, on the file as it is now (and again on every retry), after today's refusals. */
193
165
  export function teamsDefault(ctx, label, { ifAbsent = false, expect } = {}) {
194
166
  if (ifAbsent && expect !== undefined) throw fail("E_BAD_ARGS", "oats teams default takes --if-absent or --expect <label>, not both", { label });
195
- return editLocal(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
167
+ return editTeams(ctx, { verb: "oats teams default", writes: ["defaultTeam"] }, (s, model) => {
196
168
  if (!model.labels.has(label)) throw fail("E_TEAM_UNKNOWN", `team ${JSON.stringify(label)} is not declared: \`oats teams add\` it first`, { label });
197
169
  if (ifAbsent || expect !== undefined) assertDefaultPrecondition(model, { ifAbsent, expect });
198
170
  s.defaultTeam = label;
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
  }
@@ -532,18 +538,21 @@ const CAP_FILE = /^([^/]+)\/oats\.json$/;
532
538
  /**
533
539
  * Enumerate souls/*\/soul.yaml and capabilities/*\/oats.json of one repo at one commit.
534
540
  * Validates each item; collects problems instead of aborting.
535
- * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }] }
541
+ * → { souls: [SoulEntry], capabilities: [CapEntry], problems: [{ code, path, message, repoKey }],
542
+ * soulsSkipped: [path] }: where a soul may exist and is not in `souls` (the souls/ listing failed, or
543
+ * a soul.yaml could not be read or is invalid). `problems` says why; this says that a soul is missing.
536
544
  */
537
545
  async function enumerateRepo(remote, ref, key, commit) {
538
546
  const souls = [];
539
547
  const capabilities = [];
540
548
  const problems = [];
549
+ const soulsSkipped = [];
541
550
  const problem = (code, path, message) => problems.push({ code, repoKey: key, path, message });
542
551
  // A listing failure on one directory is a problem of THIS repo, never an abort of the whole picture.
543
552
  const list = async (dir) => {
544
553
  try { return await remote.listRemoteTree(ref, commit, dir, { depth: 2 }); }
545
554
  catch (e) {
546
- if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); return []; }
555
+ if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) { problem(e.code, dir, e.message); if (dir === "souls") soulsSkipped.push(dir); return []; }
547
556
  throw e;
548
557
  }
549
558
  };
@@ -555,11 +564,12 @@ async function enumerateRepo(remote, ref, key, commit) {
555
564
  const file = `${path}/soul.yaml`;
556
565
  let bytes;
557
566
  try { ({ bytes } = await remote.readRemoteFile(ref, commit, file)); }
558
- catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); continue; }
567
+ catch (e) { problem(e?.code || "E_REMOTE_UNREADABLE", file, e.message); soulsSkipped.push(file); continue; }
559
568
  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; }
569
+ 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
570
  const definition = read.value;
562
571
  if (definition.name !== m[1]) problem("E_WORKSPACE_SCHEMA", `${file}#/name`, `soul name ${show(definition.name)} does not match its directory ${show(m[1])}`);
572
+ // (A second declaration of a name is not a missing soul: the first one is listed under that name.)
563
573
  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
574
  soulNames.set(definition.name, file);
565
575
  // Souls have no private mode since 0.26.0: `private` is accepted, warned (soul-private-ignored) and never hides a soul.
@@ -612,7 +622,7 @@ async function enumerateRepo(remote, ref, key, commit) {
612
622
  else throw e;
613
623
  }
614
624
  }
615
- return { souls, capabilities, publishes, problems };
625
+ return { souls, capabilities, publishes, problems, soulsSkipped };
616
626
  }
617
627
 
618
628
  /**
@@ -649,11 +659,12 @@ export function packageSoulAgentName(id, soul) { return `${String(id).replace(/[
649
659
  * (`package`, `version`) and its qualified name `<package>/<soul>`. A package soul.yaml still carrying
650
660
  * `team:` (removed in 0.30: team membership is local) is invalid and not listed.
651
661
  * 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 }
662
+ * `lock` null (or no workspace) → nothing. → { souls: [SoulEntry], problems, skipped: [package id] }:
663
+ * `skipped` names each package with a soul the lock records and this read does not list.
653
664
  */
654
665
  export async function discoverPackageSouls(workspace, lock, { remote: injected, remoteOptions } = {}) {
655
- const souls = [], problems = [];
656
- if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems };
666
+ const souls = [], problems = [], skipped = new Set();
667
+ if (!isObject(lock?.packages) || !isObject(workspace)) return { souls, problems, skipped: [] };
657
668
  const remote = remoteOf({ remote: injected, remoteOptions });
658
669
  const declared = isObject(workspace.packages) ? workspace.packages : {};
659
670
  for (const id of Object.keys(lock.packages).sort()) {
@@ -662,10 +673,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
662
673
  const at = (rel) => `package:${id}:${rel}`;
663
674
  const problem = (code, path, message) => problems.push({ code, repoKey: null, package: id, path: at(path), message });
664
675
  const ref = lockedPackageRef(entry);
665
- if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); continue; }
676
+ if (!ref) { problem("E_PACKAGE_MISSING", entry.path, `the lock records no url for ${id} — run \`oats sync\``); skipped.add(id); continue; }
666
677
  let key;
667
678
  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; }
679
+ catch (e) { if (e?.code === "E_REPO_REF") { problem("E_REPO_REF", entry.path, e.message); skipped.add(id); continue; } throw e; }
669
680
  for (const locked of entry.souls) {
670
681
  const path = `${entry.path}/${locked.path}`;
671
682
  const file = `${path}/soul.yaml`;
@@ -675,10 +686,10 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
675
686
  try { return readDeclaration("soul", (await remote.readRemoteFile(ref, entry.commit, file)).bytes, { kind: "soul", repoKey: key, commit: entry.commit, path: file }); }
676
687
  catch (e) { if (typeof e?.code === "string" && e.code.startsWith("E_REMOTE_")) return { remoteError: { code: e.code, message: e.message } }; throw e; }
677
688
  });
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; }
689
+ if (read.remoteError) { problem(read.remoteError.code, file, read.remoteError.message); skipped.add(id); continue; }
690
+ 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
691
  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; }
692
+ 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
693
  souls.push({
683
694
  name: locked.name, path, repoKey: key, ref, commit: entry.commit, private: false, definition,
684
695
  package: id, version: entry.version, qualifiedName: `${id}/${locked.name}`, agentName: packageSoulAgentName(id, locked.name), digest: locked.digest,
@@ -697,7 +708,13 @@ export async function discoverPackageSouls(workspace, lock, { remote: injected,
697
708
  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
709
  }
699
710
  }
700
- return { souls, problems };
711
+ return { souls, problems, skipped: [...skipped] };
712
+ }
713
+
714
+ /** The packages the workspace declares and `lock` does not hold (declared, and `oats sync` not run since), by id. */
715
+ export function unlockedPackages(workspace, lock) {
716
+ const locked = isObject(lock?.packages) ? lock.packages : {};
717
+ return Object.keys(isObject(workspace?.packages) ? workspace.packages : {}).filter((id) => !Object.hasOwn(locked, id)).sort();
701
718
  }
702
719
 
703
720
  /** Members discovered at once (a fixed bound: the laptop's git and network, not the workspace's size). */
@@ -724,7 +741,13 @@ async function boundedMap(items, limit, task) {
724
741
  /**
725
742
  * The whole picture in one access context.
726
743
  * → { workspace, members: [{ key, commit, confirmed, reason?, souls, capabilities, publishes }], external: [...],
727
- * problems: [{ code, path, message, repoKey? }] }
744
+ * problems: [{ code, path, message, repoKey? }], soulsUnread }
745
+ * `soulsUnread` is where this read may be missing a soul, for the readers of oats-local.yaml souls.launch
746
+ * (lib/instance-resolution.mjs soulsOffered): { members: [repo key] (a confirmed member with a soul skipped,
747
+ * or whose enumeration carries no record of what it skipped: skippedSome),
748
+ * external: [source] (an external soul skipped), packages: [id] (a locked package with a soul skipped),
749
+ * unlocked: [id] (a package the workspace declares and `lock` does not hold) }. It is no part of any
750
+ * JSON answer: `problems` rows keep their fields.
728
751
  * `publishes` = { package, version } when the member carries oats-package/oats-package.json (informational:
729
752
  * the package's capabilities are NOT member capabilities — non-collapse rule), else null.
730
753
  * Members are read DISCOVERY_CONCURRENCY at a time; rows and problems are assembled in declaration order.
@@ -754,21 +777,23 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
754
777
  row.souls = items.souls;
755
778
  row.capabilities = items.capabilities;
756
779
  row.publishes = items.publishes;
757
- return { row, problems: items.problems };
780
+ return { row, problems: items.problems, skipped: skippedSome(items.soulsSkipped) };
758
781
  });
759
782
  } finally {
760
783
  // Every member listed now has adopted its prefetch (or the discovery failed): the rest, members dropped
761
784
  // since the host's last observed commit, are given up.
762
785
  remote.abandonPrefetches?.();
763
786
  }
764
- for (const d of discovered) { members.push(d.row); problems.push(...d.problems); }
787
+ const soulsUnread = { members: [], external: [], packages: [], unlocked: [] };
788
+ // An unconfirmed member carries no enumeration at all: its row says so, and it is not "skipped" here.
789
+ for (const d of discovered) { members.push(d.row); problems.push(...d.problems); if (d.skipped) soulsUnread.members.push(d.row.key); }
765
790
  const externalRows = [];
766
791
  for (const [index, entry] of (workspace.external || []).entries()) {
767
792
  const pin = entry.source.lastIndexOf("@");
768
793
  const sourceRef = entry.source.slice(0, pin);
769
794
  const commit = entry.source.slice(pin + 1);
770
795
  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 });
796
+ const pushProblem = (code, path, message) => { problems.push({ code, repoKey: null, path: `external/${index}:${path}`, message, source: entry.source }); if (!soulsUnread.external.includes(entry.source)) soulsUnread.external.push(entry.source); };
772
797
  let key;
773
798
  try { key = refKey(remote, sourceRef); }
774
799
  catch (e) { if (e?.code === "E_REPO_REF") { pushProblem("E_REPO_REF", "source", e.message); continue; } throw e; }
@@ -784,7 +809,9 @@ export async function discoverWorkspace(ref, { at, local, lock = null, remote: i
784
809
  }
785
810
  const pkg = await discoverPackageSouls(workspace, lock, { remote });
786
811
  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) };
812
+ soulsUnread.packages = pkg.skipped;
813
+ soulsUnread.unlocked = unlockedPackages(workspace, lock);
814
+ 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
815
  }
789
816
 
790
817
  /**
@@ -905,5 +932,8 @@ export function standaloneRepo(ref, commit, discovery, { remote: injected } = {}
905
932
  standalone: true, key, commit: source.commit ?? commit ?? null, workspace: null,
906
933
  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
934
  external: [], problems, warnings: [...privateSoulWarnings(souls), ...capabilityContractWarnings(capabilities)],
935
+ // As discoverWorkspace's: the repo's own souls are all this view offers, so only they can be missing.
936
+ // A discovery or an enumeration with no record of it counts as one with a soul skipped (skippedSome).
937
+ soulsUnread: { members: (Array.isArray(discovery.members) ? (!Array.isArray(discovery.soulsUnread?.members) || discovery.soulsUnread.members.includes(key)) : skippedSome(source.soulsSkipped)) ? [key] : [], external: [], packages: [], unlocked: [] },
908
938
  };
909
939
  }
@@ -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.9.4",
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.53.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.54.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, 54, 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
  }