@awebai/oats 0.69.22 → 0.69.24

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/bin/oats.mjs +185 -38
  2. package/docs/capabilities.md +365 -7
  3. package/docs/capability-manifest.schema.json +37 -1
  4. package/docs/configuration.md +27 -7
  5. package/docs/container.md +206 -228
  6. package/docs/design/2026-11-19-sandboxes.md +1352 -0
  7. package/docs/design/2026-11-20-provider-home-lifecycle.md +320 -0
  8. package/docs/design/README.md +7 -0
  9. package/docs/desktop-cli-api.md +673 -81
  10. package/docs/desktop.md +241 -65
  11. package/docs/execution-targets.md +186 -3
  12. package/docs/first-team.md +11 -0
  13. package/docs/implementation.md +6 -2
  14. package/docs/integrations.md +3 -3
  15. package/docs/knowledge-capability-authoring.md +10 -7
  16. package/docs/knowledge-reference/acceptance.md +21 -19
  17. package/docs/knowledge-reference/adoption.md +18 -4
  18. package/docs/knowledge-reference/model.md +11 -9
  19. package/docs/knowledge-reference/package-craft.md +2 -2
  20. package/docs/knowledge-reference/proposal.md +127 -0
  21. package/docs/knowledge-reference/provider-mapping.md +10 -10
  22. package/docs/knowledge-reference/reader-capture.md +26 -22
  23. package/docs/knowledge-theory.md +1 -1
  24. package/docs/knowledge.md +25 -16
  25. package/docs/official-catalog.md +4 -4
  26. package/docs/packages.md +13 -13
  27. package/docs/release-notes/v0.69.23.md +231 -0
  28. package/docs/release-notes/v0.69.24.md +264 -0
  29. package/docs/servers.md +10 -6
  30. package/docs/souls-and-instances.md +96 -22
  31. package/docs/tui.md +25 -4
  32. package/docs/upgrading.md +19 -5
  33. package/docs/workspaces.md +14 -6
  34. package/lib/argv.mjs +6 -2
  35. package/lib/capability-contract.mjs +2 -2
  36. package/lib/capability-show.mjs +11 -1
  37. package/lib/command-flags.mjs +40 -3
  38. package/lib/compile-cache.mjs +1 -1
  39. package/lib/core.mjs +1201 -195
  40. package/lib/errors.mjs +4 -1
  41. package/lib/hook-env.mjs +106 -0
  42. package/lib/host-run.mjs +11 -3
  43. package/lib/instance-board.mjs +337 -0
  44. package/lib/instance-events.mjs +48 -10
  45. package/lib/instance-inspect.mjs +44 -0
  46. package/lib/instance-lifecycle.mjs +34 -18
  47. package/lib/instance-listing.mjs +113 -16
  48. package/lib/instance-related-work.mjs +143 -0
  49. package/lib/kernel-features.mjs +13 -1
  50. package/lib/node-version.mjs +9 -0
  51. package/lib/provider-call-child.mjs +60 -0
  52. package/lib/provider-resume.mjs +83 -0
  53. package/lib/provider-test-seams.mjs +20 -0
  54. package/lib/read-call.mjs +2 -0
  55. package/lib/reserved-launch-env.mjs +8 -1
  56. package/lib/retire-admission.mjs +5 -1
  57. package/lib/schedule.mjs +14 -4
  58. package/lib/servers.mjs +151 -17
  59. package/lib/session-inspect.mjs +104 -13
  60. package/lib/session-providers.mjs +528 -0
  61. package/lib/session-resume.mjs +68 -15
  62. package/lib/stable-node.mjs +3 -0
  63. package/lib/triggers.mjs +3 -1
  64. package/package-catalog.json +3 -3
  65. package/package.json +2 -1
  66. package/packages/client/capability-list.mjs +21 -0
  67. package/packages/client/cli-adapter.mjs +19 -4
  68. package/packages/client/cli-locator.mjs +5 -1
  69. package/packages/client/deployment-data.mjs +27 -3
  70. package/packages/client/deployment-panel.mjs +27 -4
  71. package/packages/client/home-board.mjs +33 -19
  72. package/packages/client/inspect-boundary.mjs +18 -8
  73. package/packages/client/instance-acts.mjs +30 -3
  74. package/packages/client/instance-board.mjs +206 -0
  75. package/packages/client/instance-presentation.mjs +55 -0
  76. package/packages/client/instance-tree.mjs +34 -4
  77. package/packages/client/keymap.mjs +5 -0
  78. package/packages/client/liveness.mjs +15 -4
  79. package/packages/client/mail-contract.mjs +130 -0
  80. package/packages/client/own-codes.mjs +5 -1
  81. package/packages/client/panel-views.mjs +7 -7
  82. package/packages/client/related-work.mjs +84 -0
  83. package/packages/client/remote-roster.mjs +9 -3
  84. package/packages/client/session-backends.mjs +31 -0
  85. package/packages/client/session-start.mjs +18 -6
  86. package/packages/client/spawn-apply-cli.mjs +5 -3
  87. package/packages/client/spawn-apply-contract.mjs +25 -2
  88. package/packages/client/spawn-apply.mjs +5 -1
  89. package/packages/client/spawn-messages.mjs +3 -0
  90. package/packages/client/terminal-contract.mjs +4 -0
  91. package/packages/client/waiting-on-you.mjs +12 -2
  92. package/packages/client/workspace-cli.mjs +13 -2
  93. package/packages/tui/lib/model.mjs +14 -3
  94. package/packages/tui/lib/store.mjs +12 -3
  95. package/skills/oats-getting-started/SKILL.md +11 -8
  96. package/docs/knowledge-reference/harvester.md +0 -109
  97. package/lib/instance-same-work.mjs +0 -67
  98. package/packages/client/same-work.mjs +0 -49
