@playcraft/cli 0.1.69 → 0.1.71

package/dist/workspace-runtime/workspaces/skill-activation-requests.js

@@ -0,0 +1,512 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { z } from 'zod';
+import { platformEndpoint, productionSessionAttemptId, skillActivationPayloadSchema, skillActivationBindingHash, skillRequiresExclusiveTurn, skillActivationRegistrationSchema, skillActivationRequestRecordSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { canonicalProjectSkillsJson, parseRemoteSkillSelectionResult, projectSkillsDigest, } from '@playcraft/common/project-skills';
+import { workspaceContextFromRoot } from './registry.js';
+import { assertOperationDirectoryAccess } from '../server/directory-access.js';
+import { readWorkspaceSkillSnapshot } from './skills.js';
+import { readLockedProjectSkillCatalog } from '../../project-skills/discovery.js';
+import { activatePreparedSkillSelection } from '../../project-skills/remote-activation.js';
+import { batchDirectoryHeld } from '../batch/occupancy.js';
+import { trustedMemberPolicy } from '../batch/policy.js';
+import { wakeSourceEventUploader } from '../server/source-uploader.js';
+const privateFields = z.object({ selection: z.unknown(), leaseFence: z.number().int().nonnegative(),
+    requestedSkillRefs: z.array(z.string().min(1).max(257)).min(1).max(512) }).passthrough();
+function parsePrivate(value) {
+    const proof = skillActivationRequestRecordSchema.strip().parse(value), extra = privateFields.parse(value);
+    return { ...proof, leaseFence: extra.leaseFence, requestedSkillRefs: extra.requestedSkillRefs,
+        selection: parseRemoteSkillSelectionResult(extra.selection) };
+}
+const TERMINAL = new Set(['completed', 'failed', 'interrupted']);
+const loops = new WeakMap();
+const closing = new WeakSet();
+const waiters = new WeakMap();
+const stableId = (value) => {
+    const hash = createHash('sha256').update(value).digest('hex');
+    return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-4${hash.slice(13, 16)}-8${hash.slice(17, 20)}-${hash.slice(20, 32)}`;
+};
+async function directory(state) {
+    const target = resolve(state.config.stateDir, 'skill-activation-requests');
+    // private: controller-only activation request state, outside the shared workspace.
+    await mkdir(target, { recursive: true, mode: 0o700 });
+    const stat = await lstat(target);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('skill_activation_state_invalid');
+    const actual = await realpath(target), rel = relative(await realpath(state.config.workspaceRoot), actual);
+    if (!rel || rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+        throw new Error('skill_activation_state_not_private');
+    return actual;
+}
+async function read(state, requestId) {
+    const path = join(await directory(state), `${requestId}.json`);
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024 * 1024)
+            throw new Error('skill_activation_state_invalid');
+        return parsePrivate(JSON.parse(await handle.readFile('utf8')));
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function write(state, record) {
+    const folder = await directory(state), temporary = join(folder, `.${randomUUID()}.tmp`);
+    const bytes = canonicalProjectSkillsJson(parsePrivate(record));
+    if (Buffer.byteLength(bytes) > 16 * 1024 * 1024)
+        throw new Error('skill_activation_state_limit');
+    try {
+        // private: activation requests include trusted selections and controller lease fences.
+        await writeFile(temporary, bytes, { flag: 'wx', mode: 0o600 });
+        await rename(temporary, join(folder, `${record.requestId}.json`));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function listPrivate(state) {
+    const files = (await readdir(await directory(state))).filter(name => /^[a-f0-9-]{36}\.json$/.test(name));
+    if (files.length > 256)
+        throw new Error('skill_activation_state_limit');
+    return Promise.all(files.sort().map(name => read(state, name.slice(0, -5))));
+}
+/** Control-only proof, stripped of the trusted selection body and all host paths. */
+export async function listSkillActivationRequests(state, workspaceId, directoryName) {
+    return (await listPrivate(state)).filter(record => (!workspaceId || record.workspaceId === workspaceId)
+        && (!directoryName || record.directoryName === directoryName)).map(record => {
+        const { selection: _selection, leaseFence: _lease, requestedSkillRefs: _roots, ...proof } = record;
+        return skillActivationRequestRecordSchema.parse(proof);
+    });
+}
+async function change(state, requestId, patch) {
+    return state.journal.exclusive('skill-activation-request-store', async () => {
+        const current = await read(state, requestId);
+        if (Object.entries(patch).every(([key, value]) => current[key] === value))
+            return current;
+        const next = { ...current, ...patch, updatedAt: new Date().toISOString() };
+        await write(state, next);
+        return next;
+    });
+}
+function currentSource(state, context) {
+    const matches = state.journal.listOperations().map(item => item.operation).filter(operation => operation.kind === 'session.turn' && operation.sessionId === context.sessionId && operation.clientRequestId === context.clientRequestId
+        && operation.generation === state.config.generation && operation.runtimeEpoch === state.runtimeEpoch
+        && ['dispatched', 'accepted'].includes(operation.status));
+    const source = matches.length === 1 ? matches[0] : undefined;
+    const session = state.journal.getSession(context.sessionId);
+    if (!source?.workspaceId || !source.nativeThreadId || !source.nativeTurnId || source.directoryName === 'root'
+        || source.userId !== state.config.userId || source.environment !== state.config.environment
+        || source.workMode === 'plan' || source.permissionMode === 'read-only' || session?.permissionMode === 'read-only'
+        || !session || session.turnBlock || !['running', 'waiting_for_user'].includes(session.turnStatus ?? '')
+        || session.activeTurnId !== source.nativeTurnId || session.threadId !== source.nativeThreadId || session.cwd !== context.cwd
+        || session.workspaceId !== source.workspaceId || (session.directoryName ?? 'basic') !== (source.directoryName ?? 'basic')
+        || productionSessionAttemptId(context.sessionId) || /^member-[0-9a-f-]{36}$/i.test(context.sessionId) || trustedMemberPolicy(state, context.sessionId)
+        || state.journal.destroyed() || (source.leaseFence ?? 0) < state.acceptedLeaseFence)
+        throw new Error('skill_activation_source_unavailable');
+    return source;
+}
+async function verifyPrepared(root, selection) {
+    const preparedRoot = join(root, '.playcraft/skill-selections', selection.selectionId);
+    for (const path of [join(root, '.playcraft'), join(root, '.playcraft/skill-selections'), preparedRoot]) {
+        const stat = await lstat(path);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('skill_activation_selection_invalid');
+    }
+    const handle = await open(join(preparedRoot, 'selection.json'), constants.O_RDONLY | constants.O_NOFOLLOW);
+    let saved;
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > 16 * 1024 * 1024)
+            throw new Error('skill_activation_selection_invalid');
+        saved = parseRemoteSkillSelectionResult(JSON.parse(await handle.readFile('utf8')));
+    }
+    finally {
+        await handle.close();
+    }
+    if (canonicalProjectSkillsJson(saved) !== canonicalProjectSkillsJson(selection))
+        throw new Error('skill_activation_selection_changed');
+    const catalog = await readLockedProjectSkillCatalog(preparedRoot, join(preparedRoot, '.playcraft/skill-artifacts'));
+    if (catalog.lockHash !== selection.lockHash || catalog.skills.length !== selection.lock.entries.length)
+        throw new Error('skill_activation_selection_invalid');
+}
+function alreadyActive(snapshot, selection) {
+    return selection.lock.entries.every(selected => {
+        const matches = snapshot.lock.entries.filter(item => item.revision.skillRef === selected.revision.skillRef);
+        const locked = matches.length === 1 ? matches[0] : undefined;
+        const declared = snapshot.declaration.entries.find(item => item.entryKey === locked?.entryKey);
+        return locked?.revision.kind === 'release' && selected.revision.kind === 'release'
+            && locked.revision.version === selected.revision.version && locked.revision.artifactHash === selected.revision.artifactHash
+            && declared?.enabled && declared.surface === 'sandbox-agent';
+    });
+}
+/** Registers immutable intent while the source turn runs; activation is deferred to a new trusted turn. */
+export async function registerSkillActivationRequest(state, context, input) {
+    const selection = parseRemoteSkillSelectionResult(input), root = await realpath(context.cwd);
+    const requestedSkillRefs = [...new Set(context.requestedSkillRefs ?? selection.skills.map(skill => skill.skillRef))];
+    if (!requestedSkillRefs.length || requestedSkillRefs.some(ref => !selection.skills.some(skill => skill.skillRef === ref)))
+        throw new Error('skill_activation_selection_invalid');
+    if (root !== context.cwd)
+        context = { ...context, cwd: root };
+    const scope = await workspaceContextFromRoot(state, root), source = currentSource(state, context);
+    if (scope.workspaceId !== source.workspaceId || scope.directoryName !== (source.directoryName ?? 'basic')
+        || await batchDirectoryHeld(state, scope.workspaceId, scope.directoryName))
+        throw new Error('skill_activation_scope_unavailable');
+    await verifyPrepared(root, selection);
+    const snapshot = await readWorkspaceSkillSnapshot(root), lockHash = projectSkillsDigest(snapshot.lock);
+    if (source.context?.skills.some(skill => skill.lockHash !== lockHash))
+        throw new Error('skill_activation_source_unavailable');
+    currentSource(state, context);
+    const exclusiveRefs = selection.skills.filter(skill => skillRequiresExclusiveTurn(skill.skillRef)).map(skill => skill.skillRef);
+    const executableHere = !exclusiveRefs.length || source.directoryAccessMode === 'exclusive' && source.skillExecutionPolicyVersion === 1
+        && exclusiveRefs.every(ref => source.context?.skills.some(selected => selected.lockHash === lockHash
+            && snapshot.lock.entries.some(entry => entry.entryKey === selected.entryKey && entry.revision.skillRef === ref)));
+    if (alreadyActive(snapshot, selection) && executableHere)
+        return skillActivationRegistrationSchema.parse({ status: 'already_active', selectionId: selection.selectionId,
+            lockHash, executionReady: true });
+    return state.journal.exclusive('skill-activation-request-store', async () => {
+        currentSource(state, context);
+        const records = await listPrivate(state);
+        const requestId = stableId(canonicalProjectSkillsJson([state.config.runtimeId, state.config.generation, state.runtimeEpoch,
+            scope.workspaceId, scope.directoryName, source.operationId, selection.selectionId]));
+        const previous = records.find(item => item.requestId === requestId);
+        if (previous) {
+            if (canonicalProjectSkillsJson(previous.selection) !== canonicalProjectSkillsJson(selection))
+                throw new Error('skill_activation_request_conflict');
+            return skillActivationRegistrationSchema.parse({ status: 'activation_requested', selectionId: selection.selectionId, requestId, executionReady: false });
+        }
+        if (records.some(item => item.sourceOperationId === source.operationId))
+            throw new Error('skill_activation_request_conflict');
+        if (records.length >= 256)
+            throw new Error('skill_activation_state_limit');
+        const now = new Date().toISOString();
+        const record = { version: 1, requestId, selectionId: selection.selectionId, selection,
+            requestedSkillRefs,
+            workspaceId: scope.workspaceId, directoryName: scope.directoryName, sourceOperationId: source.operationId,
+            sourceSessionId: context.sessionId, sourceThreadId: source.nativeThreadId, sourceTurnId: source.nativeTurnId,
+            generation: state.config.generation, runtimeEpoch: state.runtimeEpoch, leaseFence: source.leaseFence ?? 0,
+            expectedLockHash: lockHash, expectedDeclarationHash: snapshot.lock.declarationHash,
+            registrationHash: skillActivationBindingHash(state.journal.getWorkspace(scope.workspaceId), scope.directoryName),
+            selectionReferences: selection.skills.map(({ skillRef, skillVersionId, version, artifactHash }) => ({ skillRef, skillVersionId, version, artifactHash })),
+            status: 'requested', createdAt: now, updatedAt: now };
+        await write(state, record);
+        await state.journal.allocateSourceEvent({ runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+            type: 'skills.activation.requested', occurredAt: now, workspaceId: scope.workspaceId, sessionId: context.sessionId,
+            operationId: source.operationId, payload: { requestId, selectionId: selection.selectionId } });
+        wakeSourceEventUploader(state);
+        wakeSkillActivationRequests(state);
+        return skillActivationRegistrationSchema.parse({ status: 'activation_requested', selectionId: selection.selectionId, requestId, executionReady: false });
+    });
+}
+const busy = (state, exceptOperationId) => state.journal.listSessions().some(session => !!session.turnBlock || ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? ''))
+    || state.journal.listOperations().some(({ operation }) => operation.operationId !== exceptOperationId
+        && ['session.turn', 'session.review', 'session.compact'].includes(operation.kind) && !TERMINAL.has(operation.status));
+const nativeBusy = (state, exceptOperationId) => state.journal.listSessions().some(session => !!session.turnBlock || ['starting', 'running', 'waiting_for_user'].includes(session.turnStatus ?? ''))
+    || state.journal.listApprovals().some(approval => approval.status === 'pending')
+    || state.journal.listOperations().some(({ operation }) => operation.operationId !== exceptOperationId
+        && ['session.turn', 'session.review', 'session.compact'].includes(operation.kind)
+        && ['dispatched', 'accepted', 'uncertain'].includes(operation.status));
+function matchesSource(state, record, source) {
+    return !!source && source.kind === 'session.turn' && source.operationId === record.sourceOperationId
+        && source.workspaceId === record.workspaceId && (source.directoryName ?? 'basic') === record.directoryName
+        && source.sessionId === record.sourceSessionId && source.nativeThreadId === record.sourceThreadId && source.nativeTurnId === record.sourceTurnId
+        && source.generation === record.generation && source.runtimeEpoch === record.runtimeEpoch
+        && source.userId === state.config.userId && source.environment === state.config.environment;
+}
+function continuation(state, record) {
+    const matches = state.journal.listOperations().map(item => item.operation).filter(operation => operation.kind === 'session.turn'
+        && operation.clientRequestId === record.requestId && operation.sessionId === record.sourceSessionId
+        && operation.workspaceId === record.workspaceId && (operation.directoryName ?? 'basic') === record.directoryName
+        && operation.generation === record.generation && operation.runtimeEpoch === record.runtimeEpoch);
+    if (matches.length > 1)
+        throw new Error('skill_activation_operation_ambiguous');
+    return matches[0];
+}
+async function applyContinuationReceipt(state, record, target) {
+    if (target.status === 'completed')
+        await change(state, record.requestId, { status: 'completed', error: undefined });
+    else if (target.status === 'failed' || target.status === 'interrupted')
+        await change(state, record.requestId, {
+            status: target.status === 'interrupted' ? 'cancelled' : 'failed', error: 'skill_activation_continuation_failed',
+        });
+    else if (target.status === 'uncertain')
+        await change(state, record.requestId, { status: 'uncertain', error: 'skill_activation_continuation_uncertain' });
+    else
+        await change(state, record.requestId, { status: 'dispatched', error: undefined });
+}
+/** Startup reconciliation reads existing receipts only; it never dispatches or restarts native work. */
+export async function reconcileSkillActivationRequestReceipts(state) {
+    for (const record of await listPrivate(state)) {
+        if (['completed', 'failed', 'cancelled', 'stale'].includes(record.status))
+            continue;
+        try {
+            const target = continuation(state, record);
+            if (target)
+                await applyContinuationReceipt(state, record, target);
+        }
+        catch {
+            await change(state, record.requestId, { status: 'uncertain', error: 'skill_activation_operation_ambiguous' });
+        }
+    }
+}
+function superseded(state, record, currentOperationId) {
+    const source = state.journal.getOperationById(record.sourceOperationId);
+    return state.journal.listOperations().some(({ operation }) => operation.sessionId === record.sourceSessionId
+        && ['session.turn', 'session.review', 'session.compact'].includes(operation.kind)
+        && operation.operationId !== source?.operationId && operation.operationId !== currentOperationId
+        && operation.clientRequestId !== record.requestId && operation.createdAt >= (source?.createdAt ?? record.createdAt));
+}
+function dispatchBody(state, record) {
+    return { ...skillActivationPayloadSchema.parse({ version: record.version, requestId: record.requestId, selectionId: record.selectionId,
+            sourceOperationId: record.sourceOperationId, sourceSessionId: record.sourceSessionId, sourceThreadId: record.sourceThreadId,
+            sourceTurnId: record.sourceTurnId, expectedLockHash: record.expectedLockHash, expectedDeclarationHash: record.expectedDeclarationHash,
+            registrationHash: record.registrationHash }), runtimeId: state.config.runtimeId, generation: record.generation,
+        runtimeEpoch: record.runtimeEpoch, workspaceId: record.workspaceId, directoryName: record.directoryName };
+}
+async function verifyActivationPermission(state, record) {
+    const response = await fetch(platformEndpoint(state.config.publicBaseUrl, '/runtime/internal/skill-activation-requests/verify'), {
+        method: 'POST', redirect: 'error', signal: AbortSignal.timeout(15_000),
+        headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
+        body: JSON.stringify(dispatchBody(state, record)),
+    });
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => undefined);
+        throw new Error('skill_activation_authority_unavailable');
+    }
+    const result = await response.json().catch(() => undefined);
+    if (result?.verified !== true)
+        throw new Error('skill_activation_authority_unavailable');
+}
+/** The continuation owns an exclusive directory lease and is verified before changing any lock bytes. */
+export async function activateSkillSelectionForTurn(state, operation, payload, root) {
+    const input = skillActivationPayloadSchema.parse(payload), record = await read(state, input.requestId);
+    for (const key of Object.keys(input))
+        if (record[key] !== input[key])
+            throw new Error('skill_activation_request_invalid');
+    const assertCurrent = () => {
+        const source = state.journal.getOperationById(record.sourceOperationId), session = state.journal.getSession(record.sourceSessionId);
+        const binding = state.journal.getWorkspace(record.workspaceId);
+        const live = state.journal.getOperationById(operation.operationId);
+        if (state.journal.destroyed() || record.generation !== state.config.generation || record.runtimeEpoch !== state.runtimeEpoch
+            || operation.kind !== 'session.turn' || operation.clientRequestId !== record.requestId || operation.sessionId !== record.sourceSessionId
+            || operation.userId !== state.config.userId || operation.environment !== state.config.environment
+            || operation.generation !== record.generation || operation.runtimeEpoch !== record.runtimeEpoch
+            || operation.workspaceId !== record.workspaceId || (operation.directoryName ?? 'basic') !== record.directoryName
+            || operation.directoryAccessMode !== 'exclusive' || (operation.leaseFence ?? 0) < state.acceptedLeaseFence
+            || operation.workMode === 'plan' || operation.permissionMode === 'read-only' || session?.permissionMode === 'read-only' || session?.cwd !== root
+            || !live || live.status !== 'dispatched' || !binding || skillActivationBindingHash(binding, record.directoryName) !== record.registrationHash
+            || !matchesSource(state, record, source) || source?.status !== 'completed'
+            || ['failed', 'cancelled', 'stale', 'uncertain', 'completed'].includes(record.status)
+            || superseded(state, record, operation.operationId) || nativeBusy(state, operation.operationId))
+            throw new Error('skill_activation_source_unavailable');
+    };
+    assertCurrent();
+    await assertOperationDirectoryAccess(state, operation, 'exclusive');
+    await verifyActivationPermission(state, record);
+    assertCurrent();
+    await verifyPrepared(root, record.selection);
+    const result = await activatePreparedSkillSelection(root, record.selection, { expectedLockHash: record.expectedLockHash,
+        expectedDeclarationHash: record.expectedDeclarationHash, transactionId: record.requestId,
+        transactionDirectory: join(await directory(state), 'transactions'), assertCurrent: async () => {
+            assertCurrent();
+            await assertOperationDirectoryAccess(state, operation, 'exclusive');
+            await verifyActivationPermission(state, record);
+            assertCurrent();
+        } });
+    await change(state, record.requestId, { status: 'dispatched', targetLockHash: result.lockHash });
+    await state.journal.allocateSourceEvent({ runtimeId: state.config.runtimeId, generation: state.config.generation, runtimeEpoch: state.runtimeEpoch,
+        type: 'skills.activation.applied', occurredAt: new Date().toISOString(), workspaceId: record.workspaceId,
+        sessionId: record.sourceSessionId, operationId: operation.operationId, payload: { requestId: record.requestId, selectionId: record.selectionId, lockHash: result.lockHash } });
+    wakeSourceEventUploader(state);
+    const catalog = await readLockedProjectSkillCatalog(root, join(state.config.stateDir, 'skill-artifacts'));
+    if (catalog.lockHash !== result.lockHash)
+        throw new Error('skill_activation_selection_changed');
+    const byRef = new Map(catalog.skills.map(skill => [skill.skillRef, skill]));
+    const skills = record.requestedSkillRefs.map(ref => {
+        const skill = byRef.get(ref);
+        if (!skill)
+            throw new Error('skill_activation_selection_invalid');
+        return { entryKey: skill.entryKey, skillRef: skill.skillRef, revision: skill.revision, path: skill.path };
+    });
+    const selected = [...catalog.skills.filter(skill => record.selection.skills.some(selected => selected.skillRef === skill.skillRef)
+            && skillRequiresExclusiveTurn(skill.skillRef)), ...skills]
+        .filter((skill, index, items) => skill.entryKey.length <= 128 && items.findIndex(item => item.entryKey === skill.entryKey) === index).slice(0, 8)
+        .map(skill => ({ entryKey: skill.entryKey, lockHash: result.lockHash }));
+    return { ...result, entries: selected,
+        instructions: [
+            'The selected exact skills are now activated. Continue the user\'s original task from the current progress, preserve completed modifications, and read these newly locked SKILL.md files before using each skill. Do not request another continuation for this same selection.',
+            ...skills.map(({ skillRef, revision, path }) => JSON.stringify({ skillRef, revision, path })),
+        ].join('\n') };
+}
+/** Called while holding native-preparation: existing turns may finish, new starts cannot overtake activation. */
+export async function waitForSkillActivationIdle(state, operation, input) {
+    const controller = new AbortController(), active = waiters.get(state) ?? new Map();
+    active.set(operation.operationId, { sessionId: operation.sessionId, controller });
+    waiters.set(state, active);
+    try {
+        await new Promise((resolveWait, reject) => {
+            let unsubscribe = () => { };
+            const finish = (error) => { unsubscribe(); controller.signal.removeEventListener('abort', abort); error ? reject(error) : resolveWait(); };
+            const abort = () => finish(new Error('skill_activation_cancelled'));
+            const check = () => {
+                const source = state.journal.getOperationById(input.sourceOperationId);
+                if (closing.has(state) || state.journal.destroyed() || operation.runtimeEpoch !== state.runtimeEpoch
+                    || operation.generation !== state.config.generation || (operation.leaseFence ?? 0) < state.acceptedLeaseFence
+                    || !source || source.status !== 'completed' || source.sessionId !== input.sourceSessionId
+                    || source.nativeThreadId !== input.sourceThreadId || source.nativeTurnId !== input.sourceTurnId) {
+                    finish(new Error('skill_activation_source_unavailable'));
+                    return;
+                }
+                if (state.journal.listOperations().some(({ operation: other }) => other.sessionId === input.sourceSessionId
+                    && ['session.turn', 'session.review', 'session.compact'].includes(other.kind)
+                    && other.operationId !== source.operationId && other.operationId !== operation.operationId
+                    && other.clientRequestId !== input.requestId && other.createdAt >= source.createdAt)) {
+                    finish(new Error('skill_activation_source_superseded'));
+                    return;
+                }
+                const live = state.journal.getOperationById(operation.operationId);
+                if (live && ['interrupted', 'failed', 'completed'].includes(live.status)) {
+                    finish(new Error('skill_activation_cancelled'));
+                    return;
+                }
+                if (!nativeBusy(state, operation.operationId))
+                    finish();
+            };
+            unsubscribe = state.journal.onChange(check);
+            controller.signal.addEventListener('abort', abort, { once: true });
+            check();
+        });
+    }
+    finally {
+        active.delete(operation.operationId);
+    }
+}
+export function cancelSkillActivationPreparation(state, operationId) {
+    waiters.get(state)?.get(operationId)?.controller.abort();
+}
+export const skillActivationRuntimeClosing = (state) => closing.has(state);
+/** Retries the same control identity after transport loss; local native receipts always take precedence. */
+export async function drainSkillActivationRequests(state, signal) {
+    for (const record of await listPrivate(state)) {
+        if (state.journal.destroyed() || signal?.aborted)
+            return;
+        if (['completed', 'failed', 'cancelled', 'stale'].includes(record.status))
+            continue;
+        const update = (patch) => change(state, record.requestId, patch);
+        if (record.generation !== state.config.generation || record.runtimeEpoch !== state.runtimeEpoch) {
+            await update({ status: 'stale', error: 'skill_activation_runtime_changed' });
+            continue;
+        }
+        const binding = state.journal.getWorkspace(record.workspaceId);
+        if (!binding || skillActivationBindingHash(binding, record.directoryName) !== record.registrationHash) {
+            await update({ status: 'stale', error: 'skill_activation_binding_changed' });
+            continue;
+        }
+        const source = state.journal.getOperationById(record.sourceOperationId);
+        if (!matchesSource(state, record, source)) {
+            await update({ status: 'stale', error: 'skill_activation_source_unavailable' });
+            continue;
+        }
+        let target;
+        try {
+            target = continuation(state, record);
+        }
+        catch {
+            await update({ status: 'uncertain', error: 'skill_activation_operation_ambiguous' });
+            continue;
+        }
+        if (target) {
+            await applyContinuationReceipt(state, record, target);
+            continue;
+        }
+        if (source.status === 'failed' || source.status === 'interrupted') {
+            await update({ status: 'cancelled', error: 'skill_activation_source_stopped' });
+            continue;
+        }
+        if (source.status === 'uncertain') {
+            await update({ status: 'uncertain', error: 'skill_activation_source_uncertain' });
+            continue;
+        }
+        if (source.status !== 'completed')
+            continue;
+        if (superseded(state, record)) {
+            await update({ status: 'stale', error: 'skill_activation_source_superseded' });
+            continue;
+        }
+        if (record.status === 'uncertain' && record.error !== 'skill_activation_source_uncertain')
+            continue;
+        if (busy(state)) {
+            await update({ status: 'queued', error: undefined });
+            continue;
+        }
+        if (await batchDirectoryHeld(state, record.workspaceId, record.directoryName)) {
+            await update({ status: 'queued', error: undefined });
+            continue;
+        }
+        await update({ status: 'queued' });
+        try {
+            const response = await fetch(platformEndpoint(state.config.publicBaseUrl, '/runtime/internal/skill-activation-requests/dispatch'), {
+                method: 'POST', redirect: 'error', signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
+                headers: { authorization: `Bearer ${state.config.controlToken}`, 'content-type': 'application/json', 'playcraft-env': state.config.environment },
+                body: JSON.stringify(dispatchBody(state, record)),
+            });
+            const result = await response.json().catch(() => ({}));
+            const reason = result.code ?? result.reason ?? result.message;
+            if (response.ok && typeof result.operationId === 'string') {
+                await update({ status: result.status === 'uncertain' ? 'uncertain' : result.status === 'failed' || result.status === 'interrupted' ? 'failed' : 'dispatched',
+                    operationId: result.operationId, error: result.status === 'uncertain' ? 'skill_activation_continuation_uncertain' : undefined });
+            }
+            else if (reason === 'uncertain_operation' || reason === 'skill_activation_request_uncertain')
+                await update({ status: 'uncertain', error: 'skill_activation_continuation_uncertain' });
+            else if (reason === 'skill_activation_source_superseded')
+                await update({ status: 'stale', error: reason });
+            else if (response.status < 500 && response.status !== 409)
+                await update({ status: 'failed', error: 'skill_activation_dispatch_denied' });
+            else
+                await update({ status: 'queued', error: 'skill_activation_control_unavailable' });
+        }
+        catch {
+            if (!signal?.aborted)
+                await update({ status: 'queued', error: 'skill_activation_control_unavailable' });
+        }
+    }
+}
+export function startSkillActivationRequestQueue(state) {
+    if (loops.has(state))
+        return;
+    closing.delete(state);
+    const loop = { running: false, closed: false, controller: new AbortController(),
+        timer: setInterval(() => wakeSkillActivationRequests(state), 2_000), unsubscribe: () => { } };
+    loop.timer.unref?.();
+    loops.set(state, loop);
+    loop.unsubscribe = state.journal.onChange(() => wakeSkillActivationRequests(state));
+    wakeSkillActivationRequests(state);
+}
+export async function stopSkillActivationRequestQueue(state) {
+    closing.add(state);
+    for (const waiter of waiters.get(state)?.values() ?? [])
+        waiter.controller.abort();
+    const loop = loops.get(state);
+    if (!loop)
+        return;
+    loop.closed = true;
+    loop.controller.abort();
+    clearInterval(loop.timer);
+    loop.unsubscribe();
+    loops.delete(state);
+    await loop.done;
+}
+export function wakeSkillActivationRequests(state) {
+    const loop = loops.get(state);
+    if (!loop || loop.closed || loop.running)
+        return;
+    loop.running = true;
+    loop.done = new Promise(done => {
+        setTimeout(() => {
+            void drainSkillActivationRequests(state, loop.controller.signal).catch(() => undefined)
+                .finally(() => { loop.running = false; done(); });
+        }, 0).unref?.();
+    });
+}