@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.
- package/bin/oats.mjs +112 -20
- package/docs/capabilities.md +697 -11
- package/docs/capability-manifest.schema.json +66 -0
- package/docs/configuration.md +27 -7
- package/docs/design/2026-11-19-sandboxes.md +595 -121
- package/docs/design/2026-11-20-provider-home-lifecycle.md +322 -0
- package/docs/design/README.md +7 -3
- package/docs/desktop-cli-api.md +330 -9
- package/docs/desktop.md +181 -48
- package/docs/execution-targets.md +210 -4
- package/docs/first-team.md +11 -0
- package/docs/implementation.md +24 -3
- package/docs/integrations.md +2 -2
- package/docs/knowledge-capability-authoring.md +1 -1
- package/docs/knowledge-reference/proposal.md +10 -0
- package/docs/knowledge.md +20 -11
- package/docs/official-catalog.md +2 -2
- package/docs/packages.md +7 -7
- package/docs/release-notes/v0.69.24.md +264 -0
- package/docs/release-notes/v0.70.0.md +155 -0
- package/docs/souls-and-instances.md +57 -0
- package/docs/trust-model.md +8 -1
- package/docs/tui.md +21 -1
- package/docs/upgrading.md +19 -5
- package/docs/workspaces.md +13 -5
- package/lib/automation-scope.mjs +1 -1
- package/lib/capability-show.mjs +20 -1
- package/lib/command-flags.mjs +2 -2
- package/lib/compile-cache.mjs +1 -1
- package/lib/core.mjs +1455 -203
- package/lib/errors.mjs +4 -1
- package/lib/home-integrity.mjs +329 -0
- package/lib/hook-env.mjs +107 -0
- package/lib/host-run.mjs +11 -3
- package/lib/instance-events.mjs +32 -5
- package/lib/instance-git.mjs +9 -0
- package/lib/instance-inspect.mjs +107 -9
- package/lib/instance-lifecycle.mjs +15 -3
- package/lib/instance-listing.mjs +101 -8
- package/lib/instance-resolution.mjs +85 -2
- package/lib/instance-upgrade.mjs +170 -14
- package/lib/kernel-features.mjs +10 -1
- package/lib/node-version.mjs +9 -0
- package/lib/provider-call-child.mjs +60 -0
- package/lib/provider-resume.mjs +83 -0
- package/lib/provider-test-seams.mjs +20 -0
- package/lib/read-call.mjs +2 -0
- package/lib/remote.mjs +33 -1
- package/lib/reserved-launch-env.mjs +8 -1
- package/lib/retire-admission.mjs +12 -1
- package/lib/sandbox-allowances.mjs +329 -0
- package/lib/schedule.mjs +14 -4
- package/lib/servers.mjs +38 -5
- package/lib/session-inspect.mjs +123 -87
- package/lib/session-providers.mjs +575 -0
- package/lib/session-receipt.mjs +93 -0
- package/lib/session-resume.mjs +68 -15
- package/lib/stable-node.mjs +3 -0
- package/lib/triggers.mjs +3 -1
- package/lib/upgrade-state.mjs +6 -1
- package/lib/worktree-hooks.mjs +18 -2
- package/lib/worktree.mjs +21 -7
- package/package-catalog.json +2 -2
- package/package.json +2 -1
- package/packages/client/capability-list.mjs +21 -0
- package/packages/client/cli-adapter.mjs +19 -4
- package/packages/client/cli-locator.mjs +5 -1
- package/packages/client/deployment-data.mjs +23 -1
- package/packages/client/deployment-panel.mjs +25 -3
- package/packages/client/home-board.mjs +33 -19
- package/packages/client/inspect-boundary.mjs +18 -8
- package/packages/client/instance-acts.mjs +30 -3
- package/packages/client/instance-board.mjs +206 -0
- package/packages/client/instance-presentation.mjs +55 -0
- package/packages/client/liveness.mjs +15 -4
- package/packages/client/own-codes.mjs +5 -1
- package/packages/client/remote-roster.mjs +6 -1
- package/packages/client/session-backends.mjs +31 -0
- package/packages/client/session-start.mjs +18 -6
- package/packages/client/spawn-apply-cli.mjs +5 -3
- package/packages/client/spawn-apply-contract.mjs +25 -2
- package/packages/client/spawn-apply.mjs +5 -1
- package/packages/client/spawn-messages.mjs +3 -0
- package/packages/client/terminal-contract.mjs +4 -0
- package/packages/client/waiting-on-you.mjs +12 -2
- package/packages/tui/lib/model.mjs +14 -3
- package/packages/tui/lib/store.mjs +12 -3
- package/skills/oats-getting-started/SKILL.md +3 -3
package/lib/instance-upgrade.mjs
CHANGED
|
@@ -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
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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/kernel-features.mjs
CHANGED
|
@@ -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
|
-
|
|
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" },
|