@@ -25,7 +25,9 @@
25
25
  *
26
26
  * Producers write claims as `waiting` rows through `setWaiting` (the CLI's
27
27
  * `oats instance waiting` and `oats instance attention`): data
28
- * `{waitingOnYou, reason?, message?}`, appended only on a change. A claim
28
+ * `{waitingOnYou, reason?, message?, session?}`, appended only on a change; `session`
29
+ * (the board's claim, lib/instance-board.mjs) binds a positive claim to the session it was
30
+ * derived in, so it never counts in another (claimsOf). A claim
29
31
  * authorizes nothing; it may only withhold an automated keystroke: a scheduled
30
32
  * wake holds on a live `permission`, `question` or unknown-reason claim
31
33
  * (waitingHold). Every other reader takes it as evidence for display.
@@ -41,6 +43,7 @@
41
43
  * one home's, so its `home` is the address that was asked about, and a consumer
42
44
  * that checks "the rows' home is the home I asked for" keeps holding. */
43
45
  import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
46
+ import { createHash } from "node:crypto";
44
47
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
45
48
  import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
46
49
 
@@ -85,6 +88,12 @@ function cutToUnits(text, max) {
85
88
  * incarnation's latest one is not live. */
86
89
  export const WAITING_BOUNDARY_KINDS = ["launched", "restarted", "stopped"];
87
90
  const sessionBoundary = (r) => (r.producer ?? "kernel") === "kernel" && WAITING_BOUNDARY_KINDS.includes(r.kind);
91
+ /** The id of the session a boundary row begins, or null for no boundary: what a session-bound claim
92
+ * (setWaiting `session`) and a board question (lib/instance-board.mjs) record. `<kind>@<at>#<digest of
93
+ * its data>`: two boundaries of one millisecond are told apart by what they record (a launch's
94
+ * `startId`, a stop's receipt), never by their place in a bounded read, and the same row written
95
+ * again (a start boundary repaired into the other log, recordStartBoundary) is the same session. */
96
+ const sessionIdOf = (r) => (r ? `${r.kind}@${r.at}#${createHash("sha256").update(JSON.stringify(r.data ?? null)).digest("hex").slice(0, 16)}` : null);
88
97
  /** The closed set of reasons a positive claim carries. A claim authorizes nothing; it may only
89
98
  * withhold an automated keystroke. `attention` never marks a screen an Enter answers: a producer
90
99
  * that wants one uses `question`, and review catches that. */
@@ -232,6 +241,10 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
232
241
  return { ok: results.some((r) => r.ok), row, results };
233
242
  }
234
243
 
244
+ /** Whether a read of one log holds the whole log: it was absent, or read in full (not a tail, not
245
+ * refused). */
246
+ const wholeRead = (log) => log.source.status === "ok" || log.source.status === "absent";
247
+
235
248
  /** Bounded, descriptor-safe read of one log: lstat → regular file only → read
236
249
  * at most the last MAX_BYTES. Returns rows plus the source's integrity facts, and
237
250
  * `lastTorn`: where the last torn row sat, as the index in `rows` of the row after it
@@ -300,8 +313,10 @@ function admit(home, reads) {
300
313
  * unknown stays unknown, it never resurrects an earlier incarnation's
301
314
  * positive. A row older than the incarnation's latest kernel session
302
315
  * boundary belongs to an ended session and is not a claim at all, nor is a
303
- * row whose producer is neither `kernel` nor a valid producer id. */
304
- function claimsOf(rows, incarnation) {
316
+ * row whose producer is neither `kernel` nor a valid producer id. `complete`:
317
+ * whether every log read was whole (wholeRead); a session-bound row needs it,
318
+ * or a boundary of the incarnation in the rows, to count (below). */
319
+ function claimsOf(rows, incarnation, { complete }) {
305
320
  const claims = new Map();
306
321
  if (incarnation === null) return claims;
307
322
  const current = rows.filter((r) => r.incarnation === incarnation);
@@ -309,8 +324,14 @@ function claimsOf(rows, incarnation) {
309
324
  // millisecond keep their append order, and a claim appended before the
310
325
  // boundary in that millisecond is still before it.
311
326
  const boundary = current.findLastIndex(sessionBoundary);
327
+ const session = sessionIdOf(current[boundary]);
312
328
  for (const r of current.slice(boundary + 1)) {
313
329
  if (!r.data || typeof r.data.waitingOnYou !== "boolean") continue;
330
+ // A session-bound row (setWaiting `session`) counts only in the session it names, and only where
331
+ // the read proves the current session: a boundary of the incarnation in the rows, or a whole read
332
+ // (with none, the first session). One appended after a boundary its writer had not seen, or read
333
+ // where the current boundary may have fallen out of a tail, says nothing. Unbound rows are as before.
334
+ if (Object.hasOwn(r.data, "session") && (r.data.session !== session || (boundary < 0 && !complete))) continue;
314
335
  const p = r.producer ?? "kernel";
315
336
  // A row the read rule refuses (a hand-edited log: its producer, its time) says nothing.
316
337
  const claim = readWaitingClaim({ since: r.at, producer: p, reason: r.data.reason, message: r.data.message });
@@ -344,7 +365,7 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
344
365
  const { home, instance, incarnation, homeLog, workspaceLog } = address;
345
366
  const a = readLog(homeLog, "home"), b = readLog(workspaceLog, "workspace");
346
367
  const { rows, foreign } = admit(home, [a, b]);
347
- const claims = claimsOf(rows, incarnation);
368
+ const claims = claimsOf(rows, incarnation, { complete: wholeRead(a) && wholeRead(b) });
348
369
  const waitingClaims = [...claims.values()];
349
370
  const positive = positiveOf(claims);
350
371
  const filtered = since ? rows.filter((r) => r.at > since) : rows;
@@ -374,11 +395,26 @@ export function readEvents(given, { limit = 200, since = null, asked } = {}) {
374
395
  * or a session boundary writes goes to both. `meta`: the home's record, when the caller has just
375
396
  * read it (lib/instance-listing.mjs listInstances), so that one read parses it once. */
376
397
  export function liveWaiting(home, { meta } = {}) {
398
+ return liveSession(home, { meta }).waitingOnYou;
399
+ }
400
+
401
+ /** The instance's current session as one read of its log shows it (liveWaiting's read):
402
+ * `{ incarnation, session, sessionKnown, waitingOnYou }`. `session` is the id of the incarnation's
403
+ * latest kernel session boundary (`launched`, `restarted`, `stopped`; `<kind>@<at>`), null when the
404
+ * read holds none. `sessionKnown` says whether the read proves it: false when the log was read as a
405
+ * tail (its last MAX_BYTES) that holds no boundary of this incarnation, where an earlier one may
406
+ * have been cut off. A board question counts only in the session it was asked in
407
+ * (lib/instance-board.mjs). An unknown incarnation is `{ incarnation: null, session: null,
408
+ * sessionKnown: false, waitingOnYou: null }`. */
409
+ export function liveSession(home, { meta } = {}) {
377
410
  const a = addressOf(home, meta);
378
- if (a.incarnation === null) return null;
411
+ if (a.incarnation === null) return { incarnation: null, session: null, sessionKnown: false, waitingOnYou: null };
379
412
  let log = readLog(a.homeLog, "home");
380
413
  if (log.source.status === "absent") log = readLog(a.workspaceLog, "workspace");
381
- return waitingShape(positiveOf(claimsOf(admit(a.home, [log]).rows, a.incarnation)));
414
+ const rows = admit(a.home, [log]).rows;
415
+ const boundary = rows.filter((r) => r.incarnation === a.incarnation).findLast(sessionBoundary);
416
+ const sessionKnown = !!boundary || wholeRead(log);
417
+ return { incarnation: a.incarnation, session: sessionIdOf(boundary), sessionKnown, waitingOnYou: waitingShape(positiveOf(claimsOf(rows, a.incarnation, { complete: wholeRead(log) }))) };
382
418
  }
383
419
 
384
420
  /** What holds a scheduled wake at this home: null (no hold), `{claimReason, producer}` (a claim), or
@@ -403,7 +439,7 @@ export function waitingHold(given) {
403
439
  if (status === "tail" && boundary < 0) return unreadable(`the ${path} events log's tail holds no session boundary`);
404
440
  if (log.lastTorn > boundary) return unreadable(`the ${path} events log has a torn row in this session`);
405
441
  }
406
- const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation).values()].filter((c) => c.waiting && c.reason !== "attention");
442
+ const claims = [...claimsOf(admit(a.home, logs).rows, a.incarnation, { complete: logs.every(wholeRead) }).values()].filter((c) => c.waiting && c.reason !== "attention");
407
443
  const newest = claims.sort((x, y) => x.since.localeCompare(y.since)).at(-1);
408
444
  return newest ? { claimReason: newest.reason, producer: newest.producer } : null;
409
445
  }
@@ -420,13 +456,15 @@ const waitingError = (code, message) => Object.assign(new Error(message), { code
420
456
  * E_SESSION_UNKNOWN; a write either log refused is E_EVENTS_FAILED (a retry
421
457
  * repairs it). The answer's `home` is the home as the caller spelled it; the row
422
458
  * records the real path. Evidence, not authority: nothing else is touched. */
423
- export function setWaiting(given, { producer, waiting, reason, message } = {}) {
459
+ export function setWaiting(given, { producer, waiting, reason, message, session } = {}) {
424
460
  if (typeof producer !== "string" || !WAITING_PRODUCER_RE.test(producer)) throw waitingError("E_BAD_ARGS", `--producer must match ${WAITING_PRODUCER_RE.source}`);
425
461
  if (producer === "kernel") throw waitingError("E_BAD_ARGS", "--producer kernel is reserved for the kernel's own events");
426
462
  if (typeof waiting !== "boolean") throw waitingError("E_BAD_ARGS", "waiting must be set or clear");
427
463
  if (waiting) {
428
464
  if (!WAITING_REASONS.includes(reason)) throw waitingError("E_BAD_ARGS", `--reason must be one of ${WAITING_REASONS.join(", ")}`);
429
465
  if (message !== undefined && !validWaitingMessage(message)) throw waitingError("E_BAD_ARGS", `--message must be one line of 1 to ${WAITING_MESSAGE_MAX} characters with no control character, line separator, bidi control (U+202A-202E, U+2066-2069), U+200B, U+2060, U+FEFF or tag character`);
466
+ // A session-bound claim (in-process only: the board's) names the session it was derived in.
467
+ if (session !== undefined && session !== null && typeof session !== "string") throw waitingError("E_BAD_ARGS", "session must be a session id or null");
430
468
  } else {
431
469
  if (reason !== undefined) throw waitingError("E_BAD_ARGS", "--reason is for set, not clear");
432
470
  if (message !== undefined) throw waitingError("E_BAD_ARGS", "--message is for set, not clear");
@@ -435,11 +473,11 @@ export function setWaiting(given, { producer, waiting, reason, message } = {}) {
435
473
  const { home, incarnation } = a;
436
474
  if (incarnation === null) throw waitingError("E_SESSION_UNKNOWN", `${given} is not an instance home (no readable instance.json)`);
437
475
  const live = [readLog(a.homeLog, "home"), readLog(a.workspaceLog, "workspace")]
438
- .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation).get(producer); return c?.waiting ? c : null; });
476
+ .map((log) => { const c = claimsOf(admit(home, [log]).rows, incarnation, { complete: wholeRead(log) }).get(producer); return c?.waiting ? c : null; });
439
477
  const agrees = (c) => (waiting ? !!c && c.reason === reason && c.message === (message ?? null) : !c);
440
478
  const answer = (changed, claim) => answered(a, { eventsApi: EVENTS_API, instance: a.instance, home, producer, changed, waitingOnYou: waitingShape(claim) });
441
479
  if (live.every(agrees)) return answer(false, waiting ? live[0] : null);
442
- const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}) } : { waitingOnYou: false };
480
+ const data = waiting ? { waitingOnYou: true, reason, ...(message !== undefined ? { message } : {}), ...(session !== undefined ? { session } : {}) } : { waitingOnYou: false };
443
481
  const res = append(a, { producer, kind: "waiting", data }, { incarnation });
444
482
  const failed = (res.results || []).filter((r) => !r.ok);
445
483
  if (!res.ok || failed.length) throw waitingError("E_EVENTS_FAILED", `could not record the waiting claim in ${failed.map((r) => `${r.path} (${r.reason})`).join(", ") || res.reason}; retry to complete it`);
@@ -34,6 +34,7 @@ import { readInstancePin } from "./instance-pin.mjs";
34
34
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
35
35
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
36
36
  import { parseStrictJson } from "./canonical-json.mjs";
37
+ import { checkProviderSession, homeSessionProvider, offeredSessionProviders, sessionProvidersOf } from "./session-providers.mjs";
37
38
  import { sameRepo } from "./repo-moves.mjs";
38
39
  import { kernelNode } from "./stable-node.mjs";
39
40
 
@@ -524,6 +525,9 @@ export function inspectDocument(t, { kernel }) {
524
525
  return {
525
526
  operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
526
527
  souls: [soulRow(t)], layers, capabilities,
528
+ // Feature session-providers: the session backends this soul's (or home's) capabilities supply
529
+ // beside the kernel's own, what `--backend` takes here: [{ name, capability }].
530
+ ...sessionProviderKeys(t),
527
531
  // The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
528
532
  // (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
529
533
  capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
@@ -674,6 +678,14 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
674
678
  ({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
675
679
  ...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
676
680
 
681
+ /** `sessionProviders` of an inspect answer: the session backends the target's capabilities supply
682
+ * and a spawn can select there, `[{ name, capability }]` sorted by name (lib/session-providers.mjs
683
+ * offeredSessionProviders over the target's modules). A malformed declaration is none: what is
684
+ * wrong with it is `oats capabilities show`'s to say. */
685
+ function sessionProviderKeys(t) {
686
+ const { providers } = offeredSessionProviders((t.modules || []).filter((x) => x.manifest).map((x) => ({ id: x.name, manifest: x.manifest })));
687
+ return { sessionProviders: providers.map(({ name, capability }) => ({ name, capability })) };
688
+ }
677
689
  /** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
678
690
  * stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
679
691
  function providerEnv(t, capability, settings) {
@@ -870,6 +882,38 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
870
882
  }
871
883
  else providers.push(item(mod.name, "unknown", { producer: "provider binding check", result: null, problems: out.problems, reason: out.problems[0]?.message ?? null, ...cap(mod.name) }));
872
884
  }
885
+ // A session provider's own readiness (lib/session-providers.mjs, the optional `check` command),
886
+ // relayed verbatim as a providers item, as a binding check is. For a home: the provider it runs
887
+ // on, required. For a soul: every provider its capabilities offer, not required (the soul can
888
+ // launch on tmux); a member capability's runs from a spawned home, as its binding check does.
889
+ for (const mod of t.modules) {
890
+ const offered = Object.values(sessionProvidersOf(mod.manifest).providers).filter((p) => p.commands.check);
891
+ for (const provider of offered) {
892
+ const onIt = t.home ? t.meta?.backend === provider.name && t.meta?.session?.provider === mod.name : false;
893
+ if (t.home && !onIt) continue;
894
+ const subject = `${mod.name} session backend ${provider.name}`;
895
+ const push = (status, rest) => providers.push(item(subject, status, { required: !!t.home, producer: "session provider check", ...rest, ...cap(mod.name) }));
896
+ const unknown = (code, message) => push("unknown", { result: null, problems: [{ code, message }], reason: message });
897
+ if (Date.now() >= deadline) { unknown("time-budget-exhausted", `time budget exhausted: the providers check stops after ${Math.round(budgetMs / 1000)} s per readiness read`); continue; }
898
+ let binding;
899
+ if (t.home) {
900
+ const found = homeSessionProvider(t.home, t.meta, mod.name, provider.name);
901
+ if (found.problem) { unknown("resource-not-found", found.problem); continue; }
902
+ binding = found.binding;
903
+ } else {
904
+ let dir = null;
905
+ if (mod.module && t.lock) { try { dir = await ensureModuleTree(t.deployment, mod.module, t.lock, { catalog, remoteOptions }); } catch (e) { unknown(e.code || "provider-unavailable", e.message); continue; } }
906
+ if (!dir) { unknown("resource-not-found", `${mod.name}: a member module runs from a spawned home; inspect an instance (--home) for its check`); continue; }
907
+ const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
908
+ binding = { home: null, meta: {}, capability: mod.name, name: provider.name, provider, moduleDir: dir, cap: { id: mod.name, settings }, digest: null,
909
+ env: { ...providerEnv(t, mod.name, settings), OATS_EVENT: "session", OATS_BACKEND: provider.name } };
910
+ }
911
+ const checked = checkProviderSession(binding, { home: t.home ?? null, soul: t.home ? null : t.soul.name, settings: binding.cap.settings }, { timeoutMs: Math.max(1, Math.min(20_000, deadline - Date.now())) });
912
+ if (checked.unavailable) { unknown("provider-unavailable", checked.unavailable); continue; }
913
+ const status = PROVIDER_STATUS_ITEM[checked.result.status];
914
+ push(status, { result: checked.result, reason: status === "pass" ? null : checked.result.problems[0]?.message ?? `the provider reports ${checked.result.status}` });
915
+ }
916
+ }
873
917
  const checks = { installed: { status: roll(installed), items: installed }, configured: { status: roll(configured), items: configured }, member: { status: roll(member), items: member }, providers: { status: roll(providers), items: providers } };
874
918
  const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
875
919
  const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
@@ -21,7 +21,7 @@ import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
21
21
  import { INSTANCE_COLOR_API, INSTANCE_COLORS, writeInstanceColor } from "./instance-color.mjs";
22
22
  import { INSTANCE_BACKGROUND_API, writeInstanceBackground } from "./instance-background.mjs";
23
23
  import { INSTANCE_PIN_API, writeInstancePin } from "./instance-pin.mjs";
24
- import { sameWorkOf, writeSameWork } from "./instance-same-work.mjs";
24
+ import { relatedWorkBinding, relatedWorkHeld, writeRelatedWork } from "./instance-related-work.mjs";
25
25
  import { resolveInstance } from "./instance-address.mjs";
26
26
  export { resolveInstance } from "./instance-address.mjs";
27
27
 
@@ -110,23 +110,27 @@ export function setInstancePin(ctx, root, name, { home, pinned }) {
110
110
  return { instancePinApi: INSTANCE_PIN_API, instance: name, home: me.home, pinned, changed };
111
111
  }
112
112
 
113
- /** `oats instance same-work <instance> on|off` (feature instance-same-work, awebai/oats#1577): bind the flag
114
- * of the home `name` resolves to to its recorded parent (`on`), or remove it (`off`). Addressed, and refused
115
- * beside a retire or in a quarantined home, exactly as setInstanceColor is. `on` needs a recorded
116
- * `parentInstance` (E_BAD_ARGS without one) and rebinds a record bound to an old parent; the same parent
117
- * again writes nothing. `off` succeeds whatever stands there, parent or none. → `{ instance, sameWork }`,
118
- * the rule (sameWorkOf) read after the write. */
119
- export function setInstanceSameWork(ctx, root, name, { home, on }) {
120
- if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance same-work takes on or off");
113
+ /** `oats instance related-work <instance> on|off` (feature instance-related-work), and its deprecated alias
114
+ * `oats instance same-work` (feature instance-same-work): bind the flag of the home
115
+ * `name` resolves to to its recorded parent, else to its recorded sibling (`on`, relatedWorkBinding), or
116
+ * remove it (`off`). Addressed, and refused beside a retire or in a quarantined home, exactly as
117
+ * setInstanceColor is. `on` needs a recorded `parentInstance` or `siblingInstance` (E_BAD_ARGS with
118
+ * neither) and rebinds a record bound to an old relation; the same binding again writes nothing. `off`
119
+ * succeeds whatever stands there, binding or none. → `{ instance, relatedWork, sameWork }`, the rule
120
+ * (relatedWorkHeld) read after the write: `relatedWork` whether it holds, `sameWork` whether it holds as a
121
+ * parent binding (the old verb's answer, for an older client). */
122
+ export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
123
+ if (typeof on !== "boolean") throw oatsError("E_BAD_ARGS", "instance related-work takes on or off");
121
124
  const me = resolveTarget(ctx, root, name, { home });
122
125
  if (existsSync(join(me.home, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${me.home} is a quarantined home (or a spawn still in progress); finish its retirement (oats retire); the flag was not changed`);
123
126
  if (existsSync(retirePendingMarkerPath(me.home))) throw oatsError("E_INSTANCE_RETIRING", `${name} is being retired; the flag was not changed`);
124
- refuseBesideRetire("instance same-work", me.home);
125
- const recorded = targetRecord(me.home)?.parentInstance;
126
- const parent = typeof recorded === "string" && recorded !== "" ? recorded : null;
127
- if (on && parent === null) throw oatsError("E_BAD_ARGS", `${name} has no parent instance: same work is declared against a recorded parent; the flag was not changed`);
128
- writeSameWork(me.home, on ? parent : null);
129
- return { instance: name, sameWork: sameWorkOf(me.home, parent) };
127
+ refuseBesideRetire("instance related-work", me.home);
128
+ const lineage = targetRecord(me.home) ?? {};
129
+ const binding = relatedWorkBinding(lineage);
130
+ if (on && binding === null) throw oatsError("E_BAD_ARGS", `${name} would record no parent or sibling instance: related work is declared against a recorded parent or sibling; the flag was not changed`);
131
+ writeRelatedWork(me.home, on ? binding : null);
132
+ const held = relatedWorkHeld(me.home, lineage);
133
+ return { instance: name, relatedWork: held !== null, sameWork: !!held?.parent };
130
134
  }
131
135
 
132
136
  /** Every instance under the roots whose recorded parent chain reaches `name`,
@@ -134,7 +138,9 @@ export function setInstanceSameWork(ctx, root, name, { home, on }) {
134
138
  * parentage is the only relation the kernel knows; it is reported as such. */
135
139
  export function descendantsOf(root, name) {
136
140
  const rows = [];
137
- for (const a of listAgents(root)) for (const i of listInstances(root).filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
141
+ // One listing, and no session provider asked: only names and records are read here.
142
+ const listed = listInstances(root, undefined, undefined, { askProviders: false });
143
+ for (const a of listAgents(root)) for (const i of listed.filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
138
144
  const home = join(a._dir, "instances", inst.instance);
139
145
  const meta = otherRecord(home);
140
146
  if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
@@ -157,6 +163,9 @@ export function descendantsOf(root, name) {
157
163
  return out; // deepest first
158
164
  }
159
165
 
166
+ /** What the session's inspect said of its activity (`running`: true, false, or null for not known),
167
+ * kept beside the facts for planStop's `midTask` and never part of a plan's JSON. */
168
+ const REPORTED_RUNNING = Symbol("reportedRunning");
160
169
  /** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
161
170
  * idle; "unknown" means a NON-shell process is running whose identity tmux
162
171
  * cannot name (the ordinary case for a launched harness). "Could not be
@@ -164,7 +173,7 @@ export function descendantsOf(root, name) {
164
173
  * the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
165
174
  * for one that has none; workFacts: E_GIT_FAILED). */
166
175
  function sessionFacts(home) {
167
- try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
176
+ try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true, [REPORTED_RUNNING]: s.running ?? null }; }
168
177
  catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
169
178
  }
170
179
  /** The instances attached to `tree`, a tree of the home of the instance `name` under `root` (its
@@ -229,7 +238,14 @@ export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDING
229
238
  const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
230
239
  // Reported activity: a running session or dirty work is mid-task; when the
231
240
  // session could not be established and work is not observed, say unknown.
232
- for (const t of targets) t.midTask = running(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || !t.work.observed) ? "unknown" : false;
241
+ // A session provider's session says its activity itself (its inspect's `running`): true is
242
+ // activity, and one that is there and reports none (null) is not reported as activity: unknown.
243
+ // (A tmux pane's state "unknown" is a process tmux cannot name, the ordinary launched harness:
244
+ // activity, as before.)
245
+ const onProvider = (s) => s.established && s.present === true && s.backend !== null && s.backend !== "tmux";
246
+ const unknownActivity = (s) => onProvider(s) && s[REPORTED_RUNNING] === null;
247
+ const active = (s) => (onProvider(s) ? s[REPORTED_RUNNING] === true : running(s));
248
+ for (const t of targets) t.midTask = active(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || unknownActivity(t.session) || !t.work.observed) ? "unknown" : false;
233
249
  const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
234
250
  const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
235
251
  const plan = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: me.home, recursive, at: new Date().toISOString(),
@@ -8,7 +8,8 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
8
8
  import { join, dirname, resolve, basename } from "node:path";
9
9
  import { noteRuntimeName } from "./deprecation.mjs";
10
10
  import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
11
- import { liveWaiting, validWaitingMessage } from "./instance-events.mjs";
11
+ import { liveSession, liveWaiting, validWaitingMessage } from "./instance-events.mjs";
12
+ import { readBoardRow } from "./instance-board.mjs";
12
13
  import { processLiveness } from "./worktree-hooks.mjs";
13
14
  import { shownHolder } from "./claim.mjs";
14
15
  import { isInstant as isInstantString, readRetireState } from "./retire-state.mjs";
@@ -16,12 +17,14 @@ import { herdrInstanceRemoved, oatsError } from "./errors.mjs";
16
17
  import { readInstanceColor } from "./instance-color.mjs";
17
18
  import { readInstanceBackground } from "./instance-background.mjs";
18
19
  import { readInstancePin } from "./instance-pin.mjs";
19
- import { sameWorkOf } from "./instance-same-work.mjs";
20
+ import { relatedWorkHeld } from "./instance-related-work.mjs";
20
21
  import { readSpawnedBy } from "./spawned-by.mjs";
21
- import { sessionEndOf } from "./session-end.mjs";
22
+ import { HOST_STOP_REASON, lostReasonOf, sessionEndOf } from "./session-end.mjs";
22
23
  import { identityHolderState, recordSeen } from "./session-seen.mjs";
23
24
  import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
24
- import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot } from "./session-inspect.mjs";
25
+ import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
26
+ import { INSPECT_MANY_MAX, sessionProviderTimeout, homeSessionProvider, recordsSessionProvider, inspectManyGroup, inspectProviderSession, inspectProviderSessions, rowSession, unsettledLaunchSaid } from "./session-providers.mjs";
27
+ import { SESSION_END } from "./session-resume-contract.mjs";
25
28
 
26
29
  /** OATS 0.25 and earlier homed local souls and capability-defined agents at
27
30
  * <scope>/local-agents/ (and <root>/local-agents|tmp-agents). The kernel never reads,
@@ -277,10 +280,79 @@ function statusTmuxPanes(snapshot, socket, session, io) {
277
280
  return { ...snapshot, panes, windowIds };
278
281
  } catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
279
282
  }
283
+ /** The row of a home on a session provider, before its provider has been asked: the kernel's own
284
+ * facts, under the receipt's authority (instanceSessionTarget). → `{ fields, ask? }`: `fields` the
285
+ * row's `backend`, `session`, `tmux` (null), `open`, `running`, `runtimeState` (`unknown`, `shell`,
286
+ * `stopped` or `unreachable`; always there) and, for a home OATS stopped, `sessionEnd`; `ask`
287
+ * (`{ binding, endpoint }`) for a session the provider must be asked about.
288
+ * `session` is `{ provider }` and, on this host only, the endpoint's thread id (rowSession): the
289
+ * endpoint itself is never on a row (`oats session inspect --home` answers it, locally).
290
+ * A home OATS stopped, and one never launched, answer without the provider. A stopped home's
291
+ * `sessionEnd` is its stop receipt's (lib/session-end.mjs): `lost` when `oats host run`'s shutdown
292
+ * stopped it, which a resume brings back, else `stopped`. A receipt or a module copy that cannot
293
+ * be used is unknown (`unreachable`, with the reason), never stopped. */
294
+ function providerRow(home, meta) {
295
+ const unreachable = (why, session) => ({ fields: { backend: meta.backend, session: session ?? rowSession(typeof meta.session?.provider === "string" ? meta.session.provider : null, null), tmux: null, open: null, running: null, runtimeState: "unreachable", runtimeError: why } });
296
+ let s;
297
+ try { s = instanceSessionTarget(home); } catch (e) { return unreachable(`${typeof e?.code === "string" ? e.code : "E_SESSION_UNAVAILABLE"}: ${e?.message ?? e}`); }
298
+ const recorded = s.session ?? s.planned;
299
+ // A record that names a session provider beside a receipt that authorises a tmux session, or none.
300
+ if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
301
+ const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null };
302
+ // A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
303
+ if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
304
+ if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
305
+ if (s.session.stoppedAt !== null) return { fields: { ...fields, running: false, runtimeState: "stopped", sessionEnd: lostReasonOf(home, s.meta) === HOST_STOP_REASON ? SESSION_END.LOST : SESSION_END.STOPPED } };
306
+ const found = homeSessionProvider(home, s.meta, s.session.provider, s.session.backend);
307
+ if (found.problem) return unreachable(found.problem, fields.session);
308
+ return { fields: { ...fields, running: null, runtimeState: "unreachable" }, ask: { binding: found.binding, endpoint: s.session.endpoint } };
309
+ }
310
+ /** The time one listing gives all its session providers together: a provider that hangs costs a
311
+ * status, a sweep or a plan this much at most, however many homes it has. */
312
+ const PROVIDER_LISTING_BUDGET_MS = 30_000;
313
+ /** Ask the providers about `asks` ([{ row, home, binding, endpoint, mayEnd }]) and write each answer
314
+ * into its row: one `inspectMany` call per group of homes that share one module copy, provider and
315
+ * settings (inspectManyGroup), at most INSPECT_MANY_MAX homes a call, and one `inspect` per home
316
+ * where a provider declares none (or its batch was bad: inspectProviderSessions). A provider that
317
+ * fails, refuses or answers outside the contract's words leaves the row unknown: `running: null`,
318
+ * `runtimeState: "unreachable"`. A session that is gone on a home OATS did not stop is a lost
319
+ * one (`sessionEnd: "lost"`, where the row may say how its session ended: `mayEnd`), which the
320
+ * sweep resumes under the home's cap. All the asks of one listing share PROVIDER_LISTING_BUDGET_MS. */
321
+ function answerProviderRows(asks, io) {
322
+ const deadline = Date.now() + PROVIDER_LISTING_BUDGET_MS;
323
+ // Each call's timeout: the verb's own (and a test's seam), never past what the listing has left.
324
+ const timeoutFor = () => Math.min(sessionProviderTimeout("inspect"), deadline - Date.now());
325
+ const groups = new Map(), single = [];
326
+ for (const ask of asks) {
327
+ const key = inspectManyGroup(ask.binding);
328
+ if (key === null) single.push(ask);
329
+ else groups.set(key, [...(groups.get(key) ?? []), ask]);
330
+ }
331
+ const answer = (ask, inspected) => {
332
+ if (inspected.unavailable) { Object.assign(ask.row, { running: null, runtimeState: "unreachable", runtimeError: inspected.unavailable }); return; }
333
+ const { state, running, open } = inspected.observed;
334
+ Object.assign(ask.row, { running, runtimeState: state, open });
335
+ delete ask.row.runtimeError;
336
+ // A producer's claim, read while the session is there and not in error (an idle session can be
337
+ // the one waiting on a person); the receipt already agreed (providerRow).
338
+ if (providerMayWait(inspected.observed)) ask.row.waitingOnYou = liveWaiting(ask.home);
339
+ if (inspected.observed.present === false && ask.mayEnd) ask.row.sessionEnd = SESSION_END.LOST;
340
+ };
341
+ for (const ask of single) { const timeoutMs = timeoutFor(); answer(ask, timeoutMs > 0 ? inspectProviderSession(ask.binding, ask.endpoint, { io, timeoutMs }) : { unavailable: "the time this listing gives its session providers was spent before this one was asked" }); }
342
+ for (const members of groups.values()) {
343
+ for (let at = 0; at < members.length; at += INSPECT_MANY_MAX) {
344
+ const chunk = members.slice(at, at + INSPECT_MANY_MAX);
345
+ inspectProviderSessions(chunk, { io, timeoutFor }).forEach((inspected, i) => answer(chunk[i], inspected));
346
+ }
347
+ }
348
+ }
280
349
  /** `records`, when given, a Map the listing fills with each home's record as read (home → the JSON
281
350
  * object its instance.json holds, before upgradeHomeMeta), for the rest of the same read to reuse
282
- * instead of reading the file again (legacyCapturedHomes). */
283
- export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records } = {}) {
351
+ * instead of reading the file again (legacyCapturedHomes).
352
+ * `askProviders: false` (the host's shutdown listing): no session provider is asked. A provider
353
+ * home whose provider would be asked reads `running: null`, `runtimeState: "unreachable"`, with a
354
+ * `runtimeError` that says so: the listing then depends on no provider's answer, or time. */
355
+ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records, askProviders = true } = {}) {
284
356
  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
285
357
  // socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
286
358
  // plus one lazy process scan for shell descendants, independent of the number of homes.
@@ -293,6 +365,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
293
365
  return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
294
366
  };
295
367
  const inspectPanes = createSessionPaneInspector(io);
368
+ // The homes on a session provider whose provider must be asked: asked together once every row is
369
+ // read (answerProviderRows), so that one call can answer for a provider's whole group.
370
+ const providerAsks = [];
296
371
  const tmuxByEndpoint = new Map();
297
372
  const windowsOf = (session, socket) => {
298
373
  const key = JSON.stringify([socket ?? null, session]);
@@ -317,9 +392,14 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
317
392
  const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
318
393
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
319
394
  // A home whose record cannot be read is listed, never observed: where its session is, is in the record.
395
+ const herdr = record.state !== "unreadable" && recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)));
396
+ // A home on a session provider is never read through tmux: its row is the kernel's facts
397
+ // and, where the provider must be asked, its answer (below, once every row is read).
398
+ const provided = record.state === "record" && !herdr && recordsSessionProvider(meta) ? providerRow(home, meta) : null;
320
399
  const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
321
- : recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
400
+ : herdr
322
401
  ? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
402
+ : provided ? (({ sessionEnd: _own, ...fields }) => fields)(provided.fields)
323
403
  : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
324
404
  // A home that records no socket and no launch (--no-launch) reads the default server only
325
405
  // by default: that server's missing socket says nothing about it, and stays "not running".
@@ -345,30 +425,46 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
345
425
  // its home log); null otherwise, and null means unknown. Pane liveness is
346
426
  // already observed in the batch; still require the independent receipt
347
427
  // to agree before showing a claim, just as session inspect does.
348
- let waitingOnYou = liveness.running === true ? liveWaiting(home, record.state === "record" ? { meta: record.meta } : {}) : null;
428
+ const recordMeta = record.state === "record" ? { meta: record.meta } : {};
429
+ const session = liveness.running === true ? liveSession(home, recordMeta) : undefined;
430
+ let waitingOnYou = session ? session.waitingOnYou : null;
349
431
  if (waitingOnYou) {
350
432
  try { const s = instanceSessionTarget(home); if (!s.target) waitingOnYou = null; }
351
433
  catch { waitingOnYou = null; }
352
434
  }
353
- // `retire` is only ever the value read above, and `background`, `pinned` and `sameWork` the home's own
435
+ // `retire` is only ever the value read above, and `background`, `pinned`, `relatedWork` and `board` the home's own
354
436
  // records (below): a record that carries any of them (hand-edited, or copied from a row) never stands in
355
- // for it.
356
- const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, sameWork: _recordedSameWork, ...recorded } = meta;
437
+ // for it. Nor does a `sameWork` key, the flag's old name (below).
438
+ const { retire: _recordedRetire, background: _recordedBackground, pinned: _recordedPinned, relatedWork: _recordedRelatedWork, sameWork: _recordedSameWork, board: _recordedBoard, ...recorded } = meta;
357
439
  // `spawnedBy` (feature spawn-attribution) is the record's own, read in place by its rule (lib/spawned-by.mjs):
358
440
  // a malformed one is null, and a home spawned before the feature has no key.
359
441
  if (Object.hasOwn(recorded, "spawnedBy")) recorded.spawnedBy = readSpawnedBy(recorded.spawnedBy);
360
442
  // Feature session-resume: how the last session of a launched home that does not run ended
361
443
  // (lib/session-end.mjs): lost, stopped or exited. Absent while it runs or reads unknown, for a
362
444
  // home never launched, and for one being set up, retired or quarantined.
363
- const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? sessionEndOf(home, meta) : null;
445
+ // A home on a session provider reads it from its receipt (providerRow): `lost` for one stopped
446
+ // with the host, which a resume brings back, `stopped` for one an operator stopped; a session
447
+ // OATS did not stop has none.
448
+ const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? (provided ? provided.fields.sessionEnd ?? null : sessionEndOf(home, meta)) : null;
364
449
  // Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
365
450
  // null, after the record so that nothing in instance.json stands in for it.
366
451
  // Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
367
452
  // otherwise, never false.
368
- // Feature instance-same-work: `sameWork: true` only while the home's flag is bound to the parent
369
- // its readable record names (lib/instance-same-work.mjs sameWorkOf); absent otherwise, never false.
370
- const sameWork = record.state === "record" && sameWorkOf(home, meta.parentInstance);
371
- return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(sameWork ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
453
+ // Feature instance-related-work: `relatedWork: true` only while the home's flag is bound to the relation
454
+ // its record still has (lib/instance-related-work.mjs relatedWorkHeld); absent otherwise, never false.
455
+ // Feature instance-same-work, the compatibility layer: `sameWork: true` beside it for a parent binding
456
+ // only, as an older client reads it; absent otherwise.
457
+ const related = record.state === "record" ? relatedWorkHeld(home, meta) : null;
458
+ // Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
459
+ // file: its facts, and the questions of its current session, by the same read of the log as the claim.
460
+ const board = readBoardRow(home, { session, ...recordMeta });
461
+ // `backend`: `tmux` for a home on the kernel's own backend, a session provider's name otherwise
462
+ // (liveness carries it, with `session`); absent for a home whose record cannot be read and
463
+ // for one opened in Herdr, whose record says what it says.
464
+ const row = { ...recorded, ...claims, home, instance: e.name, ...(record.state === "record" && !herdr && !provided ? { backend: "tmux" } : {}), ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
465
+ if (provided?.ask && askProviders) providerAsks.push({ row, home, ...provided.ask, mayEnd: meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending });
466
+ else if (provided?.ask) row.runtimeError = "its session provider was not asked (a listing that asks no provider)";
467
+ return row;
372
468
 
373
469
  });
374
470
  };
@@ -393,6 +489,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
393
489
  out.push({ name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir, instances, ...(retireFailures.length ? { retireFailures } : {}) });
394
490
  seen.add(name);
395
491
  }
492
+ if (providerAsks.length) answerProviderRows(providerAsks, io);
396
493
  // Feature session-resume: what this local listing saw of each home's session, for the sweep
397
494
  // (lib/session-seen.mjs). It never changes the listing, and never throws or prints.
398
495
  recordSeen(root, out.flatMap((a) => a.instances || []));