@awebai/oats 0.69.23 → 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 (74) hide show
  1. package/bin/oats.mjs +56 -17
  2. package/docs/capabilities.md +353 -5
  3. package/docs/capability-manifest.schema.json +36 -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 +320 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +257 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +186 -3
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +5 -1
  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/souls-and-instances.md +45 -0
  21. package/docs/tui.md +21 -1
  22. package/docs/upgrading.md +12 -5
  23. package/docs/workspaces.md +13 -5
  24. package/lib/capability-show.mjs +11 -1
  25. package/lib/command-flags.mjs +2 -2
  26. package/lib/compile-cache.mjs +1 -1
  27. package/lib/core.mjs +1176 -181
  28. package/lib/errors.mjs +4 -1
  29. package/lib/hook-env.mjs +106 -0
  30. package/lib/host-run.mjs +11 -3
  31. package/lib/instance-inspect.mjs +44 -0
  32. package/lib/instance-lifecycle.mjs +15 -3
  33. package/lib/instance-listing.mjs +97 -8
  34. package/lib/kernel-features.mjs +10 -1
  35. package/lib/node-version.mjs +9 -0
  36. package/lib/provider-call-child.mjs +60 -0
  37. package/lib/provider-resume.mjs +83 -0
  38. package/lib/provider-test-seams.mjs +20 -0
  39. package/lib/read-call.mjs +2 -0
  40. package/lib/reserved-launch-env.mjs +8 -1
  41. package/lib/retire-admission.mjs +5 -1
  42. package/lib/schedule.mjs +14 -4
  43. package/lib/servers.mjs +28 -4
  44. package/lib/session-inspect.mjs +104 -13
  45. package/lib/session-providers.mjs +528 -0
  46. package/lib/session-resume.mjs +68 -15
  47. package/lib/stable-node.mjs +3 -0
  48. package/lib/triggers.mjs +3 -1
  49. package/package-catalog.json +2 -2
  50. package/package.json +2 -1
  51. package/packages/client/capability-list.mjs +21 -0
  52. package/packages/client/cli-adapter.mjs +19 -4
  53. package/packages/client/cli-locator.mjs +5 -1
  54. package/packages/client/deployment-data.mjs +23 -1
  55. package/packages/client/deployment-panel.mjs +25 -3
  56. package/packages/client/home-board.mjs +33 -19
  57. package/packages/client/inspect-boundary.mjs +18 -8
  58. package/packages/client/instance-acts.mjs +30 -3
  59. package/packages/client/instance-board.mjs +206 -0
  60. package/packages/client/instance-presentation.mjs +55 -0
  61. package/packages/client/liveness.mjs +15 -4
  62. package/packages/client/own-codes.mjs +5 -1
  63. package/packages/client/remote-roster.mjs +6 -1
  64. package/packages/client/session-backends.mjs +31 -0
  65. package/packages/client/session-start.mjs +18 -6
  66. package/packages/client/spawn-apply-cli.mjs +5 -3
  67. package/packages/client/spawn-apply-contract.mjs +25 -2
  68. package/packages/client/spawn-apply.mjs +5 -1
  69. package/packages/client/spawn-messages.mjs +3 -0
  70. package/packages/client/terminal-contract.mjs +4 -0
  71. package/packages/client/waiting-on-you.mjs +12 -2
  72. package/packages/tui/lib/model.mjs +14 -3
  73. package/packages/tui/lib/store.mjs +12 -3
  74. 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;
@@ -890,6 +901,16 @@ function doctorMachineLaunchConfigs() {
890
901
  return { file, present: true, ok: false, configurations: [], error: e.message };
891
902
  }
892
903
  }
904
+ /** The shared Git version probe reports support, not each repository's recorded fetch mode.
905
+ * An older Git is supported too; this is information, never a warning or a refusal. */
906
+ async function doctorGitInformation() {
907
+ const version = await remoteModule.gitVersion();
908
+ if (!version) return "git-version: Git version could not be read; partial-cache support unknown";
909
+ const mode = remoteModule.keepsPartialCache(version)
910
+ ? "partial caches supported (a remote or an existing cache may still use whole-tree fetches)"
911
+ : `whole-tree fallback (partial caches need Git ${remoteModule.PARTIAL_FETCH_GIT.join(".")} or later)`;
912
+ return `git-version: Git ${terminalText(version.text)}; ${mode}`;
913
+ }
893
914
  /** The machine's resume lock when it needs a person (lib/session-resume.mjs resumeLockProblem), as
894
915
  * doctor's problems: read where a sweep would take it, nothing taken. It is this machine's, the
895
916
  * same from every deployment. */
@@ -913,7 +934,7 @@ async function doctorWorkspaceJson(ctx, soulName, ws) {
913
934
  schemaVersion: 1, workspaceApi: 2, context: ctx,
914
935
  workspace: { file: ws.local.path, ref: ws.local.workspace },
915
936
  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()],
937
+ 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
938
  machineLaunchConfigs: doctorMachineLaunchConfigs(),
918
939
  composedInstructions: composition?.text, instructionBlocks: composition?.blocks,
