@awebai/oats 0.69.24 → 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.
@@ -0,0 +1,329 @@
1
+ /** What the kernel runs of a provider home (docs/capabilities.md "What the kernel trusts in a
2
+ * provider home"; the contract's D16 rule 3).
3
+ *
4
+ * A home on a session provider can be written by its own agent: the provider may run the harness
5
+ * in a sandbox that still writes the home, and the kernel that runs the home's hooks and its
6
+ * provider's commands runs outside any sandbox, as the operator, WHILE that agent runs. So for
7
+ * such a home the kernel runs nothing that is in the home, and takes no capability setting from it:
8
+ *
9
+ * - the kernel keeps its OWN copy of the home's modules, outside the home, beside the home's
10
+ * receipt (`<instances>/.oats-retirement/modules/<hash of the home>/<store>/<capability>/`):
11
+ * made by the spawn from the copies it materialised, before the provider is asked anything
12
+ * and before any hook of the spawn runs.
13
+ * `oats instance upgrade` makes a new one beside it (another `<store>`) and the receipt's one
14
+ * write then names it, with the rows that go with it: an upgrade that fails before that write
15
+ * leaves the old copy and the old rows, together; after it, the new ones. Every hook,
16
+ * every command of the provider, every readiness check and every dispatched command of such a
17
+ * home is run from there, and its manifests are read there. The copies in the home are the
18
+ * agent's own (its skills, what its harness runs inside its sandbox): the kernel never runs
19
+ * them, so nothing the agent does to them, at any moment, changes what the kernel runs;
20
+ * - the home's receipt (lib/session-receipt.mjs) carries its `composition`: which store holds
21
+ * the kernel's copies, which modules the home has and where each came from, and the
22
+ * capability rows the spawn resolved from the
23
+ * deployment (settings, their origins, levels, and the hook commands, which name the kernel's
24
+ * copy). A capability's row is the receipt's, never instance.json's `capabilityRuntime`.
25
+ *
26
+ * Why a copy and not a check: a copy in the home that is hashed and then run can be exchanged
27
+ * between the two by the session that writes the home, for as long as the command takes to
28
+ * start and for as long as it runs.
29
+ *
30
+ * A tmux home is unchanged, and why: its agent already runs unsandboxed as the operator, and can
31
+ * do directly whatever a module it rewrote could. This protects nothing against an agent that
32
+ * can write outside its home: a provider that sandboxes keeps `<instances>/.oats-retirement/`
33
+ * unwritable.
34
+ *
35
+ * A leaf: it reads and copies files, and knows nothing of sessions or of core.mjs. */
36
+ import { cpSync, lstatSync, mkdirSync, readdirSync, rmSync } from "node:fs";
37
+ import { randomBytes } from "node:crypto";
38
+ import { basename, dirname, join, sep } from "node:path";
39
+ import { homeModulesStore, homeReceipt, isPlainObject, readJsonOrUndefined } from "./session-receipt.mjs";
40
+
41
+ /** What a row's `moduleCopy.differs` may name: capability ids (the manifest grammar's), each of
42
+ * at most this length, and at most this many. */
43
+ const MODULE_ID_RE = /^[a-z0-9][a-z0-9._-]*$/;
44
+ const MODULE_COPY_ID_MAX = 200, MODULE_COPY_IDS_MAX = 200;
45
+ /** The version of a receipt's `composition`. */
46
+ export const COMPOSITION_VERSION = 1;
47
+ const byCodeUnit = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
48
+ /** Where a home keeps ITS copy of capability `id` (the agent's own). */
49
+ const homeModuleDir = (home, id) => join(home, ".oats", "modules", id);
50
+ const STORE_RE = /^[a-f0-9]{12}$/;
51
+ /** Where the kernel keeps its copy of capability `id` of the home `home`, which is what it runs:
52
+ * in the store the home's receipt names (`trust`: providerHomeTrust's answer, read here when it
53
+ * is not given). A path that does not exist when the receipt names no store. */
54
+ export function kernelModuleDir(home, id, trust = providerHomeTrust(home)) {
55
+ return kernelModuleDirIn(home, trust?.composition?.store ?? "-", id);
56
+ }
57
+ /** The same, in the store named `store`: the one a receipt is about to name (an upgrade's new
58
+ * one), or named before (the one an undo goes back to). */
59
+ export const kernelModuleDirIn = (home, store, id) => join(homeModulesStore(home), store, id);
60
+ /** The home a module copy belongs to, when `dir` is `<home>/.oats/modules/<id>`: `{ home, id }`,
61
+ * else null (a deployment's own module store, a soul's tree, the kernel's own copy). */
62
+ export function homeOfModuleCopy(dir) {
63
+ if (typeof dir !== "string" || basename(dirname(dir)) !== "modules" || basename(dirname(dirname(dir))) !== ".oats") return null;
64
+ return { home: dirname(dirname(dirname(dir))), id: basename(dir) };
65
+ }
66
+ /** A shell word as the kernel renders one (lib/core.mjs shq): what a path looks like inside a hook command. */
67
+ const shellEscaped = (text) => text.replace(/'/g, `'\\''`);
68
+ /** A capability row whose hook commands name the home's copies → the row with them naming the
69
+ * kernel's copies: the path of the home's modules directory, where a rendered command holds it
70
+ * (`node '<home>/.oats/modules/<id>/<script>' …`), becomes the store's. */
71
+ function repointed(home, row, store, earlier) {
72
+ if (!isPlainObject(row?.hooks)) return row;
73
+ const to = shellEscaped(`${join(homeModulesStore(home), store)}${sep}`);
74
+ // From the home's copies (a row a spawn or an upgrade has just resolved), and from the store an
75
+ // earlier receipt named (a row of a module an upgrade did not move).
76
+ const from = [`${join(home, ".oats", "modules")}${sep}`, ...(earlier ? [`${join(homeModulesStore(home), earlier)}${sep}`] : [])].map(shellEscaped);
77
+ const hooks = Object.fromEntries(Object.entries(row.hooks).map(([event, command]) => [event, typeof command === "string" ? from.reduce((text, prefix) => text.split(prefix).join(to), command) : command]));
78
+ return { ...row, hooks };
79
+ }
80
+ /** The capability rows a receipt holds, naming the copies in `store`, from the rows a spawn or an
81
+ * upgrade resolved (`earlier`: the store the home's receipt named until now). */
82
+ const storedRows = (home, rows, store, earlier = null) => JSON.parse(JSON.stringify(rows ?? [])).map((row) => repointed(home, row, store, earlier));
83
+ /** A new store for a home's kernel copies: its name, and its directory, made. */
84
+ function newStore(home) {
85
+ const store = randomBytes(6).toString("hex"), dir = join(homeModulesStore(home), store);
86
+ mkdirSync(dir, { recursive: true, mode: 0o700 });
87
+ return { store, dir };
88
+ }
89
+ /** Copy a module's tree into a store: links as links, never followed, and nothing overwritten.
90
+ * A `.git` at the module's root is left out: the digest a module is verified by passes over it
91
+ * (lib/remote.mjs contentDigest), so what the kernel keeps is exactly what was verified. */
92
+ function copyModule(from, to) {
93
+ cpSync(from, to, { recursive: true, verbatimSymlinks: true, errorOnExist: true, force: false, filter: (source) => source !== join(from, ".git") });
94
+ }
95
+
96
+ /** Take away the kernel's copies of a home's modules, every store of them: a retire's and a
97
+ * spawn's rollback's last act on them, and a spawn's first (whatever an earlier home of that
98
+ * path left). */
99
+ export function removeModulesStore(home) {
100
+ rmSync(homeModulesStore(home), { recursive: true, force: true });
101
+ }
102
+ /** Take away every store of a home's kernel copies but the ones its receipt names: the one the
103
+ * kernel runs from, and the one before it (`composition.previous`), which an undo goes back to.
104
+ * Called only once a move is COMPLETE (its receipt written, and nothing left that could put the
105
+ * earlier receipt back): what it removes is what no receipt names any more and none will again
106
+ * (the store before the previous one, after a move; the newer one, after an undo), and what an
107
+ * earlier move that was interrupted had made and never named. */
108
+ export function pruneModulesStores(home) {
109
+ const composition = providerHomeTrust(home)?.composition;
110
+ if (!composition) return;
111
+ const keep = new Set([composition.store, ...(composition.previous ? [composition.previous.store] : [])]);
112
+ let names;
113
+ try { names = readdirSync(homeModulesStore(home)); } catch { return; }
114
+ for (const name of names) if (!keep.has(name)) rmSync(join(homeModulesStore(home), name), { recursive: true, force: true });
115
+ }
116
+ /** The composition an upgrade leaves a provider home, with the kernel's copies for it in a NEW
117
+ * store, beside the one the receipt names now: each module in `moved` copied from
118
+ * `source(id)` (the copy the upgrade has just found to be the one it verified against the lock:
119
+ * by default the home's own), every other module copied from the kernel's own current copy;
120
+ * `modules` (`{ <id>: { from?, commit? } }`) and `rows` are what the upgrade derived. Its
121
+ * `previous` is the composition the receipt names now (its store, modules and rows), which an
122
+ * undo goes back to. Nothing the receipt names is touched: the caller's ONE write of the
123
+ * receipt is what makes the new store and the new rows the home's, together. Throws, with the
124
+ * new store removed, when a copy cannot be made. */
125
+ export function upgradedComposition(home, trust, { moved, modules, rows, source = (id) => homeModuleDir(home, id) }) {
126
+ const { store, dir } = newStore(home);
127
+ try {
128
+ for (const id of Object.keys(modules).sort(byCodeUnit)) copyModule(moved.has(id) ? source(id) : kernelModuleDir(home, id, trust), join(dir, id));
129
+ } catch (e) { rmSync(dir, { recursive: true, force: true }); throw e; }
130
+ const { store: earlier, modules: earlierModules, capabilityRuntime: earlierRows } = trust.composition;
131
+ return { version: COMPOSITION_VERSION, store, modules, capabilityRuntime: storedRows(home, rows, store, earlier).filter((row) => Object.hasOwn(modules, row?.id)),
132
+ previous: { store: earlier, modules: earlierModules, capabilityRuntime: earlierRows } };
133
+ }
134
+ /** Take away the store `store` of a home's kernel copies, unless the home's receipt names it (as
135
+ * the one it runs from, or the previous one): what a move that failed had made, and nothing else. */
136
+ export function removeUnnamedStore(home, store) {
137
+ const composition = providerHomeTrust(home)?.composition;
138
+ if (!store || composition?.store === store || composition?.previous?.store === store) return;
139
+ rmSync(join(homeModulesStore(home), store), { recursive: true, force: true });
140
+ }
141
+ /** The composition an undo goes back to: the one the receipt keeps as `previous` (its store, which
142
+ * is still there, with its modules and rows), with no `previous` of its own; null when the
143
+ * receipt keeps none. Nothing is copied: the one write of the receipt names that store again. */
144
+ export function previousComposition(trust) {
145
+ const previous = trust?.composition?.previous;
146
+ return previous ? { version: COMPOSITION_VERSION, store: previous.store, modules: previous.modules, capabilityRuntime: previous.capabilityRuntime } : null;
147
+ }
148
+
149
+ /** A provider home's composition, as its spawn records it in the receipt, with the kernel's own
150
+ * copy of every module put in place: `{ version, store, modules: { <id>: { from?, commit? } },
151
+ * capabilityRuntime: [<row>] }` (an upgrade adds `previous: { store, modules, capabilityRuntime }`,
152
+ * the one it replaced). The modules are the directories under `<home>/.oats/modules/`
153
+ * as they are now, and `from` and `commit` (where each came from: what an upgrade moves it
154
+ * from) are the home's record's as it is now. A spawn calls this ONCE, at its first write of
155
+ * the receipt, which in every work mode is before its provider is asked to launch, so before
156
+ * the home's agent exists; every later write of that spawn keeps what this recorded (lib/core.mjs
157
+ * writeRetirementBaseline). `rows` are the capability rows the spawn resolved. Throws when a
158
+ * copy cannot be made: a spawn that cannot keep what it made records nothing. */
159
+ export function compositionOf(home, rows) {
160
+ const root = join(home, ".oats", "modules");
161
+ const recorded = readJsonOrUndefined(join(home, "instance.json"))?.modules;
162
+ const modules = {};
163
+ let names;
164
+ try { names = readdirSync(root).sort(byCodeUnit); } catch (e) { if (e?.code !== "ENOENT") throw e; names = []; }
165
+ removeModulesStore(home);
166
+ const { store, dir } = newStore(home);
167
+ for (const id of names) {
168
+ if (!lstatSync(join(root, id)).isDirectory()) continue;
169
+ copyModule(join(root, id), join(dir, id));
170
+ const source = isPlainObject(recorded) && Object.hasOwn(recorded, id) && isPlainObject(recorded[id]) ? recorded[id] : null;
171
+ modules[id] = { ...(isPlainObject(source?.from) ? { from: JSON.parse(JSON.stringify(source.from)) } : {}), ...(typeof source?.commit === "string" ? { commit: source.commit } : {}) };
172
+ }
173
+ return { version: COMPOSITION_VERSION, store, modules, capabilityRuntime: storedRows(home, rows, store) };
174
+ }
175
+
176
+ const validPair = (c) => isPlainObject(c) && typeof c.store === "string" && STORE_RE.test(c.store) && isPlainObject(c.modules) && Array.isArray(c.capabilityRuntime)
177
+ && Object.values(c.modules).every((m) => isPlainObject(m))
178
+ && c.capabilityRuntime.every((row) => isPlainObject(row) && typeof row.id === "string");
179
+ function validComposition(c) {
180
+ return isPlainObject(c) && c.version === COMPOSITION_VERSION && validPair(c) && (c.previous === undefined || (validPair(c.previous) && c.previous.store !== c.store));
181
+ }
182
+
183
+ /** What a home's receipt says the kernel runs of it:
184
+ * - null: the receipt names no session provider (a tmux home), or there is none for this home:
185
+ * the home is read and run as it always was;
186
+ * - `{ composition }`: a provider home, with what its spawn recorded;
187
+ * - `{ problem }` (one sentence): a provider home whose receipt holds no composition this kernel
188
+ * reads. A kernel from before this rule spawned it; nothing of it is run.
189
+ * The receipt is read each time: it is the record, and an upgrade may have rewritten it. */
190
+ export function providerHomeTrust(home) {
191
+ const baseline = homeReceipt(home);
192
+ return baseline ? receiptTrust(baseline, home) : null;
193
+ }
194
+ /** providerHomeTrust, of a receipt its caller has read and found to be this home's. */
195
+ export function receiptTrust(baseline, home) {
196
+ if (!isPlainObject(baseline?.runtime) || typeof baseline.runtime.provider !== "string") return null;
197
+ if (validComposition(baseline.composition)) return { composition: baseline.composition };
198
+ return { problem: `${basename(home)} is on a session provider and its receipt records nothing of what it was spawned with (a kernel from before the receipt recorded it spawned the home, or the receipt was rewritten): none of its capabilities is run. Retire it with --force (oats retire ${basename(home)} --force: its retire hooks cannot be identified, so none is run, and what its capabilities left outside is cleaned up with their own tooling), then spawn it again` };
199
+ }
200
+
201
+ /** Why the kernel runs nothing of capability `id` in a provider home → one sentence that names
202
+ * the module, or null when it may: the receipt records the module and the kernel holds its copy
203
+ * of it. Null for a home that is no provider home (`trust` null: providerHomeTrust's answer,
204
+ * read here when it is not given). */
205
+ export function moduleCopyProblem(home, id, trust = providerHomeTrust(home)) {
206
+ if (!trust) return null;
207
+ if (trust.problem) return trust.problem;
208
+ if (!Object.hasOwn(trust.composition.modules, id)) return `capability ${id} is not one ${basename(home)} was spawned with (its receipt records no such module): nothing of it is run`;
209
+ const dir = kernelModuleDir(home, id, trust);
210
+ let kept = false;
211
+ try { kept = lstatSync(dir).isDirectory(); } catch { /* not there */ }
212
+ return kept ? null : `the kernel's copy of capability ${id} for ${basename(home)} is not at ${dir}: nothing of the capability is run. Retire the instance (oats retire ${basename(home)}; where the capability has a retire hook, which then cannot be run, the retire says so and only --force removes the home), then spawn it again`;
213
+ }
214
+ /** Why the kernel launches nothing in a provider home → the first module's problem
215
+ * (moduleCopyProblem), or null. */
216
+ export function homeModulesProblem(home, trust = providerHomeTrust(home)) {
217
+ if (!trust) return null;
218
+ if (trust.problem) return trust.problem;
219
+ for (const id of Object.keys(trust.composition.modules).sort(byCodeUnit)) {
220
+ const problem = moduleCopyProblem(home, id, trust);
221
+ if (problem) return problem;
222
+ }
223
+ return null;
224
+ }
225
+ /** The directory the kernel runs capability `id` of `home` from: its own copy for a provider
226
+ * home, the home's for any other. */
227
+ export function runDirOf(home, id, trust = providerHomeTrust(home)) {
228
+ return trust ? kernelModuleDir(home, id, trust) : homeModuleDir(home, id);
229
+ }
230
+ /** For a caller that holds a directory it is about to run a file of: why it may not → a
231
+ * sentence, when `dir` is a provider home's OWN copy (`<home>/.oats/modules/<id>`), which the
232
+ * kernel never runs; null for any other directory (the kernel's copy, a tmux home's copy, a
233
+ * deployment's module store). A guard: every caller is given the kernel's copy to begin with. */
234
+ export function moduleCopyProblemAt(dir) {
235
+ const at = homeOfModuleCopy(dir);
236
+ if (!at || !providerHomeTrust(at.home)) return null;
237
+ return `${dir} is ${basename(at.home)}'s own copy of capability ${at.id}, and ${basename(at.home)} is on a session provider: the kernel runs its own copy of it (${kernelModuleDir(at.home, at.id)}), never the home's`;
238
+ }
239
+ /** What a provider home's row says of its modules' copies → `{ runs: "kernel-copy", homeCopy:
240
+ * "same" | "differs", differs: [<module id>] }`, or undefined for a home that is no provider home
241
+ * or whose receipt holds no composition. `runs`: which copy the kernel runs. `homeCopy` compares
242
+ * RECORDS only, with nothing hashed and no file of a copy read: the home's own record of each
243
+ * module (instance.json `modules.<id>`: its `from` and `commit`) against the receipt's. They
244
+ * differ after an upgrade that was interrupted between moving the home's copies and writing the
245
+ * receipt, and whenever the home's record was rewritten; `differs` names the modules, those
246
+ * only one of the two names included (capability ids only, at most 200: a name the home's
247
+ * record gives that is none is counted in `homeCopy` and not named). Whether a home copy's FILES are the kernel's is
248
+ * `oats readiness --home`'s `kernelCopies`. */
249
+ export function moduleCopyReport(meta, trust) {
250
+ if (!trust?.composition) return undefined;
251
+ const recorded = trust.composition.modules, own = isPlainObject(meta?.modules) ? meta.modules : {};
252
+ const same = (id) => Object.hasOwn(recorded, id) && Object.hasOwn(own, id) && isPlainObject(own[id])
253
+ && JSON.stringify(sorted(own[id].from ?? null)) === JSON.stringify(sorted(recorded[id].from ?? null)) && (own[id].commit ?? null) === (recorded[id].commit ?? null);
254
+ const differing = [...new Set([...Object.keys(recorded), ...Object.keys(own)])].filter((id) => !same(id));
255
+ // The names are the home's own to choose (the keys of its record): only capability ids are
256
+ // named, and no more than a row may carry; `homeCopy` says "differs" whatever is named.
257
+ const differs = differing.filter((id) => MODULE_ID_RE.test(id) && id.length <= MODULE_COPY_ID_MAX).sort(byCodeUnit).slice(0, MODULE_COPY_IDS_MAX);
258
+ return { runs: "kernel-copy", homeCopy: differing.length ? "differs" : "same", differs };
259
+ }
260
+ /** A row's `moduleCopy` as another kernel reported it (a remote roster's row), read by this
261
+ * kernel's own rule → the value, or undefined when it is not one: exactly the three keys,
262
+ * `runs: "kernel-copy"`, `homeCopy` one of the two words, `differs` a list of at most 200
263
+ * capability ids, empty when `homeCopy` is `same`. */
264
+ export function readModuleCopy(value) {
265
+ if (!isPlainObject(value) || Object.keys(value).sort().join() !== "differs,homeCopy,runs" || value.runs !== "kernel-copy") return undefined;
266
+ if (!Array.isArray(value.differs) || value.differs.length > MODULE_COPY_IDS_MAX || !value.differs.every((id) => typeof id === "string" && id.length <= MODULE_COPY_ID_MAX && MODULE_ID_RE.test(id))) return undefined;
267
+ if (value.homeCopy !== "same" && value.homeCopy !== "differs") return undefined;
268
+ if (value.homeCopy === "same" && value.differs.length) return undefined;
269
+ return { runs: "kernel-copy", homeCopy: value.homeCopy, differs: [...value.differs] };
270
+ }
271
+ /** A JSON value with every object's keys in one order, for a comparison by text. */
272
+ function sorted(value) {
273
+ if (Array.isArray(value)) return value.map(sorted);
274
+ if (!isPlainObject(value)) return value;
275
+ return Object.fromEntries(Object.keys(value).sort(byCodeUnit).map((key) => [key, sorted(value[key])]));
276
+ }
277
+ /** Whether a provider home's receipt records a module `id`: true for a home that is no provider
278
+ * home (every module of its record counts, as before). */
279
+ export function recordsModule(trust, id) {
280
+ return !trust || (!!trust.composition && Object.hasOwn(trust.composition.modules, id));
281
+ }
282
+ /** The fields of a capability row that the receipt decides, for a hook or a command of a provider
283
+ * home: whatever a caller's row says of them is replaced (trustedCapability). */
284
+ const ROW_FIELDS = ["layer", "level", "settings", "settingsOrigins", "hooks", "requiredHooks", "environment", "environmentNamespaces", "missingRequires", "trust", "executable"];
285
+ /** A capability row as the kernel may use it in a provider home → `{ cap }`: the caller's row
286
+ * with every field the receipt decides replaced by the receipt's (an absent one made absent), or
287
+ * `{ cap, problem }` when the receipt records no such capability: nothing of it is run. For a
288
+ * home that is no provider home, `{ cap }` as given. */
289
+ export function trustedCapability(home, cap, trust) {
290
+ if (!trust) return { cap };
291
+ const row = trustedRow(trust, cap.id);
292
+ if (!row) return { cap, problem: trust.problem ?? `capability ${cap.id} is not one ${basename(home)} was spawned with (its receipt records no row for it): nothing of it is run` };
293
+ return { cap: { ...cap, ...Object.fromEntries(ROW_FIELDS.map((k) => [k, row[k]])) } };
294
+ }
295
+ /** A home's record as the kernel may use it: for a provider home its `capabilityRuntime` is the
296
+ * receipt's, and so is `providers` (each capability's settings, which is where an upgrade reads
297
+ * them), whatever instance.json says; both absent when the receipt holds no composition (the
298
+ * home then records no hooks this kernel can identify). Any other home's record as given. */
299
+ export function trustedRecord(meta, trust) {
300
+ if (!trust || !isPlainObject(meta)) return meta;
301
+ const { capabilityRuntime: _rows, providers: _settings, ...rest } = meta;
302
+ if (!trust.composition) return rest;
303
+ const rows = trust.composition.capabilityRuntime;
304
+ return { ...rest, capabilityRuntime: rows, providers: Object.fromEntries(rows.map((row) => [row.id, isPlainObject(row.settings) ? row.settings : {}])) };
305
+ }
306
+ /** A provider home's record with what an upgrade reads of each module: the module set is the
307
+ * receipt's (a module the record adds or leaves out is refused: `{ problem }`), and each
308
+ * module's `from` and `commit` are the receipt's where it records them. `{ meta }` otherwise;
309
+ * `{ meta }` as given for a home that is no provider home. */
310
+ export function trustedModuleRecords(home, meta, trust) {
311
+ if (!trust?.composition || !isPlainObject(meta?.modules)) return { meta };
312
+ const recorded = trust.composition.modules;
313
+ const added = Object.keys(meta.modules).filter((id) => !Object.hasOwn(recorded, id)).sort(byCodeUnit);
314
+ const dropped = Object.keys(recorded).filter((id) => !Object.hasOwn(meta.modules, id)).sort(byCodeUnit);
315
+ if (added.length || dropped.length) return { problem: `the modules ${basename(home)}'s own record names are not the ones its receipt records (${[added.length ? `the record adds ${added.join(", ")}` : "", dropped.length ? `the record leaves out ${dropped.join(", ")}` : ""].filter(Boolean).join("; ")}). Retire the instance and spawn it again` };
316
+ const modules = Object.fromEntries(Object.entries(meta.modules).map(([id, row]) => [id, { ...row, ...(recorded[id].from ? { from: recorded[id].from } : {}), ...(recorded[id].commit ? { commit: recorded[id].commit } : {}) }]));
317
+ return { meta: { ...meta, modules } };
318
+ }
319
+ /** The capability row the kernel uses for `id` in a provider home: the receipt's, or undefined
320
+ * when it records none. */
321
+ export function trustedRow(trust, id) {
322
+ return trust?.composition?.capabilityRuntime.find((row) => row.id === id);
323
+ }
324
+ /** A home's capability rows as the kernel may use them: the receipt's for a provider home (none
325
+ * when its receipt holds no composition), else the rows of the home's own record. */
326
+ export function capabilityRuntimeOf(home, meta, trust = providerHomeTrust(home)) {
327
+ if (!trust) return Array.isArray(meta?.capabilityRuntime) ? meta.capabilityRuntime : [];
328
+ return trust.composition ? trust.composition.capabilityRuntime : [];
329
+ }
package/lib/hook-env.mjs CHANGED
@@ -64,7 +64,8 @@ export function teamEnv(resolved) {
64
64
  };
