@platless/axom-cli 0.6.36 → 0.6.52

package/dist/workstation/update/legacyOwner.js

@@ -0,0 +1,39 @@
+import os from 'node:os';
+import { deriveSessionKey, randomBytes } from '../crypto.js';
+import { connectEncryptedChannel } from '../connection/encryptedChannel.js';
+import { workstationChannelUrl } from '../channels/url.js';
+import { decodeManagementFrame, encodeManagementFrame, MANAGEMENT_WIRE_MIN_VERSION, MANAGEMENT_WIRE_VERSION } from '../protocol/management.js';
+import { AGENT_WIRE_MIN_VERSION, AGENT_WIRE_VERSION } from '../protocol/agent.js';
+/** Resolve missing legacy ownership only after proving possession of the existing workstation key
+ * to its pinned Server key. The plaintext nonce challenge can never supply account identity. */
+export async function recoverAuthenticatedLegacyOwner(options) {
+    const abort = new AbortController(), timer = setTimeout(() => abort.abort(), options.timeoutMs ?? 15_000), nonce = randomBytes(16);
+    let challenge;
+    const protocols = { MANAGEMENT: { min: MANAGEMENT_WIRE_MIN_VERSION, max: MANAGEMENT_WIRE_VERSION }, COMPUTER: { min: 1, max: 6 }, AGENT: { min: AGENT_WIRE_MIN_VERSION, max: AGENT_WIRE_VERSION } };
+    const heartbeat = (seq, sentAtEpochMs) => ({ t: 'heartbeat', seq, sentAtEpochMs, clientVersion: options.version, channels: { MANAGEMENT: 'CONNECTING', COMPUTER: 'DISCONNECTED', AGENT: 'DISCONNECTED' }, activeShellTasks: 0, activeAgentTasks: 0, update: { ...options.update, remoteForcePolicy: 'drain-only' } });
+    let channel;
+    try {
+        channel = await connectEncryptedChannel({ url: workstationChannelUrl(options.server, 'management'), signal: abort.signal, openTimeoutMs: options.timeoutMs ?? 15_000, encode: encodeManagementFrame, decode: decodeManagementFrame, decodeBytes: decodeManagementFrame, heartbeat, initialFrame: () => heartbeat(0, Date.now()), isHeartbeatAck: (frame, seq) => frame.t === 'heartbeat_ack' && frame.seq === seq, handshake: async (wire) => {
+                wire.sendText(encodeManagementFrame({ t: 'management_hello', workstationId: options.workstationId, workstation: os.hostname(), clientNonce: nonce.toString('base64'), clientVersion: options.version, clientPackage: '@platless/axom-cli', protocols }));
+                const response = await wire.receive();
+                if (response.isBinary)
+                    throw Error('Expected management nonce challenge');
+                const welcome = JSON.parse(response.data.toString());
+                if (welcome.t !== 'welcome' || typeof welcome.serverNonce !== 'string' || Buffer.from(welcome.serverNonce, 'base64').length !== 16)
+                    throw Error('Server did not authenticate this workstation identity');
+                challenge = welcome.serverNonce;
+                return deriveSessionKey(options.clientKey, options.serverPub, nonce, Buffer.from(challenge, 'base64'));
+            } });
+        for await (const frame of channel.messages)
+            if (frame.t === 'management_ready') {
+                if (frame.serverNonce !== challenge || !frame.generation || typeof frame.ownerUserId !== 'string' || !frame.ownerUserId.trim() || frame.ownerUserId.length > 1024 || /[\u0000-\u001f\u007f]/.test(frame.ownerUserId))
+                    throw Error('Authenticated Server did not supply the legacy workstation owner; a compatible Server is required');
+                return frame.ownerUserId;
+            }
+        throw Error('Authenticated management connection closed before owner verification');
+    }
+    finally {
+        clearTimeout(timer);
+        channel?.close();
+    }
+}

package/dist/workstation/update/npmInstaller.js

@@ -76,11 +76,11 @@ export class NpmInstaller {
         }
         await verifyOptionalPty(this.options.npmPrefix, this.spawn);
     }
-    /** Packs the installed package locally; `--json` gives npm's own name/version validation input. */
+    /** Snapshots installed files, without rerunning source-only lifecycle/build scripts. */
     async pack(packageRoot, destination) {
         absolute(packageRoot, 'packageRoot');
         absolute(destination, 'destination');
-        const args = ['pack', packageRoot, '--pack-destination', destination, '--json'];
+        const args = ['pack', packageRoot, '--pack-destination', destination, '--json', '--ignore-scripts'];
         return new Promise((resolve, reject) => {
             let stdout = '';
             let stderr = '';

package/dist/workstation/update/privateDurability.js

@@ -0,0 +1,61 @@
+import { constants, promises as fs } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+async function syncDirectory(directory) {
+    const handle = await fs.open(directory, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        if (!(await handle.stat()).isDirectory())
+            throw Error('Private recovery namespace is not a directory');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function ensureDurablePrivateDirectory(directory) {
+    try {
+        await fs.mkdir(directory, { mode: 0o700 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+    }
+    const stat = await fs.lstat(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+        throw Error('Unsafe private recovery evidence directory');
+    await syncDirectory(directory);
+    await syncDirectory(path.dirname(directory));
+}
+export async function syncPrivateRecoveryFile(file) {
+    const handle = await fs.open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.mode & 0o077 || process.getuid && stat.uid !== process.getuid())
+            throw Error('Unsafe private recovery dependency');
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    await syncDirectory(path.dirname(file));
+}
+export async function writeDurablePrivateUpdate(file, contents) {
+    const directory = path.dirname(file);
+    await ensureDurablePrivateDirectory(directory);
+    const temporary = path.join(directory, `.private-update-${randomUUID()}`);
+    try {
+        const handle = await fs.open(temporary, constants.O_CREAT | constants.O_EXCL | constants.O_WRONLY | constants.O_NOFOLLOW, 0o600);
+        try {
+            await handle.writeFile(contents);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await fs.rename(temporary, file);
+        await syncDirectory(directory);
+    }
+    finally {
+        await fs.rm(temporary, { force: true });
+    }
+}

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
@@ -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

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