@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
@@ -47,6 +47,22 @@
47
47
  * bypasses the crash ceiling without spending or clearing the carried budget. A blocked or
48
48
  * failed restore keeps its failure accounting, and eligibility checks still hold.
49
49
  * Without a boot id (neither Linux nor macOS) nothing is noted or counted: each sweep tries again.
50
+ * - A home on a session provider (lib/session-providers.mjs; its row carries `session`) is swept by
51
+ * its own rules, locally, and its rows carry `backend`. Its loss is the kernel's own record or
52
+ * its provider's answer, so it needs no sighting, and its bound is the home's resume cap
53
+ * (lib/provider-resume.mjs), never the note's:
54
+ * - `sessionEnd: lost`: stopped with the host (`oats host run`'s shutdown, on the stop
55
+ * receipt), or its session gone while OATS did not stop it (a provider reads one in error
56
+ * so). Both are started with `session start --resume`, which sends the resume notice
57
+ * through the provider's input: the agent continues in its own conversation. A stop with
58
+ * the host is not counted; a lost session is counted against the home's cap by the start
59
+ * itself, before the provider's input, and at the cap the row is `refused`,
60
+ * `keeps-getting-lost`;
61
+ * - stopped by an operator, never launched: no row, as for tmux;
62
+ * - its session there, whatever its state word: `already-running` (also one whose provider
63
+ * cannot tell an idle session from a settled one: nothing is resumed over a session that
64
+ * is there);
65
+ * - not readable: `skipped`, `unknown`.
50
66
  * The lock and the note are kernel-private, not a contract. `plan` predicts from the note, starting
51
67
  * nothing, taking no lock and writing no note. */
52
68
  import { hostRunAdmissionOpen, hostRunChildArgs } from "./host-run-admission.mjs";
