evolcore 0.0.29 → 0.0.30

package/dist/core/daemon-control.js

@@ -0,0 +1,205 @@
+import fs from 'fs';
+import path from 'path';
+import { AUNChannel } from '../channels/aun.js';
+import { startServiceProxy } from '../aun/service-proxy.js';
+import { remoteAccessService } from './auth/remote-access-store.js';
+import { authorizationDenialData, formatAuthorizationDenial } from './auth/authorization-denial.js';
+import { controlReplyContext } from './message/outbound.js';
+import { enforceMenuResponseSize, evaluateMenuClientCompatibility, evolMenuResponseTransportMetadata, hasValidMenuId, logMenuRequestCompleted, logMenuRequestReceived, MENU_RESPONSE_MAX_BYTES, MENU_RESPONSE_SAFETY_MARGIN_BYTES, MenuRequestDeduper, menuFailure, menuPayloadFingerprint, normalizeMenuResponseTiming, parseMenuControl, validateMenuRequest, withMenuProcessingTime, } from './command/menu-protocol.js';
+import { isProcessLevelOwner } from './command/command-handler.js';
+import { onShutdown } from '../utils/cross-platform.js';
+import { logger } from '../utils/logger.js';
+import { resolvePaths } from '../paths.js';
+const controlMenuDeduper = new MenuRequestDeduper();
+export function startDaemonControlAid({ daemonCfg, cmdHandler, bindService, diagService, getProcessOwners, }) {
+    if (!daemonCfg.aid)
+        return undefined;
+    const aunPath = resolvePaths().root;
+    const certKey = path.join(aunPath, 'AIDs', daemonCfg.aid, 'private', 'key.json');
+    if (!fs.existsSync(certKey)) {
+        logger.warn(`控制 AID 证书缺失：${daemonCfg.aid}（AUN 控制通道后台重连；如需重建运行 ec init）`);
+    }
+    const controlChannel = new AUNChannel({
+        aid: daemonCfg.aid,
+        agentName: daemonCfg.aid,
+        channelName: 'control',
+        pureIdentity: true,
+        defaultEncrypt: daemonCfg.aun?.defaultEncrypt,
+        aunTrace: daemonCfg.debug?.aunTrace,
+        aunSdkLog: daemonCfg.debug?.aunSdkLog,
+    });
+    const controlConnectPromise = controlChannel.connect()
+        .then(() => {
+        logger.info(`✓ 控制 AID 已连接: ${daemonCfg.aid}`);
+    })
+        .catch((e) => {
+        logger.warn(`控制 AID 首连失败（后台自动重连，不影响 daemon 主流程）: ${e?.message || e}`);
+    });
+    controlChannel.onMessage(async (opts) => {
+        let activeMenuRequest;
+        let menuCompletionLogged = false;
+        const menuFlowContext = {
+            source: 'control-aun',
+            selfAid: daemonCfg.aid,
+            messageId: opts.messageId,
+            requesterAid: opts.peerId,
+            authMethod: opts.protectedHeaders?.auth_method === 'remote-access-token' || opts.protectedHeaders?.auth_method === 'ecweb-token'
+                ? opts.protectedHeaders.auth_method
+                : 'daemon-owner',
+            clientName: opts.protectedHeaders?.client_name ?? 'evol',
+        };
+        try {
+            const menuTiming = normalizeMenuResponseTiming(opts);
+            const text = (opts.content || '').trim();
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                parsed = null;
+            }
+            const menuResponseContext = () => ({
+                ...controlReplyContext(opts, evolMenuResponseTransportMetadata(opts.protectedHeaders?.sdk_version, opts.protectedHeaders?.menu_volatile_v1)),
+                ...(opts.peerDeviceId ? { toDeviceId: opts.peerDeviceId } : {}),
+            });
+            const sendControlMenuResponse = async (response) => {
+                const timedResponse = withMenuProcessingTime(enforceMenuResponseSize(response, MENU_RESPONSE_MAX_BYTES - MENU_RESPONSE_SAFETY_MARGIN_BYTES), menuTiming);
+                const request = activeMenuRequest ?? {
+                    type: 'menu.unknown',
+                    id: response.id,
+                    ...(response.name ? { name: response.name } : {}),
+                };
+                try {
+                    await controlChannel.sendStructuredOrThrow(opts.channelId, timedResponse, menuResponseContext());
+                    logMenuRequestCompleted(request, timedResponse, menuFlowContext, { delivery: 'sent' });
+                    menuCompletionLogged = true;
+                }
+                catch (error) {
+                    logMenuRequestCompleted(request, timedResponse, menuFlowContext, {
+                        delivery: 'failed',
+                        reason: 'transport-error',
+                        transportError: error,
+                    });
+                    menuCompletionLogged = true;
+                    throw error;
+                }
+            };
+            if (bindService && parsed?.type === 'bind.request') {
+                const response = await bindService.handleRequest(parsed, opts.peerId);
+                if (response) {
+                    await controlChannel.sendStructuredOrThrow(opts.channelId, response, controlReplyContext(opts));
+                }
+                return;
+            }
+            const menuControl = parseMenuControl(text);
+            if (menuControl.isMenu) {
+                activeMenuRequest = menuControl.request;
+                logMenuRequestReceived(menuControl.request, menuFlowContext);
+            }
+            const isRoleMenu = menuControl.isMenu
+                && (menuControl.name === 'role' || menuControl.request.cmd === '/role');
+            const currentProcessOwners = getProcessOwners();
+            if (/^\/diag(?:\s|$)/i.test(text)) {
+                const command = text.slice(5).trim();
+                const result = await diagService.execute(command.toLowerCase() === 'stop'
+                    ? { action: 'stop' } : { action: 'start', problem: command }, opts.peerId);
+                await controlChannel.sendMessage(opts.channelId, result.message, controlReplyContext(opts));
+                return;
+            }
+            if (menuControl.isMenu && !hasValidMenuId(menuControl)) {
+                logger.warn(`[ControlMenu] dropped malformed request without id type=${menuControl.type}`);
+                logMenuRequestCompleted(menuControl.request, undefined, menuFlowContext, {
+                    delivery: 'dropped',
+                    reason: 'missing-id',
+                });
+                menuCompletionLogged = true;
+                return;
+            }
+            const menuClientCompatibilityError = menuControl.isMenu
+                ? evaluateMenuClientCompatibility({ encrypted: opts.encrypted, protectedHeaders: opts.protectedHeaders })
+                : null;
+            if (menuControl.isMenu && menuClientCompatibilityError) {
+                await sendControlMenuResponse(menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, menuClientCompatibilityError));
+                return;
+            }
+            const protectedMenuHeaders = opts.protectedHeaders;
+            const hasRemoteAccessToken = protectedMenuHeaders?.auth_method === 'remote-access-token'
+                || protectedMenuHeaders?.auth_method === 'ecweb-token';
+            if (text.toLowerCase() === '/pair' && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                logger.debug(`控制 AID 收到非 owner 配对请求，忽略: from=${opts.peerId}`);
+                return;
+            }
+            if (menuControl.isMenu && !isRoleMenu && !hasRemoteAccessToken && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                const response = menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, {
+                    code: 'NOT_ALLOWED',
+                    message: formatAuthorizationDenial('Control-channel process operations require DaemonOwner.', 'DAEMON_OWNER_REQUIRED'),
+                    data: authorizationDenialData('DAEMON_OWNER_REQUIRED'),
+                });
+                await sendControlMenuResponse(response);
+                return;
+            }
+            if (!isRoleMenu && !hasRemoteAccessToken && !isProcessLevelOwner(opts.peerId, currentProcessOwners)) {
+                logger.debug(`控制 AID 收到非 owner 消息，忽略: from=${opts.peerId}`);
+                return;
+            }
+            if (text.toLowerCase() === '/pair') {
+                const pair = remoteAccessService.getPairingCode(opts.peerId, Date.now(), 'pair');
+                const mins = Math.max(0, Math.round((pair.expiresAt - Date.now()) / 60000));
+                const reply = `远程控制配对码：${pair.code}（约 ${mins} 分钟内有效，仅可配对一次）`;
+                await controlChannel.sendMessage(opts.channelId, reply, controlReplyContext(opts));
+                return;
+            }
+            if (menuControl.isMenu) {
+                const validationError = validateMenuRequest(menuControl.request);
+                if (validationError) {
+                    await sendControlMenuResponse(menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, validationError));
+                    return;
+                }
+                const deduped = await controlMenuDeduper.execute([opts.channelId, opts.peerId, opts.peerDeviceId || '', menuControl.id].join('\u001f'), menuPayloadFingerprint(menuControl.raw), () => cmdHandler.execMenuForControl(parsed, opts.peerId, {
+                    encrypted: opts.encrypted,
+                    protectedHeaders: opts.protectedHeaders,
+                }));
+                if ('retry' in deduped) {
+                    if (deduped.replayed) {
+                        logger.warn(`[MenuControl] category=request-replay request=${menuControl.id}`
+                            + ` sender=${opts.peerId} replay=true`);
+                    }
+                    if (deduped.retry) {
+                        logger.warn(`[MenuControl] category=request-retry request=${menuControl.id}`
+                            + ` sender=${opts.peerId} retry=true`);
+                    }
+                }
+                const response = 'conflict' in deduped
+                    ? menuFailure({ id: menuControl.id, ...(menuControl.name?.trim() ? { name: menuControl.name } : {}) }, { code: 'CONFLICT', message: 'Request ID was already used with a different payload' })
+                    : deduped.value;
+                await sendControlMenuResponse(response);
+                return;
+            }
+            await controlChannel.sendMessage(opts.channelId, '可用指令：/pair（获取远程控制配对码）、/diag <问题描述>、/diag stop', controlReplyContext(opts));
+        }
+        catch (e) {
+            if (activeMenuRequest && !menuCompletionLogged) {
+                logMenuRequestCompleted(activeMenuRequest, undefined, menuFlowContext, {
+                    delivery: 'failed',
+                    reason: 'handler-error',
+                    transportError: e,
+                });
+            }
+            logger.warn(`控制 AID 消息处理失败: ${e?.message || e}`);
+        }
+    });
+    void controlConnectPromise;
+    const proxyServices = (daemonCfg.services ?? []).filter((service) => service.enabled === true && service.proxy?.enabled === true);
+    if (proxyServices.length > 0) {
+        const channel = controlChannel;
+        const aid = daemonCfg.aid;
+        const config = proxyServices;
+        setTimeout(() => {
+            const proxyHandle = startServiceProxy(channel, aid, config);
+            if (proxyHandle) {
+                onShutdown(() => proxyHandle.stop());
+            }
+        }, 500);
+    }
+    return controlChannel;
+}