919
940
  ...(problems.length ? { problems } : {}),
@@ -973,7 +994,7 @@ async function doctor(dir) {
973
994
  const hookEvents = composition ? { warnings: composition.warnings, information: [] } : await doctorHookWarnings(ws);
974
995
  for (const w of hookEvents.warnings) console.log(`\nwarning ${w.code} ${w.message}`);
975
996
  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}`);
997
+ for (const line of [await doctorGitInformation(), ...localTeams.information, ...schedules.information, ...operator.information, ...launchPreferences.information, ...disabledSouls.information, ...hookEvents.information, ...processScanInformation()]) console.log(`\nINFO: ${line}`);
977
998
  for (const block of doctorRetained(ws)) console.log(`\n${block.map((line) => `INFO: ${line}`).join("\n")}`);
978
999
  if (soulName) {
979
1000
  const information = operationalKnowledgeNote(composition, soulName);
@@ -1156,8 +1177,11 @@ function launchPreview(bail) {
1156
1177
  let plan;
1157
1178
  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
1179
  const { recipe } = plan;
1159
- const command = renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1160
- const d = describeLaunchCommand(command);
1180
+ // A home on a session provider has no command line: its launch is handed to the provider as data
1181
+ // (`command` and `argv` null, the executable's path null); its environment is listed by name.
1182
+ const onProvider = plan.command === undefined;
1183
+ const command = onProvider ? null : renderLaunchRecipe(recipe, { home, instance, redact: true, trustHome: plan.trustHome });
1184
+ 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
1185
  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
1186
  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
1187
  }
@@ -2603,6 +2627,17 @@ async function capabilityShowCmd(bail) {
2603
2627
  }
2604
2628
  for (const p of doc.triggerSourceProblems ?? []) console.log(` trigger source problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2605
2629
  }
2630
+ if (doc.sessionProviders !== undefined) {
2631
+ // As declared (a malformed declaration is shown, never refused), made safe to print.
2632
+ const { safeText } = await import("../lib/refused-text.mjs");
2633
+ const decl = doc.sessionProviders && typeof doc.sessionProviders === "object" && !Array.isArray(doc.sessionProviders) ? doc.sessionProviders : null;
2634
+ console.log(decl && Object.keys(decl).length ? " session providers:" : ` session providers: ${decl ? "(none)" : "(malformed — see session provider problems)"}`);
2635
+ for (const [n, provider] of Object.entries(decl ?? {})) {
2636
+ const o = provider && typeof provider === "object" ? provider : {};
2637
+ 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)}` : ""}`);
2638
+ }
2639
+ for (const p of doc.sessionProviderProblems ?? []) console.log(` session provider problem: ${p.pointer} — ${safeText(p.message, 300)}`);
2640
+ }
2606
2641
  for (const p of doc.problems) console.log(` problem: ${p.code}${p.path ? ` ${p.path}` : ""} — ${p.message}`);
2607
2642
  for (const w of doc.warnings) console.log(` warning ${w.code} ${w.message}`);
2608
2643
  console.log(`\n a file's text: oats capabilities show ${doc.name}${doc.kind === "package" ? ` --package ${doc.package}` : ""} --file <path>`);
