@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
@@ -14,7 +14,7 @@ import { spawnSync } from "node:child_process";
14
14
  import { accessSync, constants as fsConstants, existsSync, lstatSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
15
15
  import { delimiter, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
16
16
  import { capabilityManifests, skillEntriesIn, kernelBin, sessionDefaults, homeLaunchLayers, instanceSoulDir, launchConfigsAt, preparedSoulIdOf, stableSoulId, launchFolderTrust, previewLaunchEnvironment, removedLaunchEnv, homeDeclaredLaunchEnv, launchReportFor, manifestOperations, parseYamlNested, servedIdentityOf, teamEnv, upgradeHomeMeta, withConfigFile } from "./core.mjs";
17
- import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
17
+ import { agentDirOf, discoverOrStandalone, ensureWorkspaceSoul, findSoulEntry, homeSandboxSource, liveTeams, prepareInstance, resolutionContractWarnings, soulCopyDigests, soulsOffered } from "./instance-resolution.mjs";
18
18
  import { declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
19
19
  import { kernelCompatibility, unsafeRelPath } from "./resolve.mjs";
20
20
  import { compareCodepoints, decodeText, FILES_PER_SKILL, SKILL_DOC_BUDGET, skillDocDescription, TEXT_LIMIT } from "./capability-show.mjs";
@@ -34,6 +34,10 @@ import { readInstancePin } from "./instance-pin.mjs";
34
34
  /** Bounds of a provider check's answer (bytes, nesting, entries), as the released binding wire set them. */
35
35
  const BINDING_LIMITS = Object.freeze({ maxBytes: 1024 * 1024, maxDepth: 32, maxEntries: 16384 });
36
36
  import { parseStrictJson } from "./canonical-json.mjs";
37
+ import { checkProviderSession, homeSessionProvider, offeredSessionProviders, recordsSessionProvider, sessionProvidersOf } from "./session-providers.mjs";
38
+ import { capabilityRuntimeOf, kernelModuleDir, moduleCopyProblemAt, providerHomeTrust, runDirOf } from "./home-integrity.mjs";
39
+ import { treeDisagreement } from "./tree-copy.mjs";
40
+ import { homeSandboxAllowances, sandboxWritePathsRefusal } from "./sandbox-allowances.mjs";
37
41
  import { sameRepo } from "./repo-moves.mjs";
38
42
  import { kernelNode } from "./stable-node.mjs";
39
43
 
@@ -92,11 +96,17 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
92
96
  meta = upgradeHomeMeta(meta, realHome);
93
97
  // Only the home's own module copies: without <home>/.oats/modules the kernel's
94
98
  // manifest lookup would fall through to a classic config chain — never here.
99
+ // A provider home's modules are the ones its receipt records, read from the kernel's copies of
100
+ // them (lib/home-integrity.mjs): a home whose own modules directory or record of them is gone
101
+ // is read the same.
102
+ const trust = providerHomeTrust(realHome), trustedRows = trust ? capabilityRuntimeOf(realHome, meta, trust) : [];
95
103
  let manifests = {}; const loadProblems = [];
96
- if (existsSync(join(realHome, ".oats", "modules"))) {
104
+ // (A provider home whose receipt holds no composition lists no module: it says why, and what to do.)
105
+ if (trust?.problem) loadProblems.push({ code: "module-copy-untrusted", message: trust.problem });
106
+ if (trust || existsSync(join(realHome, ".oats", "modules"))) {
97
107
  try { manifests = capabilityManifests(realHome); } catch (e) { loadProblems.push({ code: "module-manifest-invalid", message: e.message }); }
98
108
  }
99
- const modules = obj(meta.modules) ? meta.modules : {};
109
+ const modules = trust ? Object.fromEntries(Object.entries(trust.composition?.modules ?? {}).map(([id, m]) => [id, { from: m.from ?? null }])) : obj(meta.modules) ? meta.modules : {};
100
110
  const agentsRoot = dirname(dirname(dirname(realHome)));
101
111
  const deployment = dirname(agentsRoot);
102
112
  // The deployment's removed team keys (team model 3) refuse every reader of its oats-local.yaml, before
@@ -148,9 +158,11 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
148
158
  soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
149
159
  ...(obj(ws.soul?.package) && typeof ws.soul.package.id === "string" ? { package: { id: ws.soul.package.id, soul: ws.soul.name ?? meta.agent, version: ws.soul.package.version ?? null, commit: ws.soul.package.commit ?? ws.soul.commit ?? null, integrity: ws.soul.package.digest ?? null } } : {}) },
150
160
  workspace: { key: ws.key ?? null, name: typeof ws.name === "string" ? ws.name : discovery?.workspace?.name ?? null, deployment, commit: ws.commit ?? null, standalone: ws.standalone === true },
151
- modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
152
- payloads: obj(meta.providers) ? meta.providers : {},
153
- payloadOrigins: Object.fromEntries((Array.isArray(meta.capabilities) ? meta.capabilities : []).filter((c) => c && typeof c.id === "string").map((c) => [c.id, obj(c.settingsOrigins) ? c.settingsOrigins : {}])),
161
+ // (A provider home's modules are run from the kernel's copies of them: lib/home-integrity.mjs.)
162
+ modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: runDirOf(realHome, name, trust) })),
163
+ // (A provider home's settings are its receipt's rows', never its own record's: lib/home-integrity.mjs.)
164
+ payloads: trust ? Object.fromEntries(trustedRows.map((c) => [c.id, obj(c.settings) ? c.settings : {}])) : obj(meta.providers) ? meta.providers : {},
165
+ payloadOrigins: Object.fromEntries((trust ? trustedRows : Array.isArray(meta.capabilities) ? meta.capabilities : []).filter((c) => c && typeof c.id === "string").map((c) => [c.id, obj(c.settingsOrigins) ? c.settingsOrigins : {}])),
154
166
  slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
