@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
package/bin/oats.mjs CHANGED
@@ -26,17 +26,25 @@ import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
26
26
  import { fileURLToPath } from "node:url";
27
27
  import { performance } from "node:perf_hooks";
28
28
  import { spawnSync as spawnSyncProc } from "node:child_process";
29
+ import { nodeVersionFailure } from "../lib/node-version.mjs";
29
30
  import { enableCliCompileCache } from "../lib/compile-cache.mjs";
30
31
  import { hotImport, hotRead } from "../lib/hot-reads.mjs";
31
32
  import { installStamp } from "../lib/install-stamp.mjs";
32
33
 
34
+ const unsupportedNode = nodeVersionFailure(process.versions.node);
35
+ if (unsupportedNode) {
36
+ if (process.argv.includes("--json")) process.stdout.write(`${JSON.stringify(unsupportedNode)}\n`);
37
+ else process.stderr.write(`${unsupportedNode.error.message}\n`);
38
+ process.exit(1);
39
+ }
40
+
33
41
  // The warm reader's baseline (lib/reader.mjs): its install's stamp before any kernel module loads, so that an
34
42
  // install changed while the kernel loads is never the install the reader believes it answers from.
35
43
  const READER_STAMP = process.argv[2] === "reader" ? installStamp() : null;
36
44
 
37
45
  // Node's compile cache is on before the kernel is parsed (lib/compile-cache.mjs): static imports are
38
- // all parsed and linked before this module's body runs, so they are Node built-ins and the three small
39
- // dependency-free modules above, and the kernel and `yaml` are imported here, in order, once it is on.
46
+ // all parsed and linked before this module's body runs, so they are Node built-ins and the small
47
+ // dependency-free startup modules above, and the kernel and `yaml` are imported here once it is on.
40
48
  enableCliCompileCache();
41
49
  // A hot read (lib/hot-reads.mjs) imports only the leaves it uses, never core.mjs: each line below takes
42
50
  // the leaves its names come from, and every other command imports every module, in this order. A hot
