evolcore 0.0.10 → 0.0.12

package/dist/index.js

@@ -14,7 +14,7 @@ import { CodexSessionFileAdapter } from './core/session/adapters/codex-session-f
 import { GeminiSessionFileAdapter } from './core/session/adapters/gemini-session-file-adapter.js';
 import { EcagentSessionFileAdapter } from './core/session/adapters/ecagent-session-file-adapter.js';
 import { loadDefaults, loadAllAgents, migrateIdentitiesIfNeeded, loadDaemonConfig, initializeEckSnapshotsConfig } from './config-store.js';
-import { ConfigTarget, initConfigManager, onConfigWrite } from './config/config-manager.js';
+import { ConfigTarget, initConfigManager, onConfigWrite, read as readConfig } from './config/config-manager.js';
 import { ensureRoleConfigV4OnStartup } from './config/role-config-v4-startup.js';
 import { ensureRoleConfigV5OnStartup } from './config/role-config-v5-startup.js';
 import { ensureContactBookV2OnStartup } from './config/contact-book-v2-startup.js';
@@ -45,12 +45,12 @@ import { buildEnvelope } from './core/message/message-utils.js';
 import { ResponseEngine } from './core/message/response-engine.js';
 import { MessageQueue } from './core/message/message-queue.js';
 import { MessageBridge } from './core/message/message-bridge.js';
-import { MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, parseMenuControl, validateMenuRequest } from './core/command/menu-protocol.js';
-import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata } from './core/command/evol-menu-version-gate.js';
+import { evaluateEvolMenuVersionGate, evolMenuResponseTransportMetadata, MenuRequestDeduper, hasValidMenuId, menuFailure, menuPayloadFingerprint, parseMenuControl, validateMenuRequest } from './core/command/menu-protocol.js';
 import { readInstalledEvolcoreVersion } from './utils/evolcore-version.js';
 import { recoverAllRoleMutationsSync } from './core/command/role-menu.js';
 import { HandoffRuntime } from './core/handoff/runtime.js';
-import { BootstrapService } from './core/bootstrap-service.js';
+import { BootstrapService, completeBootstrapWithWelcome } from './core/bootstrap-service.js';
+import { postBootstrapWelcomeOperationId } from './core/bootstrap-messages.js';
 import { MessageCache } from './core/message/message-cache.js';
 import { CommandHandler, isProcessLevelOwner } from './core/command/command-handler.js';
 import { EventBus } from './core/event-bus.js';
@@ -62,10 +62,13 @@ import { InteractionRouter } from './core/interaction-router.js';
 import { registerAdapterInteractions } from './core/interaction-registration.js';
 import { AgentDelegationRegistry, authorizeDelegatedAunMsgSend } from './core/auth/agent-delegation.js';
 import { authorizeOperation, buildAuthSubject } from './core/auth/auth-gateway.js';
+import { parsePeerKey } from './core/relation/peer-identity.js';
 import { isHClassPath } from './core/protected-paths.js';
 import { ChannelLoader, tryParseChannelKey } from './core/channel-loader.js';
 import { AgentLoader } from './core/baseagent-loader.js';
 import { EvolAgentRegistry } from './core/evolagent-registry.js';
+import { createRunnerReloadTransaction, disposeAgentInstances } from './core/runner-reload-transaction.js';
+import { AgentReloadBusyError, AgentReloadCoordinator } from './core/agent-reload-coordinator.js';
 import { buildReloadHooks } from './core/channel-loader.js';
 import { IpcServer } from './ipc.js';
 import { logger, setLogLevel } from './utils/logger.js';
@@ -88,6 +91,7 @@ import { validateModelSelectionForRole } from './core/model/model-permission.js'
 import { constrainRuntimePermissionMode, validateRuntimeStringFieldOverride, } from './core/role/runtime-policy.js';
 import { atomicWriteJson } from './core/session/session-fs-store.js';
 import { appendMessageLog, buildOutboundEntry, classifyAunPayloadForLog } from './core/message/message-log.js';
+import { normalizeAunMentionEntries } from './aun/msg/mention-schema.js';
 import { MAIN_PACKAGE_NAME } from './product.js';
 import fs from 'fs';
 import crypto from 'crypto';