155
167
  lock: null, prepared: null,
156
168
  };
@@ -524,6 +536,9 @@ export function inspectDocument(t, { kernel }) {
524
536
  return {
525
537
  operationsApi: INSPECT_OPERATIONS_API, kernel, subject: t.subject, workspace: t.workspace,
526
538
  souls: [soulRow(t)], layers, capabilities,
539
+ // Feature session-providers: the session backends this soul's (or home's) capabilities supply
540
+ // beside the kernel's own, what `--backend` takes here: [{ name, capability }].
541
+ ...sessionProviderKeys(t),
527
542
  // The capabilities the soul turned off (feature desktop-facts): its `off` over a workspace/team entry
528
543
  // (reason "off"), or a `<slot>: none` that dropped a workspace default (reason "slot-none", slot).
529
544
  capabilitiesOff: (t.turnedOff || []).map(({ name, reason, slot, overrides }) => ({ id: name, off: true, from: "soul", reason, ...(slot ? { slot } : {}), overrides })),
@@ -674,6 +689,14 @@ const item = (subject, status, { required = true, reason = null, producer = "ker
674
689
  ({ subject, status, required, reason: bounded(reason), producer, evidence, remedy: bounded(remedy), ...rest,
675
690
  ...(Array.isArray(rest.problems) ? { problems: rest.problems.map((p) => (obj(p) && typeof p.message === "string" ? { ...p, message: bounded(p.message) } : p)) } : {}) });
676
691
 
692
+ /** `sessionProviders` of an inspect answer: the session backends the target's capabilities supply
693
+ * and a spawn can select there, `[{ name, capability }]` sorted by name (lib/session-providers.mjs
694
+ * offeredSessionProviders over the target's modules). A malformed declaration is none: what is
695
+ * wrong with it is `oats capabilities show`'s to say. */
696
+ function sessionProviderKeys(t) {
697
+ const { providers } = offeredSessionProviders((t.modules || []).filter((x) => x.manifest).map((x) => ({ id: x.name, manifest: x.manifest })));
698
+ return { sessionProviders: providers.map(({ name, capability }) => ({ name, capability })) };
699
+ }
677
700
  /** The team/workspace facts a provider receives, as hooks get them (teamEnv), and the soul's name and
678
701
  * stable id as its hooks and dispatched commands get them. Every ambient OATS_* is removed first. */
679
702
  function providerEnv(t, capability, settings) {
@@ -697,12 +720,16 @@ function moduleExecutable(dir, script) {
697
720
  * directory, the script contained in it (moduleExecutable), one JSON `request` on stdin, the
698
721
  * environment providerEnv's for the request's `settings`, SIGKILL at `timeoutMs`, at most
699
722
  * BINDING_LIMITS of stdout, decoded as exactly one strict JSON document (whitespace around it
700
- * allowed). → { doc } or { failure: "no-command" | "no-executable" (script) | "incomplete"
723
+ * allowed). A provider home's OWN copy is never run (the kernel runs its copy of it,
724
+ * lib/home-integrity.mjs, which a caller is handed as `dir`): "no-executable", with `problem`.
725
+ * → { doc } or { failure: "no-command" | "no-executable" (script) | "incomplete"
701
726
  * (timedOut, signal, overflow) | "exit" (status) | "invalid" }. The caller judges the document. */
702
727
  export function runModuleCommand(t, mod, dir, command, request, { timeoutMs = 30000 } = {}) {
703
728
  const spec = command ? mod.manifest?.commands?.[command] : null;
704
729
  if (typeof spec !== "string" || !spec.trim()) return { failure: "no-command" };
705
730
  const [script, ...args] = spec.trim().split(/\s+/);
731
+ const untrusted = dir ? moduleCopyProblemAt(dir) : null;
732
+ if (untrusted) return { failure: "no-executable", script, problem: untrusted };
706
733
  const file = dir ? moduleExecutable(dir, script) : null;
707
734
  if (!file) return { failure: "no-executable", script };
708
735
  // The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
@@ -736,7 +763,7 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
736
763
  input: { context: { kind: "workspace", workspace: t.workspace.key, deployment: t.deployment, soul: t.soul.name, instance: t.meta?.instance ?? null, home: t.home }, action: { kind: "readiness" } } };
737
764
  const run = runModuleCommand(t, mod, dir, check, request, { timeoutMs });
738
765
  if (run.failure === "no-command") return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
739
- if (run.failure === "no-executable") return unavailable("resource-not-found", `${mod.name}: the check executable ${run.script} is unavailable`);
766
+ if (run.failure === "no-executable") return unavailable("resource-not-found", run.problem ?? `${mod.name}: the check executable ${run.script} is unavailable`);
740
767
  if (run.failure === "incomplete") return unavailable("provider-unavailable", `${mod.name} check did not complete${run.timedOut || run.signal ? " in time" : ""}`);
741
768
  if (run.failure === "exit") return unavailable("provider-unavailable", `${mod.name} check exited ${run.status}`);
742
769
  const invalid = () => unavailable("provider-unavailable", `${mod.name} check answered invalid binding data`);
@@ -818,6 +845,10 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
818
845
  /** `oats readiness --json` on the workspace model. */
819
846
  export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
820
847
  const installed = [], configured = [], member = [], providers = [];
848
+ // A provider home whose receipt holds no composition (lib/home-integrity.mjs): the kernel runs
849
+ // none of its capabilities, so it lists no module below. It is not ready, and says why.
850
+ const untrusted = t.home ? providerHomeTrust(t.home)?.problem : null;
851
+ if (untrusted) installed.push(item(t.soul.name, "fail", { producer: "instance modules", code: "module-copy-untrusted", reason: untrusted, remedy: `oats retire ${t.subject.instance} --force, then spawn it again (its retire hooks cannot be identified, so --force removes the home without running them)` }));
821
852
  const cap = (id) => ({ capability: { id } });
822
853
  if (t.resolutionError && !isTeamRefusal(t.resolutionError)) {
823
854
  installed.push(item(t.soul.name, "fail", { producer: "workspace resolution", code: t.resolutionError.code, reason: t.resolutionError.message, evidence: t.resolutionError.details, remedy: "oats sync (the lock must provide every package capability the soul resolves)" }));
@@ -870,6 +901,38 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
870
901
  }
871
902
  else providers.push(item(mod.name, "unknown", { producer: "provider binding check", result: null, problems: out.problems, reason: out.problems[0]?.message ?? null, ...cap(mod.name) }));
872
903
  }
904
+ // A session provider's own readiness (lib/session-providers.mjs, the optional `check` command),
905
+ // relayed verbatim as a providers item, as a binding check is. For a home: the provider it runs
906
+ // on, required. For a soul: every provider its capabilities offer, not required (the soul can
907
+ // launch on tmux); a member capability's runs from a spawned home, as its binding check does.
908
+ for (const mod of t.modules) {
909
+ const offered = Object.values(sessionProvidersOf(mod.manifest).providers).filter((p) => p.commands.check);
910
+ for (const provider of offered) {
911
+ const onIt = t.home ? t.meta?.backend === provider.name && t.meta?.session?.provider === mod.name : false;
912
+ if (t.home && !onIt) continue;
913
+ const subject = `${mod.name} session backend ${provider.name}`;
914
+ const push = (status, rest) => providers.push(item(subject, status, { required: !!t.home, producer: "session provider check", ...rest, ...cap(mod.name) }));
915
+ const unknown = (code, message) => push("unknown", { result: null, problems: [{ code, message }], reason: message });
916
+ if (Date.now() >= deadline) { unknown("time-budget-exhausted", `time budget exhausted: the providers check stops after ${Math.round(budgetMs / 1000)} s per readiness read`); continue; }
917
+ let binding;
918
+ if (t.home) {
919
+ const found = homeSessionProvider(t.home, t.meta, mod.name, provider.name);
920
+ if (found.problem) { unknown("resource-not-found", found.problem); continue; }
921
+ binding = found.binding;
922
+ } else {
923
+ let dir = null;
924
+ if (mod.module && t.lock) { try { dir = await ensureModuleTree(t.deployment, mod.module, t.lock, { catalog, remoteOptions }); } catch (e) { unknown(e.code || "provider-unavailable", e.message); continue; } }
925
+ if (!dir) { unknown("resource-not-found", `${mod.name}: a member module runs from a spawned home; inspect an instance (--home) for its check`); continue; }
926
+ const settings = obj(t.payloads[mod.name]) ? t.payloads[mod.name] : {};
927
+ binding = { home: null, meta: {}, capability: mod.name, name: provider.name, provider, moduleDir: dir, cap: { id: mod.name, settings }, digest: null,
928
+ env: { ...providerEnv(t, mod.name, settings), OATS_EVENT: "session", OATS_BACKEND: provider.name } };
929
+ }
930
+ const checked = checkProviderSession(binding, { home: t.home ?? null, soul: t.home ? null : t.soul.name, settings: binding.cap.settings }, { timeoutMs: Math.max(1, Math.min(20_000, deadline - Date.now())) });
931
+ if (checked.unavailable) { unknown("provider-unavailable", checked.unavailable); continue; }
932
+ const status = PROVIDER_STATUS_ITEM[checked.result.status];
933
+ push(status, { result: checked.result, reason: status === "pass" ? null : checked.result.problems[0]?.message ?? `the provider reports ${checked.result.status}` });
934
+ }
935
+ }
873
936
  const checks = { installed: { status: roll(installed), items: installed }, configured: { status: roll(configured), items: configured }, member: { status: roll(member), items: member }, providers: { status: roll(providers), items: providers } };
874
937
  const requiredStatuses = Object.values(checks).flatMap((c) => c.items.filter((i) => i.required).map((i) => i.status));
875
938
  const byCapability = [...new Set(Object.values(checks).flatMap((c) => c.items.map((i) => i.capability?.id).filter(Boolean)))].sort().map((id) => {
@@ -878,9 +941,44 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
878
941
  return { capability: { id }, checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
879
942
  ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
880
943
  });
944
+ // A home on a session provider: what its next launch may widen its harness's sandbox by
945
+ // (lib/sandbox-allowances.mjs), computed as a start computes it, from the deployment's
946
+ // configuration as it is now. Each host with the capability and the setting that asked for it,
947
+ // each path with its reason, what is missing and what was left out; or why there is none.
948
+ let sandbox;
949
+ if (t.home && recordsSessionProvider(t.meta)) {
950
+ const source = await homeSandboxSource(t.home, { remoteOptions });
951
+ if (source.unavailable) sandbox = { unavailable: source.unavailable };
952
+ else {
953
+ try {
954
+ sandbox = homeSandboxAllowances({ source, home: realpathSync(t.home), moduleNames: Object.keys(obj(t.meta.modules) ? t.meta.modules : {}) });
955
+ // What a start would refuse of the paths, read without creating one.
956
+ const refused = sandboxWritePathsRefusal(sandbox.write);
957
+ if (refused) throw refused;
958
+ }
959
+ catch (e) { if (e?.code !== "E_BACKEND_SANDBOX_HOST") throw e; sandbox = { refused: { code: e.code, message: e.message, details: e.details ?? null } }; }
960
+ }
961
+ }
962
+ // A home on a session provider: the kernel runs its own copies of the home's modules, never the
963
+ // home's (lib/home-integrity.mjs). This says which of the home's own copies differ from the
964
+ // ones the kernel runs: what the agent or its harness uses is then not what the kernel runs.
965
+ // It changes nothing the kernel does, and is compared here only, never on the status path.
966
+ let kernelCopies;
967
+ if (t.home) {
968
+ const trust = providerHomeTrust(t.home);
969
+ if (trust?.composition) {
970
+ const differing = [];
971
+ for (const capability of Object.keys(trust.composition.modules).sort()) {
972
+ const compared = treeDisagreement(kernelModuleDir(t.home, capability, trust), join(t.home, ".oats", "modules", capability));
973
+ if (compared.entries.length) differing.push({ capability, differs: true });
974
+ else if (!compared.complete) differing.push({ capability, differs: null });
975
+ }
976
+ kernelCopies = { store: trust.composition.store, differing };
977
+ }
978
+ }
881
979
  const subjectBlockers = Object.entries(checks).flatMap(([name, c]) => c.items.filter((i) => i.required && !i.capability && i.status !== "pass" && i.status !== "not-applicable").map((i) => ({ check: name, subject: i.subject, status: i.status })));
882
980
  for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
883
- return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks,
981
+ return { readinessApi: READINESS_API, subject: t.subject, selector, at: new Date().toISOString(), checks, ...(sandbox ? { sandbox } : {}), ...(kernelCopies ? { kernelCopies } : {}),
884
982
  summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
885
983
  pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
886
984
  notes: ["ready means every REQUIRED check passes; it is never inferred from an empty set",
@@ -138,7 +138,9 @@ export function setInstanceRelatedWork(ctx, root, name, { home, on }) {
138
138
  * parentage is the only relation the kernel knows; it is reported as such. */
139
139
  export function descendantsOf(root, name) {
140
140
  const rows = [];
141
- for (const a of listAgents(root)) for (const i of listInstances(root).filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
141
+ // One listing, and no session provider asked: only names and records are read here.
142
+ const listed = listInstances(root, undefined, undefined, { askProviders: false });
143
+ for (const a of listAgents(root)) for (const i of listed.filter((x) => x.name === a.name)) for (const inst of i.instances || []) {
142
144
  const home = join(a._dir, "instances", inst.instance);
143
145
  const meta = otherRecord(home);
144
146
  if (meta) rows.push({ instance: inst.instance, agent: a.name, home, parent: meta.parentInstance ?? null });
@@ -161,6 +163,9 @@ export function descendantsOf(root, name) {
161
163
  return out; // deepest first
162
164
  }
163
165
 
166
+ /** What the session's inspect said of its activity (`running`: true, false, or null for not known),
167
+ * kept beside the facts for planStop's `midTask` and never part of a plan's JSON. */
168
+ const REPORTED_RUNNING = Symbol("reportedRunning");
164
169
  /** `state` is the session backend's word: "shell"/"stopped"/"not-launched" are
165
170
  * idle; "unknown" means a NON-shell process is running whose identity tmux
166
171
  * cannot name (the ordinary case for a launched harness). "Could not be
@@ -168,7 +173,7 @@ export function descendantsOf(root, name) {
168
173
  * the kernel code of what failed, never a system error's (E_SESSION_UNAVAILABLE
169
174
  * for one that has none; workFacts: E_GIT_FAILED). */
170
175
  function sessionFacts(home) {
171
- try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true }; }
176
+ try { const s = inspectInstanceSession(home); return { state: s.state, present: s.present, backend: s.backend ?? null, established: true, [REPORTED_RUNNING]: s.running ?? null }; }
172
177
  catch (e) { return { state: "unestablished", present: null, backend: null, established: false, reason: kernelCode(e, "E_SESSION_UNAVAILABLE") }; }
173
178
  }
174
179
  /** The instances attached to `tree`, a tree of the home of the instance `name` under `root` (its
@@ -233,7 +238,14 @@ export function planStop(ctx, root, name, { home, recursive = true, [OWN_HOLDING
233
238
  const targets = [...kids.map((kid) => targetFacts(kid, otherRecord(kid.home), own)), targetFacts({ ...me, instance: name, depth: 0 }, targetRecord(me.home), own)];
234
239
  // Reported activity: a running session or dirty work is mid-task; when the
235
240
  // session could not be established and work is not observed, say unknown.
236
- for (const t of targets) t.midTask = running(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || !t.work.observed) ? "unknown" : false;
241
+ // A session provider's session says its activity itself (its inspect's `running`): true is
242
+ // activity, and one that is there and reports none (null) is not reported as activity: unknown.
243
+ // (A tmux pane's state "unknown" is a process tmux cannot name, the ordinary launched harness:
244
+ // activity, as before.)
245
+ const onProvider = (s) => s.established && s.present === true && s.backend !== null && s.backend !== "tmux";
246
+ const unknownActivity = (s) => onProvider(s) && s[REPORTED_RUNNING] === null;
247
+ const active = (s) => (onProvider(s) ? s[REPORTED_RUNNING] === true : running(s));
248
+ for (const t of targets) t.midTask = active(t.session) || (t.work.observed && t.work.changed + t.work.untracked > 0) ? true : (!t.session.established || unknownActivity(t.session) || !t.work.observed) ? "unknown" : false;
237
249
  const safety = targets.map((t) => [t.home, t.session.state, t.session.present, t.launched, t.retiring]);
238
250
  const ambiguousEdges = (kids.ambiguous || []).map((c) => ({ instance: c.instance, agent: c.agent, home: c.home, reason: c.reason }));
239
251
  const plan = { lifecycleApi: LIFECYCLE_API, action: "stop", instance: name, home: me.home, recursive, at: new Date().toISOString(),
@@ -8,7 +8,7 @@ import { readFileSync, readdirSync, lstatSync, existsSync, statSync, openSync, c
8
8
  import { join, dirname, resolve, basename } from "node:path";
9
9
  import { noteRuntimeName } from "./deprecation.mjs";
10
10
  import { createSessionPaneInspector, AGENT_PANE_OPTION } from "./session-input.mjs";
11
- import { liveSession, validWaitingMessage } from "./instance-events.mjs";
11
+ import { liveSession, liveWaiting, validWaitingMessage } from "./instance-events.mjs";
12
12
  import { readBoardRow } from "./instance-board.mjs";
13
13
  import { processLiveness } from "./worktree-hooks.mjs";
14
14
  import { shownHolder } from "./claim.mjs";
@@ -19,10 +19,13 @@ import { readInstanceBackground } from "./instance-background.mjs";
19
19
  import { readInstancePin } from "./instance-pin.mjs";
20
20
  import { relatedWorkHeld } from "./instance-related-work.mjs";
21
21
  import { readSpawnedBy } from "./spawned-by.mjs";
22
- import { sessionEndOf } from "./session-end.mjs";
22
+ import { HOST_STOP_REASON, lostReasonOf, sessionEndOf } from "./session-end.mjs";
23
23
  import { identityHolderState, recordSeen } from "./session-seen.mjs";
24
24
  import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
25
- import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot } from "./session-inspect.mjs";
25
+ import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
26
+ import { INSPECT_MANY_MAX, sessionProviderTimeout, homeSessionProvider, recordsSessionProvider, inspectManyGroup, inspectProviderSession, inspectProviderSessions, rowSession, unsettledLaunchSaid } from "./session-providers.mjs";
27
+ import { moduleCopyReport, providerHomeTrust } from "./home-integrity.mjs";
28
+ import { SESSION_END } from "./session-resume-contract.mjs";
26
29
 
27
30
  /** OATS 0.25 and earlier homed local souls and capability-defined agents at
28
31
  * <scope>/local-agents/ (and <root>/local-agents|tmp-agents). The kernel never reads,
@@ -278,10 +281,82 @@ function statusTmuxPanes(snapshot, socket, session, io) {
278
281
  return { ...snapshot, panes, windowIds };
279
282
  } catch (e) { return { error: tmuxFailure(e, "tmux list-panes failed") }; }
280
283
  }
284
+ /** The row of a home on a session provider, before its provider has been asked: the kernel's own
285
+ * facts, under the receipt's authority (instanceSessionTarget). → `{ fields, ask? }`: `fields` the
286
+ * row's `backend`, `session`, `tmux` (null), `open`, `running`, `runtimeState` (`unknown`, `shell`,
287
+ * `stopped` or `unreachable`; always there) and, for a home OATS stopped, `sessionEnd`; `ask`
288
+ * (`{ binding, endpoint }`) for a session the provider must be asked about.
289
+ * `session` is `{ provider }` and, on this host only, the endpoint's thread id (rowSession): the
290
+ * endpoint itself is never on a row (`oats session inspect --home` answers it, locally).
291
+ * A home OATS stopped, and one never launched, answer without the provider. A stopped home's
292
+ * `sessionEnd` is its stop receipt's (lib/session-end.mjs): `lost` when `oats host run`'s shutdown
293
+ * stopped it, which a resume brings back, else `stopped`. A receipt or a module copy that cannot
294
+ * be used is unknown (`unreachable`, with the reason), never stopped. */
295
+ function providerRow(home, meta) {
296
+ const unreachable = (why, session) => ({ fields: { backend: meta.backend, session: session ?? rowSession(typeof meta.session?.provider === "string" ? meta.session.provider : null, null), tmux: null, open: null, running: null, runtimeState: "unreachable", runtimeError: why } });
297
+ let s;
298
+ try { s = instanceSessionTarget(home); } catch (e) { return unreachable(`${typeof e?.code === "string" ? e.code : "E_SESSION_UNAVAILABLE"}: ${e?.message ?? e}`); }
299
+ const recorded = s.session ?? s.planned;
300
+ // A record that names a session provider beside a receipt that authorises a tmux session, or none.
301
+ if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
302
+ // `moduleCopy` (lib/home-integrity.mjs moduleCopyReport): which copy of its modules the kernel
303
+ // runs, and whether the home's own record of them is the receipt's. Records only: nothing is hashed.
304
+ const moduleCopy = moduleCopyReport(meta, providerHomeTrust(home));
305
+ const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null, ...(moduleCopy ? { moduleCopy } : {}) };
306
+ // A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
307
+ if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
308
+ if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };
309
+ if (s.session.stoppedAt !== null) return { fields: { ...fields, running: false, runtimeState: "stopped", sessionEnd: lostReasonOf(home, s.meta) === HOST_STOP_REASON ? SESSION_END.LOST : SESSION_END.STOPPED } };
310
+ const found = homeSessionProvider(home, s.meta, s.session.provider, s.session.backend);
311
+ if (found.problem) return unreachable(found.problem, fields.session);
312
+ return { fields: { ...fields, running: null, runtimeState: "unreachable" }, ask: { binding: found.binding, endpoint: s.session.endpoint } };
313
+ }
314
+ /** The time one listing gives all its session providers together: a provider that hangs costs a
315
+ * status, a sweep or a plan this much at most, however many homes it has. */
316
+ const PROVIDER_LISTING_BUDGET_MS = 30_000;
317
+ /** Ask the providers about `asks` ([{ row, home, binding, endpoint, mayEnd }]) and write each answer
318
+ * into its row: one `inspectMany` call per group of homes that share one module copy, provider and
319
+ * settings (inspectManyGroup), at most INSPECT_MANY_MAX homes a call, and one `inspect` per home
320
+ * where a provider declares none (or its batch was bad: inspectProviderSessions). A provider that
321
+ * fails, refuses or answers outside the contract's words leaves the row unknown: `running: null`,
322
+ * `runtimeState: "unreachable"`. A session that is gone on a home OATS did not stop is a lost
323
+ * one (`sessionEnd: "lost"`, where the row may say how its session ended: `mayEnd`), which the
324
+ * sweep resumes under the home's cap. All the asks of one listing share PROVIDER_LISTING_BUDGET_MS. */
325
+ function answerProviderRows(asks, io) {
326
+ const deadline = Date.now() + PROVIDER_LISTING_BUDGET_MS;
327
+ // Each call's timeout: the verb's own (and a test's seam), never past what the listing has left.
328
+ const timeoutFor = () => Math.min(sessionProviderTimeout("inspect"), deadline - Date.now());
329
+ const groups = new Map(), single = [];
330
+ for (const ask of asks) {
331
+ const key = inspectManyGroup(ask.binding);
332
+ if (key === null) single.push(ask);
333
+ else groups.set(key, [...(groups.get(key) ?? []), ask]);
334
+ }
335
+ const answer = (ask, inspected) => {
336
+ if (inspected.unavailable) { Object.assign(ask.row, { running: null, runtimeState: "unreachable", runtimeError: inspected.unavailable }); return; }
337
+ const { state, running, open } = inspected.observed;
338
+ Object.assign(ask.row, { running, runtimeState: state, open });
339
+ delete ask.row.runtimeError;
340
+ // A producer's claim, read while the session is there and not in error (an idle session can be
341
+ // the one waiting on a person); the receipt already agreed (providerRow).
342
+ if (providerMayWait(inspected.observed)) ask.row.waitingOnYou = liveWaiting(ask.home);
343
+ if (inspected.observed.present === false && ask.mayEnd) ask.row.sessionEnd = SESSION_END.LOST;
344
+ };
345
+ for (const ask of single) { const timeoutMs = timeoutFor(); answer(ask, timeoutMs > 0 ? inspectProviderSession(ask.binding, ask.endpoint, { io, timeoutMs }) : { unavailable: "the time this listing gives its session providers was spent before this one was asked" }); }
346
+ for (const members of groups.values()) {
347
+ for (let at = 0; at < members.length; at += INSPECT_MANY_MAX) {
348
+ const chunk = members.slice(at, at + INSPECT_MANY_MAX);
349
+ inspectProviderSessions(chunk, { io, timeoutFor }).forEach((inspected, i) => answer(chunk[i], inspected));
350
+ }
351
+ }
352
+ }
281
353
  /** `records`, when given, a Map the listing fills with each home's record as read (home → the JSON
282
354
  * object its instance.json holds, before upgradeHomeMeta), for the rest of the same read to reuse
283
- * instead of reading the file again (legacyCapturedHomes). */
284
- export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records } = {}) {
355
+ * instead of reading the file again (legacyCapturedHomes).
356
+ * `askProviders: false` (the host's shutdown listing): no session provider is asked. A provider
357
+ * home whose provider would be asked reads `running: null`, `runtimeState: "unreachable"`, with a
358
+ * `runtimeError` that says so: the listing then depends on no provider's answer, or time. */
359
+ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { records, askProviders = true } = {}) {
285
360
  // Liveness reads each home's RECORDED endpoint (a pre-0.31 home records pi-agents): the recorded
286
361
  // socket, never the ambient $TMUX server: one window read and one pane read per socket/session,
287
362
  // plus one lazy process scan for shell descendants, independent of the number of homes.
@@ -294,6 +369,9 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
294
369
  return hostScan.ok ? { ok: true, processes: processesWorkingIn(hostScan.processes, home) } : hostScan;
295
370
  };
296
371
  const inspectPanes = createSessionPaneInspector(io);
372
+ // The homes on a session provider whose provider must be asked: asked together once every row is
373
+ // read (answerProviderRows), so that one call can answer for a provider's whole group.
374
+ const providerAsks = [];
297
375
  const tmuxByEndpoint = new Map();
298
376
  const windowsOf = (session, socket) => {
299
377
  const key = JSON.stringify([socket ?? null, session]);
@@ -318,9 +396,14 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
318
396
  const { rollbackIncomplete, spawnInProgress, retirePending, retire } = readRetireFacts(home);
319
397
  // A home opened in Herdr (removed in 0.31.0) is listed, never observed: its row says so.
320
398
  // A home whose record cannot be read is listed, never observed: where its session is, is in the record.
399
+ const herdr = record.state !== "unreadable" && recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)));
400
+ // A home on a session provider is never read through tmux: its row is the kernel's facts
401
+ // and, where the provider must be asked, its answer (below, once every row is read).
402
+ const provided = record.state === "record" && !herdr && recordsSessionProvider(meta) ? providerRow(home, meta) : null;
321
403
  const liveness = record.state === "unreadable" ? { running: null, runtimeState: "unreachable", runtimeError: `E_UNIDENTIFIED_INSTANCE_HOME: ${unreadableRecordSaid(record)}` }
322
- : recordsHerdr(meta, readJsonOrUndefined(findRetirementBaseline(home)))
404
+ : herdr
323
405
  ? { running: null, runtimeState: "unsupported", runtimeError: `E_HERDR_REMOVED: ${herdrInstanceRemoved(e.name).message}` }
406
+ : provided ? (({ sessionEnd: _own, ...fields }) => fields)(provided.fields)
324
407
  : tmuxLiveness(windowsOf(meta.tmux?.session || tmuxSession, meta.tmux?.socket), meta.tmux?.window || meta.instance || e.name, scanOf(home),
325
408
  // A home that records no socket and no launch (--no-launch) reads the default server only
326
409
  // by default: that server's missing socket says nothing about it, and stays "not running".
@@ -363,7 +446,10 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
363
446
  // Feature session-resume: how the last session of a launched home that does not run ended
364
447
  // (lib/session-end.mjs): lost, stopped or exited. Absent while it runs or reads unknown, for a
365
448
  // home never launched, and for one being set up, retired or quarantined.
366
- const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? sessionEndOf(home, meta) : null;
449
+ // A home on a session provider reads it from its receipt (providerRow): `lost` for one stopped
450
+ // with the host, which a resume brings back, `stopped` for one an operator stopped; a session
451
+ // OATS did not stop has none.
452
+ const sessionEnd = record.state === "record" && liveness.running === false && meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending ? (provided ? provided.fields.sessionEnd ?? null : sessionEndOf(home, meta)) : null;
367
453
  // Feature instance-color: the home's own colour record (lib/instance-color.mjs), a palette name or
368
454
  // null, after the record so that nothing in instance.json stands in for it.
369
455
  // Feature instance-pin: `pinned: true` while the home holds a valid pin (lib/instance-pin.mjs), absent
@@ -376,7 +462,13 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
376
462
  // Feature instance-board: the agent's board (lib/instance-board.mjs), null for a home with no board
377
463
  // file: its facts, and the questions of its current session, by the same read of the log as the claim.
378
464
  const board = readBoardRow(home, { session, ...recordMeta });
379
- return { ...recorded, ...claims, home, instance: e.name, ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
465
+ // `backend`: `tmux` for a home on the kernel's own backend, a session provider's name otherwise
466
+ // (liveness carries it, with `session`); absent for a home whose record cannot be read and
467
+ // for one opened in Herdr, whose record says what it says.
468
+ const row = { ...recorded, ...claims, home, instance: e.name, ...(record.state === "record" && !herdr && !provided ? { backend: "tmux" } : {}), ...facts, color: readInstanceColor(home), ...(readInstanceBackground(home) ? { background: true } : {}), ...(readInstancePin(home) ? { pinned: true } : {}), ...(related ? { relatedWork: true } : {}), ...(related?.parent ? { sameWork: true } : {}), ...(identity ? { identity } : {}), ...(meta.launch && typeof meta.launch === "object" ? { launch: redactLaunchRecipe(meta.launch) } : {}), ...(typeof meta.command === "string" ? { command: redactLaunchCommand(meta.command) } : {}), ...liveness, ...(sessionEnd ? { sessionEnd } : {}), waitingOnYou, board, ...(rollbackIncomplete ? { rollbackIncomplete } : {}), ...(spawnInProgress ? { spawnInProgress } : {}), ...(retirePending ? { retirePending } : {}), ...(retire ? { retire } : {}) };
469
+ if (provided?.ask && askProviders) providerAsks.push({ row, home, ...provided.ask, mayEnd: meta.launched === true && !rollbackIncomplete && !spawnInProgress && !retirePending });
470
+ else if (provided?.ask) row.runtimeError = "its session provider was not asked (a listing that asks no provider)";
471
+ return row;
380
472
 
381
473
  });
382
474
  };
@@ -401,6 +493,7 @@ export function listInstances(root, tmuxSession = DEFAULT_TMUX_SESSION, io, { re
401
493
  out.push({ name, kind: "capability", capability: cap, description: cap ? `capability agent (${cap})` : "capability agent", dir, instances, ...(retireFailures.length ? { retireFailures } : {}) });
402
494
  seen.add(name);
403
495
  }
496
+ if (providerAsks.length) answerProviderRows(providerAsks, io);
404
497
  // Feature session-resume: what this local listing saw of each home's session, for the sweep
405
498
  // (lib/session-seen.mjs). It never changes the listing, and never throws or prints.
406
499
  recordSeen(root, out.flatMap((a) => a.instances || []));
@@ -17,14 +17,14 @@
17
17
  * Nothing here reads `oats-config.yaml`, an installed-capability directory or a
18
18
  * per-soul `source:` — those do not exist in this model. */
19
19
  import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
20
- import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
20
+ import { basename, join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
21
21
  import { loadLocal, observeWorkspace } from "./workspace.mjs";
22
22
  import { resolveSoul, kernelCompatibility, packageRef } from "./resolve.mjs";
23
23
  import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
24
24
  import { LOCAL_FILE, launchLayers, nearestSoulKeys } from "./launch-preference.mjs";
25
25
  import { APPROVED_HOOKS, declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
26
26
  import { materialize, moduleSkills, MODULES_DIR, plannedModuleSkills, SKILLS_DIR } from "./materialize.mjs";
27
- import { contentDigest, fetchRemoteTree } from "./remote.mjs";
27
+ import { contentDigest, createReadSession, fetchRemoteTree } from "./remote.mjs";
28
28
  import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
29
29
  import { tmpdir } from "node:os";
30
30
  import { randomBytes } from "node:crypto";
@@ -77,6 +77,27 @@ export function parseProviderFlags(pairs) {
77
77
  return JSON.parse(JSON.stringify(out));
78
78
  }
79
79
 
80
+ /** Why a discovery made without reaching any remote cannot say which soul a home is of: a member
81
+ * of the workspace that this host could not read (its cache does not hold it) → the cause, naming
82
+ * each such repository and the way out, or null when every member was read. A member that was
83
+ * read and is no member (no backlink, not listed) is not one of these. */
84
+ export function unreadMembersCause(discovery) {
85
+ if (discovery?.standalone === true) return null;
86
+ const unread = (discovery?.members || []).filter((m) => m.confirmed === false && m.reason === "cannot-read");
87
+ if (!unread.length) return null;
88
+ return `E_REMOTE_UNREADABLE: ${unread.map((m) => m.detail).join("; ")}. A member that was not read can hold this home's soul, or another of its name, so the deployment's configuration for the home cannot be told. Any oats command that reads the workspace (oats status) brings it to this host's cache; if this host cannot read that repository at all, name the member the home's soul is in as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host`;
89
+ }
90
+ /** The soul a home under the agent directory `agentDir` is of, among the workspace's souls
91
+ * (`entries`) → `{ entry }`, or `{ unavailable: "<why>" }`. Nothing outside the home says which
92
+ * soul a home is but the directory it is in, so two souls that share that directory (the same
93
+ * bare name, in two members, or a member's and an external one) leave it untold: the cause names
94
+ * them and what the operator can do. */
95
+ export function homeSoulEntry(entries, agentDir) {
96
+ const here = entries.filter((entry) => agentDirOf(entry) === agentDir);
97
+ if (here.length === 1) return { entry: here[0] };
98
+ if (!here.length) return { unavailable: `E_SOUL_UNKNOWN: the workspace offers no soul whose agent directory is ${agentDir}` };
99
+ return { unavailable: `${here.length} souls of this workspace share the agent directory ${agentDir} (${here.map(qualifiedSoulName).join(", ")}), so which one this home is of cannot be told: rename one of them, or take one out of the workspace` };
100
+ }
80
101
  /** The qualified name of a discovered soul: `<package>/<soul>` for a package soul,
81
102
  * `<member name>/<soul>` for a member's, `<source repo name>/<soul>` for an external one. */
82
103
  export function qualifiedSoulName(entry) {
@@ -286,6 +307,68 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
286
307
  }
287
308
  }
288
309
 
310
+ /**
311
+ * What a start or a restart of a session-provider home computes its sandbox allowances from
312
+ * (lib/sandbox-allowances.mjs): the DEPLOYMENT'S configuration, resolved for the home's soul as a
313
+ * spawn preview resolves it (workspace, lock, soul payload), WITHOUT REACHING ANY REMOTE: every
314
+ * repository is read as this host last read it (lib/remote.mjs, an offline read session: the head
315
+ * last observed here, from the cache), and the deployment's own oats-local.yaml and lock as they
316
+ * are now. So a launch never waits on the network or fails with it, and what `oats aweb setup`
317
+ * writes to oats-local.yaml reaches an existing home at its next launch. A repository this host's
318
+ * cache does not hold is a cause of `unavailable`, by name.
319
+ *
320
+ * NOTHING INSIDE THE HOME decides which deployment or which soul that is: a sandboxed agent can
321
+ * write its home, instance.json included. Both come from where the home IS: the deployment is the
322
+ * fourth ancestor of the home's real path (`<deployment>/agents/<agent>/instances/<instance>`),
323
+ * and it must hold its own oats-local.yaml; the soul is the one soul the workspace offers whose
324
+ * agent directory is `<agent>`. A home whose real path is elsewhere (an agents root reached
325
+ * through a link) has no deployment to read by this rule, and none is guessed.
326
+ *
327
+ * → `{ deployment, modules: [{ name, manifest }], slots, payloads, teams: [team id], defaultTeam }`, or
328
+ * `{ unavailable: "<why>" }` when that cannot be established or resolved (no deployment there, no
329
+ * such soul any more or several, a member remote that cannot be read, an invalid workspace): the
330
+ * cause, in one line. It never throws for those: what a launch does without allowances is the
331
+ * caller's rule.
332
+ */
333
+ export async function homeSandboxSource(home, { remoteOptions, remote } = {}) {
334
+ let real;
335
+ try { real = realpathSync(home); } catch (e) { return { unavailable: `the home cannot be resolved (${e.code ?? e.message})` }; }
336
+ const deployment = dirname(dirname(dirname(dirname(real)))), agentDir = basename(dirname(dirname(real)));
337
+ if (basename(dirname(real)) !== "instances") return { unavailable: `${real} is not an instance home of a deployment (<deployment>/agents/<agent>/instances/<instance>)` };
338
+ // Never the caller's session: this read reaches no remote, whatever the command around it does.
339
+ const offline = createReadSession({ offline: true });
340
+ try {
341
+ const found = loadLocal(deployment);
342
+ if (!found.path || resolvePath(dirname(found.path)) !== deployment) return { unavailable: `${deployment}, where this home is, holds no deployment configuration (oats-local.yaml): the home's agents directory is reached through a symbolic link, or the home is not a deployment's` };
343
+ remoteOptions = { ...remoteOptions, session: offline };
344
+ const lock = readLockIfPresent(deployment);
345
+ const discovery = await discoverOrStandalone(found.local, { lock, deployment, remoteOptions, remote });
346
+ // A member this host did not read can hold the home's soul, or another of its name: with one
347
+ // unread, which soul the home is of is not told, whatever the members that were read offer.
348
+ const unread = unreadMembersCause(discovery);
349
+ if (unread) return { unavailable: unread };
350
+ const soul = homeSoulEntry(soulCandidates(discovery).map((c) => c.entry), agentDir);
351
+ if (soul.unavailable) return { unavailable: soul.unavailable };
352
+
353
+ // resolveSoul, not prepareInstance: a soul disabled for SPAWNING on this machine (souls.disabled)
354
+ // still has the homes it spawned, which start as any home does, with their allowances.
355
+ const resolution = await resolveSoul(discovery, soul.entry, { local: found.local, lock, spawn: {}, remoteOptions, remote });
356
+ return {
357
+ deployment,
358
+ modules: resolution.modules.map((m) => ({ name: m.name, manifest: m.manifest })), slots: resolution.slots ?? {}, payloads: resolution.payloads ?? {},
359
+ teams: (resolution.teams ?? []).map((row) => row.team).filter((team) => typeof team === "string"),
360
+ defaultTeam: typeof resolution.defaultTeam?.team === "string" ? resolution.defaultTeam.team : null,
361
+ };
362
+ } catch (e) {
363
+ if (typeof e?.code !== "string" || !e.code.startsWith("E_")) throw e;
364
+ // A repository this host can NEVER read (a member whose workspace host it has no access to: a
365
+ // spawn then works from the member alone) is never brought to the cache by any command: the
366
+ // way out is to say so in the deployment, which needs no read of that host.
367
+ const never = e.details?.reason === "not-cached" ? " If this host cannot read that repository at all, name the member as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host" : "";
368
+ return { unavailable: `${e.code}: ${e.message}${never}` };
369
+ } finally { offline.close(); }
370
+ }
371
+
289
372
  /**
290
373
  * For `session start|restart --reselect-launch`: what the home's launch layers need of the workspace
291
374
  * (lib/core.mjs homeLaunchLayers `offered`) to say which keys of souls.launch name no soul. The workspace