@awebai/oats 0.69.14 → 0.69.16
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/README.md +1 -1
- package/bin/oats.mjs +79 -18
- package/docs/capabilities.md +57 -14
- package/docs/container.md +111 -17
- package/docs/desktop-cli-api.md +215 -19
- package/docs/desktop.md +3 -3
- package/docs/execution-targets.md +15 -3
- package/docs/first-team.md +4 -3
- package/docs/implementation.md +19 -9
- package/docs/integrations.md +9 -8
- package/docs/knowledge-and-learning.md +2 -2
- package/docs/knowledge-theory.md +17 -15
- package/docs/knowledge.md +202 -179
- package/docs/official-catalog.md +4 -4
- package/docs/packages.md +13 -13
- package/docs/release-notes/v0.69.15.md +444 -0
- package/docs/release-notes/v0.69.16.md +169 -0
- package/docs/schedules.md +168 -34
- package/docs/servers.md +64 -3
- package/docs/souls-and-instances.md +100 -19
- package/docs/upgrading.md +26 -6
- package/docs/workspaces.md +2 -2
- package/lib/claim.mjs +2 -3
- package/lib/command-flags.mjs +4 -2
- package/lib/core.mjs +215 -72
- package/lib/dir-lock.mjs +17 -0
- package/lib/errors.mjs +2 -1
- package/lib/host-run.mjs +218 -0
- package/lib/host-stop-child.mjs +21 -0
- package/lib/instance-git.mjs +32 -6
- package/lib/instance-lifecycle.mjs +4 -3
- package/lib/instance-listing.mjs +35 -6
- package/lib/kernel-features.mjs +4 -1
- package/lib/read-call.mjs +1 -1
- package/lib/remote.mjs +17 -14
- package/lib/schedule.mjs +237 -20
- package/lib/servers.mjs +83 -5
- package/lib/session-end.mjs +28 -8
- package/lib/session-resume.mjs +10 -18
- package/lib/session-seen.mjs +4 -64
- package/lib/status-words.mjs +11 -4
- package/lib/system-tools.mjs +1 -36
- package/lib/worktree-hooks.mjs +6 -175
- package/lib/worktree.mjs +19 -10
- package/package-catalog.json +3 -3
- package/package.json +4 -1
- package/packages/record/README.md +56 -21
- package/packages/record/docs/capture-service.md +8 -5
- package/packages/record/docs/turn-record-sot.md +9 -0
- package/packages/record/lib/capture-health.mjs +6 -4
- package/packages/record/lib/capture-lock.mjs +31 -27
- package/packages/record/lib/capture-retained-scratch.mjs +4 -3
- package/packages/record/lib/capture-scratch.mjs +2 -1
- package/packages/record/lib/derived-state.mjs +4 -2
- package/packages/record/lib/index-db.mjs +4 -2
- package/packages/record/lib/lock-holder.mjs +21 -0
- package/packages/record/lib/private-files.mjs +18 -0
- package/packages/record/lib/process-identity.mjs +310 -0
- package/packages/record/lib/store.mjs +31 -25
- package/skills/oats-getting-started/SKILL.md +9 -6
package/lib/core.mjs
CHANGED
|
@@ -51,7 +51,7 @@ import { RETIRE_HOOK_WARNING_KIND, appendEvent, incarnationOf, recordStartBounda
|
|
|
51
51
|
import { killGroup } from "./process-group.mjs";
|
|
52
52
|
import { NAMING_CALLS, NAMING_TIMEOUT_MS, suggestInstanceName } from "./instance-naming.mjs";
|
|
53
53
|
import { interruptExitStatus, isStartToken, originRemoteOf, runWorktreeHooks, selfIdentity, processLiveness, processStartToken, signalGuard, terminateRecordedGroup, treeStillThere, unknownGroupNote, unverifiedGroupWarning, worktreeHooksOf } from "./worktree-hooks.mjs";
|
|
54
|
-
import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
|
|
54
|
+
import { CLAIM_WAIT_MS, acquireClaim, claimUnavailable, claimUnheld, claimWrite, readClaim, recordInClaim, releaseClaim, removeGoneClaim, shownHolder, unwritableCode } from "./claim.mjs";
|
|
55
55
|
import { captureLoginEnvironment } from "./login-environment.mjs";
|
|
56
56
|
import { kernelNode } from "./stable-node.mjs";
|
|
57
57
|
import { assertNoPartialUpgrade, packageRespawnWarning, packageUpgradeDrift, upgradeCleanupWarnings, upgradeMutexRetry, UPGRADE_RECEIPT_NAME_RE } from "./upgrade-state.mjs";
|
|
@@ -87,14 +87,15 @@ import { readPortableBytes } from "./bounded-read.mjs";
|
|
|
87
87
|
import { copyTreeSafe, entriesAsBytes, joinBytes, pathBytes, treeDisagreement } from "./tree-copy.mjs";
|
|
88
88
|
import { readAheadConsumed, readingAhead } from "./read-ahead.mjs";
|
|
89
89
|
import { hashFile, readFilePieces, readFileUpTo } from "./file-pieces.mjs";
|
|
90
|
-
import { assertSameWorktreeHead, filterOverrides, gitRead, gitRefPresence, gitRepoRead, gitRepoRun, headName, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
|
|
90
|
+
import { assertSameWorktreeHead, filterOverrides, gitRead, gitRefPresence, gitRepoRead, gitRepoRun, headName, workTreeOverrides, worktreeCommitUnreached, worktreeHead } from "./instance-git.mjs";
|
|
91
91
|
import { retireGitReadsNoWorkTreeFile, retireSubcommandAt } from "./retire-git-forms.mjs";
|
|
92
92
|
import { systemTool } from "./system-tools.mjs";
|
|
93
93
|
import { SCOPE_ENV_NAMES, agentScope, agentScopeArgv, agentScopeUnit, creatorPlacement, serverScopePlan, serverScopeUnit, serverScopeWarning } from "./tmux-server-scope.mjs";
|
|
94
94
|
import { writeThroughPrivateFile } from "./write-through-private-file.mjs";
|
|
95
95
|
import { readInstanceBackground, writeInstanceBackground } from "./instance-background.mjs";
|
|
96
96
|
import { SAME_WORK_FILE, writeSameWork } from "./instance-same-work.mjs";
|
|
97
|
-
import { readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
|
|
97
|
+
import { HOST_STOP_REASON, readStartExited, sessionEndOf, START_EXITED_FILE, STOP_RECEIPT_FILE } from "./session-end.mjs";
|
|
98
|
+
import { thisBoot } from "./session-seen.mjs";
|
|
98
99
|
import { FRESH_REASON, RESUME_WAITING, SESSION_END } from "./session-resume-contract.mjs";
|
|
99
100
|
import { START_ENV_FILE, START_ENV_KEY_FILE, START_ENV_TMP, checkStartEnv, launchEnvChangedMessage, launchEnvMissingMessage, launchEnvUnverifiedWarning, recordStartEnv } from "./start-env.mjs";
|
|
100
101
|
import { watchResumeConfirmation } from "./launch-prompt-resume.mjs";
|
|
@@ -103,7 +104,7 @@ import { PKG_ROOT } from "./version.mjs";
|
|
|
103
104
|
import { canonicalDeploymentPath } from "./deployment-path.mjs";
|
|
104
105
|
import { INSTANCE_NAME_RE, RESERVED, capabilityAgentDirs, enclosingInstanceHome, findInstanceHomes, listAgents, logicalCwd, readSoul, soulOf, stripInternalAnnotations, withConfigFile, yamlKey } from "./soul-listing.mjs";
|
|
105
106
|
import { RETIRE_BASELINE_VERSION, authorityMismatch, findRetirementBaseline, inspectInstanceSession, instanceSessionTarget, instancesRetirementRoot, isPlainObject, launchStateAgrees, missingSessionReceipt, readJsonOrUndefined, receiptHomeIdentity, receiptRecordsHome, recordsHerdr, refuseHerdrHome, retirementBaselinePath, runtimeAuthorityOf, tmuxEndpointAgrees } from "./session-inspect.mjs";
|
|
106
|
-
import { CLAIM_VERBS, DEFAULT_TMUX_SESSION, LAUNCH_RECIPE_VERSION, claimAction, defaultTmuxWindows, deferredRetireResultPath, directoryRollbackPath, hostProcesses, isCapturedHome, lookupOnPath, missingSocketUnestablished, namedProcesses, parseLaunchCommand, procReadable, processesWorkingIn, readHomeRecord, readRetirePending, redactLaunchCommand, redactLaunchRecipe, retireClaimPath, retirePendingMarkerPath, retireStateOf, subdirs, tmuxFailure, tmuxOn, tmuxServerAbsence, unreadableRecordSaid, upgradeHomeMeta, upgradeLaunchRecipe } from "./instance-listing.mjs";
|
|
107
|
+
import { CLAIM_VERBS, DEFAULT_TMUX_SESSION, LAUNCH_RECIPE_VERSION, claimAction, completionLiveness, defaultTmuxWindows, deferredRetireResultPath, directoryRollbackPath, hostProcesses, isCapturedHome, lookupOnPath, missingSocketUnestablished, namedProcesses, parseLaunchCommand, procReadable, processesWorkingIn, readHomeRecord, readRetirePending, redactLaunchCommand, redactLaunchRecipe, retireCarried, retireClaimPath, retirePendingMarkerPath, retireStateOf, subdirs, tmuxFailure, tmuxOn, tmuxServerAbsence, unreadableRecordSaid, upgradeHomeMeta, upgradeLaunchRecipe } from "./instance-listing.mjs";
|
|
107
108
|
import { LAYERS, PACKAGE_ID_RE } from "./package-catalog.mjs";
|
|
108
109
|
import { RESERVED_LAUNCH_ENV } from "./reserved-launch-env.mjs";
|
|
109
110
|
import { workspaceOf } from "./agents-root.mjs";
|
|
@@ -1460,7 +1461,7 @@ function replacedDialogClaims(prior, ran) {
|
|
|
1460
1461
|
function voidedDialogClaims(ran) {
|
|
1461
1462
|
return ran && Object.fromEntries(Object.keys(ran).map((id) => [id, null]));
|
|
1462
1463
|
}
|
|
1463
|
-
export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots }) {
|
|
1464
|
+
export function runLifecycleHooks(event, { home, instance, agentName, soulDir, soulId, contextDir, workspaceDir, rootDir, resolved, priorMeta = {}, extraEnv = {}, assertRoots, finished, onFinished }) {
|
|
1464
1465
|
const results = { meta: {}, briefs: [], warnings: [], order: [], launch: {}, env: {}, failures: [], contributions: [], volatileEnv: {}, dialogClaims: {} };
|
|
1465
1466
|
// OATS_SOUL is set for EVERY hook: a caller that does not name the soul (launch,
|
|
1466
1467
|
// retire) gets the directory the home's spawn recorded.
|
|
@@ -1476,6 +1477,13 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
|
|
|
1476
1477
|
if (cap.executable && !cap.trust?.trusted) results.warnings.push(`${cap.id}: executable surface disabled — ${cap.trust?.reason || "not trusted"}`);
|
|
1477
1478
|
const cmd = cap.hooks?.[event];
|
|
1478
1479
|
if (!cmd) continue;
|
|
1480
|
+
// A hook that has ended already (`finished`: capability → the meta it answered, or undefined)
|
|
1481
|
+
// is not run: it is in the order, with that meta, as if this call had run it.
|
|
1482
|
+
if (finished?.has(cap.id)) {
|
|
1483
|
+
results.order.push(cap.id);
|
|
1484
|
+
if (finished.get(cap.id) !== undefined) results.meta[cap.id] = finished.get(cap.id);
|
|
1485
|
+
continue;
|
|
1486
|
+
}
|
|
1479
1487
|
assertRoots?.();
|
|
1480
1488
|
results.order.push(cap.id);
|
|
1481
1489
|
if (event === "spawn" || event === "launch") results.dialogClaims[cap.id] = null;
|
|
@@ -1510,6 +1518,8 @@ export function runLifecycleHooks(event, { home, instance, agentName, soulDir, s
|
|
|
1510
1518
|
if (DIALOG_CLAIMS.includes(o.dialogClaims)) results.dialogClaims[cap.id] = o.dialogClaims;
|
|
1511
1519
|
else results.warnings.push(`${cap.id} ${event} hook answered dialogClaims ${String(JSON.stringify(o.dialogClaims)).slice(0, 64)}, neither "reported" nor "none"; read as no answer`);
|
|
1512
1520
|
}
|
|
1521
|
+
// The hook ended and its answer is taken: the caller is told, with the meta it answered.
|
|
1522
|
+
onFinished?.(cap.id, o.meta || undefined);
|
|
1513
1523
|
} catch (e) {
|
|
1514
1524
|
if (e instanceof HookEnvironmentContractError) {
|
|
1515
1525
|
const detail = String(e.message || e).slice(0, 200);
|
|
@@ -3506,6 +3516,11 @@ export async function spawnInstanceAsync(root, agent, o = {}) {
|
|
|
3506
3516
|
}
|
|
3507
3517
|
return step.value;
|
|
3508
3518
|
}
|
|
3519
|
+
/** The command a spawn's answer gives to attach to its instance: the tmux session of its window when
|
|
3520
|
+
* it was launched (`meta.tmux` then names the socket), else the session surface by home. */
|
|
3521
|
+
function spawnAttach(meta, launched) {
|
|
3522
|
+
return launched ? `tmux -S ${shellWord(meta.tmux.socket)} attach -t ${shellWord(meta.tmux.session)}` : `oats session attach --home ${shellWord(meta.home)}`;
|
|
3523
|
+
}
|
|
3509
3524
|
/** The producer sets this only when dispatched effects or their compensation
|
|
3510
3525
|
* cannot be confirmed. A diagnostic's wording or home path is not evidence. */
|
|
3511
3526
|
function unconfirmedSpawn(error) {
|
|
@@ -3629,7 +3644,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
3629
3644
|
if (prior.spawnCompleted !== true) throw unconfirmedSpawn(Object.assign(oatsError("E_SPAWN_INCOMPLETE", `${prior.instance} was created for this key but its spawn did not complete (launch or lineage unfinished); inspect it with oats session inspect --home ${prior.home} — do not spawn again`), { instance: prior.instance, home: prior.home, launched: prior.launched === true ? "unknown" : false }));
|
|
3630
3645
|
// The receipt's warnings that are facts of the composition (a hook event this kernel ignores),
|
|
3631
3646
|
// from the home's module copies: nothing runs again, and the captured composition is unchanged.
|
|
3632
|
-
return { ...prior, background: readInstanceBackground(prior.home), replayed: true, launch: undefined, command: undefined, wake: prior.wake ?? { requested: null, saved: null, error: null }, warnings: replayedContractWarnings(prior.home) };
|
|
3647
|
+
return { ...prior, background: readInstanceBackground(prior.home), replayed: true, launch: undefined, command: undefined, attach: spawnAttach(prior, prior.launched === true && !!prior.tmux?.socket), wake: prior.wake ?? { requested: null, saved: null, error: null }, warnings: replayedContractWarnings(prior.home) };
|
|
3633
3648
|
}
|
|
3634
3649
|
}
|
|
3635
3650
|
|
|
@@ -4192,9 +4207,19 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4192
4207
|
if (o.prepared) {
|
|
4193
4208
|
// The soul's AGENTS.md is the body materialize composes onto: the capability
|
|
4194
4209
|
// injects in the resolution's instruction order, then the kernel's blocks.
|
|
4210
|
+
// The copy is the one wait between the home's creation and its first hook. A SIGINT, SIGTERM
|
|
4211
|
+
// or SIGHUP that arrives during it is held (signalGuard, as while the worktree hooks run): the
|
|
4212
|
+
// process is not ended with a home that has no record. The copy ends, by itself or because the
|
|
4213
|
+
// signal closed what it read from, and the home is removed as for any failure here.
|
|
4214
|
+
const copyGuard = signalGuard();
|
|
4195
4215
|
try {
|
|
4196
4216
|
const kernelBlocks = composition.blocks.filter((b) => !b.source.startsWith("capability:"));
|
|
4197
|
-
materializeOutcome = yield () => (o.materialize ?? materializePreparedDefault)({ ...o.prepared, soulAgentsMd: composition.body, blocks: kernelBlocks, soulDir }, home);
|
|
4217
|
+
try { materializeOutcome = yield () => (o.materialize ?? materializePreparedDefault)({ ...o.prepared, soulAgentsMd: composition.body, blocks: kernelBlocks, soulDir }, home); }
|
|
4218
|
+
catch (e) { if (!copyGuard.signal) throw e; }
|
|
4219
|
+
if (copyGuard.signal) {
|
|
4220
|
+
throw Object.assign(oatsError("E_INTERRUPTED", `the spawn was interrupted by ${copyGuard.signal} while its capabilities were copied into the home; no hook had run`),
|
|
4221
|
+
{ exitStatus: interruptExitStatus(copyGuard.signal), details: { signal: copyGuard.signal, hooks: [] } });
|
|
4222
|
+
}
|
|
4198
4223
|
const rows = (typeof o.prepared.toCapabilityRows === "function" ? o.prepared.toCapabilityRows : toCapabilityRows)(o.prepared.resolution, home);
|
|
4199
4224
|
if (!Array.isArray(rows)) throw new Error("toCapabilityRows returned no rows");
|
|
4200
4225
|
for (const row of rows) row.hooks = materializedHookCommands(row, home);
|
|
@@ -4243,6 +4268,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4243
4268
|
}
|
|
4244
4269
|
}
|
|
4245
4270
|
} catch (e) { throw rollbackEmptyOrPreparedHome(e); }
|
|
4271
|
+
finally { copyGuard.restore(); }
|
|
4246
4272
|
}
|
|
4247
4273
|
initializeNativeHistory(home);
|
|
4248
4274
|
|
|
@@ -4366,9 +4392,21 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4366
4392
|
if (work === "worktree") {
|
|
4367
4393
|
branch = plannedBranch;
|
|
4368
4394
|
const wt = join(home, "work");
|
|
4395
|
+
// The checkout writes the tree's files: no filter driver the repository's configuration
|
|
4396
|
+
// defines runs in it, nor the file monitor it names (lib/instance-git.mjs workTreeOverrides).
|
|
4397
|
+
// This Git reads the operator's own configuration, so a driver of a name that configuration
|
|
4398
|
+
// defines too runs with the operator's command. Nothing outside the home exists yet, so
|
|
4399
|
+
// removing the scaffold is the whole rollback.
|
|
4400
|
+
const filters = workTreeOverrides(["-C", repoAbs], process.env);
|
|
4401
|
+
if (!filters.ok) {
|
|
4402
|
+
let removal = " — spawn rolled back", removalFailed = false;
|
|
4403
|
+
try { rmSync(home, { recursive: true, force: true }); } catch (e) { removalFailed = true; removal = ` — rollback INCOMPLETE, remove ${home} manually: ${e.message}`; }
|
|
4404
|
+
const error = oatsError("E_WORK_INSPECTION_FAILED", `could not make the instance worktree: git worktree add was not run in ${repoAbs}: ${filters.err}${removal}`);
|
|
4405
|
+
throw removalFailed ? unconfirmedSpawn(error) : error;
|
|
4406
|
+
}
|
|
4369
4407
|
let added = false;
|
|
4370
4408
|
try {
|
|
4371
|
-
execFileSync("git", ["-C", repoAbs, "worktree", "add", wt, "-b", branch, plannedBase.oid],
|
|
4409
|
+
execFileSync("git", [...filters.args, "-C", repoAbs, "worktree", "add", wt, "-b", branch, plannedBase.oid],
|
|
4372
4410
|
{ stdio: ["ignore", "pipe", "pipe"] });
|
|
4373
4411
|
added = true;
|
|
4374
4412
|
// Git registers a canonical path. Retain it now: compensation hooks can
|
|
@@ -4456,11 +4494,69 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4456
4494
|
// soul), never the swappable agents/<name>/soul pointer: a provider that pins a
|
|
4457
4495
|
// path must pin this instance's content, and OATS_SOUL_ID is what it keys on.
|
|
4458
4496
|
const harnessExecutableHanded = harnessExecutableEnv(bin, !!(executable.lookup || launchConfig?.executable?.includes("/")));
|
|
4459
|
-
|
|
4497
|
+
// What the record says of the workspace and the teams, for the final record and, before it, for
|
|
4498
|
+
// the marker written ahead of the spawn hooks: a retire's hooks read both from the record.
|
|
4499
|
+
// M5/3a: the workspace's name and the deployment directory are recorded, so a home
|
|
4500
|
+
// answers them (inspect/operation run --home, OATS_WORKSPACE_NAME) without discovery.
|
|
4501
|
+
// Team model v2: the teams at spawn, exactly as the providers received them (OATS_TEAMS: mapped
|
|
4502
|
+
// rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
|
|
4503
|
+
// capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
|
|
4504
|
+
// what they fall back to when the workspace cannot answer.
|
|
4505
|
+
const workspaceRecord = o.prepared ? {
|
|
4506
|
+
workspace: { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) },
|
|
4507
|
+
teams: envRows(o.prepared.resolution.teams ?? []),
|
|
4508
|
+
defaultTeam: structuredClone(o.prepared.resolution.defaultTeam ?? null),
|
|
4509
|
+
} : {};
|
|
4510
|
+
// #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
|
|
4511
|
+
// in-progress marker that covers a parent killed while its spawn or worktree hooks run.
|
|
4512
|
+
const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
|
|
4513
|
+
let worktreeRun = null, treeGuard = null, inProgressMarker = false;
|
|
4514
|
+
let hookRes = null;
|
|
4515
|
+
const inProgressStartedAt = new Date().toISOString();
|
|
4516
|
+
/** `event`: the hooks the spawn is about to run, or runs, when it writes the marker ("spawn",
|
|
4517
|
+
* "worktree"). Until the spawn hooks have answered, each capability with a spawn hook may have
|
|
4518
|
+
* started: the retire hook of every one of them is owed, and there is no receipt of theirs yet. */
|
|
4519
|
+
const writeSpawnInProgressMarker = (event, hook) => {
|
|
4520
|
+
const attempted = hookRes ? hookRes.order || [] : resolvedCfg.capabilities.filter((c) => c.hooks?.spawn).map((c) => c.id);
|
|
4521
|
+
const retireOwed = new Set(attempted.filter((id) => resolvedCfg.capabilities.find((c) => c.id === id)?.hooks?.retire));
|
|
4522
|
+
// Never through a home a hook put in its place.
|
|
4523
|
+
if (work === "directory") assertDirectoryHome(home, homeReal);
|
|
4524
|
+
writeQuarantineMarker(home, buildQuarantineMarker({
|
|
4525
|
+
instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId,
|
|
4526
|
+
incomplete: [event === "worktree" ? "the spawn is running its worktree hooks; until its process is gone this home is a spawn in progress" : "the spawn has not written its record; until its process is gone this home is a spawn in progress"],
|
|
4527
|
+
failed: [{ capability: "oats.kernel", event }],
|
|
4528
|
+
outstandingHooks: retireOwed, outstandingGit: new Set(work !== "worktree" ? [] : branch ? ["worktree", "branch"] : ["worktree"]),
|
|
4529
|
+
repoAbs, work, branch, resolvedCfg, hookMeta: hookRes?.meta || {}, launched: false, tmux: { session, window: instance },
|
|
4530
|
+
reason: event === "worktree" ? "spawn interrupted while its worktree hooks ran" : "spawn interrupted before its record was written",
|
|
4531
|
+
workspaceRecord,
|
|
4532
|
+
}), { inProgress: { ...selfIdentity(), startedAt: inProgressStartedAt, branch, baseOid: plannedBase?.oid, ...hook } }, work === "directory" ? 0o600 : undefined);
|
|
4533
|
+
inProgressMarker = true;
|
|
4534
|
+
};
|
|
4535
|
+
// The spawn's commit point for the marker: the final instance.json is written. The marker goes
|
|
4536
|
+
// before the final baseline is taken: the baseline digests the home, and a home digested with
|
|
4537
|
+
// the marker in it would read as changed since spawn at every retire.
|
|
4538
|
+
const clearSpawnInProgressMarker = () => {
|
|
4539
|
+
if (!inProgressMarker) return;
|
|
4540
|
+
rmSync(join(home, ".oats-rollback-incomplete.json"), { force: true });
|
|
4541
|
+
inProgressMarker = false;
|
|
4542
|
+
};
|
|
4543
|
+
// Write-ahead: what a retire needs to run the retire hooks (the repository they come from, the
|
|
4544
|
+
// capabilities, the soul) is on disk before the first spawn hook runs. Until the final record
|
|
4545
|
+
// is written, instance.json is the stub lib/materialize.mjs wrote, which names none of it: a
|
|
4546
|
+
// spawn killed in between (SIGKILL, a container stop) would leave a home whose retire could run
|
|
4547
|
+
// no hook, with what its spawn hooks registered outside the home still there. Written only when
|
|
4548
|
+
// a spawn hook is about to run whose capability has a retire hook: nothing else is owed yet.
|
|
4549
|
+
if (resolvedCfg.capabilities.some((c) => c.hooks?.spawn && c.hooks?.retire)) writeSpawnInProgressMarker("spawn", {});
|
|
4550
|
+
hookRes = runLifecycleHooks("spawn", {
|
|
4460
4551
|
home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs,
|
|
4461
4552
|
workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg,
|
|
4462
4553
|
extraEnv: { OATS_TASK: task, OATS_REPO: repoAbs, OATS_BRANCH: branch || "", OATS_WORK: work, OATS_HARNESS: harness, ...harnessExecutableHanded, OATS_RUNTIME: harness, OATS_KIND: agent.kind || "persistent", ...(triggerEventFile ? { OATS_TRIGGER_EVENT_FILE: triggerEventFile } : {}), ...(spawnedBy ? { OATS_SPAWNER_HOME: spawnedBy.home } : {}) },
|
|
4463
4554
|
});
|
|
4555
|
+
// The spawn hooks' receipt (their `meta`), on disk as soon as there is one: a retire after a kill
|
|
4556
|
+
// from here on hands it to the retire hooks.
|
|
4557
|
+
if (inProgressMarker) {
|
|
4558
|
+
try { writeSpawnInProgressMarker("spawn", {}); } catch { /* the marker written before the hooks stands: it owes the same retire hooks, without the receipt */ }
|
|
4559
|
+
}
|
|
4464
4560
|
warnings.push(...hookRes.warnings);
|
|
4465
4561
|
if (kernelNode().warning) warnings.push(kernelNode().warning);
|
|
4466
4562
|
// Which capability hooks RAN (in order) and how each ended — recorded on the
|
|
@@ -4490,32 +4586,6 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4490
4586
|
throw new Error(`relation "parent": failed to re-point anchor "${relativeTo}" (${e.message})`);
|
|
4491
4587
|
}
|
|
4492
4588
|
};
|
|
4493
|
-
// #796: the `worktree` hooks this spawn fires (work: worktree only), their run, and the
|
|
4494
|
-
// in-progress marker that covers a parent killed while they run.
|
|
4495
|
-
const treeHooks = work === "worktree" ? worktreeHooksOf(resolvedCfg.capabilities) : [];
|
|
4496
|
-
let worktreeRun = null, treeGuard = null, inProgressMarker = false;
|
|
4497
|
-
const writeSpawnInProgressMarker = (hook) => {
|
|
4498
|
-
const retireOwed = new Set((hookRes.order || []).filter((id) => resolvedCfg.capabilities.find((c) => c.id === id)?.hooks?.retire));
|
|
4499
|
-
writeQuarantineMarker(home, buildQuarantineMarker({
|
|
4500
|
-
instance, agent, soulDir: homeSoulTarget, soulId: preparedSoulId,
|
|
4501
|
-
incomplete: ["the spawn is running its worktree hooks; until its process is gone this home is a spawn in progress"],
|
|
4502
|
-
failed: [{ capability: "oats.kernel", event: "worktree" }],
|
|
4503
|
-
outstandingHooks: retireOwed, outstandingGit: new Set(branch ? ["worktree", "branch"] : ["worktree"]),
|
|
4504
|
-
repoAbs, work, branch, resolvedCfg, hookMeta: hookRes.meta || {}, launched: false, tmux: { session, window: instance },
|
|
4505
|
-
reason: "spawn interrupted while its worktree hooks ran",
|
|
4506
|
-
}), { inProgress: { ...selfIdentity(), startedAt: inProgressStartedAt, branch, baseOid: plannedBase.oid, ...hook } });
|
|
4507
|
-
if (!inProgressMarker) {
|
|
4508
|
-
inProgressMarker = true;
|
|
4509
|
-
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: { session, window: instance } });
|
|
4510
|
-
}
|
|
4511
|
-
};
|
|
4512
|
-
const inProgressStartedAt = new Date().toISOString();
|
|
4513
|
-
// The spawn's commit point for the marker: the final instance.json and baseline are written.
|
|
4514
|
-
const clearSpawnInProgressMarker = () => {
|
|
4515
|
-
if (!inProgressMarker) return;
|
|
4516
|
-
rmSync(join(home, ".oats-rollback-incomplete.json"), { force: true });
|
|
4517
|
-
inProgressMarker = false;
|
|
4518
|
-
};
|
|
4519
4589
|
let promptDispatched = false, promptTarget, promptResult, promptStartId;
|
|
4520
4590
|
let windowMayExist = false;
|
|
4521
4591
|
let spawnTmux;
|
|
@@ -4688,7 +4758,8 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4688
4758
|
// The marker names this process by pid and start; one whose start cannot be read could not be told
|
|
4689
4759
|
// apart from a dead one after a kill, so the spawn does not run its worktree hooks without it.
|
|
4690
4760
|
if (!processStartToken(process.pid)) throw oatsError("E_SPAWN_FAILED", `this process's start time cannot be read, so a spawn killed while its worktree hooks ran could not be recovered safely; no worktree hook ran`);
|
|
4691
|
-
writeSpawnInProgressMarker({});
|
|
4761
|
+
writeSpawnInProgressMarker("worktree", {});
|
|
4762
|
+
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: { session, window: instance } });
|
|
4692
4763
|
treeGuard = signalGuard();
|
|
4693
4764
|
const treeEnv = {
|
|
4694
4765
|
OATS_TREE: tree, OATS_TREE_CLONE: cloneReal, OATS_TREE_REMOTE: originRemoteOf(cloneReal),
|
|
@@ -4698,7 +4769,7 @@ function* spawnBody(root, agent, o = {}) {
|
|
|
4698
4769
|
worktreeRun = yield () => runWorktreeHooks(treeHooks, {
|
|
4699
4770
|
envFor: (cap) => lifecycleHookEnv("worktree", cap, { home, instance, agentName: agent.name, soulDir: homeSoulTarget, soulId: preparedSoulId, contextDir: repoAbs, workspaceDir: workspaceOf(root), rootDir: root, resolved: resolvedCfg, priorMeta: hookRes.meta || {}, extraEnv: treeEnv }),
|
|
4700
4771
|
cwd: tree, home, purpose: "", guard: treeGuard,
|
|
4701
|
-
onStart: ({ pgid, hookStart }) => writeSpawnInProgressMarker({ hookPgid: pgid, hookStart }),
|
|
4772
|
+
onStart: ({ pgid, hookStart }) => writeSpawnInProgressMarker("worktree", { hookPgid: pgid, hookStart }),
|
|
4702
4773
|
});
|
|
4703
4774
|
warnings.push(...worktreeRun.warnings);
|
|
4704
4775
|
if (worktreeRun.interrupted) {
|
|
@@ -4871,15 +4942,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4871
4942
|
// digests) in instance.json before this metadata is assembled — carry them.
|
|
4872
4943
|
if (o.prepared) {
|
|
4873
4944
|
try { const prior = JSON.parse(readFileSync(join(home, "instance.json"), "utf8")); if (prior.modules) meta.modules = prior.modules; if (prior.providers) meta.providers = prior.providers; } catch { /* materialize wrote it; absent means nothing to carry */ }
|
|
4874
|
-
|
|
4875
|
-
// answers them (inspect/operation run --home, OATS_WORKSPACE_NAME) without discovery.
|
|
4876
|
-
meta.workspace = { key: o.prepared.discovery?.key ?? null, name: o.prepared.discovery?.workspace?.name ?? null, deployment: o.prepared.deployment ?? null, commit: o.prepared.discovery?.commit ?? null, resolution: o.prepared.resolution.revision, standalone: o.prepared.discovery?.standalone === true, soul: { id: preparedSoulIdOf(o.prepared.soulEntry), repoKey: o.prepared.soulEntry.repoKey, commit: o.prepared.soulEntry.commit, ...(typeof o.prepared.soulEntry.package === "string" ? { name: o.prepared.soulEntry.name, qualifiedName: o.prepared.soulEntry.qualifiedName, package: { id: o.prepared.soulEntry.package, version: o.prepared.soulEntry.version, commit: o.prepared.soulEntry.commit, digest: o.prepared.soulEntry.digest, path: o.prepared.soulEntry.path } } : {}) }, layers: layerRows(o.prepared.resolution) };
|
|
4877
|
-
// Team model v2: the teams at spawn, exactly as the providers received them (OATS_TEAMS: mapped
|
|
4878
|
-
// rows only) and the default, recorded as EVIDENCE beside `providers` (never inside that
|
|
4879
|
-
// capability-keyed map). A home's hooks and operations get the LIVE set (liveTeams); this is
|
|
4880
|
-
// what they fall back to when the workspace cannot answer.
|
|
4881
|
-
meta.teams = envRows(o.prepared.resolution.teams ?? []);
|
|
4882
|
-
meta.defaultTeam = structuredClone(o.prepared.resolution.defaultTeam ?? null);
|
|
4945
|
+
Object.assign(meta, workspaceRecord);
|
|
4883
4946
|
}
|
|
4884
4947
|
const spawnWarnings = warnings;
|
|
4885
4948
|
// Feature instance-same-work: bound to the parent the home records, written before the launch so that
|
|
@@ -4958,8 +5021,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
4958
5021
|
// Commit the final child metadata and its independent byte authority before
|
|
4959
5022
|
// the managed harness can write. No child-home transition follows launch.
|
|
4960
5023
|
writeHomeRecord(home, meta);
|
|
4961
|
-
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
|
|
4962
5024
|
clearSpawnInProgressMarker();
|
|
5025
|
+
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: true, tmux: meta.tmux });
|
|
4963
5026
|
// The first start's launch environment (lib/start-env.mjs), after the baseline, as a start records its own.
|
|
4964
5027
|
const refs = launchEnvRefs(recipe, process.env);
|
|
4965
5028
|
recordStartEnv(home, promptStartId, refs.map((r) => r.source), Object.fromEntries(refs.map((r) => [r.source, r.value])));
|
|
@@ -5001,8 +5064,8 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
5001
5064
|
} else {
|
|
5002
5065
|
meta.launched = false;
|
|
5003
5066
|
writeHomeRecord(home, meta);
|
|
5004
|
-
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
|
|
5005
5067
|
clearSpawnInProgressMarker();
|
|
5068
|
+
writeRetirementBaseline(home, join(home, "work"), work, resolvedCfg.capabilities, { launched: false, tmux: meta.tmux });
|
|
5006
5069
|
}
|
|
5007
5070
|
|
|
5008
5071
|
// Ordinary launches and scaffolds commit here; launches that engage the
|
|
@@ -5018,7 +5081,7 @@ ${task.trim() ? `\n## Task\n\n${task.trim()}\n` : "\nNo task was provided at spa
|
|
|
5018
5081
|
meta.spawnCompleted = true;
|
|
5019
5082
|
writeHomeRecord(home, meta); // a kernel-owned field: the baseline fingerprint ignores it
|
|
5020
5083
|
}
|
|
5021
|
-
return deliver({ ...meta, background, ...(backgroundFrom ? { backgroundFrom } : {}), ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach:
|
|
5084
|
+
return deliver({ ...meta, background, ...(backgroundFrom ? { backgroundFrom } : {}), ...(o.expectDecision !== undefined ? { replayed: false } : {}), ...(worktreeRun ? { worktreeHooks: worktreeRun.receipt } : {}), launch: redactLaunchRecipe(recipe), command: redactLaunchCommand(cmdline), attach: spawnAttach(meta, launch), warnings: spawnWarnings.length ? spawnWarnings : undefined, ...(naming ? { naming } : {}) });
|
|
5022
5085
|
} catch (error) {
|
|
5023
5086
|
if (promptDispatched) {
|
|
5024
5087
|
// Once a launch that engages the confirmation was dispatched, uncertainty retains all effects.
|
|
@@ -5233,7 +5296,7 @@ function deleteBranchAsCreated(run, repoAbs, branch, oid) {
|
|
|
5233
5296
|
/** The quarantine marker (`.oats-rollback-incomplete.json`) a rollback that cannot finish leaves:
|
|
5234
5297
|
* the cleanup descriptor a retry consumes (usableCleanupDescriptor). One builder for the
|
|
5235
5298
|
* rollback below and for a spawn's in-progress marker (#796), which adds `inProgress`. */
|
|
5236
|
-
function buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation = false, orphanedWork = false }) {
|
|
5299
|
+
function buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, failed, outstandingHooks, outstandingGit, repoAbs, work, branch, resolvedCfg, hookMeta, compensationMeta, launched, tmux, reason, directoryPreservation = false, orphanedWork = false, workspaceRecord = {} }) {
|
|
5237
5300
|
return {
|
|
5238
5301
|
// `reason` is optional and DEFAULTS to the spawn wording, so every existing
|
|
5239
5302
|
// caller is byte-identical; only a caller that supplies one differs. The
|
|
@@ -5261,6 +5324,9 @@ function buildQuarantineMarker({ instance, agent, soulDir, soulId, incomplete, f
|
|
|
5261
5324
|
trust: cap.trust, executable: cap.executable,
|
|
5262
5325
|
})),
|
|
5263
5326
|
capabilityMeta: hookMeta || {},
|
|
5327
|
+
// A spawn's in-progress marker: the record's `workspace`, `teams` and `defaultTeam`, which
|
|
5328
|
+
// the retire hooks' team and workspace environment is read from and the stub does not hold.
|
|
5329
|
+
...workspaceRecord,
|
|
5264
5330
|
},
|
|
5265
5331
|
createdAt: new Date().toISOString(),
|
|
5266
5332
|
};
|
|
@@ -6412,7 +6478,11 @@ function recordedSessionAbsence(home, meta, io) {
|
|
|
6412
6478
|
* (`instanceSessionTarget`), bounded and never escalated: a harness still
|
|
6413
6479
|
* there after the grace is reported still running, nothing is killed harder.
|
|
6414
6480
|
* A no-launch or already-idle instance is a no-op that says so. A missing socket
|
|
6415
|
-
* file is idle only when no process works in the home (#624).
|
|
6481
|
+
* file is idle only when no process works in the home (#624).
|
|
6482
|
+
* `withHost: true` is a stop with the host (`oats host run` when the host stops,
|
|
6483
|
+
* lib/host-run.mjs): the same stop, whose record asks for a resume and is written
|
|
6484
|
+
* before the harness is signalled (recordStop), so that the home reads `lost` and
|
|
6485
|
+
* the next start's sweep brings it back, also when the host is killed mid-stop. */
|
|
6416
6486
|
export function stopInstanceSession(home, o = {}) {
|
|
6417
6487
|
if (typeof home !== "string" || !isAbsolute(home)) throw oatsError("E_BAD_ARGS", "session stop needs an absolute instance home");
|
|
6418
6488
|
requireStopGrace(o.graceMs);
|
|
@@ -6442,9 +6512,11 @@ function stopStartId(home) {
|
|
|
6442
6512
|
* receipt `.oats-stop.json`, `stop` being what was done to the harness (stopHarness's receipt, or
|
|
6443
6513
|
* null when nothing was signalled). Its `startId` names the start, so the home reads `stopped`
|
|
6444
6514
|
* and no resume brings that start back. The one writer of the receipt: a stop, an idle stop, and
|
|
6445
|
-
* a retire and a restart before they end the session. Throws what the write throws.
|
|
6446
|
-
|
|
6447
|
-
|
|
6515
|
+
* a retire and a restart before they end the session. Throws what the write throws.
|
|
6516
|
+
* `withHost`: a stop with the host. Its record says `resume: true` and `reason: "host-stop"`, and
|
|
6517
|
+
* the home reads `lost` (lib/session-end.mjs): a resume brings that start back. */
|
|
6518
|
+
function recordStop(home, stop, { withHost = false } = {}) {
|
|
6519
|
+
writeJsonAtomic(join(home, STOP_RECEIPT_FILE), { instance: basename(home), at: new Date().toISOString(), stop, retained: ["home", "work", "transcript", "launch"], startId: stopStartId(home), ...(withHost ? { resume: true, reason: HOST_STOP_REASON } : {}) });
|
|
6448
6520
|
}
|
|
6449
6521
|
/** An explicit stop of a launched home found idle whose session reads `lost` (the host went down or
|
|
6450
6522
|
* its tmux server died; or a home from before 0.69 whose harness ended): nothing is signalled, but
|
|
@@ -6457,13 +6529,14 @@ function recordIdleStop(realHome) {
|
|
|
6457
6529
|
catch { /* the idle stop's answer is unchanged: see above */ }
|
|
6458
6530
|
}
|
|
6459
6531
|
/** The stop of stopInstanceSession, under the home's claim. The pending self-retire marker is read
|
|
6460
|
-
* here, under it: a `--self` retire writes the marker while it holds the claim.
|
|
6532
|
+
* here, under it: a `--self` retire writes the marker while it holds the claim. A marker whose
|
|
6533
|
+
* completion is gone refuses nothing (retireCarried). */
|
|
6461
6534
|
function stopSessionClaimed(home, o) {
|
|
6462
6535
|
const realHome = realPathOrNearest(home);
|
|
6463
6536
|
// `signalling`: the stop reached the step that signals the harness; `receipt`: that step's answer.
|
|
6464
6537
|
let signalling = false, receipt;
|
|
6465
6538
|
try {
|
|
6466
|
-
if (
|
|
6539
|
+
if (retireCarried(realHome)) throw oatsError("E_INSTANCE_RETIRING", `${basename(realHome)} is being retired; nothing was stopped`);
|
|
6467
6540
|
const s = instanceSessionTarget(realHome);
|
|
6468
6541
|
if (!s.target) return { home: s.home, backend: null, stopped: false, alreadyIdle: true, state: "not-launched", receipt: null };
|
|
6469
6542
|
let before;
|
|
@@ -6473,13 +6546,20 @@ function stopSessionClaimed(home, o) {
|
|
|
6473
6546
|
if (lost.gone) before = { present: false, state: "stopped" };
|
|
6474
6547
|
else throw oatsError("E_SESSION_UNAVAILABLE", `cannot establish whether ${basename(realHome)} is running, so nothing was stopped: ${lost.why ?? e.message}`);
|
|
6475
6548
|
}
|
|
6549
|
+
const withHost = o.withHost === true;
|
|
6476
6550
|
if (!before.present || before.state === "shell" || before.state === "stopped") {
|
|
6477
|
-
|
|
6551
|
+
// A stop with the host records nothing of a home it finds idle: one that reads `lost` stays
|
|
6552
|
+
// lost, for the sweep.
|
|
6553
|
+
if (!withHost) recordIdleStop(realHome);
|
|
6478
6554
|
return { home: s.home, backend: s.target.backend, stopped: false, alreadyIdle: true, state: before.state, receipt: null };
|
|
6479
6555
|
}
|
|
6556
|
+
// A stop with the host is recorded before the signal: a host killed while the harness ends
|
|
6557
|
+
// leaves a home that reads `lost`, never `exited`. A record that cannot be written stops
|
|
6558
|
+
// nothing: the harness is then ended by the host, with no record, which reads `lost` too.
|
|
6559
|
+
if (withHost) recordStop(realHome, null, { withHost });
|
|
6480
6560
|
signalling = true;
|
|
6481
6561
|
receipt = stopHarness(s.target, { graceMs: o.graceMs ?? 20000, kill: o.io?.kill, sleep: o.io?.sleep });
|
|
6482
|
-
recordStop(realHome, receipt);
|
|
6562
|
+
recordStop(realHome, receipt, { withHost });
|
|
6483
6563
|
appendEvent(realHome, { kind: receipt.exited ? "stopped" : "stop-refused", data: { signal: receipt.signal, waitedMs: receipt.waitedMs, stillRunning: receipt.stillRunning ?? [], state: receipt.state } });
|
|
6484
6564
|
if (!receipt.exited) throw Object.assign(oatsError("E_SESSION_STOP_FAILED", `${basename(realHome)} was asked to stop (${receipt.signal} to ${receipt.requested.map((r) => `${r.comm} pid ${r.pid}`).join(", ")}) and is still running after ${receipt.waitedMs} ms; nothing was escalated`), { receipt });
|
|
6485
6565
|
return { home: s.home, backend: s.target.backend, stopped: true, alreadyIdle: false, state: receipt.state, receipt };
|
|
@@ -7041,7 +7121,14 @@ function startSession(home, o) {
|
|
|
7041
7121
|
if (existsSync(join(realHome, ".oats-rollback-incomplete.json"))) throw oatsError("E_INSTANCE_RETIRING", `${realHome} is a quarantined home whose cleanup is incomplete; finish its retirement (oats retire) before starting anything there`);
|
|
7042
7122
|
// A self-retirement leaves this marker while its detached teardown runs:
|
|
7043
7123
|
// the home is about to disappear, so nothing is relaunched into it.
|
|
7044
|
-
|
|
7124
|
+
// A marker whose completion is gone (the row's `retire` reads `interrupted`) promises a retire
|
|
7125
|
+
// that nothing carries out. The home is owed it, and a start would bring back a home that
|
|
7126
|
+
// retire may have half taken down: the refusal names the retire that finishes it.
|
|
7127
|
+
if (existsSync(retirePendingMarkerPath(realHome))) {
|
|
7128
|
+
throw oatsError("E_INSTANCE_RETIRING", owedRetire(realHome)?.state === "interrupted"
|
|
7129
|
+
? `${basename(realHome)} is owed a retire (its retire was interrupted): finish it with \`oats retire ${basename(realHome)} --home ${realHome}\`; nothing was started`
|
|
7130
|
+
: `${basename(realHome)} is being retired (${retirePendingMarkerPath(realHome)} is present); nothing was started`);
|
|
7131
|
+
}
|
|
7045
7132
|
// A start that leaves the server the home recorded says so: one line per move (see the docs'
|
|
7046
7133
|
// "Existing instances"), in the answer and as a launch-warning event.
|
|
7047
7134
|
const movedWarnings = [];
|
|
@@ -9148,7 +9235,7 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
|
|
|
9148
9235
|
};
|
|
9149
9236
|
// The completion is told who scheduled it: this process, by pid and by the start token its
|
|
9150
9237
|
// holding of the home's claim records (lib/claim.mjs takes both from the same reading). It is
|
|
9151
|
-
// told in its environment and nowhere else: the marker
|
|
9238
|
+
// told in its environment and nowhere else: the marker does not record it, and the completion
|
|
9152
9239
|
// compares the claim against what it was given, never against what it reads later beside the
|
|
9153
9240
|
// home (completeDeferredRetirement).
|
|
9154
9241
|
const requestedByStart = processStartToken(process.pid);
|
|
@@ -9185,10 +9272,11 @@ function scheduleDeferredSelfRetirement(root, found, name, o, session) {
|
|
|
9185
9272
|
} catch { /* the marker alone then shows RETIRING; status names its age */ }
|
|
9186
9273
|
});
|
|
9187
9274
|
child.unref();
|
|
9188
|
-
// The marker names its completion (pid
|
|
9189
|
-
// while that process lives, any other retire of this home is
|
|
9275
|
+
// The marker names its completion (pid, start time and boot; the start and the boot are null
|
|
9276
|
+
// when they cannot be read): while that process lives, any other retire of this home is
|
|
9277
|
+
// refused (refusePendingCompletion).
|
|
9190
9278
|
const completionStart = processStartToken(child.pid);
|
|
9191
|
-
writeFileSync(marker, JSON.stringify({ ...intent, completionPid: child.pid, completionStart }, null, 2) + "\n");
|
|
9279
|
+
writeFileSync(marker, JSON.stringify({ ...intent, completionPid: child.pid, completionStart, completionBoot: thisBoot() }, null, 2) + "\n");
|
|
9192
9280
|
wroteMarker = true;
|
|
9193
9281
|
// The marker promises a completion that is on its way. One that has ended by now is not: it
|
|
9194
9282
|
// looked for its marker before this call wrote one, and nothing would ever remove it. So the
|
|
@@ -9329,7 +9417,7 @@ export function completeDeferredRetirement(intentOrMarkerPath, opts = {}) {
|
|
|
9329
9417
|
const path = retirePendingMarkerPath(home), marker = readJsonOrUndefined(path);
|
|
9330
9418
|
if (!isPlainObject(marker) || typeof intent.requestedAt !== "string" || marker.requestedAt !== intent.requestedAt) return false;
|
|
9331
9419
|
const pid = marker.completionPid;
|
|
9332
|
-
if (Number.isSafeInteger(pid) && pid !== process.pid &&
|
|
9420
|
+
if (Number.isSafeInteger(pid) && pid !== process.pid && completionLiveness(marker).state !== "gone") return false;
|
|
9333
9421
|
try { rmSync(path); return true; }
|
|
9334
9422
|
catch (e) { if (e?.code !== "ENOENT") console.error(`deferred retirement: cannot remove ${path}: ${e.message}`); return false; }
|
|
9335
9423
|
};
|
|
@@ -9495,6 +9583,31 @@ function retireRetryPath(home) {
|
|
|
9495
9583
|
* the answer is that it is running, and neither is read. A symbol, so no caller can set it from
|
|
9496
9584
|
* parsed arguments or JSON. */
|
|
9497
9585
|
export const RETIRE_UNDER_CLAIM = Symbol("oats.retireUnderClaim");
|
|
9586
|
+
/** The one internal option that hands a retire's steps the claim it runs under (claimHomeFor's
|
|
9587
|
+
* holding): where it records the retire hooks that ended, and what the gone holder it took over
|
|
9588
|
+
* from had recorded (finishedRetireHooks). A symbol, so no caller can set it. */
|
|
9589
|
+
const RETIRE_CLAIM = Symbol("oats.retireClaim");
|
|
9590
|
+
/** The retire hooks a gone retire had finished, as the claim it left says (`tookOver`: its record,
|
|
9591
|
+
* or null) → Map of capability → the meta that hook answered (undefined when it answered none).
|
|
9592
|
+
* A retire writes the list as it goes (`retireHooks: [{ capability, meta? }]`, with
|
|
9593
|
+
* `retireHooksFor`, the incarnation of the home), and the retire that takes its claim over does
|
|
9594
|
+
* not run those hooks again. The claim is a file others can write, read back as whatever is in
|
|
9595
|
+
* it: the list counts only when the record is a retire's and names this incarnation (`created`,
|
|
9596
|
+
* the home's `createdAt`), and of it only the entries whose capability has a retire hook in this
|
|
9597
|
+
* home (`caps`) and whose meta is an object or absent. Anything else names no hook, so that hook
|
|
9598
|
+
* runs: a claim without the list (an earlier kernel's) skips nothing. */
|
|
9599
|
+
function finishedRetireHooks(tookOver, created, caps) {
|
|
9600
|
+
const finished = new Map();
|
|
9601
|
+
if (!isPlainObject(tookOver) || claimAction(tookOver) !== "retire" || !Array.isArray(tookOver.retireHooks)) return finished;
|
|
9602
|
+
if (typeof created !== "string" || !created || tookOver.retireHooksFor !== created) return finished;
|
|
9603
|
+
const hooked = new Set(caps.filter((cap) => cap?.hooks?.retire).map((cap) => cap.id));
|
|
9604
|
+
for (const entry of tookOver.retireHooks) {
|
|
9605
|
+
if (!isPlainObject(entry) || !hooked.has(entry.capability)) continue;
|
|
9606
|
+
if (entry.meta !== undefined && !isPlainObject(entry.meta)) continue;
|
|
9607
|
+
finished.set(entry.capability, entry.meta);
|
|
9608
|
+
}
|
|
9609
|
+
return finished;
|
|
9610
|
+
}
|
|
9498
9611
|
/** How many times a retire starts over because the name resolved to another home once it held the
|
|
9499
9612
|
* claim of the first (that one removed, a same-named home of another agent made, in between). */
|
|
9500
9613
|
const RETIRE_CLAIM_RESTARTS = 2;
|
|
@@ -9592,7 +9705,9 @@ export const READ_CLAIM_WHEN_UNWRITABLE = Symbol("oats.readClaimWhenUnwritable")
|
|
|
9592
9705
|
* made as retire makes it for its recovery copies; the claims are private. A directory that
|
|
9593
9706
|
* cannot be made is a claim that cannot be taken: nothing was done (awebai/oats#874).
|
|
9594
9707
|
*
|
|
9595
|
-
* → `{ lock, me }`, the holding
|
|
9708
|
+
* → `{ lock, me, tookOver }`, the holding; `tookOver` is the record of the gone holder whose claim
|
|
9709
|
+
* this one took over, as its file held it, or null when the claim was free (the last one, when
|
|
9710
|
+
* several were taken over in turn). With READ_CLAIM_WHEN_UNWRITABLE, also
|
|
9596
9711
|
* → `{ lock, me: null, unwritable, look }` (awebai/oats#946): the claim could not be written,
|
|
9597
9712
|
* for the system's code `unwritable` (lib/claim.mjs CLAIM_UNWRITABLE_CODES) at one of its
|
|
9598
9713
|
* writes, and it was read where it would have been taken: nobody holds it. Nothing is held,
|
|
@@ -9611,7 +9726,11 @@ export function claimHomeFor(verb, name, home, { waitMs = 0, [READ_CLAIM_WHEN_UN
|
|
|
9611
9726
|
claimWrite(() => mkdirSync(dirname(dirname(lock)), { recursive: true }));
|
|
9612
9727
|
claimWrite(() => mkdirSync(dirname(lock), { recursive: true, mode: 0o700 }));
|
|
9613
9728
|
} catch (e) { throw claimUnavailable(lock, e); }
|
|
9614
|
-
|
|
9729
|
+
// The takeovers of this claim hand over what the gone holder's file held; those of the claims
|
|
9730
|
+
// that serialize a takeover (lib/claim.mjs takeOver) are of other files.
|
|
9731
|
+
let tookOver = null;
|
|
9732
|
+
const me = acquireClaim(lock, { ...refusals, facts: { action: verb }, waitMs, endHolderStep: (holder, at) => { if (at === lock) tookOver = holder; return {}; } });
|
|
9733
|
+
return { lock, me, tookOver };
|
|
9615
9734
|
} catch (refusal) {
|
|
9616
9735
|
const unwritable = readInstead ? unwritableCode(refusal) : undefined;
|
|
9617
9736
|
if (!unwritable) throw refusal;
|
|
@@ -9712,14 +9831,15 @@ function removeAbandonedRetireClaims(root, name) {
|
|
|
9712
9831
|
* (scheduleDeferredSelfRetirement) names it. Nothing refuses when there is no marker, when the
|
|
9713
9832
|
* completion left its outcome (it failed: this retire retries it), when the marker names no
|
|
9714
9833
|
* completion (an older kernel wrote it), when this process is that completion, or when that
|
|
9715
|
-
* process is gone (it died: this retire does what it
|
|
9834
|
+
* process is gone (it died, or the marker was written in another boot: this retire does what it
|
|
9835
|
+
* owed; completionLiveness). */
|
|
9716
9836
|
function refusePendingCompletion(name, home) {
|
|
9717
9837
|
const marker = retirePendingMarkerPath(home);
|
|
9718
9838
|
if (!existsSync(marker) || existsSync(deferredRetireResultPath(home))) return;
|
|
9719
9839
|
const pending = readJsonOrUndefined(marker);
|
|
9720
9840
|
const pid = pending?.completionPid;
|
|
9721
9841
|
if (!Number.isSafeInteger(pid) || pid === process.pid) return;
|
|
9722
|
-
const live =
|
|
9842
|
+
const live = completionLiveness(pending);
|
|
9723
9843
|
if (live.state === "gone") return;
|
|
9724
9844
|
const start = typeof pending.completionStart === "string" ? pending.completionStart : "none";
|
|
9725
9845
|
const details = { instance: name, home, lock: marker, pid, since: pending.requestedAt ?? null, action: "retire" };
|
|
@@ -9783,7 +9903,7 @@ function retireUnderClaim(root, name, o) {
|
|
|
9783
9903
|
// anything of the home. What it returns of the plan binds the retire.
|
|
9784
9904
|
const confirmed = o[RETIRE_UNDER_CLAIM]?.();
|
|
9785
9905
|
const bound = confirmed ? { ...o, ...(confirmed.children ? { children: confirmed.children } : {}), ...(confirmed.plannedExtraWorktrees ? { plannedExtraWorktrees: confirmed.plannedExtraWorktrees } : {}), ...(confirmed.ambiguous ? { ambiguous: confirmed.ambiguous } : {}) } : o;
|
|
9786
|
-
return retireClaimed(root, name, bound, now);
|
|
9906
|
+
return retireClaimed(root, name, { ...bound, [RETIRE_CLAIM]: held }, now);
|
|
9787
9907
|
} finally {
|
|
9788
9908
|
releaseHomeClaim(held);
|
|
9789
9909
|
}
|
|
@@ -9913,7 +10033,7 @@ function retireSteps(root, name, o, found, at) {
|
|
|
9913
10033
|
else markerUnusable = true;
|
|
9914
10034
|
} catch { markerUnusable = true; }
|
|
9915
10035
|
}
|
|
9916
|
-
// #796: a marker a spawn wrote before its worktree hooks (`inProgress`). While that spawn's
|
|
10036
|
+
// #796: a marker a spawn wrote before its spawn or worktree hooks (`inProgress`). While that spawn's
|
|
9917
10037
|
// process is verifiably alive it is a spawn in progress, never a quarantine to retry, --force
|
|
9918
10038
|
// included. Once it is gone, the hook group it left is ended when its leader is alive at the
|
|
9919
10039
|
// recorded start time; a group whose leader is gone is never signalled, only reported (its id may
|
|
@@ -9927,9 +10047,9 @@ function retireSteps(root, name, o, found, at) {
|
|
|
9927
10047
|
if (isPlainObject(rawMarker?.inProgress)) {
|
|
9928
10048
|
const p = rawMarker.inProgress;
|
|
9929
10049
|
const live = processLiveness(p);
|
|
9930
|
-
if (live.state === "alive") throw lifecycleBusy("running", `${name} is still being spawned (pid ${p.pid}, running its
|
|
10050
|
+
if (live.state === "alive") throw lifecycleBusy("running", `${name} is still being spawned (pid ${p.pid}, running its hooks since ${p.startedAt ?? "?"}); nothing was retired`, "wait for the spawn to end, or stop that process, then retire");
|
|
9931
10051
|
if (live.state === "unknown") {
|
|
9932
|
-
if (!o.force) throw lifecycleBusy("unknown", `${name}: whether its spawn (pid ${p.pid}, recorded start ${p.processStart ?? "none"}, running its
|
|
10052
|
+
if (!o.force) throw lifecycleBusy("unknown", `${name}: whether its spawn (pid ${p.pid}, recorded start ${p.processStart ?? "none"}, running its hooks since ${p.startedAt ?? "?"}) still runs cannot be read (${live.reason}); nothing was retired`,
|
|
9933
10053
|
`check that pid by hand, and if it is not that spawn, run \`oats retire ${name} --force\``, { pid: p.pid, processStart: p.processStart ?? null, unknown: live.reason, remedy: `oats retire ${name} --force` });
|
|
9934
10054
|
inProgressUnverified = true;
|
|
9935
10055
|
spawnGroupWarnings.push(`retired with --force although whether its spawn (pid ${p.pid}) still runs could not be read (${live.reason}); its branch is kept`);
|
|
@@ -10000,6 +10120,16 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10000
10120
|
if (!existsSync(metaPath) && !quarantine && !o.force) {
|
|
10001
10121
|
throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${found.home} has no instance.json and no cleanup descriptor, so OATS cannot tell whether external state (identities, worktrees) still depends on it. Retiring it would delete whatever it holds without running any cleanup. Inspect it, then re-run with \`--force\` to remove it anyway.`);
|
|
10002
10122
|
}
|
|
10123
|
+
// The retire hooks run from the record: the repository they are run for (`repo`) and the
|
|
10124
|
+
// capabilities with their hooks (`capabilityRuntime`). A record with no repository runs none.
|
|
10125
|
+
// That is a retire with nothing left out only when the record says that no capability has a
|
|
10126
|
+
// retire hook. One that does not say (the stub lib/materialize.mjs writes, left by a spawn that
|
|
10127
|
+
// was killed before its record and wrote no marker before its hooks) may stand for an identity
|
|
10128
|
+
// registered outside the home: removing the home would leave it there with nothing that knows
|
|
10129
|
+
// of it. Fail closed, as for a home with no record; `--force` is the same deliberate escape.
|
|
10130
|
+
if (!o.force && !nonEmptyString(meta.repo) && !(Array.isArray(meta.capabilityRuntime) && !meta.capabilityRuntime.some((cap) => cap?.hooks?.retire))) {
|
|
10131
|
+
throw oatsError("E_UNIDENTIFIED_INSTANCE_HOME", `${metaPath} records neither a repository nor its capabilities' hooks (a spawn that was interrupted before it wrote its record leaves such a file), so OATS cannot tell which retire hooks to run, and what the spawn's hooks registered outside the home (an identity, a seat) may still be there. Retiring it would remove the home without running any of them. Nothing was stopped, run or removed. Inspect the home, clean up by hand what its capabilities registered, then remove it with \`oats retire ${name} --force\`.`);
|
|
10132
|
+
}
|
|
10003
10133
|
|
|
10004
10134
|
const workPath = join(found.home, "work");
|
|
10005
10135
|
// What work/ is, by the one function the plan reads too (instanceWork, #962). Read once, here.
|
|
@@ -10223,11 +10353,24 @@ function retireSteps(root, name, o, found, at) {
|
|
|
10223
10353
|
at.phase = "after-hooks";
|
|
10224
10354
|
at.hooksStarted = true;
|
|
10225
10355
|
at.said = () => `The retire hooks were started and may not all have run; the home, its work and the pre-hook recovery (if any) are kept; ${sessionSaid()}`;
|
|
10356
|
+
// The hooks that end are recorded in this retire's claim as they end, after those a gone
|
|
10357
|
+
// retire it took over from had recorded: a retire that takes this one's claim over does not
|
|
10358
|
+
// run them again (finishedRetireHooks). The claim is beside the home, so nothing is written
|
|
10359
|
+
// into the home; a record that cannot be written leaves the hook to be run again.
|
|
10360
|
+
const claim = o[RETIRE_CLAIM];
|
|
10361
|
+
const finished = finishedRetireHooks(claim?.tookOver, meta.createdAt, resolved.capabilities);
|
|
10362
|
+
const ended = [...finished].map(([capability, answered]) => ({ capability, ...(answered !== undefined ? { meta: answered } : {}) }));
|
|
10363
|
+
const recordEnded = () => {
|
|
10364
|
+
if (!claim?.me || typeof meta.createdAt !== "string" || !meta.createdAt) return;
|
|
10365
|
+
try { recordInClaim(claim.lock, claim.me, { retireHooks: ended, retireHooksFor: meta.createdAt }); } catch { /* that hook is run again by a take-over */ }
|
|
10366
|
+
};
|
|
10367
|
+
if (ended.length) recordEnded();
|
|
10226
10368
|
hookResults = runLifecycleHooks("retire", {
|
|
10227
10369
|
home: found.home, instance: name, agentName: found.agent.name,
|
|
10228
10370
|
soulDir: instanceSoulDir(found.home, meta) || found.agent._soulDir || join(found.agent._dir, "soul"),
|
|
10229
10371
|
...(nonEmptyString(meta.soulId) ? { soulId: meta.soulId } : {}),
|
|
10230
10372
|
contextDir: meta.repo, workspaceDir: workspaceOf(root), rootDir: root, resolved, priorMeta: meta.capabilityMeta || {},
|
|
10373
|
+
finished, onFinished: (capability, answered) => { ended.push({ capability, ...(isPlainObject(answered) ? { meta: answered } : {}) }); recordEnded(); },
|
|
10231
10374
|
});
|
|
10232
10375
|
// The hooks ran: their warnings are events now, whatever the retire does
|
|
10233
10376
|
// next (a refusal, a quarantine), so an action a hook names outlives the
|
package/lib/dir-lock.mjs
CHANGED
|
@@ -72,6 +72,23 @@ export function dirLockHeld(path, { holderGone } = {}) {
|
|
|
72
72
|
return null;
|
|
73
73
|
}
|
|
74
74
|
|
|
75
|
+
/** What to do about a lock `path` that needs a person, by what was found (`found`: refusals), said
|
|
76
|
+
* to whoever ran `command` (`oats session resume`), the one command that takes the lock. A
|
|
77
|
+
* directory is the lock of a kernel that locked with one: nothing here tells whether that kernel's
|
|
78
|
+
* command runs, so it is the operator who removes it. A record that cannot be read, or whose
|
|
79
|
+
* holder cannot be told to run, is removed once a person has seen that no `command` runs. A gone
|
|
80
|
+
* holder's record is removed without that. Where nothing is in the way (the lock was taken again
|
|
81
|
+
* each time, or this process cannot read its own start) there is nothing to remove. */
|
|
82
|
+
const STUCK_REMEDY = {
|
|
83
|
+
directory: (path) => `once no earlier oats is running on this machine, remove the directory ${path} and run it again`,
|
|
84
|
+
"cannot-take-over": (path) => `remove ${path} and run it again`,
|
|
85
|
+
"held-again": () => "run it again",
|
|
86
|
+
"own-start-unreadable": (path) => `run it again; nothing at ${path} is to be removed`,
|
|
87
|
+
};
|
|
88
|
+
export function stuckLockRemedy(path, found, command) {
|
|
89
|
+
return STUCK_REMEDY[found]?.(path) ?? `if no ${command} is running on this machine, remove ${path} and run it again`;
|
|
90
|
+
}
|
|
91
|
+
|
|
75
92
|
/** The signals a section is not cut short by. */
|
|
76
93
|
const HELD_SIGNALS = ["SIGINT", "SIGTERM"];
|
|
77
94
|
let sections = 0, listening = false, idle = null;
|