evolcore 0.0.18 → 0.0.20

package/dist/channels/aun.js

@@ -19,7 +19,7 @@ import { appendAidLifecycle } from '../aun/aid/identity.js';
 import { enableFullGroupPullPagination, getAidStore, loadClient, SLOT } from '../aun/aid/store.js';
 import { MAX_AUN_ATTACHMENT_SIZE, uploadBufferAndBuildPayload, uploadFileAndBuildPayload } from '../aun/msg/upload.js';
 import { loadAgent } from '../config-store.js';
-import { normalizeAgentLifecycle } from '../config/lifecycle.js';
+import { resolveAgentLifecycle } from '../config/lifecycle.js';
 import { resolveEffective } from '../config/config-manager.js';
 import { isManagementRole } from '../config/builtin-roles.js';
 import { normalizeMentionMode } from '../config/mention-mode.js';
@@ -195,6 +195,211 @@ export function buildAunFilePayload(params) {
     }
     return payload;
 }
+const AUN_PERMANENT_ERROR_CODES = new Set([
+    400, 401, 403, 404,
+    4000, 4001, 4010, 4030, 4040, 4090,
+    -32700, -32600, -32601, -32602,
+    -32001, -32002, -32003, -32004, -32005, -32008, -32009, -32011, -32013,
+    -32040, -32041, -32042, -32043, -32044, -32050, -32051,
+    -32100, -32101, -32102, -32103, -32104, -32105, -32150, -32152, -32153,
+    -32160, -32161, -32162, -32164, -32170, -32171, -32172, -32173, -32174, -32175,
+    -32176, -32177, -32178, -32179, -32185, -32186,
+    -32180, -32181, -32182, -32183, -32184,
+    -33001, -33004, -33005, -33006, -33007, -33008, -33009,
+    -33401, -33403, -33404, -33405,
+]);
+const AUN_RETRYABLE_ERROR_CODES = new Set([
+    429, 4290,
+    -32603,
+    -32010, -32029, -32429,
+    -32151, -32154, -32163,
+    -33402, -33406, -33407,
+]);
+const AUN_ACCEPTED_DISPATCH_STATUSES = new Set([
+    'debounced', 'dispatched', 'accepted', 'queued', 'queued_batch', 'broadcast', 'sent',
+]);
+const AUN_PERMANENT_STRING_CODES = new Set([
+    'invalid_params', 'invalid_param', 'invalid_request', 'permission_denied',
+    'unauthorized', 'authentication_failed', 'not_found', 'group_not_found',
+    'group_not_member', 'member_not_found', 'target_not_found', 'agent_not_found',
+    'recipient_not_found', 'invalid_argument', 'invalid_payload', 'forbidden',
+]);
+const AUN_RETRYABLE_STRING_CODES = new Set([
+    'network_error', 'connection_error', 'timeout', 'timed_out', 'rate_limited',
+    'too_many_requests', 'temporarily_unavailable', 'server_error', 'aun_not_connected',
+]);
+function errorRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function firstErrorField(candidates, keys, accept) {
+    for (const candidate of candidates) {
+        for (const key of keys) {
+            const value = candidate[key];
+            if (value !== undefined && value !== null && value !== '' && (!accept || accept(value)))
+                return value;
+        }
+    }
+    return undefined;
+}
+function aunErrorDetails(value, fallback = 'AUN send failed') {
+    const root = errorRecord(value);
+    const nested = root
+        ? [root.error, root.data, root.details, root.cause]
+            .map(errorRecord)
+            .filter((candidate) => !!candidate)
+        : [];
+    const candidates = root ? [root, ...nested] : [];
+    const rawMessage = firstErrorField(candidates, [
+        'message', 'error_message', 'errorMessage', 'error', 'reason', 'detail',
+    ], value => typeof value === 'string');
+    const message = typeof value === 'string'
+        ? value
+        : typeof rawMessage === 'string'
+            ? rawMessage
+            : value instanceof Error
+                ? value.message
+                : fallback;
+    const rawCode = firstErrorField(candidates, [
+        'code', 'error_code', 'errorCode', 'stringCode', 'string_code',
+    ], value => typeof value === 'string' || typeof value === 'number');
+    const rawStatus = firstErrorField(candidates, ['status', 'statusCode', 'http_status', 'httpStatus'], value => (typeof value === 'number' && Number.isFinite(value))
+        || (typeof value === 'string' && /^\d+$/.test(value)));
+    const status = typeof rawStatus === 'number'
+        ? rawStatus
+        : typeof rawStatus === 'string' && /^\d+$/.test(rawStatus)
+            ? Number(rawStatus)
+            : undefined;
+    const retryableCandidate = candidates.find(candidate => Object.prototype.hasOwnProperty.call(candidate, 'retryable'));
+    const retryable = retryableCandidate && typeof retryableCandidate.retryable === 'boolean'
+        ? retryableCandidate.retryable
+        : undefined;
+    const name = firstErrorField(candidates, ['name', 'type'], value => typeof value === 'string');
+    const messageStatus = message.match(/\b(?:HTTP\b[^\d]{0,40}|status(?:\s*code)?\s*[:=]?\s*)(\d{3})\b/i);
+    const dispatchStatus = root?.message_dispatch && typeof root.message_dispatch === 'object'
+        ? root.message_dispatch.status
+        : undefined;
+    return {
+        code: typeof rawCode === 'string' || typeof rawCode === 'number' ? rawCode : undefined,
+        message: message || fallback,
+        name: typeof name === 'string' ? name : undefined,
+        retryable,
+        status: status ?? (messageStatus ? Number(messageStatus[1]) : undefined),
+        dispatchStatus: typeof dispatchStatus === 'string' ? dispatchStatus.toLowerCase() : undefined,
+    };
+}
+function numericErrorCode(code) {
+    if (typeof code === 'number' && Number.isFinite(code))
+        return code;
+    if (typeof code === 'string' && /^-?\d+$/.test(code.trim()))
+        return Number(code);
+    return undefined;
+}
+function normalizedErrorCode(code) {
+    return code === undefined ? '' : String(code).trim().toLowerCase().replace(/[\s-]+/g, '_');
+}
+function shortErrorMessage(message) {
+    const compact = message.replace(/\s+/g, ' ').trim();
+    return compact.length > 500 ? `${compact.slice(0, 497)}...` : compact;
+}
+/**
+ * Classify a gateway response before it reaches the durable queue. Protocol
+ * and HTTP semantics take precedence; the SDK's `retryable` bit is used when
+ * no known code or explicit rejection already determines the outcome.
+ */
+export function classifyAunSendFailure(value, fallback = 'AUN send failed') {
+    const details = aunErrorDetails(value, fallback);
+    const numericCode = numericErrorCode(details.code);
+    const stringCode = normalizedErrorCode(details.code);
+    const text = `${details.name ?? ''} ${stringCode} ${details.message}`.toLowerCase();
+    const httpStatus = details.status
+        ?? (numericCode !== undefined && numericCode >= 100 && numericCode <= 599 ? numericCode : undefined);
+    const retryByName = /(?:timeout|connection|rate.?limit|temporar(?:y|ily)|unavailable|network|socket)/i.test(details.name ?? '');
+    const relayTargetMissing = text.includes('relay_target_not_found') || text.includes('relay target not found');
+    const rpcHandlerTimeout = numericCode === -32004 && /rpc handler timeout/i.test(text);
+    const groupStateCode = numericCode === -33002 || numericCode === -33003;
+    const groupClosed = groupStateCode && /\b(?:closed|dissolved|disbanded)\b|解散|已关闭/i.test(text);
+    const groupSuspended = groupStateCode && /\bsuspend(?:ed)?\b|暂停/i.test(text);
+    const transientHttpStatus = httpStatus === 408 || httpStatus === 425 || httpStatus === 429
+        || (httpStatus !== undefined && httpStatus >= 500 && httpStatus < 600);
+    const permanentHttpStatus = httpStatus !== undefined
+        && httpStatus >= 400 && httpStatus < 500
+        && !transientHttpStatus;
+    const permanentByText = !relayTargetMissing && /(?:group|peer|agent|recipient|target|member|object|task|stream)\s*(?:id\s*)?(?:not found|does not exist|不存在)|group[_ -]?not[_ -]?found|not[_ -]?a[_ -]?member|(?:permission|access|role).*(?:denied|forbidden|拒绝|无权限)|(?:invalid|malformed|bad)\s*(?:argument|param|request)|unauthori[sz]ed|authentication failed|signature invalid/i.test(text);
+    const retryByText = /timeout|timed out|temporar|unavailable|overload|rate.?limit|too many requests|try again|not connected|connection|network|socket|econn|eai_again|etimedout|epipe|broken pipe|connection refused|connect timeout|fetch failed|dns|reset by peer|gateway service degraded|upstream/i.test(text);
+    const acceptedDispatch = details.dispatchStatus !== undefined
+        && AUN_ACCEPTED_DISPATCH_STATUSES.has(details.dispatchStatus);
+    const rejectedDispatch = details.dispatchStatus === 'failed'
+        || details.dispatchStatus === 'skipped';
+    const successfulHttpWithoutReceipt = httpStatus !== undefined
+        && httpStatus >= 200 && httpStatus < 300
+        && numericCode === undefined && !permanentByText && !retryByText;
+    const ambiguousAccepted = errorRecord(value)?.ok === true
+        && numericCode === undefined
+        && httpStatus === undefined
+        && !permanentByText
+        && !retryByText;
+    const ambiguousNoReceipt = (value === null || value === undefined)
+        && /no message[_ -]?id|no receipt|empty response|returned no/i.test(fallback);
+    const missingReceipt = /no message[_ -]?id|missing message[_ -]?id|no receipt|empty response|returned no/i.test(fallback);
+    const unconfirmedDelivery = missingReceipt
+        && (acceptedDispatch || ambiguousAccepted || ambiguousNoReceipt || successfulHttpWithoutReceipt);
+    let status;
+    if ((AUN_PERMANENT_ERROR_CODES.has(numericCode ?? Number.NaN) && !rpcHandlerTimeout)
+        || permanentByText
+        || AUN_PERMANENT_STRING_CODES.has(stringCode)
+        || rejectedDispatch
+        || groupClosed
+        || (groupStateCode && !groupSuspended)
+        || permanentHttpStatus) {
+        status = 'permanent';
+    }
+    else if (unconfirmedDelivery) {
+        // The RPC completed with a success-looking result but without the protocol
+        // receipt. Reissuing it could duplicate a message because AUN send calls
+        // do not carry our local outbox operation ID as an idempotency key.
+        status = 'permanent';
+    }
+    else if (AUN_RETRYABLE_ERROR_CODES.has(numericCode ?? Number.NaN)
+        || transientHttpStatus
+        || rpcHandlerTimeout
+        || AUN_RETRYABLE_STRING_CODES.has(stringCode)
+        || retryByName
+        || relayTargetMissing
+        || groupSuspended
+        || retryByText) {
+        // Known transient protocol, HTTP, SDK-class and transport signals take
+        // precedence over the SDK's generic `retryable` default. Several SDK
+        // error classes default that flag to false even for connection failures.
+        status = 'retry';
+    }
+    else if (details.retryable === false) {
+        status = 'permanent';
+    }
+    else if (details.retryable === true) {
+        status = 'retry';
+    }
+    else {
+        // A response with no recognized transient signal is deterministic enough
+        // to stop retrying. This is deliberately fail-closed for durable sends.
+        status = 'permanent';
+    }
+    return {
+        status,
+        error: shortErrorMessage(details.message),
+        ...(details.code !== undefined
+            ? { code: details.code }
+            : details.status !== undefined
+                ? { code: details.status }
+                : missingReceipt
+                    ? { code: 'MISSING_MESSAGE_ID' }
+                    : {}),
+    };
+}
+function sentOutboxResult() {
+    return { status: 'sent' };
+}
 function setIfDefined(target, key, value) {
     if (value !== undefined)
         target[key] = value;
@@ -1017,6 +1222,7 @@ export class AUNChannel {
      * the event handler boundary, before payload/slash/mention parsing.
      */
     inboundSeenMessages = new Map();
+    invalidInboundEnvelopeLastLogAt = 0;
     groupNameCache = new Map(); // groupId → 群显示名（进程内缓存，群名极少变）
     peerInfoCache = new Map();
     messageSeqMap = new Map(); // messageId → seq (for ack/diagnostics)
@@ -1174,11 +1380,9 @@ export class AUNChannel {
         const aidName = this.config.aid;
         // encryptionSeed 由 getAidStore 内部解析（config / env / 'evol'）
         // Migration from ~/.aun is handled by ensureDataDirs() at startup with a marker file.
-        // Gateway discovery/cache is owned by the SDK. Do not do a blocking
-        // well-known probe here: it prevents the SDK from using its token-store
-        // gateway metadata cache when well-known is temporarily unavailable.
-        const configuredGateway = this.config.gatewayUrl || '';
-        logger.info(`${this.logPrefix()} Initializing: aid=${aidName}, gateway=${configuredGateway || '<sdk-discovery>'}, aun_path=${aunPath}`);
+        // Gateway discovery/cache is owned entirely by the SDK.
+        this.gatewayUrl = '';
+        logger.info(`${this.logPrefix()} Initializing: aid=${aidName}, gateway=<sdk-discovery>, aun_path=${aunPath}`);
         // 构造 AIDStore。daemon 使用独立 slot，CLI/netcheck 不能触碰业务入站游标。
         // encryptionSeed / rootCaPath 由 getAidStore 内部注入
         const store = await getAidStore({
@@ -1193,13 +1397,6 @@ export class AUNChannel {
         // A reconnect replaces the SDK client. Late events from the retired
         // instance must not mutate the new instance's health or message state.
         const isCurrentClient = () => this.client === client;
-        // fastaun gives a preset in-memory gateway precedence over its metadata
-        // cache and AID discovery. authenticate({ gateway }) is deliberately
-        // rejected by its public API, so set the documented client preset before
-        // authentication instead.
-        if (configuredGateway)
-            client._gatewayUrl = configuredGateway;
-        this.gatewayUrl = configuredGateway;
         // Register event handlers before connecting
         client.on('message.received', (data) => {
             if (!isCurrentClient())
@@ -1306,7 +1503,7 @@ export class AUNChannel {
             const auth = await client.authenticate();
             this.trace('OUT', 'auth.authenticate.ok', { aid: client.aid, gateway: auth?.gateway, hasToken: !!auth?.access_token });
             this.trace('IN', 'auth.result', { aid: client.aid, gateway: auth?.gateway, hasToken: !!auth?.access_token });
-            const resolvedGateway = String(auth?.gateway ?? this.gatewayUrl);
+            const resolvedGateway = typeof auth?.gateway === 'string' ? auth.gateway : '';
             this.gatewayUrl = resolvedGateway;
             logger.info(`${this.logPrefix()} Authenticated as ${client.aid ?? '?'}, gateway=${resolvedGateway}`);
         }
@@ -1393,22 +1590,11 @@ export class AUNChannel {
             if (hasMessageLogOperation(chatDir, operationId))
                 return true;
             const prepared = outbox.findByDedupeKey(aidName, operationId);
-            const initial = outbox.findByDedupeKey(aidName, bootstrapInitialMessageOperationId(aidName));
-            const initialDelivery = initial && outbox.isDeliveryForChannel(initial.delivery, owner)
-                ? initial.delivery
-                : undefined;
-            // During bootstrap completion the lifecycle is intentionally still
-            // non-active. Persisting the welcome must stay local and must not block
-            // on a best-effort group RPC before the lifecycle commit. If the initial
-            // bootstrap route is already known, preserve it; otherwise migration
-            // will resolve a group route after the channel is active.
-            const lifecycle = normalizeAgentLifecycle(agentConfig).lifecycle;
-            const ownerIsGroup = initialDelivery
-                ? initialDelivery.chatType === 'group'
-                : lifecycle === 'active' ? await this.isGroup(owner) : undefined;
-            const delivery = initialDelivery ?? (ownerIsGroup === true
-                ? { chatType: 'group', groupId: owner }
-                : { chatType: 'private' });
+            // Bootstrap welcomes target the configured personal Owner AID. They are
+            // not replies to an inbound group message, so their route is always
+            // private and must not be inferred with group.get_info.
+            const lifecycle = resolveAgentLifecycle(agentConfig);
+            const delivery = { chatType: 'private' };
             if (prepared
                 && prepared.channelId === owner
                 && isDeliveryTarget(prepared.delivery)
@@ -1452,6 +1638,7 @@ export class AUNChannel {
         return this.reconcilePostBootstrapWelcome();
     }
     async hasPendingPostBootstrapWelcome() {
+        this.repairBootstrapRoutes();
         const aid = this.config.aid.replace(/^@/, '');
         return hasPendingPostBootstrapWelcomeOutbox(aid);
     }
@@ -1467,6 +1654,7 @@ export class AUNChannel {
      * already-active agent from manufacturing another welcome message.
      */
     async reconcilePostBootstrapWelcome() {
+        this.repairBootstrapRoutes();
         const configuredAid = this.config.aid;
         const aid = configuredAid.startsWith('@') ? configuredAid.slice(1) : configuredAid;
         const operationId = postBootstrapWelcomeOperationId(aid);
@@ -1484,15 +1672,17 @@ export class AUNChannel {
             return false;
         }
         const agentConfig = loadAgent(aid);
-        if (!agentConfig || normalizeAgentLifecycle(agentConfig).lifecycle !== 'active') {
+        if (!agentConfig || resolveAgentLifecycle(agentConfig) !== 'active') {
             logger.info(`${this.logPrefix()} Post-bootstrap welcome prepared; waiting for lifecycle=active`);
             return true;
         }
         if (!this.connected || !this.client)
             return true;
-        const sent = await this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), false);
-        if (sent)
-            outbox.remove(aid, entry.id);
+        const sent = await this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
+        if (sent.status === 'sent')
+            this.removeDeliveredOutboxEntry(entry);
+        else if (sent.status === 'permanent')
+            this.markPermanentOutboxFailure(entry, sent);
         return true;
     }
     // ── Event handlers ──────────────────────────────────────────
@@ -1743,17 +1933,30 @@ export class AUNChannel {
         const msg = data;
         const receivedAt = Date.now();
         const receivedAtMono = performance.now();
-        // Claim before any payload extraction or command parsing. Retransmits may
-        // carry a new seq, but the application identity remains message_id.
+        // Validate the authenticated envelope before any payload extraction or
+        // command parsing. Retransmits may carry a new seq, but the application
+        // identity remains message_id.
         const messageId = typeof msg.message_id === 'string' ? msg.message_id : '';
         const seq = typeof msg.seq === 'number' ? msg.seq : undefined;
-        if (!this.claimInboundMessage('private', messageId, seq))
-            return;
         // SDK 0.5.* 移除了顶层 from/to/group_id/encrypted 等别名，统一从 msg.envelope.* 读取。
         // message_id / seq / payload / same_* 等仍是顶层独立字段，不在 envelope 内。
         const env = (msg.envelope && typeof msg.envelope === 'object') ? msg.envelope : {};
+        const fromAid = typeof env.from === 'string' ? env.from.trim() : '';
+        if (!messageId || !fromAid) {
+            this.acknowledgeImmediately(messageId, seq);
+            const now = Date.now();
+            if (now - this.invalidInboundEnvelopeLastLogAt >= 60_000) {
+                this.invalidInboundEnvelopeLastLogAt = now;
+                logger.warn(`${this.logPrefix()} Dropped private inbound: invalid envelope code=INVALID_INBOUND_ENVELOPE mid=${messageId || 'unknown'} from=${fromAid || 'unknown'}`);
+            }
+            else {
+                logger.debug(`${this.logPrefix()} Dropped private inbound: invalid envelope (suppressed duplicate) mid=${messageId || 'unknown'}`);
+            }
+            return;
+        }
+        if (!this.claimInboundMessage('private', messageId, seq))
+            return;
         const protectedHeaders = verifiedProtectedHeaders(msg, env);
-        const fromAid = env.from ?? '';
         const payload = msg.payload ?? '';
         const mentions = this.parsePayloadMentionsOrReject(payload, 'p2p.inbound', messageId, seq);
         if (!mentions)
@@ -2319,7 +2522,7 @@ export class AUNChannel {
     setObserverConfigResolver(fn) {
         this.observerConfigResolver = fn;
     }
-    /** 读取 observable 开关 + owners；无 resolver（如未接入 daemon）时视为关闭。 */
+    /** 读取 observable 开关 + owners；未接入 daemon 时没有 owning Agent，保持关闭。 */
     getObserverConfig() {
         return this.observerConfigResolver?.() ?? { observable: false, owners: [] };
     }
@@ -2869,8 +3072,27 @@ export class AUNChannel {
             this.outboxInFlight.delete(entry.id);
         }
     }
+    markPermanentOutboxFailure(entry, result) {
+        const error = result.error ?? 'permanent send failure';
+        const terminated = outbox.markTerminal(this.config.aid, entry.id, { error, code: result.code }, entry);
+        if (terminated) {
+            logger.error(`${this.logPrefix()} Permanent AUN delivery failure; outbox entry terminated: id=${entry.id} channel=${entry.channelId} code=${result.code ?? 'unknown'} error=${error}`);
+        }
+        else {
+            logger.warn(`${this.logPrefix()} Ignored stale permanent delivery result after outbox route changed: id=${entry.id} submittedChannel=${entry.channelId}`);
+        }
+    }
+    removeDeliveredOutboxEntry(entry) {
+        if (!outbox.removeIfRouteMatches(this.config.aid, entry)) {
+            logger.warn(`${this.logPrefix()} Preserved outbox entry whose route changed while delivery was in flight: id=${entry.id} submittedChannel=${entry.channelId}`);
+        }
+    }
     messageIdFromSendResult(result) {
-        return result?.message?.message_id ?? result?.message_id ?? null;
+        const nested = result?.message?.message_id;
+        if (typeof nested === 'string' && nested.trim())
+            return nested;
+        const direct = result?.message_id;
+        return typeof direct === 'string' && direct.trim() ? direct : null;
     }
     /**
      * An AUN send result is only a gateway transport result. It is not a
@@ -3140,10 +3362,11 @@ export class AUNChannel {
             const detail = error instanceof Error ? error.message : String(error);
             const code = error?.code ?? 'INVALID_MENTION_SCHEMA';
             logger.error(`${this.logPrefix()} Dropped durable AUN payload: invalid payload.mentions (${detail}) code=${code} channel=${channelId}`);
-            return { ok: false, discarded: true };
+            return { ok: false, status: 'permanent', error: detail, code };
+        }
+        if (!this.client || !this.connected) {
+            return { ok: false, status: 'retry', error: 'AUN channel is not connected', code: 'AUN_NOT_CONNECTED' };
         }
-        if (!this.client || !this.connected)
-            return { ok: false };
         const isGroup = delivery.chatType === 'group';
         const targetAid = channelId;
         const encryptTarget = isGroup ? channelId : targetAid;
@@ -3171,10 +3394,11 @@ export class AUNChannel {
                 : await this.callAndTrace(method, sendParams);
             const mid = this.messageIdFromSendResult(result);
             if (!mid) {
-                logger.warn(`${this.logPrefix()} ${method}${fallback ? ' fallback' : ''} (${label}) returned no message_id: ${JSON.stringify(result)}`);
-                return { ok: false, result, encrypt: !!sendParams.encrypt };
+                const failure = classifyAunSendFailure(result, `${method} (${label}) returned no message_id`);
+                logger.warn(`${this.logPrefix()} ${method}${fallback ? ' fallback' : ''} (${label}) returned no message_id: ${JSON.stringify(result)}; disposition=${failure.status}`);
+                return { ok: false, status: failure.status, error: failure.error, code: failure.code, result, encrypt: !!sendParams.encrypt };
             }
-            return { ok: true, messageId: mid, result, encrypt: !!sendParams.encrypt };
+            return { ok: true, status: 'sent', messageId: mid, result, encrypt: !!sendParams.encrypt };
         };
         try {
             return await callOnce(params, false);
@@ -3187,18 +3411,22 @@ export class AUNChannel {
                 try {
                     this.trace('OUT', `${method}.${label}.fallback`, fallbackParams);
                     const sent = await callOnce(fallbackParams, true);
-                    this.trace('OUT', `${method}.${label}.fallback.${sent.ok ? 'ok' : 'missing_id'}`, { message_id: sent.messageId });
+                    this.trace('OUT', `${method}.${label}.fallback.${sent.ok ? 'ok' : 'missing_id'}`, sent.ok
+                        ? { message_id: sent.messageId }
+                        : { disposition: sent.status, code: sent.code });
                     return sent;
                 }
                 catch (e2) {
                     this.trace('OUT', `${method}.${label}.fallback.error`, { channelId, error: String(e2) });
-                    logger.error(`${this.logPrefix()} Plaintext ${label} fallback also failed to ${channelId}: ${e2}`);
-                    return { ok: false };
+                    const failure = classifyAunSendFailure(e2, `${method} plaintext fallback failed`);
+                    logger.error(`${this.logPrefix()} Plaintext ${label} fallback also failed to ${channelId}: ${failure.error}; disposition=${failure.status}`);
+                    return { ok: false, status: failure.status, error: failure.error, code: failure.code };
                 }
             }
             this.trace('OUT', `${method}.${label}.error`, { channelId, error: String(e) });
-            logger.error(`${this.logPrefix()} ${label} send failed to ${channelId}: ${e}`);
-            return { ok: false };
+            const failure = classifyAunSendFailure(e, `${method} failed`);
+            logger.error(`${this.logPrefix()} ${label} send failed to ${channelId}: ${failure.error}; disposition=${failure.status}${failure.code === undefined ? '' : ` code=${failure.code}`}`);
+            return { ok: false, status: failure.status, error: failure.error, code: failure.code };
         }
     }
     recordDurableOutbound(channelId, payload, messageId, encrypt, context, isGroup, contentKind, logText, result, statsContext) {
@@ -3270,11 +3498,19 @@ export class AUNChannel {
             }
             return { queued: true };
         }
-        const result = await this.withOutboxInFlight(entry, () => this.deliverPayloadEntry(entry), { ok: false });
+        const result = await this.withOutboxInFlight(entry, () => this.deliverPayloadEntry(entry), { ok: false, status: 'retry', error: 'outbox send is already in flight' });
         if (result.ok) {
-            outbox.remove(this.config.aid, entry.id);
+            this.removeDeliveredOutboxEntry(entry);
             return { messageId: result.messageId };
         }
+        if (result.status === 'permanent') {
+            this.markPermanentOutboxFailure(entry, result);
+            return {
+                status: 'permanent',
+                ...(result.error !== undefined ? { error: result.error } : {}),
+                ...(result.code !== undefined ? { code: result.code } : {}),
+            };
+        }
         return { queued: true };
     }
     buildTaskPayloadBase(envelope, context) {
@@ -3462,6 +3698,10 @@ export class AUNChannel {
                 ? routedContext.metadata.outboxTtl
                 : undefined,
         });
+        if (entry.terminal) {
+            logger.warn(`${this.logPrefix()} Skipping previously terminated durable operation: operation=${operationId ?? '<none>'} entry=${entry.id} code=${entry.lastErrorCode ?? 'unknown'}`);
+            return;
+        }
         logger.debug(`${this.logPrefix()} Outbox enqueued: id=${entry.id} channel=${channelId} text=${finalText.slice(0, 40)}`);
         // 积压深度告警：outbox 待发条目累积说明发送速度跟不上，回复将出现明显延迟。
         const backlog = outbox.pendingCount(this.config.aid);
@@ -3476,9 +3716,12 @@ export class AUNChannel {
             return;
         }
         // Attempt immediate delivery
-        const ok = await this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), false);
-        if (ok) {
-            outbox.remove(this.config.aid, entry.id);
+        const result = await this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
+        if (result.status === 'sent') {
+            this.removeDeliveredOutboxEntry(entry);
+        }
+        else if (result.status === 'permanent') {
+            this.markPermanentOutboxFailure(entry, result);
         }
     }
     /** Daemon-side transport for `ec msg send` running inside an agent task. */
@@ -3724,7 +3967,7 @@ export class AUNChannel {
                         ttl: 300_000,
                     };
                     const ok = await this.deliverTextEntry(echoEntry);
-                    if (!ok) {
+                    if (ok.status !== 'sent' && ok.status !== 'permanent') {
                         outbox.enqueue(this.config.aid, {
                             channelId,
                             delivery,
@@ -3733,7 +3976,7 @@ export class AUNChannel {
                             context: this.withDelivery(echo.context, delivery),
                         });
                     }
-                    logger.info(`${this.logPrefix()} [Echo] long echo trace delivered=${ok} to ${channelId} (agent ${agentDuration}ms)`);
+                    logger.info(`${this.logPrefix()} [Echo] long echo trace status=${ok.status} code=${ok.code ?? 'none'} to=${channelId} agentDurationMs=${agentDuration}`);
                 }
                 else {
                     outbox.enqueue(this.config.aid, {
@@ -3751,6 +3994,10 @@ export class AUNChannel {
     }
     async deliverTextEntry(entry) {
         const channelId = entry.channelId;
+        if (typeof entry.text !== 'string' || !entry.text.trim()) {
+            logger.warn(`${this.logPrefix()} deliverTextEntry: missing or empty text (outbox id=${entry.id})`);
+            return { status: 'permanent', error: 'durable text is missing or empty', code: 'MISSING_TEXT' };
+        }
         const finalText = entry.text;
         const delivery = this.requirePersistedDelivery(channelId, entry.delivery);
         const context = this.withDelivery(entry.context, delivery);
@@ -3760,12 +4007,13 @@ export class AUNChannel {
             const chatDir = chatDirPath(resolvePaths().sessionsDir, 'aun', channelId, this.config.aid);
             if (hasMessageLogOperation(chatDir, operationId)) {
                 logger.info(`${this.logPrefix()} Durable operation already logged; skipping duplicate send: ${operationId}`);
-                return true;
+                return sentOutboxResult();
             }
             if (operationId === postBootstrapWelcomeOperationId(this.config.aid)) {
                 const agentConfig = loadAgent(this.config.aid);
-                if (!agentConfig || normalizeAgentLifecycle(agentConfig).lifecycle !== 'active')
-                    return false;
+                if (!agentConfig || resolveAgentLifecycle(agentConfig) !== 'active') {
+                    return { status: 'retry', error: 'post-bootstrap welcome is waiting for active lifecycle', code: 'BOOTSTRAP_NOT_ACTIVE' };
+                }
             }
         }
         // 从 context.metadata.source 读取 source，默认为 'daemon'
@@ -3796,7 +4044,7 @@ export class AUNChannel {
         logger.info(`${this.logPrefix()} deliverTextEntry: channelId=${channelId} thread_id=${payload.thread_id ?? 'none'} task_id=${payload.task_id ?? 'none'} chatmode=${payload.chatmode ?? 'none'} source=${source} textLen=${finalText.length}`);
         const isGroup = delivery.chatType === 'group';
         const targetAid = channelId;
-        if (operationId && entry.deliveryReceipt) {
+        if (entry.deliveryReceipt) {
             this.appendOutboundJsonl(channelId, {
                 ...classifyAunPayloadForLog(payload),
                 msgId: entry.deliveryReceipt.messageId,
@@ -3806,7 +4054,7 @@ export class AUNChannel {
                 source,
                 transport: entry.deliveryReceipt.transport,
             });
-            return true;
+            return sentOutboxResult();
         }
         const encryptTarget = isGroup ? channelId : targetAid;
         const encrypt = context?.metadata?.encrypted != null
@@ -3819,16 +4067,19 @@ export class AUNChannel {
             if (isGroup) {
                 params.group_id = channelId;
                 const result = await this.callAndTrace('group.send', params);
-                const mid = result?.message?.message_id ?? result?.message_id ?? null;
+                const mid = this.messageIdFromSendResult(result);
                 if (!mid) {
-                    const dispatchStatus = result?.message_dispatch?.status;
-                    if (dispatchStatus === 'debounced' || dispatchStatus === 'dispatched') {
-                        logger.warn(`${this.logPrefix()} group.send returned ${dispatchStatus} without message_id; keeping outbox entry: group=${channelId} encrypt=${encrypt} text=${finalText.slice(0, 60)}`);
+                    const failure = classifyAunSendFailure(result, 'group.send returned no message_id');
+                    const dispatchStatus = typeof result?.message_dispatch?.status === 'string'
+                        ? result.message_dispatch.status.toLowerCase()
+                        : undefined;
+                    if (dispatchStatus && AUN_ACCEPTED_DISPATCH_STATUSES.has(dispatchStatus)) {
+                        logger.warn(`${this.logPrefix()} group.send returned ${dispatchStatus} without message_id: disposition=${failure.status} code=${failure.code ?? 'unknown'} group=${channelId}`);
                     }
                     else {
-                        logger.warn(`${this.logPrefix()} group.send returned no message_id: ${JSON.stringify(result)}`);
+                        logger.warn(`${this.logPrefix()} group.send returned no message_id: disposition=${failure.status} code=${failure.code ?? 'unknown'} group=${channelId} dispatch=${dispatchStatus ?? 'unknown'}`);
                     }
-                    return false;
+                    return failure;
                 }
                 else {
                     this.logAunSendAccepted('group.send', channelId, mid, encrypt, result, finalText);
@@ -3847,34 +4098,40 @@ export class AUNChannel {
             else {
                 params.to = targetAid;
                 const result = await this.callAndTrace('message.send', params);
-                if (!result || !result.message_id) {
+                const mid = this.messageIdFromSendResult(result);
+                if (!mid) {
                     logger.warn(`${this.logPrefix()} message.send returned no message_id: ${JSON.stringify(result)}`);
-                    return false;
+                    return classifyAunSendFailure(result, 'message.send returned no message_id');
                 }
                 else {
-                    this.logAunSendAccepted('message.send', this.peerLabel(targetAid), result.message_id, encrypt, result, finalText);
-                    this.checkpointTextDelivery(entry, result.message_id, encrypt, result);
+                    this.logAunSendAccepted('message.send', this.peerLabel(targetAid), mid, encrypt, result, finalText);
+                    this.checkpointTextDelivery(entry, mid, encrypt, result);
                     const causation = normalizeCausation(context?.metadata?.causation);
                     if (causation) {
-                        registerAunCausation(result.message_id, this.config.aid, targetAid, causation);
+                        registerAunCausation(mid, this.config.aid, targetAid, causation);
                         recordCausationSpan(causation, 'message.outbound', {
                             status: 'completed',
-                            refs: { messageId: result.message_id, taskId: context?.metadata?.taskId },
+                            refs: { messageId: mid, taskId: context?.metadata?.taskId },
                         });
                     }
-                    appendAidEvent({ ts: Date.now(), iso: new Date().toISOString(), event: 'message_out', aid: this.config.aid, to: targetAid, msgId: result.message_id, kind: 'text', len: finalText.length });
+                    appendAidEvent({ ts: Date.now(), iso: new Date().toISOString(), event: 'message_out', aid: this.config.aid, to: targetAid, msgId: mid, kind: 'text', len: finalText.length });
                     this.aidStatsCollector?.recordOutbound(this.config.aid, targetAid, Buffer.byteLength(finalText, 'utf-8'), finalText, false, encrypt, context?.metadata?.chatmode, 'send');
                     this.appendOutboundJsonl(targetAid, {
-                        ...classifyAunPayloadForLog(payload), msgId: result.message_id, encrypt, context, isGroup: false, source,
+                        ...classifyAunPayloadForLog(payload), msgId: mid, encrypt, context, isGroup: false, source,
                         transport: this.sendReceiptFromResult(result),
                     });
                     // Observer forward: outbound (private) — 原样转发 SDK SendResult（含 envelope + payload）
                     this.forwardOutbound(result);
                 }
             }
-            return true;
+            return sentOutboxResult();
         }
         catch (e) {
+            if (entry.deliveryReceipt) {
+                const error = e instanceof Error ? e.message : String(e);
+                logger.error(`${this.logPrefix()} AUN accepted the durable text but local post-send processing failed; retaining receipt for recovery: id=${entry.id} error=${error}`);
+                return { status: 'retry', error, code: 'OUTBOX_POST_SEND_FAILED' };
+            }
             if (encrypt && e instanceof E2EEError) {
                 this.peerE2ee.set(encryptTarget, { ok: false, ts: Date.now() });
                 logger.warn(`${this.logPrefix()} E2EE send failed to ${channelId}, retrying plaintext: ${e}`);
@@ -3884,11 +4141,14 @@ export class AUNChannel {
                         this.trace('OUT', 'group.send.fallback', params);
                         const result = await this.client.call('group.send', params);
                         const mid = this.messageIdFromSendResult(result);
-                        this.trace('OUT', 'group.send.fallback.ok', { message_id: mid });
                         if (!mid) {
+                            const resultRecord = errorRecord(result);
+                            const dispatch = errorRecord(resultRecord?.message_dispatch)?.status;
+                            this.trace('OUT', 'group.send.fallback.missing_id', { dispatch });
                             logger.warn(`${this.logPrefix()} group.send fallback returned no message_id: ${JSON.stringify(result)}`);
-                            return false;
+                            return classifyAunSendFailure(result, 'group.send plaintext fallback returned no message_id');
                         }
+                        this.trace('OUT', 'group.send.fallback.ok', { message_id: mid });
                         this.checkpointTextDelivery(entry, mid, false, result);
                         appendAidEvent({ ts: Date.now(), iso: new Date().toISOString(), event: 'message_out', aid: this.config.aid, to: channelId, msgId: mid, kind: 'text', len: finalText.length, groupId: channelId });
                         const statsContext = await this.groupStatsContext(channelId);
@@ -3902,12 +4162,13 @@ export class AUNChannel {
                     else {
                         this.trace('OUT', 'message.send.fallback', params);
                         const result = await this.client.call('message.send', params);
-                        const mid = result?.message_id;
-                        this.trace('OUT', 'message.send.fallback.ok', { message_id: mid });
-                        if (!result || !mid) {
+                        const mid = this.messageIdFromSendResult(result);
+                        if (!mid) {
+                            this.trace('OUT', 'message.send.fallback.missing_id', {});
                             logger.warn(`${this.logPrefix()} message.send fallback returned no message_id: ${JSON.stringify(result)}`);
-                            return false;
+                            return classifyAunSendFailure(result, 'message.send plaintext fallback returned no message_id');
                         }
+                        this.trace('OUT', 'message.send.fallback.ok', { message_id: mid });
                         this.checkpointTextDelivery(entry, mid, false, result);
                         const causation = normalizeCausation(context?.metadata?.causation);
                         if (causation) {
@@ -3925,31 +4186,48 @@ export class AUNChannel {
                         });
                         this.forwardOutbound(result);
                     }
-                    return true;
+                    return sentOutboxResult();
                 }
                 catch (e2) {
+                    if (entry.deliveryReceipt) {
+                        const error = e2 instanceof Error ? e2.message : String(e2);
+                        logger.error(`${this.logPrefix()} AUN accepted the plaintext fallback but local post-send processing failed; retaining receipt for recovery: id=${entry.id} error=${error}`);
+                        return { status: 'retry', error, code: 'OUTBOX_POST_SEND_FAILED' };
+                    }
                     this.trace('OUT', 'send.fallback.error', { channelId, error: String(e2) });
                     logger.error(`${this.logPrefix()} Plaintext fallback also failed to ${channelId}: ${e2}`);
-                    return false;
+                    return classifyAunSendFailure(e2, `plaintext send fallback failed to ${channelId}`);
                 }
             }
             else {
                 this.trace('OUT', 'send.error', { channelId, error: String(e) });
                 logger.error(`${this.logPrefix()} Send failed to ${channelId} (outbox id=${entry.id}): ${e}`);
-                return false;
+                return classifyAunSendFailure(e, `send failed to ${channelId}`);
             }
         }
     }
     checkpointTextDelivery(entry, messageId, encrypt, result) {
-        if (!entry.dedupeKey)
-            return;
-        entry.deliveryReceipt = {
+        this.checkpointDurableDelivery(entry, messageId, encrypt, result);
+    }
+    checkpointDurableDelivery(entry, messageId, encrypt, result) {
+        const submittedRoute = {
+            id: entry.id,
+            channelId: entry.channelId,
+            delivery: entry.delivery,
+        };
+        const receipt = {
             messageId,
             encrypt,
             transport: this.sendReceiptFromResult(result),
         };
-        if (!outbox.replace(this.config.aid, entry)) {
-            logger.warn(`${this.logPrefix()} Failed to checkpoint durable operation receipt: ${entry.dedupeKey}`);
+        const replaced = outbox.updateDeliveryReceiptIfRouteMatches(this.config.aid, submittedRoute, receipt);
+        if (replaced === 'replaced') {
+            entry.deliveryReceipt = receipt;
+            return true;
+        }
+        else {
+            logger.warn(`${this.logPrefix()} Did not checkpoint durable delivery receipt: entry=${entry.id} operation=${entry.dedupeKey ?? 'none'} reason=${replaced}`);
+            return false;
         }
     }
     async deliverPayloadEntry(entry) {
@@ -3958,32 +4236,71 @@ export class AUNChannel {
             : undefined;
         if (interactionId && this.invalidatedInteractions.has(interactionId)) {
             logger.info(`${this.logPrefix()} Discarded invalidated interaction from durable outbox: request=${interactionId} entry=${entry.id}`);
-            return { ok: true };
+            return { ok: true, status: 'sent' };
         }
         const channelId = entry.channelId;
         const payload = entry.payload;
         if (!payload) {
             logger.warn(`${this.logPrefix()} deliverPayloadEntry: missing payload (outbox id=${entry.id})`);
-            return { ok: true };
+            return { ok: false, status: 'permanent', error: 'durable payload is missing', code: 'MISSING_PAYLOAD' };
         }
         const contentKind = entry.contentKind;
         const logText = entry.logText ?? this.payloadLogText(payload, contentKind);
         const delivery = this.requirePersistedDelivery(channelId, entry.delivery);
         const context = this.withDelivery(entry.context, delivery);
         logger.info(`${this.logPrefix()} deliverPayloadEntry: id=${entry.id} kind=${contentKind ?? payload.type ?? 'payload'} channelId=${channelId} thread_id=${payload.thread_id ?? 'none'} task_id=${payload.task_id ?? 'none'} textLen=${logText.length}`);
-        const sent = await this.sendAunPayload(channelId, payload, context, `${contentKind ?? payload.type ?? 'payload'}`);
-        if (sent.discarded) {
-            logger.warn(`${this.logPrefix()} Removed malformed durable payload from outbox: id=${entry.id} channel=${channelId}`);
-            return { ok: true, discarded: true };
+        const isGroup = delivery.chatType === 'group';
+        const source = context?.metadata?.source ?? 'daemon';
+        if (entry.deliveryReceipt) {
+            try {
+                this.appendOutboundJsonl(channelId, {
+                    ...classifyAunPayloadForLog(payload),
+                    msgId: entry.deliveryReceipt.messageId,
+                    encrypt: entry.deliveryReceipt.encrypt,
+                    context,
+                    isGroup,
+                    source,
+                    transport: entry.deliveryReceipt.transport,
+                });
+                this.runPostSend(entry, entry.deliveryReceipt.messageId);
+                return {
+                    ok: true,
+                    status: 'sent',
+                    messageId: entry.deliveryReceipt.messageId,
+                    encrypt: entry.deliveryReceipt.encrypt,
+                };
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                logger.error(`${this.logPrefix()} Failed to recover local post-send state from durable payload receipt: id=${entry.id} error=${detail}`);
+                return { ok: false, status: 'retry', error: detail, code: 'OUTBOX_POST_SEND_FAILED' };
+            }
         }
+        const sent = await this.sendAunPayload(channelId, payload, context, `${contentKind ?? payload.type ?? 'payload'}`);
         if (!sent.ok || !sent.messageId)
             return sent;
-        const isGroup = delivery.chatType === 'group';
-        const statsContext = isGroup ? await this.groupStatsContext(channelId) : undefined;
-        this.logAunSendAccepted(isGroup ? 'group.send' : 'message.send', isGroup ? channelId : this.peerLabel(channelId), sent.messageId, !!sent.encrypt, sent.result, logText);
-        this.recordDurableOutbound(channelId, payload, sent.messageId, !!sent.encrypt, context, isGroup, contentKind, logText, sent.result, statsContext);
-        this.runPostSend(entry, sent.messageId);
-        return sent;
+        try {
+            this.checkpointDurableDelivery(entry, sent.messageId, !!sent.encrypt, sent.result);
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            logger.error(`${this.logPrefix()} AUN accepted the durable payload but its receipt could not be persisted: id=${entry.id} mid=${sent.messageId} error=${detail}`);
+            return { ok: false, status: 'permanent', error: detail, code: 'OUTBOX_RECEIPT_CHECKPOINT_FAILED' };
+        }
+        try {
+            const statsContext = isGroup ? await this.groupStatsContext(channelId) : undefined;
+            this.logAunSendAccepted(isGroup ? 'group.send' : 'message.send', isGroup ? channelId : this.peerLabel(channelId), sent.messageId, !!sent.encrypt, sent.result, logText);
+            this.recordDurableOutbound(channelId, payload, sent.messageId, !!sent.encrypt, context, isGroup, contentKind, logText, sent.result, statsContext);
+            this.runPostSend(entry, sent.messageId);
+            return sent;
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            logger.error(`${this.logPrefix()} AUN accepted the durable payload but local post-send processing failed: id=${entry.id} mid=${sent.messageId} error=${detail}`);
+            return entry.deliveryReceipt
+                ? { ok: false, status: 'retry', error: detail, code: 'OUTBOX_POST_SEND_FAILED' }
+                : { ok: false, status: 'permanent', error: detail, code: 'OUTBOX_POST_SEND_UNCHECKPOINTED' };
+        }
     }
     /** 有效会话正文写入 messages.jsonl（message.send/group.send 成功后调用）。 */
     appendOutboundJsonl(channelId, descriptor) {
@@ -4127,16 +4444,22 @@ export class AUNChannel {
             logger.debug(`${this.logPrefix()} thought.put failed to ${channelId}: ${err?.name}(${err?.code})=${err?.message}`);
         }
     }
-    /** 发送结构化 AUN payload；transient 协议载荷不写本地 messages.jsonl。 */
-    async sendStructured(channelId, payload, context) {
+    /** Send a transient structured payload and preserve the gateway disposition. */
+    async sendStructuredResult(channelId, payload, context) {
         const delivery = this.requireDelivery(channelId, context);
         context = this.withDelivery(context, delivery);
         // Validate before checking connection state so malformed producer payloads
         // are reported deterministically instead of being hidden by a disconnect.
         const validatedPayload = this.normalizeAunPayloadMentions(payload);
         const finalPayload = this.stripUndefinedDeep(validatedPayload);
-        if (!this.connected || !this.client)
-            return null;
+        if (!this.connected || !this.client) {
+            return {
+                ok: false,
+                status: 'retry',
+                error: 'AUN channel is not connected',
+                code: 'AUN_NOT_CONNECTED',
+            };
+        }
         const isGroup = delivery.chatType === 'group';
         const targetAid = channelId;
         const encryptTarget = isGroup ? channelId : targetAid;
@@ -4165,27 +4488,54 @@ export class AUNChannel {
             if (isGroup) {
                 params.group_id = delivery.groupId;
                 const result = await this.callAndTrace('group.send', params);
-                const mid = result?.message?.message_id ?? result?.message_id ?? null;
+                const mid = this.messageIdFromSendResult(result);
+                if (!mid) {
+                    const failure = classifyAunSendFailure(result, 'group.send returned no message_id');
+                    logger.warn(`${this.logPrefix()} group.send (${payload.type}) returned no message_id; disposition=${failure.status}`);
+                    return { ok: false, ...failure };
+                }
                 logger.info(`${this.logPrefix()} group.send (${payload.type}) ok: group=${channelId} mid=${mid} encrypt=${encrypt}`);
                 if (!isMenuPayload)
                     this.forwardOutbound(result);
-                return mid;
+                return { ok: true, messageId: mid };
             }
             else {
                 params.to = targetAid;
                 const result = await this.callAndTrace('message.send', params);
-                logger.info(`${this.logPrefix()} message.send (${payload.type}) ok: to=${this.peerLabel(targetAid)} mid=${result?.message_id} encrypt=${encrypt}`);
+                const mid = this.messageIdFromSendResult(result);
+                if (!mid) {
+                    const failure = classifyAunSendFailure(result, 'message.send returned no message_id');
+                    logger.warn(`${this.logPrefix()} message.send (${payload.type}) returned no message_id; disposition=${failure.status}`);
+                    return { ok: false, ...failure };
+                }
+                logger.info(`${this.logPrefix()} message.send (${payload.type}) ok: to=${this.peerLabel(targetAid)} mid=${mid} encrypt=${encrypt}`);
                 if (!isMenuPayload)
                     this.forwardOutbound(result);
-                return result?.message_id ?? null;
+                return { ok: true, messageId: mid };
             }
         }
         catch (e) {
-            const err = e;
-            logger.warn(`${this.logPrefix()} sendStructured failed (${payload.type}) to ${channelId}: ${err?.name}(${err?.code})=${err?.message}`);
-            return null;
+            const failure = classifyAunSendFailure(e, `structured send failed to ${channelId}`);
+            logger.warn(`${this.logPrefix()} sendStructured failed (${payload.type}) to ${channelId}: disposition=${failure.status} code=${failure.code ?? 'unknown'} error=${failure.error}`);
+            return { ok: false, ...failure };
         }
     }
+    /** Compatibility API for optional transient payloads. */
+    async sendStructured(channelId, payload, context) {
+        const result = await this.sendStructuredResult(channelId, payload, context);
+        return result.ok ? result.messageId : null;
+    }
+    /** Strict API for callers that must not report a failed transport as sent. */
+    async sendStructuredOrThrow(channelId, payload, context) {
+        const result = await this.sendStructuredResult(channelId, payload, context);
+        if (result.ok)
+            return result.messageId;
+        throw Object.assign(new Error(result.error), {
+            name: 'AUNSendError',
+            code: result.code ?? 'AUN_SEND_FAILED',
+            retryable: result.status === 'retry',
+        });
+    }
     async sendFile(channelId, filePath, context) {
         const delivery = this.requireDelivery(channelId, context);
         context = this.withDelivery(context, delivery);
@@ -4208,7 +4558,9 @@ export class AUNChannel {
             channelId,
             delivery,
             type: 'file',
+            contentKind: 'file',
             filePath: absPath,
+            logText: `📎 ${path.basename(absPath)} (${formatSize(stat.size)})`,
             context,
         });
         logger.debug(`${this.logPrefix()} Outbox enqueued file: id=${entry.id} channel=${channelId} file=${absPath}`);
@@ -4219,9 +4571,12 @@ export class AUNChannel {
             }
             return;
         }
-        const ok = await this.withOutboxInFlight(entry, () => this.deliverFileEntry(entry), false);
-        if (ok) {
-            outbox.remove(this.config.aid, entry.id);
+        const result = await this.withOutboxInFlight(entry, () => this.deliverFileEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
+        if (result.status === 'sent') {
+            this.removeDeliveredOutboxEntry(entry);
+        }
+        else if (result.status === 'permanent') {
+            this.markPermanentOutboxFailure(entry, result);
         }
     }
     async sendImage(channelId, data, mimeType, alt, context) {
@@ -4263,9 +4618,11 @@ export class AUNChannel {
             }
             return;
         }
-        const ok = await this.withOutboxInFlight(entry, () => this.deliverImageEntry(entry), false);
-        if (ok)
-            outbox.remove(this.config.aid, entry.id);
+        const result = await this.withOutboxInFlight(entry, () => this.deliverImageEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
+        if (result.status === 'sent')
+            this.removeDeliveredOutboxEntry(entry);
+        else if (result.status === 'permanent')
+            this.markPermanentOutboxFailure(entry, result);
     }
     async buildUploadedImagePayload(data, mimeType, alt) {
         if (!this.connected || !this.client) {
@@ -4305,7 +4662,7 @@ export class AUNChannel {
         const image = entry.image;
         if (!image || typeof image.dataBase64 !== 'string') {
             logger.warn(`${this.logPrefix()} deliverImageEntry: missing image data (outbox id=${entry.id})`);
-            return true;
+            return { status: 'permanent', error: 'durable image data is missing', code: 'MISSING_IMAGE_DATA' };
         }
         const delivery = this.requirePersistedDelivery(entry.channelId, entry.delivery);
         entry.delivery = delivery;
@@ -4313,43 +4670,75 @@ export class AUNChannel {
         const data = Buffer.from(image.dataBase64, 'base64');
         if (data.length === 0) {
             logger.warn(`${this.logPrefix()} deliverImageEntry: invalid image data (outbox id=${entry.id})`);
-            return true;
+            return { status: 'permanent', error: 'durable image data is invalid', code: 'INVALID_IMAGE_DATA' };
         }
-        const imagePayload = await this.buildUploadedImagePayload(data, image.mimeType, image.alt);
-        entry.type = 'payload';
-        entry.contentKind = 'image';
-        entry.payload = this.applyReplyContextToPayload(imagePayload, entry.context);
-        entry.logText ??= image.alt ? `[image] ${image.alt}` : '[image]';
-        delete entry.image;
-        // Persist the attachment reference before message.send. A failed send then
-        // retries the compact wire payload without re-uploading the same image.
-        let payloadEntry = entry;
-        if (!outbox.replace(this.config.aid, entry)) {
-            payloadEntry = outbox.enqueue(this.config.aid, {
+        try {
+            const imagePayload = await this.buildUploadedImagePayload(data, image.mimeType, image.alt);
+            entry.type = 'payload';
+            entry.contentKind = 'image';
+            entry.payload = this.applyReplyContextToPayload(imagePayload, entry.context);
+            entry.logText ??= image.alt ? `[image] ${image.alt}` : '[image]';
+            delete entry.image;
+            // Persist the attachment reference before message.send. A failed send then
+            // retries the compact wire payload without re-uploading the same image.
+            const submittedRoute = {
+                id: entry.id,
                 channelId: entry.channelId,
                 delivery,
-                type: 'payload',
-                contentKind: 'image',
-                payload: entry.payload,
-                context: entry.context,
-                logText: entry.logText,
-                ttl: entry.ttl,
-            });
+            };
+            const replaced = outbox.replaceIfRouteMatches(this.config.aid, submittedRoute, entry);
+            if (replaced === 'route-changed') {
+                logger.warn(`${this.logPrefix()} Image route changed during upload; preserving original outbox entry for the corrected route: id=${entry.id}`);
+                return { status: 'retry', error: 'image delivery route changed during upload', code: 'OUTBOX_ROUTE_CHANGED' };
+            }
+            if (replaced === 'missing') {
+                logger.warn(`${this.logPrefix()} Image outbox entry disappeared during upload; skipping send: id=${entry.id}`);
+                return { status: 'permanent', error: 'image outbox entry disappeared during upload', code: 'OUTBOX_ENTRY_MISSING' };
+            }
+            const sent = await this.deliverPayloadEntry(entry);
+            return sent.ok ? sentOutboxResult() : sent;
         }
-        const sent = await this.deliverPayloadEntry(payloadEntry);
-        if (sent.ok && payloadEntry.id !== entry.id) {
-            outbox.remove(this.config.aid, payloadEntry.id);
+        catch (error) {
+            const failure = classifyAunSendFailure(error, 'image upload or send failed');
+            logger.error(`${this.logPrefix()} Image delivery failed (outbox id=${entry.id}): ${failure.error}; disposition=${failure.status}`);
+            return failure;
         }
-        return sent.ok;
     }
     async deliverFileEntry(entry) {
         const channelId = entry.channelId;
+        if (typeof entry.filePath !== 'string' || !entry.filePath.trim()) {
+            logger.warn(`${this.logPrefix()} deliverFileEntry: missing file path (outbox id=${entry.id})`);
+            return { status: 'permanent', error: 'durable file path is missing', code: 'MISSING_FILE_PATH' };
+        }
         const absPath = entry.filePath;
         const delivery = this.requirePersistedDelivery(channelId, entry.delivery);
         const context = this.withDelivery(entry.context, delivery);
+        const isGroup = delivery.chatType === 'group';
+        const source = context?.metadata?.source ?? 'daemon';
+        if (entry.deliveryReceipt) {
+            const filename = path.basename(absPath);
+            const logText = entry.logText ?? `[file] ${filename}`;
+            try {
+                this.appendOutboundJsonl(channelId, {
+                    ...classifyAunPayloadForLog({ type: 'file', text: logText }),
+                    msgId: entry.deliveryReceipt.messageId,
+                    encrypt: entry.deliveryReceipt.encrypt,
+                    context,
+                    isGroup,
+                    source,
+                    transport: entry.deliveryReceipt.transport,
+                });
+                return sentOutboxResult();
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                logger.error(`${this.logPrefix()} Failed to recover local file post-send state from durable receipt: id=${entry.id} error=${detail}`);
+                return { status: 'retry', error: detail, code: 'OUTBOX_POST_SEND_FAILED' };
+            }
+        }
         if (!fs.existsSync(absPath)) {
             logger.warn(`${this.logPrefix()} deliverFileEntry: file gone: ${absPath}`);
-            return true; // remove from outbox, file no longer exists
+            return { status: 'permanent', error: 'file no longer exists', code: 'FILE_NOT_FOUND' };
         }
         const filename = path.basename(absPath);
         const fileData = fs.readFileSync(absPath);
@@ -4404,7 +4793,6 @@ export class AUNChannel {
                 attachment,
                 context,
             });
-            const isGroup = delivery.chatType === 'group';
             const fileTargetAid = channelId;
             const encryptTarget = isGroup ? channelId : fileTargetAid;
             const encrypt = context?.metadata?.encrypted != null
@@ -4419,12 +4807,12 @@ export class AUNChannel {
                     this.trace('OUT', 'group.send.file', params);
                     const result = await this.client.call('group.send', params);
                     sendResult = result;
-                    const fileMid = result?.message?.message_id ?? result?.message_id;
+                    const fileMid = this.messageIdFromSendResult(result);
                     sentMid = fileMid ?? null;
                     this.trace('OUT', 'group.send.file.ok', { message_id: fileMid });
                     if (!fileMid) {
                         logger.warn(`${this.logPrefix()} group.send.file returned no message_id: ${JSON.stringify(result)}`);
-                        return false;
+                        return classifyAunSendFailure(result, 'group.send.file returned no message_id');
                     }
                 }
                 else {
@@ -4432,11 +4820,11 @@ export class AUNChannel {
                     this.trace('OUT', 'message.send.file', params);
                     const result = await this.client.call('message.send', params);
                     sendResult = result;
-                    sentMid = result?.message_id ?? null;
+                    sentMid = this.messageIdFromSendResult(result);
                     this.trace('OUT', 'message.send.file.ok', { message_id: sentMid });
-                    if (!result || !sentMid) {
+                    if (!sentMid) {
                         logger.warn(`${this.logPrefix()} message.send.file returned no message_id: ${JSON.stringify(result)}`);
-                        return false;
+                        return classifyAunSendFailure(result, 'message.send.file returned no message_id');
                     }
                 }
             }
@@ -4453,23 +4841,23 @@ export class AUNChannel {
                         this.trace('OUT', 'group.send.file.fallback', params);
                         const result = await this.client.call('group.send', params);
                         sendResult = result;
-                        const fbMid = result?.message?.message_id ?? result?.message_id;
+                        const fbMid = this.messageIdFromSendResult(result);
                         sentMid = fbMid ?? null;
                         this.trace('OUT', 'group.send.file.fallback.ok', { message_id: fbMid });
                         if (!fbMid) {
                             logger.warn(`${this.logPrefix()} group.send.file fallback returned no message_id: ${JSON.stringify(result)}`);
-                            return false;
+                            return classifyAunSendFailure(result, 'group.send.file plaintext fallback returned no message_id');
                         }
                     }
                     else {
                         this.trace('OUT', 'message.send.file.fallback', params);
                         const result = await this.client.call('message.send', params);
                         sendResult = result;
-                        sentMid = result?.message_id ?? null;
+                        sentMid = this.messageIdFromSendResult(result);
                         this.trace('OUT', 'message.send.file.fallback.ok', { message_id: sentMid });
-                        if (!result || !sentMid) {
+                        if (!sentMid) {
                             logger.warn(`${this.logPrefix()} message.send.file fallback returned no message_id: ${JSON.stringify(result)}`);
-                            return false;
+                            return classifyAunSendFailure(result, 'message.send.file plaintext fallback returned no message_id');
                         }
                     }
                 }
@@ -4477,26 +4865,40 @@ export class AUNChannel {
                     throw sendErr;
                 }
             }
-            logger.info(`${this.logPrefix()} File sent: ${filename} (${formatSize(stat.size)}) → ${channelId}`);
-            if (sentMid) {
-                const fileText = filePayload.text;
-                appendAidEvent({ ts: Date.now(), iso: new Date().toISOString(), event: 'message_out', aid: this.config.aid, to: channelId, msgId: sentMid, kind: 'file', len: fileText.length, ...(isGroup && { groupId: channelId }) });
-                const statsContext = isGroup ? await this.groupStatsContext(channelId) : undefined;
-                this.aidStatsCollector?.recordOutbound(this.config.aid, channelId, Buffer.byteLength(fileText, 'utf-8'), fileText, false, !!params.encrypt, context?.metadata?.chatmode, 'send', statsContext);
-                const source = context?.metadata?.source ?? 'daemon';
-                this.appendOutboundJsonl(channelId, {
-                    ...classifyAunPayloadForLog(filePayload), msgId: sentMid, encrypt: !!params.encrypt,
-                    context, isGroup, source,
-                });
+            if (!sentMid) {
+                return { status: 'permanent', error: 'file send returned no message_id', code: 'MISSING_MESSAGE_ID' };
+            }
+            try {
+                this.checkpointDurableDelivery(entry, sentMid, !!params.encrypt, sendResult);
+            }
+            catch (error) {
+                const detail = error instanceof Error ? error.message : String(error);
+                logger.error(`${this.logPrefix()} AUN accepted the durable file but its receipt could not be persisted: id=${entry.id} mid=${sentMid} error=${detail}`);
+                return { status: 'permanent', error: detail, code: 'OUTBOX_RECEIPT_CHECKPOINT_FAILED' };
             }
+            logger.info(`${this.logPrefix()} File sent: ${filename} (${formatSize(stat.size)}) → ${channelId}`);
+            const fileText = filePayload.text;
+            appendAidEvent({ ts: Date.now(), iso: new Date().toISOString(), event: 'message_out', aid: this.config.aid, to: channelId, msgId: sentMid, kind: 'file', len: fileText.length, ...(isGroup && { groupId: channelId }) });
+            const statsContext = isGroup ? await this.groupStatsContext(channelId) : undefined;
+            this.aidStatsCollector?.recordOutbound(this.config.aid, channelId, Buffer.byteLength(fileText, 'utf-8'), fileText, false, !!params.encrypt, context?.metadata?.chatmode, 'send', statsContext);
+            this.appendOutboundJsonl(channelId, {
+                ...classifyAunPayloadForLog(filePayload), msgId: sentMid, encrypt: !!params.encrypt,
+                context, isGroup, source, transport: this.sendReceiptFromResult(sendResult),
+            });
             if (sendResult)
                 this.forwardOutbound(sendResult);
-            return true;
+            return sentOutboxResult();
         }
         catch (e) {
+            if (entry.deliveryReceipt) {
+                const detail = e instanceof Error ? e.message : String(e);
+                logger.error(`${this.logPrefix()} AUN accepted the durable file but local post-send processing failed; retaining receipt for recovery: id=${entry.id} error=${detail}`);
+                return { status: 'retry', error: detail, code: 'OUTBOX_POST_SEND_FAILED' };
+            }
             this.trace('OUT', 'sendFile.error', { channelId, filePath: absPath, error: String(e) });
-            logger.error(`${this.logPrefix()} sendFile failed for ${channelId} (outbox id=${entry.id}): ${e}`);
-            return false;
+            const failure = classifyAunSendFailure(e, `sendFile failed for ${channelId}`);
+            logger.error(`${this.logPrefix()} sendFile failed for ${channelId} (outbox id=${entry.id}): ${failure.error}; disposition=${failure.status}`);
+            return failure;
         }
     }
     // ── Outbox drain ───────────────────────────────────────────
@@ -4519,58 +4921,80 @@ export class AUNChannel {
     async drainOutbox() {
         if (!this.connected || !this.client)
             return;
-        await this.migrateLegacyBootstrapRoutes();
+        this.repairBootstrapRoutes();
         if (!outbox.hasPending(this.config.aid))
             return;
         logger.info(`${this.logPrefix()} Draining outbox...`);
         const result = await outbox.drain(this.config.aid, async (entry) => {
             if (!isDeliveryTarget(entry.delivery)) {
                 logger.warn(`${this.logPrefix()} Discarding legacy/malformed outbox entry without a trusted delivery route: id=${entry.id} channel=${entry.channelId}`);
-                return true;
+                return {
+                    status: 'permanent',
+                    error: 'outbox entry has no valid delivery route',
+                    code: 'AUN_OUTBOUND_ROUTE_REQUIRED',
+                };
             }
             if (entry.type === 'text') {
-                return this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), false);
+                return this.withOutboxInFlight(entry, () => this.deliverTextEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
             }
             else if (entry.type === 'file') {
-                return this.withOutboxInFlight(entry, () => this.deliverFileEntry(entry), false);
+                return this.withOutboxInFlight(entry, () => this.deliverFileEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
             }
             else if (entry.type === 'image') {
-                return this.withOutboxInFlight(entry, () => this.deliverImageEntry(entry), false);
+                return this.withOutboxInFlight(entry, () => this.deliverImageEntry(entry), { status: 'retry', error: 'outbox send is already in flight' });
             }
             else if (entry.type === 'payload') {
-                const sent = await this.withOutboxInFlight(entry, () => this.deliverPayloadEntry(entry), { ok: false });
-                return sent.ok;
+                const sent = await this.withOutboxInFlight(entry, () => this.deliverPayloadEntry(entry), { ok: false, status: 'retry', error: 'outbox send is already in flight' });
+                return sent.ok ? { status: 'sent' } : sent;
             }
-            return true; // unknown type, discard
+            return { status: 'permanent', error: `unsupported outbox entry type: ${entry.type}`, code: 'UNSUPPORTED_OUTBOX_TYPE' };
         });
-        if (result.sent > 0 || result.expired > 0) {
-            logger.info(`${this.logPrefix()} Outbox drained: sent=${result.sent} expired=${result.expired} failed=${result.failed}`);
+        if (result.sent > 0 || result.expired > 0 || result.permanent) {
+            logger.info(`${this.logPrefix()} Outbox drained: sent=${result.sent} expired=${result.expired} failed=${result.failed} permanent=${result.permanent ?? 0}`);
         }
     }
-    /** Repair pre-route bootstrap entries once the AUN group endpoint is available. */
-    async migrateLegacyBootstrapRoutes() {
+    /** Repair bootstrap outbox entries to the configured personal Owner route. */
+    repairBootstrapRoutes() {
+        const aid = this.config.aid.replace(/^@/, '');
+        const owner = getFirstStaticAgentOwner(aid);
+        if (!owner)
+            return;
         const operationIds = new Set([
-            bootstrapInitialMessageOperationId(this.config.aid),
-            postBootstrapWelcomeOperationId(this.config.aid),
+            bootstrapInitialMessageOperationId(aid),
+            postBootstrapWelcomeOperationId(aid),
         ]);
-        const entries = outbox.load(this.config.aid).filter(entry => typeof entry.dedupeKey === 'string'
-            && operationIds.has(entry.dedupeKey)
-            && entry.channelId
-            && entry.delivery?.chatType === 'private');
+        const entries = [...operationIds]
+            .map(operationId => outbox.findByDedupeKey(aid, operationId, { includeTerminal: true }))
+            .filter((entry) => !!entry?.channelId);
         for (const entry of entries) {
-            const group = await this.isGroup(entry.channelId);
-            if (group !== true)
+            const delivery = { chatType: 'private' };
+            const nestedDelivery = entry.context?.delivery;
+            const routeAlreadyPrivate = entry.channelId === owner
+                && entry.delivery?.chatType === 'private'
+                && (nestedDelivery === undefined || nestedDelivery?.chatType === 'private');
+            if (routeAlreadyPrivate)
                 continue;
-            const delivery = { chatType: 'group', groupId: entry.channelId };
-            if (!outbox.replace(this.config.aid, {
+            const repaired = {
                 ...entry,
+                channelId: owner,
                 delivery,
                 context: entry.context
                     ? { ...entry.context, delivery }
                     : entry.context,
-            }))
+            };
+            // A receipt is scoped to the original transport target. Never treat a
+            // send accepted for a stale group/private address as proof that the
+            // corrected Owner route was delivered.
+            if (entry.channelId !== owner || entry.delivery?.chatType !== 'private') {
+                delete repaired.deliveryReceipt;
+            }
+            delete repaired.terminal;
+            delete repaired.lastError;
+            delete repaired.lastErrorCode;
+            delete repaired.attempts;
+            if (outbox.replaceIfRouteMatches(aid, entry, repaired) !== 'replaced')
                 continue;
-            logger.warn(`${this.logPrefix()} Migrated legacy bootstrap outbox route to group.send: entry=${entry.id} group=${entry.channelId}`);
+            logger.warn(`${this.logPrefix()} Repaired bootstrap outbox route to private Owner delivery: entry=${entry.id} owner=${owner}`);
         }
     }
     acknowledge(messageId) {
@@ -4673,7 +5097,7 @@ export class AUNChannel {
         catch {
             payloadObj = { text: payload };
         }
-        await this.sendStructured(channelId, payloadObj, context);
+        await this.sendStructuredOrThrow(channelId, payloadObj, context);
     }
     async disconnect() {
         this.intentionalDisconnect = true;
@@ -4839,18 +5263,6 @@ export class AUNChannel {
             return undefined; // 不写缓存，下次仍可重试
         }
     }
-    /** Query the authoritative group endpoint without guessing from an AID string. */
-    async isGroup(groupId) {
-        if (!groupId || !this.client)
-            return undefined;
-        try {
-            const result = await this.callAndTrace('group.get_info', { group_id: groupId });
-            return !!(result?.group || result?.group_id || result?.groupId);
-        }
-        catch {
-            return undefined;
-        }
-    }
     /** 统计关系键继续使用群 ID，仅为智能体预览补充可读群名。 */
     async groupStatsContext(groupId) {
         return {
@@ -4895,7 +5307,6 @@ export class AUNChannelPlugin {
         const channel = new AUNChannel({
             aid,
             keystorePath: inst.keystorePath,
-            gatewayUrl: inst.gatewayUrl,
             defaultEncrypt: ctx.aunDefaultEncrypt,
             accessToken: inst.accessToken,
             flushDelay: inst.flushDelay,
@@ -5133,7 +5544,6 @@ export class AUNChannelPlugin {
             uploadAgentMd: (content) => channel.uploadAgentMd(content),
             downloadAgentMd: (aid) => channel.downloadAgentMd(aid),
             getGroupName: (groupId) => channel.getGroupName(groupId),
-            isGroup: (groupId) => channel.isGroup(groupId),
             getGroupMemberRole: (groupId, aid) => channel.getGroupMemberRole(groupId, aid),
             _selfAid: () => channel.getStatus().aid,
             _selfName: () => channel.getSelfName(),