65
65
  }
66
66
  export function withoutAmbientHookFacts(env) {
67
- const { OATS_LAUNCH_PREVIEW: _ambient, OATS_HARNESS_EXECUTABLE: _inherited, OATS_SPAWNER_HOME: _spawner, ...rest } = env;
67
+ // (OATS_PREVIOUS_BACKEND: a launch hook's, from the home's receipt; absent means a first launch.)
68
+ const { OATS_LAUNCH_PREVIEW: _ambient, OATS_HARNESS_EXECUTABLE: _inherited, OATS_SPAWNER_HOME: _spawner, OATS_PREVIOUS_BACKEND: _previous, ...rest } = env;
68
69
  return rest;
69
70
  }
70
71
  /** The environment one capability's lifecycle hook runs with: the invoker's own
@@ -42,7 +42,7 @@
42
42
  * home the way the caller did: `admit` has proved every returned row is this
43
43
  * one home's, so its `home` is the address that was asked about, and a consumer
44
44
  * that checks "the rows' home is the home I asked for" keeps holding. */
45
- import { appendFileSync, closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync } from "node:fs";
45
+ import { closeSync, constants as fsConstants, existsSync, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, writeSync } from "node:fs";
46
46
  import { createHash } from "node:crypto";
47
47
  import { basename, dirname, isAbsolute, join, resolve } from "node:path";
