@awebai/oats 0.69.23 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
@@ -0,0 +1,93 @@
1
+ /** A home's independent receipt (its retirement baseline, which is also its session receipt): where
2
+ * it is kept, outside the home, and how a home is told from another. A leaf, with nothing of the
3
+ * kernel above it, so that whatever must read a receipt can (lib/session-inspect.mjs reads a
4
+ * home's session by it; lib/home-integrity.mjs reads what a provider home may run). */
5
+ import { existsSync, lstatSync, readFileSync } from "node:fs";
6
+ import { basename, dirname, join } from "node:path";
7
+ import { createHash } from "node:crypto";
8
+ import { canonicalHomePath, realPathOrNearest } from "./real-path.mjs";
9
+
10
+ /** A home's receipt, read and found to be this home's and of this kernel's version → the
11
+ * receipt, or undefined when there is none, it cannot be read, or it is another home's. */
12
+ export function homeReceipt(home) {
13
+ const baseline = readJsonOrUndefined(findRetirementBaseline(home));
14
+ return baseline?.version === RETIRE_BASELINE_VERSION && receiptRecordsHome(baseline, canonicalHomePath(home)) ? baseline : undefined;
15
+ }
16
+ export function isPlainObject(v) { return !!v && typeof v === "object" && !Array.isArray(v); }
17
+ export function readJsonOrUndefined(path) { try { return JSON.parse(readFileSync(path, "utf8")); } catch { return undefined; } }
18
+
19
+ // The stored digests are versioned apart (`digestVersion`, BASELINE_DIGEST_VERSION): this version
20
+ // also gates runtime, directory-home and provider-exclusion authority, so a bump would refuse them all.
21
+ export const RETIRE_BASELINE_VERSION = 2;
22
+
23
+ export function retirementStateRoot(home) {
24
+ // Independent of the bytes it authenticates, but colocated with the agent's
25
+ // already instance-owned storage rather than the source repository or user
26
+ // config home. Retiring <instances>/<name> never removes this sibling.
27
+ return instancesRetirementRoot(dirname(home));
28
+ }
29
+ /** The retirement state of the homes in the instances directory `instances`. */
30
+ export function instancesRetirementRoot(instances) {
31
+ return join(instances, ".oats-retirement");
32
+ }
33
+
34
+ /** A home's identity as a receipt records it: its on-disk spelling, own name included. A home that
35
+ * is a symlink is not followed: its parent's on-disk spelling and its name as given (a home
36
+ * exchanged for a symlink is not the home it points at). */
37
+ export function receiptHomeIdentity(home) {
38
+ let st;
39
+ try { st = lstatSync(home); } catch { /* not there: spelled as the nearest existing ancestor */ }
40
+ return st && !st.isSymbolicLink() ? canonicalHomePath(home) : join(canonicalHomePath(dirname(home)), basename(home));
41
+ }
42
+
43
+ /** Whether a receipt's recorded home is this home, whatever spelling either was written in.
44
+ * `current` is the home as the caller resolves it for the comparison. */
45
+ export function receiptRecordsHome(baseline, current) {
46
+ return typeof baseline?.home === "string" && receiptHomeIdentity(baseline.home) === current;
47
+ }
48
+
49
+ export function retirementBaselineFile(identity) {
50
+ return join(retirementStateRoot(identity), "baselines", `${createHash("sha256").update(identity).digest("hex")}.json`);
51
+ }
52
+
53
+ /** Where the kernel keeps its own copies of a provider home's modules (lib/home-integrity.mjs):
54
+ * beside the receipts, keyed as the home's receipt is. */
55
+ export function homeModulesStore(home) {
56
+ const identity = receiptHomeIdentity(home);
57
+ return join(retirementStateRoot(identity), "modules", createHash("sha256").update(identity).digest("hex"));
58
+ }
59
+
60
+ /** Where a spawn writes a home's receipt: keyed by its canonical identity. */
61
+ export function retirementBaselinePath(home) {
62
+ return retirementBaselineFile(receiptHomeIdentity(home));
63
+ }
64
+
65
+ /** Where a kernel before 0.49.0 wrote it: keyed by the parent's realpath in the spawn's own
66
+ * spelling, which on a case-insensitive filesystem need not be the on-disk one. */
67
+ export function legacyRetirementBaselinePath(home) {
68
+ return retirementBaselineFile(join(realPathOrNearest(dirname(home)), basename(home)));
69
+ }
70
+
71
+ /** The receipt every reader uses: the canonical one if it exists, else one an earlier kernel left
72
+ * under this caller's spelling, else the canonical path (absent). Read-only: a receipt found at the
73
+ * legacy key is used where it is, never moved, copied or rewritten elsewhere.
74
+ *
75
+ * Limits. A legacy receipt written under spelling S is found only from S, or from the canonical
76
+ * spelling when that is S: a third spelling of such a home misses it (address the home as
77
+ * `oats status` prints it, the spawn's spelling). Receipts outlive retire, so a reused name can
78
+ * leave an earlier incarnation's receipt behind; the canonical one wins, which is right for every
79
+ * home spawned from 0.49.0 on. It is wrong in one case: two incarnations of the same name, both
80
+ * spawned by a kernel before 0.49.0 under different spellings, the earlier one under the canonical
81
+ * spelling. The later home then reads the earlier one's receipt. Its stale endpoint disagrees with
82
+ * instance.json (E_RUNTIME_AUTHORITY_MISMATCH) unless the later incarnation sits at the same
83
+ * endpoint, where session control already targets the right session. Retire finds the home
84
+ * fingerprint changed and preserves the home, less the stale receipt's disposable roots; a
85
+ * directory-work disagreement is E_WORK_INSPECTION_FAILED; and a start's record rewrites the stale
86
+ * file, as a kernel before 0.49.0 already does when a caller's spelling matches an earlier
87
+ * incarnation's. */
88
+ export function findRetirementBaseline(home) {
89
+ const canonical = retirementBaselinePath(home);
90
+ if (existsSync(canonical)) return canonical;
91
+ const legacy = legacyRetirementBaselinePath(home);
92
+ return legacy !== canonical && existsSync(legacy) ? legacy : canonical;
93
+ }
@@ -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.");
@@ -8,6 +8,7 @@ import { driftOf } from "./materialize.mjs";
8
8
  import { parseStrictJson } from "./canonical-json.mjs";