@@ -95,7 +103,7 @@ const { readBoardDetail, askBoardQuestion, clearBoardQuestion, setBoardFact, uns
95
103
  const { CLIENT_VIA, addDeployment, deploymentAtOrAbove, importDesktopDeployments, listDeployments, listResolved, removeDeployment } = await kernelImport("deployments", () => import("../lib/deployments.mjs"));
96
104
  const { observeResolvedDeployment } = await kernelImport("resolved-deployment", () => import("../lib/resolved-deployment.mjs"));
97
105
  const { SESSION_RESUME_FEATURE } = await kernelImport("session-resume-contract", () => import("../lib/session-resume-contract.mjs"));
98
- const { BOARD_API, KERNEL_FEATURES, READER_API } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
106
+ const { BOARD_API, BUILTIN_SESSION_BACKENDS, KERNEL_FEATURES, READER_API, SESSION_PROVIDER_NAME_RE } = await kernelImport("kernel-features", () => import("../lib/kernel-features.mjs"));
99
107
  const { inheritedContextRefusal } = await kernelImport("captured-context", () => import("../lib/captured-context.mjs"));
100
108
  const { callSession, parseMaxAge, readBudget } = await kernelImport("read-call", () => import("../lib/read-call.mjs"));
101
109
  const { cachedWorkspace, legacyLayoutProblems, statusAnswer, statusView } = await kernelImport("roster-read", () => import("../lib/roster-read.mjs"));
@@ -518,7 +526,8 @@ function scopeSouls(ctx, { extraRoots = [] } = {}) {
518
526
  const roots = [...new Set([findRoot(ctx), ...extraRoots].filter(Boolean).map((p) => realOrResolved(resolve(p))))];
519
527
  const souls = [];
520
528
  for (const root of roots) {
521
- for (const a of listInstances(root)) {
529
+ // Names only: no session provider is asked.
530
+ for (const a of listInstances(root, undefined, undefined, { askProviders: false })) {
522
531
  const soul = findAgent(root, a.name) || a;
523
532
  const e = soulEntry(soul, root);
524
533
  e.instances = (a.instances || []).map((i) => i.instance);
@@ -676,6 +685,8 @@ function printWorkspaceInspect(doc) {
676
685
  if (doc.identity) console.log(` identity: ${servedIdentityLine(doc.identity)}`);
677
686
  for (const l of LAYERS) console.log(` ${l} capability: ${doc.layers[l].id || "none"}`);
678
687
  for (const c of doc.capabilities) console.log(` ${c.id}@${c.version || "?"} ${c.from?.kind === "package" ? `package ${c.from.package}` : c.from?.kind === "member" ? `member ${c.from.repoKey}` : ""}${c.operations.length ? ` ops: ${c.operations.map((o) => `${o.name}${o.available ? "" : "(unavailable)"}`).join(", ")}` : ""}`);
688
+ // Feature session-providers: the backends `--backend` takes here beside tmux, each with the capability that supplies it.
689
+ if (doc.sessionProviders?.length) console.log(` session backends: tmux, ${doc.sessionProviders.map((p) => `${p.name} (${p.capability})`).join(", ")}`);
679
690
  for (const p of doc.problems) console.log(` ! ${p.code}: ${p.message}`);
680
691
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
681
692
  const board = doc.instance?.board;
@@ -710,6 +721,19 @@ async function homeLiveTeams(home) {
710
721
  return Array.isArray(teams) ? { teams, defaultTeam, teamsSource: source } : {};
711
722
  }
712
723
 
724
+ /** For a start or a restart of a home on a session provider: the deployment's configuration its
725
+ * sandbox allowances are computed from (lib/instance-resolution.mjs homeSandboxSource), read now.
726
+ * → `{ sandboxSource }`, or `{}` for a tmux home, which reads nothing. (A `--resume` launches
727
+ * nothing on a provider, and reads nothing either.) The home's record only says whether to read:
728
+ * which deployment and which soul are the home's path's to say. */
729
+ async function homeSandboxSourceOf(home) {
730
+ let meta;
731
+ try { meta = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); } catch { return {}; }
732
+ const { recordsSessionProvider } = await import("../lib/session-providers.mjs");
733
+ if (!recordsSessionProvider(meta)) return {};
734
+ const { homeSandboxSource } = await import("../lib/instance-resolution.mjs");
735
+ return { sandboxSource: await homeSandboxSource(home, { remoteOptions: remoteOptionsFromEnv() }) };
736
+ }
713
737
  /** For `--reselect-launch`: what the home's launch layers need of the workspace to say which keys of
714
738
  * souls.launch name no soul (lib/core.mjs homeLaunchLayers), read only when they need it and the layers
715
739
  * decide (`named`: --harness names the launch, so no key is consulted). A home the start will refuse
@@ -827,6 +851,9 @@ async function workspaceOperation(t, { bail, address, layer, opName }) {
827
851
  const [script, ...rest] = spec.trim().split(/\s+/);
828
852
  const abs = lp?.executable(script);
829
853
  if (!abs) return bail("E_CAPABILITY_BROKEN", `${mod.name} ${op.command}: script not found (${script})`);
854
+ // A provider home's own copy is never run: the kernel runs its copy of it (a guard; `dir` is that copy).
855
+ const untrustedCopy = lp.dir ? (await import("../lib/home-integrity.mjs")).moduleCopyProblemAt(lp.dir) : null;
856
+ if (untrustedCopy) return bail("E_CAPABILITY_BLOCKED", `${address} was not run: ${untrustedCopy}`);
830
857
  const settings = lp.settings;
831
858
  const cwd = op.context === "home" ? t.home : t.deployment;
832
859
  const env = { ...lp.env(mod.name, settings), OATS_OPERATION: address, OATS_CONTEXT: t.deployment, OATS_ROOT: t.agentsRoot, PI_AGENTS_ROOT: t.agentsRoot };
@@ -890,6 +917,16 @@ function doctorMachineLaunchConfigs() {
890
917
  return { file, present: true, ok: false, configurations: [], error: e.message };
891
918
  }
892
919
  }
920
+ /** The shared Git version probe reports support, not each repository's recorded fetch mode.
921
+ * An older Git is supported too; this is information, never a warning or a refusal. */
922
+ async function doctorGitInformation() {
923
+ const version = await remoteModule.gitVersion();
924
+ if (!version) return "git-version: Git version could not be read; partial-cache support unknown";
925
+ const mode = remoteModule.keepsPartialCache(version)
926
+ ? "partial caches supported (a remote or an existing cache may still use whole-tree fetches)"
927
+ : `whole-tree fallback (partial caches need Git ${remoteModule.PARTIAL_FETCH_GIT.join(".")} or later)`;
928
+ return `git-version: Git ${terminalText(version.text)}; ${mode}`;
929
+ }
893
930
  /** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
894
931
  * doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
895
932
  * same from every deployment. */
@@ -913,7 +950,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
913
950
  schemaVersion: 1, workspaceApi: 2, context: ctx,
914
951
  workspace: { file: ws.local.path, ref: ws.local.workspace },
915
952
  workspaceError: ws.localError, lockFile: ws.lockFile, packages: ws.packages, lockError: ws.lockError,
916
- information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
953
+ information: [...(operationalKnowledgeNote(composition, soulName) ? [operationalKnowledgeNote(composition, soulName)] : []), await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation(), ...doctorRetained(ws).flat()],
917
954
  machineLaunchConfigs: doctorMachineLaunchConfigs(),
918
955
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
919
956
  ...(problems.length ? { problems } : {}),
@@ -973,7 +1010,7 @@ async function doctor(dir) {
973
1010
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
974
1011
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
975
1012
  if (!soulName) for (const w of doctorCaptureWarnings()) console.log(`\nwarning ${w.code} ${terminalText(w.message)}`);
976
- for (const line of [...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
1013
+ for (const line of [await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
977
1014
  for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
978
1015
  if (soulName) {
979
1016
  const information = operationalKnowledgeNote(composition, soulName);
@@ -1156,8 +1193,11 @@ function launchPreview(bail) {
1156
1193
  let plan;
1157
1194
  try { plan = planLaunch({ home, instance, meta, contextDir: context, agentLike, selection: sel, resolvedCfg: r, preview: true, pane: () => previewPaneEnvironment(meta ? { home, meta } : { deployment: context }) }); } catch (e) { bail(e.code || "E_BAD_ARGS", e.message); }
1158
1195
  const { recipe } = plan;
1159
- const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1160
- const d = describeLaunchCommand(command);
1196
+ // A home on a session provider has no command line: its launch is handed to the provider as data
1197
+ // (`command` and `argv` null, the executable's path null); its environment is listed by name.
1198
+ const onProvider = plan.command === undefined;
1199
+ const command = onProvider ? null : renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1200
+ const d = onProvider ? { argv: null, environment: [...Object.keys(recipe.hooks?.env || {}).sort().map((name) => ({ name, redacted: true })), ...Object.keys(recipe.env || {}).sort().map((name) => (typeof recipe.env[name] === "string" ? { name, redacted: true } : { name, reference: true }))] } : describeLaunchCommand(command);
1161
1201
  const environment = d.environment.map((e) => e.reference && recipe.env[e.name] && typeof recipe.env[e.name] === "object" ? { name: e.name, ...recipe.env[e.name] } : e);
1162
1202
  jsonOk({ context, selected, ...(plan.warnings?.length ? { warnings: plan.warnings } : {}), selection: { source: plan.selectionSource, launchConfig: recipe.launchConfig, harness: sel.harness ?? null, model: sel.model ?? null, yolo: sel.yolo ?? null }, harness: plan.harness, model: recipe.model, modelSource: plan.modelSource, yolo: recipe.yolo ?? null, launchConfig: recipe.launchConfig, launchConfigSource: recipe.launchConfigSource, launchConfigDefault: recipe.launchConfigDefault === true, executable: { path: plan.executable.path, declared: plan.executable.declared ?? null, resolvedFrom: plan.executable.resolvedFrom }, argv: d.argv, environment, command, prompt: recipe.prompt, hooks: redactLaunchRecipe(recipe).hooks, preflight: plan.preflight, ok: plan.ok });
1163
1203
  }
@@ -1755,6 +1795,7 @@ async function readinessCmd() {
1755
1795
  }
1756
1796
  if (doc.policy) console.log(` policy: child spawns ${doc.policy.childSpawns.allowed ? "allowed" : "disabled"} (${doc.policy.childSpawns.origin.kind}${doc.policy.childSpawns.enforced ? ", enforced" : ""}); worktrees ${doc.policy.worktrees.allowed === null ? "unknown" : doc.policy.worktrees.allowed ? "allowed" : "not in this work mode"}`);
1757
1797
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
1798
+ printSandboxAllowances(doc.sandbox, " ");
1758
1799
  for (const n of doc.notes) console.log(` note: ${terminalText(n)}`);
1759
1800
  return;
1760
1801
  }
@@ -2603,6 +2644,26 @@ async function capabilityShowCmd(bail) {
2603
2644
  }
2604
2645
  for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2605
2646
  }
2647
+ if (doc.sessionProviders !== undefined) {
2648
+ // As declared (a malformed declaration is shown, never refused), made safe to print.
2649
+ const { safeText } = await import("../lib/refused-text.mjs");
2650
+ const decl = doc.sessionProviders && typeof doc.sessionProviders === "object" && !Array.isArray(doc.sessionProviders) ? doc.sessionProviders : null;
2651
+ console.log(decl && Object.keys(decl).length ? " session providers:" : ` session providers: ${decl ? "(none)" : "(malformed — see session provider problems)"}`);
2652
+ for (const [n, provider] of Object.entries(decl ?? {})) {
2653
+ const o = provider && typeof provider === "object" ? provider : {};
2654
+ console.log(` ${safeText(n, 60)} harnesses ${Array.isArray(o.harnesses) ? o.harnesses.map((h) => safeText(String(h), 40)).join(",") : "?"}${typeof o.description === "string" ? ` — ${safeText(o.description, 200)}` : ""}`);
2655
+ }
2656
+ for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2657
+ }
2658
+ if (doc.sandboxDomains !== undefined) {
2659
+ // As declared, made safe to print: the settings whose hosts a session provider's sandbox may be widened by.
2660
+ const { safeText } = await import("../lib/refused-text.mjs");
2661
+ // A `{ setting }` line: the setting's host. A `{ settingFile, urls }` line: the hosts in the file the setting names.
2662
+ const lines = Array.isArray(doc.sandboxDomains) ? doc.sandboxDomains.map((l) => (typeof l?.setting === "string" ? `the host of setting ${safeText(l.setting, 80)}${l.optional === true ? " (optional)" : ""}`
2663
+ : typeof l?.settingFile === "string" ? `the hosts in the file of setting ${safeText(l.settingFile, 80)} at ${safeText(String(l.urls ?? "?"), 200)}` : "?")) : null;
2664
+ console.log(` sandbox domains: ${lines ? lines.join("; ") : "(malformed — see sandbox domain problems)"}`);
2665
+ for (const p of doc.sandboxDomainProblems ?? []) console.log(` sandbox domain problem: ${safeText(p, 300)}`);
2666
+ }
2606
2667
  for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
2607
2668
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
2608
2669
  console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
@@ -2731,7 +2792,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2731
2792
  if (a.description) console.log(` ${a.description}`);
2732
2793
  for (const i of a.instances) {
2733
2794
  // Feature instance-background: the row is marked; it is listed like any other.
2734
- console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2795
+ console.log(` • ${i.instance}${i.background === true ? " [background]" : ""} ${statusWord(i)} (branch ${i.branch || "?"}, ${i.work || "?"}${i.session ? `, on ${i.backend}` : ""})${i.runtimeError ? ` ${i.runtimeError}` : ""}`);
2735
2796
  { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2736
2797
  // Feature waiting-on-you: non-null only on a running row; the reader has
2737
2798
  // already validated the message (one line, no control characters).
@@ -2745,6 +2806,9 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2745
2806
  if (s && (verbose || s.status !== "current")) console.log(` ${soulDriftLine(s, a.name)}`);
2746
2807
  const rows = ws?.drift.get(key) || [];
2747
2808
  for (const r of rows) if (verbose || r.status !== "current") console.log(` ${driftLine(r)}`);
2809
+ // A provider home: the kernel runs its own copy of the home's modules; said when the home's
2810
+ // own record of them is not the receipt's, and always with --verbose.
2811
+ if (i.moduleCopy && (verbose || i.moduleCopy.homeCopy === "differs")) console.log(` modules: the kernel runs its own copy${i.moduleCopy.homeCopy === "differs" ? `; the home's own record differs${i.moduleCopy.differs.length ? ` for ${i.moduleCopy.differs.join(", ")}` : ""} (oats readiness --home ${i.home} compares the files)` : "; the home's record of them is the same"}`);
2748
2812
  }
2749
2813
  for (const f of a.retireFailures || []) {
2750
2814
  console.log(` ! deferred retirement of ${f.instance} FAILED${f.completedAt ? ` at ${f.completedAt}` : ""}: ${f.error || (f.incomplete || []).join("; ") || "see result file"} — retry with \`oats retire ${f.instance}\``);
@@ -2777,6 +2841,21 @@ function namingLine(naming) {
2777
2841
  if (naming?.source === "numbered") return `numbered (${terminalText(naming.reason)}: ${terminalText(naming.message)})`;
2778
2842
  return null;
2779
2843
  }
2844
+ /** What a session provider may widen its harness's sandbox by (lib/sandbox-allowances.mjs), as a
2845
+ * spawn preview and readiness say it in text: each host with who asked for it, each path with its
2846
+ * reason, what is missing, what was left out or not read; or why there is none. Nothing for a
2847
+ * launch that has none (tmux). */
2848
+ function printSandboxAllowances(sb, indent = "") {
2849
+ if (!sb) return;
2850
+ if (sb.unavailable) { console.log(`${indent}sandbox allowances: none could be computed (${terminalText(sb.unavailable)})`); return; }
2851
+ if (sb.refused) { console.log(`${indent}sandbox allowances: refused (${sb.refused.code}): ${terminalText(sb.refused.message)}`); return; }
2852
+ console.log(`${indent}sandbox allowances:`);
2853
+ for (const d of sb.domains) console.log(`${indent} host ${terminalText(d.host)} asked by ${terminalText(d.capability)} (setting ${terminalText(d.setting)}${d.team ? `, for team ${terminalText(d.team)}, which this instance may join` : ""})`);
2854
+ for (const w of sb.write) console.log(`${indent} path ${terminalText(w.path)} asked by the kernel (${terminalText(w.reason)})`);
2855
+ for (const m of sb.missing) console.log(`${indent} missing${m.optional ? " (optional)" : ""}: ${terminalText(m.capability)} setting ${terminalText(m.setting)}${m.team === null ? " has no value" : ` has no entry for team ${terminalText(m.team)}${m.defaultTeam ? " (the default team)" : ""}`}`);
2856
+ for (const k of sb.skipped ?? []) console.log(`${indent} left out: ${terminalText(k.capability)}: ${terminalText(k.reason)}`);
2857
+ for (const u of sb.unread ?? []) console.log(`${indent} not read: ${terminalText(u.capability)} setting ${terminalText(u.setting)}: ${terminalText(u.reason)}`);
2858
+ }
2780
2859
  /** A spawn preview's text: the local one, or a host's answer to a routed
2781
2860
  * preview (`server`, its id), which this side printed the same way (#610). */
2782
2861
  function printSpawnPreview(r, { server, soulFetched = false } = {}) {
@@ -2787,6 +2866,7 @@ function printSpawnPreview(r, { server, soulFetched = false } = {}) {
2787
2866
  { const line = namingLine(r.naming); if (line) console.log(`name: ${line}`); }
2788
2867
  if (r.background === true) console.log(`list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
2789
2868
  if (Array.isArray(r.worktreeHooks)) console.log(r.worktreeHooks.length ? `worktree hooks: ${r.worktreeHooks.map((h) => `${h.capability}${h.required ? " (required)" : ""}`).join(", ")}` : "worktree hooks: none");
2869
+ printSandboxAllowances(r.sandbox);
2790
2870
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
2791
2871
  }
2792
2872
  async function spawnCmd() {
@@ -2798,7 +2878,9 @@ async function spawnCmd() {
2798
2878
  const yolo = yoloFlag();
2799
2879
  { const herdr = herdrSpawnFlag(); if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); } }
2800
2880
  const backend = valueFlag("backend");
2801
- if (backend !== undefined && backend !== "tmux") bail("E_BAD_ARGS", "--backend must be tmux");
2881
+ // tmux, or a session provider one of the soul's capabilities declares: the kernel resolves the name
2882
+ // against the instance's modules (E_BACKEND_UNKNOWN names the backends available there).
2883
+ if (backend !== undefined && !SESSION_PROVIDER_NAME_RE.test(backend)) bail("E_BAD_ARGS", "--backend must be tmux or a session provider's name (1 to 40 lowercase letters, digits and dashes)");
2802
2884
  const requestedWork = valueFlag("work");
2803
2885
  const workDir = valueFlag("work-dir"), branch = valueFlag("branch"), repo = valueFlag("repo");
2804
2886
  const checkDirectoryOptions = (work) => {
@@ -3067,7 +3149,8 @@ async function spawnCmd() {
3067
3149
  // #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
3068
3150
  ...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
3069
3151
  ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
3070
- tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
3152
+ // A home on a session provider carries its backend's name and `session` ({ provider, endpoint }), and no tmux.
3153
+ tmux: r.tmux || null, backend: r.session ? r.backend : "tmux", ...(r.session ? { session: r.session } : {}), repo: r.repo || null, harness: r.harness || null,
3071
3154
  model: r.model || null, parent: r.parentInstance || null,
3072
3155
  sibling: r.siblingInstance || null, relation: r.relation || null,
3073
3156
  spawnOrigin: r.spawnOrigin, attach: r.attach,
@@ -3085,7 +3168,7 @@ async function spawnCmd() {
3085
3168
  });
3086
3169
  return;
3087
3170
  }
3088
- console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3171
+ console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${r.backend} session` : ` — tmux window "${r.tmux.window}"`) : " — not launched"}`);
3089
3172
  console.log(` home: ${shortPath(r.home)}`);
3090
3173
  if (r.background === true) console.log(` list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
3091
3174
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
@@ -3095,7 +3178,8 @@ async function spawnCmd() {
3095
3178
  if (wakeScheduleError) console.error(` wake: NOT saved — ${wakeScheduleError.message} (the instance is created and launched; add the wake by hand with oats schedule add)`);
3096
3179
  if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
3097
3180
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
3098
- console.log(` attach: ${r.attach}`);
3181
+ if (r.attach) console.log(` attach: ${r.attach}`);
3182
+ else if (r.session) console.log(` open: oats session inspect --home ${shellQuote(r.home)} --json (its \`open\` link; ${terminalText(r.backend)} has no terminal to attach to)`);
3099
3183
  }
3100
3184
 
3101
3185
  /** The line naming the branch a FAILED_SPAWN_BRANCH_LEFT item speaks of, on a line of its own: the item names
@@ -3586,7 +3670,7 @@ async function sessionCmd() {
3586
3670
  const deployment = flag("deployment");
3587
3671
  if (deployment === true || (typeof deployment === "string" && !deployment.trim())) throw Object.assign(new Error(`--deployment needs a deployment directory\n${usage}`), { code: "E_BAD_ARGS" });
3588
3672
  const { resumeSessions } = await import("../lib/session-resume.mjs");
3589
- const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3673
+ const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), askProviders: !args.includes("--without-provider-inspect"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3590
3674
  if (JSON_MODE) { jsonOk(answer); return; }
3591
3675
  for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
3592
3676
  for (const r of answer.rows) console.log(` ${r.instance} ${answer.plan ? "would be " : ""}${r.outcome}${r.reason ? ` (${r.reason}${r.code ? `, ${r.code}` : ""})` : ""}${r.message ? `: ${terminalText(r.message)}` : ""}`);
@@ -3620,7 +3704,7 @@ async function sessionCmd() {
3620
3704
  // upgrade that runs (it holds the claim) the start is busy, not a partial upgrade: that one is
3621
3705
  // left to the claim. A resume is always refused under the claim.
3622
3706
  if (!resume && !upgradeHoldsClaim(home)) assertNoPartialUpgrade(home);
3623
- const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3707
+ const opts = { model: model || undefined, launchConfig, harness, yolo: yoloFlag(), ...(resume ? {} : await homeSandboxSourceOf(home)), ...(reselectLaunch ? { reselectLaunch: true, launchOffered: await homeLaunchOffered(home, { named: harness !== undefined }) } : {}), ...(resume ? { resume: true } : {}), env: process.env, ...(await homeLiveTeams(home)) };
3624
3708
  if (args[1] === "restart") {
3625
3709
  const grace = flag("stop-grace");
3626
3710
  if (grace !== undefined) { if (grace === true || !/^\d+$/.test(String(grace)) || Number(grace) < 1 || Number(grace) > 300) bad("--stop-grace needs a number of seconds (1..300) to wait for the harness after SIGTERM"); opts.stopGraceMs = Number(grace) * 1000; }
@@ -4075,8 +4159,13 @@ async function capabilityCommand() {
4075
4159
  try {
4076
4160
  if (metaFile && existsSync(metaFile)) {
4077
4161
  const meta = JSON.parse(readFileSync(metaFile, "utf8"));
4078
- activeIds = (meta.capabilities || []).map((c) => c.id);
4079
- for (const c of meta.capabilities || []) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
4162
+ // A provider home's capabilities and their settings are its receipt's, never its own
4163
+ // record's, which its agent can write (lib/home-integrity.mjs).
4164
+ const { capabilityRuntimeOf, providerHomeTrust } = await import("../lib/home-integrity.mjs");
4165
+ const trust = providerHomeTrust(instanceHome);
4166
+ const rows = trust ? capabilityRuntimeOf(instanceHome, meta, trust) : meta.capabilities || [];
4167
+ activeIds = rows.map((c) => c.id);
4168
+ for (const c of rows) { capSettings[c.id] = c.settings || {}; capOrigins[c.id] = c.settingsOrigins || {}; }
4080
4169
  // Workspace-model homes only (lead decision c3 Q2).
4081
4170
  if (isCapturedHome(meta)) { const e = capturedHomeRefusal(instanceHome, "nothing was dispatched"); bail(e.code, e.message, e.details); }
4082
4171
  if (!isWorkspaceHome(meta)) { const e = preWorkspaceHome(instanceHome, "nothing was dispatched"); bail(e.code, e.message); }
@@ -4169,6 +4258,9 @@ async function capabilityCommand() {
4169
4258
  try { abs = capabilityExecutablePath(withDir, script); }
4170
4259
  catch (e) { bail("E_CAPABILITY_BROKEN", e.message); }
4171
4260
  if (!abs) bail("E_CAPABILITY_BROKEN", `${cmd} ${sub}: script not found (${join(dir, script)})`);
4261
+ // A provider home's own copy is never run: the kernel runs its copy of it (a guard; `dir` is that copy).
4262
+ const untrustedCopy = (await import("../lib/home-integrity.mjs")).moduleCopyProblemAt(dir);
4263
+ if (untrustedCopy) bail("E_CAPABILITY_BLOCKED", `oats ${cmd} ${sub} was not run: ${untrustedCopy}`);
4172
4264
  // The soul the command acts for → { dir, cleanup, agent, id }: a home's recorded soul directory, or
4173
4265
  // (operator dispatch) the soul read at its resolved commit, whose temporary copy goes when this
4174
4266
  // process exits; with its name and stable id, as the soul's lifecycle hooks get them.
@@ -4307,7 +4399,7 @@ function versionCmd() {
4307
4399
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4308
4400
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4309
4401
  // never listed.
4310
- console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: ["tmux"], launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, boardApi: BOARD_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
4402
+ console.log(JSON.stringify({ schemaVersion: 1, name: "@awebai/oats", version: OATS_VERSION, desktopApi: 1, harnesses: ["pi", "claude", "codex"], sessionBackends: BUILTIN_SESSION_BACKENDS, launchOptions: ["yolo"], remote: ["spawn", "retire", "status", "session", "session-start", "session-restart", "launch-config", "roster", "harvest", "schedule", "session-upload", "operations", "readiness", "instance-events", "instance-git", "lifecycle-plans"], features: KERNEL_FEATURES, automationsApi: A.AUTOMATIONS_API, workspaceApi: 2, instanceGitApi: 1, spawnApplyApi: 1, soulsApi: 2, lifecycleApi: 1, readinessApi: 2, spawnPreviewApi: 2, eventsApi: 2, scheduleHistoryApi: 3, scheduleApi: SCHEDULE_API, operationsApi: 2, capabilityShowApi: 1, readerApi: READER_API, boardApi: BOARD_API, sessionViewer: readSessionViewer(), package: OATS_PACKAGE_NAME }));
4311
4403
  return;
4312
4404
  }
4313
4405
  console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
@@ -4787,7 +4879,7 @@ async function serverRouteCmd() {
4787
4879
  // The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
4788
4880
  if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
4789
4881
  else if (cmd === "spawn") {
4790
- console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}` : " — not launched"}`);
4882
+ console.log(`Spawned ${r.instance} on ${id} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? (r.session ? ` — ${terminalText(r.backend)} session on ${r.target.sshHost}` : ` — tmux window "${r.tmux?.window}" on ${r.target.sshHost}`) : " — not launched"}`);
4791
4883
  console.log(` remote home: ${r.home}`);
4792
4884
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
4793
4885
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
@@ -5187,7 +5279,7 @@ Usage:
5187
5279
  is a unit (a conflicting --harness is refused)
5188
5280
  [--model <id>|@native-default] override the selected model; @native-default
5189
5281
  selects the harness's own model default
5190
- [--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
5282
+ [--backend tmux|<provider>] [--yolo|--no-yolo] session backend (tmux, or a session provider of the soul's capabilities) and launch permission option
5191
5283
  [--background|--no-background] list the instance under Background (presentation
5192
5284
  only); default: the soul's background:, else no
5193
5285
  [--no-launch] [--json] scaffold without launching; JSON result envelope