package/dist/core/daemon-lifecycle.js

@@ -0,0 +1,225 @@
+import { tryParseChannelKey } from './channel-loader.js';
+import { replyContextFromSession } from './message/message-utils.js';
+import { logger } from '../utils/logger.js';
+import fs from 'fs';
+import { disposeAgentInstances } from './runner-reload-transaction.js';
+export function daemonIdleTimeoutMs(settings) {
+    const idleTimeoutSec = settings.idleMonitor?.timeout;
+    return typeof idleTimeoutSec === 'number' && Number.isFinite(idleTimeoutSec) && idleTimeoutSec > 0
+        ? idleTimeoutSec * 1000
+        : 120_000;
+}
+export function daemonConversationWatchdogMs(settings) {
+    const idleMs = daemonIdleTimeoutMs(settings);
+    return Math.ceil(idleMs * 5 + 60_000);
+}
+export function daemonConversationTotalExecutionMs(settings) {
+    const seconds = settings.idleMonitor?.maxExecutionTime;
+    return typeof seconds === 'number' && Number.isFinite(seconds) && seconds > 0
+        ? seconds * 1000
+        : undefined;
+}
+export async function cleanupStartupHandoffs(recoveryAids, handoffRuntime) {
+    for (const aid of recoveryAids) {
+        try {
+            const discarded = await handoffRuntime.discardExpired([aid]);
+            if (discarded > 0)
+                logger.info(`[Handoff] discarded ${discarded} expired handoff(s) for ${aid}`);
+            const expired = handoffRuntime.expireQueued([aid]);
+            if (expired > 0)
+                logger.info(`[Handoff] expired ${expired} stale queued delivery item(s) for ${aid}`);
+        }
+        catch (error) {
+            logger.error(`[Handoff] startup TTL cleanup failed for ${aid}:`, error);
+        }
+    }
+}
+export async function recoverStartupHandoffs({ channelInstances, recoveryAids, agentRegistry, queuePendingObserverHints, startupObserverRecoveries, handoffRuntime, setRestoringStartupQueue, startRestoredQueue, }) {
+    try {
+        for (const inst of channelInstances) {
+            if (inst.channelType !== 'aun')
+                continue;
+            const agent = agentRegistry.resolveByChannel(inst.adapter.channelKey);
+            if (agent && recoveryAids.includes(agent.aid)) {
+                startupObserverRecoveries.push(...queuePendingObserverHints(agent.aid, inst.adapter.channelKey));
+            }
+        }
+        await Promise.all(startupObserverRecoveries);
+        const outcomes = await Promise.allSettled(recoveryAids.map(aid => handoffRuntime.recover([aid])));
+        outcomes.forEach((outcome, index) => {
+            if (outcome.status === 'rejected') {
+                logger.error(`[Handoff] startup recovery failed for ${recoveryAids[index]}:`, outcome.reason);
+            }
+        });
+    }
+    finally {
+        setRestoringStartupQueue(false);
+        startupObserverRecoveries.length = 0;
+        startRestoredQueue();
+    }
+}
+export function resumePendingSessions({ sessionManager, messageQueue, droppedTriggerSessionIds, agentRegistry, agentMap, }) {
+    const pendingSessions = sessionManager.getPendingProcessingSessions();
+    if (pendingSessions.length === 0)
+        return;
+    logger.info(`[Resume] Found ${pendingSessions.length} pending session(s) from before restart`);
+    for (const session of pendingSessions) {
+        if (droppedTriggerSessionIds.has(session.id)) {
+            if (messageQueue.isProcessing(session.id) || messageQueue.getQueueLength(session.id) > 0) {
+                logger.info(`[Resume] session ${session.id}: Trigger scheduler already reclaimed execution, skipping generic resume`);
+            }
+            else {
+                logger.info(`[Resume] session ${session.id}: dropped stale Trigger execution was not reclaimable, clearing processing`);
+                sessionManager.clearProcessing(session.id);
+            }
+            continue;
+        }
+        if (messageQueue.isProcessing(session.id) || messageQueue.getQueueLength(session.id) > 0) {
+            logger.info(`[Resume] session ${session.id}: persisted queue already restored, skipping generic resume`);
+            continue;
+        }
+        if (!session.agentSessionId) {
+            sessionManager.clearProcessing(session.id);
+            continue;
+        }
+        const owningAgent = agentRegistry.resolveByChannel(session.channel);
+        if (!owningAgent) {
+            logger.warn(`[Resume] session ${session.id}: channel "${session.channel}" not routable, skipping`);
+            sessionManager.clearProcessing(session.id);
+            continue;
+        }
+        const evolName = owningAgent.aid;
+        const baseagentName = typeof session.baseagent === 'string' ? session.baseagent.trim() : '';
+        if (!baseagentName) {
+            logger.error(`[Resume] session ${session.id}: missing baseagent binding, refusing implicit runner fallback`);
+            sessionManager.clearProcessing(session.id);
+            continue;
+        }
+        const agent = agentMap.get(`${evolName}::${baseagentName}`);
+        if (!agent) {
+            logger.error(`[Resume] session ${session.id}: runner unavailable for ${evolName}::${baseagentName}; refusing fallback`);
+            sessionManager.clearProcessing(session.id);
+            continue;
+        }
+        logger.info(`[Resume] Resuming session: ${session.id} (agent: ${evolName}::${baseagentName})`);
+        const parsedResumeKey = tryParseChannelKey(session.channel);
+        const resumeSelfAID = session.selfAID || parsedResumeKey?.selfAID;
+        const resumeMessage = {
+            channel: session.channel,
+            channelType: session.channelType || parsedResumeKey?.type,
+            selfAID: resumeSelfAID,
+            channelId: session.channelId,
+            groupId: session.chatType === 'group' ? (session.metadata?.groupId || session.channelId) : undefined,
+            chatType: session.chatType === 'group' ? 'group' : 'private',
+            content: '服务已重启，请继续之前未完成的任务。',
+            timestamp: Date.now(),
+            peerId: '',
+            threadId: session.threadId || undefined,
+            replyContext: replyContextFromSession(session),
+        };
+        sessionManager.clearProcessing(session.id);
+        messageQueue.enqueue(session.id, resumeMessage, session.projectPath, {
+            sessionKeyField: session.sessionKey,
+            selfAID: resumeSelfAID,
+        }).catch(error => {
+            logger.error(`[Resume] Failed to resume session ${session.id}:`, error);
+        });
+    }
+}
+export function createDaemonShutdown({ ipcServer, readySignalPath, bindService, ecwebSupervisor, messageQueue, permissionGateway, removePermissionConfigListener, stopStatsPersistence, triggerSchedulers, agentMap, eventBus, removeGroupInviteConfigListener, groupInviteReviewService, channelLoader, channelInstances, controlChannel, sessionManager, removeAll, exit, }) {
+    let shutdownSignal = 'unknown';
+    let shutdownInProgress = false;
+    return async (signal) => {
+        if (shutdownInProgress)
+            return;
+        shutdownInProgress = true;
+        if (signal)
+            shutdownSignal = signal;
+        const pid = process.pid;
+        const ppid = process.ppid;
+        logger.info(`\n\nShutting down gracefully... (signal=${shutdownSignal}, pid=${pid}, ppid=${ppid})`);
+        ipcServer.stopCpuTracking();
+        ipcServer.stop();
+        try {
+            fs.unlinkSync(readySignalPath);
+        }
+        catch { }
+        bindService?.stopCleanup();
+        const shutdownStep = async (label, operation) => {
+            try {
+                await operation();
+            }
+            catch (error) {
+                logger.error(`[Shutdown] ${label} failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        };
+        try {
+            await shutdownStep('stop ECWeb supervisor', async () => {
+                await ecwebSupervisor?.stop();
+            });
+            const queueShutdown = messageQueue.shutdownGracefully();
+            await shutdownStep('cancel pending permissions', () => permissionGateway.cancelAllPending('daemon_restart'));
+            await shutdownStep('wait for trigger schedulers', async () => {
+                await triggerSchedulers.waitForIdle(5_000);
+            });
+            await shutdownStep('suspend trigger schedulers', async () => {
+                await triggerSchedulers.suspendForDaemonExit();
+            });
+            await shutdownStep('interrupt active message queue tasks', async () => { await queueShutdown; });
+            await shutdownStep('dispose agent runners', async () => {
+                const currentInstances = [...agentMap.entries()].map(([key, agent]) => {
+                    const split = key.lastIndexOf('::');
+                    return {
+                        evolagentName: split > 0 ? key.slice(0, split) : '<unknown>',
+                        baseagent: split > 0 ? key.slice(split + 2) : 'unknown',
+                        agent,
+                    };
+                });
+                await disposeAgentInstances(currentInstances, (instance, error) => {
+                    logger.warn(`[Shutdown] Failed to dispose runner ${instance.evolagentName}::${instance.baseagent}: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            });
+            eventBus.publish({ type: 'system:shutdown', timestamp: Date.now() });
+            removeGroupInviteConfigListener();
+            await shutdownStep('stop group invitation review', () => groupInviteReviewService.dispose());
+            await shutdownStep('stop global skill watcher', async () => {
+                const { stopGlobalSkillWatcher } = await import('./skill/global-watcher.js');
+                await stopGlobalSkillWatcher();
+            });
+            await shutdownStep('disconnect channels', () => channelLoader.disconnectAll(channelInstances));
+            for (const instance of channelInstances) {
+                const type = instance.channelType || instance.adapter.channelName;
+                eventBus.publish({
+                    type: 'channel:disconnected',
+                    channel: type,
+                    channelName: instance.adapter.channelName,
+                    reason: 'shutdown',
+                });
+            }
+            if (controlChannel) {
+                await shutdownStep('disconnect control AID', () => controlChannel?.disconnect());
+            }
+        }
+        catch (error) {
+            logger.error(`[Shutdown] Unexpected shutdown failure: ${error instanceof Error ? error.stack || error.message : String(error)}`);
+        }
+        finally {
+            await shutdownStep('remove permission config listener', () => removePermissionConfigListener?.());
+            await shutdownStep('stop stats persistence', () => stopStatsPersistence?.());
+            try {
+                sessionManager.close();
+            }
+            catch (error) {
+                logger.error(`[Shutdown] session manager close failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            try {
+                removeAll();
+            }
+            catch (error) {
+                logger.error(`[Shutdown] instance cleanup failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            logger.info('✓ Shutdown complete');
+            exit(0);
+        }
+    };
+}

package/dist/core/data-migration.js

@@ -1197,7 +1197,10 @@ export function finalizeDataMigration(root, manifest) {
     }
     for (const source of liveSources)
         fs.rmSync(source, { recursive: true, force: false });
-    pruneEmptyLegacyParents(root, liveSources);
+    const discardedSources = manifest.operations
+        .filter(operation => operation.kind === 'discard')
+        .map(operation => operation.source);
+    pruneEmptyLegacyParents(root, [...absoluteSources, ...discardedSources]);
     const finalization = {
         schemaVersion: 1,
         migrationId: manifest.id,

package/dist/core/handoff/ipc-registration.js

@@ -0,0 +1,156 @@
+import { isManagementRole } from '../../config/builtin-roles.js';
+import { hasTrustedFullAccessDelegation, trustedExecutionIdentityInput, } from '../auth/agent-delegation.js';
+import { authorizeOperation, buildAuthSubject } from '../auth/auth-gateway.js';
+import { parsePeerKey } from '../relation/peer-identity.js';
+export function registerHandoffIpc({ ipcServer, agentDelegationRegistry, responseEngine, sessionManager, agentRegistry, handoffRuntime, getProcessOwners, }) {
+    const resolveManagedHandoffScope = async (params, operation) => {
+        const delegation = agentDelegationRegistry.validate(params.delegationToken, params.sessionId, params.delegationCommandHash);
+        if (!delegation.ok)
+            return { ok: false, code: delegation.code, error: delegation.reason };
+        const runtime = responseEngine.getTaskRuntimeContext(params.sessionId);
+        const session = await sessionManager.getSessionById(params.sessionId);
+        const selfAid = runtime?.selfAid || session?.selfAID;
+        if (!selfAid || !session) {
+            return { ok: false, code: 'HANDOFF_CALL_SESSION_INVALID', error: 'current session is invalid' };
+        }
+        if (delegation.grant.selfAid !== selfAid) {
+            return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation self agent does not match current session' };
+        }
+        if (params.agent && params.agent !== selfAid && !hasTrustedFullAccessDelegation(delegation.grant)) {
+            return { ok: false, code: 'HANDOFF_AGENT_SCOPE_MISMATCH', error: 'agent does not match the current session' };
+        }
+        let conversationId;
+        try {
+            conversationId = parsePeerKey(delegation.grant.peerKey).channelId;
+        }
+        catch {
+            return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation contains an invalid relation key' };
+        }
+        const subject = buildAuthSubject({
+            selfAid,
+            actorId: delegation.grant.actorId,
+            channel: delegation.grant.channel,
+            channelType: delegation.grant.channelType,
+            channelId: conversationId,
+            chatType: delegation.grant.chatType,
+            conversationId,
+            processOwners: getProcessOwners(),
+            ...trustedExecutionIdentityInput(delegation.grant),
+        });
+        const managementRole = isManagementRole(subject.role) || subject.dataScope === 'daemon';
+        const decision = authorizeOperation({
+            source: 'agent-tool',
+            subject,
+            intent: {
+                operation,
+                scope: managementRole ? 'agent' : 'relation',
+                source: 'agent-tool',
+                args: {
+                    self: selfAid,
+                    peer: conversationId,
+                    peerKey: delegation.grant.peerKey,
+                },
+            },
+            auditMetadata: { taskId: delegation.grant.taskId, messageId: delegation.grant.messageId },
+        });
+        if (!decision.allow) {
+            return {
+                ok: false,
+                code: decision.command?.code ?? 'ROLE_ACCESS_DENIED',
+                error: decision.reason,
+            };
+        }
+        return {
+            ok: true,
+            aid: selfAid,
+            currentSessionId: params.sessionId,
+            managementRole,
+            role: subject.role,
+            actorId: delegation.grant.actorId,
+        };
+    };
+    const resolveHandoffQueryScope = async (params, operation) => {
+        if (params.sessionId) {
+            return resolveManagedHandoffScope({ ...params, sessionId: params.sessionId }, operation);
+        }
+        if (!params.agent) {
+            return { ok: false, code: 'HANDOFF_AGENT_REQUIRED', error: '--agent is required outside a task context' };
+        }
+        if (!agentRegistry.get(params.agent)) {
+            return { ok: false, code: 'HANDOFF_AGENT_NOT_FOUND', error: `agent not found: ${params.agent}` };
+        }
+        return { ok: true, aid: params.agent, currentSessionId: undefined, managementRole: true };
+    };
+    const returnHandoff = async (params) => {
+        if (!params.sessionId)
+            return responseEngine.returnHandoffResult(params);
+        const scope = await resolveManagedHandoffScope({ ...params, sessionId: params.sessionId }, 'ec.handoff.return');
+        if (!scope.ok)
+            return scope;
+        return responseEngine.returnAuthorizedHandoffResult({ sessionId: params.sessionId, handoffId: params.handoffId, content: params.content }, scope.aid);
+    };
+    const recoverHandoff = async (params) => {
+        if (!params.sessionId)
+            return { ok: false, code: 'HANDOFF_CALL_SESSION_INVALID', error: 'current session is required' };
+        const scope = await resolveManagedHandoffScope({ ...params, sessionId: params.sessionId }, 'ec.handoff.recover');
+        if (!scope.ok)
+            return scope;
+        if (scope.role !== 'owner') {
+            return { ok: false, code: 'ROLE_ACCESS_DENIED', error: 'handoff recovery requires the current Agent owner' };
+        }
+        return responseEngine.recoverAuthorizedHandoffResult({
+            sessionId: params.sessionId,
+            handoffId: params.handoffId,
+            content: params.content,
+            actorId: scope.actorId,
+        }, scope.aid);
+    };
+    const statusHandoff = async (params) => {
+        const scope = await resolveHandoffQueryScope(params, 'ec.handoff.status');
+        if (!scope.ok)
+            return scope;
+        const status = handoffRuntime.status(scope.aid, params.handoffId);
+        if (!status)
+            return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
+        if (!scope.managementRole
+            && status.origin_session_id !== scope.currentSessionId
+            && status.target_session_id !== scope.currentSessionId) {
+            return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found in the current session' };
+        }
+        return status;
+    };
+    const listHandoff = async (params) => {
+        const scope = await resolveHandoffQueryScope(params, 'ec.handoff.list');
+        if (!scope.ok)
+            return scope;
+        if (!scope.managementRole && params.filterSessionId && params.filterSessionId !== scope.currentSessionId) {
+            return { ok: false, code: 'HANDOFF_SESSION_SCOPE_MISMATCH', error: 'only the current session can be queried' };
+        }
+        return handoffRuntime.listHandoffs({
+            selfAid: scope.aid,
+            state: params.state,
+            sessionId: scope.managementRole ? params.filterSessionId : scope.currentSessionId,
+            limit: params.limit,
+        });
+    };
+    const traceHandoff = async (params) => {
+        const scope = await resolveHandoffQueryScope(params, 'ec.handoff.trace');
+        if (!scope.ok)
+            return scope;
+        if (!scope.managementRole) {
+            const status = handoffRuntime.status(scope.aid, params.handoffId);
+            if (!status
+                || (status.origin_session_id !== scope.currentSessionId
+                    && status.target_session_id !== scope.currentSessionId)) {
+                return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found in the current session' };
+            }
+        }
+        return handoffRuntime.traceHandoff(scope.aid, params.handoffId, params.limit)
+            ?? { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
+    };
+    ipcServer.setHandoffReturnExecutor(returnHandoff);
+    ipcServer.setHandoffRecoverReturnExecutor(recoverHandoff);
+    ipcServer.setHandoffStatusExecutor(statusHandoff);
+    ipcServer.setHandoffListExecutor(listHandoff);
+    ipcServer.setHandoffTraceExecutor(traceHandoff);
+}