@awebai/oats 0.69.23 → 0.70.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (88) hide show
  1. package/bin/oats.mjs +112 -20
  2. package/docs/capabilities.md +697 -11
  3. package/docs/capability-manifest.schema.json +66 -0
  4. package/docs/configuration.md +27 -7
  5. package/docs/design/2026-11-19-sandboxes.md +595 -121
  6. package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
  7. package/docs/design/README.md +7 -3
  8. package/docs/desktop-cli-api.md +330 -9
  9. package/docs/desktop.md +181 -48
  10. package/docs/execution-targets.md +210 -4
  11. package/docs/first-team.md +11 -0
  12. package/docs/implementation.md +24 -3
  13. package/docs/integrations.md +2 -2
  14. package/docs/knowledge-capability-authoring.md +1 -1
  15. package/docs/knowledge-reference/proposal.md +10 -0
  16. package/docs/knowledge.md +20 -11
  17. package/docs/official-catalog.md +2 -2
  18. package/docs/packages.md +7 -7
  19. package/docs/release-notes/v0.69.24.md +264 -0
  20. package/docs/release-notes/v0.70.0.md +155 -0
  21. package/docs/souls-and-instances.md +57 -0
  22. package/docs/trust-model.md +8 -1
  23. package/docs/tui.md +21 -1
  24. package/docs/upgrading.md +19 -5
  25. package/docs/workspaces.md +13 -5
  26. package/lib/automation-scope.mjs +1 -1
  27. package/lib/capability-show.mjs +20 -1
  28. package/lib/command-flags.mjs +2 -2
  29. package/lib/compile-cache.mjs +1 -1
  30. package/lib/core.mjs +1455 -203
  31. package/lib/errors.mjs +4 -1
  32. package/lib/home-integrity.mjs +329 -0
  33. package/lib/hook-env.mjs +107 -0
  34. package/lib/host-run.mjs +11 -3
  35. package/lib/instance-events.mjs +32 -5
  36. package/lib/instance-git.mjs +9 -0
  37. package/lib/instance-inspect.mjs +107 -9
  38. package/lib/instance-lifecycle.mjs +15 -3
  39. package/lib/instance-listing.mjs +101 -8
  40. package/lib/instance-resolution.mjs +85 -2
  41. package/lib/instance-upgrade.mjs +170 -14
  42. package/lib/kernel-features.mjs +10 -1
  43. package/lib/node-version.mjs +9 -0
  44. package/lib/provider-call-child.mjs +60 -0
  45. package/lib/provider-resume.mjs +83 -0
  46. package/lib/provider-test-seams.mjs +20 -0
  47. package/lib/read-call.mjs +2 -0
  48. package/lib/remote.mjs +33 -1
  49. package/lib/reserved-launch-env.mjs +8 -1
  50. package/lib/retire-admission.mjs +12 -1
  51. package/lib/sandbox-allowances.mjs +329 -0
  52. package/lib/schedule.mjs +14 -4
  53. package/lib/servers.mjs +38 -5
  54. package/lib/session-inspect.mjs +123 -87
  55. package/lib/session-providers.mjs +575 -0
  56. package/lib/session-receipt.mjs +93 -0
  57. package/lib/session-resume.mjs +68 -15
  58. package/lib/stable-node.mjs +3 -0
  59. package/lib/triggers.mjs +3 -1
  60. package/lib/upgrade-state.mjs +6 -1
  61. package/lib/worktree-hooks.mjs +18 -2
  62. package/lib/worktree.mjs +21 -7
  63. package/package-catalog.json +2 -2
  64. package/package.json +2 -1
  65. package/packages/client/capability-list.mjs +21 -0
  66. package/packages/client/cli-adapter.mjs +19 -4
  67. package/packages/client/cli-locator.mjs +5 -1
  68. package/packages/client/deployment-data.mjs +23 -1
  69. package/packages/client/deployment-panel.mjs +25 -3
  70. package/packages/client/home-board.mjs +33 -19
  71. package/packages/client/inspect-boundary.mjs +18 -8
  72. package/packages/client/instance-acts.mjs +30 -3
  73. package/packages/client/instance-board.mjs +206 -0
  74. package/packages/client/instance-presentation.mjs +55 -0
  75. package/packages/client/liveness.mjs +15 -4
  76. package/packages/client/own-codes.mjs +5 -1
  77. package/packages/client/remote-roster.mjs +6 -1
  78. package/packages/client/session-backends.mjs +31 -0
  79. package/packages/client/session-start.mjs +18 -6
  80. package/packages/client/spawn-apply-cli.mjs +5 -3
  81. package/packages/client/spawn-apply-contract.mjs +25 -2
  82. package/packages/client/spawn-apply.mjs +5 -1
  83. package/packages/client/spawn-messages.mjs +3 -0
  84. package/packages/client/terminal-contract.mjs +4 -0
  85. package/packages/client/waiting-on-you.mjs +12 -2
  86. package/packages/tui/lib/model.mjs +14 -3
  87. package/packages/tui/lib/store.mjs +12 -3
  88. package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/remote.mjs CHANGED
@@ -139,6 +139,11 @@
139
139
  * unref'd while idle and ended by session.close();
140
140
  * - `maxAge` (seconds): > 0 lets observeRemote reuse a recorded head observation
141
141
  * (the observation store below) no older than that;
142
+ * - `offline` (true): the session NEVER reaches a remote. A head is the one this host last
143
+ * observed (its record, of any age); a commit, a tree and a file are read only when the cache
144
+ * holds them. Whatever is not there is E_REMOTE_UNREADABLE { reason: "not-cached" } naming the
145
+ * repository: no ls-remote and no fetch is ever run, and nothing is recorded. What it reads is
146
+ * the configuration as this host last read it (OFFLINE, below);
142
147
  * - the head observations used, for the `observation` output block;
143
148
  * - `deadline` (DEADLINE; the deployment reads `oats status` and `oats workspace status` only, READ_REMOTE_BUDGET_MS
144
149
  * after their session starts): every remote step gets what is left of it, not its own default — each git call's
@@ -164,6 +169,13 @@
164
169
  * under `maxAge`, only when key, ref args and urlDigest all match, and never in place of
165
170
  * a live observation that failed.
166
171
  *