48
48
  import { REFUSED_TEXT, safeText } from "./refused-text.mjs";
@@ -184,6 +184,35 @@ function workspaceLogPath(given, home, meta) {
184
184
  return join(realOrNearest(deployment), ".agents", "events", `${agent}--${instance}.jsonl`);
185
185
  }
186
186
 
187
+ /** THE ONE WRITE OF AN EVENT ROW: `eventLog.appendRow(path, line)` appends one line to the log
188
+ * at `path`, to that file and to no other. Every event-log write of the kernel goes through it,
189
+ * and it is a seam: a test replaces `eventLog.appendRow` to hold, fail or follow one row's write,
190
+ * with the log's path and the row's text together (test/helpers/fs-gate-preload.mjs `appendEventRow`).
191
+ *
192
+ * The open never follows a symbolic link at the log's own name (O_NOFOLLOW, so a dangling one
193
+ * creates nothing either) and never waits on a FIFO, and what it opened must be a regular file
194
+ * with one name, checked on the descriptor the line is then written to: there is no instant
195
+ * between the check and the write in which the file can be exchanged. Both logs are in places an
196
+ * agent can write (its home; the deployment's events directory, which a session provider's
197
+ * sandbox is allowed to write, lib/sandbox-allowances.mjs), and the kernel that appends runs
198
+ * outside any sandbox: a link planted there, symbolic or hard, would otherwise carry its line
199
+ * into any file of the operator's, and a row holds text its agent chose. The reader refuses the
200
+ * same files (readLog). Throws with why; the directory is made when it is missing. */
201
+ export const eventLog = {
202
+ appendRow(path, line) {
203
+ mkdirSync(dirname(path), { recursive: true });
204
+ let fd;
205
+ try { fd = openSync(path, fsConstants.O_WRONLY | fsConstants.O_APPEND | fsConstants.O_CREAT | (fsConstants.O_NOFOLLOW ?? 0) | (fsConstants.O_NONBLOCK ?? 0), 0o666); }
206
+ catch (e) { throw e?.code === "ELOOP" ? new Error("the log is a symbolic link, which is never written through") : e; }
207
+ try {
208
+ const stat = fstatSync(fd);
209
+ if (!stat.isFile()) throw new Error("the log is not a regular file");
210
+ if (stat.nlink > 1) throw new Error("the log has a second name (a hard link), so a line would be written into another file too");
211
+ writeSync(fd, line);
212
+ } finally { closeSync(fd); }
213
+ },
214
+ };
215
+
187
216
  /** The one address of the home a caller named, in any spelling: the real home, its
188
217
  * instance name and incarnation, its two logs, and `asked`, the caller's spelling. `known`: the
189
218
  * home's record as the caller already read it (a JSON object), else it is read here. */
