@platless/axom-cli 0.5.9 → 0.6.52

package/dist/workstation/update/rdRollback.js

@@ -0,0 +1,145 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { assertLockOwnership, withPrivateLock } from '../control/locks.js';
+import { privateDirectory } from '../keepers/kit/paths.js';
+import { rdStateSchema } from '../rd/state.js';
+export function rdStateDigest(value) { return createHash('sha256').update(value).digest('hex'); }
+function snapshotPath(directory, commandId) { return path.join(directory, 'update', `rd-rollback-${rdStateDigest(commandId)}.json`); }
+export async function readPrivateRdFile(file, maxBytes = 131072) {
+    let handle;
+    try {
+        handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+    try {
+        const info = await handle.stat();
+        if (!info.isFile() || info.uid !== process.getuid?.() || info.mode & 0o077 || info.size > maxBytes)
+            throw new Error('Unsafe RD rollback state');
+        return await handle.readFile('utf8');
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function writePrivate(file, contents) {
+    await privateDirectory(path.dirname(file));
+    const staging = path.join(path.dirname(file), `.rd-rollback-${randomUUID()}`);
+    try {
+        await fs.writeFile(staging, contents, { mode: 0o600, flag: 'wx' });
+        assertLockOwnership();
+        await fs.rename(staging, file);
+    }
+    finally {
+        await fs.rm(staging, { force: true });
+    }
+}
+export async function snapshotRdForRollback(directory, command) {
+    return withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const previous = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        const snapshot = snapshotPath(directory, command.commandId);
+        const value = { schemaVersion: 1, commandId: command.commandId, targetVersion: command.release.version,
+            releaseSha512: command.release.sha512, previous };
+        await writePrivate(snapshot, JSON.stringify(value));
+        return { directory, snapshot };
+    });
+}
+async function pendingUpdate(directory) {
+    const contents = await readPrivateRdFile(path.join(directory, 'update-state.json'));
+    return contents === null ? null : JSON.parse(contents);
+}
+export async function guardRdActivation(directory, cliVersion, next) {
+    const update = await pendingUpdate(directory);
+    if (!update || update.version !== cliVersion || !update.commandId)
+        return;
+    if (update.phase === 'ROLLED_BACK')
+        throw new Error('The CLI update was already rolled back before RD activation');
+    if (!update.releaseSha512)
+        return;
+    const planFile = path.join(directory, 'update', `watchdog-${rdStateDigest(update.commandId)}.json`);
+    const planContents = await readPrivateRdFile(planFile);
+    if (planContents === null)
+        return;
+    const plan = JSON.parse(planContents);
+    if (plan.commandId !== update.commandId || plan.targetVersion !== update.version)
+        throw new Error('RD watchdog plan does not match the pending CLI update');
+    const current = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (current === null)
+        throw new Error('RD state disappeared before activation');
+    const guard = { commandId: update.commandId, targetVersion: update.version, releaseSha512: update.releaseSha512, previousSha256: rdStateDigest(current) };
+    if (!plan.rdRollback)
+        return await authenticatedRdActivation(directory, guard) ? undefined : guard;
+    const expected = snapshotPath(directory, update.commandId);
+    if (plan.rdRollback.directory !== directory || plan.rdRollback.snapshot !== expected)
+        throw new Error('RD rollback snapshot path does not match this update');
+    const contents = await readPrivateRdFile(expected);
+    if (contents === null)
+        throw new Error('RD rollback snapshot is missing');
+    const saved = JSON.parse(contents);
+    if (saved.schemaVersion !== 1 || saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512)
+        throw new Error('RD rollback snapshot belongs to another CLI update');
+    const nextDigest = rdStateDigest(JSON.stringify(rdStateSchema.parse(next)));
+    if (saved.previous !== current && saved.activatedSha256 !== rdStateDigest(current))
+        return guard;
+    await writePrivate(expected, JSON.stringify({ ...saved, activatedSha256: nextDigest, activatedIdentity: undefined }));
+}
+async function stateIdentity(directory) {
+    const info = await fs.lstat(path.join(directory, 'rd', 'state.json'), { bigint: true });
+    return `${info.dev}:${info.ino}:${info.birthtimeNs}:${info.mtimeNs}`;
+}
+export async function completeRdActivation(directory, cliVersion) {
+    const update = await pendingUpdate(directory);
+    if (!update?.commandId || update.version !== cliVersion)
+        return;
+    const file = snapshotPath(directory, update.commandId);
+    const contents = await readPrivateRdFile(file);
+    if (contents === null)
+        return;
+    const saved = JSON.parse(contents);
+    if (saved.commandId !== update.commandId || saved.targetVersion !== update.version || saved.releaseSha512 !== update.releaseSha512 || !saved.activatedSha256)
+        return;
+    const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+    if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+        return;
+    await writePrivate(file, JSON.stringify({ ...saved, activatedIdentity: await stateIdentity(directory) }));
+}
+export async function authenticatedRdActivation(directory, guard) {
+    const update = await pendingUpdate(directory);
+    if (update?.phase !== 'SUCCEEDED' || update.commandId !== guard.commandId || update.version !== guard.targetVersion || update.releaseSha512 !== guard.releaseSha512)
+        return false;
+    const contents = await readPrivateRdFile(path.join(directory, 'update', 'restart-ready.json'));
+    if (contents === null)
+        return false;
+    const marker = JSON.parse(contents);
+    return marker.commandId === guard.commandId && marker.version === guard.targetVersion && typeof marker.generation === 'string' && marker.generation.length > 0;
+}
+export async function restoreRdAfterRollback(reference, commandId, targetVersion) {
+    const directory = reference.directory;
+    if (reference.snapshot !== snapshotPath(directory, commandId))
+        throw new Error('RD rollback snapshot path does not match this update');
+    await withPrivateLock(path.join(directory, 'rd', 'install'), async () => {
+        const update = await pendingUpdate(directory);
+        if (update?.commandId !== commandId || update.version !== targetVersion)
+            return;
+        const contents = await readPrivateRdFile(reference.snapshot);
+        if (contents === null)
+            throw new Error('RD rollback snapshot is missing');
+        const saved = JSON.parse(contents);
+        if (saved.schemaVersion !== 1 || saved.commandId !== commandId || saved.targetVersion !== targetVersion || saved.releaseSha512 !== update.releaseSha512)
+            throw new Error('RD rollback snapshot belongs to another CLI update');
+        if (!saved.activatedSha256)
+            return;
+        const active = await readPrivateRdFile(path.join(directory, 'rd', 'state.json'), 32768);
+        if (active === null || rdStateDigest(active) !== saved.activatedSha256)
+            return;
+        if (saved.activatedIdentity && await stateIdentity(directory) !== saved.activatedIdentity)
+            return;
+        if (saved.previous === null)
+            throw new Error('RD activation has no previous state to restore');
+        await writePrivate(path.join(directory, 'rd', 'state.json'), saved.previous);
+    });
+}

package/dist/workstation/update/recoveryPlan.js

@@ -0,0 +1,124 @@
+import { constants, promises as fs } from 'node:fs';
+import { createHash } from 'node:crypto';
+import path from 'node:path';
+import { z } from 'zod';
+import { deviceWatchdogRecoverySchema, runtimeFilesDigest } from './deviceHealthProtocol.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
+import { deploymentDownloadURL } from '../control/serverIdentity.js';
+const absolute = z.string().min(1).max(4096).refine(value => path.isAbsolute(value) && path.resolve(value) === value);
+export const deviceWatchdogPlanSchema = z.object({
+    schemaVersion: z.literal(2),
+    program: z.object({ path: absolute, sha256: z.string().regex(/^[a-f0-9]{64}$/) }).strict(),
+    deviceRecovery: deviceWatchdogRecoverySchema,
+    rdRollback: z.object({ directory: absolute, snapshot: absolute }).strict().optional(),
+    commandId: z.string().uuid(), targetVersion: z.string().min(1).max(128), archive: absolute,
+    marker: absolute, state: absolute, npmPath: absolute, npmPrefix: absolute, cliPath: absolute,
+    npmEnvironment: z.object({ NPM_CONFIG_PREFIX: absolute, PATH: z.string().max(32768), NPM_CONFIG_CACHE: absolute.optional() }).strict().optional(),
+}).strict();
+export function updateTransactionKey(transactionId) { return createHash('sha256').update(transactionId).digest('hex'); }
+export async function readPrivateUpdateBytes(file, maximum) {
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const before = await handle.stat();
+        if (!before.isFile() || before.nlink !== 1 || before.size > maximum || before.mode & 0o077 || process.getuid && before.uid !== process.getuid())
+            throw Error('Unsafe private update evidence');
+        const bytes = await handle.readFile();
+        const after = await handle.stat();
+        if (bytes.length !== before.size || before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs)
+            throw Error('Private update evidence changed while reading');
+        return bytes;
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function readDeviceWatchdogPlan(planPath, expectedRoot) {
+    const plan = deviceWatchdogPlanSchema.parse(JSON.parse((await readPrivateUpdateBytes(planPath, 1_048_576)).toString('utf8')));
+    const root = path.resolve(expectedRoot), key = updateTransactionKey(plan.commandId), update = path.join(root, 'update');
+    const recovery = plan.deviceRecovery;
+    if (recovery.root !== root || recovery.expectation.transactionId !== plan.commandId || recovery.expectation.release.version !== plan.targetVersion || recovery.rollback.archive !== plan.archive || planPath !== path.join(update, `watchdog-${key}.json`) || plan.program.path !== path.join(update, `watchdog-${key}.mjs`) || plan.archive !== path.join(update, `rollback-${key}.tgz`) || plan.marker !== path.join(update, 'restart-ready.json') || plan.state !== path.join(root, 'update-state.json') || plan.rdRollback && (plan.rdRollback.directory !== root || plan.rdRollback.snapshot !== path.join(update, `rd-rollback-${key}.json`)))
+        throw Error('Device watchdog plan does not bind the original transaction');
+    const program = await readPrivateUpdateBytes(plan.program.path, 33_554_432);
+    if (createHash('sha256').update(program).digest('hex') !== plan.program.sha256)
+        throw Error('Copied device watchdog program digest changed');
+    if (recovery.expectation.resolvedSource !== deploymentDownloadURL(recovery.expectation.origin.server, recovery.expectation.release.url))
+        throw Error('Copied watchdog source binding changed');
+    const source = recovery.rollback.source;
+    if (source.kind === 'local-pack' && (!source.packageRoot || !path.isAbsolute(source.packageRoot)))
+        throw Error('Original rollback package source is missing');
+    if (source.kind === 'authenticated-release' && (source.release.version !== recovery.rollback.version || source.release.sha512 !== recovery.rollback.sha512 || source.release.size !== recovery.rollback.size || !deploymentDownloadURL(source.server, source.release.url)))
+        throw Error('Original authenticated rollback source changed');
+    return plan;
+}
+export async function readDeviceBootstrapRecovery(root, startup) {
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/device-transaction.json'), 33_554_432)).toString('utf8')));
+    const device = z.object({ schemaVersion: z.literal(1), deviceId: z.string().uuid(), initialized: z.literal(true) }).strict().parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'device.json'), 4096)).toString('utf8')));
+    if (!transaction.recoveryRequired && !transaction.installedRollback && transaction.installation === 'not-started' && ['BUSY', 'FAILED'].includes(transaction.phase)) {
+        if ((await fs.readdir(path.join(root, 'update'))).some(name => /^watchdog-.*\.json(?:\..*)?$/.test(name)))
+            throw Error('An armed watchdog still owns terminal recovery');
+        try {
+            const state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString('utf8'));
+            if (!['BUSY', 'FAILED', 'SUCCEEDED', 'ROLLED_BACK'].includes(state.phase))
+                throw Error('Public update evidence remains unresolved');
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        return;
+    }
+    if (!device.initialized || transaction.recoveryRequired && !transaction.installedRollback || !transaction.targetEvidence || !['RESTARTING', 'SUCCEEDED', 'ROLLED_BACK', ...(transaction.installedRollback ? ['FAILED'] : [])].includes(transaction.phase))
+        throw Error('Only an already initialized device can adopt its exact new recovery transaction');
+    if (transaction.targetEvidence.version !== transaction.release.version || transaction.targetEvidence.sha512 !== transaction.release.sha512 || transaction.targetEvidence.size !== transaction.release.size || transaction.resolvedSource !== deploymentDownloadURL(transaction.origin.server, transaction.release.url))
+        throw Error('Exact target archive and source evidence changed');
+    const state = JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update-state.json'), 65536)).toString('utf8'));
+    if (!['RESTARTING', 'SUCCEEDED', 'ROLLED_BACK', ...(transaction.installedRollback ? ['FAILED'] : [])].includes(state.phase) || state.commandId !== transaction.transactionId || state.version !== transaction.release.version || state.releaseSha512 && state.releaseSha512 !== transaction.release.sha512)
+        throw Error('Device recovery state does not match the exact transaction');
+    if (transaction.lifecycle !== 'provision-and-arm') {
+        const policy = transaction.restartPolicy;
+        if (!policy || policy.mode !== (transaction.lifecycle === 'container' ? 'external' : 'manual') || policy.predecessor?.generation !== transaction.initiatingDaemonGeneration || !policy.predecessor.prepared || transaction.installation !== 'started' || transaction.installedRollback || !['RESTARTING', 'SUCCEEDED'].includes(transaction.phase) || !['RESTARTING', 'SUCCEEDED'].includes(state.phase))
+            throw Error('Explicit restart policy and positive original predecessor handoff are required');
+        if ((await fs.readdir(path.join(root, 'update'))).some(name => /^watchdog-.*\.json(?:\..*)?$/.test(name)))
+            throw Error('An armed watchdog cannot be adopted as a no-watchdog restart');
+        if (startup.version !== transaction.release.version || startup.runtimeDigest !== runtimeFilesDigest(transaction.targetEvidence.runtimeFiles))
+            throw Error('Original startup inventory differs from the exact no-watchdog restart target');
+        return { transaction, plan: undefined };
+    }
+    if (transaction.restartPolicy)
+        throw Error('Managed watchdog policy cannot be replaced by a no-watchdog declaration');
+    const plan = await readDeviceWatchdogPlan(path.join(root, 'update', `watchdog-${updateTransactionKey(transaction.transactionId)}.json`), root);
+    const expected = plan.deviceRecovery.expectation;
+    if (expected.transactionId !== transaction.transactionId || expected.challenge !== transaction.challenge || expected.initiatingDaemonGeneration !== transaction.initiatingDaemonGeneration || JSON.stringify(expected.origin) !== JSON.stringify(transaction.origin) || JSON.stringify(expected.release) !== JSON.stringify(transaction.release) || expected.resolvedSource !== transaction.resolvedSource || expected.runtimeDigest !== runtimeFilesDigest(transaction.targetEvidence.runtimeFiles))
+        throw Error('Device recovery plan changed its original private transaction');
+    const rollback = await readArchiveEvidence(plan.archive), frozen = plan.deviceRecovery.rollback;
+    if (rollback.name !== frozen.name || rollback.version !== frozen.version || rollback.size !== frozen.size || rollback.sha512 !== frozen.sha512 || JSON.stringify(rollback.reader) !== JSON.stringify(frozen.reader))
+        throw Error('Frozen rollback reader archive changed');
+    if (transaction.installedRollback) {
+        const installed = transaction.installedRollback;
+        if (installed.transactionId !== transaction.transactionId || installed.archive.version !== rollback.version || installed.archive.sha512 !== rollback.sha512 || installed.archive.size !== rollback.size || runtimeFilesDigest(installed.archive.runtimeFiles) !== runtimeFilesDigest(rollback.runtimeFiles))
+            throw Error('Installed rollback evidence differs from the exact frozen recovery archive');
+        const { assertDeviceRollbackReceipt } = await import('./deviceRollback.js');
+        await assertDeviceRollbackReceipt(root, expected, installed.handoff);
+    }
+    else if (state.phase === 'ROLLED_BACK')
+        throw Error('A terminal label does not prove installed rollback bytes');
+    const expectedVersion = transaction.installedRollback ? rollback.version : transaction.release.version;
+    const expectedDigest = transaction.installedRollback ? runtimeFilesDigest(rollback.runtimeFiles) : expected.runtimeDigest;
+    if (startup.version !== expectedVersion || startup.runtimeDigest !== expectedDigest)
+        throw Error('Original process startup inventory is not the exact recovery package');
+    return { transaction, plan };
+}
+export async function deviceRollbackCompleted(root, startup, originalTransactionId) {
+    const { deviceTransactionSchema } = await import('./deviceCoordinator.js');
+    const transaction = deviceTransactionSchema.parse(JSON.parse((await readPrivateUpdateBytes(path.join(root, 'update/device-transaction.json'), 33_554_432)).toString('utf8')));
+    if (transaction.transactionId !== originalTransactionId || transaction.phase !== 'ROLLED_BACK' || transaction.recoveryRequired || !transaction.targetEvidence || !transaction.installedRollback)
+        return false;
+    const installed = transaction.installedRollback, archive = await readArchiveEvidence(path.join(root, 'update', `rollback-${updateTransactionKey(originalTransactionId)}.tgz`));
+    if (installed.transactionId !== originalTransactionId || installed.archive.sha512 !== archive.sha512 || installed.archive.size !== archive.size || installed.archive.version !== archive.version || runtimeFilesDigest(installed.archive.runtimeFiles) !== runtimeFilesDigest(archive.runtimeFiles) || startup.version !== archive.version || startup.runtimeDigest !== runtimeFilesDigest(archive.runtimeFiles))
+        throw Error('Completed rollback no longer matches original startup and frozen installed evidence');
+    const { assertDeviceRollbackReceipt, writePrivateDeviceEvidence } = await import('./deviceRollback.js');
+    await assertDeviceRollbackReceipt(root, { transactionId: transaction.transactionId, challenge: transaction.challenge, initiatingDaemonGeneration: transaction.initiatingDaemonGeneration, origin: transaction.origin, release: transaction.release, resolvedSource: transaction.resolvedSource, runtimeDigest: runtimeFilesDigest(transaction.targetEvidence.runtimeFiles) }, installed.handoff);
+    await writePrivateDeviceEvidence(path.join(root, 'update/device-transaction.json'), transaction);
+    return true;
+}

