openclaw-lark-multi-agent 1.8.4 → 1.8.6

package/dist/message-store.d.ts

@@ -100,7 +100,69 @@ export type GoJobRow = {
 };
 export declare class MessageStore {
     private db;
-    constructor(dbPath?: string);
+    private knownDeliveryReceipts;
+    constructor(dbPath?: string, options?: {
+        existingOnly?: boolean;
+    });
+    /** LMA-owned recovery journal. Never edits OpenClaw state. Unknown attempts
+     * remain durable and are never selected by the ordinary pending drain. */
+    private initReliabilityTables;
+    getStopGeneration(bot: string, chat: string): number;
+    bumpStopGeneration(bot: string, chat: string): number;
+    setReactionIntent(bot: string, chat: string, row: number, record: object): void;
+    getReactionIntent(bot: string, chat: string, row: number): any;
+    listReactionIntents(bot: string, chat?: string): any[];
+    bindDeliveryRun(bot: string, chat: string, runId: string, record: object): void;
+    getDeliveryRunTarget(bot: string, chat: string, runId: string): any;
+    /** Reserved is persisted before the send-attempt callback; dispatching is
+     * persisted before the RPC. Only reserved + unchanged stop generation proves
+     * no business effect and may be restored on startup. Unknown never replays. */
+    recoverUnsentReservations(bot: string): number;
+    saveAdmission(sessionKey: string, submissionId: string, state: string, record: object): void;
+    listAdmissions(sessionKey: string): any[];
+    stopExactRun(sessionKey: string, runId: string): void;
+    isStoppedObservation(sessionKey: string, runId: string): boolean;
+    settleRunReactionIntents(bot: string, chat: string, runId: string): void;
+    cancelReactionIntents(bot: string, chat: string, epoch: number): void;
+    saveRunObservation(sessionKey: string, runId: string, record: object, nextCheckAt?: number): void;
+    runObservationState(sessionKey: string, runId: string): string | undefined;
+    stopSessionObservations(sessionKey: string): void;
+    settleExactRunReactions(sessionKey: string, runId: string): void;
+    finishRunObservation(sessionKey: string, runId: string, state?: string): void;
+    listRunObservations(sessionKey?: string, due?: number, limit?: number): any[];
+    saveInsertion(bot: string, chat: string, row: number, id: string, state: string, record: object, next?: number): void;
+    claimInsertionAttempt(bot: string, chat: string, row: number): boolean;
+    getInsertion(bot: string, chat: string, row: number): any;
+    listInsertions(bot: string, chat?: string): any[];
+    isInsertionReserved(bot: string, chat: string, row: number): boolean;
+    stopInsertions(bot: string, chat: string): void;
+    hasUnknownDeliveryOperation(outbox: number): boolean;
+    /** Retain the full known result BEFORE the fallible main-journal checkpoint.
+     * The memory copy survives local SQLite failures while this process is alive;
+     * the independent insert journal also survives an interrupted UPDATE/reopen. */
+    rememberKnownDeliveryReceipt(outbox: number, key: string, record: any): void;
+    flushKnownDeliveryReceipts(outbox: number): void;
+    listDeliveryReceipts(outbox: number): Array<{
+        messageId: string;
+        operation: string;
+        payload: any;
+        stage: string;
+    }>;
+    getDeliveryOperation(outbox: number, key: string): any;
+    deferLocalDelivery(id: number, reason: string): number;
+    saveDeliveryOperation(outbox: number, key: string, state: string, record?: object): void;
+    /** Context registration and the corresponding payload checkpoint are one
+     * SQLite transaction. Receipt aliases deduplicate platform echoes by identity,
+     * not by text (two identical legitimate tasks must remain two tasks). */
+    confirmDeliveryStage(id: number, stage: string, content: string, receipts: Array<{
+        messageId: string;
+    }>, checkpoint: 'text' | 'none' | number): void;
+    registerPartialBodyContext(id: number, onlyIfAlreadyPartial?: boolean): void;
+    registerPartialAttachmentContext(id: number): void;
+    /** Read-only preview. Historical text_delivered alone is not a receipt.
+     * Explicit repair requires supplied exact outbox+platform IDs, never resends. */
+    previewMissingDeliveryContext(bot: string, limit?: number): any[];
+    registerHistoricalDeliveryContext(id: number, bot: string, chat: string, messageIds: string[]): void;
     /** Go / Go-Checker supervision state (design: artifacts/lma-go-checker-design-20260917 §10). */
     private initGoTables;
     private ensureGoIntegrationSchema;

package/dist/message-store.js

@@ -4,14 +4,332 @@ import { resolve } from "path";
 import { mkdirSync } from "fs";
 export class MessageStore {
     db;
-    constructor(dbPath) {
+    knownDeliveryReceipts = new Map();
+    constructor(dbPath, options = {}) {
         const path = dbPath || resolve(process.cwd(), "data", "messages.db");
         const dir = resolve(path, "..");
-        mkdirSync(dir, { recursive: true });
-        this.db = new Database(path);
+        if (!options.existingOnly)
+            mkdirSync(dir, { recursive: true });
+        this.db = new Database(path, options.existingOnly ? { fileMustExist: true } : {});
+        if (options.existingOnly)
+            return;
         this.db.pragma("journal_mode = WAL");
         this.init();
         this.initGoTables();
+        this.initReliabilityTables();
+    }
+    /** LMA-owned recovery journal. Never edits OpenClaw state. Unknown attempts
+     * remain durable and are never selected by the ordinary pending drain. */
+    initReliabilityTables() {
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS lma_database_identity (id INTEGER PRIMARY KEY CHECK(id=1),owner TEXT NOT NULL);
+      INSERT OR IGNORE INTO lma_database_identity VALUES(1,'openclaw-lark-multi-agent:messages:v1');
+      CREATE TABLE IF NOT EXISTS bridge_generations(bot_name TEXT NOT NULL,chat_id TEXT NOT NULL,stop_epoch INTEGER NOT NULL DEFAULT 0,PRIMARY KEY(bot_name,chat_id));
+      CREATE TABLE IF NOT EXISTS reaction_custody(bot_name TEXT NOT NULL,chat_id TEXT NOT NULL,row_id INTEGER NOT NULL,record_json TEXT NOT NULL,
+        PRIMARY KEY(bot_name,chat_id,row_id));
+      CREATE TABLE IF NOT EXISTS run_delivery_targets(bot_name TEXT NOT NULL,chat_id TEXT NOT NULL,run_id TEXT NOT NULL,record_json TEXT NOT NULL,PRIMARY KEY(bot_name,chat_id,run_id));
+      CREATE TABLE IF NOT EXISTS admission_custody(session_key TEXT NOT NULL,submission_id TEXT PRIMARY KEY,state TEXT NOT NULL,record_json TEXT NOT NULL);
+      CREATE TABLE IF NOT EXISTS run_observations (
+        session_key TEXT NOT NULL, run_id TEXT NOT NULL, record_json TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'observing', next_check_at INTEGER NOT NULL DEFAULT 0,
+        PRIMARY KEY(session_key,run_id));
+      CREATE TABLE IF NOT EXISTS insertion_custody (
+        bot_name TEXT NOT NULL,chat_id TEXT NOT NULL,message_row_id INTEGER NOT NULL,
+        insertion_id TEXT UNIQUE NOT NULL,record_json TEXT NOT NULL,state TEXT NOT NULL,
+        next_check_at INTEGER NOT NULL DEFAULT 0,PRIMARY KEY(bot_name,chat_id,message_row_id));
+      CREATE TABLE IF NOT EXISTS delivery_operations (
+        outbox_id INTEGER NOT NULL,operation_key TEXT NOT NULL,state TEXT NOT NULL,
+        record_json TEXT NOT NULL DEFAULT '{}',PRIMARY KEY(outbox_id,operation_key));
+      CREATE TABLE IF NOT EXISTS delivery_receipt_custody (
+        outbox_id INTEGER NOT NULL,operation_key TEXT NOT NULL,record_json TEXT NOT NULL,PRIMARY KEY(outbox_id,operation_key));
+      CREATE TABLE IF NOT EXISTS delivery_local_obligations (
+        outbox_id INTEGER PRIMARY KEY,failures INTEGER NOT NULL DEFAULT 0,reason TEXT NOT NULL,updated_at INTEGER NOT NULL);
+      CREATE TABLE IF NOT EXISTS delivery_context (
+        outbox_id INTEGER NOT NULL,stage TEXT NOT NULL,message_row_id INTEGER,
+        PRIMARY KEY(outbox_id,stage));
+      CREATE TABLE IF NOT EXISTS platform_message_aliases (
+        message_id TEXT PRIMARY KEY,message_row_id INTEGER NOT NULL);
+      -- The preceding local candidate never dispatched these blocked inputs.
+      -- Migrate ONLY its explicit no-attempt rows; unknown/attempted stay fenced.
+      UPDATE insertion_custody SET state='pending',next_check_at=0
+        WHERE state='capability_blocked' AND json_extract(record_json,'$.attempted')=0;
+    `);
+    }
+    getStopGeneration(bot, chat) {
+        return this.db.prepare('SELECT stop_epoch FROM bridge_generations WHERE bot_name=? AND chat_id=?').get(bot, chat)?.stop_epoch || 0;
+    }
+    bumpStopGeneration(bot, chat) {
+        this.db.prepare(`INSERT INTO bridge_generations VALUES(?,?,1) ON CONFLICT(bot_name,chat_id) DO UPDATE SET stop_epoch=stop_epoch+1`).run(bot, chat);
+        return this.getStopGeneration(bot, chat);
+    }
+    setReactionIntent(bot, chat, row, record) {
+        this.db.prepare(`INSERT INTO reaction_custody VALUES(?,?,?,?) ON CONFLICT(bot_name,chat_id,row_id) DO UPDATE SET record_json=excluded.record_json`).run(bot, chat, row, JSON.stringify(record));
+    }
+    getReactionIntent(bot, chat, row) {
+        const r = this.db.prepare('SELECT record_json FROM reaction_custody WHERE bot_name=? AND chat_id=? AND row_id=?').get(bot, chat, row);
+        return r ? JSON.parse(r.record_json) : null;
+    }
+    listReactionIntents(bot, chat) {
+        return this.db.prepare(`SELECT chat_id,row_id,record_json FROM reaction_custody WHERE bot_name=? ${chat ? 'AND chat_id=?' : ''}
+      AND (json_extract(record_json,'$.desired')!=json_extract(record_json,'$.shown') OR json_array_length(json_extract(record_json,'$.cleanupReceipts'))>0) LIMIT 200`).all(bot, ...(chat ? [chat] : []))
+            .map(r => ({ ...JSON.parse(r.record_json), chatId: r.chat_id, rowId: r.row_id })).filter(r => r.desired !== r.shown || r.cleanupReceipts?.length);
+    }
+    bindDeliveryRun(bot, chat, runId, record) {
+        this.db.prepare('INSERT OR REPLACE INTO run_delivery_targets VALUES(?,?,?,?)').run(bot, chat, runId, JSON.stringify(record));
+    }
+    getDeliveryRunTarget(bot, chat, runId) {
+        const row = this.db.prepare('SELECT record_json FROM run_delivery_targets WHERE bot_name=? AND chat_id=? AND run_id=?').get(bot, chat, runId);
+        return row ? JSON.parse(row.record_json) : null;
+    }
+    /** Reserved is persisted before the send-attempt callback; dispatching is
+     * persisted before the RPC. Only reserved + unchanged stop generation proves
+     * no business effect and may be restored on startup. Unknown never replays. */
+    recoverUnsentReservations(bot) {
+        return this.db.transaction(() => {
+            let restored = 0;
+            const rows = this.db.prepare(`SELECT a.submission_id,t.chat_id,t.record_json FROM admission_custody a
+        JOIN run_delivery_targets t ON t.run_id=a.submission_id WHERE t.bot_name=? AND a.state='reserved' LIMIT 100`).all(bot);
+            for (const row of rows) {
+                const r = JSON.parse(row.record_json);
+                if (r.stopGeneration !== this.getStopGeneration(bot, row.chat_id))
+                    continue;
+                for (const id of r.triggerIds || []) {
+                    this.markPendingTrigger(bot, row.chat_id, id);
+                    restored++;
+                }
+                this.db.prepare("UPDATE admission_custody SET state='restored-unsubmitted' WHERE submission_id=? AND state='reserved'").run(row.submission_id);
+            }
+            return restored;
+        })();
+    }
+    saveAdmission(sessionKey, submissionId, state, record) {
+        this.db.prepare(`INSERT INTO admission_custody VALUES(?,?,?,?) ON CONFLICT(submission_id) DO UPDATE SET state=excluded.state,record_json=excluded.record_json`).run(sessionKey, submissionId, state, JSON.stringify(record));
+    }
+    listAdmissions(sessionKey) {
+        return this.db.prepare('SELECT * FROM admission_custody WHERE session_key=? ORDER BY rowid DESC LIMIT 100').all(sessionKey).map(r => ({ ...JSON.parse(r.record_json), submissionId: r.submission_id, state: r.state }));
+    }
+    stopExactRun(sessionKey, runId) {
+        this.db.prepare(`INSERT INTO run_observations VALUES(?,?,'{}','stopped',0)
+      ON CONFLICT(session_key,run_id) DO UPDATE SET state='stopped'`).run(sessionKey, runId);
+    }
+    isStoppedObservation(sessionKey, runId) {
+        return !!this.db.prepare("SELECT 1 FROM run_observations WHERE session_key=? AND run_id=? AND state='stopped'").get(sessionKey, runId);
+    }
+    settleRunReactionIntents(bot, chat, runId) {
+        this.db.prepare(`UPDATE reaction_custody SET record_json=json_set(record_json,'$.desired','DONE')
+      WHERE bot_name=? AND chat_id=? AND json_extract(record_json,'$.runId')=?
+      AND json_extract(record_json,'$.desired') IN ('Get','Typing')
+      AND json_extract(record_json,'$.stopEpoch')=?`).run(bot, chat, runId, this.getStopGeneration(bot, chat));
+    }
+    cancelReactionIntents(bot, chat, epoch) {
+        this.db.prepare(`UPDATE reaction_custody SET record_json=json_set(record_json,'$.desired','','$.stopEpoch',?)
+      WHERE bot_name=? AND chat_id=? AND json_extract(record_json,'$.desired') IN ('Typing','Get')`).run(epoch, bot, chat);
+    }
+    saveRunObservation(sessionKey, runId, record, nextCheckAt = Date.now()) {
+        this.db.prepare(`INSERT INTO run_observations VALUES(?,?,?,'observing',?)
+      ON CONFLICT(session_key,run_id) DO UPDATE SET record_json=excluded.record_json,next_check_at=excluded.next_check_at
+      WHERE run_observations.state='observing'`).run(sessionKey, runId, JSON.stringify(record), nextCheckAt);
+    }
+    runObservationState(sessionKey, runId) {
+        return this.db.prepare('SELECT state FROM run_observations WHERE session_key=? AND run_id=?').get(sessionKey, runId)?.state;
+    }
+    stopSessionObservations(sessionKey) {
+        this.db.prepare("UPDATE run_observations SET state='stopped' WHERE session_key=? AND state IN ('observing','outbox_owned')").run(sessionKey);
+    }
+    settleExactRunReactions(sessionKey, runId) {
+        const targets = this.db.prepare('SELECT bot_name,chat_id FROM run_delivery_targets WHERE run_id=?').all(runId);
+        for (const target of targets) {
+            // run ids can repeat across gateways/sessions: require the exact durable target.
+            const row = this.getDeliveryRunTarget(target.bot_name, target.chat_id, runId);
+            const observed = this.db.prepare("SELECT 1 FROM run_observations WHERE session_key=? AND run_id=? AND state='observing'").get(sessionKey, runId);
+            if (observed && (row?.sessionKey || `agent:main:lma-${target.bot_name.toLowerCase()}-${target.chat_id}`) === sessionKey)
+                this.settleRunReactionIntents(target.bot_name, target.chat_id, runId);
+        }
+    }
+    finishRunObservation(sessionKey, runId, state = 'settled') {
+        this.db.prepare("UPDATE run_observations SET state=? WHERE session_key=? AND run_id=? AND state='observing'").run(state, sessionKey, runId);
+    }
+    listRunObservations(sessionKey, due = Date.now(), limit = 50) {
+        return this.db.prepare(`SELECT * FROM run_observations WHERE state='observing' AND next_check_at<=?
+      ${sessionKey ? 'AND session_key=?' : ''} ORDER BY next_check_at LIMIT ?`).all(due, ...(sessionKey ? [sessionKey] : []), limit)
+            .map(r => ({ ...JSON.parse(r.record_json), sessionKey: r.session_key, runId: r.run_id }));
+    }
+    saveInsertion(bot, chat, row, id, state, record, next = Date.now()) {
+        this.db.prepare(`INSERT INTO insertion_custody VALUES(?,?,?,?,?,?,?)
+      ON CONFLICT(bot_name,chat_id,message_row_id) DO UPDATE SET state=excluded.state,record_json=excluded.record_json,next_check_at=excluded.next_check_at
+      WHERE insertion_custody.state NOT IN ('stopped','committed')`).run(bot, chat, row, id, JSON.stringify(record), state, next);
+    }
+    claimInsertionAttempt(bot, chat, row) {
+        return this.db.prepare(`UPDATE insertion_custody SET state='dispatching',record_json=json_set(record_json,'$.attempted',json('true'))
+      WHERE bot_name=? AND chat_id=? AND message_row_id=? AND state='pending'`).run(bot, chat, row).changes === 1;
+    }
+    getInsertion(bot, chat, row) {
+        const r = this.db.prepare('SELECT * FROM insertion_custody WHERE bot_name=? AND chat_id=? AND message_row_id=?').get(bot, chat, row);
+        return r ? { ...JSON.parse(r.record_json), state: r.state, insertionId: r.insertion_id, rowId: r.message_row_id } : null;
+    }
+    listInsertions(bot, chat) {
+        return this.db.prepare(`SELECT * FROM insertion_custody WHERE bot_name=? ${chat ? 'AND chat_id=?' : ''}
+      AND state IN ('pending','accepted','unknown','dispatching') ORDER BY next_check_at LIMIT 100`).all(bot, ...(chat ? [chat] : []))
+            .map(r => ({ ...JSON.parse(r.record_json), state: r.state, insertionId: r.insertion_id, rowId: r.message_row_id, chatId: r.chat_id, nextCheckAt: r.next_check_at }));
+    }
+    isInsertionReserved(bot, chat, row) {
+        const item = this.getInsertion(bot, chat, row);
+        return !!item && !['ordinary', 'stopped'].includes(item.state);
+    }
+    stopInsertions(bot, chat) {
+        this.db.prepare("UPDATE insertion_custody SET state='stopped' WHERE bot_name=? AND chat_id=? AND state NOT IN ('committed','ordinary')").run(bot, chat);
+    }
+    hasUnknownDeliveryOperation(outbox) {
+        return !!this.db.prepare(`SELECT 1 FROM delivery_operations o WHERE outbox_id=? AND state IN ('attempted','unknown')
+      AND NOT EXISTS(SELECT 1 FROM delivery_receipt_custody k WHERE k.outbox_id=o.outbox_id AND k.operation_key=o.operation_key) LIMIT 1`).get(outbox);
+    }
+    /** Retain the full known result BEFORE the fallible main-journal checkpoint.
+     * The memory copy survives local SQLite failures while this process is alive;
+     * the independent insert journal also survives an interrupted UPDATE/reopen. */
+    rememberKnownDeliveryReceipt(outbox, key, record) {
+        this.knownDeliveryReceipts.set(`${outbox}:${key}`, { outbox, key, record });
+        this.flushKnownDeliveryReceipts(outbox);
+    }
+    flushKnownDeliveryReceipts(outbox) {
+        for (const [identity, item] of this.knownDeliveryReceipts)
+            if (item.outbox === outbox) {
+                this.db.prepare('INSERT OR REPLACE INTO delivery_receipt_custody VALUES(?,?,?)').run(outbox, item.key, JSON.stringify(item.record));
+                this.knownDeliveryReceipts.delete(identity);
+            }
+    }
+    listDeliveryReceipts(outbox) {
+        const records = new Map();
+        for (const r of this.db.prepare(`SELECT operation_key,record_json FROM delivery_operations WHERE outbox_id=? AND state='accepted'
+      UNION ALL SELECT operation_key,record_json FROM delivery_receipt_custody WHERE outbox_id=?`).all(outbox, outbox))
+            records.set(r.operation_key, JSON.parse(r.record_json));
+        for (const item of this.knownDeliveryReceipts.values())
+            if (item.outbox === outbox)
+                records.set(item.key, item.record);
+        return [...records].map(([key, r]) => ({ ...r, stage: key.split(':').slice(2, -1).join(':') }))
+            .filter(r => r.result?.data?.message_id || r.result?.message_id)
+            .map(r => ({ messageId: r.result?.data?.message_id || r.result?.message_id, operation: r.operation, payload: r.payload, stage: r.stage }));
+    }
+    getDeliveryOperation(outbox, key) {
+        const known = this.knownDeliveryReceipts.get(`${outbox}:${key}`)?.record;
+        const receipt = this.db.prepare('SELECT record_json FROM delivery_receipt_custody WHERE outbox_id=? AND operation_key=?').get(outbox, key);
+        if (known || receipt)
+            return { state: 'accepted', ...(known || JSON.parse(receipt.record_json)) };
+        const r = this.db.prepare('SELECT * FROM delivery_operations WHERE outbox_id=? AND operation_key=?').get(outbox, key);
+        return r ? { state: r.state, ...JSON.parse(r.record_json) } : null;
+    }
+    deferLocalDelivery(id, reason) {
+        return this.db.transaction(() => {
+            this.db.prepare(`INSERT INTO delivery_local_obligations VALUES(?,1,?,?) ON CONFLICT(outbox_id)
+        DO UPDATE SET failures=failures+1,reason=excluded.reason,updated_at=excluded.updated_at`).run(id, reason, Date.now());
+            // Local persistence and unknown audit custody consume no platform retry budget.
+            this.db.prepare("UPDATE delivery_outbox SET status='pending',attempts=MAX(0,attempts-1),updated_at=? WHERE id=? AND status='delivering'").run(Date.now(), id);
+            return this.db.prepare('SELECT failures FROM delivery_local_obligations WHERE outbox_id=?').get(id).failures;
+        })();
+    }
+    saveDeliveryOperation(outbox, key, state, record = {}) {
+        this.db.prepare(`INSERT INTO delivery_operations VALUES(?,?,?,?) ON CONFLICT(outbox_id,operation_key)
+      DO UPDATE SET state=excluded.state,record_json=excluded.record_json`).run(outbox, key, state, JSON.stringify(record));
+    }
+    /** Context registration and the corresponding payload checkpoint are one
+     * SQLite transaction. Receipt aliases deduplicate platform echoes by identity,
+     * not by text (two identical legitimate tasks must remain two tasks). */
+    confirmDeliveryStage(id, stage, content, receipts, checkpoint) {
+        this.db.transaction(() => {
+            const item = this.db.prepare('SELECT * FROM delivery_outbox WHERE id=?').get(id);
+            if (!item)
+                throw new Error('Missing outbox identity');
+            if (!this.db.prepare('SELECT 1 FROM delivery_context WHERE outbox_id=? AND stage=?').get(id, stage)) {
+                const worthy = ['assistant_visible', 'discussion', 'proactive'].some(k => item.source_type.startsWith(k));
+                let row = null;
+                if (worthy && content.trim() && content.trim().toUpperCase() !== 'NO_REPLY') {
+                    const existing = receipts.map(r => this.getMessageId(r.messageId)).find(Boolean);
+                    if (existing) {
+                        const source = this.db.prepare('SELECT chat_id,sender_type,sender_name FROM messages WHERE id=?').get(existing);
+                        if (source?.chat_id !== item.chat_id || source?.sender_type !== 'bot' || source?.sender_name !== item.bot_name)
+                            throw new Error('Platform receipt identity conflicts with existing message origin');
+                    }
+                    const identity = JSON.parse(item.delivery_meta_json || '{}').botIdentity || item.bot_name;
+                    const messageId = `lma:${JSON.stringify([identity, item.bot_name, item.chat_id, item.delivery_key, stage])}`;
+                    row = existing ?? this.insert({ chatId: item.chat_id, messageId,
+                        senderType: 'bot', senderName: item.bot_name, content, timestamp: Date.now() });
+                    if (row === -1)
+                        row = this.getMessageId(messageId);
+                    for (const receipt of receipts)
+                        if (row)
+                            this.db.prepare('INSERT OR IGNORE INTO platform_message_aliases VALUES(?,?)').run(receipt.messageId, row);
+                }
+                this.db.prepare('INSERT INTO delivery_context VALUES(?,?,?)').run(id, stage, row);
+            }
+            if (checkpoint === 'text')
+                this.markDeliveryTextDelivered(id);
+            else if (typeof checkpoint === 'number')
+                this.markDeliveryAttachmentCursor(id, checkpoint);
+        })();
+    }
+    registerPartialBodyContext(id, onlyIfAlreadyPartial = false) {
+        const hasPartial = !!this.db.prepare("SELECT 1 FROM delivery_context WHERE outbox_id=? AND stage LIKE 'body:partial:%' LIMIT 1").get(id);
+        if (onlyIfAlreadyPartial && !hasPartial)
+            return;
+        for (const receipt of this.listDeliveryReceipts(id).filter(r => r.stage === 'body' && r.payload?.msg_type === 'text')) {
+            let text = '';
+            try {
+                text = JSON.parse(receipt.payload.content).text || '';
+            }
+            catch {
+                continue;
+            }
+            this.confirmDeliveryStage(id, `body:partial:${receipt.messageId}`, text, [receipt], 'none');
+        }
+    }
+    registerPartialAttachmentContext(id) {
+        for (const receipt of this.listDeliveryReceipts(id).filter(r => /^attachment:\d+$/.test(r.stage))) {
+            // Only confirmed, visible file/image payload. A document upload is not a message.
+            if (!['file', 'image'].includes(receipt.payload?.msg_type))
+                continue;
+            let payload;
+            try {
+                payload = JSON.parse(receipt.payload.content);
+            }
+            catch {
+                continue;
+            }
+            this.confirmDeliveryStage(id, `${receipt.stage}:partial:${receipt.messageId}`, `[Attachment: ${receipt.payload.msg_type}] ${JSON.stringify(payload)}`, [receipt], 'none');
+        }
+    }
+    /** Read-only preview. Historical text_delivered alone is not a receipt.
+     * Explicit repair requires supplied exact outbox+platform IDs, never resends. */
+    previewMissingDeliveryContext(bot, limit = 100) {
+        return this.db.prepare(`SELECT d.id,d.chat_id,d.delivery_key,d.source_type,d.text_delivered,d.attachment_cursor
+      FROM delivery_outbox d WHERE bot_name=? AND (status='delivered' AND NOT EXISTS(SELECT 1 FROM delivery_context c WHERE c.outbox_id=d.id)
+        OR EXISTS(SELECT 1 FROM delivery_operations o WHERE o.outbox_id=d.id AND o.state IN ('attempted','unknown'))) ORDER BY d.id LIMIT ?`).all(bot, limit);
+    }
+    registerHistoricalDeliveryContext(id, bot, chat, messageIds) {
+        const item = this.db.prepare("SELECT * FROM delivery_outbox WHERE id=? AND bot_name=? AND chat_id=?").get(id, bot, chat);
+        if (!item || !messageIds.length || messageIds.some(x => !x) || new Set(messageIds).size !== messageIds.length)
+            throw new Error('Exact outbox and independently verified platform receipts required');
+        if (item.status === 'delivered') {
+            this.confirmDeliveryStage(id, 'body', item.content, messageIds.map(messageId => ({ messageId })), 'text');
+            return;
+        }
+        // Explicit operator reconciliation, never an automatic rejection or resend.
+        // Match every supplied message to exactly one unresolved visible operation.
+        const unknown = this.db.prepare("SELECT * FROM delivery_operations WHERE outbox_id=? AND state IN ('attempted','unknown') ORDER BY operation_key").all(id)
+            .map(r => ({ ...r, record: JSON.parse(r.record_json) }));
+        const legacyBody = (r) => r.record.visible === undefined && r.operation_key.split(':').slice(2, -1).join(':') === 'body';
+        if (unknown.length !== messageIds.length || unknown.some(r => (!r.record.visible || !r.record.payload) && !legacyBody(r) || this.getDeliveryOperation(id, r.operation_key)?.state === 'accepted'))
+            throw new Error('Exact visible unknown operations and independent receipts required');
+        this.db.transaction(() => {
+            unknown.forEach((r, i) => {
+                const record = { ...r.record, visible: true, result: { code: 0, data: { message_id: messageIds[i], chat_id: chat } }, reconciliation: { independentlyVerified: true, at: Date.now(), bot, chat } };
+                this.rememberKnownDeliveryReceipt(id, r.operation_key, record);
+                this.saveDeliveryOperation(id, r.operation_key, 'accepted', record);
+            });
+            this.registerPartialBodyContext(id);
+            this.registerPartialAttachmentContext(id);
+            if (unknown.every(r => r.operation_key.split(':').slice(2, -1).join(':') === 'body'))
+                this.confirmDeliveryStage(id, 'body', item.content, messageIds.map(messageId => ({ messageId })), 'text');
+            this.db.prepare("UPDATE delivery_outbox SET status='pending' WHERE id=?").run(id);
+        })();
     }
     /** Go / Go-Checker supervision state (design: artifacts/lma-go-checker-design-20260917 §10). */
     initGoTables() {
@@ -664,6 +982,8 @@ export class MessageStore {
      */
     insert(msg) {
         try {
+            if (this.db.prepare('SELECT 1 FROM platform_message_aliases WHERE message_id=?').get(msg.messageId))
+                return -1;
             const result = this.db.prepare(`
         INSERT INTO messages (chat_id, message_id, sender_type, sender_name, content, timestamp, trigger_kind)
         VALUES (?, ?, ?, ?, ?, ?, ?)
@@ -678,7 +998,7 @@ export class MessageStore {
     }
     getMessageId(messageId) {
         const row = this.db.prepare(`SELECT id FROM messages WHERE message_id = ?`).get(messageId);
-        return row?.id || null;
+        return row?.id || this.db.prepare('SELECT message_row_id FROM platform_message_aliases WHERE message_id=?').get(messageId)?.message_row_id || null;
     }
     getMessageByMessageId(messageId) {
         const row = this.db.prepare(`SELECT * FROM messages WHERE message_id = ?`).get(messageId);
@@ -776,13 +1096,20 @@ export class MessageStore {
     `).run(botName, chatId, triggerMessageRowId, Date.now(), replyMessageId);
     }
     enqueueDelivery(item) {
-        const now = Date.now();
-        const result = this.db.prepare(`
+        return this.db.transaction(() => {
+            const p = JSON.parse(item.deliveryMetaJson || '{}').provenance;
+            if (p?.final && p.sessionKey && p.runId && this.isStoppedObservation(p.sessionKey, p.runId))
+                return null;
+            const now = Date.now();
+            const result = this.db.prepare(`
       INSERT OR IGNORE INTO delivery_outbox
         (session_key, chat_id, bot_name, source_type, source_id, delivery_key, content_hash, content, attachments_json, reply_to_message_id, delivery_mode, target_message_id, delivery_meta_json, text_delivered, attachment_cursor, cleanup_pending, status, attempts, created_at, updated_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, ?)
     `).run(item.sessionKey, item.chatId, item.botName, item.sourceType, item.sourceId, item.deliveryKey, item.contentHash, item.content, item.attachmentsJson, item.replyToMessageId || '', item.deliveryMode || 'send', item.targetMessageId || '', item.deliveryMetaJson || '{}', item.textDelivered ? 1 : 0, item.attachmentCursor || 0, item.cleanupPending ? 1 : 0, now, now);
-        return result.changes ? Number(result.lastInsertRowid) : null;
+            if (p?.final === true && p.sessionKey && p.runId)
+                this.finishRunObservation(p.sessionKey, p.runId, 'outbox_owned');
+            return result.changes ? Number(result.lastInsertRowid) : null;
+        })();
     }
     getDeliveryBySource(sessionKey, sourceType, sourceId) {
         const row = this.db.prepare(`
@@ -899,7 +1226,8 @@ export class MessageStore {
         const result = this.db.prepare(`
       UPDATE delivery_outbox
       SET status = 'pending', updated_at = ?
-      WHERE bot_name = ? AND status = 'delivering'
+      WHERE bot_name = ? AND (status = 'delivering' OR status='failed' AND EXISTS(
+        SELECT 1 FROM delivery_operations o WHERE o.outbox_id=delivery_outbox.id AND o.state IN ('accepted','attempted','unknown')))
     `).run(Date.now(), botName);
         return result.changes;
     }

package/dist/openclaw-client.d.ts

@@ -2,7 +2,7 @@ import type { GoExecutorResult } from "./go-execution.js";
 import { type ErrorProvenance, type ProactiveMessageMeta } from "./terminal-errors.js";
 import { SessionWaitPaused, type SessionRuntimeStatus } from "./session-status.js";
 import { OpenClawConfig } from "./config.js";
-import { ChatMessage } from "./message-store.js";
+import { MessageStore, ChatMessage } from "./message-store.js";
 export type ProgressEvent = {
     kind: "tool";
     phase: "start" | "end" | "error";
@@ -31,6 +31,10 @@ export declare class InactiveRunObservation extends Error {
 export declare class SupersededObservation extends Error {
     constructor(reason?: string);
 }
+export declare class AdmissionUnconfirmed extends Error {
+    readonly submissionId: string;
+    constructor(submissionId: string, cause?: unknown);
+}
 export type ChatAttachment = {
     type?: string;
     mimeType?: string;
@@ -67,8 +71,10 @@ export declare class OpenClawClient {
     /** Deduplicates 2026.8 canonical `agent.stream=tool` events against legacy
      * `stream=item` mirrors when a runtime emits both representations. */
     private recentToolEventKeys;
+    private sessionSettlementCallbacks;
     private sessionMessageCallbacks;
     private progressCallbacks;
+    private progressGenerations;
     /** Live collectReply fences per canonical session key. The most recent
      *  collector for a session owns the shared event bucket; a new batch (or a
      *  queue-custody revocation) fences stale ones synchronously so they cannot
@@ -115,6 +121,19 @@ export declare class OpenClawClient {
     private maintenanceConcurrency;
     private activeMaintenanceRpcs;
     private maintenanceWaiters;
+    private observationEpoch;
+    private stopGenerations;
+    private recoveryStore?;
+    private recoveryTimer?;
+    private recoveryChecking;
+    private eventCollectors;
+    private forwardedFinals;
+    /** One paced recovery scheduler for all persisted exact runs. No business
+     * replay, no per-run infinite timers, and each query has its own deadline. */
+    bindRecoveryStore(store: MessageStore): void;
+    private scheduleRecovery;
+    private recoverExactRuns;
+    private bufferEvent;
     constructor(config: OpenClawConfig);
     connect(): Promise<void>;
     private _doConnect;
@@ -179,24 +198,27 @@ export declare class OpenClawClient {
         message: string;
         label?: string;
     }): Promise<any>;
-    /**
-     * Submit a mid-run message through the lma-steer plugin.
-     *
-     * OpenClaw's public `chat.send { queueMode: "steer" }` returns `started` even
-     * when it falls through to a later ordinary run; it therefore cannot tell the
-     * bridge whether THIS message entered the active run. The plugin resolves the
-     * active embedded run and reports `steered` only when it actually queued there.
-     * A matching session.message remains the final consumption confirmation.
-     *
-     * If the plugin is missing, stale, or rejects the injection, return unavailable
-     * and let LMA's durable trigger run normally after the current turn. Never use
-     * the ambiguous public admission as a realtime-insertion success signal.
-     */
-    steer(sessionKey: string, text: string, displayText?: string): Promise<{
-        status: "steered" | "unavailable" | "no_active_run";
-        runId?: string;
-        /** Cancel provisional transcript correlation when LMA falls back to a normal run. */
-        cancelPending?: () => void;
+    /** Real-time session input uses the coordinated plugin's durable callback
+     * receipt protocol. SDK eligibility/text mirrors never prove acceptance;
+     * missing/legacy plugin observations stay pending without blind mutation. */
+    exactRunSettled(runId: string): Promise<boolean>;
+    cancelSteerSession(sessionKey: string, stopEpoch: number): Promise<void>;
+    steer(sessionKey: string, text: string, displayText?: string, identity?: {
+        insertionId: string;
+        expectedRunId: string;
+        expectedSessionId?: string;
+        stopEpoch?: number;
+        cancel?: boolean;
+        queryOnly?: boolean;
+        originalRunEnded?: boolean;
+    }): Promise<{
+        status: 'pending' | 'accepted' | 'rejected' | 'unknown' | 'target_changed' | 'target_ended' | 'stopped' | 'capability_blocked' | 'unavailable' | 'no_active_run';
+        attempted?: boolean;
+        ordinaryEligible?: boolean;
+        sessionId?: string;
+        reason?: string;
+        insertionId?: string;
+        expectedRunId?: string;
     }>;
     /** Callbacks fired when a steered message is confirmed consumed by the model
      *  (matching sessionUser event). Keyed by bare/short session key. Multiple may
@@ -205,8 +227,8 @@ export declare class OpenClawClient {
      *  Callbacks are one-shot: returning true removes them. */
     private steerConsumedCallbacks;
     /** Register a callback (per bare session key) invoked when a steered message
-     *  is actually consumed by the active run. The bridge uses this to flip the
-     *  Feishu reaction from "Typing" (awaiting insertion) to "Get" (inserted).
+     *  is actually consumed by the active run. This legacy text observer is
+     *  presentation-only; it cannot authorize a receipt reaction.
      *  Return true from the callback to consume/remove it (one-shot). */
     onSteerConsumed(sessionKey: string, matchText: string, cb: (text: string) => boolean | void): () => void;
     private shortKey;
@@ -389,9 +411,11 @@ export declare class OpenClawClient {
         timeoutMs?: number;
         emptyFinalAsNoReply?: boolean;
         /** Called immediately before issuing chat.send RPC; use for at-most-once bookkeeping. */
-        onSendAttempt?: () => void | Promise<void>;
+        onSendAttempt?: (submissionId: string) => void | Promise<void>;
         /** Called after chat.send RPC succeeds and OpenClaw has accepted the user message. */
         onSubmitted?: (runId: string) => void | Promise<void>;
+        /** Identifies collection target; not an acceptance receipt. */
+        onRunIdentified?: (runId: string) => void | Promise<void>;
         onProgress?: (event: ProgressEvent) => void | Promise<void>;
         onWaitPaused?: (notice: SessionWaitPaused) => void | Promise<void>;
     }): Promise<string>;
@@ -424,9 +448,11 @@ export declare class OpenClawClient {
         /** Disable bridge attachment hints for native commands and other exact pass-through messages. */
         includeBridgeAttachmentHint?: boolean;
         /** Called immediately before issuing chat.send RPC; use for at-most-once bookkeeping. */
-        onSendAttempt?: () => void | Promise<void>;
+        onSendAttempt?: (submissionId: string) => void | Promise<void>;
         /** Called after chat.send RPC succeeds and OpenClaw has accepted the combined message. */
         onSubmitted?: (runId: string) => void | Promise<void>;
+        /** Identifies collection target; not an acceptance receipt. */
+        onRunIdentified?: (runId: string) => void | Promise<void>;
         onProgress?: (event: ProgressEvent) => void | Promise<void>;
         onWaitPaused?: (notice: SessionWaitPaused) => void | Promise<void>;
     }): Promise<string>;
@@ -438,7 +464,7 @@ export declare class OpenClawClient {
      * Subscribe to message events for a session.
      * When the agent proactively produces a message, the callback fires.
      */
-    subscribeSession(sessionKey: string, onMessage: (text: string, meta?: ProactiveMessageMeta) => void): Promise<void>;
+    subscribeSession(sessionKey: string, onMessage: (text: string, meta?: ProactiveMessageMeta) => void, onSettled?: (meta: ProactiveMessageMeta) => void | Promise<void>): Promise<void>;
     setVerboseTranscriptDelivery(sessionKey: string, enabled: boolean): void;
     unsubscribeSession(sessionKey: string): Promise<void>;
     /**