@@ -233,8 +262,7 @@ function append(a, event, { workspaceOnly = false, incarnation, at } = {}) {
233
262
  for (const path of [...(workspaceOnly ? [] : [a.homeLog]), a.workspaceLog]) {
234
263
  try {
235
264
  if (path === a.homeLog && !existsSync(a.home)) { results.push({ path, ok: false, reason: "home absent" }); continue; }
236
- mkdirSync(dirname(path), { recursive: true });
237
- appendFileSync(path, line);
265
+ eventLog.appendRow(path, line);
238
266
  results.push({ path, ok: true });
239
267
  } catch (e) { results.push({ path, ok: false, reason: e.message }); }
240
268
  }
@@ -509,8 +537,7 @@ export function recordStartBoundary(given, { startId, startedAt, ...data }) {
509
537
  const results = paths.filter((_, i) => !found[i]).map((path) => {
510
538
  try {
511
539
  if (path === a.homeLog && !existsSync(home)) return { path, ok: false, reason: "home absent" };
512
- mkdirSync(dirname(path), { recursive: true });
513
- appendFileSync(path, line);
540
+ eventLog.appendRow(path, line);
514
541
  return { path, ok: true };
515
542
  } catch (e) { return { path, ok: false, reason: e.message }; }
516
543
  });
@@ -59,6 +59,15 @@ export const INSTANCE_GIT_API = 1;
59
59
  /** The setting that keeps Git from running the `core.fsmonitor` command a repository's
60
60
  * configuration names, which it asks whenever it reads the index of a work tree. */
61
61
  export const NO_FILE_MONITOR = ["-c", "core.fsmonitor=false"];
62
+ /** For every Git the kernel runs over the trees of a home on a session provider, or over their
63
+ * repository: neither the `core.fsmonitor` command nor any hook the repository's configuration
64
+ * or its `hooks` directory names is run. Such a home's agent may be able to write a tree's `.git`
65
+ * pointer, and its repository's configuration and hooks; Git would run what they name outside
66
+ * any sandbox, as the operator (the contract's D16 rule 6). A read by this module, and a retire's
67
+ * Git, already run so for every home (READ_ONLY_GIT, lib/core.mjs RETIRE_GIT_FLAGS); these are
68
+ * for the writes: a spawn's `git worktree add` and its rollback, and `oats worktree add|remove`.
69
+ * A tmux home's are unchanged: its hooks (a `post-checkout`) run as before. */
70
+ export const PROVIDER_TREE_GIT = [...NO_FILE_MONITOR, "-c", "core.hooksPath=/dev/null"];
62
71
  const READ_ONLY_GIT = ["--no-optional-locks",
63
72
  ...NO_FILE_MONITOR, "-c", "core.hooksPath=/dev/null", "-c", "diff.external=", "-c", "core.pager=cat",
64
73
  "-c", "core.untrackedCache=false", "-c", "index.threads=1", "-c", "safe.bareRepository=explicit"];
@@ -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,7 +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, sessionProvidersOf } from "./session-providers.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";
38
41
  import { sameRepo } from "./repo-moves.mjs";
39
42
  import { kernelNode } from "./stable-node.mjs";
40
43
 
@@ -93,11 +96,17 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
93
96
  meta = upgradeHomeMeta(meta, realHome);
94
97
  // Only the home's own module copies: without <home>/.oats/modules the kernel's
95
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) : [];
96
103
  let manifests = {}; const loadProblems = [];