@@ -2731,7 +2766,7 @@ function printStatus({ root, agents: data, ws, problems }, verbose) {
2731
2766
  if (a.description) console.log(` ${a.description}`);
2732
2767
  for (const i of a.instances) {
2733
2768
  // 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}` : ""}`);
2769
+ 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
2770
  { const lost = lostLine(i); if (lost) console.log(` ${lost}`); }
2736
2771
  // Feature waiting-on-you: non-null only on a running row; the reader has
2737
2772
  // already validated the message (one line, no control characters).
@@ -2798,7 +2833,9 @@ async function spawnCmd() {
2798
2833
  const yolo = yoloFlag();
2799
2834
  { const herdr = herdrSpawnFlag(); if (herdr) { const e = herdrSettingRemoved(`${herdr} was given`); bail(e.code, e.message); } }
2800
2835
  const backend = valueFlag("backend");
2801
- if (backend !== undefined && backend !== "tmux") bail("E_BAD_ARGS", "--backend must be tmux");
2836
+ // tmux, or a session provider one of the soul's capabilities declares: the kernel resolves the name
2837
+ // against the instance's modules (E_BACKEND_UNKNOWN names the backends available there).
2838
+ 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
2839
  const requestedWork = valueFlag("work");
2803
2840
  const workDir = valueFlag("work-dir"), branch = valueFlag("branch"), repo = valueFlag("repo");
2804
2841
  const checkDirectoryOptions = (work) => {
@@ -3067,7 +3104,8 @@ async function spawnCmd() {
3067
3104
  // #917: what this spawn's start did with Claude's development-channel prompt, as a start answers it.
3068
3105
  ...(r.launchPrompts ? { launchPrompts: r.launchPrompts } : {}),
3069
3106
  ...(wakeSchedule ? { wakeSchedule } : {}), ...(wakeScheduleError ? { wakeScheduleError } : {}),
3070
- tmux: r.tmux || null, backend: "tmux", repo: r.repo || null, harness: r.harness || null,
3107
+ // A home on a session provider carries its backend's name and `session` ({ provider, endpoint }), and no tmux.
3108
+ tmux: r.tmux || null, backend: r.session ? r.backend : "tmux", ...(r.session ? { session: r.session } : {}), repo: r.repo || null, harness: r.harness || null,
3071
3109
  model: r.model || null, parent: r.parentInstance || null,
3072
3110
  sibling: r.siblingInstance || null, relation: r.relation || null,
3073
3111
  spawnOrigin: r.spawnOrigin, attach: r.attach,
@@ -3085,7 +3123,7 @@ async function spawnCmd() {
3085
3123
  });
3086
3124
  return;
3087
3125
  }
3088
- console.log(`Spawned ${r.instance} (${r.work}${r.branch ? `, branch ${r.branch}` : ""})${r.launched ? ` — tmux window "${r.tmux.window}"` : " — not launched"}`);
3126
+ 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
3127
  console.log(` home: ${shortPath(r.home)}`);
3090
3128
  if (r.background === true) console.log(` list: background (from the ${r.backgroundFrom === "flag" ? "--background flag" : "soul"})`);
3091
3129
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
@@ -3095,7 +3133,8 @@ async function spawnCmd() {
3095
3133
  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
3134
  if (!r.launched) console.log(` launch: oats session start --home ${shellQuote(r.home)}`);
3097
3135
  for (const w of r.warnings || []) console.log(` WARNING: ${terminalText(w)}`);
3098
- console.log(` attach: ${r.attach}`);
3136
+ if (r.attach) console.log(` attach: ${r.attach}`);
3137
+ 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
3138
  }
3100
3139
 
3101
3140
  /** The line naming the branch a FAILED_SPAWN_BRANCH_LEFT item speaks of, on a line of its own: the item names
@@ -3586,7 +3625,7 @@ async function sessionCmd() {
3586
3625
  const deployment = flag("deployment");
3587
3626
  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
3627
  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 } });
3628
+ const answer = await resumeSessions({ deployment, plan: args.includes("--plan"), askProviders: !args.includes("--without-provider-inspect"), kernel: { execPath: process.execPath, bin: CLI_BIN } });
3590
3629
  if (JSON_MODE) { jsonOk(answer); return; }
3591
3630
  for (const d of answer.deployments) console.log(`${d.deployment}: ${d.swept ? "swept" : `not swept (${d.reason}${d.code ? `, ${d.code}` : ""})`}`);
3592
3631
  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)}` : ""}`);
@@ -4307,7 +4346,7 @@ function versionCmd() {
4307
4346
  // Phase B: `instance-modules` and `spawn-provider-payload` are advertised only once spawn
4308
4347
  // runs on resolve/materialize (contract §6); a feature the binary does not implement is
4309
4348
  // 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 }));
4349
+ 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
4350
  return;
4312
4351
  }
4313
4352
  console.log(`${OATS_PACKAGE_NAME} ${OATS_VERSION} (desktop API v1)`);
@@ -4787,7 +4826,7 @@ async function serverRouteCmd() {
4787
4826
  // The host's answer decides, not the flag: one that spawned is reported as the spawn it was.
4788
4827
  if (cmd === "spawn" && rest.includes("--preview") && r.preview === true) printSpawnPreview(r, { server: id, soulFetched: r.soulFetched === true });
4789
4828
  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"}`);
4829
+ 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
4830
  console.log(` remote home: ${r.home}`);
4792
4831
  { const line = namingLine(r.naming); if (line) console.log(` name: ${line}`); }
4793
4832
  console.log(` route snapshot: ${r.snapshot ? shortPath(r.snapshot) : "none (see the warning)"}`);
@@ -5187,7 +5226,7 @@ Usage:
5187
5226
  is a unit (a conflicting --harness is refused)
5188
5227
  [--model <id>|@native-default] override the selected model; @native-default
5189
5228
  selects the harness's own model default
5190
- [--backend tmux] [--yolo|--no-yolo] session backend and launch permission option
5229
+ [--backend tmux|<provider>] [--yolo|--no-yolo] session backend (tmux, or a session provider of the soul's capabilities) and launch permission option
5191
5230
  [--background|--no-background] list the instance under Background (presentation
5192
5231
  only); default: the soul's background:, else no
5193
5232
  [--no-launch] [--json] scaffold without launching; JSON result envelope
@@ -441,6 +441,10 @@ A self-contained package has an `oats.json`:
441
441
  - `triggerSources` (optional) declares the capability's
442
442
  [trigger sources](#trigger-sources-triggersources). It is checked only
443
443
  where a source is used, never when the capability loads.
444
+ - `sessionProviders` (optional) declares the session backends the
445
+ capability supplies beside the kernel's tmux
446
+ ([session providers](#session-providers-sessionproviders)). It is checked
447
+ only where a provider is used, never when the capability loads.
444
448
  - Target names never appear in a package manifest.
445
449
 
446
450
  `capability` is the only manifest identity field; it may also carry
@@ -655,11 +659,17 @@ A spawn hook also gets `OATS_TASK`, `OATS_REPO`, `OATS_BRANCH`, `OATS_WORK`,
655
659
  `OATS_TRIGGER_EVENT_FILE`. A launch hook also gets `OATS_HARNESS` and
656
660
  `OATS_PREVIOUS_HARNESS`, and `OATS_LAUNCH_PREVIEW=1` when it runs for a
657
661
  preview (only a preview-aware hook does, below); on a real run
658
- `OATS_LAUNCH_PREVIEW` is not set. A worktree hook also gets the tree
662
+ `OATS_LAUNCH_PREVIEW` is not set. A spawn hook and a launch hook also get
663
+ `OATS_BACKEND` (feature `session-providers`): the session
664
+ backend the instance launches on, `tmux` or the name of a
665
+ [session provider](#session-providers-sessionproviders). A spawn that launches
666
+ nothing (`--no-launch`) sets it too: it is what a later start launches on. A
667
+ kernel without the feature sets none, which means tmux. A worktree hook also gets the tree
659
668
  variables of [The worktree event](#the-worktree-event).
660
669
 
661
670
  A spawn or launch hook also gets `OATS_HARNESS_EXECUTABLE`, for every harness
662
- and the same way in a preview: the absolute real path of the executable the
671
+ on tmux and the same way in a preview (a session provider runs the harness
672
+ itself, so the variable is absent there): the absolute real path of the executable the
663
673
  pane will run, found the way the pane finds it. It is reserved, so a launch
664
674
  configuration's `env` or a trigger cannot set it, and an inherited value is
665
675
  dropped. It doesn't reach the harness's pane, even from an existing server's
@@ -1424,8 +1434,9 @@ waiting clear --producer oats.core --home <home>` from anywhere.
1424
1434
  - **Its own entries only.** oats.core marks its entries by the absolute
1425
1435
  path of its `claude-waiting.sh`. Each run removes only the entries that
1426
1436
  name that path (and any matcher group or event array the removal
1427
- empties), then appends its current ones. Every other key and entry stays
1428
- as it was, in order. The file is written atomically, mode 0600, and only
1437
+ empties), then appends its current ones. Apart from adding `tui` when
1438
+ absent (below), every other key and entry stays as it was, in order.
1439
+ The file is written atomically, mode 0600, and only
1429
1440
  when its content changes. A temp file an interrupted write left behind
1430
1441
  (`.claude/.settings.json.oats-core-<pid>-<ms>.tmp`) is removed by the next
1431
1442
  spawn or start once its writer is gone, so it needs no retirement
@@ -1546,10 +1557,25 @@ that file replaces earlier ones wholesale, even one with no hooks. The
1546
1557
  project `.claude/settings.json` composes with the user's settings (under any
1547
1558
  `CLAUDE_CONFIG_DIR`) and with a `--settings`. So any capability that needs
1548
1559
  Claude settings uses the same managed `<home>/.claude/settings.json` with
1549
- its own marker, never `--settings`. oats.core leaves
1560
+ marked entries for its hooks, never `--settings`. oats.core leaves
1550
1561
  `.claude/settings.local.json` to Claude Code, which writes its "don't ask
1551
1562
  again" permission rules there.
1552
1563
 
1564
+ **Renderer selection.** In the same merge, at spawn and every launch,
1565
+ oats.core adds `"tui": "default"` when the project's settings have no `tui`
1566
+ key. Any existing value, including a non-string, is kept: a scalar has no
1567
+ marker to distinguish the person's choice from oats.core's. Any `tui` in
1568
+ Claude's merged settings skips its fullscreen-renderer offer, which can
1569
+ otherwise stop an unattended agent before it receives a wake. `"default"`
1570
+ selects the classic renderer used by the launch-prompt captures and keeps
1571
+ tmux scrollback. The cost: agent panes use Claude's classic renderer even
1572
+ where Claude defaults to fullscreen, and the project setting overrides a
1573
+ user-level `"tui": "fullscreen"`. An existing project `tui` still wins.
1574
+ A pass that changes nothing does not rewrite the file. The existing file
1575
+ refusals, preview behaviour and non-Claude behaviour above apply to `tui`
1576
+ too. If oats.core ever stops adding it, existing homes keep the key until
1577
+ respawn.
1578
+
1553
1579
  **Limits.**
1554
1580
 
1555
1581
  - If the user's Claude configuration sets `disableAllHooks` or
@@ -1944,3 +1970,325 @@ whole poll, resolution included, gets 35 s, and polls run only while they can
1944
1970
  end within 50 s of the tick's start. Answer from a cache or a quick query: a
1945
1971
  source slower than that should cache.
1946
1972
 
1973
+ ## Session providers (`sessionProviders`)
1974
+
1975
+ A kernel that lists the feature `session-providers` in `oats version --json`
1976
+ has this contract. tmux is the kernel's own session backend. A capability can supply another one, a
1977
+ **session provider**: the instance's agent then runs wherever the provider
1978
+ runs it (a thread of another product, a remote runner), and the kernel reaches
1979
+ it through four of the capability's own commands. The kernel keeps what a
1980
+ backend must not own: the receipts and the authority check, the lifecycle
1981
+ claims, the refusals and the JSON answers. What an operator sees is in
1982
+ [execution-targets.md](execution-targets.md#session-providers).
1983
+
1984
+ ```json
1985
+ "commands": { "session-launch": "bin/session.mjs launch", "session-inspect": "bin/session.mjs inspect",
1986
+ "session-input": "bin/session.mjs input", "session-stop": "bin/session.mjs stop",
1987
+ "session-inspect-many": "bin/session.mjs inspect-many" },
1988
+ "sessionProviders": {
1989
+ "bb": {
1990
+ "description": "Runs the agent as a bb thread",
1991
+ "harnesses": ["claude"],
1992
+ "commands": { "launch": "session-launch", "inspect": "session-inspect", "input": "session-input",
1993
+ "stop": "session-stop", "inspectMany": "session-inspect-many" }
1994
+ }
1995
+ }
1996
+ ```
1997
+
1998
+ - The **name** is 1 to 40 lowercase letters, digits and dashes, starting with
1999
+ a letter or digit. `tmux`, `session-provider` and `herdr` are reserved. It
2000
+ is what `--backend` takes, and what a hook reads in `OATS_BACKEND`. At most
2001
+ 16 providers.
2002
+ - **`commands`** names `launch`, `inspect`, `input` and `stop`, and optionally
2003
+ `inspectMany` and `check`. Each value is a key of the manifest's
2004
+ `commands`.
2005
+ - **`harnesses`** lists the harnesses the provider runs (1 to 16 names). A
2006
+ spawn or a start on another one is refused `E_BACKEND_HARNESS`.
2007
+ - **`description`** is optional: one line of at most 200 characters.
2008
+ - No other key.
2009
+
2010
+ **Containment.** A malformed `sessionProviders` never refuses the capability:
2011
+ it is validated where a provider is used. A problem inside one provider
2012
+ disables that provider only, and `--backend <name>` then answers
2013
+ `E_BACKEND_UNKNOWN` with the problem. `oats capabilities show <name> --json`
2014
+ adds `sessionProviders` (as declared) and, when there is one,
2015
+ `sessionProviderProblems: [{provider, pointer, message}]`.
2016
+ [`docs/capability-manifest.schema.json`](capability-manifest.schema.json)
2017
+ carries the same shape; that a verb names one of the manifest's commands is
2018
+ checked by the kernel only.
2019
+
2020
+ **One name, one meaning.** A provider is selected among the capabilities of
2021
+ the instance being spawned. Two of them declaring the same name is
2022
+ `E_BACKEND_AMBIGUOUS`: compose only one.
2023
+
2024
+ ### The call
2025
+
2026
+ Every call runs the **home's own copy** of the capability:
2027
+ `node <home>/.oats/modules/<capability>/<script> <args>`. **Its working
2028
+ directory is not the home** (it is the filesystem root): read the home from
2029
+ the request (`input.home`) or `OATS_INSTANCE_HOME`, and leave
2030
+ nothing of the call's own running in the home (the session's processes work
2031
+ there; a helper of your command must not). OATS looks for
2032
+ processes working in a home before it resumes a lost session and before it
2033
+ retires the home, and a provider's call must never be one of them.
2034
+
2035
+ - **Environment:** what a lifecycle hook of the capability gets in that home
2036
+ ([Commands and hooks](#commands-and-hooks)): `OATS_INSTANCE`,
2037
+ `OATS_INSTANCE_HOME`, `OATS_SETTINGS` (the settings captured at spawn),
2038
+ `OATS_META`, `OATS_CLI_BIN` and the rest, with `OATS_EVENT=session` and
2039
+ `OATS_BACKEND=<name>`.
2040
+ - **stdin:** one JSON request,
2041
+ `{ "schemaVersion": 1, "phase": "session", "capability": "<id>", "provider": "<name>", "verb": "<verb>", "input": { … } }`.
2042
+ - **stdout:** exactly one JSON document of at most 1 MiB, the same five header
2043
+ keys echoed, then `"ok": true, "result": { … }` or
2044
+ `"ok": false, "error": { "code": "E_…", "message": "…" }`. No other key.
2045
+ A refusal's code is `E_` followed by capitals, digits and underscores.
2046
+ - **Exit status 0**, for a result and for a refusal.
2047
+ - **Timeouts:** launch 120 s, stop 20 s plus the grace it is given, every
2048
+ other verb 20 s. The command is killed at its timeout.
2049
+ - **Process group:** OATS runs each command in a process group of its own,
2050
+ and ends the whole group (SIGKILL) at the timeout, and when the `oats`
2051
+ command that ran a `launch`, an `input` or a `stop` was itself killed
2052
+ while it waited (the next stop, start, input or retire of the home does
2053
+ it, before it calls you again). A stop also waits for an `input` that is
2054
+ being sent, up to its timeout, before it asks you to `stop`. **Run your helpers inside that group and never detach
2055
+ them** (no `setsid`, no daemon): a helper that escapes it can start a
2056
+ session OATS has no record of.
2057
+ - stderr is never read.
2058
+
2059
+ A call that does not end that way (another exit status, a signal, the
2060
+ timeout, no or malformed JSON, a wrong envelope, a result that breaks its
2061
+ verb's rules) is a **failed call**. A failed call is never read as an answer:
2062
+ an inspect that failed is never "stopped".
2063
+
2064
+ | Verb | A failed call, or a refusal the kernel does not relay |
2065
+ |---|---|
2066
+ | `inspect`, `inspectMany` | `E_SESSION_UNAVAILABLE`; the status row reads `running: null`, `runtimeState: "unreachable"` |
2067
+ | `check` | the readiness item reads `unknown`; a launch is refused `E_BACKEND_NOT_READY` |
2068
+ | `input` | `E_SESSION_INPUT_FAILED` |
2069
+ | `stop` | `E_SESSION_STOP_FAILED` |
2070
+ | `launch` | `E_SESSION_START_FAILED` |
2071
+
2072
+ The kernel relays these refusals under the provider's own code: from
2073
+ `launch`, any `E_BACKEND_*`; from `input`, `E_SESSION_PROMPT_OPEN` and
2074
+ `E_SESSION_INPUT_QUEUED`. The message of any refusal is carried into the
2075
+ kernel's, made safe to print and cut to 500 characters.
2076
+
2077
+ ### launch
2078
+
2079
+ In:
2080
+
2081
+ ```json
2082
+ { "home": "/abs/home", "instance": "dev-a", "harness": "claude", "model": "id-or-null", "yolo": true,
2083
+ "env": [ { "name": "OATS_INSTANCE", "value": "dev-a", "source": "kernel" },
2084
+ { "name": "AWEB_IDENTITY_HOME", "value": "/abs/…", "source": "capability", "capability": "oats.aweb" },
2085
+ { "name": "REGION", "value": "eu", "source": "launch-config" },
2086
+ { "name": "API_KEY", "value": "…", "source": "launch-config-reference", "secret": true } ],
2087
+ "unset": ["NAME"],
2088
+ "pathPrepend": ["/abs/home/.oats/bin"],
2089
+ "args": ["--flag", "value"],
2090
+ "promptFile": "/abs/home/TASK.md",
2091
+ "previous": null }
2092
+ ```
2093
+
2094
+ - `env` is every variable the launch sets, in the order a tmux launch sets
2095
+ them. `source` says where each comes from: `kernel` (the instance's
2096
+ identity, a trigger's event file), `capability` (a hook's `env`, with the
2097
+ `capability` that owns it), `launch-config` (a launch configuration's
2098
+ literal value) or `launch-config-reference` (a launch configuration's
2099
+ `fromEnv` or `fromFile`: a secret source, marked `secret: true`, its value
2100
+ read on this host).
2101
+ - `unset` lists the names the launch removes: declared by a capability and
2102
+ left out of this launch.
2103
+ - `pathPrepend` is the home's kernel shim directory. Put it first on the
2104
+ agent's `PATH`, so its plain `oats` is the kernel that launched it.
2105
+ - `args` is the launch configuration's arguments, then the capabilities'
2106
+ launch arguments for the harness, as the words a shell would hand it
2107
+ (arguments the kernel cannot read as words are refused,
2108
+ `E_BACKEND_LAUNCH_ARG`, naming the capability). The kernel's own choices are never in
2109
+ it: they are `model` (null: the harness's default), `yolo` (`true`,
2110
+ `false`, or `null` when nobody chose) and the prompt.
2111
+ - `promptFile` is the home's `TASK.md`: the briefing a fresh conversation
2112
+ starts on.
2113
+ - `previous` is the endpoint of the session a start or a restart replaces;
2114
+ `null` for the home's first launch. The kernel has asked you to stop it
2115
+ just before, always (a restart's stop, once more for a home OATS had
2116
+ stopped, and for a session you answered as gone too: an input that reached
2117
+ it since may have had you restart it).
2118
+
2119
+ **A provider that cannot carry an env entry, an argument or `unset`
2120
+ refuses, naming it** (`E_BACKEND_LAUNCH_ENV`, `E_BACKEND_LAUNCH_ARG`). It
2121
+ never drops one silently, and it never stores a `secret` value where others
2122
+ can read it.
2123
+
2124
+ Out: `{ "endpoint": { … } }`. The endpoint is a JSON object whose canonical
2125
+ JSON is at most 4 KiB (4096 bytes). **It names one session: answer an
2126
+ endpoint you never answered before for that home** (a new thread id, not a
2127
+ locator a later session takes over). The kernel stops a session by its
2128
+ endpoint, also after a newer one was launched. The kernel records it as given, in the
2129
+ home's `instance.json` and its receipt, and hands it back on every call. It
2130
+ holds **locators only, never a credential**.
2131
+
2132
+ The kernel refuses, before anything is created, a launch configuration that
2133
+ declares `executable` for a provider backend (`E_BACKEND_LAUNCH_ARG`): the
2134
+ provider runs the harness itself.
2135
+
2136
+ ### inspect and inspectMany
2137
+
2138
+ `inspect` in: `{ "home", "endpoint" }`. Out:
2139
+ `{ "present": true|false, "state": "unknown"|"shell"|"stopped", "running": true|false|null, "open"?: { "label", "url" } }`,
2140
+ exactly those keys.
2141
+
2142
+ | The session | present | state | running |
2143
+ |---|---|---|---|
2144
+ | a turn or a start is in progress | true | `unknown` | true |
2145
+ | there, and the provider cannot tell a live idle session from a settled one | true | `unknown` | null |
2146
+ | gone: missing, deleted, or in error with nothing running | false | `stopped` | false |
2147
+ | the harness ended and something else holds the session, as a terminal left at its shell | true | `shell` | false |
2148
+
2149
+ A session that is not there (`present: false`) is `stopped` and runs nothing:
2150
+ any other answer with `present: false` is outside the table, and is read as
2151
+ no answer (unavailable), like a word outside the contract.
2152
+
2153
+ Map only what the product shows; never infer. **A session that is gone on a
2154
+ home OATS did not stop is a lost session**: OATS resumes it through `input`,
2155
+ under its cap ([below](#what-the-kernel-does-around-the-verbs)). So answer a
2156
+ session whose run ended in error as gone, not as `shell`, when your product
2157
+ restarts it on the next input. `open` is what a client may
2158
+ show instead of a terminal: a one-line `label` of at most 100 characters and
2159
+ an `http` or `https` `url` of at most 2000, without credentials.
2160
+
2161
+ `inspectMany` (optional) in:
2162
+ `{ "homes": [ { "home", "instance", "endpoint" } ] }`, at most 200. Out:
2163
+ `{ "results": [ … ] }`, one per home in the same order, each an inspect
2164
+ result or `{ "error": { "code", "message" } }`. `oats status` calls it once
2165
+ per group of homes that share the capability's module copy (same digest),
2166
+ the provider and the settings; the call's environment is the group's first
2167
+ home's. Each entry is judged as one `inspect` answer would be. A batch that
2168
+ fails or is not one result per home, and an entry that is neither a result
2169
+ nor a refusal, fall back to that home's own `inspect`, never to "stopped".
2170
+ Without `inspectMany`, status calls `inspect` per home.
2171
+
2172
+ **The kernel never calls inspect for a home OATS stopped** (below).
2173
+
2174
+ ### input
2175
+
2176
+ In: `{ "home", "endpoint", "text" }`. Out: `{ "submitted": true, "verified": true|false }`
2177
+ **only when the text was dispatched** to the session. `submitted` is never
2178
+ `false` in a result: an input that was not dispatched is a refusal.
2179
+
2180
+ - A session with a prompt open (a permission prompt, a question) is not
2181
+ answered by an input: refuse `E_SESSION_PROMPT_OPEN` and send nothing.
2182
+ Otherwise any mail could approve a permission.
2183
+ - An input the product queued instead of dispatching is not a submission:
2184
+ withdraw it and refuse `E_SESSION_INPUT_QUEUED`.
2185
+
2186
+ Both reach the caller as they are, with `ok: false`. The messaging broker
2187
+ leaves such a mail unread; a scheduled wake records it not delivered.
2188
+
2189
+ ### stop
2190
+
2191
+ In: `{ "home", "endpoint", "graceSeconds", "launchSent"? }`. Out: `{ "stopped": true }`.
2192
+ `endpoint` is `null` when the kernel has no endpoint for a session you may
2193
+ have started: a launch whose answer was lost, and a launch it sent whose
2194
+ spawn or start ended before recording your answer (it was killed while you
2195
+ launched). Then stop whatever live session is rooted at the home, and answer
2196
+ `stopped: true` also when there is none. The input then also carries
2197
+ `"launchSent": "<instant>"`, the time the kernel recorded for that launch,
2198
+ when it has one: what the launch started was created at or after it, so you
2199
+ can leave alone what was in the home's place before (a person's own session
2200
+ there). **The kernel relies on this stop**: it is the only way a session
2201
+ started by a killed spawn is ever stopped.
2202
+
2203
+ ### check (optional)
2204
+
2205
+ The provider's readiness. In: `{ "home": "/abs/home" | null, "soul": "<name>" | null, "settings": { … } }`:
2206
+ a home, or, before any home exists, a soul. Out:
2207
+ `{ "status": "ready" | "needs-configuration" | "authorization-required" | "unavailable", "problems": [ { "code", "message" } ], "warnings": [ { "code", "message" } ] }`
2208
+ (`warnings` optional; no problem on `ready`). Say where a credential comes
2209
+ from, never print it.
2210
+
2211
+ - `oats readiness` relays the answer as a `providers` item, the shape a
2212
+ binding check's answer has: for a home, its own backend's, required; for a
2213
+ soul, each provider its capabilities offer, not required (the soul can
2214
+ launch on tmux).
2215
+ - **The kernel asks it right before every launch** (a spawn's, a start's, a
2216
+ restart's before its stop). A status other than `ready` refuses the launch:
2217
+ with the first problem's code when that is an `E_BACKEND_*` code, else
2218
+ `E_BACKEND_NOT_READY`, the message carrying your problems. A check that
2219
+ fails or answers outside these words is not ready.
2220
+
2221
+ ### Requirements by backend (`requires[].backends`)
2222
+
2223
+ A harness-package requirement (`requires: [{ harness, package, … }]`) is for
2224
+ the harness install on this host. A row may say which backends it is for:
2225
+ `"backends": ["tmux"]`, `["session-provider"]` (any session provider) or
2226
+ both. Without the key it applies to every backend, a provider's launch
2227
+ included, where it is probed on this host. It is a key of its own, never
2228
+ inside `when`, whose keys are the capability's settings. A kernel without
2229
+ `session-providers` knows no such key and applies the row to every launch:
2230
+ a package that uses `backends` raises its OATS floor to a kernel that lists
2231
+ the feature.
2232
+
2233
+ ### What the kernel does around the verbs
2234
+
2235
+ - **Stop stays stopped.** At every OATS stop (`oats instance stop`, a
2236
+ restart's stop, a retire, `oats host run`'s shutdown) the kernel records
2237
+ `stoppedAt` in the home's receipt **before** it calls `stop`, and a start
2238
+ clears it. While it is set, inspect answers stopped (`present: false`,
2239
+ `running: false`) without calling the provider, and every input (a
2240
+ person's `oats session input`, a scheduled wake, a client, the messaging
2241
+ broker) is refused `E_SESSION_NOT_RUNNING` before any call. A provider
2242
+ whose product restarts a session on its next input can rely on this.
2243
+ - **Hooks first.** The capabilities' spawn hooks (at a spawn) and launch
2244
+ hooks (at a start or a restart) run before `launch`, as before a tmux
2245
+ window, with `OATS_BACKEND`.
2246
+ - **Retire** records `stoppedAt`, calls `stop`, then runs the retire hooks
2247
+ and removes the home. The retire hook is not handed the endpoint: a
2248
+ provider that archives its session finds it by the home.
2249
+ - **A launch that fails** leaves the home as it was (stopped, or never
2250
+ launched; a spawn is rolled back). When its answer was lost, the kernel
2251
+ calls `stop` with `endpoint: null` first.
2252
+ - **A launch that was sent and never recorded.** The kernel writes in the
2253
+ home's receipt that a launch is being sent, right before it calls you, and
2254
+ takes that away when it has recorded your endpoint. A spawn or a start
2255
+ that is killed while you launch leaves it there: the home then reads as
2256
+ unknown, and the next stop, start or retire first calls `stop` with
2257
+ `endpoint: null`.
2258
+ - **Which stop it was** is on the home's stop receipt, never a field of
2259
+ yours: `oats host run`'s shutdown is a loss that the sweep resumes, an
2260
+ operator's stop is the intent that keeps the home down.
2261
+ - **A lost session is resumed through `input`.** A home whose session you
2262
+ answer as gone, and that OATS did not stop, is resumed by the sweep with
2263
+ one notice, and any other input to it is a resume too. The kernel counts
2264
+ each against the home's cap before it calls `input` (at most 3 in an hour,
2265
+ within one boot), refuses at the cap with `E_SESSION_NOT_RUNNING` without
2266
+ calling you, and first waits (a resume) or refuses (an input) while a
2267
+ process still works in the home. So an `inspect` precedes every `input` to
2268
+ a home OATS did not stop (the resume of a home stopped with the host sends
2269
+ its notice without one).
2270
+ An input you refuse (`ok: false`: nothing was sent) is not counted. One
2271
+ whose call fails or answers outside the rules stays counted: you may have
2272
+ restarted the session on it.
2273
+ - **`stop` is idempotent.** The kernel calls it again wherever it needs the
2274
+ session gone: an operator's stop of a home that is already stopped (how a
2275
+ stop you did not confirm is finished), a start of a stopped home before
2276
+ its launch, and after an input that crossed a stop (an input holds no
2277
+ claim: when a stop or a restart lands while one is being sent, the kernel
2278
+ asks you to stop that session again and does not deliver the input,
2279
+ whatever you answered to it, a refusal included). After a restart it asks
2280
+ that only when the new session has another endpoint: where you hand a
2281
+ restart the same locator again, that locator is the new session's, and the
2282
+ kernel tells the two apart by its own record of the start. An input that
2283
+ is in flight when a start begins its launch is such a crossing too.
2284
+ Answer `stopped: true` for a session that is already stopped.
2285
+ - **A spawn holds the home while you launch.** From before the home can be
2286
+ acted on until your launch's endpoint is recorded (or the spawn is undone),
2287
+ the spawn holds the home's lifecycle claim: a stop, a start or a retire
2288
+ that arrives meanwhile is refused as busy, never answered as if there were
2289
+ nothing to stop.
2290
+ - **Nothing of your endpoint leaves the host.** A status row carries the
2291
+ capability and, on its own host only, the endpoint's `threadId` when it
2292
+ is a string; the endpoint is on local inspect, spawn and start answers.
2293
+ `open` is relayed: make its `url` one a viewer may open, never your API's
2294
+ address off its host, and put no token in either.