@@ -62,16 +78,18 @@ import { FRESH_REASON, NOT_SWEPT, OUTCOME, RESUME_WAITING, ROW_REASON, SESSION_E
62
78
  import { bootId, homeKey, judgeLosses, readSeen, recordSeen, resumeEligible, resumeStateDir, sameBoot, takenInAnotherBoot } from "./session-seen.mjs";
63
79
  import { isAgentScopeWarning } from "./tmux-server-scope.mjs";
64
80
  import { hostStoppedAt as readHostStoppedAt } from "./session-end.mjs";
81
+ import { RESUME_LIMIT, RESUME_WINDOW_MS, providerResumes } from "./provider-resume.mjs";
82
+ import { isProviderRow } from "./session-providers.mjs";
83
+ import { instanceSessionTarget } from "./session-inspect.mjs";
65
84
 
66
85
  export { bootId, resumeStateDir };
67
86
 
68
87
  export const RESUME_SCHEMA = 1;
69
88
  /** At most this many starts run at once. */
70
89
  export const RESUME_CONCURRENCY = 4;
71
- /** At most this many sweep starts of one home in RESUME_WINDOW_MS. */
72
- export const RESUME_LIMIT = 3;
73
- /** The span over which a home's sweep starts are counted. */
74
- export const RESUME_WINDOW_MS = 60 * 60_000;
90
+ /** At most this many sweep starts of one home in RESUME_WINDOW_MS (lib/provider-resume.mjs holds
91
+ * the two numbers: a provider home's resume cap is the same bound). */
92
+ export { RESUME_LIMIT, RESUME_WINDOW_MS };
75
93
  /** A home that uses up its starts in this many hours in a row is not started by a sweep again. */
76
94
  export const RESUME_SPENT_HOURS = 3;
77
95
  /** How long after a refused start a sweep tries it again: this after the first refusal, doubled at
@@ -205,7 +223,7 @@ function sweptDeployments(deployment) {
205
223
  }
206
224
 
207
225
  /** One deployment: its entry for `deployments[]` and, when it is swept, its homes' rows to act on. */
208
- function readDeployment(dir) {
226
+ function readDeployment(dir, { askProviders = true } = {}) {
209
227
  const state = deploymentState(dir);
210
228
  if (state !== "ok") return { entry: { deployment: dir, state, swept: false, reason: NOT_SWEPT.NOT_OK } };
211
229
  let rows;
@@ -213,7 +231,7 @@ function readDeployment(dir) {
213
231
  // The status rows `oats status --dir <deployment> --json` lists (listInstances), from the
214
232
  // deployment's own instance root.
215
233
  const root = join(dir, "agents");
216
- rows = existsSync(root) ? listInstances(root).flatMap((a) => (a.instances || []).map((i) => ({ deployment: dir, ...i }))) : [];
234
+ rows = existsSync(root) ? listInstances(root, undefined, undefined, { askProviders }).flatMap((a) => (a.instances || []).map((i) => ({ deployment: dir, ...i }))) : [];
217
235
  } catch (e) {
218
236
  return { entry: { deployment: dir, state, swept: false, reason: NOT_SWEPT.UNREADABLE, code: typeof e?.code === "string" && e.code.startsWith("E_") ? e.code : "E_RESUME_UNREADABLE", message: String(e?.message ?? e) } };
219
237
  }
@@ -301,18 +319,31 @@ async function inBatches(items, limit, fn, stop = () => false) {
301
319
  * `warnings`, only when there is one, holds each distinct host-wide warning of its starts once. `kernel`:
302
320
  * `{ execPath, bin }`, how a start is run; `env` the environment each start gets. `start` (tests):
303
321
  * row → Promise of the start's JSON answer, in place of the child process. */
304
- export async function resumeSessions({ deployment, plan = false, kernel, env = process.env, boot = bootId(), start = (row) => runStart({ ...kernel, env }, row) } = {}) {
322
+ export async function resumeSessions({ deployment, plan = false, askProviders = true, kernel, env = process.env, boot = bootId(), start = (row) => runStart({ ...kernel, env }, row) } = {}) {
323
+ // `askProviders: false` (a plan only: `--plan --without-provider-inspect`, what `oats host run`
324
+ // lists with at shutdown): no session provider is asked, so the plan depends on none of them. A
325
+ // provider home OATS has not stopped is then `skipped`, `unknown`, with its `backend`.
326
+ if (!askProviders && !plan) throw oatsError("E_BAD_ARGS", "--without-provider-inspect goes with --plan: a sweep that asks no session provider could not tell which sessions were lost; nothing was started");
305
327
  const release = plan ? null : acquireResumeLock({ boot });
306
328
  try {
307
329
  const deployments = [], candidates = [], rows = [], seen = new Map();
308
330
  for (const dir of sweptDeployments(deployment)) {
309
- const { entry, rows: found } = readDeployment(dir);
331
+ const { entry, rows: found } = readDeployment(dir, { askProviders });
310
332
  deployments.push(entry);
311
333
  // What the kernel has seen of each home (lib/session-seen.mjs), read after the deployment's own
312
334
  // listing recorded what it saw now.
313
335
  const { homes } = found ? readSeen(join(dir, "agents")) : { homes: {} };
314
336
  for (const [home, record] of Object.entries(homes)) seen.set(home, record);
315
337
  for (const row of found ?? []) {
338
+ if (isProviderRow(row)) {
339
+ const tag = { backend: row.backend };
340
+ // A session that is there, whatever its state word (`unknown`, or `shell`), has a row: nothing
341
+ // is resumed over it, and `oats host run` stops every provider home that has one.
342
+ if (row.runtimeState === "unreachable") rows.push({ ...base(row), ...tag, outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN });
343
+ else if (row.runtimeState === "unknown" || row.runtimeState === "shell") rows.push({ ...base(row), ...tag, outcome: OUTCOME.ALREADY_RUNNING });
344
+ else if (row.sessionEnd === SESSION_END.LOST) candidates.push({ ...row, providerResume: true });
345
+ continue;
346
+ }
316
347
  if (row.running === true) rows.push({ ...base(row), outcome: OUTCOME.ALREADY_RUNNING });
317
348
  else if (row.running === null) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.UNKNOWN });
318
349
  // A launched home that is owed a self-retire reads no sessionEnd (its marker withholds it):
@@ -333,15 +364,19 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
333
364
  const startId = row.startId ?? null, key = homeKey(row.home);
334
365
  const prior = note.refused.find((r) => r.home === key && (r.startId ?? null) === startId);
335
366
  const record = seen.get(key), at = readHostStoppedAt(row.home, row, { now });
336
- const hostStoppedAt = at !== null && at <= Date.parse(record?.firstNotRunningAt) ? at : null;
337
- const fit = resumeEligible(record, row, { now, hostStoppedAt });
367
+ // A session provider's home: the kernel's own receipt says it was stopped with the host, or its
368
+ // provider that its session is gone. Neither needs a sighting; its bound is the home's own
369
+ // resume cap, which the start counts (lib/provider-resume.mjs), never this note's.
370
+ const provided = row.providerResume !== undefined, tag = provided ? { backend: row.backend } : {};
371
+ const hostStoppedAt = provided ? now : at !== null && at <= Date.parse(record?.firstNotRunningAt) ? at : null;
372
+ const fit = provided ? { eligible: true } : resumeEligible(record, row, { now, hostStoppedAt });
338
373
  const busy = lifecycleBusy(row);
339
374
  // A recorded stop of this start with the host is administrative, not another crash.
340
375
  // Keep the crash budget, but neither charge a successful restore nor let it prevent one.
341
376
  if (hostStoppedAt !== null) hostStopped.add(key);
342
- if (busy) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, message: busy });
377
+ if (busy) rows.push({ ...base(row), ...tag, outcome: OUTCOME.SKIPPED, reason: ROW_REASON.LIFECYCLE_BUSY, message: busy });
343
378
  else if (!fit.eligible) rows.push({ ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_SEEN_RECENTLY, message: `${row.instance} is not resumed automatically: ${fit.why}; start it by hand (oats session start --resume --home ${row.home}) if it should run` });
344
- else if (prior && now < retryDueAt(prior)) rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED_RETRYING, code: prior.code, message: prior.message, nextAttemptAt: iso(retryDueAt(prior)) });
379
+ else if (prior && now < retryDueAt(prior)) rows.push({ ...base(row), ...tag, outcome: OUTCOME.REFUSED, reason: ROW_REASON.START_REFUSED_RETRYING, code: prior.code, message: prior.message, nextAttemptAt: iso(retryDueAt(prior)) });
345
380
  else if (!hostStopped.has(key) && inWindow(note.starts[key], now).length >= RESUME_LIMIT) {
346
381
  const counted = inWindow(note.starts[key], now), again = iso(Date.parse(counted[0]) + RESUME_WINDOW_MS);
347
382
  const hour = spentHours(note.spent[key], counted[0]);
@@ -352,6 +387,19 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
352
387
  rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.KEEPS_GETTING_LOST, message: `${row.instance} was resumed ${counted.length} times an hour for ${hour.hours} hours in a row and was lost again each time; no sweep starts it again: ${by}` });
353
388
  } else rows.push({ ...base(row), outcome: OUTCOME.REFUSED, reason: ROW_REASON.KEEPS_GETTING_LOST, nextAttemptAt: again, message: `${row.instance} was resumed ${counted.length} times in the last hour and was lost again each time; a sweep starts it again after ${again}, or ${by}` });
354
389
  }
