evolcore 0.0.20 → 0.0.21

package/dist/core/message/message-bridge.js

@@ -2,7 +2,7 @@ import { createHash, randomBytes } from 'crypto';
 import { logger } from '../../utils/logger.js';
 import { StreamDebouncer } from './stream-debouncer.js';
 import { appendMessageLog, appendMessageLogStrict, buildInboundEntry, isTransientProtocolMessage } from './message-log.js';
-import { buildEnvelope, sendInteractionPayload } from './message-utils.js';
+import { buildEnvelope, isInteractionSendAccepted, sendInteractionPayload } from './message-utils.js';
 import { chatDirPath } from '../session/session-fs-store.js';
 import { formatChannelKey, tryParseChannelKey } from '../channel-loader.js';
 import { agentDir, resolvePaths } from '../../paths.js';
@@ -25,7 +25,10 @@ import { createRootCausation, deriveCausation, normalizeCausation } from '../cau
 import { recordCausationSpan } from '../causation/audit.js';
 import { renderActionAsText } from '../interaction-router.js';
 import { planApprovalRoute } from '../permission/approval-gateway.js';
-import { consumeAdmissionReplyBudget, clearAdmissionReplyBudgets, evaluateInboundAdmissionPreflight, evaluateOrdinaryInboundAdmission, } from './inbound-admission.js';
+import { parseFullAccessCommand } from '../command/slash-gate.js';
+import { isFullAccessEnabled } from '../../config-store.js';
+import { auditFullAccessEvent } from '../auth/authorization-audit.js';
+import { consumeAdmissionReplyBudget, clearAdmissionReplyBudgets, evaluateInboundAdmissionPreflight, evaluateOrdinaryInboundAdmission, } from './message-admission.js';
 const CONTACT_REJECTION_NOTICE = '[rejection] Not accepting messages from you.';
 const REJECTABLE_PEER_TYPES = new Set(['ai', 'bot', 'agent', 'service']);
 const REJECTION_MAX = 3;
@@ -431,6 +434,27 @@ export class MessageBridge {
         await this.sendContactRequestProtocolResponse(adapter, msg, result, owningAgent?.name);
         return true;
     }
