@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
@@ -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
  {
@@ -8,7 +8,16 @@ import { SESSION_RESUME_FEATURE } from "./session-resume-contract.mjs";
8
8
  /** `oats spawn --task-file -` reads the task from standard input: how a routed spawn's task reaches
9
9
  * its host (lib/servers.mjs routeCommand); a host that does not list this gets it as an argument. */
10
10
  export const SPAWN_TASK_STDIN_FEATURE = "spawn-task-stdin";
11
- export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "instance-related-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE, "instance-board"]);
11
+ /** Session providers (lib/session-providers.mjs): a session backend a capability supplies, beside the
12
+ * kernel's built-in ones. A host that lists this takes `--backend <provider>`, records and answers
13
+ * provider homes; one that does not refuses such a home's session verbs. */
14
+ export const SESSION_PROVIDERS_FEATURE = "session-providers";
15
+ /** The kernel's built-in session backends: `sessionBackends` in `oats version --json`. A session
16
+ * provider is never listed there: it is a capability's, named by the homes and souls that have it. */
17
+ export const BUILTIN_SESSION_BACKENDS = Object.freeze(["tmux"]);
18
+ /** A session provider's name, and what `--backend` takes. */
19
+ export const SESSION_PROVIDER_NAME_RE = /^[a-z0-9][a-z0-9-]{0,39}$/;
20
+ export const KERNEL_FEATURES = Object.freeze(["retire-home", "session-start", "session-restart", "launch-config", "schedule", "schedule-host-caps", "session-upload", "operations", "instance-git", "instance-git-remote", "souls-declarations", "lifecycle-plans", "retire-retention", "readiness", "spawn-preview", "instance-events", "instance-events-2", "schedule-history", "schedule-read-2", "spawn-preview-2", "spawn-idempotency", "spawn-idempotency-2", "spawn-apply-2", "workspace-v2", "instance-modules", "spawn-provider-payload", "served-identity", "packages-no-approval", "spawn-name", "settings-origins", "team-model-3", "settings-declared", "capabilities-private", "layers-from", "harness", "package-souls", "triggers", "automations", "desktop-facts", "launch-preference", "preview-composed-from", "observe-max-age", "spawn-preview-max-age", "launch-config-default", "capability-show", "capture-file", "workspace-identity", "server-connect", "capability-route", "servers-per-workspace", "operator-default-soul", "waiting-on-you", "automation-descriptions", "souls-capabilities", "soul-composed-instructions", "teams-conditional-default", "server-probe-features", "worktree-event", "trigger-sources", "session-attach-detach-key", "lifecycle-kernel-codes", "schedule-run-warnings", "lifecycle-claim-stop", "launch-prompt-dev-channel", "soul-launch", "retire-plan-own-worktree", "spawn-kernel-codes", "soul-skills", "roster-workspace-key", "spawn-apply-max-age", "status-retire-state", "session-inspect-size", "session-inspect-running", "deployments-list", "soul-composed-skills", "instance-color", "spawn-suggest-name", "instance-upgrade", "session-attach-no-status-line", "session-attach-prefix-scroll", "instance-suggest-name", "spawn-apply-suggest-name", SESSION_RESUME_FEATURE, "instance-background", "instance-pin", "instance-same-work", "instance-related-work", "warm-reader", "status-liveness", "lifecycle-claim-start", "wake-hold", "spawn-attribution", "workspace-tasks-payload", "settings-committed-only", "schedule-host-register-only", SPAWN_TASK_STDIN_FEATURE, "instance-board", SESSION_PROVIDERS_FEATURE]);
12
21
  /** The agent's board (feature instance-board, lib/instance-board.mjs): `boardApi` in the probe, the board
13
22
  * file and the board commands' answers. */
14
23
  export const BOARD_API = 1;
@@ -0,0 +1,9 @@
1
+ /** CLI startup's Node floor. No imports or effects: this must load before the kernel. */
2
+ export function nodeVersionFailure(found) {
3
+ if (Number(found.split(".")[0]) >= 22) return null;
4
+ return { schemaVersion: 1, ok: false, error: {
5
+ code: "E_NODE_UNSUPPORTED",
6
+ message: `oats needs Node.js 22 or later; this is Node.js ${found}`,
7
+ details: { found, minimum: "22" },
8
+ } };
9
+ }
@@ -0,0 +1,60 @@
1
+ /** Private entry point of lib/session-providers.mjs (callSessionProvider); no CLI or provider
2
+ * contract. The kernel runs every command of a session provider through this process, started in
3
+ * a process group of its own, of which it is the leader:
4
+ *
5
+ * node provider-call-child.mjs <group file | -> <provider script> [arguments…]
6
+ *
7
+ * - With a group file, it records who it is there first (`{ pid, processStart }`, created
8
+ * exclusively), outside the home, and only then runs the provider. A kernel that finds the call
9
+ * of a kernel that was killed ends this group by that record before it settles anything the
10
+ * call may still do (lib/core.mjs endProviderCall). A file that is already there is that
11
+ * kernel's word that the call is void: the provider is not run. Nor is it once the call's own
12
+ * record (the group file's name without `.group`) is gone: that kernel has ended the call and
13
+ * taken its records away, the void one last.
14
+ * - The provider's script runs in this group, with this process's stdin, stdout and stderr: its
15
+ * request and its answer pass through untouched. A provider runs its own helpers in the group
16
+ * and never detaches them.
17
+ * - A signal to end it (the kernel's timeout sends SIGTERM) ends the whole group, by SIGKILL.
18
+ *
19
+ * It exits as the provider's script did. 125: the call was void or could not be recorded, and
20
+ * nothing was run. 126: the script could not be started. */
21
+ import { spawn } from "node:child_process";
22
+ import { existsSync, linkSync, rmSync, writeFileSync } from "node:fs";
23
+ import { processStartToken } from "../packages/record/lib/process-identity.mjs";
24
+
25
+ const [groupFile, script, ...args] = process.argv.slice(2);
26
+ const endGroup = () => process.kill(0, "SIGKILL");
27
+ // A test's seam (reserved launch environment): this leader starts late, as on a loaded host.
28
+ const late = Number(process.env.OATS_TEST_PROVIDER_LEADER_DELAY_MS);
29
+ delete process.env.OATS_TEST_PROVIDER_LEADER_DELAY_MS;
30
+ if (Number.isFinite(late) && late > 0) Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(late, 10_000));
31
+ for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.on(signal, endGroup);
32
+
33
+ if (groupFile !== "-") {
34
+ const processStart = processStartToken(process.pid);
35
+ // Without its start time the record could not tell this group from a later one of the same id.
36
+ if (!processStart) process.exit(125);
37
+ // Published whole, by an exclusive link from a file of its own: a reader never finds it half
38
+ // written, whenever this process ends (lib/core.mjs publishExclusive, the same rule).
39
+ const own = `${groupFile}.${process.pid}.tmp`;
40
+ try {
41
+ writeFileSync(own, `${JSON.stringify({ pid: process.pid, processStart })}\n`, { flag: "wx", mode: 0o600 });
42
+ linkSync(own, groupFile);
43
+ } catch { rmSync(own, { force: true }); process.exit(125); } // already there (void), or not writable: nothing is run
44
+ rmSync(own, { force: true });
45
+ if (!existsSync(groupFile.slice(0, -".group".length))) { rmSync(groupFile, { force: true }); process.exit(125); }
46
+ }
47
+ // A test's seam (reserved launch environment): the kernel that waits for this command ends
48
+ // while its provider's command runs, shortly after it started and read its request
49
+ // (lib/provider-test-seams.mjs).
50
+ const endsKernel = process.env.OATS_TEST_PROVIDER_KILL_KERNEL !== undefined;
51
+ delete process.env.OATS_TEST_PROVIDER_KILL_KERNEL;
52
+ const kernel = process.ppid;
53
+ const child = spawn(process.execPath, [script, ...args], { stdio: "inherit" });
54
+ if (endsKernel) setTimeout(() => process.kill(kernel, "SIGKILL"), 150);
55
+ child.on("error", () => process.exit(126));
56
+ child.on("close", (code, signal) => {
57
+ if (!signal) process.exit(code ?? 1);
58
+ for (const handled of ["SIGTERM", "SIGINT", "SIGHUP"]) process.removeAllListeners(handled);
59
+ process.kill(process.pid, signal);
60
+ });
@@ -0,0 +1,83 @@
1
+ /** The resume cap of a home on a session provider (lib/session-providers.mjs;
2
+ * docs/execution-targets.md, "Lost sessions, and the resume"). A
3
+ * provider home's session that is gone, and that OATS did not stop, is a lost session, and whatever
4
+ * brings it back is a resume: the machine sweep's notice (`oats session resume`), `session start
5
+ * --resume`, and any input to it (a mail the broker delivers, a scheduled wake, a person's
6
+ * `session input`), since the provider restarts the session on that input. The cap is the kernel's
7
+ * own, counted here BEFORE the provider's input is called, so no path to the provider bypasses it:
8
+ * at most RESUME_LIMIT resumes of one home in RESUME_WINDOW_MS, in one boot, as the sweep bounds a
9
+ * tmux home's starts (lib/session-resume.mjs). At the cap the resume is refused
10
+ * E_SESSION_NOT_RUNNING, nothing is sent, and a mail stays unread.
11
+ *
12
+ * One file per home under OATS_HOME_DIR (`session-resume/provider-resumes/<sha256 of the home's
13
+ * real path>.json`): `{ bootId, home, resumes: [<ISO time>] }`. Another boot's file counts
14
+ * nothing. Without a boot id (neither Linux nor macOS) nothing is counted, as for the sweep.
15
+ * Kernel-private, not a contract. A leaf: `session input` reads it without loading the sweep. */
16
+ import { createHash } from "node:crypto";
17
+ import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
18
+ import { join } from "node:path";
19
+ import { oatsError } from "./errors.mjs";
20
+ import { bootId, homeKey, resumeStateDir, sameBoot } from "./session-seen.mjs";
21
+
22
+ /** The resume notice of a home on a session provider: one line that asserts only what holds for
23
+ * every such instance, whatever ended its session. It is sent as the session's input. */
24
+ export const PROVIDER_RESUME_NOTICE = "OATS resumed this session after it was interrupted. Continue from where you were.";
25
+ /** How long the resume of a lost session waits for the processes of its last run to leave the home,
26
+ * before it refuses: `waitMs` is the caller's (150 s for a start, none for an input). */
27
+ export const RESUME_QUIET_WAIT_MS = 150_000;
28
+ /** That wait as this process runs it. OATS_TEST_PROVIDER_RESUME_WAIT_MS (a test's seam) shortens a
29
+ * resume that waits: a value above the caller's own wait is that wait, so the seam never makes a
30
+ * resume wait longer; and a resume that does not wait (an input) still does not. */
31
+ export function resumeQuietWait(waitMs = RESUME_QUIET_WAIT_MS) {
32
+ const seam = Number(process.env.OATS_TEST_PROVIDER_RESUME_WAIT_MS);
33
+ return waitMs > 0 && seam > 0 ? Math.min(seam, waitMs) : waitMs;
34
+ }
35
+ /** At most this many resumes of one home in RESUME_WINDOW_MS. */
36
+ export const RESUME_LIMIT = 3;
37
+ /** The span over which a home's resumes are counted. */
38
+ export const RESUME_WINDOW_MS = 60 * 60_000;
39
+
40
+ const fileOf = (home) => join(resumeStateDir(), "provider-resumes", `${createHash("sha256").update(homeKey(home)).digest("hex").slice(0, 32)}.json`);
41
+ /** The lock a resume of `home` is counted under (lib/dir-lock.mjs): the caller's to take around
42
+ * countProviderResume and its `undo`, so two counts never read the same file. Not taken here:
43
+ * this module is a leaf the hot reads load. */
44
+ export const resumeCountLock = (home) => `${fileOf(home)}.lock`;
45
+ function readResumes(home, boot, now) {
46
+ let doc;
47
+ try { doc = JSON.parse(readFileSync(fileOf(home), "utf8")); } catch { return []; }
48
+ if (!doc || typeof doc !== "object" || !sameBoot(doc.bootId, boot) || !Array.isArray(doc.resumes)) return [];
49
+ return doc.resumes.filter((t) => typeof t === "string" && Number.isFinite(Date.parse(t)) && now - Date.parse(t) < RESUME_WINDOW_MS).sort();
50
+ }
51
+ function writeResumes(home, boot, resumes) {
52
+ const path = fileOf(home), tmp = `${path}.${process.pid}.tmp`;
53
+ mkdirSync(join(resumeStateDir(), "provider-resumes"), { recursive: true, mode: 0o700 });
54
+ try { writeFileSync(tmp, JSON.stringify({ bootId: boot, home: homeKey(home), resumes }, null, 2) + "\n", { mode: 0o600 }); renameSync(tmp, path); }
55
+ catch (e) { rmSync(tmp, { force: true }); throw e; }
56
+ }
57
+
58
+ /** How many resumes of `home` are counted now → `{ count, limit, nextAttemptAt }`: `nextAttemptAt`
59
+ * (an ISO time) when the cap is reached, the instant its oldest counted resume leaves the window. */
60
+ export function providerResumes(home, { boot = bootId(), now = Date.now() } = {}) {
61
+ const resumes = boot ? readResumes(home, boot, now) : [];
62
+ return { count: resumes.length, limit: RESUME_LIMIT, nextAttemptAt: resumes.length >= RESUME_LIMIT ? new Date(Date.parse(resumes[0]) + RESUME_WINDOW_MS).toISOString() : null };
63
+ }
64
+
65
+ /** Count one resume of the provider home `home`, before the provider's input is called → `{ undo }`:
66
+ * `undo()` takes the count back, only for an input the provider itself then refused (nothing was
67
+ * sent: a notice that was not sent is no resume). An input whose call failed, or answered outside
68
+ * the rules, keeps its count: the provider may have restarted the session on it. Throws E_SESSION_NOT_RUNNING at the cap, having counted nothing;
69
+ * `details.resumeCap` is `{ limit, windowMs, nextAttemptAt }`. `instance` names the home in the
70
+ * refusal. A count that cannot be written refuses the resume (E_SESSION_NOT_RUNNING too): an
71
+ * uncounted resume would be one the cap never sees. */
72
+ export function countProviderResume(home, instance, { boot = bootId(), now = Date.now() } = {}) {
73
+ if (!boot) return { undo() {} };
74
+ const resumes = readResumes(home, boot, now);
75
+ if (resumes.length >= RESUME_LIMIT) {
76
+ const nextAttemptAt = new Date(Date.parse(resumes[0]) + RESUME_WINDOW_MS).toISOString();
77
+ throw Object.assign(oatsError("E_SESSION_NOT_RUNNING", `${instance} lost its session and was resumed ${resumes.length} times in the last hour, and was lost again each time: it is not resumed again before ${nextAttemptAt}, and nothing was sent. Start it by hand (oats session restart --home ${home}) if it should run`), { details: { resumeCap: { limit: RESUME_LIMIT, windowMs: RESUME_WINDOW_MS, nextAttemptAt } } });
78
+ }
79
+ const at = new Date(now).toISOString();
80
+ try { writeResumes(home, boot, [...resumes, at]); }
81
+ catch (e) { throw oatsError("E_SESSION_NOT_RUNNING", `${instance} lost its session, and its resume could not be counted (${e?.code ?? e?.message ?? e}); nothing was sent`); }
82
+ return { undo() { try { const kept = readResumes(home, boot, now); const i = kept.lastIndexOf(at); if (i >= 0) { kept.splice(i, 1); writeResumes(home, boot, kept); } } catch { /* the count stands: a resume too many is counted, never one too few */ } } };
83
+ }
@@ -0,0 +1,20 @@
1
+ /** Test seams for the lifecycle of a provider home (docs/design/2026-11-20-provider-home-lifecycle.md,
2
+ * "The holder died" and "A provider's command outlives the kernel that ran it"). No effect unless
3
+ * OATS_TEST_PROVIDER_DIE_AT is set; reserved launch environment (lib/reserved-launch-env.mjs):
4
+ * never a launch's to set.
5
+ *
6
+ * OATS_TEST_PROVIDER_DIE_AT names one point, and the kernel dies there, by SIGKILL, as a killed
7
+ * command does:
8
+ * - a point between two writes (`mark:receipt-written`, `stop:stoppedAt-written`, …: lib/core.mjs);
9
+ * - `call:<verb>:before` and `call:<verb>:after`: right before and right after a provider's
10
+ * command (lib/session-providers.mjs callSessionProvider);
11
+ * - `call:<verb>:during`: while the provider's command runs. The kernel cannot kill itself
12
+ * inside a synchronous wait, so the leader of the command's process group does it, before it
13
+ * runs the provider (lib/provider-call-child.mjs, OATS_TEST_PROVIDER_KILL_KERNEL). */
14
+ export function dieAt(point) {
15
+ if (process.env.OATS_TEST_PROVIDER_DIE_AT !== point) return;
16
+ process.kill(process.pid, "SIGKILL");
17
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10_000); // the signal is on its way
18
+ }
19
+ /** Whether this kernel is to die while the provider's `verb` command runs. */
20
+ export const diesDuring = (verb) => process.env.OATS_TEST_PROVIDER_DIE_AT === `call:${verb}:during`;
package/lib/read-call.mjs CHANGED
@@ -25,6 +25,7 @@ import { resetRuntimeNames, runtimeNameWarning } from "./deprecation.mjs";
25
25
  import { OWN_NAME_FAILURES } from "./errors.mjs";