@@ -205,7 +209,7 @@ function originFromActorSession(session, authenticatedPeerId, authenticatedChann
 }
 function seedUpgradeCheckTrigger(manager, owner) {
     const now = Date.now();
-    const scriptName = 'upgrade-check.sh';
+    const scriptName = 'upgrade-check.cjs';
     const definition = normalizeTriggerDefinition({
         $schema_version: 3.1,
         id: '__upgrade-check',
@@ -232,7 +236,7 @@ function seedUpgradeCheckTrigger(manager, owner) {
             type: 'script',
             script: {
                 path: scriptName,
-                runtime: 'bash',
+                runtime: 'node',
                 timeoutMs: 60_000,
             },
             permissionMode: 'bypass',
@@ -258,67 +262,107 @@ function seedUpgradeCheckTrigger(manager, owner) {
     const cliPath = path.join(packageRoot, 'dist', 'cli', 'index.js');
     const packageJsonPath = path.join(packageRoot, 'package.json');
     const devMode = fs.existsSync(path.join(packageRoot, 'src', 'index.ts'));
-    fs.writeFileSync(scriptPath, [
-        '#!/usr/bin/env bash',
-        'set -euo pipefail',
-        '',
-        `CLI_PATH=${JSON.stringify(cliPath)}`,
-        `PACKAGE_JSON=${JSON.stringify(packageJsonPath)}`,
-        `DEV_MODE=${devMode ? '1' : '0'}`,
-        '',
-        'json() {',
-        '  local outcome="$1"',
-        '  local text="$2"',
-        '  node -e \'console.log(JSON.stringify({ outcome: process.argv[1], text: process.argv[2], files: [] }))\' "$outcome" "$text"',
-        '}',
-        '',
-        'if [ "$DEV_MODE" = "1" ]; then',
-        '  json "noop" "upgrade check skipped in dev mode"',
-        '  exit 0',
-        'fi',
-        '',
-        'local_version="$(node -e \'try { console.log(require(process.argv[1]).version || "") } catch { process.exit(0) }\' "$PACKAGE_JSON")"',
-        `remote_version="$(npm view ${MAIN_PACKAGE_NAME} version 2>/dev/null || true)"`,
-        '',
-        'if [ -z "$remote_version" ]; then',
-        '  json "error" "failed to check evolcore latest version"',
-        '  exit 0',
-        'fi',
-        '',
-        'if [ -z "$local_version" ]; then',
-        '  json "error" "failed to read local ec version"',
-        '  exit 0',
-        'fi',
-        '',
-        'version_cmp="$(node -e \'',
-        'const [a, b] = process.argv.slice(1);',
-        'const pa = a.split("-")[0].split(".").map(Number);',
-        'const pb = b.split("-")[0].split(".").map(Number);',
-        'const n = Math.max(pa.length, pb.length);',
-        'let out = 0;',
-        'for (let i = 0; i < n; i++) {',
-        '  const av = Number.isFinite(pa[i]) ? pa[i] : 0;',
-        '  const bv = Number.isFinite(pb[i]) ? pb[i] : 0;',
-        '  if (av < bv) { out = -1; break; }',
-        '  if (av > bv) { out = 1; break; }',
-        '}',
-        'console.log(out);',
-        '\' "$local_version" "$remote_version")"',
-        '',
-        'if [ "$version_cmp" != "-1" ]; then',
-        '  json "noop" "evolcore is already up to date ($local_version; latest $remote_version)"',
-        '  exit 0',
-        'fi',
-        '',
-        'if [ ! -f "$CLI_PATH" ]; then',
-        '  json "error" "restart-monitor entry not found: $CLI_PATH"',
-        '  exit 0',
-        'fi',
-        '',
-        'nohup node "$CLI_PATH" restart-monitor >/dev/null 2>&1 &',
-        'json "success" "evolcore upgrade available: ${local_version:-unknown} -> $remote_version; restart-monitor started"',
-        '',
-    ].join('\n'));
+    fs.writeFileSync(scriptPath, `#!/usr/bin/env node
+const { existsSync, readFileSync } = require('node:fs');
+const { spawn } = require('node:child_process');
+
+const CLI_PATH = ${JSON.stringify(cliPath)};
+const PACKAGE_JSON = ${JSON.stringify(packageJsonPath)};
+const PACKAGE_NAME = ${JSON.stringify(MAIN_PACKAGE_NAME)};
+const DEV_MODE = ${devMode ? 'true' : 'false'};
+
+function emit(outcome, text) {
+  process.stdout.write(JSON.stringify({ outcome, text, files: [] }));
+}
+
+function compareVersions(a, b) {
+  const pa = a.split('-')[0].split('.').map(Number);
+  const pb = b.split('-')[0].split('.').map(Number);
+  const count = Math.max(pa.length, pb.length);
+  for (let i = 0; i < count; i += 1) {
+    const av = Number.isFinite(pa[i]) ? pa[i] : 0;
+    const bv = Number.isFinite(pb[i]) ? pb[i] : 0;
+    if (av < bv) return -1;
+    if (av > bv) return 1;
+  }
+  return 0;
+}
+
+async function latestVersion() {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), 10_000);
+  try {
+    const response = await fetch('https://registry.npmjs.org/' + encodeURIComponent(PACKAGE_NAME) + '/latest', {
+      signal: controller.signal,
+      headers: { Accept: 'application/json' },
+    });
+    if (!response.ok) return null;
+    const data = await response.json();
+    return typeof data.version === 'string' ? data.version : null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function main() {
+  if (DEV_MODE) {
+    emit('noop', 'upgrade check skipped in dev mode');
+    return;
+  }
+
+  let localVersion;
+  try {
+    localVersion = JSON.parse(readFileSync(PACKAGE_JSON, 'utf8')).version;
+  } catch {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+  if (typeof localVersion !== 'string' || !localVersion) {
+    emit('error', 'failed to read local ec version');
+    return;
+  }
+
+  let remoteVersion;
+  try {
+    remoteVersion = await latestVersion();
+  } catch {
+    remoteVersion = null;
+  }
+  if (!remoteVersion) {
+    emit('error', 'failed to check evolcore latest version');
+    return;
+  }
+  if (compareVersions(localVersion, remoteVersion) >= 0) {
+    emit('noop', 'evolcore is already up to date (' + localVersion + '; latest ' + remoteVersion + ')');
+    return;
+  }
+  if (!existsSync(CLI_PATH)) {
+    emit('error', 'restart-monitor entry not found: ' + CLI_PATH);
+    return;
+  }
+
+  try {
+    const child = spawn(process.execPath, [CLI_PATH, 'restart-monitor'], {
+      detached: true,
+      stdio: 'ignore',
+      windowsHide: process.platform === 'win32',
+      env: { ...process.env },
+    });
+    child.unref();
+    emit('success', 'evolcore upgrade available: ' + localVersion + ' -> ' + remoteVersion + '; restart-monitor started');
+  } catch (error) {
+    emit('error', 'failed to start restart-monitor: ' + (error && error.message ? error.message : String(error)));
+  }
+}
+
+main().catch((error) => {
+  emit('error', 'upgrade check failed: ' + (error && error.message ? error.message : String(error)));
+});
+`);
+    // Remove the pre-Node script left by older installations so it cannot be
+    // selected by a stale trigger definition or run manually by accident.
+    fs.rmSync(path.join(dir, 'upgrade-check.sh'), { force: true });
+    fs.rmSync(path.join(dir, 'upgrade-check.js'), { force: true });
     fs.chmodSync(scriptPath, 0o755);
     atomicWriteJson(manager.definitionPath(definition.id), definition);
     fs.rmSync(manager.activePath(definition.id), { force: true });
@@ -336,7 +380,9 @@ function removeLegacyAgentUpgradeCheck(manager) {
         return;
     const isLegacySystemOrigin = existing.origin?.channelKey === '__system__' || existing.origin?.channelKey === 'daemon';
     const isUpgradeScript = existing.execution.type === 'script'
-        && existing.execution.script?.path === 'upgrade-check.sh';
+        && (existing.execution.script?.path === 'upgrade-check.sh'
+            || existing.execution.script?.path === 'upgrade-check.js'
+            || existing.execution.script?.path === 'upgrade-check.cjs');
     if (!isLegacySystemOrigin || !isUpgradeScript)
         return;
     fs.rmSync(manager.triggerDir('__upgrade-check'), { recursive: true, force: true });
@@ -394,6 +440,13 @@ async function runBindBootstrapDaemon(daemonCfg) {
             await controlChannel.sendMessage(opts.channelId, JSON.stringify(response));
         }
     });
+    const controlToken = crypto.randomBytes(32).toString('base64url');
+    fs.mkdirSync(path.dirname(resolvePaths().controlToken), { recursive: true });
+    fs.writeFileSync(resolvePaths().controlToken, controlToken, { mode: 0o600 });
+    try {
+        fs.chmodSync(resolvePaths().controlToken, 0o600);
+    }
+    catch { }
     const ipcServer = new IpcServer(resolvePaths().socket, () => ({
         pid: process.pid,
         uptime: Math.round(process.uptime() * 1000),
@@ -415,6 +468,7 @@ async function runBindBootstrapDaemon(daemonCfg) {
             };
         })(),
     }));
+    ipcServer.setControlToken(controlToken);
     ipcServer.setBindExecutor({
         begin: (cmd) => bindService.begin(cmd),
         status: (taskId) => bindService.status(taskId),
@@ -974,6 +1028,7 @@ async function main() {
     }
     const channelInstances = evolagentInstances;
     logger.info(`✓ Created ${channelInstances.length} channel instance(s)`);
+    let bootstrapService;
     const contactRequestExpiryTimer = setInterval(() => {
         for (const agent of agentRegistry.runnableAgents()) {
             void expirePendingContactRequests(agent.aid).catch(error => {
@@ -988,6 +1043,35 @@ async function main() {
             getAvailableBaseagents: detectAvailableBaseagentsForBind,
             getUptimeSeconds: () => Math.floor(process.uptime()),
             onDaemonOwnersUpdated: (owners) => { processLevelOwners = owners; },
+            onAgentOwnerUpdated: (agentAid, ownerAid) => {
+                const service = bootstrapService;
+                if (!service)
+                    return;
+                const instance = channelInstances.find(candidate => {
+                    const owner = agentRegistry.resolveByChannel(candidate.adapter.channelKey)
+                        ?? agentRegistry.resolveByChannel(candidate.adapter.channelName);
+                    return owner?.aid === agentAid;
+                });
+                if (!instance)
+                    return;
+                eventBus.publish({
+                    type: 'channel:owner-bound',
+                    channel: instance.channelType || instance.adapter.channelName,
+                    channelName: instance.adapter.channelName,
+                    userId: ownerAid,
+                });
+                void service.tryStartBootstrap({
+                    adapter: instance.adapter,
+                    channelKey: instance.adapter.channelKey,
+                    channelType: instance.channelType,
+                    agentAid,
+                    recipientId: ownerAid,
+                    channelId: instance.channelType === 'aun' ? ownerAid : undefined,
+                    source: 'owner-bound',
+                }).catch((error) => {
+                    logger.warn(`[Bootstrap] Owner-bound start failed for ${agentAid}: ${error instanceof Error ? error.message : String(error)}`);
+                });
+            },
         })
         : null;
     bindService?.startCleanup();
@@ -1097,6 +1181,7 @@ async function main() {
         return { ok: result.ok, message_id: result.message_id, error: result.error };
     }, undefined, { queueTtlMs: taskExecutionTtlMs });
     responseEngine.setHandoffRuntime(handoffRuntime);
+    cmdHandler.setHandoffRuntime(handoffRuntime);
     // Trigger runtime: daemon-level script + feedback scheduler.
     const triggerSchedulers = new Map();
     const targetSessionLocks = new TargetSessionLockRegistry();
@@ -1541,7 +1626,7 @@ async function main() {
     msgBridge.setInteractionRouter(interactionRouter);
     msgBridge.setContactBindRuntimeChecker(isContactBindChannelReady);
     msgBridge.setAidStatsCollector(aidStatsCollector);
-    const bootstrapService = new BootstrapService(agentRegistry, eventBus);
+    bootstrapService = new BootstrapService(agentRegistry, eventBus);
     msgBridge.setBootstrapService(bootstrapService);
     msgBridge.setHandoffRuntime(handoffRuntime);
     // ── Channel instance registration (shared by startup and hot-load) ──
@@ -1961,7 +2046,7 @@ async function main() {
         const delegation = agentDelegationRegistry.validate(delegationToken, sessionId, delegationCommandHash);
         if (!delegation.ok)
             return { ok: false, code: delegation.code, error: delegation.reason };
-        return cmdHandler.handleCtl(cmd, sessionId);
+        return cmdHandler.handleCtl(cmd, sessionId, delegation.grant);
     });
     // Register every IPC executor/provider before exposing the endpoint. The
     // function declaration is hoisted, while its invocation remains here so a
@@ -2048,10 +2133,11 @@ async function main() {
                 }
                 else {
                     try {
-                        const ecwebProc = spawn('node', [ecwebEntry], {
+                        const ecwebProc = spawn(process.execPath, [ecwebEntry], {
                             cwd: ecwebPath,
                             detached: true,
                             stdio: 'ignore',
+                            windowsHide: platform.isWindows,
                             env: { ...process.env, EVOLCORE_HOME: resolvePaths().root }
                         });
                         ecwebProc.unref();
@@ -2227,6 +2313,9 @@ async function main() {
     const recoveryAids = triggerStartupAgents.map(agent => agent.aid);
     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}`);
@@ -2312,6 +2401,60 @@ async function main() {
     function configureIpc() {
         // M3: direct call (not cast) — wire EvolAgentRegistry into IPC for evolagent.* handlers
         ipcServer.setAgentRegistry(agentRegistry);
+        ipcServer.setControlToken(triggerControlToken);
+        ipcServer.setBootstrapCompleteExecutor(async (aid, auth) => {
+            if (auth?.sessionId) {
+                const authorization = await authorizeManagedAgentOperation({
+                    sessionId: auth.sessionId,
+                    delegationToken: auth.delegationToken,
+                    delegationCommandHash: auth.delegationCommandHash,
+                    targetAid: aid,
+                }, 'agent.bootstrapComplete');
+                if (!authorization.ok)
+                    return authorization;
+            }
+            else {
+                const providedToken = typeof auth?.controlToken === 'string' ? Buffer.from(auth.controlToken) : undefined;
+                const expectedToken = Buffer.from(triggerControlToken);
+                if (!providedToken
+                    || providedToken.length !== expectedToken.length
+                    || !crypto.timingSafeEqual(providedToken, expectedToken)) {
+                    return { ok: false, code: 'INVALID_CONTROL_TOKEN', error: 'valid local control token is required' };
+                }
+            }
+            const aunInstance = channelInstances.find(candidate => {
+                if (candidate.channelType !== 'aun')
+                    return false;
+                const owner = agentRegistry.resolveByChannel(candidate.adapter.channelKey)
+                    ?? agentRegistry.resolveByChannel(candidate.adapter.channelName);
+                return owner?.aid === aid;
+            });
+            const welcome = aunInstance?.channel;
+            const ownerAid = getFirstStaticAgentOwner(aid);
+            const owningAgent = agentRegistry.get(aid);
+            const sessions = aunInstance && ownerAid && owningAgent
+                ? {
+                    ensurePostBootstrapMainSession: async () => {
+                        const channel = aunInstance.adapter.channelName;
+                        const active = await sessionManager.getActiveSession(channel, ownerAid);
+                        const ensured = await sessionManager.ensureNewMainSessionForOperation({
+                            channel,
+                            channelId: ownerAid,
+                            projectPath: active?.projectPath || owningAgent.projectPath || defaultProjectPath,
+                            baseagent: owningAgent.baseagent || active?.baseagent || primaryBaseagent,
+                            operationId: postBootstrapWelcomeOperationId(aid),
+                            identityMetadata: {
+                                ...(active?.metadata ?? {}),
+                                channelKey: aunInstance.adapter.channelKey,
+                                peerId: ownerAid,
+                            },
+                        });
+                        return { sessionId: ensured.session.id, created: ensured.created };
+                    },
+                }
+                : undefined;
+            return completeBootstrapWithWelcome(bootstrapService, aid, welcome, sessions);
+        });
         ipcServer.setDingtalkContactBindExecutor({
             register: (cmd) => registerPendingDingtalkContactBind(cmd),
             isChannelReady: isContactBindChannelReady,
@@ -2335,6 +2478,10 @@ async function main() {
         ipcServer.setMenuExecutor((payload, auth) => cmdHandler.execMenuForEcweb(payload, auth));
         ipcServer.setConfigOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleConfigOperation(argv, sessionId, delegationToken, delegationCommandHash));
         ipcServer.setContactOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleContactOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setAidOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleAidOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setGroupOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleGroupOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setMsgOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleMsgOperation(argv, sessionId, delegationToken, delegationCommandHash));
+        ipcServer.setFsOperationExecutor((argv, sessionId, delegationToken, delegationCommandHash) => cmdHandler.handleFsOperation(argv, sessionId, delegationToken, delegationCommandHash));
         cmdHandler.setDaemonStatusProvider(() => {
             const aidState = controlChannel?.getAidState?.();
             return {
@@ -2403,30 +2550,82 @@ async function main() {
             aidStatsCollector.recordOutbound(params.aid, params.toPeer, Buffer.byteLength(params.text || '', 'utf-8'), params.text, false, params.encrypt, params.chatmode, 'send');
         });
         ipcServer.setTaskRuntimeContextProvider(({ sessionId }) => responseEngine.getTaskRuntimeContext(sessionId));
-        ipcServer.setHandoffReturnExecutor((params) => responseEngine.returnHandoffResult(params));
-        ipcServer.setHandoffStatusExecutor(async (params) => {
-            if (!params.sessionId)
-                return { ok: false, code: 'HANDOFF_CALL_SESSION_REQUIRED', error: 'current session is required' };
+        ipcServer.setCodexPreToolUseExecutor(async (params) => {
+            for (const runner of new Set(agentMap.values())) {
+                if (typeof runner?.evaluatePreToolUse !== 'function')
+                    continue;
+                const result = await runner.evaluatePreToolUse(params.threadId, params.toolName, params.toolInput);
+                if (result.applicable)
+                    return result;
+            }
+            return {
+                ok: false,
+                applicable: true,
+                decision: 'deny',
+                reason: 'No active EvolCore Codex runner accepted this managed hook request',
+            };
+        });
+        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)
-                return { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
-            return handoffRuntime.status(selfAid, params.handoffId)
-                ?? { ok: false, code: 'HANDOFF_NOT_FOUND', error: 'handoff not found' };
-        });
-        const resolveHandoffQueryAid = async (params) => {
+            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) {
+                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: daemonCfg.owners ?? [],
+            });
+            const managementRole = isManagementRole(subject.role);
+            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 };
+        };
+        const resolveHandoffQueryScope = async (params, operation) => {
             if (params.sessionId) {
-                const runtime = responseEngine.getTaskRuntimeContext(params.sessionId);
-                const session = await sessionManager.getSessionById(params.sessionId);
-                const selfAid = runtime?.selfAid || session?.selfAID;
-                if (!selfAid) {
-                    return { ok: false, code: 'HANDOFF_CALL_SESSION_INVALID', error: 'current session is invalid' };
-                }
-                if (params.agent && params.agent !== selfAid) {
-                    return { ok: false, code: 'HANDOFF_AGENT_SCOPE_MISMATCH', error: 'agent does not match the current session' };
-                }
-                return { ok: true, aid: selfAid };
+                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' };
@@ -2434,23 +2633,56 @@ async function main() {
             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 };
+            return { ok: true, aid: params.agent, currentSessionId: undefined, managementRole: true };
         };
+        ipcServer.setHandoffReturnExecutor(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);
+        });
+        ipcServer.setHandoffStatusExecutor(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;
+        });
         ipcServer.setHandoffListExecutor(async (params) => {
-            const scope = await resolveHandoffQueryAid(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: params.filterSessionId,
+                sessionId: scope.managementRole ? params.filterSessionId : scope.currentSessionId,
                 limit: params.limit,
             });
         });
         ipcServer.setHandoffTraceExecutor(async (params) => {
-            const scope = await resolveHandoffQueryAid(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' };
         });
@@ -2522,12 +2754,27 @@ async function main() {
             if (!payload) {
                 return { ok: false, error: 'message payload is required', code: 'INVALID_PAYLOAD' };
             }
+            try {
+                if (Object.prototype.hasOwnProperty.call(payload, 'mentions')) {
+                    payload = { ...payload, mentions: normalizeAunMentionEntries(payload.mentions) };
+                }
+                if (params.scope === 'group' && params.mentions !== undefined) {
+                    const normalizedMentions = normalizeAunMentionEntries(params.mentions);
+                    if (normalizedMentions.length > 0) {
+                        payload = { ...payload, mentions: normalizedMentions };
+                    }
+                }
+            }
+            catch (error) {
+                return {
+                    ok: false,
+                    error: error instanceof Error ? error.message : String(error),
+                    code: error?.code ?? 'INVALID_MENTION_SCHEMA',
+                };
+            }
             if (params.thread && typeof payload.thread_id !== 'string') {
                 payload = { ...payload, thread_id: params.thread };
             }
-            if (params.scope === 'group' && params.mentions?.length) {
-                payload = { ...payload, mentions: params.mentions };
-            }
             let targetSessionId;
             if (params.originSessionId && params.originMessageId) {
                 try {
@@ -2600,16 +2847,17 @@ async function main() {
             });
         });
         // ── Reload hooks: enable agentRegistry.reload() to drain/disconnect/restart channels ──
+        const unregisterRuntimeChannel = (channelName) => {
+            markChannelDisconnected(channelName);
+            processor.unregisterChannel(channelName);
+            cmdHandler.unregisterChannel(channelName);
+            msgBridge.removeChannel(channelName);
+        };
         const reloadHooks = buildReloadHooks({
             channelLoader,
             channelInstances,
             registerChannelInstance,
-            unregisterChannelInstance: (channelName) => {
-                markChannelDisconnected(channelName);
-                processor.unregisterChannel(channelName);
-                cmdHandler.unregisterChannel(channelName);
-                msgBridge.removeChannel(channelName);
-            },
+            unregisterChannelInstance: unregisterRuntimeChannel,
             onChannelStarted: (inst) => {
                 // startChannel 重建渠道时重新注入 AidStatsCollector（与 hot-load 路径对齐）
                 if (inst.channelType === 'aun') {
@@ -2619,9 +2867,112 @@ async function main() {
                 }
             },
             onChannelConnected: markChannelConnected,
+            onAgentReloaded: async (agent) => {
+                const instance = channelInstances.find(candidate => {
+                    const owner = agentRegistry.resolveByChannel(candidate.adapter.channelKey)
+                        ?? agentRegistry.resolveByChannel(candidate.adapter.channelName);
+                    return owner?.aid === agent.aid;
+                });
+                if (!instance)
+                    return;
+                await bootstrapService.tryStartBootstrap({
+                    adapter: instance.adapter,
+                    channelKey: instance.adapter.channelKey,
+                    channelType: instance.channelType,
+                    agentAid: agent.aid,
+                    source: 'owner-bound',
+                });
+            },
             messageQueue,
             handoffRuntime,
+            stageAgentRunners: async (candidate) => {
+                const creationErrors = [];
+                const staged = candidate.config.enabled === false
+                    ? []
+                    : agentLoader.createForAgent(candidate, {
+                        onSessionIdUpdate: async (sessionId, agentSessionId) => {
+                            await sessionManager.updateAgentSessionIdBySessionId(sessionId, agentSessionId);
+                        },
+                    }, creationErrors);
+                const onDisposeError = (instance, error) => {
+                    logger.warn(`[Reload] Failed to dispose runner ${instance.evolagentName}::${instance.baseagent}: ${error instanceof Error ? error.message : String(error)}`);
+                };
+                if (creationErrors.length > 0) {
+                    await disposeAgentInstances(staged, onDisposeError);
+                    throw new Error(creationErrors.map(error => `${error.baseagent}: ${error.message}`).join('; '));
+                }
+                if (candidate.config.enabled !== false && staged.length === 0 && candidate.config.active_baseagent) {
+                    throw new Error(`No runner could be created for ${candidate.aid}::${candidate.config.active_baseagent}`);
+                }
+                for (const instance of staged) {
+                    instance.agent.setPermissionGateway?.(permissionGateway);
+                    instance.agent.setCompactStartCallback?.((sessionId) => {
+                        processor.handleCompactStart(sessionId);
+                    });
+                }
+                return createRunnerReloadTransaction({
+                    aid: candidate.aid,
+                    agentMap,
+                    staged,
+                    onDisposeError,
+                });
+            },
+        });
+        const reloadOwnedMutes = new Set();
+        const reloadCoordinator = new AgentReloadCoordinator({
+            registry: agentRegistry,
+            hooks: reloadHooks,
+            getBusyCount: (aid) => {
+                const agentName = agentRegistry.get(aid)?.name;
+                if (!agentName)
+                    return 0;
+                return messageQueue.getProcessingCountByAgent(agentName)
+                    + messageQueue.getQueueLengthByAgent(agentName);
+            },
+            beforeReload: invalidateKitCache,
+            forceReload: async (aid) => {
+                const agentName = agentRegistry.get(aid)?.name;
+                if (!agentName)
+                    return;
+                messageQueue.clearByAgent(agentName);
+                await messageQueue.interruptByAgentAndWait(agentName);
+                const deadline = Date.now() + 5_000;
+                while (messageQueue.getProcessingCountByAgent(agentName) > 0) {
+                    if (Date.now() >= deadline) {
+                        throw new Error(`Timed out waiting for Agent "${aid}" tasks to stop`);
+                    }
+                    await new Promise(resolve => setTimeout(resolve, 25));
+                }
+            },
+            acquireWorkGate: (aid) => {
+                const agentName = agentRegistry.get(aid)?.name;
+                if (!agentName)
+                    return;
+                const inheritedReloadMute = reloadOwnedMutes.delete(agentName);
+                const alreadyMuted = messageQueue.isAgentMuted(agentName);
+                const ownsMute = inheritedReloadMute || !alreadyMuted;
+                if (!alreadyMuted)
+                    messageQueue.muteAgent(agentName);
+                return () => {
+                    const current = agentRegistry.get(aid);
+                    if (!current) {
+                        messageQueue.clearByAgent(agentName);
+                        if (ownsMute)
+                            messageQueue.unmuteAgent(agentName);
+                        return;
+                    }
+                    if (current.status === 'disabled') {
+                        messageQueue.clearByAgent(agentName);
+                        if (ownsMute)
+                            reloadOwnedMutes.add(agentName);
+                        return;
+                    }
+                    if (ownsMute)
+                        messageQueue.unmuteAgent(agentName);
+                };
+            },
         });
+        ipcServer.setAgentReloadExecutor((aid, options) => reloadCoordinator.reload(aid, options));
         // Make reload hooks accessible to IPC handler & ctl handler (both run in this process)
         globalThis.__evolcore_reloadHooks = reloadHooks;
         // Hot-load handler: dynamically add a new agent at runtime
@@ -2677,7 +3028,7 @@ async function main() {
                 agent.status = 'running';
                 // 连接
                 await channelLoader.connectAll(instances, { onConnected: markChannelConnected });
-                await handoffRuntime.recover([aid]);
+                await handoffRuntime.recover([aid], { discardExpired: false });
                 await ensureTriggerSchedulerStarted(agent);
                 handoffRuntime.resumeAgent(aid);
                 resumed = true;
@@ -2691,90 +3042,121 @@ async function main() {
             }
         };
         // Full resync handler: scan disk, load new agents, unload removed/disabled, reload changed
+        let resyncInFlight;
         globalThis.__evolcore_resyncAgents = async () => {
-            // 先清 kit 缓存：'kits' 组（manifest / fragment / schema / 角色模板）走 on-reload
-            // 策略，平时不查盘。放在扫盘与 reload 之前，本轮上下线的 agent 才能读到磁盘上的
-            // 最新版本——放在末尾的话，这一轮全用旧值，改动要等下一次 resync 才生效。
-            invalidateKitCache();
-            const { loadAllAgents: scanAgents, loadDefaults: readDefaults } = await import('./config-store.js');
-            const { resolveEffective } = await import('./config/config-manager.js');
-            const freshDefaults = readDefaults();
-            const { agents: diskAgents } = scanAgents();
-            const diskAidSet = new Set(diskAgents.map(a => a.aid));
-            const results = [];
-            // 1. 下线：运行时有但磁盘上没有 / disabled 的
-            for (const [aid, agent] of [...agentRegistry.agents.entries()]) {
-                const diskCfg = diskAgents.find(a => a.aid === aid);
-                if (!diskCfg || diskCfg.enabled === false) {
-                    handoffRuntime.pauseAgent(aid);
-                    try {
-                        await handoffRuntime.drainAgent(aid);
-                    }
-                    catch (error) {
-                        handoffRuntime.resumeAgent(aid);
-                        results.push(`⚠ ${aid}: ${error instanceof Error ? error.message : String(error)}`);
-                        continue;
-                    }
-                    await triggerSchedulers.get(aid)?.stop();
-                    triggerSchedulers.delete(aid);
-                    triggerSchedulerStarts.delete(aid);
-                    // 断开所有 channels
-                    for (const chName of agent.channelInstanceNames()) {
-                        const inst = channelInstances.find(i => i.adapter.channelName === chName);
-                        if (inst) {
-                            try {
-                                await inst.disconnect();
+            if (resyncInFlight)
+                return resyncInFlight;
+            const operation = (async () => {
+                // 先清 kit 缓存：'kits' 组（manifest / fragment / schema / 角色模板）走 on-reload
+                // 策略，平时不查盘。放在扫盘与 reload 之前，本轮上下线的 agent 才能读到磁盘上的
+                // 最新版本——放在末尾的话，这一轮全用旧值，改动要等下一次 resync 才生效。
+                invalidateKitCache();
+                const { loadAllAgents: scanAgents } = await import('./config-store.js');
+                const { agents: diskAgents } = scanAgents();
+                const results = [];
+                // 1. 下线：运行时有但磁盘上没有 / disabled 的
+                for (const [aid] of [...agentRegistry.agents.entries()]) {
+                    const diskCfg = diskAgents.find(a => a.aid === aid);
+                    if (!diskCfg || diskCfg.enabled === false) {
+                        try {
+                            const offlined = await reloadCoordinator.runExclusive(aid, async () => {
+                                const latestDiskCfg = readConfig(ConfigTarget.Agent, { self: aid }, { cache: false, expand: true });
+                                if (latestDiskCfg && latestDiskCfg.enabled !== false)
+                                    return false;
+                                const runtimeAgent = agentRegistry.get(aid);
+                                if (!runtimeAgent)
+                                    return false;
+                                let removed = false;
+                                handoffRuntime.pauseAgent(aid);
+                                try {
+                                    await handoffRuntime.drainAgent(aid);
+                                    await triggerSchedulers.get(aid)?.stop();
+                                    triggerSchedulers.delete(aid);
+                                    triggerSchedulerStarts.delete(aid);
+                                    // 断开所有 channels
+                                    for (const chName of runtimeAgent.channelInstanceNames()) {
+                                        const inst = channelInstances.find(i => i.adapter.channelName === chName);
+                                        if (inst) {
+                                            try {
+                                                await inst.disconnect();
+                                            }
+                                            catch { }
+                                            const idx = channelInstances.indexOf(inst);
+                                            if (idx >= 0)
+                                                channelInstances.splice(idx, 1);
+                                        }
+                                        unregisterRuntimeChannel(chName);
+                                    }
+                                    agentRegistry.agents.delete(aid);
+                                    messageQueue.clearByAgent(runtimeAgent.name);
+                                    removed = true;
+                                    return true;
+                                }
+                                finally {
+                                    if (!removed)
+                                        handoffRuntime.resumeAgent(aid);
+                                }
+                            });
+                            if (offlined)
+                                results.push(`- ${aid} (offline)`);
+                        }
+                        catch (error) {
+                            if (error instanceof AgentReloadBusyError) {
+                                results.push(`⏸ ${aid} (busy: ${error.busyCount} task(s); reload skipped)`);
+                            }
+                            else {
+                                results.push(`⚠ ${aid}: ${error instanceof Error ? error.message : String(error)}`);
                             }
-                            catch { }
-                            markChannelDisconnected(inst.adapter.channelName);
-                            const idx = channelInstances.indexOf(inst);
-                            if (idx >= 0)
-                                channelInstances.splice(idx, 1);
                         }
+                        continue;
                     }
-                    agentRegistry.agents.delete(aid);
-                    results.push(`- ${aid} (offline)`);
-                    continue;
                 }
-            }
-            // 2. 新增：磁盘上有但运行时没有的
-            for (const cfg of diskAgents) {
-                if (cfg.enabled === false)
-                    continue;
-                if (agentRegistry.agents.has(cfg.aid))
-                    continue;
-                try {
-                    await globalThis.__evolcore_hotLoadAgent(cfg.aid);
-                    results.push(`+ ${cfg.aid} (online)`);
+                // 2. 新增：磁盘上有但运行时没有的
+                for (const cfg of diskAgents) {
+                    if (cfg.enabled === false)
+                        continue;
+                    if (agentRegistry.agents.has(cfg.aid))
+                        continue;
+                    try {
+                        await globalThis.__evolcore_hotLoadAgent(cfg.aid);
+                        results.push(`+ ${cfg.aid} (online)`);
+                    }
+                    catch (e) {
+                        results.push(`✗ ${cfg.aid}: ${e?.message || e}`);
+                    }
                 }
-                catch (e) {
-                    results.push(`✗ ${cfg.aid}: ${e?.message || e}`);
+                // 3. 已有的：重新 reload（config 可能改了）
+                for (const cfg of diskAgents) {
+                    if (cfg.enabled === false)
+                        continue;
+                    if (!agentRegistry.agents.has(cfg.aid))
+                        continue;
+                    // 只有磁盘上存在且运行时也存在的才 reload
+                    try {
+                        await reloadCoordinator.reload(cfg.aid);
+                        const runtimeAgent = agentRegistry.get(cfg.aid);
+                        if (runtimeAgent)
+                            await startTriggerScheduler(runtimeAgent);
+                        results.push(`↻ ${cfg.aid} (reloaded)`);
+                    }
+                    catch (e) {
+                        results.push(`⚠ ${cfg.aid}: ${e?.message || e}`);
+                    }
                 }
+                // 重建 channel index（kit 缓存已在本轮开头清过）
+                agentRegistry.channelIndex.clear();
+                agentRegistry.buildChannelIndex();
+                logger.info(`[Resync] Done: ${results.length} agent(s) processed`);
+                return results;
+            })();
+            resyncInFlight = operation;
+            try {
+                return await operation;
             }
-            // 3. 已有的：重新 reload（config 可能改了）
-            const hooks = globalThis.__evolcore_reloadHooks;
-            for (const cfg of diskAgents) {
-                if (cfg.enabled === false)
-                    continue;
-                if (!agentRegistry.agents.has(cfg.aid))
-                    continue;
-                // 只有磁盘上存在且运行时也存在的才 reload
-                try {
-                    await agentRegistry.reload(cfg.aid, hooks);
-                    const runtimeAgent = agentRegistry.get(cfg.aid);
-                    if (runtimeAgent)
-                        await startTriggerScheduler(runtimeAgent);
-                    results.push(`↻ ${cfg.aid} (reloaded)`);
-                }
-                catch (e) {
-                    results.push(`⚠ ${cfg.aid}: ${e?.message || e}`);
-                }
+            finally {
+                if (resyncInFlight === operation)
+                    resyncInFlight = undefined;
             }
-            // 重建 channel index（kit 缓存已在本轮开头清过）
-            agentRegistry.channelIndex.clear();
-            agentRegistry.buildChannelIndex();
-            logger.info(`[Resync] Done: ${results.length} agent(s) processed`);
-            return results;
         };
         ipcServer.setStatsProvider(() => statsCollector.getSnapshot());
         ipcServer.setAgentStatsProvider(() => agentRegistry.list().map((agent) => {
@@ -2825,6 +3207,88 @@ async function main() {
                     return { ok: false, error: `unknown action: ${params.action}` };
             }
         });
+        async function authorizeManagedAgentOperation(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 session = await sessionManager.getSessionById(params.sessionId);
+            if (!session || session.selfAID !== delegation.grant.selfAid) {
+                return { ok: false, code: 'INVALID_DELEGATION', error: 'delegation does not match the current session' };
+            }
+            if (params.targetAid && params.targetAid !== delegation.grant.selfAid) {
+                return { ok: false, code: 'SCOPE_MISMATCH', error: 'only the current Agent can be targeted' };
+            }
+            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: delegation.grant.selfAid,
+                actorId: delegation.grant.actorId,
+                channel: delegation.grant.channel,
+                channelType: delegation.grant.channelType,
+                channelId: conversationId,
+                chatType: delegation.grant.chatType,
+                conversationId,
+                processOwners: daemonCfg.owners ?? [],
+            });
+            if (!isManagementRole(subject.role)) {
+                return { ok: false, code: 'ROLE_ACCESS_DENIED', error: `${operation} requires Agent admin permission` };
+            }
+            const decision = authorizeOperation({
+                source: 'agent-tool',
+                subject,
+                intent: {
+                    operation,
+                    scope: operation === 'system.status' ? 'process' : 'agent',
+                    source: 'agent-tool',
+                    args: { self: delegation.grant.selfAid, aid: params.targetAid ?? delegation.grant.selfAid },
+                },
+                auditMetadata: { taskId: delegation.grant.taskId, messageId: delegation.grant.messageId },
+            });
+            return decision.allow
+                ? { ok: true, aid: delegation.grant.selfAid }
+                : { ok: false, code: decision.code, error: decision.reason };
+        }
+        ipcServer.setQueueOperationExecutor(async (params) => {
+            const operation = `ec.queue.${params.action ?? 'read'}`;
+            const authorization = await authorizeManagedAgentOperation(params, operation);
+            if (!authorization.ok)
+                return authorization;
+            const handle = agentRegistry.get(authorization.aid);
+            if (!handle?.name)
+                return { ok: false, code: 'AGENT_NOT_FOUND', error: 'current Agent not found' };
+            if (!params.action)
+                return { ok: true, items: messageQueue.getQueueItemsByAgent(handle.name) };
+            if (params.action === 'clear')
+                return { ok: true, cleared: messageQueue.clearByAgent(handle.name) };
+            if (params.action === 'cancel') {
+                if (!params.messageId)
+                    return { ok: false, code: 'INVALID_ARGUMENT', error: 'missing messageId' };
+                return { ok: true, cancelled: messageQueue.cancelMessageById(handle.name, params.messageId) };
+            }
+            if (!params.sessionKey)
+                return { ok: false, code: 'INVALID_ARGUMENT', error: 'missing sessionKey' };
+            const targetSessionId = messageQueue.findSessionIdBySessionKey(params.sessionKey);
+            if (!targetSessionId)
+                return { ok: false, code: 'SESSION_NOT_FOUND', error: `session not found: ${params.sessionKey}` };
+            const targetSession = await sessionManager.getSessionById(targetSessionId);
+            if (!targetSession || targetSession.selfAID !== authorization.aid) {
+                return { ok: false, code: 'SCOPE_MISMATCH', error: 'session does not belong to the current Agent' };
+            }
+            return { ok: true, interrupted: await messageQueue.interruptBySession(targetSessionId) };
+        });
+        ipcServer.setStatusAuthorizationExecutor(async (params) => {
+            const authorization = await authorizeManagedAgentOperation(params, 'system.status');
+            return authorization.ok ? { ok: true } : authorization;
+        });
+        ipcServer.setStorageAuthorizationExecutor(async (params) => {
+            const authorization = await authorizeManagedAgentOperation({ ...params, targetAid: params.aid }, params.operation);
+            return authorization.ok ? { ok: true } : authorization;
+        });
         ipcServer.setTriggerExecutor(async (cmd) => {
             const schedulerFor = (agentAid) => {
                 const scheduler = triggerSchedulers.get(agentAid);