172
+ * OFFLINE (`createReadSession({ offline: true })`): for a read that must not depend on the network
173
+ * or change with it (the sandbox allowances of a session provider's start: lib/instance-resolution.mjs
174
+ * homeSandboxSource). Its three refusals, each before any git process that could reach a remote:
175
+ * a head never observed on this host (observeInSession), a commit the cache does not hold
176
+ * (ensureCommit), a file whose blob the cache does not hold (ensureBlobs). Local git reads of the
177
+ * cache (peel, ls-tree, cat-file) are what they always are.
178
+ *
167
179
  * VERIFIED STORE (`treeVerification`; kernel-private, not a contract):
168
180
  * `<cacheRoot>/.verified/<sha256([key, commit, dir, digest])>.json` records that the tree `dir` of
169
181
  * (repo key, commit), read from this cache, had the content digest `digest`:
@@ -1080,8 +1092,10 @@ function pinRef(oid) { return `refs/oats/commits/${oid}`; }
1080
1092
 
1081
1093
  class ReadSession {
1082
1094
  constructor({ maxAge = 0, now = Date.now, fingerprint = null, treeIndexBudget = TREE_INDEX_BUDGET, parsedLimits = null, batchTimeoutMs = GIT_TIMEOUT_MS,
1083
- cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET } = {}) {
1095
+ cacheWriteWaitMs = CACHE_WRITE_WAIT_MS, fetchTimeoutMs = GIT_FETCH_TIMEOUT_MS, deadline = null, v0AdvertisementBudget = V0_ADVERTISEMENT_BUDGET, offline = false } = {}) {
1084
1096
  if (!Number.isInteger(maxAge) || maxAge < 0 || maxAge > MAX_AGE_LIMIT) throw new TypeError(`maxAge must be an integer from 0 to ${MAX_AGE_LIMIT}`);
1097
+ if (typeof offline !== "boolean") throw new TypeError("offline must be true or false");
1098
+ this.offline = offline; // never reach a remote: the module header's OFFLINE
1085
1099
  if (deadline !== null && !Number.isFinite(deadline)) throw new TypeError("deadline must be null or a time in Date.now() milliseconds");
1086
1100
  this.maxAge = maxAge;
1087
1101
  this.now = now;
@@ -1187,6 +1201,11 @@ class ReadSession {
1187
1201
  * `fingerprint`, `treeIndexBudget`, `parsedLimits`, `batchTimeoutMs`, `cacheWriteWaitMs`, `fetchTimeoutMs`,
1188
1202
  * `v0AdvertisementBudget`. */
1189
1203
  export function createReadSession(options = {}) { return new ReadSession(options); }
1204
+ /** What an offline session (the module header's OFFLINE) answers for what this host's cache does not
1205
+ * hold: the repository is named, and nothing was asked of it. */
1206
+ function notCached(ref, what, extra = {}) {
1207
+ return fail("E_REMOTE_UNREADABLE", `cannot read ${displayRepoRef(ref.url)} without reaching it: ${what}. Any oats command that reads the workspace (oats status, oats spawn --preview) brings it to this host`, { url: ref.url, key: ref.key, reason: "not-cached", ...extra });
1208
+ }
1190
1209
  /** An observation the command no longer wants (its session closed, or its prefetch abandoned): never adopted
1191
1210
  * by a caller that is still reading, so its shape only has to be a typed remote failure. */
1192
1211
  function abandonedError() {
@@ -1599,6 +1618,8 @@ async function ensureCommit(ref, oid, options) {
1599
1618
  };
1600
1619
  const present = await usable(repoHandle(dir, options.exec ?? runGit, session));
1601
1620
  if (present) return { repo: repoHandle(dir, options.exec ?? runGit, session), commit: remember(present) };
1621
+ // Offline: what the cache does not hold is not fetched.
1622
+ if (session?.offline) throw notCached(ref, `this host's cache does not hold its commit ${oid}`, { commit: oid });
1602
1623
  // Every write below (init, config, fetch, pin) holds the cache's cross-process write lock; a process that
1603
1624
  // waited for it finds what the holder fetched.
1604
1625
  return withCacheWriteLock(ref, dir, "fetch", session, async ({ waited }) => {
@@ -1878,6 +1899,7 @@ const fetchFailure = (repo, ref, error, commit) => unreadable(ref, error, { comm
1878
1899
  * a caller that reads it). Every fetch first removes the temporary files earlier fetches left in the object
1879
1900
  * store, by their age (removeStaleTemporaryFiles). → { stdout, stderr } */
1880
1901
  async function fetchInto(repo, ref, args, { what, commit, input, raw = false } = {}) {
1902
+ if (repo.session?.offline) throw notCached(ref, `this read never fetches${commit ? ` (commit ${commit})` : ""}`, commit ? { commit } : {});
1881
1903
  const started = Date.now();
1882
1904
  removeStaleTemporaryFiles(repo);
1883
1905
  let lastError;
@@ -1917,6 +1939,8 @@ async function ensureBlobs(repo, ref, commit, entries) {
1917
1939
  await withCacheLock(repo.dir, async () => {
1918
1940
  let sizes = await blobSizes(repo, oids); // another read may have fetched them meanwhile
1919
1941
  let wanted = oids.filter((o) => sizes.get(o) === null);
1942
+ // Offline: a file the cache does not hold is not fetched.
1943
+ if (wanted.length && repo.session?.offline) throw notCached(ref, `this host's cache does not hold ${wanted.length === 1 ? "a file" : `${wanted.length} files`} of its commit ${commit}`, { commit });
1920
1944
  if (wanted.length) await withCacheWriteLock(ref, repo.dir, "fetch", repo.session, async ({ waited }) => {
1921
1945
  if (waited) { // another process may have fetched them while this one waited
1922
1946
  sizes = await blobSizes(repo, oids);
@@ -2079,6 +2103,13 @@ async function observeInSession(ref, args, at, options, session, prefetch = null
2079
2103
  try {
2080
2104
  // A prefetch given up while it queued (or a session closed meanwhile) runs no git at all.
2081
2105
  if (session.closed || prefetch?.abandoned) throw abandonedError();
2106
+ if (session.offline) {
2107
+ // The head this host last observed, of any age, when the cache still holds it: never a live one.
2108
+ const record = readObservation(root, ref, atArgs, session, { anyAge: true });
2109
+ if (!record) throw notCached(ref, "this host has not observed it yet");
2110
+ const reused = { key: ref.key, url: ref.url, commit: record.commit, ref: record.ref, observedAt: record.observedAt, reused: true };
2111
+ return { ...reused, commit: (await ensureCommit(ref, record.commit, options)).commit };
2112
+ }
2082
2113
  if (session.maxAge > 0) {
2083
2114
  const record = readObservation(root, ref, atArgs, session);
2084
2115
  if (record) {
@@ -2160,6 +2191,7 @@ const V0_FINAL_REASONS = new Set(["timeout", "auth", "not-found", "cache"]);
2160
2191
  async function observeLive(ref, args, at, options) {
2161
2192
  const exec = options.exec ?? runGit;
2162
2193
  const session = sessionOf(options);
2194
+ if (session?.offline) throw notCached(ref, "this read never observes a remote");
2163
2195
  const signal = session?.signal;
2164
2196
  // Every git call takes what is left of the session's deadline, if it has one (sessionExec).
2165
2197
  const run = (argv, extra = {}) => sessionExec(exec, session, argv, { timeout: GIT_TIMEOUT_MS, ...(signal ? { signal } : {}), ...extra });
@@ -21,4 +21,11 @@ export const RESERVED_LAUNCH_ENV = new Set(["OATS_INSTANCE", "OATS_INSTANCE_HOME
21
21
  // lib/system-tools.mjs).
22
22
  "OATS_TEST_CGROUP", "OATS_TEST_SYSTEMD_BOOTED", "OATS_TEST_SYSTEM_TOOL_DIRS",
23
23
  // The test seam of #1421 §3: the naming call's time limit (lib/instance-naming.mjs NAMING_TIMEOUT_MS).
24
- "OATS_TEST_NAMING_TIMEOUT_MS"]);
24
+ "OATS_TEST_NAMING_TIMEOUT_MS",
25
+ // The test seams of the session-provider contract: the timeout of every provider call
26
+ // (lib/session-providers.mjs sessionProviderTimeout) and how long a lost session's resume waits
27
+ // for its last run's processes to leave the home (lib/provider-resume.mjs resumeQuietWait). Each
28
+ // only shortens: a value above the kernel's own limit is that limit.
29
+ "OATS_TEST_SESSION_PROVIDER_TIMEOUT_MS", "OATS_TEST_PROVIDER_RESUME_WAIT_MS",
30
+ // The test seam of a provider home's write orders: the point at which the kernel dies (lib/core.mjs dieAt).
31
+ "OATS_TEST_PROVIDER_DIE_AT", "OATS_TEST_PROVIDER_LEADER_DELAY_MS", "OATS_TEST_PROVIDER_KILL_KERNEL"]);
@@ -4,6 +4,8 @@ import { existsSync, readFileSync } from "node:fs";
4
4
  import { join } from "node:path";
5
5
  import { directoryRollbackPath, isCapturedHome, readHomeRecord, unreadableRecordSaid } from "./instance-listing.mjs";
6
6
  import { isPlainObject } from "./session-inspect.mjs";
7
+ import { recordsSessionProvider } from "./session-providers.mjs";
8
+ import { providerHomeTrust } from "./home-integrity.mjs";
7
9
  import { processLiveness } from "./worktree-hooks.mjs";
8
10
  import { lifecycleBusy, oatsError } from "./errors.mjs";
9
11
 
@@ -160,7 +162,16 @@ export function retireCleanupAdmission(home, name, { force = false } = {}, readW
160
162
  // Compensation metadata is the SPAWN's, from whichever record survived — never
161
163
  // a failed retry's report, which says nothing about what still needs undoing.
162
164
  if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;
163
- if (quarantine && typeof quarantine.cleanup.launched === "boolean") {
165
+ // A provider home's capability rows (which retire hooks it owes, and their commands) are its
166
+ // receipt's, never its own record's or its rollback marker's, which its agent can write
167
+ // (lib/home-integrity.mjs). A receipt with no composition leaves none: the hooks cannot be
168
+ // identified, and the retire says so as for a home that records none.
169
+ const trust = providerHomeTrust(home);
170
+ if (trust) { if (trust.composition) meta.capabilityRuntime = trust.composition.capabilityRuntime; else delete meta.capabilityRuntime; }
171
+ // A home on a session provider keeps what its own record says of its launch: its receipt is the
172
+ // authority for it, and a rollback marker is written `launched: false` whatever the provider had
173
+ // answered by then, which would set the record against the receipt and refuse every retire.
174
+ if (quarantine && typeof quarantine.cleanup.launched === "boolean" && !recordsSessionProvider(liveMeta)) {
164
175
  meta.launched = quarantine.cleanup.launched;
165
176
  meta.tmux = quarantine.cleanup.tmux;
166
177
  meta.sessionTarget = quarantine.cleanup.sessionTarget;
@@ -0,0 +1,329 @@
1
+ /** Sandbox allowances (docs/capabilities.md "Sandbox allowances"): what a session provider may
2
+ * widen its harness's sandbox by, for one launch. The kernel builds the list; the provider writes
3
+ * it and nothing else. Two kinds of entry, and where each may come from:
4
+ *
5
+ * - `domains`: exact hosts. Only the capability that fills the instance's messaging, knowledge or
6
+ * tasks slot may contribute one, only by a manifest line `sandboxDomains: [{ "setting": "<key>" }]`
7
+ * that names one of its own settings. The setting's value is a URL (the kernel takes its host),
8
+ * a bare host, or a map from team id to one of those, of which only the entries of the
9
+ * instance's own teams are taken. A line on any other capability refuses the launch, never
10
+ * drops the line. A line may instead be `{ "settingFile": "<key>", "urls": "<JSON pointer>" }`:
11
+ * the setting's value is the path of a JSON file of the deployment, and the hosts are those
12
+ * of every string at the pointer (readSettingFileHosts, with its bounds). Nothing at run time
13
+ * (hook output, an environment variable, a task, a launch argument) can add a host.
14
+ * - `write`: exact absolute paths, the kernel's own, never a capability's: the deployment's events
15
+ * directory (sandboxEventsDir), which the kernel creates before the launch
16
+ * (ensureSandboxWritePaths): an allowance on a path that does not exist does not let a
17
+ * sandboxed agent create it.
18
+ *
19
+ * The values are the DEPLOYMENT'S: a resolution's `slots` and `payloads` (what a spawn preview
20
+ * shows), never a file inside an instance home, which a sandboxed agent can write. For an existing
21
+ * home, which deployment and which soul are resolved is the home's PATH'S to say
22
+ * (lib/instance-resolution.mjs homeSandboxSource), never its instance.json's; the one thing read
23
+ * from the home is the list of its modules, which can only leave a host out (homeSandboxAllowances).
24
+ *
25
+ * A leaf: no import of the kernel's heavy modules. Every refusal is E_BACKEND_SANDBOX_HOST, with
26
+ * `details: { capability, setting?, host? }`. */
27
+ import { closeSync, constants as fsConstants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync } from "node:fs";
28
+ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
29
+ import { parseStrictJson } from "./canonical-json.mjs";
30
+ import { oatsError } from "./errors.mjs";
31
+
32
+ /** The slots whose provider may declare `sandboxDomains`. */
33
+ export const SANDBOX_SLOTS = ["messaging", "knowledge", "tasks"];
34
+ /** At most this many lines in one manifest. */
35
+ export const MAX_SANDBOX_LINES = 16;
36
+ const SETTING_KEY_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,79}$/;
37
+ /** A host as an allowlist takes it: DNS labels (letters, digits, hyphens; no wildcard, no
38
+ * underscore), at most 253 characters, or a dotted IPv4 address, which the same pattern covers. */
39
+ const LABEL = "[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?";
40
+ const HOST_RE = new RegExp(`^${LABEL}(?:\\.${LABEL})*$`);
41
+ /** `scheme://[userinfo@]host[:port][/path][?query][#fragment]`, the authority kept as written: WHATWG
42
+ * URL drops a port that is the scheme's default, and the entry carries a port only when the URL names one. */
43
+ const URL_RE = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]*)(?:[/?#].*)?$/i;
44
+
45
+ /** A `settingFile` line's file: at most this many bytes, and this many hosts. */
46
+ export const SETTING_FILE_MAX_BYTES = 64 * 1024, SETTING_FILE_MAX_HOSTS = 16;
47
+ /** A JSON pointer (RFC 6901) of at most 16 segments, of which at most one is `*`: every key of the
48
+ * object, or every element of the array, at that place. */
49
+ const pointerSegments = (pointer) => {
50
+ if (typeof pointer !== "string" || !pointer.startsWith("/") || pointer.length > 400) return null;
51
+ const segments = pointer.slice(1).split("/");
52
+ if (segments.length > 16 || segments.some((s) => s === "" || /~(?![01])/.test(s)) || segments.filter((s) => s === "*").length > 1) return null;
53
+ return segments.map((s) => (s === "*" ? { any: true } : { key: s.replace(/~1/g, "/").replace(/~0/g, "~") }));
54
+ };
55
+ /** A git remote in scp form, `user@host:path` or `host.name:path`: its host. Only a `settingFile`'s
56
+ * strings are read so. `host:<port number>` is a bare host with its port, never this; and without
57
+ * a user the host must have a dot, so that `C:/dir` or `name:path` is no remote. */
58
+ const SCP_REMOTE_RE = /^(?:[A-Za-z0-9._-]+@([A-Za-z0-9.-]+)|([A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+)):(?!\/\/)(?![0-9]{1,5}$)[^\s]+$/;
59
+
60
+ const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
61
+ const refuse = (message, details) => Object.assign(oatsError("E_BACKEND_SANDBOX_HOST", message), { details });
62
+
63
+ /** `manifest.sandboxDomains` as the kernel reads it → `{ lines: [{ setting, optional }], problems:
64
+ * [string] }`. A line is `{ "setting": "<key>" }`, with `"optional": true` when the session works
65
+ * without that host (its absence is then no reason for a provider to refuse a launch).
66
+ * Total: it never throws. A manifest without the key has no lines and no problems. A problem is a
67
+ * refusal wherever the lines are used (sandboxAllowances): a line is never dropped. */
68
+ export function sandboxDomainsOf(manifest) {
69
+ const declared = manifest?.sandboxDomains;
70
+ if (declared === undefined) return { lines: [], problems: [] };
71
+ if (!Array.isArray(declared) || declared.length < 1 || declared.length > MAX_SANDBOX_LINES) return { lines: [], problems: [`sandboxDomains must list 1 to ${MAX_SANDBOX_LINES} entries`] };
72
+ const lines = [], problems = [];
73
+ declared.forEach((line, i) => {
74
+ const keys = isObject(line) ? Object.keys(line) : [];
75
+ if (isObject(line) && Object.hasOwn(line, "settingFile")) {
76
+ if (typeof line.settingFile !== "string" || !SETTING_KEY_RE.test(line.settingFile) || keys.some((k) => k !== "settingFile" && k !== "urls") || !pointerSegments(line.urls)) problems.push(`sandboxDomains[${i}] must be { "settingFile": "<one of the capability's setting keys>", "urls": "<a JSON pointer, at most one * segment>" }`);
77
+ else if (lines.some((l) => (l.settingFile ?? l.setting) === line.settingFile)) problems.push(`sandboxDomains[${i}] names the setting ${line.settingFile} a second time`);
78
+ else lines.push({ settingFile: line.settingFile, urls: line.urls });
79
+ return;
80
+ }
81
+ if (!isObject(line) || typeof line.setting !== "string" || !SETTING_KEY_RE.test(line.setting) || keys.some((k) => k !== "setting" && k !== "optional") || (line.optional !== undefined && typeof line.optional !== "boolean")) problems.push(`sandboxDomains[${i}] must be { "setting": "<one of the capability's setting keys>", "optional"?: true }`);
82
+ else if (lines.some((l) => (l.settingFile ?? l.setting) === line.setting)) problems.push(`sandboxDomains[${i}] names the setting ${line.setting} a second time`);
83
+ else lines.push({ setting: line.setting, optional: line.optional === true });
84
+ });
85
+ if (!SANDBOX_SLOTS.includes(manifest?.layer)) problems.push(`sandboxDomains is for a capability whose layer is ${SANDBOX_SLOTS.join(", ")}: this one declares ${manifest?.layer === undefined ? "none" : JSON.stringify(manifest.layer)}`);
86
+ return { lines, problems };
87
+ }
88
+
89
+ /** The host of a setting's value, as an allowlist entry → `{ host }`, or `{ problem }` saying why
90
+ * the value gives none. The value is a URL (anything with `://`: its host is taken) or a bare host
91
+ * (`host` or `host:port`). The entry is a bare host: lower case, no wildcard, scheme or path; its
92
+ * port only when the value names one. A value that carries credentials is refused whole: nothing
93
+ * of it is quoted. */
94
+ export function sandboxHostOf(value, { userName = false } = {}) {
95
+ if (typeof value !== "string" || !value.trim()) return { problem: "is not a URL or a host" };
96
+ const text = value.trim();
97
+ const m = URL_RE.exec(text);
98
+ if (!m && /[/?#\s]/.test(text)) return { problem: "is neither a URL with a scheme and a host nor a bare host" };
99
+ const authority = m ? m[2] : text;
100
+ // A user name alone is no credential (a git remote carries one), where the caller reads such values.
101
+ const user = authority.includes("@") ? authority.slice(0, authority.lastIndexOf("@")) : null;
102
+ if (user !== null && !(userName && m && /^[A-Za-z0-9._-]+$/.test(user))) return { problem: "is a URL that carries credentials" };
103
+ const hostPort = user === null ? authority : authority.slice(user.length + 1);
104
+ const at = hostPort.lastIndexOf(":");
105
+ const [name, port] = at >= 0 && !hostPort.endsWith("]") ? [hostPort.slice(0, at), hostPort.slice(at + 1)] : [hostPort, null];
106
+ const host = name.toLowerCase();
107
+ if (!host) return { problem: "is a URL without a host" };
108
+ if (host.includes("*")) return { problem: `names a wildcard host (${host}): an allowance is one exact host` };
109
+ if (host.length > 253 || !HOST_RE.test(host)) return { problem: "names a host that is no plain DNS name or IPv4 address" };
110
+ if (port !== null && (!/^[0-9]{1,5}$/.test(port) || Number(port) < 1 || Number(port) > 65535)) return { problem: "names a port that is no port number" };
111
+ return { host: port === null ? host : `${host}:${Number(port)}` };
112
+ }
113
+
114
+ /** The hosts a `settingFile` line gives → `{ hosts: [host] }`, `{ unread: "<why>" }` when the file
115
+ * gives none this kernel will use (missing, not a regular file, too large, no strict JSON, more
116
+ * than SETTING_FILE_MAX_HOSTS hosts: the launch goes on without them, and readiness names it), or
117
+ * `{ refused: "<why>" }` when the path itself is one no allowance may be read from.
118
+ *
119
+ * `path`: the setting's value. `within`: the deployment's directory. `outside`: directories inside
120
+ * it that are never a source (its instance homes, the paths the allowances make writable). The
121
+ * path must be inside `within` and outside each of those, as its REAL path, with no symbolic link
122
+ * anywhere along it below the deployment: a link planted in a parent directory cannot move the
123
+ * read to a file a sandboxed agent can write. The file is opened without following a link, as a
124
+ * regular file, and read once, at most SETTING_FILE_MAX_BYTES.
125
+ *
126
+ * A string at the pointer gives a host when it is a URL with a plain host (a user name is allowed,
127
+ * as git remotes carry one; a password is not) or a git remote in scp form (`git@host:path`);
128
+ * another string is skipped and counted in `skippedValues`. */
129
+ export function readSettingFileHosts({ path, pointer, within, outside = [] }) {
130
+ if (typeof path !== "string" || !path.trim()) return { unread: "the setting names no file" };
131
+ let root;
132
+ try { root = realpathSync(within); } catch (e) { return { refused: `the deployment's directory cannot be resolved (${e.code ?? e.message})` }; }
133
+ // The path as written, under the deployment's real directory. An absolute path may spell the
134
+ // deployment through a link; it is re-rooted at the FIRST place it enters the deployment, the
135
+ // outermost of its ancestors whose real path is the deployment's, and from there down no link
136
+ // is allowed. Outermost, never nearest: a link below the deployment that leads back to it (one
137
+ // an agent makes in its home) is then part of what must be link-free, not a new root. And the
138
+ // same whichever spelling the caller knows the deployment by (a spawn's `--dir`, a start's real
139
+ // path): both read the same file, or both refuse.
140
+ const written = resolve(isAbsolute(path) ? path : resolve(within, path));
141
+ let entered = null;
142
+ for (let dir = dirname(written); ; dir = dirname(dir)) {
143
+ try { if (realpathSync(dir) === root) entered = dir; } catch { /* not there: the file is not either, said below */ }
144
+ if (dirname(dir) === dir) break;
145
+ }
146
+ const rel = entered === null ? null : relative(entered, written);
147
+ const below = rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
148
+ if (!below) return { refused: `${path} is not inside the deployment (${root}): a host is read only from the deployment's own files` };
149
+ const target = resolve(root, below);
150
+ const inside = (dir) => { const rel = relative(dir, target); return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel)); };
151
+ const forbidden = outside.map((dir) => { try { return realpathSync(dir); } catch { return resolve(dir); } }).find(inside);
152
+ if (forbidden) return { refused: `${path} is inside ${forbidden}, which a session's agent can write: a host is never read from there` };
153
+ let real;
154
+ try { real = realpathSync(target); } catch (e) { return e.code === "ENOENT" || e.code === "ENOTDIR" ? { unread: `${target} does not exist` } : { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
155
+ if (real !== target) return { refused: `${path} reaches its file through a symbolic link (${target} is ${real}): a host is read only from a path with no link along it` };
156
+ let fd;
157
+ try { fd = openSync(target, fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0)); } catch (e) { return { unread: `${target} cannot be opened (${e.code ?? e.message})` }; }
158
+ let doc;
159
+ try {
160
+ const st = fstatSync(fd);
161
+ if (!st.isFile()) return { unread: `${target} is not a regular file` };
162
+ // Another name of the same file could be in a place a session's agent can write. (What this
163
+ // sees is a second name that exists NOW: one made, written through and removed before this
164
+ // read is not seen. The file's own mode and place are what keep it from that.)
165
+ if (st.nlink > 1) return { unread: `${target} has more than one hard link` };
166
+ if (st.size > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
167
+ const buffer = Buffer.alloc(SETTING_FILE_MAX_BYTES + 1);
168
+ let length = 0;
169
+ for (let n; length < buffer.length && (n = readSync(fd, buffer, length, buffer.length - length, null)) > 0;) length += n;
170
+ if (length > SETTING_FILE_MAX_BYTES) return { unread: `${target} is larger than ${SETTING_FILE_MAX_BYTES / 1024} KiB` };
171
+ try { doc = parseStrictJson(buffer.subarray(0, length), { maxBytes: SETTING_FILE_MAX_BYTES }); } catch { return { unread: `${target} is not strict JSON` }; }
172
+ } catch (e) { return { unread: `${target} cannot be read (${e.code ?? e.message})` }; }
173
+ finally { closeSync(fd); }
174
+ // Every value at the pointer.
175
+ let values = [doc];
176
+ for (const segment of pointerSegments(pointer) ?? []) {
177
+ values = values.flatMap((v) => {
178
+ if (segment.any) return Array.isArray(v) ? v : v !== null && typeof v === "object" ? Object.values(v) : [];
179
+ if (Array.isArray(v)) return /^(0|[1-9][0-9]*)$/.test(segment.key) && Number(segment.key) < v.length ? [v[Number(segment.key)]] : [];
180
+ return v !== null && typeof v === "object" && Object.hasOwn(v, segment.key) ? [v[segment.key]] : [];
181
+ });
182
+ }
183
+ const hosts = [];
184
+ let skippedValues = 0;
185
+ for (const value of values) {
186
+ const scp = typeof value === "string" ? SCP_REMOTE_RE.exec(value.trim()) : null;
187
+ const { host } = scp ? sandboxHostOf(scp[1] ?? scp[2]) : sandboxHostOf(value, { userName: true });
188
+ if (!host) skippedValues += 1;
189
+ else if (!hosts.includes(host)) hosts.push(host);
190
+ }
191
+ if (hosts.length > SETTING_FILE_MAX_HOSTS) return { unread: `${target} names ${hosts.length} hosts, more than the ${SETTING_FILE_MAX_HOSTS} one file may give` };
192
+ return { hosts, skippedValues };
193
+ }
194
+
195
+ /** The path the kernel itself allows a sandboxed session to write: the deployment's events
196
+ * directory (`<deployment>/.agents/events`, where lib/instance-events.mjs appends a home's events
197
+ * and `oats instance attention` its claim), under the deployment's REAL path. `deployment` is the
198
+ * caller's, established outside any instance home. */
199
+ export function sandboxEventsDir(deployment) {
200
+ let real;
201
+ try { real = realpathSync(deployment); } catch { real = resolve(deployment); }
202
+ return join(real, ".agents", "events");
203
+ }
204
+ /** What ensureSandboxWritePaths would refuse of `write`, without creating anything (a readiness
205
+ * read): a path that exists and is not a real directory at exactly that path, or whose nearest
206
+ * existing ancestor is reached through a link → the refusal, or null. */
207
+ export function sandboxWritePathsRefusal(write) {
208
+ for (const { path } of write ?? []) {
209
+ // The nearest ancestor that is THERE, a link that leads nowhere included (lstat, which does
210
+ // not follow one): a launch would refuse that link, so a read does.
211
+ const there = (at) => { try { lstatSync(at); return true; } catch { return false; } };
212
+ let ancestor = path;
213
+ while (!there(ancestor) && dirname(ancestor) !== ancestor) ancestor = dirname(ancestor);
214
+ let sound;
215
+ try { sound = realpathSync(ancestor) === ancestor && (ancestor !== path || lstatSync(path).isDirectory()); } catch { sound = false; }
216
+ if (!sound) return refuse(`the session's sandbox may not be allowed to write ${path}: it is reached through a symbolic link, or is no directory; nothing was created or launched`, { capability: null, setting: null, host: null, path });
217
+ }
218
+ return null;
219
+ }
220
+ /** Make the `write` paths of an allowance exist, right before the launch that is handed them, and
221
+ * hold each to what it must be: a real directory at exactly that path, reached through no symbolic
222
+ * link. A path that is anything else is refused (E_BACKEND_SANDBOX_HOST): an allowance on it would
223
+ * let the session write wherever the link leads. */
224
+ export function ensureSandboxWritePaths(write) {
225
+ for (const { path } of write ?? []) {
226
+ // Nothing is created through a link: what a read would refuse is refused before anything is made.
227
+ const refused = sandboxWritePathsRefusal([{ path }]);
228
+ if (refused) throw refused;
229
+ try {
230
+ mkdirSync(path, { recursive: true });
231
+ if (realpathSync(path) !== path || !lstatSync(path).isDirectory()) throw Object.assign(new Error("it is reached through a symbolic link, or is no directory"), { code: "ELOOP" });
232
+ } catch (e) {
233
+ throw refuse(`the session's sandbox may not be allowed to write ${path}: ${e.code === "ELOOP" ? e.message : `it cannot be made (${e.code ?? e.message})`}; nothing was created or launched`, { capability: null, setting: null, host: null, path });
234
+ }
235
+ }
236
+ }
237
+ /** The allowances of a launch of an EXISTING home (a start, a restart; readiness): the deployment's
238
+ * resolution for the home's soul (`source`: lib/instance-resolution.mjs homeSandboxSource, which
239
+ * takes the deployment and the soul from where the home is, never from what is in it), with hosts
240
+ * only for the capabilities that are also the home's modules (`moduleNames`, the home's own
241
+ * record: it can only leave a host of that resolution out, never add one). `home`: its real path. */
242
+ export function homeSandboxAllowances({ source, home, moduleNames }) {
243
+ const eventsDir = sandboxEventsDir(source.deployment);
244
+ return sandboxAllowances({ modules: source.modules, slots: source.slots, payloads: source.payloads, teams: source.teams, defaultTeam: source.defaultTeam ?? null, eventsDir, only: moduleNames, deployment: source.deployment, outside: [dirname(dirname(dirname(home))), eventsDir] });
245
+ }
246
+
247
+ /** What a provider's launch is handed of the allowances: the three lists, each host with the
248
+ * capability and the setting that asked for it, never the kernel's own notes (a host's `team`,
249
+ * `skipped`, `unread`), which are for the answer and for readiness. */
250
+ export const sandboxLaunchInput = ({ domains, write, missing }) => ({ domains: domains.map(({ host, capability, setting }) => ({ host, capability, setting })), write, missing });
251
+
252
+ /** The allowances of one launch → `{ domains: [{ host, capability, setting, team? }], write: [{ path, reason }],
253
+ * missing: [{ capability, setting, team, defaultTeam, optional? }] }` (`sandboxLaunchInput` is what a
254
+ * provider is handed of it). `missing`: what a line names and the deployment's configuration does
255
+ * not hold: a team of the instance with no entry in a map (`team`: its id), or a setting with no
256
+ * value at all (`team: null`). `defaultTeam` is true on the row of the soul's default team and on
257
+ * a row with `team: null`, false on another team's; `optional: true` on a row of a line declared
258
+ * so. The kernel adds no host for those and refuses nothing: a provider that would sandbox the
259
+ * session refuses on a row that is not optional and whose `defaultTeam` is true (without its
260
+ * default team's service the agent has no messaging at all), since only it knows its mode; the
261
+ * other rows are for readiness.
262
+ *
263
+ * `modules`: the instance's capabilities, `[{ name, manifest }]`. `slots`: `{ messaging, knowledge,
264
+ * tasks }`, each the name of the capability that fills it, or null. `payloads`: `{ <capability>:
265
+ * { <setting>: value } }`, the deployment's effective settings, and `origins` (`{ <capability>: {
266
+ * <JSON pointer>: { kind } } }`, a resolution's `payloadOrigins`) where each came from. `teams`: the instance's team ids
267
+ * (the `team` of each row of the resolution's `teams`) and `defaultTeam`, the id of the soul's
268
+ * default team there, or null. `eventsDir`: the deployment's events
269
+ * directory, absolute. `deployment` and `outside`: where a `settingFile` line's file may be (inside
270
+ * the first, outside each of the second: readSettingFileHosts); `unread: [{ capability, setting,
271
+ * reason }]`, in the answer only when there is one, names each such file that gave no host, or
272
+ * values in it that were skipped. `only`, when given (a start of an existing home): the names of the home's
273
+ * own modules; a slot's provider of the deployment that is not one of them contributes no host
274
+ * and is named in `skipped: [{ capability, reason }]`, which is in the answer only then.
275
+ *
276
+ * Refused (E_BACKEND_SANDBOX_HOST), naming the capability and what it asked for: a malformed
277
+ * declaration; a capability that declares the line and fills none of the three slots; a setting
278
+ * a line names whose value was given to this spawn alone (origin `spawn`); a setting whose value
279
+ * is set and gives no plain host. A setting with no value contributes no host and is
280
+ * listed in `missing`. Of a map (team id → URL or host) only the entries of the instance's teams
281
+ * are read: another team's entry is neither taken nor judged, and a team without an entry
282
+ * contributes no host and is listed in `missing`.
283
+ * Hosts are deduplicated: the first capability, in `modules` order, to ask for one is named. */
284
+ export function sandboxAllowances({ modules = [], slots = {}, payloads = {}, origins = {}, teams = [], defaultTeam = null, eventsDir, only, deployment, outside = [] }) {
285
+ const domains = [], skipped = [], missing = [], unread = [];
286
+ for (const { name, manifest } of modules) {
287
+ if (manifest?.sandboxDomains === undefined) continue;
288
+ const { lines, problems } = sandboxDomainsOf(manifest);
289
+ const slot = SANDBOX_SLOTS.find((s) => slots?.[s] === name);
290
+ // One entry per value a line names: the setting's own, or each of the instance's teams' in a map.
291
+ const asked = lines.filter((l) => l.setting !== undefined).flatMap(({ setting, optional }) => {
292
+ const value = isObject(payloads?.[name]) && Object.hasOwn(payloads[name], setting) ? payloads[name][setting] : undefined;
293
+ if (!isObject(value)) return [{ setting, optional, team: null, value }];
294
+ return teams.filter((team, i) => typeof team === "string" && teams.indexOf(team) === i).map((team) => ({ setting, optional, team, value: Object.hasOwn(value, team) ? value[team] : undefined }));
295
+ });
296
+ if (!slot) {
297
+ // Named with the host it asked for, where its setting gives one.
298
+ const first = asked.map((l) => ({ setting: l.setting, host: sandboxHostOf(l.value).host ?? null })).find((l) => l.host) ?? { setting: asked[0]?.setting ?? null, host: null };
299
+ throw refuse(`capability ${name} declares sandboxDomains${first.host ? ` (the host ${first.host}, from its setting ${first.setting})` : ""}, and it is not this instance's ${SANDBOX_SLOTS.join(", ")} provider: only the capability that fills one of those slots may add a host to a session's sandbox; nothing was launched`, { capability: name, setting: first.setting, host: first.host });
300
+ }
301
+ if (only && !only.includes(name)) { skipped.push({ capability: name, reason: `the deployment's ${slot} provider is ${name}, which is not one of this home's modules: its hosts are not allowed here (respawn the instance to take the deployment's composition)` }); continue; }
302
+ // A value given to one spawn (`--provider <capability> <setting>=…`) is a launch's own
303
+ // argument, never the deployment's configuration: no host comes from it, and it is not passed
304
+ // over in silence either (the next start would resolve another host without a word).
305
+ const pointer = (setting) => `/${String(setting).replace(/~/g, "~0").replace(/\//g, "~1")}`;
306
+ const perSpawn = lines.map((l) => l.setting ?? l.settingFile).find((setting) => Object.entries(isObject(origins?.[name]) ? origins[name] : {}).some(([at, origin]) => (at === pointer(setting) || at.startsWith(`${pointer(setting)}/`)) && origin?.kind === "spawn"));
307
+ if (perSpawn !== undefined) throw refuse(`capability ${name} asks to allow the host of its setting ${perSpawn}, and this spawn was given that setting itself (--provider ${name} ${perSpawn}=…): a host comes from the deployment's configuration (the soul, the workspace, oats-local.yaml), never from a launch's own arguments; set it there, or leave it out of this spawn; nothing was launched`, { capability: name, setting: perSpawn, host: null });
308
+ if (problems.length) throw refuse(`capability ${name} declares a sandboxDomains this kernel cannot use: ${problems.join("; ")}; nothing was launched`, { capability: name, setting: null, host: null });
309
+ for (const { setting, optional, team, value } of asked) {
310
+ if (value === undefined || value === null || value === "") { missing.push({ capability: name, setting, team, defaultTeam: team === null || team === defaultTeam, ...(optional ? { optional: true } : {}) }); continue; }
311
+ const { host, problem } = sandboxHostOf(value);
312
+ if (!host) throw refuse(`capability ${name} asks to allow the host of its setting ${setting}${team === null ? "" : ` for team ${team}`}, whose value ${problem}; nothing was launched`, { capability: name, setting, host: null, ...(team === null ? {} : { team }) });
313
+ // A host from a map says whose it is: the team's id. The team is one the instance MAY join
314
+ // (a row of the resolution's `teams`), which is not to say it has.
315
+ if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting, ...(team === null ? {} : { team }) });
316
+ }
317
+ // A `settingFile` line: the hosts of a file of the deployment. A path that may not be read
318
+ // from refuses; a file that gives nothing is named, and the launch goes on without its hosts.
319
+ for (const { settingFile: setting, urls } of lines.filter((l) => l.settingFile !== undefined)) {
320
+ const path = isObject(payloads?.[name]) ? payloads[name][setting] : undefined;
321
+ const read = readSettingFileHosts({ path, pointer: urls, within: deployment, outside });
322
+ if (read.refused) throw refuse(`capability ${name} asks to allow the hosts in the file its setting ${setting} names, and ${read.refused}; nothing was launched`, { capability: name, setting, host: null });
323
+ if (read.unread) { unread.push({ capability: name, setting, reason: read.unread }); continue; }
324
+ for (const host of read.hosts) if (!domains.some((d) => d.host === host)) domains.push({ host, capability: name, setting });
325
+ if (read.skippedValues) unread.push({ capability: name, setting, reason: `${read.skippedValues} ${read.skippedValues === 1 ? "value" : "values"} at ${urls} ${read.skippedValues === 1 ? "is" : "are"} no URL with a plain host, and ${read.skippedValues === 1 ? "was" : "were"} skipped` });
326
+ }
327
+ }
328
+ return { domains, write: [{ path: eventsDir, reason: "oats events" }], missing, ...(skipped.length ? { skipped } : {}), ...(unread.length ? { unread } : {}) };
329
+ }
package/lib/schedule.mjs CHANGED
@@ -35,6 +35,7 @@ import { herdrSettingRemoved } from "./errors.mjs";
35
35
  import { withDirLock as withSharedDirLock } from "./dir-lock.mjs";
36
36
  import { pollSourced, tickTriggers } from "./triggers.mjs";
37
37
  import { SCHEDULE_NAME_RE, HOST_NAME_RE, readSnapshot, hostOf, trusted, parseOwner, MODEL_RE, automationError, baseRow, localEntry, localId, soulOriginOf, splitId, validateDescription } from "./automations.mjs";
38
+ import { SESSION_PROVIDER_NAME_RE } from "./kernel-features.mjs";
38
39
  import { MAX_INSTANCE_NAME, shq, shellWord, findAgent, findInstanceHomes, inspectInstanceSession, inputInstanceSession, sessionServerGone, startInstanceSession, retirePendingMarkerPath } from "./core.mjs";
39
40
  import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
40
41
  import { readStartExited } from "./session-end.mjs";
@@ -487,7 +488,9 @@ export function validateDefinition(ws, def, { checkAgent = true, backendSource,
487
488
  }
488
489
  if (def.repo !== undefined) { if (typeof def.repo !== "string" || !def.repo.trim() || def.repo.startsWith("-")) throw scheduleError("E_SCHEDULE_INVALID", "repo: the work repository path, as oats spawn --repo", { field: "repo" }); out.repo = def.repo; }
489
490
  if (def.backend === "herdr") throw herdrBackendRefusal(backendSource ?? `${definitionsPath(ws)} sets jobs.${id}.backend`);
490
- if (def.backend !== undefined) { if (def.backend !== "tmux") throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux", { field: "backend" }); out.backend = def.backend; }
491
+ // tmux, or a session provider of the soul's capabilities (lib/session-providers.mjs): a name here;
492
+ // the run's spawn resolves it against the instance's modules (E_BACKEND_UNKNOWN, E_BACKEND_HARNESS).
493
+ if (def.backend !== undefined) { if (typeof def.backend !== "string" || !SESSION_PROVIDER_NAME_RE.test(def.backend)) throw scheduleError("E_SCHEDULE_INVALID", "backend: tmux, or a session provider's name (1 to 40 lowercase letters, digits and dashes)", { field: "backend" }); out.backend = def.backend; }
491
494
  if (def.purpose !== undefined) { if (typeof def.purpose !== "string" || !/^[a-z0-9-]{1,40}$/.test(def.purpose)) throw scheduleError("E_SCHEDULE_INVALID", "purpose: lowercase letters, digits and dashes", { field: "purpose" }); out.purpose = def.purpose; }
492
495
  // A run spawns <agent>-<purpose|id>-<YYYYMMDDHHMM>; instance names are at most
493
496
  // MAX_INSTANCE_NAME characters, so refuse here what would fail at every firing.
@@ -646,8 +649,12 @@ export function observeHome(home, io) {
646
649
  const retiring = existsSync(retirePendingMarkerPath(home));
647
650
  try {
648
651
  const s = (io?.inspect || inspectInstanceSession)(home);
649
- if (s.present && s.state !== "shell") return { outcome: "active", ...(retiring ? { note: "retiring" } : {}) };
652
+ // A home on a session provider (its inspect answer carries `session`): a wake never starts it
653
+ // (performWake). Its session in error (`shell`) is no startup phase: an input recovers it.
654
+ const provider = s.session !== undefined && s.session !== null ? { provider: true } : {};
655
+ if (s.present && s.state !== "shell") return { outcome: "active", ...provider, ...(retiring ? { note: "retiring" } : {}) };
650
656
  if (retiring) return { outcome: "active", note: "retiring: home present, teardown pending" };
657
+ if (provider.provider) return { outcome: "stopped", ...provider };
651
658
  // A shell right after `session start` is that launch's startup phase
652
659
  // until its wrapper writes the exit marker for the launch id; only then
653
660
  // (or with no start receipt at all) is a shell a finished harness.
@@ -915,7 +922,10 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve,
915
922
  if (seen.outcome === "ended") return { kind: "wake", action: "skipped", reason: "home is gone", pending: false };
916
923
  if (seen.outcome === "unknown") return { kind: "wake", action: "skipped", reason: `cannot observe the session: ${seen.error}`, pending: true };
917
924
  if (seen.outcome === "starting") return { kind: "wake", action: "skipped", reason: "session is starting; delivery pending", pending: true };
918
- if (seen.outcome === "stopped") {
925
+ // A home on a session provider is never started by a wake: the wake is its session's input, which
926
+ // the kernel refuses (E_SESSION_NOT_RUNNING, before any provider call) for a home OATS stopped,
927
+ // and which the provider answers for any other.
928
+ if (seen.outcome === "stopped" && !seen.provider) {
919
929
  if (!startIfStopped) return { kind: "wake", action: "skipped", reason: "session stopped; it is started again only at the next due minute; delivery pending", pending: true };
920
930
  if (!canStart) return { kind: "wake", action: "skipped", reason: "host busy: starting this session needs a launch slot; delivery pending", pending: true };
921
931
  // The slot is persisted BEFORE the start call and kept on a start
@@ -945,7 +955,7 @@ function performWake(def, io, { startIfStopped = true, canStart = true, reserve,
945
955
  // Delivery custody: name the instance ONLY when the input result names it; the home's current incarnation at record time.
946
956
  return { kind: "wake", action: "delivered", pending: false, ...(typeof r?.instance === "string" ? { instance: r.instance } : {}), home: def.home, incarnation: incarnationOfHome(def.home) };
947
957
  }
948
- catch (e) { return { kind: "wake", action: "skipped", reason: `input refused: ${e.message}`, pending: true }; }
958
+ catch (e) { return { kind: "wake", action: "skipped", reason: `input refused: ${e.message}`, ...(seen.provider && typeof e?.code === "string" ? { errorCode: e.code } : {}), pending: true }; }
949
959
  }
950
960
 
951
961
  /** A held run as the tick records it: `held.since` is the first skip's time, kept on