390
+ else if (plan && provided) {
391
+ // A provider home's resume is counted by its start (lib/provider-resume.mjs), by inputs too:
392
+ // the plan reads that count, so that it predicts the refusal the apply would answer. A home
393
+ // stopped with the host (`at`: its stop receipt says so) is resumed outside the cap.
394
+ // (Stopped with the host only while its receipt still says stopped: a stop receipt left by
395
+ // a resume that died after it cleared the stop does not make a later loss a host's stop.)
396
+ let stoppedByOats = false;
397
+ try { stoppedByOats = (instanceSessionTarget(row.home).session?.stoppedAt ?? null) !== null; } catch { /* unreadable: counted as a loss */ }
398
+ const cap = at !== null && stoppedByOats ? null : providerResumes(row.home, { boot, now });
399
+ rows.push(cap && cap.count >= cap.limit
400
+ ? { ...base(row), ...tag, outcome: OUTCOME.REFUSED, reason: ROW_REASON.KEEPS_GETTING_LOST, code: "E_SESSION_NOT_RUNNING", nextAttemptAt: cap.nextAttemptAt, message: `${row.instance} lost its session and was resumed ${cap.count} times in the last hour, and was lost again each time: it is not resumed again before ${cap.nextAttemptAt}` }
401
+ : { ...base(row), ...tag, outcome: OUTCOME.RESUMED });
402
+ }
355
403
  else if (plan) rows.push(predicted(row, env));
356
404
  else { toStart.push(row); if (prior) refusedBefore.set(key, prior); }
357
405
  }
@@ -373,7 +421,11 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
373
421
  // sweep tries it again; the row says when.
374
422
  const refusal = { home: key, startId: row.startId ?? null, at: iso(Date.now()), attempts: (refusedBefore.get(key)?.attempts ?? 0) + 1 };
375
423
  const from = gone ? { ...base(row), outcome: OUTCOME.SKIPPED, reason: ROW_REASON.NOT_LOST, ...(typeof answer?.error?.code === "string" ? { code: answer.error.code } : {}) } : rowFromStart(row, answer);
