@awcp/sdk 0.0.16 → 0.0.18

package/dist/executor/service.js

@@ -2,144 +2,240 @@
  * AWCP Executor Service
  */
 import { EventEmitter } from 'node:events';
-import { generateSnapshotId, PROTOCOL_VERSION, ErrorCodes, AwcpError, CancelledError, } from '@awcp/core';
+import { join } from 'node:path';
+import { AssignmentStateMachine, isTerminalAssignmentState, generateSnapshotId, createAssignment, PROTOCOL_VERSION, ErrorCodes, AwcpError, CancelledError, } from '@awcp/core';
 import { resolveExecutorConfig } from './config.js';
+import { AdmissionController } from './admission.js';
+import { AssignmentManager } from './assignment-manager.js';
 import { WorkspaceManager } from './workspace-manager.js';
 export class ExecutorService {
-    executor;
     config;
     transport;
-    workspace;
-    pendingInvitations = new Map();
-    activeDelegations = new Map();
-    completedDelegations = new Map();
+    executor;
+    admissionController;
+    workspaceManager;
+    assignmentManager;
+    assignments = new Map();
+    stateMachines = new Map();
+    eventEmitters = new Map();
+    cleanupTimer;
     constructor(options) {
-        this.executor = options.executor;
         this.config = resolveExecutorConfig(options.config);
         this.transport = this.config.transport;
-        this.workspace = new WorkspaceManager(this.config.workDir);
+        this.executor = options.executor;
+        this.admissionController = new AdmissionController(this.config.admission);
+        this.workspaceManager = new WorkspaceManager(this.config.workDir);
+        this.assignmentManager = new AssignmentManager({
+            baseDir: join(this.config.workDir, '.awcp', 'assignments'),
+        });
     }
-    async handleMessage(message) {
-        switch (message.type) {
-            case 'INVITE':
-                return this.handleInvite(message);
-            case 'START':
-                await this.handleStart(message);
-                return null;
-            case 'ERROR':
-                await this.handleError(message);
-                return null;
-            default:
-                throw new Error(`Unexpected message type: ${message.type}`);
+    async initialize() {
+        await this.transport.initialize?.(this.config.workDir);
+        if (this.config.cleanupOnInitialize) {
+            const persistedAssignments = await this.assignmentManager.loadAll();
+            for (const assignment of persistedAssignments) {
+                await this.transport.release({ delegationId: assignment.id, localPath: assignment.workPath }).catch(() => { });
+                await this.workspaceManager.release(assignment.workPath);
+                await this.assignmentManager.delete(assignment.id).catch(() => { });
+            }
+            this.startCleanupTimer();
+            return;
+        }
+        const persistedAssignments = await this.assignmentManager.loadAll();
+        const knownIds = new Set(persistedAssignments.map(a => a.id));
+        for (const assignment of persistedAssignments) {
+            this.assignments.set(assignment.id, assignment);
+            this.stateMachines.set(assignment.id, new AssignmentStateMachine(assignment.state));
+            if (!isTerminalAssignmentState(assignment.state)) {
+                this.eventEmitters.set(assignment.id, new EventEmitter());
+            }
         }
+        await this.workspaceManager.cleanupStale(knownIds);
+        this.startCleanupTimer();
     }
-    /**
-     * Subscribe to task events via SSE
-     */
-    subscribeTask(delegationId, callback) {
-        const delegation = this.activeDelegations.get(delegationId);
-        if (!delegation) {
-            const errorEvent = {
-                delegationId,
-                type: 'error',
-                timestamp: new Date().toISOString(),
-                code: 'NOT_FOUND',
-                message: 'Delegation not found',
-            };
-            callback(errorEvent);
-            return () => { };
+    async shutdown() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = undefined;
+        }
+        await this.transport.shutdown?.();
+        this.assignments.clear();
+        this.stateMachines.clear();
+        this.eventEmitters.clear();
+    }
+    async handleMessage(message) {
+        try {
+            switch (message.type) {
+                case 'INVITE':
+                    return await this.handleInvite(message);
+                case 'START':
+                    await this.handleStart(message);
+                    return null;
+                case 'ERROR':
+                    await this.handleError(message);
+                    return null;
+                default:
+                    throw new Error(`Unexpected message type: ${message.type}`);
+            }
+        }
+        catch (error) {
+            if (error instanceof AwcpError) {
+                return this.createErrorMessage(message.delegationId, error.code, error.message, error.hint);
+            }
+            throw error;
         }
-        const handler = (event) => callback(event);
-        delegation.eventEmitter.on('event', handler);
-        return () => {
-            delegation.eventEmitter.off('event', handler);
-        };
     }
     async handleInvite(invite) {
         const { delegationId } = invite;
-        if (this.activeDelegations.size >= this.config.policy.maxConcurrentDelegations) {
-            return this.createErrorMessage(delegationId, ErrorCodes.DECLINED, 'Maximum concurrent delegations reached', 'Try again later when current tasks complete');
+        const existing = this.assignments.get(delegationId);
+        if (existing) {
+            await this.transport.detach({ delegationId, localPath: existing.workPath }).catch(() => { });
+            this.eventEmitters.delete(delegationId);
+            const retentionMs = Math.min(invite.retentionMs, this.config.assignment.maxRetentionMs);
+            existing.state = 'pending';
+            existing.invite = invite;
+            existing.retentionMs = retentionMs;
+            this.stateMachines.set(delegationId, new AssignmentStateMachine());
+            this.eventEmitters.set(delegationId, new EventEmitter());
+            await this.persistAssignment(delegationId);
+            console.log(`[AWCP:Executor] Re-accepting delegation ${delegationId} (was ${existing.state})`);
+            return {
+                version: PROTOCOL_VERSION,
+                type: 'ACCEPT',
+                delegationId,
+                retentionMs,
+                executorWorkDir: { path: existing.workPath },
+                executorConstraints: {
+                    acceptedAccessMode: invite.lease.accessMode,
+                    maxTtlSeconds: Math.min(invite.lease.ttlSeconds, this.config.admission.maxTtlSeconds),
+                    sandboxProfile: this.config.assignment.sandbox,
+                },
+            };
         }
-        const maxTtl = this.config.policy.maxTtlSeconds;
-        if (invite.lease.ttlSeconds > maxTtl) {
-            return this.createErrorMessage(delegationId, ErrorCodes.DECLINED, `Requested TTL (${invite.lease.ttlSeconds}s) exceeds maximum (${maxTtl}s)`, `Request a shorter TTL (max: ${maxTtl}s)`);
+        await this.admissionController.check({ invite, assignments: this.assignments, transport: this.transport });
+        await this.config.hooks.onAdmissionCheck?.(invite);
+        const retentionMs = Math.min(invite.retentionMs, this.config.assignment.maxRetentionMs);
+        const workPath = this.workspaceManager.allocate(delegationId);
+        try {
+            const assignment = createAssignment({ id: delegationId, invite, workPath, retentionMs });
+            this.assignments.set(delegationId, assignment);
+            this.stateMachines.set(delegationId, new AssignmentStateMachine());
+            this.eventEmitters.set(delegationId, new EventEmitter());
+            await this.persistAssignment(delegationId);
+            const executorConstraints = {
+                acceptedAccessMode: invite.lease.accessMode,
+                maxTtlSeconds: Math.min(invite.lease.ttlSeconds, this.config.admission.maxTtlSeconds),
+                sandboxProfile: this.config.assignment.sandbox,
+            };
+            return {
+                version: PROTOCOL_VERSION,
+                type: 'ACCEPT',
+                delegationId,
+                retentionMs,
+                executorWorkDir: { path: workPath },
+                executorConstraints,
+            };
         }
-        const allowedModes = this.config.policy.allowedAccessModes;
-        if (!allowedModes.includes(invite.lease.accessMode)) {
-            return this.createErrorMessage(delegationId, ErrorCodes.DECLINED, `Access mode '${invite.lease.accessMode}' not allowed`, `Allowed modes: ${allowedModes.join(', ')}`);
+        catch (error) {
+            this.assignments.delete(delegationId);
+            this.stateMachines.delete(delegationId);
+            this.eventEmitters.delete(delegationId);
+            await this.workspaceManager.release(workPath);
+            await this.assignmentManager.delete(delegationId).catch(() => { });
+            throw error;
         }
-        const depCheck = await this.transport.checkDependency();
-        if (!depCheck.available) {
-            return this.createErrorMessage(delegationId, ErrorCodes.DEP_MISSING, `Transport ${this.transport.type} is not available`, depCheck.hint);
+    }
+    async handleStart(start) {
+        const { delegationId } = start;
+        const assignment = this.assignments.get(delegationId);
+        if (!assignment) {
+            throw new Error(`Unknown delegation for START: ${delegationId}` +
+                ` (known=[${Array.from(this.assignments.keys()).join(',')}])`);
         }
-        if (this.config.hooks.onInvite) {
-            const accepted = await this.config.hooks.onInvite(invite);
-            if (!accepted) {
-                return this.createErrorMessage(delegationId, ErrorCodes.DECLINED, 'Invitation declined by policy', 'The agent declined this delegation request');
-            }
+        this.transitionState(delegationId, { type: 'RECEIVE_START' });
+        assignment.lease = start.lease;
+        assignment.startedAt = new Date().toISOString();
+        await this.persistAssignment(delegationId);
+        console.log(`[AWCP:Executor] Delegation ${delegationId} started` +
+            ` (active=${Array.from(this.assignments.values()).filter(a => a.state === 'active').length}, workPath=${assignment.workPath})`);
+        this.executeTask(delegationId, start);
+    }
+    async handleError(error) {
+        const { delegationId } = error;
+        const assignment = this.assignments.get(delegationId);
+        if (!assignment) {
+            throw new Error(`Unknown delegation for ERROR: ${delegationId}` +
+                ` (known=[${Array.from(this.assignments.keys()).join(',')}])`);
         }
-        else if (!this.config.policy.autoAccept) {
-            this.pendingInvitations.set(delegationId, {
-                invite,
-                receivedAt: new Date(),
-            });
-            return this.createErrorMessage(delegationId, ErrorCodes.DECLINED, 'Manual acceptance required but no hook provided', 'Configure autoAccept: true or provide onInvite hook');
+        this.transitionState(delegationId, { type: 'RECEIVE_ERROR' });
+        console.log(`[AWCP:Executor] Received ERROR for ${delegationId}: ${error.code} - ${error.message}`);
+        assignment.completedAt = new Date().toISOString();
+        assignment.error = { code: error.code, message: error.message, hint: error.hint };
+        await this.persistAssignment(delegationId);
+        this.config.hooks.onError?.(delegationId, new AwcpError(error.code, error.message, error.hint, delegationId));
+    }
+    subscribeTask(delegationId, callback) {
+        const assignment = this.assignments.get(delegationId);
+        if (!assignment) {
+            console.error(`[AWCP:Executor] SSE subscribe rejected for ${delegationId}: unknown delegation`);
+            const errorEvent = {
+                delegationId, type: 'error', timestamp: new Date().toISOString(),
+                code: 'NOT_FOUND', message: 'Delegation not found on executor',
+            };
+            callback(errorEvent);
+            return () => { };
+        }
+        const sm = this.stateMachines.get(delegationId);
+        if (sm.isTerminal()) {
+            console.log(`[AWCP:Executor] SSE reconnect for ${delegationId}, replaying ${assignment.state} event`);
+            const event = assignment.state === 'completed'
+                ? {
+                    delegationId, type: 'done', timestamp: assignment.completedAt,
+                    summary: assignment.result?.summary ?? 'Task completed',
+                    highlights: assignment.result?.highlights,
+                }
+                : {
+                    delegationId, type: 'error', timestamp: assignment.completedAt,
+                    code: assignment.error?.code ?? ErrorCodes.TASK_FAILED,
+                    message: assignment.error?.message ?? 'Task failed',
+                    hint: assignment.error?.hint,
+                };
+            setImmediate(() => callback(event));
+            return () => { };
         }
-        const workPath = this.workspace.allocate(delegationId);
-        const validation = this.workspace.validate(workPath);
-        if (!validation.valid) {
-            await this.workspace.release(workPath);
-            return this.createErrorMessage(delegationId, ErrorCodes.WORKDIR_DENIED, validation.reason ?? 'Workspace validation failed', 'Check workDir configuration');
+        const emitter = this.eventEmitters.get(delegationId);
+        if (!emitter) {
+            console.error(`[AWCP:Executor] SSE subscribe failed for ${delegationId}: no event emitter`);
+            return () => { };
         }
-        this.pendingInvitations.set(delegationId, {
-            invite,
-            receivedAt: new Date(),
-        });
-        const executorConstraints = {
-            acceptedAccessMode: invite.lease.accessMode,
-            maxTtlSeconds: Math.min(invite.lease.ttlSeconds, maxTtl),
-            sandboxProfile: this.config.sandbox,
-        };
-        const acceptMessage = {
-            version: PROTOCOL_VERSION,
-            type: 'ACCEPT',
-            delegationId,
-            executorWorkDir: { path: workPath },
-            executorConstraints,
+        console.log(`[AWCP:Executor] SSE subscriber attached for ${delegationId} (state=${assignment.state})`);
+        const handler = (event) => callback(event);
+        emitter.on('event', handler);
+        return () => {
+            console.log(`[AWCP:Executor] SSE subscriber detached for ${delegationId}`);
+            emitter.off('event', handler);
         };
-        return acceptMessage;
-    }
-    async handleStart(start) {
-        const { delegationId } = start;
-        const pending = this.pendingInvitations.get(delegationId);
-        if (!pending) {
-            console.warn(`[AWCP:Executor] Unknown delegation for START: ${delegationId}`);
-            return;
-        }
-        const workPath = this.workspace.allocate(delegationId);
-        this.pendingInvitations.delete(delegationId);
-        const eventEmitter = new EventEmitter();
-        this.activeDelegations.set(delegationId, {
-            id: delegationId,
-            workPath,
-            task: pending.invite.task,
-            lease: start.lease,
-            environment: pending.invite.environment,
-            startedAt: new Date(),
-            eventEmitter,
-        });
-        // Task execution runs async - don't await
-        this.executeTask(delegationId, start, workPath, pending.invite.task, start.lease, pending.invite.environment, eventEmitter);
     }
-    async executeTask(delegationId, start, workPath, task, lease, environment, eventEmitter) {
+    async executeTask(delegationId, start) {
+        const assignment = this.assignments.get(delegationId);
+        const emitter = this.eventEmitters.get(delegationId);
         try {
-            await this.workspace.prepare(workPath);
+            console.log(`[AWCP:Executor] Task ${delegationId} preparing workspace...`);
+            await this.workspaceManager.prepare(assignment.workPath);
+            console.log(`[AWCP:Executor] Task ${delegationId} setting up transport (${this.transport.type})...`);
             const actualPath = await this.transport.setup({
                 delegationId,
-                workDirInfo: start.workDir,
-                workDir: workPath,
+                handle: start.transportHandle,
+                localPath: assignment.workPath,
+            });
+            this.config.hooks.onTaskStart?.({
+                delegationId,
+                workPath: actualPath,
+                task: assignment.invite.task,
+                lease: assignment.lease,
+                environment: assignment.invite.environment,
             });
-            this.config.hooks.onTaskStart?.({ delegationId, workPath: actualPath, task, lease, environment });
+            console.log(`[AWCP:Executor] Task ${delegationId} executing (listeners=${emitter.listenerCount('event')})...`);
             const statusEvent = {
                 delegationId,
                 type: 'status',
@@ -147,16 +243,17 @@ export class ExecutorService {
                 status: 'running',
                 message: 'Task execution started',
             };
-            eventEmitter.emit('event', statusEvent);
+            emitter.emit('event', statusEvent);
             const result = await this.executor.execute({
                 delegationId,
                 workPath: actualPath,
-                task,
-                environment,
+                task: assignment.invite.task,
+                environment: assignment.invite.environment,
             });
-            const teardownResult = await this.transport.teardown({ delegationId, workDir: actualPath });
+            console.log(`[AWCP:Executor] Task ${delegationId} completed, capturing snapshot...`);
+            const snapshotResult = await this.transport.captureSnapshot?.({ delegationId, localPath: actualPath });
             const snapshotId = generateSnapshotId();
-            if (teardownResult.snapshotBase64) {
+            if (snapshotResult?.snapshotBase64) {
                 const snapshotEvent = {
                     delegationId,
                     type: 'snapshot',
@@ -164,10 +261,10 @@ export class ExecutorService {
                     snapshotId,
                     summary: result.summary,
                     highlights: result.highlights,
-                    snapshotBase64: teardownResult.snapshotBase64,
+                    snapshotBase64: snapshotResult.snapshotBase64,
                     recommended: true,
                 };
-                eventEmitter.emit('event', snapshotEvent);
+                emitter.emit('event', snapshotEvent);
             }
             const doneEvent = {
                 delegationId,
@@ -175,32 +272,25 @@ export class ExecutorService {
                 timestamp: new Date().toISOString(),
                 summary: result.summary,
                 highlights: result.highlights,
-                snapshotIds: teardownResult.snapshotBase64 ? [snapshotId] : undefined,
-                recommendedSnapshotId: teardownResult.snapshotBase64 ? snapshotId : undefined,
+                snapshotIds: snapshotResult?.snapshotBase64 ? [snapshotId] : undefined,
+                recommendedSnapshotId: snapshotResult?.snapshotBase64 ? snapshotId : undefined,
             };
-            eventEmitter.emit('event', doneEvent);
+            emitter.emit('event', doneEvent);
+            console.log(`[AWCP:Executor] Task ${delegationId} done event emitted` +
+                ` (listeners=${emitter.listenerCount('event')})`);
             this.config.hooks.onTaskComplete?.(delegationId, result.summary);
-            this.completedDelegations.set(delegationId, {
-                id: delegationId,
-                completedAt: new Date(),
-                state: 'completed',
-                snapshot: teardownResult.snapshotBase64 ? {
-                    id: snapshotId,
-                    summary: result.summary,
-                    highlights: result.highlights,
-                    snapshotBase64: teardownResult.snapshotBase64,
-                } : undefined,
-            });
-            this.scheduleResultCleanup(delegationId);
-            this.activeDelegations.delete(delegationId);
-            await this.workspace.release(actualPath);
+            this.transitionState(delegationId, { type: 'TASK_COMPLETE' });
+            assignment.completedAt = new Date().toISOString();
+            assignment.result = {
+                summary: result.summary,
+                highlights: result.highlights,
+                snapshotBase64: snapshotResult?.snapshotBase64,
+            };
+            await this.persistAssignment(delegationId);
+            await this.transport.detach({ delegationId, localPath: assignment.workPath }).catch(() => { });
         }
         catch (error) {
-            const delegation = this.activeDelegations.get(delegationId);
-            if (delegation) {
-                await this.transport.teardown({ delegationId, workDir: delegation.workPath }).catch(() => { });
-                await this.workspace.release(delegation.workPath);
-            }
+            console.error(`[AWCP:Executor] Task ${delegationId} failed:`, error instanceof Error ? error.message : error);
             const errorEvent = {
                 delegationId,
                 type: 'error',
@@ -209,37 +299,30 @@ export class ExecutorService {
                 message: error instanceof Error ? error.message : String(error),
                 hint: 'Check task requirements and try again',
             };
-            eventEmitter.emit('event', errorEvent);
+            emitter.emit('event', errorEvent);
+            console.log(`[AWCP:Executor] Task ${delegationId} error event emitted` +
+                ` (listeners=${emitter.listenerCount('event')})`);
             this.config.hooks.onError?.(delegationId, error instanceof Error ? error : new Error(String(error)));
-            this.completedDelegations.set(delegationId, {
-                id: delegationId,
-                completedAt: new Date(),
-                state: 'error',
-                error: {
-                    code: ErrorCodes.TASK_FAILED,
-                    message: error instanceof Error ? error.message : String(error),
-                    hint: 'Check task requirements and try again',
-                },
-            });
-            this.scheduleResultCleanup(delegationId);
-            this.activeDelegations.delete(delegationId);
-        }
-    }
-    async handleError(error) {
-        const { delegationId } = error;
-        const delegation = this.activeDelegations.get(delegationId);
-        if (delegation) {
-            await this.transport.teardown({ delegationId, workDir: delegation.workPath }).catch(() => { });
-            this.activeDelegations.delete(delegationId);
-            await this.workspace.release(delegation.workPath);
+            this.transitionState(delegationId, { type: 'TASK_FAIL' });
+            assignment.completedAt = new Date().toISOString();
+            assignment.error = {
+                code: ErrorCodes.TASK_FAILED,
+                message: error instanceof Error ? error.message : String(error),
+                hint: 'Check task requirements and try again',
+            };
+            await this.persistAssignment(delegationId);
+            await this.transport.detach({ delegationId, localPath: assignment.workPath }).catch(() => { });
         }
-        this.pendingInvitations.delete(delegationId);
-        this.config.hooks.onError?.(delegationId, new AwcpError(error.code, error.message, error.hint, delegationId));
     }
     async cancelDelegation(delegationId) {
-        const delegation = this.activeDelegations.get(delegationId);
-        if (delegation) {
-            await this.transport.teardown({ delegationId, workDir: delegation.workPath }).catch(() => { });
+        const assignment = this.assignments.get(delegationId);
+        if (!assignment) {
+            throw new Error(`Delegation not found: ${delegationId}`);
+        }
+        this.transitionState(delegationId, { type: 'CANCEL' });
+        console.log(`[AWCP:Executor] Cancelling delegation ${delegationId}`);
+        const emitter = this.eventEmitters.get(delegationId);
+        if (emitter) {
             const errorEvent = {
                 delegationId,
                 type: 'error',
@@ -247,67 +330,98 @@ export class ExecutorService {
                 code: ErrorCodes.CANCELLED,
                 message: 'Delegation cancelled',
             };
-            delegation.eventEmitter.emit('event', errorEvent);
-            this.activeDelegations.delete(delegationId);
-            await this.workspace.release(delegation.workPath);
-            this.config.hooks.onError?.(delegationId, new CancelledError('Delegation cancelled by Delegator', undefined, delegationId));
-            return;
+            emitter.emit('event', errorEvent);
         }
-        if (this.pendingInvitations.has(delegationId)) {
-            this.pendingInvitations.delete(delegationId);
-            return;
-        }
-        throw new Error(`Delegation not found: ${delegationId}`);
+        assignment.completedAt = new Date().toISOString();
+        assignment.error = { code: ErrorCodes.CANCELLED, message: 'Delegation cancelled' };
+        await this.persistAssignment(delegationId);
+        await this.transport.detach({ delegationId, localPath: assignment.workPath }).catch(() => { });
+        this.config.hooks.onError?.(delegationId, new CancelledError('Delegation cancelled by Delegator', undefined, delegationId));
     }
     getStatus() {
+        const active = Array.from(this.assignments.values()).filter(a => a.state === 'active');
         return {
-            pendingInvitations: this.pendingInvitations.size,
-            activeDelegations: this.activeDelegations.size,
-            completedDelegations: this.completedDelegations.size,
-            delegations: Array.from(this.activeDelegations.values()).map((d) => ({
-                id: d.id,
-                workPath: d.workPath,
-                startedAt: d.startedAt.toISOString(),
+            pendingInvitations: Array.from(this.assignments.values()).filter(a => a.state === 'pending').length,
+            activeDelegations: active.length,
+            completedDelegations: Array.from(this.assignments.values()).filter(a => a.state === 'completed' || a.state === 'error').length,
+            delegations: active.map((a) => ({
+                id: a.id,
+                workPath: a.workPath,
+                startedAt: a.startedAt,
             })),
         };
     }
     getTaskResult(delegationId) {
-        const active = this.activeDelegations.get(delegationId);
-        if (active) {
-            return { status: 'running' };
-        }
-        const completed = this.completedDelegations.get(delegationId);
-        if (completed) {
-            if (completed.state === 'completed') {
-                return {
-                    status: 'completed',
-                    completedAt: completed.completedAt.toISOString(),
-                    summary: completed.snapshot?.summary,
-                    highlights: completed.snapshot?.highlights,
-                    snapshotBase64: completed.snapshot?.snapshotBase64,
-                };
+        const assignment = this.assignments.get(delegationId);
+        if (!assignment) {
+            if (this.transport.type === 'sshfs') {
+                return { status: 'not_applicable', reason: 'SSHFS transport writes directly to source' };
             }
-            return {
-                status: 'error',
-                completedAt: completed.completedAt.toISOString(),
-                error: completed.error,
-            };
+            return { status: 'not_found' };
         }
-        if (this.transport.type === 'sshfs') {
+        const sm = this.stateMachines.get(delegationId);
+        if (!sm.isTerminal()) {
+            return { status: 'running' };
+        }
+        if (assignment.state === 'completed') {
             return {
-                status: 'not_applicable',
-                reason: 'SSHFS transport writes directly to source',
+                status: 'completed',
+                completedAt: assignment.completedAt,
+                summary: assignment.result?.summary,
+                highlights: assignment.result?.highlights,
+                snapshotBase64: assignment.result?.snapshotBase64,
             };
         }
-        return { status: 'not_found' };
+        return {
+            status: 'error',
+            completedAt: assignment.completedAt,
+            error: assignment.error,
+        };
     }
     acknowledgeResult(delegationId) {
-        this.completedDelegations.delete(delegationId);
+        const assignment = this.assignments.get(delegationId);
+        const sm = this.stateMachines.get(delegationId);
+        if (assignment && sm?.isTerminal()) {
+            this.assignments.delete(delegationId);
+            this.stateMachines.delete(delegationId);
+            this.eventEmitters.delete(delegationId);
+            this.assignmentManager.delete(delegationId).catch(() => { });
+        }
+    }
+    transitionState(delegationId, event) {
+        const sm = this.stateMachines.get(delegationId);
+        const assignment = this.assignments.get(delegationId);
+        const result = sm.transition(event);
+        if (!result.success) {
+            throw new Error(`Cannot transition assignment ${delegationId} (${event.type}) in state '${assignment.state}': ${result.error}`);
+        }
+        assignment.state = sm.getState();
+        assignment.updatedAt = new Date().toISOString();
     }
-    scheduleResultCleanup(delegationId) {
-        setTimeout(() => {
-            this.completedDelegations.delete(delegationId);
-        }, this.config.policy.resultRetentionMs);
+    async persistAssignment(delegationId) {
+        const assignment = this.assignments.get(delegationId);
+        if (assignment) {
+            await this.assignmentManager.save(assignment);
+        }
+    }
+    startCleanupTimer() {
+        this.cleanupTimer = setInterval(async () => {
+            const now = Date.now();
+            for (const [id, assignment] of this.assignments) {
+                const sm = this.stateMachines.get(id);
+                if (!sm?.isTerminal())
+                    continue;
+                const updatedAt = new Date(assignment.updatedAt).getTime();
+                if (now - updatedAt > assignment.retentionMs) {
+                    await this.transport.release({ delegationId: id, localPath: assignment.workPath }).catch(() => { });
+                    await this.workspaceManager.release(assignment.workPath);
+                    await this.assignmentManager.delete(id).catch(() => { });
+                    this.assignments.delete(id);
+                    this.stateMachines.delete(id);
+                    this.eventEmitters.delete(id);
+                }
+            }
+        }, 60 * 1000);
     }
     createErrorMessage(delegationId, code, message, hint) {
         return {