97
- 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"))) {
98
107
  try { manifests = capabilityManifests(realHome); } catch (e) { loadProblems.push({ code: "module-manifest-invalid", message: e.message }); }
99
108
  }
100
- 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 : {};
101
110
  const agentsRoot = dirname(dirname(dirname(realHome)));
102
111
  const deployment = dirname(agentsRoot);
103
112
  // The deployment's removed team keys (team model 3) refuse every reader of its oats-local.yaml, before
@@ -149,9 +158,11 @@ export async function homeTarget(home, meta, { remoteOptions, discover = true, l
149
158
  soul: { name: meta.agent, repoKey: ws.soul?.repoKey ?? null, commit: ws.soul?.commit ?? null, external, path: null, soulDir, definition, problems: [...problems, ...loadProblems],
150
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 } } : {}) },
151
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 },
152
- modules: Object.keys(modules).sort().map((name) => ({ name, from: modules[name]?.from ?? null, manifest: manifests[name] ?? null, dir: join(realHome, ".oats", "modules", name) })),
153
- payloads: obj(meta.providers) ? meta.providers : {},
154
- 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 : {}])),
155
166
  slots, slotsFrom: Object.fromEntries(LAYERS.map((l) => [l, obj(ws.layers?.[l]) ? ws.layers[l].from ?? null : null])), discovery, discoveryError, resolutionError: null,
