@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.
@@ -17,14 +17,14 @@
17
17
  * Nothing here reads `oats-config.yaml`, an installed-capability directory or a
18
18
  * per-soul `source:` — those do not exist in this model. */
19
19
  import { existsSync, readFileSync, readdirSync, lstatSync, readlinkSync, realpathSync } from "node:fs";
20
- import { join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
20
+ import { basename, join, resolve as resolvePath, dirname, relative, isAbsolute, sep } from "node:path";
21
21
  import { loadLocal, observeWorkspace } from "./workspace.mjs";
22
22
  import { resolveSoul, kernelCompatibility, packageRef } from "./resolve.mjs";
23
23
  import { BY_TEAM_REMOVED, isRemovedTeamKeys, isTeamRefusal, memberNameOf, recordedTeams, reportRows, soulKeyOf, soulTeams, teamKeyOf, teamModel } from "./teams.mjs";
24
24
  import { LOCAL_FILE, launchLayers, nearestSoulKeys } from "./launch-preference.mjs";
25
25
  import { APPROVED_HOOKS, declaredSettings, locatedContractWarnings } from "./capability-contract.mjs";
26
26
  import { materialize, moduleSkills, MODULES_DIR, plannedModuleSkills, SKILLS_DIR } from "./materialize.mjs";
27
- import { contentDigest, fetchRemoteTree } from "./remote.mjs";
27
+ import { contentDigest, createReadSession, fetchRemoteTree } from "./remote.mjs";
28
28
  import { mkdirSync, mkdtempSync, renameSync, rmSync, writeFileSync, symlinkSync } from "node:fs";
29
29
  import { tmpdir } from "node:os";
30
30
  import { randomBytes } from "node:crypto";
@@ -77,6 +77,27 @@ export function parseProviderFlags(pairs) {
77
77
  return JSON.parse(JSON.stringify(out));
78
78
  }
79
79
 
80
+ /** Why a discovery made without reaching any remote cannot say which soul a home is of: a member
81
+ * of the workspace that this host could not read (its cache does not hold it) → the cause, naming
82
+ * each such repository and the way out, or null when every member was read. A member that was
83
+ * read and is no member (no backlink, not listed) is not one of these. */
84
+ export function unreadMembersCause(discovery) {
85
+ if (discovery?.standalone === true) return null;
86
+ const unread = (discovery?.members || []).filter((m) => m.confirmed === false && m.reason === "cannot-read");
87
+ if (!unread.length) return null;
88
+ return `E_REMOTE_UNREADABLE: ${unread.map((m) => m.detail).join("; ")}. A member that was not read can hold this home's soul, or another of its name, so the deployment's configuration for the home cannot be told. Any oats command that reads the workspace (oats status) brings it to this host's cache; if this host cannot read that repository at all, name the member the home's soul is in as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host`;
89
+ }
90
+ /** The soul a home under the agent directory `agentDir` is of, among the workspace's souls
91
+ * (`entries`) → `{ entry }`, or `{ unavailable: "<why>" }`. Nothing outside the home says which
92
+ * soul a home is but the directory it is in, so two souls that share that directory (the same
93
+ * bare name, in two members, or a member's and an external one) leave it untold: the cause names
94
+ * them and what the operator can do. */
95
+ export function homeSoulEntry(entries, agentDir) {
96
+ const here = entries.filter((entry) => agentDirOf(entry) === agentDir);
97
+ if (here.length === 1) return { entry: here[0] };
98
+ if (!here.length) return { unavailable: `E_SOUL_UNKNOWN: the workspace offers no soul whose agent directory is ${agentDir}` };
99
+ return { unavailable: `${here.length} souls of this workspace share the agent directory ${agentDir} (${here.map(qualifiedSoulName).join(", ")}), so which one this home is of cannot be told: rename one of them, or take one out of the workspace` };
100
+ }
80
101
  /** The qualified name of a discovered soul: `<package>/<soul>` for a package soul,
81
102
  * `<member name>/<soul>` for a member's, `<source repo name>/<soul>` for an external one. */
82
103
  export function qualifiedSoulName(entry) {
@@ -286,6 +307,68 @@ export async function liveTeams(home, meta, { remoteOptions, remote } = {}) {
286
307
  }
287
308
  }
288
309
 
310
+ /**
311
+ * What a start or a restart of a session-provider home computes its sandbox allowances from
312
+ * (lib/sandbox-allowances.mjs): the DEPLOYMENT'S configuration, resolved for the home's soul as a
313
+ * spawn preview resolves it (workspace, lock, soul payload), WITHOUT REACHING ANY REMOTE: every
314
+ * repository is read as this host last read it (lib/remote.mjs, an offline read session: the head
315
+ * last observed here, from the cache), and the deployment's own oats-local.yaml and lock as they
316
+ * are now. So a launch never waits on the network or fails with it, and what `oats aweb setup`
317
+ * writes to oats-local.yaml reaches an existing home at its next launch. A repository this host's
318
+ * cache does not hold is a cause of `unavailable`, by name.
319
+ *
320
+ * NOTHING INSIDE THE HOME decides which deployment or which soul that is: a sandboxed agent can
321
+ * write its home, instance.json included. Both come from where the home IS: the deployment is the
322
+ * fourth ancestor of the home's real path (`<deployment>/agents/<agent>/instances/<instance>`),
323
+ * and it must hold its own oats-local.yaml; the soul is the one soul the workspace offers whose
324
+ * agent directory is `<agent>`. A home whose real path is elsewhere (an agents root reached
325
+ * through a link) has no deployment to read by this rule, and none is guessed.
326
+ *
327
+ * → `{ deployment, modules: [{ name, manifest }], slots, payloads, teams: [team id], defaultTeam }`, or
328
+ * `{ unavailable: "<why>" }` when that cannot be established or resolved (no deployment there, no
329
+ * such soul any more or several, a member remote that cannot be read, an invalid workspace): the
330
+ * cause, in one line. It never throws for those: what a launch does without allowances is the
331
+ * caller's rule.
332
+ */
333
+ export async function homeSandboxSource(home, { remoteOptions, remote } = {}) {
334
+ let real;
335
+ try { real = realpathSync(home); } catch (e) { return { unavailable: `the home cannot be resolved (${e.code ?? e.message})` }; }
336
+ const deployment = dirname(dirname(dirname(dirname(real)))), agentDir = basename(dirname(dirname(real)));
337
+ if (basename(dirname(real)) !== "instances") return { unavailable: `${real} is not an instance home of a deployment (<deployment>/agents/<agent>/instances/<instance>)` };
338
+ // Never the caller's session: this read reaches no remote, whatever the command around it does.
339
+ const offline = createReadSession({ offline: true });
340
+ try {
341
+ const found = loadLocal(deployment);
342
+ if (!found.path || resolvePath(dirname(found.path)) !== deployment) return { unavailable: `${deployment}, where this home is, holds no deployment configuration (oats-local.yaml): the home's agents directory is reached through a symbolic link, or the home is not a deployment's` };
343
+ remoteOptions = { ...remoteOptions, session: offline };
344
+ const lock = readLockIfPresent(deployment);
345
+ const discovery = await discoverOrStandalone(found.local, { lock, deployment, remoteOptions, remote });
346
+ // A member this host did not read can hold the home's soul, or another of its name: with one
347
+ // unread, which soul the home is of is not told, whatever the members that were read offer.
348
+ const unread = unreadMembersCause(discovery);
349
+ if (unread) return { unavailable: unread };
350
+ const soul = homeSoulEntry(soulCandidates(discovery).map((c) => c.entry), agentDir);
351
+ if (soul.unavailable) return { unavailable: soul.unavailable };
352
+
353
+ // resolveSoul, not prepareInstance: a soul disabled for SPAWNING on this machine (souls.disabled)
354
+ // still has the homes it spawned, which start as any home does, with their allowances.
355
+ const resolution = await resolveSoul(discovery, soul.entry, { local: found.local, lock, spawn: {}, remoteOptions, remote });
356
+ return {
357
+ deployment,
358
+ modules: resolution.modules.map((m) => ({ name: m.name, manifest: m.manifest })), slots: resolution.slots ?? {}, payloads: resolution.payloads ?? {},
359
+ teams: (resolution.teams ?? []).map((row) => row.team).filter((team) => typeof team === "string"),
360
+ defaultTeam: typeof resolution.defaultTeam?.team === "string" ? resolution.defaultTeam.team : null,
361
+ };
362
+ } catch (e) {
363
+ if (typeof e?.code !== "string" || !e.code.startsWith("E_")) throw e;
364
+ // A repository this host can NEVER read (a member whose workspace host it has no access to: a
365
+ // spawn then works from the member alone) is never brought to the cache by any command: the
366
+ // way out is to say so in the deployment, which needs no read of that host.
367
+ const never = e.details?.reason === "not-cached" ? " If this host cannot read that repository at all, name the member as the deployment's own source (standalone: <member repository> in oats-local.yaml), which reads no workspace host" : "";
368
+ return { unavailable: `${e.code}: ${e.message}${never}` };
369
+ } finally { offline.close(); }
370
+ }
371
+
289
372
  /**
290
373
  * For `session start|restart --reselect-launch`: what the home's launch layers need of the workspace
291
374
  * (lib/core.mjs homeLaunchLayers `offered`) to say which keys of souls.launch name no soul. The workspace
@@ -42,6 +42,9 @@ import {
42
42
  findRetirementBaseline,
43
43
  officialPackageCatalog,
44
44
  } from "./core.mjs";
45
+ import { homeModulesProblem, kernelModuleDir, kernelModuleDirIn, previousComposition, providerHomeTrust, pruneModulesStores, removeUnnamedStore, trustedModuleRecords, trustedRecord, trustedRow, upgradedComposition } from "./home-integrity.mjs";
46
+ import { dieAt } from "./provider-test-seams.mjs";
47
+ import { homeReceipt } from "./session-receipt.mjs";
45
48
  import {
46
49
  stageMaterialize,
47
50
  driftOf,
@@ -115,16 +118,42 @@ function safeHomePaths(home) {
115
118
  const previous = join(home, ".oats/previous");
116
119
  if (existsSync(previous)) realDir(previous);
117
120
  }
121
+ /** A home on a session provider (lib/home-integrity.mjs) is upgraded from its receipt's record of
122
+ * it, and the kernel's own copies of its modules move with the receipt:
123
+ * - its capability rows, its module set and each module's source are the receipt's, never its
124
+ * own record's (trustedRecord, trustedModuleRecords);
125
+ * - the kernel's copies for the upgraded home are made in a new store before any hook runs
126
+ * (kernelMove), every upgrade hook runs from the kernel's copy, and the receipt's ONE write
127
+ * names the new store and the new rows together, keeping the pair it replaced as `previous`;
128
+ * - an undo names that previous pair again, in one write, and its hook runs from the kernel's
129
+ * previous copy: nothing the kernel runs comes from the copies kept in the home;
130
+ * - an upgrade that was interrupted is not resumed from the journal in the home, which the
131
+ * home's agent can write: the kernel's side is whole either way (the old pair before the
132
+ * write, the new one after).
133
+ * → providerHomeTrust's answer; refused when the receipt holds no composition. */
134
+ function providerUpgradeTrust(home, name) {
135
+ const trust = providerHomeTrust(home);
136
+ if (trust?.problem) throw fail("E_UPGRADE_INTEGRITY", `${trust.problem}; no modules were upgraded`);
137
+ return trust;
138
+ }
118
139
  function target(ctx, root, name, opts) {
119
140
  const found = resolveInstance(ctx, root, name, opts);
120
- const meta = identifiedHomeRecord(found.home).meta;
141
+ const trust = providerUpgradeTrust(found.home, name);
142
+ if (trust && opts.undo && !previousComposition(trust)) throw fail("E_UPGRADE_UNDO", `${name} has no previous move to undo: the kernel keeps no earlier copy of its modules; respawn the instance`);
143
+ const untrusted = homeModulesProblem(found.home, trust);
144
+ if (untrusted) throw fail("E_UPGRADE_INTEGRITY", `${untrusted}; no modules were upgraded`);
145
+ // Its module set, and where each module came from, are the receipt's too: a module only the
146
+ // home's own record names is no module of the home, and is never carried into the receipt.
147
+ const records = trustedModuleRecords(found.home, trustedRecord(identifiedHomeRecord(found.home).meta, trust), trust);
148
+ if (records.problem) throw fail("E_UPGRADE_INTEGRITY", `${records.problem}; no modules were upgraded`);
149
+ const meta = records.meta;
121
150
  if (!object(meta?.modules) || !meta.workspace?.soul?.commit)
122
151
  throw fail(
123
152
  "E_UNSUPPORTED_MODE",
124
153
  `${name} has no recorded workspace modules and soul commit; respawn the instance`,
125
154
  );
126
155
  safeHomePaths(found.home);
127
- return { ...found, meta };
156
+ return { ...found, meta, trust };
128
157
  }
129
158
  function stopped(home, name, opts, absentMeta) {
130
159
  let session;
@@ -158,7 +187,16 @@ function hookCommand(manifest) {
158
187
  const h = manifest.hooks?.upgrade;
159
188
  return typeof h === "string" ? h : h?.command;
160
189
  }
161
- function runHook(phase, { home, meta, module, dir, to, root }) {
190
+ /** A provider home's composition after a move (lib/home-integrity.mjs), written into its receipt:
191
+ * the one writer of it after the spawn. Only `composition` changes. Refused when the receipt
192
+ * is not this home's, or names no session provider. */
193
+ function writeUpgradedComposition(home, composition) {
194
+ const baseline = homeReceipt(home);
195
+ if (!object(baseline?.runtime) || typeof baseline.runtime.provider !== "string")
196
+ throw fail("E_UPGRADE_INTEGRITY", `the receipt of ${home} is missing, or names no session provider; nothing of it was rewritten. Retire the instance and spawn it again`);
197
+ writeFileAtomic(findRetirementBaseline(home), JSON.stringify({ ...baseline, composition }, null, 2) + "\n", { mode: 0o600 });
198
+ }
199
+ function runHook(phase, { home, meta, module, dir, to, root, moduleDir = join(home, ".oats/modules", module.name) }) {
162
200
  const cap = toCapabilityRows(
163
201
  {
164
202
  modules: [module],
@@ -189,11 +227,14 @@ function runHook(phase, { home, meta, module, dir, to, root }) {
189
227
  priorMeta: meta.capabilityMeta || {},
190
228
  extraEnv: {
191
229
  OATS_UPGRADE_PHASE: phase,
192
- OATS_UPGRADE_MODULE_DIR: join(home, ".oats/modules", module.name),
230
+ // (A provider home's apply: the kernel's copy of the module, where its code runs from then on.)
231
+ OATS_UPGRADE_MODULE_DIR: moduleDir,
232
+ // (A provider home: `from` and `commit` are the receipt's; the home's own record of the
233
+ // copy's digest is not handed on.)
193
234
  OATS_UPGRADE_FROM: JSON.stringify({
194
235
  from: meta.modules[module.name].from,
195
236
  commit: meta.modules[module.name].commit,
196
- digest: meta.modules[module.name].digest,
237
+ ...(providerHomeTrust(home) ? {} : { digest: meta.modules[module.name].digest }),
197
238
  }),
198
239
  OATS_UPGRADE_TO: JSON.stringify(to),
199
240
  },
@@ -421,7 +462,7 @@ function finishCleanup(home, path, receipt) {
421
462
  }
422
463
  /** Build the exact frozen composition, leaving unchanged modules at their recorded bytes. */
423
464
  async function prepare(ctx, root, name, opts, { own = false } = {}) {
424
- const { home, meta } = target(ctx, root, name, opts);
465
+ const { home, meta, trust } = target(ctx, root, name, opts);
425
466
  unclaimed(home, name, own);
426
467
  assertNoPartialUpgrade(home);
427
468
  cleanupPending(home);
@@ -441,7 +482,9 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
441
482
  moving = [],
442
483
  kept = [],
443
484
  packages = new Map(),
444
- restored = {};
485
+ restored = {},
486
+ hookDirs = {},
487
+ undoTargets = {};
445
488
  const previousReceipts = [
446
489
  ...new Set(
447
490
  Object.values(meta.modules)
@@ -475,7 +518,9 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
475
518
  const recorded = meta.modules[id],
476
519
  oldDir = join(home, ".oats/modules", id);
477
520
  realDir(oldDir);
478
- const oldManifest = readJson(join(oldDir, "oats.json"));
521
+ // (A provider home: the manifest the upgrade reads of a module it holds is the kernel's
522
+ // copy's, never the home's own, which its agent can write.)
523
+ const oldManifest = readJson(join(trust ? kernelModuleDir(home, id, trust) : oldDir, "oats.json"));
479
524
  const base = {
480
525
  name: id,
481
526
  from: recorded.from,
@@ -500,13 +545,23 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
500
545
  ),
501
546
  env: prev.meta.launch?.hooks?.env || {},
502
547
  };
548
+ // A provider home: the module an undo goes back to is the kernel's previous copy of it,
549
+ // whose manifest is read and whose upgrade hook is run, and what that hook is told it goes
550
+ // back to is the receipt's record of that copy; the copy kept in the home only restores
551
+ // the home's own.
552
+ if (trust) {
553
+ const earlier = previousComposition(trust);
554
+ if (!Object.hasOwn(earlier.modules, id)) throw fail("E_UPGRADE_UNDO", `${id}: the kernel keeps no earlier copy of it for ${name}; respawn the instance`);
555
+ hookDirs[id] = kernelModuleDirIn(home, earlier.store, id);
556
+ undoTargets[id] = { ...(earlier.modules[id].from ?? {}), ...(earlier.modules[id].commit ? { commit: earlier.modules[id].commit } : {}) };
557
+ }
503
558
  next = {
504
559
  name: id,
505
560
  from: prev.record.from,
506
561
  digest: prev.record.digest,
507
- manifest: readJson(join(dir, "oats.json")),
562
+ manifest: readJson(join(hookDirs[id] ?? dir, "oats.json")),
508
563
  };
509
- to = {
564
+ to = undoTargets[id] ?? {
510
565
  ...prev.record.from,
511
566
  commit: prev.record.commit,
512
567
  digest: prev.record.digest,
@@ -581,7 +636,7 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
581
636
  });
582
637
  modules.push(next);
583
638
  existingModules[id] = dir;
584
- const provider = adoption(home, meta, next, dir, to, root, !!opts.undo, oldManifest);
639
+ const provider = adoption(home, meta, next, hookDirs[id] ?? dir, to, root, !!opts.undo, oldManifest);
585
640
  hookTargets[id] = to;
586
641
  moving.push({
587
642
  capability: id,
@@ -610,6 +665,17 @@ async function prepare(ctx, root, name, opts, { own = false } = {}) {
610
665
  "E_UPGRADE_UNDO",
611
666
  `${name} has no previous move to undo; respawn the instance`,
612
667
  );
668
+ // A provider home's undo goes back to the receipt's previous pair, whole: the modules it
669
+ // moves are the ones whose source differs between the two, by the receipt. The home's own
670
+ // record of what its last move was must name the same ones, or nothing is undone.
671
+ if (opts.undo && trust) {
672
+ const now = trust.composition.modules, earlier = previousComposition(trust).modules;
673
+ const differs = (id) => JSON.stringify([earlier[id]?.from ?? null, earlier[id]?.commit ?? null]) !== JSON.stringify([now[id]?.from ?? null, now[id]?.commit ?? null]);
674
+ const byReceipt = [...new Set([...Object.keys(now), ...Object.keys(earlier)])].filter(differs).sort();
675
+ const byRecord = moving.map((m) => m.capability).sort();
676
+ if (JSON.stringify(byReceipt) !== JSON.stringify(byRecord))
677
+ throw fail("E_UPGRADE_UNDO", `${name}'s own record of its last move (${byRecord.join(", ") || "none"}) is not the kernel's (${byReceipt.join(", ") || "none"}): nothing was undone; retire the instance and spawn it again`);
678
+ }
613
679
  const soul = meta.workspace.soul,
614
680
  path = soul.package?.path || memberSoulPath(meta.agent);
615
681
  let body;
@@ -942,6 +1008,56 @@ function derivedMetadata(p, tx, receipt) {
942
1008
  /** The home's capability-block order, from the `instructions` it recorded (its AGENTS.md as
943
1009
  * spawned or last upgraded); a module with no recorded block follows, by name. An upgrade
944
1010
  * keeps that order, and the kernel's blocks close the recomposed AGENTS.md. */
1011
+ /** What a move does to the kernel's own copies of a provider home's modules → `{ before, next }`,
1012
+ * or null for a home on no session provider. `before` is the composition the receipt names now;
1013
+ * `next` the one its ONE write will name:
1014
+ * - an upgrade: a new store, made here, with each moved module copied from the upgrade's staged
1015
+ * copy once that is found to be the one it verified against the lock (`nextMeta`, made in
1016
+ * this process), every other module copied from the kernel's current copy, the rows the
1017
+ * upgrade derived, and `previous` = the pair it replaces;
1018
+ * - an undo: the receipt's `previous` pair, as it is, with nothing copied.
1019
+ * Nothing the receipt names is touched here. */
1020
+ function kernelMove(home, receipt, tx) {
1021
+ const trust = providerHomeTrust(home);
1022
+ if (!trust) return null;
1023
+ const before = trust.composition;
1024
+ // (An undo: target() refused it already when the receipt keeps no previous pair.)
1025
+ if (receipt.undo) return { before, next: previousComposition(trust) };
1026
+ const meta = receipt.nextMeta, moved = new Set(receipt.modules.map((m) => m.capability)), modules = {};
1027
+ for (const id of Object.keys(meta.modules).sort()) {
1028
+ if (!moved.has(id)) {
1029
+ // Not moved: as the receipt recorded it, and nothing the receipt did not record.
1030
+ if (!Object.hasOwn(before.modules, id)) throw fail("E_UPGRADE_INTEGRITY", `${id} is not a module ${home}'s receipt records, and this upgrade did not move it; retire the instance and spawn it again`);
1031
+ modules[id] = before.modules[id];
1032
+ continue;
1033
+ }
1034
+ if (remote.contentDigest(join(tx.staging, "modules", id), { allowSymlinks: remote.OATS_ALIAS_SYMLINK }) !== meta.modules[id].digest)
1035
+ throw fail("E_UPGRADE_INTEGRITY", `${id}'s staged copy is not the one this upgrade verified; retire the instance and spawn it again`);
1036
+ modules[id] = { ...(object(meta.modules[id].from) ? { from: clone(meta.modules[id].from) } : {}), ...(typeof meta.modules[id].commit === "string" ? { commit: meta.modules[id].commit } : {}) };
1037
+ }
1038
+ // The rows: a module that did not move keeps the receipt's row as it is; a moved one takes its
1039
+ // hook commands and declarations from the row the upgrade derived of its NEW manifest (the
1040
+ // staged copy, verified above), and its settings, their origins, its layer and its level from
1041
+ // the receipt's row. Nothing of a row comes from the home's own record or its own copies.
1042
+ const derived = new Map((meta.capabilityRuntime ?? []).map((row) => [row?.id, row]));
1043
+ const rows = [];
1044
+ for (const id of Object.keys(modules)) {
1045
+ const kept = trustedRow(trust, id);
1046
+ if (!moved.has(id)) { if (kept) rows.push(kept); continue; }
1047
+ const fresh = derived.get(id);
1048
+ if (fresh) rows.push({ ...fresh, ...(kept ? { settings: kept.settings, settingsOrigins: kept.settingsOrigins, layer: kept.layer, level: kept.level } : {}) });
1049
+ }
1050
+ const next = upgradedComposition(home, trust, { moved, modules, rows, source: (id) => join(tx.staging, "modules", id) });
1051
+ // What was copied is what was verified: the staged copy is in the home, so the kernel's copy
1052
+ // of each moved module is digested again where the home cannot write it.
1053
+ try {
1054
+ for (const id of moved) {
1055
+ if (remote.contentDigest(kernelModuleDirIn(home, next.store, id), { allowSymlinks: remote.OATS_ALIAS_SYMLINK }) === meta.modules[id].digest) continue;
1056
+ throw fail("E_UPGRADE_INTEGRITY", `the kernel's copy of ${id} is not the one this upgrade verified (its staged copy changed while it was copied); retire the instance and spawn it again`);
1057
+ }
1058
+ } catch (e) { removeUnnamedStore(home, next.store); throw e; }
1059
+ return { before, next, made: next.store };
1060
+ }
945
1061
  function recordedInstructionOrder(meta, modules) {
946
1062
  const names = modules.map((m) => m.name),
947
1063
  order = [];
@@ -1088,6 +1204,10 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1088
1204
  }
1089
1205
  }
1090
1206
  const holding = claimHomeFor("upgrade", name, home);
1207
+ // A provider home's move of the kernel's own copies (kernelMove); null for any other home.
1208
+ let kernel = null;
1209
+ // A provider home's receipt, as this process read it before it moved anything; null otherwise.
1210
+ let receiptBytes = null;
1091
1211
  let mutexIdentity,
1092
1212
  p,
1093
1213
  tx,
@@ -1153,6 +1273,12 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1153
1273
  replayed: true,
1154
1274
  };
1155
1275
  if (stored?.status === "partial") {
1276
+ // (Its journal and its staged copies are in the home, which its agent can write.)
1277
+ if (providerHomeTrust(home))
1278
+ throw fail(
1279
+ "E_UPGRADE_PARTIAL",
1280
+ `${name} is on a session provider, and its upgrade was interrupted at ${stored.step ?? "an unrecorded step"}: a provider home's upgrade is not resumed from the journal in its home. The kernel still runs its own copies of the modules, the ones its receipt names; retire the instance (oats retire ${name}) and spawn it again`,
1281
+ );
1156
1282
  if (
1157
1283
  !Array.isArray(stored.steps?.hooks) ||
1158
1284
  !object(stored.priorMeta) ||
@@ -1279,6 +1405,11 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1279
1405
  const baseline = findRetirementBaseline(home);
1280
1406
  if (existsSync(baseline))
1281
1407
  copyTreeSafe(baseline, join(tx.staging, "retirement-baseline.json"));
1408
+ // A provider home: the receipt as it is now, kept in this process. A move that fails puts
1409
+ // THESE bytes back, never the copy kept in the home's staging, which the home can write:
1410
+ // the receipt says whether the home is a provider home at all, where its session is, and
1411
+ // what the kernel runs of it.
1412
+ if (providerHomeTrust(home)) receiptBytes = readFileSync(baseline);
1282
1413
  // All replacement bytes now belong to the durable staging transaction.
1283
1414
  // Drop temporary planning copies before a killed resumable invocation can
1284
1415
  // strand them outside the receipt's staging tree.
@@ -1286,6 +1417,10 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1286
1417
  // A durable partial fence precedes the hook. If the process dies before
1287
1418
  // recording its success, retry re-runs that idempotent hook, never restores.
1288
1419
  writeJson(path, receipt);
1420
+ // A provider home: the kernel's copies for the home as this move leaves it, before any
1421
+ // hook runs (each hook then runs from the kernel's copy). The receipt still names the old pair.
1422
+ kernel = kernelMove(home, receipt, tx);
1423
+ dieAt("upgrade:copies-made");
1289
1424
  }
1290
1425
  const save = () => writeJson(path, receipt);
1291
1426
  for (const row of receipt.modules) {
@@ -1295,7 +1430,8 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1295
1430
  );
1296
1431
  if (!hookCommand(module.manifest)) continue;
1297
1432
  const moduleDirectory = join(tx.staging, "modules", module.name);
1298
- const manifest = readJson(join(moduleDirectory, "oats.json"));
1433
+ // (A provider home: the manifest whose hook is run is the kernel's copy's, as the hook is.)
1434
+ const manifest = readJson(join(kernel ? kernelModuleDirIn(home, kernel.next.store, module.name) : moduleDirectory, "oats.json"));
1299
1435
  if (
1300
1436
  manifest.capability !== module.name ||
1301
1437
  remote.contentDigest(moduleDirectory, {
@@ -1317,7 +1453,8 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1317
1453
  home,
1318
1454
  meta: receipt.priorMeta,
1319
1455
  module,
1320
- dir: join(tx.staging, "modules", module.name),
1456
+ dir: kernel ? kernelModuleDirIn(home, kernel.next.store, module.name) : join(tx.staging, "modules", module.name),
1457
+ ...(kernel ? { moduleDir: kernelModuleDirIn(home, kernel.next.store, module.name) } : {}),
1321
1458
  to: receipt.hookTargets?.[row.capability] ?? row.to,
1322
1459
  root,
1323
1460
  });
@@ -1363,6 +1500,13 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1363
1500
  save();
1364
1501
  }
1365
1502
  tx.commit({ preserveOnFailure: forwardOnly, retainStaging: true });
1503
+ // A provider home: the receipt's ONE write names the kernel's new copies and the new rows
1504
+ // together (an undo: the previous pair again). Before it the kernel runs the old pair,
1505
+ // after it the new one; there is no moment between. A store is removed only after it.
1506
+ if (kernel) {
1507
+ writeUpgradedComposition(home, kernel.next);
1508
+ dieAt("upgrade:receipt-written");
1509
+ }
1366
1510
  receipt.steps.swapped = true;
1367
1511
  save();
1368
1512
  }
@@ -1405,6 +1549,9 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1405
1549
  // after this point finishes event publication and staging cleanup only.
1406
1550
  writeJson(path, complete);
1407
1551
  receipt = complete;
1552
+ // A provider home: the move is complete, and nothing can put the earlier receipt back any
1553
+ // more. Only now does a store go: the one before the previous (after an undo, the newer one).
1554
+ if (kernel) pruneModulesStores(home);
1408
1555
  return finishCleanup(home, path, receipt);
1409
1556
  } catch (error) {
1410
1557
  if (receipt?.status === "complete") throw error;
@@ -1412,6 +1559,9 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1412
1559
  receipt?.status === "partial" &&
1413
1560
  (forwardOnly || receipt.steps?.hooks?.length)
1414
1561
  ) {
1562
+ // (A provider home: the store this move made goes unless the receipt names it; the move is
1563
+ // not resumed, and the kernel runs the pair the receipt names.)
1564
+ if (kernel?.made) removeUnnamedStore(home, kernel.made);
1415
1565
  try {
1416
1566
  writeJson(path, receipt);
1417
1567
  } catch {
@@ -1425,7 +1575,9 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1425
1575
  for (const entry of readdirSync(history))
1426
1576
  renameSync(join(history, entry), join(home, ".oats/previous", entry));
1427
1577
  const baseline = join(tx.staging, "retirement-baseline.json");
1428
- if (existsSync(baseline))
1578
+ // (A provider home's receipt is put back whole from this process's own copy of it.)
1579
+ if (receiptBytes) writeFileAtomic(findRetirementBaseline(home), receiptBytes, { mode: 0o600 });
1580
+ else if (existsSync(baseline))
1429
1581
  writeFileAtomic(findRetirementBaseline(home), readFileSync(baseline), { mode: 0o600 });
1430
1582
  tx.rollback();
1431
1583
  }
@@ -1439,6 +1591,10 @@ export async function applyUpgrade(ctx, root, name, opts = {}) {
1439
1591
  if (existsSync(previous) && readdirSync(previous).length === 0)
1440
1592
  rmSync(previous, { recursive: true });
1441
1593
  }
1594
+ // A provider home: the store this move made goes, unless the receipt names it (a move whose
1595
+ // receipt was written and that could not be rolled back). No other store is touched: the
1596
+ // earlier pair, and the one before it, are as the receipt names them.
1597
+ if (kernel?.made) removeUnnamedStore(home, kernel.made);
1442
1598
  appendEvent(
1443
1599
  home,
1444
1600
  {
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 });
@@ -5,6 +5,7 @@ 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
7
  import { recordsSessionProvider } from "./session-providers.mjs";
8
+ import { providerHomeTrust } from "./home-integrity.mjs";
8
9
  import { processLiveness } from "./worktree-hooks.mjs";
9
10
  import { lifecycleBusy, oatsError } from "./errors.mjs";
10
11
 
@@ -161,6 +162,12 @@ export function retireCleanupAdmission(home, name, { force = false } = {}, readW
161
162
  // Compensation metadata is the SPAWN's, from whichever record survived — never
162
163
  // a failed retry's report, which says nothing about what still needs undoing.
163
164
  if (!liveMeta?.capabilityMeta && quarantine?.cleanup?.capabilityMeta) meta.capabilityMeta = quarantine.cleanup.capabilityMeta;
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; }
164
171
  // A home on a session provider keeps what its own record says of its launch: its receipt is the
165
172
  // authority for it, and a rollback marker is written `launched: false` whatever the provider had
166
173
  // answered by then, which would set the record against the receipt and refuse every retire.