+    /**
+     * Agent self-service contact add: create/update a pending request and send
+     * the same Owner action card used by inbound `/request`.
+     */
+    async submitAgentContactRequest(input) {
+        const owningAgent = this.agentRegistry?.get(input.selfAid) ?? null;
+        const submission = await submitContactRequest({
+            selfAid: input.selfAid,
+            applicantAid: input.applicantAid,
+            sourceChannelKey: input.sourceChannelKey,
+            note: '通过 ec contact add 发起的联系人申请',
+        });
+        if ((submission.code !== 'submitted' && submission.code !== 'resubmitted') || !submission.requestId) {
+            return { ...submission, reviewCardSent: false };
+        }
+        const reviewCardSent = await this.deliverContactReviewCard(input.selfAid, input.applicantAid, submission, owningAgent);
+        if (!reviewCardSent) {
+            logger.warn(`[MessageBridge] Agent contact add request persisted without review card: self=${input.selfAid} applicant=${input.applicantAid} request=${submission.requestId}`);
+        }
+        return { ...submission, reviewCardSent };
+    }
     contactRequestReply(result) {
         switch (result.code) {
             case 'submitted': return '联系人申请已提交，等待管理员审核。';
@@ -507,14 +531,17 @@ export class MessageBridge {
             toolInput: { applicantAid, requestId: submission.requestId },
             summary: `Review contact request from ${applicantAid}`,
             grantable: true,
-            approverPolicy: 'agent_manager',
+            // Contact membership is an Agent-owner decision. Do not use the broader
+            // agent_manager policy here: that policy intentionally prefers an Admin,
+            // which made request cards invisible to the configured Owner.
+            approverPolicy: 'agent_owner',
             createdAt: Date.parse(submission.submittedAt),
         }, {
             userId: applicantAid,
             chatType: 'private',
             selfAid,
             approvalRouting: {
-                approverPolicy: 'agent_manager',
+                approverPolicy: 'agent_owner',
                 owners,
                 admins,
                 resolveApproverCandidates,
@@ -602,10 +629,11 @@ export class MessageBridge {
             chatmode: 'interactive',
             replyContext: { delivery: { chatType: 'private' }, metadata: { source: 'handoff', chatmode: 'interactive' } },
         });
-        const sent = await sendInteractionPayload(route.adapter, envelope, interaction, renderActionAsText(interaction), envelope.replyContext);
-        if (!sent)
+        const receipt = await sendInteractionPayload(route.adapter, envelope, interaction, renderActionAsText(interaction), envelope.replyContext);
+        const accepted = isInteractionSendAccepted(receipt);
+        if (!accepted)
             await this.interactionRouter.cancel(submission.requestId, 'delivery_failed');
-        return !!sent;
+        return accepted;
     }
     async sendContactReviewOutcome(adapter, ownerAid, applicantAid, code, agentName) {
         const text = code === 'approved' ? `已通过 ${applicantAid} 的联系人申请。`
@@ -666,12 +694,23 @@ export class MessageBridge {
         const available = this.availableBaseagentsFor(channelName);
         if (available.length === 0 || available.includes(session.baseagent))
             return session;
+        // A topic's backend binding is fenced by SessionManager and cannot be
+        // cleared as a side effect of routing alignment. Reassigning the
+        // baseagent while leaving the old provider's agentSessionId persisted
+        // would make the new runner resume an incompatible backend. Keep the
+        // binding intact and let normal baseagent-mismatch handling report it;
+        // an explicit boundary operation must perform any future migration.
+        if (session.threadId) {
+            logger.error(`[MessageBridge] Cannot align topic to another baseagent: `
+                + `session=${session.id} thread=${session.threadId} current=${session.baseagent} preferred=${owningAgent.baseagent}`);
+            return session;
+        }
         const preferred = available.includes(owningAgent.baseagent)
             ? owningAgent.baseagent
             : available[0];
         logger.warn(`[MessageBridge] Aligning unavailable session baseagent: session=${session.id} ${session.baseagent} -> ${preferred} agent=${owningAgent.name} available=${available.join(',')}`);
-        await this.sessionManager.updateSession(session.id, { baseagent: preferred, agentSessionId: null });
-        return { ...session, baseagent: preferred, agentSessionId: undefined };
+        await this.sessionManager.updateSession(session.id, { baseagent: preferred });
+        return { ...session, baseagent: preferred };
     }
     /**
      * 为渠道注册消息桥梁：入站处理管线 + 出站命令响应
@@ -685,8 +724,14 @@ export class MessageBridge {
     register(channelName, onMessage, sendReply, adapter, channelType) {
         const effectiveChannelType = channelType || channelName;
         onMessage(async (msg) => {
+            let releaseSessionIngress;
+            const releaseIngress = () => {
+                releaseSessionIngress?.();
+                releaseSessionIngress = undefined;
+            };
             try {
                 let content = msg.content.trim();
+                let executionPermissionOverride;
                 // Channels that expose adapter receive time (notably AUN) must keep
                 // that timestamp through session resolution and queue processing.
                 // The fallback is only for legacy adapters that do not provide it.
@@ -890,6 +935,61 @@ export class MessageBridge {
                     await this.sendAccessDenied(adapter, channelName, msg, sendReply);
                     return;
                 }
+                // /fa is an execution prefix, not a session-mode switch or a normal
+                // quick command. Only this trusted bridge path can construct the
+                // internal per-call authorization carried into ResponseEngine.
+                const fullAccessCommand = parseFullAccessCommand(content);
+                if (fullAccessCommand.matched) {
+                    const reject = async (text) => {
+                        logger.warn(`[MessageBridge] fullaccess command rejected: channel=${channelName} `
+                            + `actor=${authSubject.principalId ?? authSubject.actorId ?? '<none>'} reason=${text}`);
+                        auditFullAccessEvent({
+                            event: 'fullaccess.command.rejected',
+                            source: 'fullaccess-command',
+                            decision: 'deny',
+                            actorId: authSubject.principalId ?? authSubject.actorId,
+                            processRole: authSubject.processRole,
+                            messageId: msg.messageId,
+                            reason: text,
+                        });
+                        await sendReply(msg.channelId, `❌ ${text}`, msg.replyContext);
+                    };
+                    if (msg.source !== undefined && msg.source !== 'user') {
+                        await reject('fullaccess 只能由用户直接发送的 /fa 或 /fullaccess 命令发起');
+                        return;
+                    }
+                    if (!fullAccessCommand.prompt) {
+                        await reject('用法：/fa <提示词> 或 /fullaccess <提示词>');
+                        return;
+                    }
+                    if (!isFullAccessEnabled()) {
+                        await reject('fullaccess 功能未启用，请先设置 daemon.json.fullaccess.enabled=true');
+                        return;
+                    }
+                    if (!authSubject.isDaemonOwner || !authSubject.principalId) {
+                        await reject('仅可信 daemon-owner 可以使用 fullaccess');
+                        return;
+                    }
+                    if (!msg.messageLogContent)
+                        msg.messageLogContent = content;
+                    content = fullAccessCommand.prompt;
+                    executionPermissionOverride = {
+                        permissionMode: 'fullaccess',
+                        processRole: 'fullaccess-run',
+                        dataScope: 'daemon',
+                        source: 'fullaccess-command',
+                        authorizedBy: authSubject.principalId,
+                    };
+                    logger.warn(`[MessageBridge] fullaccess command accepted: channel=${channelName} `
+                        + `actor=${authSubject.principalId} message=${msg.messageId ?? '<none>'}`);
+                    auditFullAccessEvent({
+                        event: 'fullaccess.command.accepted',
+                        source: 'fullaccess-command',
+                        actorId: authSubject.principalId,
+                        processRole: authSubject.processRole,
+                        messageId: msg.messageId,
+                    });
+                }
                 // 0. 仅阻止协议遥测进入 session / model / messages.jsonl；协议本身已在
                 // channel/main/events/AUN/handoff 专用链路中处理和记录。
                 // 注：menu.* 自定义消息已由上方 handleMenuControl 快速路径处理。
@@ -928,6 +1028,11 @@ export class MessageBridge {
                 const contentForCmd = content.replace(/^(>[^\n]*\n)+\n?/, '').trim();
                 const cmdContent = contentForCmd || content;
                 const isCmd = msg.source !== 'handoff'
+                    // Once /fa has been accepted, its remainder is always model input.
+                    // A prompt such as `/fa /status` must not be re-routed as the
+                    // ordinary `/status` quick command after the prefix is removed.
+                    && !executionPermissionOverride
+                    && !parseFullAccessCommand(cmdContent).matched
                     && this.cmdHandler.isCommand(cmdContent);
                 if (isCmd) {
                     logger.debug(`[MessageBridge] Command detected: "${cmdContent}", routing to handler`);
@@ -966,6 +1071,7 @@ export class MessageBridge {
                     }
                 }
                 if (msg.source !== 'handoff'
+                    && !executionPermissionOverride
                     && await this.handleCommand(cmdContent, channelName, msg.channelId, (text) => {
                         const taskId = `cmd-${msg.messageId || Date.now()}`;
                         logger.channelOut({ channel: channelName, channelId: msg.channelId, taskId, correlationId: taskId, sessionId: msg.replyContext?.sessionId, agentAid: msg.selfAID, payload: { kind: 'command.result', text } });
@@ -1011,6 +1117,9 @@ export class MessageBridge {
                     ?? this.defaultProjectPath;
                 const hadMainSession = msg.threadId ? true : this.sessionManager.hasMainSession(channelName, msg.channelId, msg.channelType || effectiveChannelType, msg.selfAID || selfAid);
                 let session = await this.sessionManager.getOrCreateSession(channelName, msg.channelId, effectiveProjectPath, msg.threadId, Object.keys(metadata).length ? metadata : undefined, this.extractTopicName(msg), msg.peerId, chatType, owningAgent?.baseagent, msg.selfAID, msg.channelType || effectiveChannelType, msg.peerType, identity);
+                if (session.threadId && typeof this.messageQueue.reserveSessionIngress === 'function') {
+                    releaseSessionIngress = this.messageQueue.reserveSessionIngress(session.id);
+                }
                 session = await this.alignSessionBaseagent(channelName, session);
                 const replyToMessageId = typeof msg.replyContext?.metadata?.refMessageId === 'string'
                     ? msg.replyContext.metadata.refMessageId
@@ -1065,6 +1174,7 @@ export class MessageBridge {
                     topicName: this.extractTopicName(msg),
                     replyContext: msg.replyContext,
                     source: msg.source,
+                    ...(executionPermissionOverride ? { executionPermissionOverride } : {}),
                     boundSessionId: session.id,
                     resolvedIdentity: identity,
                     mentionMode: msg.mentionMode,
@@ -1158,6 +1268,7 @@ export class MessageBridge {
                             role: !isInterrupt ? (session.identity?.role ?? 'none') : undefined,
                             sessionKeyField: session.sessionKey,
                             selfAID, // ← 传递 selfAID，用于队列隔离
+                            onPersisted: releaseIngress,
                         });
                     }
                     catch (error) {
@@ -1193,6 +1304,9 @@ export class MessageBridge {
             catch (error) {
                 logger.error(`[MessageBridge] Error in onMessage handler for ${channelName}:`, error);
             }
+            finally {
+                releaseIngress();
+            }
         });
     }
     // ── Menu Protocol ──
@@ -1541,7 +1655,7 @@ export class MessageBridge {
             return;
         logger.warn(`[MenuControl] category=${category} request=${parsed.id || '<missing>'}`
             + ` type=${parsed.type} name=${parsed.name || '<none>'} action=${parsed.action || '<none>'}`
-            + ` transport=${channel} scope=${this.shortHash(scope)} sender=${this.shortHash(msg.peerId)}`
+            + ` transport=${channel} scope=${scope || 'none'} sender=${msg.peerId || 'none'}`
             + (category === 'request-replay' ? ' replay=true' : '')
             + (category === 'request-retry' ? ' retry=true' : '')
             + `${code ? ` code=${code}` : ''}${decision.suppressed ? ` suppressed=${decision.suppressed}` : ''}`);

package/dist/core/message/message-log.js

@@ -231,24 +231,31 @@ export function messageLogPath(chatDir) {
     return path.join(chatDir, MESSAGE_LOG_FILE);
 }
 export function hasMessageLogOperation(chatDir, operationId) {
+    return findMessageLogOperationMessageId(chatDir, operationId) !== undefined;
+}
+export function findMessageLogOperationMessageId(chatDir, operationId) {
     const file = messageLogPath(chatDir);
     if (!fs.existsSync(file))
-        return false;
+        return undefined;
     try {
-        return fs.readFileSync(file, 'utf-8').split('\n').some(line => {
+        for (const line of fs.readFileSync(file, 'utf-8').split('\n')) {
             if (!line.trim())
-                return false;
+                continue;
             try {
                 const entry = JSON.parse(line);
-                return entry?.dir === 'out' && entry.operationId === operationId;
+                if (entry?.dir === 'out' && entry.operationId === operationId) {
+                    if (typeof entry.msgId === 'string' && entry.msgId)
+                        return entry.msgId;
+                }
             }
             catch {
-                return false;
+                // skip malformed message log lines
             }
-        });
+        }
+        return undefined;
     }
     catch {
-        return false;
+        return undefined;
     }
 }
 export function resolveChatDir(sessionsDir, channelType, channelId, selfAID) {

package/dist/core/message/message-queue.js

@@ -3,6 +3,7 @@ import fs from 'fs';
 import { logger } from '../../utils/logger.js';
 import { LogicalQueueBridge } from './logical-queue-bridge.js';
 import { normalizeCausation } from '../causation/context.js';
+import { KeyedFairMutex } from '../handoff/mutex.js';
 const DEFAULT_AGENT_NAME = '<unknown>';
 const RESTART_RESUME_CONTENT = 'evolcore 服务已重启，请继续之前未完成的任务。';
 export class MessageQueue {
@@ -10,6 +11,9 @@ export class MessageQueue {
     processing = new Set();
     processingAgent = new Map(); // queueKey → agentName（处理中项目的 agent）
     externalLocks = new Map();
+    prequeueReservations = new Map();
+    /** Serializes fast session commands while retaining the existing dequeue gate. */
+    sessionBarrierMutex = new KeyedFairMutex();
     handler;
     activeStates = new Map(); // queueKey → active task state
     interruptCallback;
@@ -32,6 +36,7 @@ export class MessageQueue {
     shutdownPromise;
     /** 逻辑队列桥接：管理出队顺序（响应模式可注入自定义策略，默认 FIFO） */
     logicalQueue = new LogicalQueueBridge();
+    enqueueSequence = 0;
     constructor(handler, options) {
         this.handler = handler;
         this.persistencePath = options?.persistencePath;
@@ -138,6 +143,42 @@ export class MessageQueue {
         setTimeout(() => this.recentMessageIds.delete(dedupKey), this.DEDUP_WINDOW);
         return true;
     }
+    /**
+     * Claim a stable inbound message for a fast command that bypasses the
+     * normal queue.  The claim uses exactly the same durable ledger and key as
+     * ordinary enqueue deduplication, but deliberately does not enqueue or
+     * affect queue scheduling.
+     */
+    claimInbound(sessionKey, messageId, selfAID) {
+        const normalizedMessageId = messageId.trim();
+        if (!normalizedMessageId) {
+            const error = new Error('inbound claim requires a stable messageId');
+            error.code = 'INBOUND_MESSAGE_ID_REQUIRED';
+            throw error;
+        }
+        const key = this.dedupKey(sessionKey, normalizedMessageId, selfAID);
+        if (this.recentMessageIds.has(key)
+            || this.durableMessageIds.has(key)
+            || this.hasEnqueuedMessage(sessionKey, normalizedMessageId, selfAID)) {
+            return 'duplicate';
+        }
+        if (!this.dedupPath) {
+            const error = new Error('durable inbound dedup is unavailable');
+            error.code = 'INBOUND_DEDUP_UNAVAILABLE';
+            throw error;
+        }
+        const seenAt = Date.now();
+        this.durableMessageIds.set(key, seenAt);
+        if (!this.persistDurableDedup()) {
+            this.durableMessageIds.delete(key);
+            const error = new Error('failed to persist inbound dedup claim');
+            error.code = 'INBOUND_DEDUP_PERSIST_FAILED';
+            throw error;
+        }
+        this.recentMessageIds.add(key);
+        setTimeout(() => this.recentMessageIds.delete(key), this.DEDUP_WINDOW);
+        return 'claimed';
+    }
     rememberDurably(sessionKey, message, selfAID) {
         if (!this.dedupPath || !message.messageId)
             return;
@@ -174,20 +215,64 @@ export class MessageQueue {
     }
     persistDurableDedup() {
         if (!this.dedupPath)
-            return;
+            return false;
         const now = Date.now();
         for (const [key, seenAt] of this.durableMessageIds) {
             if (now - seenAt > this.dedupTtlMs)
                 this.durableMessageIds.delete(key);
         }
+        const tmp = `${this.dedupPath}.tmp-${process.pid}-${Date.now()}-${this.enqueueSequence}`;
+        let fd;
         try {
             fs.mkdirSync(path.dirname(this.dedupPath), { recursive: true });
-            const tmp = `${this.dedupPath}.tmp-${process.pid}-${Date.now()}`;
-            fs.writeFileSync(tmp, JSON.stringify({ version: 1, updatedAt: now, entries: [...this.durableMessageIds].map(([key, seenAt]) => ({ key, seenAt })) }));
+            const content = Buffer.from(JSON.stringify({
+                version: 1,
+                updatedAt: now,
+                entries: [...this.durableMessageIds].map(([key, seenAt]) => ({ key, seenAt })),
+            }));
+            fd = fs.openSync(tmp, 'w');
+            let offset = 0;
+            while (offset < content.length) {
+                const written = fs.writeSync(fd, content, offset, content.length - offset, null);
+                if (written <= 0)
+                    throw new Error('dedup ledger write made no progress');
+                offset += written;
+            }
+            fs.fsyncSync(fd);
+            fs.closeSync(fd);
+            fd = undefined;
             fs.renameSync(tmp, this.dedupPath);
+            const persistedFd = fs.openSync(this.dedupPath, 'r');
+            try {
+                fs.fsyncSync(persistedFd);
+            }
+            finally {
+                fs.closeSync(persistedFd);
+            }
+            if (process.platform !== 'win32') {
+                const directoryFd = fs.openSync(path.dirname(this.dedupPath), 'r');
+                try {
+                    fs.fsyncSync(directoryFd);
+                }
+                finally {
+                    fs.closeSync(directoryFd);
+                }
+            }
+            return true;
         }
         catch (error) {
             logger.warn(`[Queue] Failed to persist durable dedup ledger: ${error instanceof Error ? error.message : String(error)}`);
+            if (fd !== undefined) {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { }
+            }
+            try {
+                fs.unlinkSync(tmp);
+            }
+            catch { }
+            return false;
         }
     }
     hasEnqueuedMessage(sessionKey, messageId, selfAID) {
@@ -768,6 +853,8 @@ export class MessageQueue {
     shouldRestoreMessage(message, sessionId) {
         // The Trigger scheduler records open runs as daemon_restart. Replaying their
         // queued work afterwards would execute side effects for an already-failed run.
+        if (message.executionPermissionOverride)
+            return false;
         if (message.source !== 'trigger' && !message.triggerMeta)
             return true;
         this.droppedTriggerSessionIds.add(sessionId);
@@ -794,9 +881,9 @@ export class MessageQueue {
         }
         // 拦截器检查：AskUserQuestion 等场景的一次性消息拦截
         const interceptor = this.interceptors.get(sessionKey);
-        const canAnswerInteraction = message.source === undefined
+        const canAnswerInteraction = !message.executionPermissionOverride && (message.source === undefined
             || message.source === 'user'
-            || message.source === 'card-trigger';
+            || message.source === 'card-trigger');
         if (interceptor && canAnswerInteraction) {
             this.interceptors.delete(sessionKey);
             logger.debug(`[Queue] Message intercepted for ${sessionKey}`);
@@ -849,6 +936,7 @@ export class MessageQueue {
             // Capture the physical enqueue instant once. It must not be regenerated
             // on every persistence snapshot, otherwise old messages appear fresh.
             const enqueuedAt = Date.now();
+            this.enqueueSequence += 1;
             // Clone at the physical queue boundary. The same inbound object may be
             // broadcast to multiple agents; mutating it would make all copies share
             // the last queue's enqueue timestamp.
@@ -1154,7 +1242,10 @@ export class MessageQueue {
         return result;
     }
     isMergeBarrier(message) {
-        return !!message.handoffDelivery || !!message.triggerMeta || !!message.causation?.trigger?.path.length;
+        return !!message.executionPermissionOverride
+            || !!message.handoffDelivery
+            || !!message.triggerMeta
+            || !!message.causation?.trigger?.path.length;
     }
     isOriginHandoff(message) {
         return message.source === 'handoff' && message.handoffDelivery?.direction === 'origin';
@@ -1437,23 +1528,122 @@ export class MessageQueue {
         return { found: false, barrier: Promise.resolve() };
     }
     /**
-     * 外部锁：快速命令（/compact, /clear）执行期间阻塞队列处理
-     * 返回 release 函数
+     * Capture the session's queue state and install a dequeue gate in one
+     * synchronous critical section.  Messages arriving after this call remain
+     * durable in the queue, but processNext will wait until the last holder
+     * releases the gate.
      */
-    acquireLock(sessionKey) {
-        let releaseFn;
-        const promise = new Promise(resolve => { releaseFn = resolve; });
-        this.externalLocks.set(sessionKey, promise);
+    acquireDequeueGate(sessionKey) {
+        const existing = this.externalLocks.get(sessionKey);
+        if (existing) {
+            existing.holders += 1;
+            let released = false;
+            return {
+                snapshot: { ...existing.snapshot },
+                release: () => {
+                    if (released)
+                        return;
+                    released = true;
+                    existing.holders -= 1;
+                    if (existing.holders > 0)
+                        return;
+                    if (this.externalLocks.get(sessionKey) === existing)
+                        this.externalLocks.delete(sessionKey);
+                    existing.releasePromise();
+                },
+            };
+        }
+        let releasePromise;
+        const promise = new Promise(resolve => { releasePromise = resolve; });
+        let queued = 0;
+        let active = false;
+        let dispatching = false;
+        for (const [queueKey, queue] of this.queues.entries()) {
+            if (!this.matchesSession(queueKey, sessionKey))
+                continue;
+            queued += this.queueRawMessageCount(queue);
+            if (this.processing.has(queueKey) || this.activeBatches.has(queueKey))
+                active = true;
+            if (this.processing.has(queueKey) && !this.activeBatches.has(queueKey))
+                dispatching = true;
+        }
+        for (const queueKey of this.activeBatches.keys()) {
+            if (this.matchesSession(queueKey, sessionKey))
+                active = true;
+        }
+        const state = {
+            promise,
+            releasePromise,
+            holders: 1,
+            snapshot: {
+                prequeue: this.prequeueReservations.get(sessionKey) ?? 0,
+                active,
+                queued,
+                dispatching,
+                cutoff: this.enqueueSequence,
+            },
+        };
+        this.externalLocks.set(sessionKey, state);
+        let released = false;
+        return {
+            snapshot: { ...state.snapshot },
+            release: () => {
+                if (released)
+                    return;
+                released = true;
+                state.holders -= 1;
+                if (state.holders > 0)
+                    return;
+                if (this.externalLocks.get(sessionKey) === state)
+                    this.externalLocks.delete(sessionKey);
+                state.releasePromise();
+            },
+        };
+    }
+    /**
+     * Mark an admitted message before it enters debounce or other pre-queue
+     * work. The returned release is idempotent so callers can use it both from
+     * onPersisted and a surrounding finally block.
+     */
+    reserveSessionIngress(sessionKey) {
+        this.prequeueReservations.set(sessionKey, (this.prequeueReservations.get(sessionKey) ?? 0) + 1);
+        let released = false;
         return () => {
-            this.externalLocks.delete(sessionKey);
-            releaseFn();
+            if (released)
+                return;
+            released = true;
+            const remaining = (this.prequeueReservations.get(sessionKey) ?? 1) - 1;
+            if (remaining > 0)
+                this.prequeueReservations.set(sessionKey, remaining);
+            else
+                this.prequeueReservations.delete(sessionKey);
         };
     }
+    /**
+     * Run a fast session command while no queued work can start.  The queue
+     * snapshot and external gate are installed before the callback is invoked;
+     * messages arriving afterwards remain durable but are outside this probe.
+     */
+    async withSessionBarrier(sessionKey, callback) {
+        return this.sessionBarrierMutex.forKey(sessionKey).runExclusive(async () => {
+            const gate = this.acquireDequeueGate(sessionKey);
+            try {
+                return await callback(gate.snapshot);
+            }
+            finally {
+                gate.release();
+            }
+        });
+    }
+    /** Backwards-compatible lock API used by existing quick commands. */
+    acquireLock(sessionKey) {
+        return this.acquireDequeueGate(sessionKey).release;
+    }
     /** 检查是否有外部锁 */
     getExternalLock(queueKey) {
-        for (const [key, promise] of this.externalLocks) {
+        for (const [key, state] of this.externalLocks) {
             if (this.matchesSession(queueKey, key))
-                return promise;
+                return state.promise;
         }
         return undefined;
     }

package/dist/core/message/message-utils.js

@@ -4,6 +4,12 @@
  * 从 message-processor.ts 提取的独立工具函数，供 ResponseEngine 和其他模块使用。
  */
 import { renderCommandCardAsText, renderActionAsText } from '../interaction-router.js';
+/** A legacy adapter resolved its send call without providing a structured receipt. */
+export const LEGACY_INTERACTION_ACCEPTED = 'legacy-accepted';
+export function isInteractionSendAccepted(result) {
+    return result === LEGACY_INTERACTION_ACCEPTED
+        || (result !== false && (result.status === 'sent' || result.status === 'queued'));
+}
 /**
  * 构造出站消息信封
  */
@@ -129,7 +135,8 @@ export function defaultFallbackText(interaction) {
  * 通过统一的 adapter.send 入口发送交互负载
  *
  * 通过 adapter.send(envelope, { kind: 'interaction', ... }) 发送交互。
- * 成功返回 'sent'，失败返回 false。
+ * 保留 adapter 的结构化回执，让调用方区分 sent、queued、failed 和
+ * suppressed；legacy adapter 的 void 返回表示已接受但尚无可验证回执。
  */
 export async function sendInteractionPayload(adapter, envelope, interaction, fallbackText, replyCtx) {
     const text = fallbackText ?? defaultFallbackText(interaction);
@@ -141,11 +148,11 @@ export async function sendInteractionPayload(adapter, envelope, interaction, fal
     try {
         const enriched = replyCtx ? withEnvelopeReplyContext(envelope, replyCtx) : envelope;
         const receipt = await adapter.send(enriched, payload);
-        if (receipt?.status === 'suppressed')
+        if (!receipt)
+            return LEGACY_INTERACTION_ACCEPTED;
+        if (receipt.status === 'sent' && !(receipt.messageId || receipt.messages[0]?.messageId))
             return false;
-        if (receipt?.status === 'sent')
-            return receipt.messages[0]?.messageId || false;
-        return 'sent';
+        return receipt;
     }
     catch {
         return false;