156
167
  lock: null, prepared: null,
157
168
  };
@@ -709,12 +720,16 @@ function moduleExecutable(dir, script) {
709
720
  * directory, the script contained in it (moduleExecutable), one JSON `request` on stdin, the
710
721
  * environment providerEnv's for the request's `settings`, SIGKILL at `timeoutMs`, at most
711
722
  * BINDING_LIMITS of stdout, decoded as exactly one strict JSON document (whitespace around it
712
- * 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"
713
726
  * (timedOut, signal, overflow) | "exit" (status) | "invalid" }. The caller judges the document. */
714
727
  export function runModuleCommand(t, mod, dir, command, request, { timeoutMs = 30000 } = {}) {
715
728
  const spec = command ? mod.manifest?.commands?.[command] : null;
716
729
  if (typeof spec !== "string" || !spec.trim()) return { failure: "no-command" };
717
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 };
718
733
  const file = dir ? moduleExecutable(dir, script) : null;
719
734
  if (!file) return { failure: "no-executable", script };
720
735
  // The environment is providerEnv's: ambient OATS_/OAS_/PI_ identity removed, the rest
@@ -748,7 +763,7 @@ export function runProviderCheck(t, mod, dir, { timeoutMs = 30000 } = {}) {
748
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" } } };
749
764
  const run = runModuleCommand(t, mod, dir, check, request, { timeoutMs });
750
765
  if (run.failure === "no-command") return unavailable("provider-not-qualified", `${mod.name} declares binding.check but no command ${JSON.stringify(check)}`);
751
- 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`);
752
767
  if (run.failure === "incomplete") return unavailable("provider-unavailable", `${mod.name} check did not complete${run.timedOut || run.signal ? " in time" : ""}`);
753
768
  if (run.failure === "exit") return unavailable("provider-unavailable", `${mod.name} check exited ${run.status}`);
754
769
  const invalid = () => unavailable("provider-unavailable", `${mod.name} check answered invalid binding data`);
@@ -830,6 +845,10 @@ export const PROVIDER_CHECK_BUDGET_MS = 60_000;
830
845
  /** `oats readiness --json` on the workspace model. */
831
846
  export async function readinessDocument(t, { selector = null, remoteOptions, catalog = null, budgetMs = PROVIDER_CHECK_BUDGET_MS } = {}) {
832
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)` }));
833
852
  const cap = (id) => ({ capability: { id } });