26
26
  import { activateLocalInputs, localRevision, resetLocalInputs } from "./local-inputs.mjs";
27
27
  import { createReadSession, MAX_AGE_LIMIT, READ_REMOTE_BUDGET_MS, resetGitProbes, resetSshCommand } from "./remote.mjs";
28
+ import { resetKernelNode } from "./stable-node.mjs";
28
29
  import { observeResolvedDeployment, resetResolvedDeployment, settleResolvedDeployment } from "./resolved-deployment.mjs";
29
30
 
30
31
  /** Every module-level binding the reads' import closure writes, and what a call does with it: `reset`
@@ -38,6 +39,7 @@ export const READ_STATE = [
38
39
  { module: "lib/remote.mjs", binding: "gitVersions", how: "reset", reset: resetGitProbes },
39
40
  { module: "lib/remote.mjs", binding: "protocolPins", how: "reset", reset: resetGitProbes },
40
41
  { module: "lib/resolved-deployment.mjs", binding: "reported", how: "reset", reset: resetResolvedDeployment },
42
+ { module: "lib/stable-node.mjs", binding: "kernel", how: "reset", reset: resetKernelNode },
41
43
  { module: "lib/resolved-deployment.mjs", binding: "observer", how: "scoped", why: "set and settled by the call when it is given `deployments`; else the CLI's own, settled at exit" },
42
44
  { module: "lib/remote.mjs", binding: "liveChildren", how: "safe", why: "a registry of live git process groups, each leaving on 'close': empty once a call's session is closed, never cleared (that would lose exit reaping)" },
43
45
  { module: "lib/remote.mjs", binding: "cacheLocks", how: "safe", why: "an in-process mutex per cache repo; an entry is removed when its holder releases it" },