package/dist/workstation/update/runUpdate.js

@@ -8,6 +8,7 @@ import { TaskRegistry } from './taskRegistry.js';
 import { LastKnownGoodCache, SERVICE_UNREGISTERED_REMEDIATION, writeReadinessMarker } from './watchdog.js';
 import { updateServiceContext } from '../config.js';
 import { CLIENT_VERSION } from '../version.js';
+import { readArchiveEvidence } from './archiveEvidence.js';
 /**
  * The argv `provisionService` spawns the installed CLI with. Exported so a test can spawn the
  * same command out-of-process and prove it resolves against the unified CLI's actual command
@@ -124,7 +125,7 @@ export function lifecyclePolicy(lifecycle) {
 export function createUpdateCoordinator(deps) {
     const policy = lifecyclePolicy(deps.serviceLifecycle);
     const updateContext = updateServiceContext(deps.dir);
-    const npm = new NpmInstaller(updateContext);
+    const npm = new NpmInstaller({ ...updateContext, installationLockHeld: deps.installationLockHeld });
     // This cache also resumes the restart handshake after service supervision starts a new daemon.
     const releaseCache = new LastKnownGoodCache({
         ...updateContext, runningVersion: CLIENT_VERSION, pack: (root, destination) => npm.pack(root, destination),
@@ -133,9 +134,14 @@ export function createUpdateCoordinator(deps) {
         // rollback can re-provision with it; the watchdog runs from a copy outside the package and has
         // no way to find it otherwise.
         cliPath: deps.cliPath,
+        deviceTransaction: deps.deviceUpdate?.currentTransaction,
+        sourceServer: deps.server,
     });
     return new UpdateCoordinator({
-        tasks: deps.tasks ?? new TaskRegistry(), installer: npm, state: new UpdateStateStore(deps.dir),
+        tasks: deps.deviceUpdate ? undefined : deps.tasks ?? new TaskRegistry(), installer: npm, state: new UpdateStateStore(deps.dir),
+        deviceAdmission: deps.deviceUpdate,
+        verifyArtifact: deps.deviceUpdate ? async (artifact) => { await deps.deviceUpdate.recordTarget(await readArchiveEvidence(artifact.path)); } : undefined,
+        persistDevicePhase: deps.deviceUpdate?.recordPhase,
         drainTimeoutMs: deps.drainTimeoutMs,
         // Without an artifact source the coordinator cannot fetch the release at all: every update and
         // reinstall fails at DOWNLOADING with "requires the configured server URL". The artifact is
@@ -180,7 +186,8 @@ export function createUpdateCoordinator(deps) {
             const log = openSync(`${deps.dir}/daemon.log`, 'a');
             let child;
             try {
-                child = spawn(process.execPath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                child = spawn(updateContext.nodePath, [deps.cliPath, ...PROVISION_SERVICE_ARGV], {
+                    ...(updateContext.env ? { env: updateContext.env } : {}),
                     detached: true,
                     stdio: ['ignore', log, log],
                 });

package/dist/workstation/update/taskRegistry.js

@@ -8,8 +8,166 @@ export class TaskRegistry {
     agentOpenReservations = new Map();
     agentSessions = new Map();
     idleWaiters = new Set();
+    acceptedAgentWaiters = new Set();
     stopping = null;
-    accepting = true;
+    baseAccepting = true;
+    externalClosures = 0;
+    lifetime = {};
+    lifetimeClosed = false;
+    accountingUnknown = false;
+    pendingAccepted = 0;
+    inFlightAccepted = 0;
+    reservedAccepted = 0;
+    accepted = new WeakMap();
+    externalHolds = new WeakMap();
+    get accepting() { return this.baseAccepting && this.externalClosures === 0 && !this.accountingUnknown && !this.lifetimeClosed; }
+    set accepting(open) { this.baseAccepting = open; }
+    holdExternalAdmission() {
+        if (!Number.isSafeInteger(this.externalClosures + 1)) {
+            this.accountingUnknown = true;
+            throw new Error('Admission accounting is uncertain');
+        }
+        const hold = Object.freeze({});
+        this.externalHolds.set(hold, true);
+        this.externalClosures += 1;
+        return hold;
+    }
+    releaseExternalAdmission(hold) {
+        const active = this.externalHolds.get(hold);
+        if (active === undefined)
+            throw new Error('Invalid admission hold');
+        if (!active)
+            return;
+        this.externalHolds.set(hold, false);
+        if (this.externalClosures <= 0) {
+            this.accountingUnknown = true;
+            throw new Error('Admission accounting is uncertain');
+        }
+        this.externalClosures -= 1;
+    }
+    beginAcceptedAgentWork(kind, frame, adoption) {
+        if (frame.t !== kind)
+            throw new Error('Original agent frame kind mismatch');
+        const durableTurn = kind === 'agent_prompt' && typeof frame.sessionRef === 'string' && this.isDurableSession(frame.sessionRef);
+        const conditionalAdoption = !this.accepting && !durableTurn && kind === 'agent_prompt' && typeof frame.sessionRef === 'string' && adoption !== null && typeof adoption === 'object' ? adoption : undefined;
+        if (!this.accepting && !((durableTurn || conditionalAdoption !== undefined) && this.externalClosures === 0 && !this.accountingUnknown && !this.lifetimeClosed))
+            return null;
+        if (!Number.isSafeInteger(this.inFlightAccepted + 1)) {
+            this.accountingUnknown = true;
+            return null;
+        }
+        const ticket = Object.freeze({});
+        this.accepted.set(ticket, { frame, kind, lifetime: this.lifetime, adoption: conditionalAdoption, phase: 'pending' });
+        this.pendingAccepted += 1;
+        this.inFlightAccepted += 1;
+        return ticket;
+    }
+    originalAccepted(ticket, kind, frame) {
+        const state = this.accepted.get(ticket);
+        if (!state || state.frame !== frame || state.kind !== kind || state.lifetime !== this.lifetime || this.lifetimeClosed || state.phase !== 'pending')
+            throw new Error('Invalid or expired original agent admission');
+        return state;
+    }
+    reserveAcceptedAgentOpen(ticket, frame) {
+        const state = this.originalAccepted(ticket, 'agent_open', frame);
+        const count = (this.agentOpenReservations.get(frame.sessionRef) ?? 0) + 1;
+        if (!Number.isSafeInteger(count)) {
+            this.accountingUnknown = true;
+            throw new Error('Admission accounting is uncertain');
+        }
+        this.agentOpenReservations.set(frame.sessionRef, count);
+        state.phase = 'reserved';
+        this.pendingAccepted -= 1;
+        this.reservedAccepted += 1;
+    }
+    consumeAcceptedAgentWork(ticket, kind, frame) {
+        const state = this.originalAccepted(ticket, kind, frame);
+        if (state.adoption) {
+            const sessionRef = frame.sessionRef;
+            const session = typeof sessionRef === 'string' ? this.agentSessions.get(sessionRef) : undefined;
+            if (kind !== 'agent_prompt' || !session?.durable || session.adoption !== state.adoption)
+                throw new Error('Original durable adoption is not established');
+        }
+        state.phase = 'consumed';
+    }
+    finishAcceptedAgentWork(ticket) {
+        const state = this.accepted.get(ticket);
+        if (!state)
+            throw new Error('Invalid original agent admission');
+        if (state.phase === 'finished')
+            return;
+        if (state.phase !== 'reserved')
+            this.pendingAccepted -= 1;
+        else
+            this.reservedAccepted -= 1;
+        this.inFlightAccepted -= 1;
+        state.phase = 'finished';
+        state.frame = undefined;
+        state.adoption = undefined;
+        if (![this.pendingAccepted, this.inFlightAccepted, this.reservedAccepted].every(count => Number.isSafeInteger(count) && count >= 0)) {
+            this.accountingUnknown = true;
+            throw new Error('Admission accounting is uncertain');
+        }
+        if (this.inFlightAccepted === 0)
+            for (const done of [...this.acceptedAgentWaiters])
+                done();
+        this.notifyIfIdle();
+    }
+    /** Wait for already accepted handlers, including asynchronous opens, to finish their late-stop cleanup. */
+    waitForAcceptedAgentWork(timeoutMs) {
+        if (this.accountingUnknown)
+            return Promise.resolve(false);
+        if (this.inFlightAccepted === 0)
+            return Promise.resolve(true);
+        return new Promise(resolve => {
+            const finish = (settled) => {
+                clearTimeout(timer);
+                this.acceptedAgentWaiters.delete(done);
+                resolve(settled && !this.accountingUnknown);
+            };
+            const done = () => finish(true);
+            const timer = setTimeout(() => finish(false), timeoutMs);
+            this.acceptedAgentWaiters.add(done);
+        });
+    }
+    closeAgentWorkLifetime() { this.lifetimeClosed = true; this.baseAccepting = false; this.lifetime = {}; }
+    async cancelTargetWork() {
+        this.closeAgentWorkLifetime();
+        const shells = [...this.shellTasks.entries()];
+        for (const [controller] of shells)
+            controller.abort();
+        let timer;
+        try {
+            await Promise.race([Promise.all(shells.map(([, completed]) => completed)), new Promise((_, reject) => { timer = setTimeout(() => reject(Error('Original shell cleanup remains pending')), 5000); })]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    assertTargetWorkSettled() {
+        if (!this.lifetimeClosed || this.accountingUnknown || this.inFlightAccepted || this.agentOpenReservations.size || this.shellTasks.size)
+            throw Error('Original accepted work remains pending');
+    }
+    observeTargetPending() {
+        let reservations = 0;
+        for (const count of this.agentOpenReservations.values())
+            reservations += count;
+        let pending = this.inFlightAccepted + Math.max(0, reservations - this.reservedAccepted) + this.shellTasks.size;
+        let known = !this.accountingUnknown;
+        for (const session of this.agentSessions.values())
+            try {
+                if (session.busy())
+                    pending += 1;
+            }
+            catch {
+                known = false;
+            }
+        if (!Number.isSafeInteger(pending) || pending < 0) {
+            this.accountingUnknown = true;
+            known = false;
+        }
+        return { pending, registered: this.agentSessions.size, known };
+    }
     /** Keeper-terminal execs also counted in `activeShellTasks` right now (see {@link countKeeperExec}). */
     keeperExecsCounted = 0;
     /**
@@ -167,7 +325,7 @@ export class TaskRegistry {
      * its detach (see {@link AgentSessionRegistration}).
      */
     registerAgentSession(sessionRef, close, busy, registration = {}) {
-        this.agentSessions.set(sessionRef, { close, busy, durable: registration.durable === true });
+        this.agentSessions.set(sessionRef, { close, busy, durable: registration.durable === true, adoption: registration.adoption });
     }
     /**
      * 采样式判据没有"变空闲"这个事件可以挂钩，所以持有者在可能变空闲时喊一声。
@@ -214,7 +372,7 @@ export class TaskRegistry {
     tryAdmitTurn(sessionRef) {
         // Spec §8.2: a keeper-hosted session's prompt is admitted while draining — it enters keeper-acp's log first and a restart
         // continues it; a fallback session's would be cut by the restart.
-        return this.accepting || this.agentSessions.get(sessionRef)?.durable === true;
+        return !this.lifetimeClosed && (this.accepting || this.agentSessions.get(sessionRef)?.durable === true && this.externalClosures === 0);
     }
     /**
      * The restart path of an update (Task 21, spec §5.5.5): every durable session is detached (its registered close), so the next daemon