834
853
  if (t.resolutionError && !isTeamRefusal(t.resolutionError)) {
835
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)" }));
@@ -922,9 +941,44 @@ export async function readinessDocument(t, { selector = null, remoteOptions, cat
922
941
  return { capability: { id }, checks: Object.fromEntries(Object.keys(checks).map((name) => [name, of(name).length ? roll(of(name)) : "not-applicable"])),
923
942
  ownReady: statuses.length > 0 && statuses.every((s) => s === "pass" || s === "not-applicable") };
924
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
+ }
925
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 })));
926
980
  for (const g of byCapability) g.ready = g.ownReady && subjectBlockers.length === 0;
927
- 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 } : {}),
928
982
  summary: { ready: requiredStatuses.length > 0 && requiredStatuses.every((s) => s === "pass" || s === "not-applicable"), required: requiredStatuses.length,
929
983
  pass: requiredStatuses.filter((s) => s === "pass").length, fail: requiredStatuses.filter((s) => s === "fail").length, unknown: requiredStatuses.filter((s) => s === "unknown").length, byCapability, subjectBlockers },
930
984
  notes: ["ready means every REQUIRED check passes; it is never inferred from an empty set",
@@ -24,6 +24,7 @@ import { identityHolderState, recordSeen } from "./session-seen.mjs";
24
24
  import { listAgents, capabilityAgentDirs } from "./soul-listing.mjs";
25
25
  import { recordsHerdr, readJsonOrUndefined, findRetirementBaseline, instanceSessionTarget, harnessRunning, isPlainObject, instancesRetirementRoot, providerMayWait } from "./session-inspect.mjs";
26
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";
27
28
  import { SESSION_END } from "./session-resume-contract.mjs";
28
29
 
29
30
  /** OATS 0.25 and earlier homed local souls and capability-defined agents at
@@ -298,7 +299,10 @@ function providerRow(home, meta) {
298
299
  const recorded = s.session ?? s.planned;
299
300
  // A record that names a session provider beside a receipt that authorises a tmux session, or none.
300
301
  if (!recorded) return unreachable("E_RUNTIME_AUTHORITY_MISMATCH: instance metadata records a session provider and its independent session receipt does not");
301
- const fields = { backend: recorded.backend, session: rowSession(recorded.provider, recorded.endpoint ?? null), tmux: null, open: null };
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 } : {}) };
302
306
  // A launch that was sent and never recorded: unknown, never stopped (lib/session-providers.mjs launchSentOf).
303
307
  if (s.unsettled) return unreachable(unsettledLaunchSaid(basename(home), s.unsettled.backend, s.unsettled.launchSent), fields.session);
304
308
  if (!s.session) return { fields: { ...fields, running: false, runtimeState: "stopped" } };