9
9
  import { readPortableBytes } from "./bounded-read.mjs";
10
10
  import { canonicalHomePath } from "./real-path.mjs";
11
+ import { providerHomeTrust } from "./home-integrity.mjs";
11
12
 
12
13
  export const UPGRADE_RECEIPT_NAME_RE = /^upgrade-receipt\.[A-Za-z0-9][A-Za-z0-9._:-]{0,127}\.json$/;
13
14
  const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
@@ -73,7 +74,11 @@ export function assertNoPartialUpgrade(home) {
73
74
  for (const { path, receipt } of readUpgradeReceipts(home)) {
74
75
  if (receipt.status !== "partial") continue;
75
76
  const { instance, command } = retryFor(home, receipt);
76
- throw Object.assign(oatsError("E_UPGRADE_PARTIAL", `the package upgrade of ${instance} is partial (${path}); nothing was stopped or started. Retry ${command} to finish it; if it cannot finish, respawn the instance`), {
77
+ // (A provider home's upgrade is not resumed, its journal being in the home: lib/instance-upgrade.mjs.)
78
+ const trust = providerHomeTrust(home);
79
+ // (With no composition in its receipt, the home's retire hooks cannot be identified: only --force removes it.)
80
+ const remedy = trust ? `${instance} is on a session provider, whose interrupted upgrade is not resumed: retire the instance (oats retire ${instance}${trust.problem ? " --force" : ""}) and spawn it again` : `Retry ${command} to finish it; if it cannot finish, respawn the instance`;
81
+ throw Object.assign(oatsError("E_UPGRADE_PARTIAL", `the package upgrade of ${instance} is partial (${path}); nothing was stopped or started. ${remedy}`), {
77
82
  details: { home, receipt: path, instance, idempotencyKey: receipt.idempotencyKey },
78
83
  });
79
84
  }
@@ -19,6 +19,8 @@ import { spawn as spawnProcess, execFileSync } from "node:child_process";
19
19
  import { closeSync, fchmodSync, mkdirSync, openSync, realpathSync, writeSync } from "node:fs";
20
20
  import { dirname, join } from "node:path";
21
21
  import { terminateGroup, watchGroup, TERM_GRACE_MS } from "./process-group.mjs";
22
+ import { moduleCopyProblem, providerHomeTrust, trustedCapability } from "./home-integrity.mjs";
23
+ import { PROVIDER_TREE_GIT } from "./instance-git.mjs";
22
24
  import { isStartToken, processLiveness, processStart, processStartToken } from "../packages/record/lib/process-identity.mjs";
23
25
 
24
26
  export { PS_ENV, isStartToken, processLiveness, processStart, processStartToken, runPs } from "../packages/record/lib/process-identity.mjs";
@@ -203,8 +205,20 @@ export async function runWorktreeHooks(hooks, { envFor, cwd, home, purpose, stre
203
205
  try {
204
206
  for (const hook of hooks) {
205
207
  if (guard?.signal) { out.interrupted = guard.signal; break; }
208
+ // A provider home's hook runs only from the kernel's own copy of its module, by the
209
+ // receipt's row for it (lib/home-integrity.mjs), whatever row and command the caller holds:
210
+ // with no such row or copy it is a failed required hook.
211
+ const trust = home ? providerHomeTrust(home) : null;
212
+ const trusted = trust ? trustedCapability(home, hook.cap ?? { id: hook.id }, trust) : null;
213
+ const untrusted = trust ? trusted.problem ?? (typeof trusted.cap.hooks?.worktree === "string" ? moduleCopyProblem(home, hook.id, trust) : `capability ${hook.id} has no worktree hook in the home's receipt`) : null;
214
+ if (untrusted) {
215
+ out.receipt.push({ capability: hook.id, ok: false, required: true, log: null });
216
+ out.failures.push({ capability: hook.id, event: "worktree", message: untrusted, required: true, integrity: true });
217
+ continue;
218
+ }
219
+ const run = trust ? { ...hook, command: trusted.cap.hooks.worktree, cap: trusted.cap } : hook;
206
220
  const log = worktreeHookLogPath(home, purpose, hook.id);
207
- const one = await runOne(hook, { env: envFor(hook.cap), cwd, log, sink, closed, guard, onStart, timeoutMs });
221
+ const one = await runOne(run, { env: envFor(run.cap), cwd, log, sink, closed, guard, onStart, timeoutMs });
208
222
  out.receipt.push({ capability: hook.id, ok: one.ok, required: hook.required, log, ...one.facts });
209
223
  out.warnings.push(...one.warnings);
210
224
  if (!one.ok) {
@@ -299,7 +313,9 @@ function runOne(hook, { env, cwd, log, sink, closed, guard, onStart, timeoutMs }
299
313
 
300
314
  // ---------- git facts about a tree and its clone ----------
301
315
 
302
- const gitOut = (argv) => { try { return execFileSync("git", argv, { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30_000 }).trim(); } catch { return null; } };
316
+ // (No hook and no file monitor of the repository: these reads may be of a provider home's tree,
317
+ // lib/instance-git.mjs PROVIDER_TREE_GIT; they read no index, so nothing changes for any home.)
318
+ const gitOut = (argv) => { try { return execFileSync("git", [...PROVIDER_TREE_GIT, ...argv], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 30_000 }).trim(); } catch { return null; } };
303
319
 
304
320
  /** The clone's `origin` URL, scrubbed (scrubRemoteUrl); "" when it has no `origin`. */
305
321
  export function originRemoteOf(clone) {
package/lib/worktree.mjs CHANGED
@@ -33,7 +33,9 @@ import { GIT_FETCH_TIMEOUT_MS } from "./remote.mjs";
33
33
  import { terminateGroup, watchGroup } from "./process-group.mjs";
34
34
  import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, recordInClaim, releaseClaim, shownHolder } from "./claim.mjs";
35
35
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
36
- import { NO_FILE_MONITOR, workTreeOverrides } from "./instance-git.mjs";
36
+ import { AsyncLocalStorage } from "node:async_hooks";
37
+ import { NO_FILE_MONITOR, PROVIDER_TREE_GIT, workTreeOverrides } from "./instance-git.mjs";
38
+ import { providerHomeTrust, trustedRecord } from "./home-integrity.mjs";
37
39
  import {
38
40
  cloneOfMember, instanceSoulDir, isCapturedHome, isWorkspaceHome, capturedHomeRefusal, preWorkspaceHome, lifecycleHookEnv,
39
41
  refuseBesideRetire, retirePendingMarkerPath, stableSoulId, workspaceOf,
@@ -55,9 +57,17 @@ export function worktreeFetchTimeoutMs(env = process.env) {
55
57
  }
56
58
  /** The git environment of every step: the invoker's, never prompting for credentials. */
57
59
  const gitEnv = () => ({ ...process.env, GIT_TERMINAL_PROMPT: "0" });
60
+ /** The Git settings every command of one `oats worktree` verb runs with, for the home it acts
61
+ * on: PROVIDER_TREE_GIT for a home on a session provider (no hook, no file monitor), none for any
62
+ * other. Held for the verb's own calls (and what they await), so that no call site can leave them
63
+ * out, and two verbs in one process do not share them. */
64
+ const treeGit = new AsyncLocalStorage();
65
+ const treeGitFor = (home) => { try { return providerHomeTrust(home) ? PROVIDER_TREE_GIT : []; } catch { return []; } };
66
+ const withTreeGit = (home, verb) => treeGit.run(treeGitFor(home), verb);
67
+ const treeArgv = (argv) => [...(treeGit.getStore() ?? []), ...argv];
58
68
  /** Run git → { ok, out, err, status }. Never a shell. */
59
69
  function git(argv, { timeout = 120_000, env = {}, input } = {}) {
60
- const r = spawnSync("git", argv, { encoding: "utf8", stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, env: { ...gitEnv(), ...env }, timeout, maxBuffer: 64 * 1024 * 1024 });
70
+ const r = spawnSync("git", treeArgv(argv), { encoding: "utf8", stdio: [input === undefined ? "ignore" : "pipe", "pipe", "pipe"], input, env: { ...gitEnv(), ...env }, timeout, maxBuffer: 64 * 1024 * 1024 });
61
71
  return { ok: r.status === 0 && !r.error, out: String(r.stdout ?? ""), err: String(r.stderr ?? "").trim() || r.error?.message || "", status: r.status };
62
72
  }
63
73
  /** Run a git step that changes something (a tree, a ref, the worktree list) as a recorded child:
@@ -74,7 +84,7 @@ export function trackedGit(argv, { track, timeout = 120_000 }) {
74
84
  return new Promise((resolve, fail) => {
75
85
  let child;
76
86
  try {
77
- child = spawnChild("/bin/sh", ["-c", 'read _ || exit 125; exec git "$@"', "oats-git", ...argv], { detached: true, stdio: ["pipe", "pipe", "pipe"], env: gitEnv() });
87
+ child = spawnChild("/bin/sh", ["-c", 'read _ || exit 125; exec git "$@"', "oats-git", ...treeArgv(argv)], { detached: true, stdio: ["pipe", "pipe", "pipe"], env: gitEnv() });
78
88
  } catch (e) { resolve({ ok: false, out: "", err: `git could not be started: ${e.message}`, status: null }); return; }
79
89
  watchGroup(child);
80
90
  let out = "", err = "", tracked = false, timedOut = false, settled = false;
@@ -174,7 +184,8 @@ export function readTreeHome(home) {
174
184
  // A retire in flight holds the home's lifecycle claim. Read, never taken: an add runs hooks for
175
185
  // minutes and has its purpose's claim.
176
186
  refuseBesideRetire("worktree add", home);
177
- return { home, meta };
187
+ // (A provider home's capability rows, its worktree hooks among them, are its receipt's: lib/home-integrity.mjs.)
188
+ return { home, meta: trustedRecord(meta, providerHomeTrust(home)) };
178
189
  }
179
190
 
180
191
  // ---------- the clone ----------
@@ -302,7 +313,8 @@ function addCreatedBranch(rec, tree) {
302
313
  * → { owed, warnings, branchDeleted, branchKept, branchKeptReason? }: `owed` is [] when all of
303
314
  * that is verified, else what is still owed (the record is then kept, so the next add or remove
304
315
  * tries again); a branch kept on purpose is not owed. `branchKept`: the branch exists afterwards. */
305
- export async function rollbackTree(home, rec, { track }) {
316
+ export function rollbackTree(home, rec, o) { return withTreeGit(home, () => rollbackTreeOf(home, rec, o)); }
317
+ async function rollbackTreeOf(home, rec, { track }) {
306
318
  const owed = [], warnings = [];
307
319
  const tree = extraTreePath(home, rec.purpose);
308
320
  const otherwise = leftoverRemedy(treeRecordPath(home, rec.purpose), tree, rec);
@@ -496,7 +508,8 @@ const publicReceipt = (rec, extra = {}) => ({
496
508
 
497
509
  /** `oats worktree add`. `o`: { purpose, branch, base, repo?, preview?, stream? }.
498
510
  * → the receipt ({ ..., resumed }) or, with preview, the plan. Throws typed errors. */
499
- export async function worktreeAdd(homeArg, o = {}) {
511
+ export function worktreeAdd(homeArg, o = {}) { return withTreeGit(homeArg, () => worktreeAddOf(homeArg, o)); }
512
+ async function worktreeAddOf(homeArg, o) {
500
513
  validateTreeArgs(o);
501
514
  const { home, meta } = readTreeHome(homeArg);
502
515
  const { purpose, branch, base } = o;
@@ -742,7 +755,8 @@ function removeWritableResidue(tree) {
742
755
  * nobody, and no flag removes anyway. An attached instance whose session is stopped does not
743
756
  * refuse: the tree is removed, and the answer's `warnings` name it, since its link then points at
744
757
  * a path that is gone. A tree that is already gone is removed under nobody: no one is looked at. */
745
- export async function worktreeRemove(homeArg, o = {}) {
758
+ export function worktreeRemove(homeArg, o = {}) { return withTreeGit(homeArg, () => worktreeRemoveOf(homeArg, o)); }
759
+ async function worktreeRemoveOf(homeArg, o) {
746
760
  validateTreeArgs(o, { forRemove: true });
747
761
  const home = homeArg;
748
762
  if (typeof home !== "string" || !isAbsolute(home) || !existsSync(join(home, "instance.json"))) throw badArgs("oats worktree runs from an instance home (in the home, or with $OATS_INSTANCE_HOME set to it)");
@@ -8,7 +8,7 @@
8
8
  },
9
9
  "oats.aweb": {
10
10
  "url": "https://github.com/awebai/oats-aweb.git",
11
- "ref": "v1.46.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.27.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.23",
3
+ "version": "0.70.0",
4
4
  "description": "OATS (Open Agent Team Specification) — durable souls, disposable instances, targetable capability packages, and the runtime-neutral oats CLI/kernel.",
5
5
  "keywords": [
6
6
  "agents",
@@ -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);