376
- const answered = from.outcome === OUTCOME.REFUSED && boot ? { ...from, nextAttemptAt: iso(retryDueAt(refusal)) } : from;
424
+ const provided = row.providerResume !== undefined;
425
+ // A provider home at its resume cap (the start refused it, E_SESSION_NOT_RUNNING with the
426
+ // cap's details) keeps getting lost, as a tmux home at the sweep's own bound does.
427
+ const capped = provided && from.outcome === OUTCOME.REFUSED && from.code === "E_SESSION_NOT_RUNNING" ? { reason: ROW_REASON.KEEPS_GETTING_LOST } : {};
428
+ const answered = { ...(from.outcome === OUTCOME.REFUSED && boot ? { ...from, nextAttemptAt: iso(retryDueAt(refusal)) } : from), ...capped, ...(provided ? { backend: row.backend } : {}) };
377
429
  try {
378
430
  noteSweep({
379
431
  refusals: answered.outcome === OUTCOME.REFUSED ? [{ ...refusal, code: answered.code, message: answered.message }] : [],
@@ -387,7 +439,8 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
387
439
  // resumes a judged loss (a status read never uses one up). A plan judges nothing. Judge the
388
440
  // lost start before recording its replacement: a new start resets the record and its judgement.
389
441
  if (!plan) {
390
- const lost = new Set(candidates.map((c) => c.home)), byDeployment = new Map();
442
+ // A session provider's home has no sighting record to judge: its receipt is its record.
443
+ const lost = new Set(candidates.filter((c) => c.providerResume === undefined).map((c) => c.home)), byDeployment = new Map();
391
444
  for (const r of rows) if (lost.has(r.home) && (!NOT_JUDGED.has(r.reason) || givenUp.has(r.home))) byDeployment.set(r.deployment, [...(byDeployment.get(r.deployment) ?? []), { home: r.home, startId: candidates.find((c) => c.home === r.home).startId ?? null, outcome: r.outcome }]);
392
445
  for (const [dir, judged] of byDeployment) judgeLosses(join(dir, "agents"), judged, { boot });
393
446
  }
@@ -395,7 +448,7 @@ export async function resumeSessions({ deployment, plan = false, kernel, env = p
395
448
  // a home lost again before the next listing would have no record for its start: no later
396
449
  // sweep would resume it, and its starts would never be counted.
397
450
  const launchedIn = new Map();
398
- for (const r of started) if (r.outcome === OUTCOME.RESUMED || r.outcome === OUTCOME.FRESH) launchedIn.set(r.deployment, (launchedIn.get(r.deployment) ?? new Set()).add(r.home));
451
+ for (const r of started) if ((r.outcome === OUTCOME.RESUMED || r.outcome === OUTCOME.FRESH) && r.backend === undefined) launchedIn.set(r.deployment, (launchedIn.get(r.deployment) ?? new Set()).add(r.home));
399
452
  for (const [dir, homes] of launchedIn) {
400
453
  const root = join(dir, "agents");
401
454
  try { recordSeen(root, listInstances(root).flatMap((a) => a.instances || []).map((i) => (homes.has(i.home) ? { ...i, running: true } : i)), { boot }); } catch { /* the next listing records it */ }
@@ -60,3 +60,6 @@ export function kernelNode() {
60
60
  }
61
61
  return kernel.answer;
62
62
  }
63
+ /** Forget the answer kept for this process's node (lib/read-call.mjs READ_STATE): a process that
64
+ * answers many reads computes it again for each. */
65
+ export function resetKernelNode() { kernel = null; }
package/lib/triggers.mjs CHANGED
@@ -43,6 +43,7 @@ import { fileURLToPath } from "node:url";
43
43
  import { readDefinitions, writeDefinitions, stateDir, withScopeLock, childEnv, parseEnvelopeText, schedulerStatus, readRegistry, definitionsPath, runWarnings } from "./schedule.mjs";
44
44
  import { herdrSettingRemoved } from "./errors.mjs";
45
45
  import { MODEL_RE, SNAPSHOT_MAX_AGE_MS, automationError, baseRow, localEntry, localId, parseOwner, qualifiedId, soulOriginOf, validateDescription } from "./automations.mjs";
46
+ import { SESSION_PROVIDER_NAME_RE } from "./kernel-features.mjs";
46
47
  import { judgeAnswer, pollFailure, triggerSourcesOf } from "./trigger-sources.mjs";
47
48
  import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
48
49
  import { lockedPackageRef } from "./packages.mjs";
@@ -207,7 +208,8 @@ export function validateTrigger(def, { backendSource = "the trigger's spawn.back
207
208
  if (sp.model !== undefined && (typeof sp.model !== "string" || !MODEL_RE.test(sp.model))) throw invalid("spawn.model", "a model id: a letter or digit, then letters, digits and . _ : / @ + - [ ] (at most 128 characters)");
208
209
  if (sp.yolo !== undefined && typeof sp.yolo !== "boolean") throw invalid("spawn.yolo", "boolean");
209
210
  if (sp.backend === "herdr") throw Object.assign(herdrSettingRemoved(`${backendSource}: herdr`), { field: "spawn.backend", details: { field: "spawn.backend" } });
210
- if (sp.backend !== undefined && sp.backend !== "tmux") throw invalid("spawn.backend", "tmux");
211
+ // tmux, or a session provider of the soul's capabilities: a name here, resolved by the spawn.
212
+ if (sp.backend !== undefined && (typeof sp.backend !== "string" || !SESSION_PROVIDER_NAME_RE.test(sp.backend))) throw invalid("spawn.backend", "tmux, or a session provider's name (1 to 40 lowercase letters, digits and dashes)");
211
213
  const cc = def.concurrency === undefined ? {} : def.concurrency;
212
214
  if (!isObject(cc)) throw invalid("concurrency", "{ max?, perKey? }");
213
215
  onlyKeys(cc, ["max", "perKey"], "concurrency.");
@@ -3,12 +3,12 @@
3
3
  "packages": {
4
4
  "oats.okf": {
5
5
  "url": "https://github.com/awebai/oats-okf.git",
6
- "ref": "v6.2.0",
6
+ "ref": "v6.3.0",
7
7
  "path": "oats-package"
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.45.0",
11
+ "ref": "v1.47.0",
12
12
  "path": "oats-package"
13
13
  },
14
14
  "oats.jira": {
@@ -48,7 +48,7 @@
48
48
  },
49
49
  "oats.framework": {
50
50
  "url": "https://github.com/awebai/oats.git",
51
- "ref": "oats-framework/v1.26.0",
51
+ "ref": "oats-framework/v1.28.0",
52
52
  "path": "oats-package"
53
53
  }
54
54
  },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@awebai/oats",
3
- "version": "0.69.22",
3
+ "version": "0.69.24",
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",
@@ -19,6 +19,7 @@
19
19
  "scripts": {
20
20
  "test": "node scripts/run-tests.mjs",
21
21
  "test:session": "node scripts/test-session-inheritance.mjs",
22
+ "test:provider-lifecycle": "node scripts/test-provider-lifecycle.mjs",
22
23
  "check": "node scripts/check-package-dry-runs.mjs --syntax-only",
23
24
  "check:pi": "node --experimental-strip-types --check packages/pi/extension/index.ts",
24
25
  "validate": "node scripts/validate-project.mjs",
@@ -67,3 +67,24 @@ export function defaultsSummary(status, rows) {
67
67
  const unlisted = [...slots.filter(([, value]) => value).map(([, value]) => value), ...caps].filter(entry => !listed(entry)).map(entry => ({ name: entry.name, off: entry.off === true }));
68
68
  return { empty: !filled.size && !caps.length, emptySlots: CORE_LAYERS.filter(layer => !filled.has(layer)), unlisted };
69
69
  }
70
+
71
+ /** The Workspace defaults section (slice 2b, Amendment 1, D: Pepe, 2026-11-20, "el list de capabilities m'agradaven mes
72
+ * com avans que et deia quins son els defaults del workspace"), above the flat list, never narrowed by a search: null
73
+ * when the kernel reports no `defaults` (no claim). `core`: each core slot in CORE_LAYERS order, `{ layer, entries,
74
+ * unlisted }`, the listed rows that fill it by default (two: the workspace's own conflict, both shown), and `unlisted`:
75
+ * the name the slot's declared default has when no row matches it (it is said, never dropped), else null. No entries
76
+ * and no unlisted name: the slot has no default. `additional`: every other listed default, on or turned off (`default` says which), in the list's order.
77
+ * Entries are capabilityList's, so a row draws as it does in the list. A declared default no row matches is
78
+ * defaultsSummary's `unlisted`, said in words, not as a row. */
79
+ export function workspaceDefaultsSections(rows, status) {
80
+ if (!record(status?.defaults)) return null;
81
+ const entries = capabilityList(rows, status).filter(entry => entry.default);
82
+ const on = entries.filter(entry => entry.default === 'on');
83
+ return {
84
+ core: CORE_LAYERS.map(layer => {
85
+ const filled = on.filter(entry => entry.core === layer), slot = record(status.defaults.slots) ? status.defaults.slots[layer] : null;
86
+ return { layer, entries: filled, unlisted: !filled.length && record(slot) && text(slot.name) ? slot.name : null };
87
+ }),
88
+ additional: entries.filter(entry => !(entry.default === 'on' && entry.core)),
89
+ };
90
+ }
@@ -33,6 +33,8 @@ import { MACHINE_ID, machineFieldProblem } from './machine-contract.mjs';
33
33
  import { kernelMade } from './kernel-made.mjs';
34
34
  import { SOUL_COLORS } from './soul-colors.mjs';
35
35
  import { NAMING_TIMEOUT_MS } from './spawn-preview-contract.mjs';
36
+ import { listedBackends } from './session-backends.mjs';
37
+ import { sessionProviderName } from './instance-presentation.mjs';
36
38
 
37
39
  const ENVELOPE_TIMEOUT_MS = 60_000;
38
40
 
@@ -64,7 +66,10 @@ const SPAWN_ARG_RULES = {
64
66
  name: { flag: "--name", re: /^[a-z0-9][a-z0-9-]*$/ },
65
67
  repo: { flag: "--repo", re: /^[^-][^\0]*$/ }, // path — anything not option-shaped
66
68
  work: { flag: "--work", re: /^(worktree|checkout|attached|workspace|directory)$/ },
67
- backend: { flag: "--backend", re: /^tmux$/ },
69
+ // A session backend's name: the kernel's own ("tmux") or a session provider's (instance-presentation.mjs
70
+ // `sessionProviderName`: 1 to 40 lowercase letters, digits and dashes, never option-shaped, never a reserved
71
+ // word), and only one the kernel lists (`backendsListed`, below).
72
+ backend: { flag: "--backend", re: { test: (value) => value === "tmux" || sessionProviderName(value) } },
68
73
  // The flag is the kernel's (harness-names.mjs harnessFlag): the caller names it, never guessed.
69
74
  harness: { flag: null, re: /^(pi|claude|codex)$/ },
70
75
  // A configuration's name, or the word that selects none (launch-contract.mjs LAUNCH_CONFIG_NONE), which this rule admits.
@@ -81,6 +86,12 @@ const SPAWN_ARG_RULES = {
81
86
  // the pair when it spawns related — path-shaped, never option-shaped.
82
87
  relativeRoot: { flag: "--relative-root", re: /^[^-][^\0]*$/ },
83
88
  };
89
+ /** The session backends a spawn may name: the caller's `backends`, the names the kernel lists (`oats version
90
+ * --json` `sessionBackends`, the kernel's own, and `oats inspect --json` `sessionProviders`, the ones a soul's
91
+ * capabilities supply). With no list, "tmux" alone, as before session providers. Never "herdr": OATS removed it. */
92
+ const backendsListed = (backends) => (Array.isArray(backends) ? listedBackends(backends) : ["tmux"]);
93
+
94
+ /** `opts.backends` is not an argument: it is the list `opts.backend` is held to (`backendsListed`). */
84
95
  export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
85
96
  const agentName = String(agent);
86
97
  if (agentName.startsWith("-")) { const e = new Error(`invalid agent name "${agentName}"`); e.code = "E_BAD_ARGS"; throw e; }
@@ -117,7 +128,7 @@ export function spawnArgv(agent, workspaceDir, taskFile, opts = {}) {
117
128
  const v = opts[key];
118
129
  if (v === undefined || v === null || v === "") continue;
119
130
  const s = String(v);
120
- if (!rule.re.test(s)) { const e = new Error(`invalid ${key} value`); e.code = "E_BAD_ARGS"; throw e; }
131
+ if (!rule.re.test(s) || (key === "backend" && !backendsListed(opts.backends).includes(s))) { const e = new Error(`invalid ${key} value`); e.code = "E_BAD_ARGS"; throw e; }
121
132
  argv.push(key === "harness" ? flagFor(opts.harnessFlag) : rule.flag, s);
122
133
  }
123
134
  if (opts.yolo !== undefined) {
@@ -697,7 +708,7 @@ export async function cliInstancePin(bin, args, io = {}) {
697
708
 
698
709
  /** `maxAge` (feature observe-max-age) is inspect's alone; `features` is the probe's list and
699
710
  * gates the flags (also `instructions`, `skills` and `composedSkills`), so an undeclared kernel gets the flagless argv even when a value is given. */
700
- export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, composedSkills = false, features }, io = {}) {
711
+ export async function cliCapability(bin, { action, context, server, soul, agentsRoot, home, operation, args, localCwd, maxAge, instructions = false, skills = false, composedSkills = false, board = false, features }, io = {}) {
701
712
  const bad = message => { throw Object.assign(new Error(message), { code: 'E_BAD_ARGS' }); };
702
713
  const value = (v, label) => {
703
714
  if (typeof v !== 'string' || !v || v.startsWith('-') || v.includes('\0')) bad(`Invalid ${label}`);
@@ -735,7 +746,11 @@ export async function cliCapability(bin, { action, context, server, soul, agents
735
746
  // inspect --soul only, gated the same way; routed, only for a host whose roster row names it (hostComposesSkills).
736
747
  if (composedSkills && (action !== 'inspect' || !soul || home)) bad('Composed skills belong to a soul inspection');
737
748
  const composedSkillsArgv = composedSkills && Array.isArray(features) && features.includes('soul-composed-skills') ? ['--composed-skills'] : [];
738
- return await runJson(bin, [...argv, ...target, ...composed, ...skillsArgv, ...composedSkillsArgv, ...maxAgeArgv(features, maxAge), '--json'], {
749
+ // --board (feature instance-board) adds the agent's board with each fact's history and each question's context:
750
+ // inspect --home only, gated the same way; routed, only for a host whose roster row names it (inspect-boundary.mjs).
751
+ if (board && (action !== 'inspect' || !home || soul)) bad('The board belongs to a home inspection');
752
+ const boardArgv = board && Array.isArray(features) && features.includes('instance-board') ? ['--board'] : [];
753
+ return await runJson(bin, [...argv, ...target, ...composed, ...skillsArgv, ...composedSkillsArgv, ...boardArgv, ...maxAgeArgv(features, maxAge), '--json'], {
739
754
  cwd: localCwd, exec: io.exec, timeout: io.timeout ?? (action === 'run' ? 300_000 : ENVELOPE_TIMEOUT_MS),
740
755
  // The skills' text makes the answer larger than any other read: an allowance of its own, still bounded.
741
756
  maxBuffer: skillsArgv.length || composedSkillsArgv.length ? SKILLS_INSPECT_MAX_BUFFER : ENVELOPE_MAX_BUFFER,
@@ -253,7 +253,11 @@ export async function discover(io, probe) {
253
253
  } catch (e) {
254
254
  // Probe REJECTED (nonzero exit, timeout, spawn failure) — the
255
255
  // candidate is out even if it printed a plausible payload first.
256
- tried.push({ path, source: src.source, reason: `probe failed: ${String(e.message || e).slice(0, 120)}` });
256
+ const failure = parseProbeStdout(e.stdout);
257
+ // Candidate stdout reaches the CLI status payload and change comparison; bound it.
258
+ const reason = failure?.schemaVersion === 1 && failure.ok === false && typeof failure.error?.message === "string"
259
+ ? failure.error.message.slice(0, 200) : `probe failed: ${String(e.message || e).slice(0, 120)}`;
260
+ tried.push({ path, source: src.source, reason });
257
261
  continue;
258
262
  }
259
263
  const a = acceptProbe(payload, io.testedVersion);
@@ -10,7 +10,8 @@ import { readIdentity } from './workspace-views.mjs';
10
10
  import { waitingOnYouData } from './waiting-on-you.mjs';
11
11
  import { attributedHumanData } from './attributed-human.mjs';
12
12
  import { retireData } from './retire-state.mjs';
13
- import { instanceColor } from './instance-presentation.mjs';
13
+ import { instanceColor, openLink, sessionThreadId } from './instance-presentation.mjs';
14
+ import { boardData } from './instance-board.mjs';
14
15
  const text = value => typeof value === 'string' && value.length <= 8192 && !value.includes('\0');
15
16
  const absolute = value => text(value) && isAbsolute(value) && resolve(value) === value;
16
17
  const own = (value, key) => Object.hasOwn(value, key);
@@ -215,6 +216,24 @@ export function deploymentStatusData(document, deployment) {
215
216
  }
216
217
  if (own(instance, 'tmux')) row.tmux = instance.tmux === null ? null : fields(instance.tmux, ['session', 'window', 'socket']);
217
218
  if (own(instance, 'sessionTarget')) row.sessionTarget = sessionTarget(instance.sessionTarget);
219
+ // Session providers (feature session-providers): where the instance runs, when it is not tmux's. Validated,
220
+ // never check()ed: `backend` is kept when it is text that is not empty (instance-presentation.mjs `sessionProvider` reads it:
221
+ // "tmux", or anything else, which is a provider's and never asked of tmux), else dropped, and the row reads
222
+ // as one with none (a tmux row). "herdr" is not kept: a Herdr-recorded row of this machine is known by its
223
+ // `sessionTarget` or its `runtimeState`, as before session providers, and a row that only names the backend
224
+ // reads as it always did. Of `session` the
225
+ // row keeps the provider's capability and, on this machine's rows, the thread id (`session.threadId`), both
226
+ // for display only; of `open` the link a client may show in place of a terminal (`openLink`: an http(s) url).
227
+ // A value this reader's text check refuses (over-long, or with a NUL) is not carried, and still is no tmux's:
228
+ // the row then names the contract's reserved word for any provider, which is never a provider's name.
229
+ if (own(instance, 'backend') && typeof instance.backend === 'string' && instance.backend.length > 0 && instance.backend !== 'herdr')
230
+ row.backend = text(instance.backend) ? instance.backend : 'session-provider';
231
+ if (own(instance, 'session') && record(instance.session)) {
232
+ const provider = instance.session.provider, threadId = sessionThreadId(instance);
233
+ const session = { ...(text(provider) && provider.length > 0 && provider.length <= 200 ? { provider } : {}), ...(threadId !== null ? { threadId } : {}) };
234
+ if (Object.keys(session).length) row.session = session;
235
+ }
236
+ if (own(instance, 'open')) { const link = openLink(instance); if (link !== null) row.open = link; }
218
237
  if (own(instance, 'retirePending')) row.retirePending = true;
219
238
  // #1247 (feature status-retire-state): the retire that runs, or failed, or was interrupted. Validated, never
220
239
  // check()ed: a value out of the contract is dropped and the row reads as if it had none.
@@ -236,9 +255,14 @@ export function deploymentStatusData(document, deployment) {
236
255
  // Session resume: how the instance's last session ended, one of SESSION_ENDS exactly. Any other value is
237
256
  // dropped, never checked: the row reads as one that did not say.
238
257
  if (own(instance, 'sessionEnd') && SESSION_END_VALUES.includes(instance.sessionEnd)) row.sessionEnd = instance.sessionEnd;
239
- // #1577 (feature instance-same-work): the child does its parent's work, so its parent line is drawn
240
- // (same-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
258
+ // Related work (features instance-related-work, and instance-same-work before it): the row's work is
259
+ // related to its parent's, or a top-level row's to its sibling's, so the line between them is drawn
260
+ // (related-work.mjs). Boolean true only; any other value is dropped, never checked: the row reads unflagged.
261
+ if (own(instance, 'relatedWork') && instance.relatedWork === true) row.relatedWork = true;
241
262
  if (own(instance, 'sameWork') && instance.sameWork === true) row.sameWork = true;
263
+ // Feature instance-board: the agent's facts and questions (instance-board.mjs). Validated, never check()ed: a
264
+ // malformed board reads as none (null), its malformed entries are left out. Absent stays absent.
265
+ if (own(instance, 'board')) row.board = boardData(instance.board);
242
266
  if (own(instance, 'modules')) row.modules = modules(instance.modules);
243
267
  if (own(instance, 'soul')) row.soul = soulSource(instance.soul);
244
268
  if (own(instance, 'workspace')) row.workspace = recordedWorkspace(instance.workspace);
@@ -14,10 +14,15 @@
14
14
  * test/inventory.test.mjs holds that its page reaches no module that imports a Node builtin. */
15
15
  import { dirname } from 'node:path';
16
16
  import { livenessOrigin } from './liveness.mjs';
17
- import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor } from './instance-presentation.mjs';
17
+ import { knownOrigin, hasRuntimeError, byRuntimeState, instanceColor, sessionProvider } from './instance-presentation.mjs';
18
18
  import { retireData } from './retire-state.mjs';
19
19
 
20
20
  const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
21
+ /** The `backend` a row of this machine carries on, or undefined: the row's own, but never "herdr". A Herdr-recorded
22
+ * row of this machine is known by its `sessionTarget` or its `runtimeState` (instance-presentation.mjs
23
+ * `unsupportedSession`), as before session providers; one that only names the backend reads as it always did.
24
+ * deployment-data.mjs already drops it from a kernel's row; this serves the rows that reach the panel another way. */
25
+ const localBackend = (row) => (row.backend === 'herdr' ? undefined : row.backend);
21
26
 
22
27
  /** One row per instance of a roster (deployment-data.mjs `deploymentStatusData`): the kernel's row,
23
28
  * with `agent`, `description` and `team` from its soul and `agentsRoot` from the roster, and `soulKey`, the
@@ -53,6 +58,9 @@ export function kernelLiveness(cli) {
53
58
  * `running` is the kernel's answer: the collector leaves a row it answered `null` as the kernel has it. */
54
59
  export function livenessInput(rows) {
55
60
  return rows.map((i) => ({ instance: i.instance, running: i.running, tmux: i.tmux, sessionTarget: i.sessionTarget,
61
+ // A row on a session provider is never probed (liveness.mjs): the collector knows it by its `backend`. Never
62
+ // "herdr": a Herdr-recorded row of this machine is known by its `sessionTarget` or its state, as before.
63
+ ...(localBackend(i) !== undefined ? { backend: localBackend(i) } : {}),
56
64
  runtimeState: i.runtimeState, runtimeError: i.runtimeError }));
57
65
  }
58
66
 
@@ -105,6 +113,13 @@ export function panelInstance(i) {
105
113
  // Who made that text: only beside a `runtimeError`, and only one of the three speakers.
106
114
  ...(hasRuntimeError(i) && knownOrigin(i.runtimeErrorOrigin) ? { runtimeErrorOrigin: i.runtimeErrorOrigin } : {}),
107
115
  tmux: i.tmux, git: null,
116
+ // Session providers: the row's backend ("tmux" or a provider's name), the provider's capability and thread
117
+ // id, and the link it offers in place of a terminal, each as deployment-data.mjs validated it; absent stays
118
+ // absent. instance-presentation.mjs `sessionProvider` and instance-acts.mjs `openAct` read them. "herdr" is no
119
+ // backend of a row of this machine (`localBackend`).
120
+ ...(localBackend(i) !== undefined ? { backend: localBackend(i) } : {}),
121
+ ...(i.session !== undefined ? { session: i.session } : {}),
122
+ ...(i.open !== undefined ? { open: i.open } : {}),
108
123
  // Workspace-model v2 facts exactly as `oats status --json` reported them:
109
124
  // module drift rows (or the recorded map when the workspace is
110
125
  // unreachable), the soul source and the served identity. Identity is
@@ -127,7 +142,8 @@ export function panelInstance(i) {
127
142
  // Session resume: how the last session ended, as deployment-data.mjs validated it (SESSION_ENDS); absent stays
128
143
  // absent. The resume trigger reads it (session-resume-trigger.mjs lostLocalHomes).
129
144
  ...(i.sessionEnd !== undefined ? { sessionEnd: i.sessionEnd } : {}),
130
- // #1577: the kernel's same-work flag (deployment-data.mjs keeps it as true only); same-work.mjs reads it.
145
+ // The kernel's related-work flags (deployment-data.mjs keeps each as true only); related-work.mjs reads them.
146
+ ...(i.relatedWork === true ? { relatedWork: true } : {}),
131
147
  ...(i.sameWork === true ? { sameWork: true } : {}),
132
148
  ...(i.captured ? { captured: true } : {}),
133
149
  // Needs input (PR K): the validated claim (or null, unknown) as status reported it; absent stays absent.
@@ -141,6 +157,8 @@ export function panelInstance(i) {
141
157
  ...(i.background === true ? { background: true } : {}),
142
158
  // Feature instance-pin: exactly true, else absent (instance-tree.mjs rowPinned).
143
159
  ...(i.pinned === true ? { pinned: true } : {}),
160
+ // Feature instance-board: the board deployment-data.mjs validated (instance-board.mjs), or null; absent stays absent.
161
+ ...(i.board !== undefined ? { board: i.board } : {}),
144
162
  team: i.team || null,
145
163
  };
146
164
  }
@@ -151,10 +169,15 @@ export function panelInstance(i) {
151
169
  *
152
170
  * The merged row's `runtimeErrorOrigin` is set here or removed, whatever the row carried: when the
153
171
  * answer holds the `runtimeError`, the answer's speaker; when the answer has none and the kernel's row
154
- * had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel". */
172
+ * had one (a probed row the kernel reported with a text), the text is the kernel's, so "kernel".
173
+ *
174
+ * A row on a session provider (instance-presentation.mjs `sessionProvider`) takes nothing from its answer: the
175
+ * collector knows nothing of it, so whatever it printed for the row, and the unknown answer written for every row
176
+ * when the collector failed (`livenessAnswers`), is left out. Its `running`, `runtimeState` and `runtimeError` are
177
+ * the kernel's, whole, and its text's speaker is the kernel. */
155
178
  export function panelInstances(rows, answers) {
156
179
  return rows.map((row, index) => {
157
- const answer = answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
180
+ const answer = sessionProvider(row) ? undefined : answers[index], { runtimeErrorOrigin: _carried, ...merged } = { ...row, ...answer };
158
181
  const origin = record(answer) && Object.hasOwn(answer, "runtimeError") ? answer.runtimeErrorOrigin : "kernel";
159
182
  return panelInstance(hasRuntimeError(merged) ? { ...merged, runtimeErrorOrigin: origin } : merged);
160
183
  }).sort(byRuntimeState);
@@ -1,44 +1,58 @@
1
- /** Home's board and its flat list of agents (Desktop UI rework, slice 2): the groupings both clients draw, so the
2
- * TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows as
3
- * the roster holds them; nothing here reorders the roster (needs-input-preserves-liveness-and-recognition: the
1
+ /** Home's board and its flat list of agents (Desktop UI rework, slices 2 and 2b): the groupings both clients draw,
2
+ * so the TUI can render the same Home later. Pure, no DOM, never throws. Rows are `oats status --json` instance rows
3
+ * as the roster holds them; nothing here reorders the roster (needs-input-preserves-liveness-and-recognition: the
4
4
  * urgency order lives on Home only).
5
5
  *
6
- * homeBoard(rows, { stale }) -> { needsYou: [{ row, claim }], running: [row] }
6
+ * homeBoard(rows, { stale, pins }) -> { needsYou: [{ row, claim }], running: [row], counts: { agents, running, needYou, stopped, unknown } }
7
7
  * needsYou: every row with a claim it may show (waiting-on-you.mjs `waitingClaim`, the one liveness gate,
8
8
  * `stale(row)` the roster's held-stale rule), newest claim first (its `since`), then the roster's
9
- * order. running: every other live row (`running === true`, no reported state but `running`, a
10
- * reached server), newest spawn first (instance-tree.mjs `rosterOrder`). There is no working/idle
9
+ * order.
10
+ * running: every other live row, in the roster's order (pinned first where `pins`, as homeAgents): Home shows
11
+ * the first few, cropped and expandable (slice 2b, Amendment 1: Pepe, 2026-11-20).
12
+ * counts: the summary line's numbers. agents: every row. needYou: the rows in needsYou. running: every other live row
13
+ * (`running === true`, no reported state but `running`, a reached server; a row on a session
14
+ * provider on `running === true` and a reached server alone). stopped: every other row
15
+ * that says `running: false`. unknown: the rest (no runtime fact, an unreached server, another
16
+ * reported state). Each row is counted once, so the four add up to agents. There is no working/idle
11
17
  * fact yet (the activity contract is not built), and none is inferred
12
- * (instance-activity-is-reported-not-inferred): a live row is "running". Stopped and unknown rows
13
- * aren't on the board (D11). The "New" group (stopped or finished since you last looked) has no
14
- * fact to read, so it isn't here.
15
- * homeAgents(rows) -> rows: every agent, running or stopped, in the roster's order (newest spawn first).
18
+ * (instance-activity-is-reported-not-inferred): a live row is "running".
19
+ * homeAgents(rows, { pins }) -> rows: every agent, running or stopped, in the roster's order: pinned rows first
20
+ * where the roster shows pins (`pins`: the CLI lists PIN_FEATURE; instance-tree.mjs `rowPinned`,
21
+ * #1974's shared order), then newest spawn first (`rosterOrder`).
16
22
  * startedBy(row) -> string | null: who started it, the row's attributed human (attributed-human.mjs), else
17
23
  * its parent's name (`parentInstance`), else null. */
18
24
  import { waitingClaim } from './waiting-on-you.mjs';
19
- import { rosterOrder } from './instance-tree.mjs';
25
+ import { rosterOrder, rowPinned } from './instance-tree.mjs';
20
26
  import { attributedHumanData } from './attributed-human.mjs';
21
27
  import { instanceDisplayName } from './instance-display-name.mjs';
28
+ import { sessionProvider } from './instance-presentation.mjs';
22
29
 
23
30
  const record = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
24
31
  const rowsOf = (rows) => (Array.isArray(rows) ? rows.filter((row) => record(row) && typeof row.instance === 'string' && row.instance) : []);
25
32
  const since = (claim) => { const t = Date.parse(claim.since); return Number.isFinite(t) ? t : -Infinity; };
26
- const live = (row) => row.running === true && row.serverUnreached !== true && (row.runtimeState == null || row.runtimeState === 'running');
33
+ // A row on a session provider is live on `running === true` alone: its `runtimeState` is the provider's word
34
+ // ("unknown" while it runs), never tmux's "running".
35
+ const live = (row) => row.running === true && row.serverUnreached !== true
36
+ && (row.runtimeState == null || row.runtimeState === 'running' || sessionProvider(row) !== null);
27
37
 
28
- export function homeBoard(rows, { stale = () => false } = {}) {
29
- const needsYou = [], running = [];
38
+ export function homeBoard(rows, { stale = () => false, pins = false } = {}) {
39
+ const needsYou = [], running = [], counts = { agents: 0, running: 0, needYou: 0, stopped: 0, unknown: 0 };
30
40
  for (const row of rowsOf(rows)) {
41
+ counts.agents++;
31
42
  const claim = waitingClaim(row, { stale: stale(row) === true });
32
43
  if (claim) needsYou.push({ row, claim });
33
- else if (live(row)) running.push(row);
44
+ else if (live(row)) { counts.running++; running.push(row); }
45
+ else if (row.running === false) counts.stopped++;
46
+ else counts.unknown++;
34
47
  }
35
48
  needsYou.sort((a, b) => since(b.claim) - since(a.claim) || rosterOrder(a.row, b.row));
36
- running.sort(rosterOrder);
37
- return { needsYou, running };
49
+ counts.needYou = needsYou.length;
50
+ return { needsYou, running: homeAgents(running, { pins }), counts };
38
51
  }
39
52
 
40
- export function homeAgents(rows) {
41
- return rowsOf(rows).sort(rosterOrder);
53
+ export function homeAgents(rows, { pins = false } = {}) {
54
+ const pinned = (row) => (rowPinned(row, pins) ? 1 : 0);
55
+ return rowsOf(rows).sort((a, b) => pinned(b) - pinned(a) || rosterOrder(a, b));
42
56
  }
43
57
 
44
58
  export function startedBy(row) {