@c4t4/heyamigo 0.9.0 → 0.9.1

package/dist/gateway/outgoing.js

@@ -1,10 +1,11 @@
-import { existsSync, unlinkSync } from 'fs';
+import { existsSync, statSync } from 'fs';
+import { extname } from 'path';
 import { isJidGroup } from 'baileys';
 import { config } from '../config.js';
+import { formatAddress, jidToAddress } from '../db/address.js';
 import { logger } from '../logger.js';
-import { append } from '../store/messages.js';
-import { detectMediaType, sendFile, sendText } from '../wa/sender.js';
-import { getSocket } from '../wa/socket.js';
+import { enqueueOutbound } from '../queue/outbound.js';
+import { detectMediaType } from '../wa/sender.js';
 // Matches [FILE: path], [IMAGE: path], [VIDEO: path], [AUDIO: path], [DOCUMENT: path]
 const FILE_TAG_RE = /\[(?:FILE|IMAGE|VIDEO|AUDIO|DOCUMENT):\s*([^\]]+)\]/gi;
 function extractFiles(reply) {
@@ -21,104 +22,140 @@ function extractFiles(reply) {
     }).trim();
     return { text, files };
 }
-export async function handleReply(job, result, originalMsg) {
-    const sock = getSocket();
-    if (!sock) {
-        logger.warn({ jid: job.jid }, 'no socket available to send reply');
-        return;
+function kindForFile(filePath) {
+    return detectMediaType(filePath);
+}
+const MIME_MAP = {
+    '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif', '.webp': 'image/webp',
+    '.mp4': 'video/mp4', '.avi': 'video/avi', '.mov': 'video/quicktime',
+    '.mkv': 'video/x-matroska',
+    '.mp3': 'audio/mpeg', '.ogg': 'audio/ogg', '.opus': 'audio/opus',
+    '.m4a': 'audio/mp4', '.wav': 'audio/wav',
+    '.pdf': 'application/pdf',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.csv': 'text/csv', '.txt': 'text/plain', '.zip': 'application/zip',
+};
+function mimeFor(filePath) {
+    return MIME_MAP[extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+function fileSize(filePath) {
+    try {
+        return statSync(filePath).size;
+    }
+    catch {
+        return undefined;
     }
+}
+// `originalMsg` is currently ignored when routing through the outbound
+// queue — Baileys quoting needs the full WAMessage embedded in
+// contextInfo, which we'd have to serialize through the DB row and
+// reconstruct. Known regression for Phase 1; see refactor-scrap.md.
+// Kept in the signature so existing callers don't change.
+export async function handleReply(job, result, _originalMsg) {
     const raw = result.reply?.replaceAll('—', ', ').replaceAll('–', '-');
     if (!raw)
         return;
     const { text, files } = extractFiles(raw);
     const isGroup = isJidGroup(job.jid) === true;
-    const quoted = isGroup && config.reply.quoteInGroups ? originalMsg : undefined;
+    void isGroup; // quoting deferred; see comment above
+    const address = formatAddress(jidToAddress(job.jid));
     const footer = result.stats && config.reply.showStats
         ? formatStatsFooter(result.stats)
         : '';
-    try {
-        // Send files first (images, videos, PDFs, audio, etc.)
-        for (const filePath of files) {
-            const isFirst = filePath === files[0];
-            const mediaType = detectMediaType(filePath);
-            // First file gets caption if text is short + single file + supports captions
-            const supportsCaption = mediaType !== 'audio';
-            const caption = isFirst && text && text.length <= 1000 && files.length === 1 && supportsCaption
-                ? text
-                : undefined;
-            // Append footer to caption at send time only (not to storage). Only
-            // when this media file is the final user-facing payload (no text
-            // coming after, single file with caption case).
-            const willHaveTextAfter = !!text &&
-                !(files.length === 1 && text.length <= 1000 && supportsCaption);
-            const captionForSend = caption && footer && !willHaveTextAfter
-                ? `${caption}\n\n${footer}`
-                : caption;
-            await sendFile(sock, job.jid, filePath, captionForSend, isFirst ? quoted : undefined);
-            await append({
-                id: `reply-file-${Date.now()}`,
-                jid: job.jid,
-                direction: 'out',
-                fromMe: true,
-                sender: sock.user?.id ?? '',
-                senderNumber: config.owner.number,
-                timestamp: Math.floor(Date.now() / 1000),
-                text: caption || `[${mediaType}: ${filePath}]`,
-                messageType: `${mediaType}Message`,
-                mediaPath: filePath,
-                mediaType,
-            });
-            logger.info({ jid: job.jid, path: filePath, mediaType }, 'file sent');
-            // Clean up temp file after sending
-            try {
-                unlinkSync(filePath);
-            }
-            catch { }
-            if (files.length > 1)
-                await sleep(config.reply.chunkDelayMs);
-        }
-        // Send text (skip if already used as caption on single file)
-        const textAlreadySent = files.length === 1 && text && text.length <= 1000 && detectMediaType(files[0]) !== 'audio';
-        if (text && !textAlreadySent) {
-            const chunks = chunkText(text, config.reply.chunkChars);
-            for (let i = 0; i < chunks.length; i++) {
-                const chunk = chunks[i];
-                const q = i === 0 && files.length === 0 ? quoted : undefined;
-                const isLast = i === chunks.length - 1;
-                const chunkForSend = isLast && footer ? `${chunk}\n\n${footer}` : chunk;
-                await sendText(sock, job.jid, chunkForSend, q);
-                await append({
-                    id: `reply-${Date.now()}-${i}`,
-                    jid: job.jid,
-                    direction: 'out',
-                    fromMe: true,
-                    sender: sock.user?.id ?? '',
-                    senderNumber: config.owner.number,
-                    timestamp: Math.floor(Date.now() / 1000),
-                    text: chunk,
-                    messageType: 'conversation',
-                });
-                if (i < chunks.length - 1)
-                    await sleep(config.reply.chunkDelayMs);
-            }
-        }
-        if (config.reply.typingIndicator) {
-            await sock
-                .sendPresenceUpdate('paused', job.jid)
-                .catch(() => undefined);
-        }
-        logger.info({
-            jid: job.jid,
-            files: files.length,
-            chars: text.length,
-        }, 'reply sent');
+    let pieceIdx = 0;
+    const baseKey = `reply-${job.jid}-${Date.now()}`;
+    const enqueuePiece = (input) => {
+        enqueueOutbound({ ...input, idempotencyKey: `${baseKey}-${pieceIdx++}` });
+    };
+    // Files first. Caption goes on the single-file-with-short-text case,
+    // matching pre-refactor behavior.
+    for (let i = 0; i < files.length; i++) {
+        const filePath = files[i];
+        const isFirst = i === 0;
+        const kind = kindForFile(filePath);
+        const supportsCaption = kind !== 'audio';
+        const caption = isFirst && text && text.length <= 1000 && files.length === 1 && supportsCaption
+            ? text
+            : undefined;
+        const willHaveTextAfter = !!text && !(files.length === 1 && text.length <= 1000 && supportsCaption);
+        const captionForSend = caption && footer && !willHaveTextAfter
+            ? `${caption}\n\n${footer}`
+            : caption;
+        enqueuePiece({
+            address,
+            kind,
+            text: captionForSend,
+            mediaPath: filePath,
+            mediaMime: mimeFor(filePath),
+            mediaBytes: fileSize(filePath),
+        });
     }
-    catch (err) {
-        logger.error({ err, jid: job.jid }, 'failed to send reply');
+    // Text — skip if already used as a caption on a single file.
+    const textAlreadySent = files.length === 1 &&
+        text &&
+        text.length <= 1000 &&
+        kindForFile(files[0]) !== 'audio';
+    if (text && !textAlreadySent) {
+        const chunks = chunkText(text, config.reply.chunkChars);
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
+            const isLast = i === chunks.length - 1;
+            const chunkForSend = isLast && footer ? `${chunk}\n\n${footer}` : chunk;
+            enqueuePiece({ address, kind: 'text', text: chunkForSend });
+        }
     }
+    logger.info({ jid: job.jid, files: files.length, chars: text.length, pieces: pieceIdx }, 'reply enqueued for outbound');
 }
-function sleep(ms) {
-    return new Promise((r) => setTimeout(r, ms));
+// Proactive outbound: send a message to a chat without an incoming
+// trigger. Same parsing as handleReply; enqueues outbound rows.
+// `text` may contain [FILE:...] tags; they're extracted and enqueued
+// as media. Returns true if anything was enqueued.
+export async function initiate(params) {
+    const raw = params.text.replaceAll('—', ', ').replaceAll('–', '-');
+    if (!raw.trim())
+        return false;
+    const { text, files } = extractFiles(raw);
+    if (!text && files.length === 0)
+        return false;
+    const address = formatAddress(jidToAddress(params.jid));
+    let pieceIdx = 0;
+    const baseKey = `initiate-${params.jid}-${Date.now()}`;
+    const enqueuePiece = (input) => {
+        enqueueOutbound({ ...input, idempotencyKey: `${baseKey}-${pieceIdx++}` });
+    };
+    for (let i = 0; i < files.length; i++) {
+        const filePath = files[i];
+        const isFirst = i === 0;
+        const kind = kindForFile(filePath);
+        const supportsCaption = kind !== 'audio';
+        const caption = isFirst && text && text.length <= 1000 && files.length === 1 && supportsCaption
+            ? text
+            : undefined;
+        enqueuePiece({
+            address,
+            kind,
+            text: caption,
+            mediaPath: filePath,
+            mediaMime: mimeFor(filePath),
+            mediaBytes: fileSize(filePath),
+        });
+    }
+    const textAlreadySent = files.length === 1 &&
+        text &&
+        text.length <= 1000 &&
+        kindForFile(files[0]) !== 'audio';
+    if (text && !textAlreadySent) {
+        const chunks = chunkText(text, config.reply.chunkChars);
+        for (const chunk of chunks) {
+            enqueuePiece({ address, kind: 'text', text: chunk });
+        }
+    }
+    logger.info({ jid: params.jid, files: files.length, chars: text.length, pieces: pieceIdx }, 'proactive message enqueued for outbound');
+    return pieceIdx > 0;
 }
 // Append-only-at-send footer. Never stored, never in Claude's recent-context
 // feedback loop. Adaptive: shows only what's interesting for this reply.
@@ -142,16 +179,12 @@ export function formatStatsFooter(stats) {
         else if (pct >= 70)
             parts.push(`${pct}% ctx`);
     }
-    // Fresh session — resume is default, says nothing
     if (stats.fresh)
         parts.push('fresh');
-    // Journal flagged — show each slug (usually 0 or 1)
     for (const slug of stats.journalSlugs)
         parts.push(`+journal:${slug}`);
-    // Digest fired
     if (stats.hasDigest)
         parts.push('+digest');
-    // Async spawned
     if (stats.asyncCount > 0) {
         parts.push(stats.asyncCount === 1 ? '+async' : `+${stats.asyncCount} async`);
     }
@@ -164,89 +197,6 @@ function compactTokens(n) {
         return `${(n / 1000).toFixed(1)}k`;
     return `${Math.round(n / 1000)}k`;
 }
-// Proactive outbound: send a message to a chat without an incoming trigger.
-// Extracts [FILE:]/[IMAGE:]/etc tags the same way handleReply does — files
-// get sent as WhatsApp media, remaining text sent normally. Chunks, persists
-// to the message log, never throws. Callers are responsible for the
-// canSendProactive() gate — this function does not re-check it.
-export async function initiate(params) {
-    const sock = getSocket();
-    if (!sock) {
-        logger.warn({ jid: params.jid }, 'initiate: no socket available');
-        return false;
-    }
-    const raw = params.text.replaceAll('—', ', ').replaceAll('–', '-');
-    if (!raw.trim())
-        return false;
-    const { text, files } = extractFiles(raw);
-    try {
-        // Send any files first — images, video, PDFs, audio, etc.
-        for (const filePath of files) {
-            const isFirst = filePath === files[0];
-            const mediaType = detectMediaType(filePath);
-            const supportsCaption = mediaType !== 'audio';
-            const caption = isFirst &&
-                text &&
-                text.length <= 1000 &&
-                files.length === 1 &&
-                supportsCaption
-                ? text
-                : undefined;
-            await sendFile(sock, params.jid, filePath, caption);
-            await append({
-                id: `initiate-file-${Date.now()}`,
-                jid: params.jid,
-                direction: 'out',
-                fromMe: true,
-                sender: sock.user?.id ?? '',
-                senderNumber: config.owner.number,
-                timestamp: Math.floor(Date.now() / 1000),
-                text: caption || `[${mediaType}: ${filePath}]`,
-                messageType: `${mediaType}Message`,
-                mediaPath: filePath,
-                mediaType,
-            });
-            logger.info({ jid: params.jid, path: filePath, mediaType }, 'proactive file sent');
-            try {
-                unlinkSync(filePath);
-            }
-            catch { }
-            if (files.length > 1)
-                await sleep(config.reply.chunkDelayMs);
-        }
-        // Send text — skip only when it was used as the caption on a single file
-        const textAlreadySent = files.length === 1 &&
-            text &&
-            text.length <= 1000 &&
-            detectMediaType(files[0]) !== 'audio';
-        if (text && !textAlreadySent) {
-            const chunks = chunkText(text, config.reply.chunkChars);
-            for (let i = 0; i < chunks.length; i++) {
-                const chunk = chunks[i];
-                await sendText(sock, params.jid, chunk);
-                await append({
-                    id: `initiate-${Date.now()}-${i}`,
-                    jid: params.jid,
-                    direction: 'out',
-                    fromMe: true,
-                    sender: sock.user?.id ?? '',
-                    senderNumber: config.owner.number,
-                    timestamp: Math.floor(Date.now() / 1000),
-                    text: chunk,
-                    messageType: 'conversation',
-                });
-                if (i < chunks.length - 1)
-                    await sleep(config.reply.chunkDelayMs);
-            }
-        }
-        logger.info({ jid: params.jid, files: files.length, chars: text.length }, 'proactive message sent');
-        return true;
-    }
-    catch (err) {
-        logger.error({ err, jid: params.jid }, 'initiate failed');
-        return false;
-    }
-}
 export function chunkText(text, maxChars) {
     if (text.length <= maxChars)
         return [text];

package/dist/index.js

@@ -1,19 +1,28 @@
+import { setBaileysSocket } from './channels/index.js';
 import { closeDb, initDb } from './db/index.js';
+import { syncIdentitiesFromAccess } from './db/identity-sync.js';
 import { attachIncoming } from './gateway/incoming.js';
 import { handleReply } from './gateway/outgoing.js';
 import { logger } from './logger.js';
 import { startScheduler } from './memory/scheduler.js';
 import { replayPending } from './queue/queue.js';
+import { startSenderWorker, stopSenderWorker } from './queue/sender-worker.js';
 import { startSocket } from './wa/socket.js';
 async function main() {
     logger.info('heyamigo starting');
     // Migrations + drift check first; refuses to start on schema mismatch.
-    // Additive — flat-file storage (sessions.json, memory files,
-    // access.json) still authoritative until later phases swap them.
     initDb();
+    // Derived view: populate persons + identities from access.json.
+    syncIdentitiesFromAccess();
+    // Sender worker drains outbound queue → channel adapters. Started
+    // before the socket so it's ready when handleReply enqueues rows.
+    startSenderWorker();
     startScheduler();
     await startSocket((sock) => {
         attachIncoming(sock);
+        // Point the Baileys adapter at the live socket. Called on each
+        // reconnect with a fresh sock; the adapter just keeps the latest.
+        setBaileysSocket(sock);
     });
     // Replay any jobs left from a previous crash (no original WAMessage
     // available, so replies are sent as plain messages, not quoted).
@@ -23,11 +32,13 @@ async function main() {
 }
 process.on('SIGINT', () => {
     logger.info('SIGINT received, shutting down');
+    stopSenderWorker();
     closeDb();
     process.exit(0);
 });
 process.on('SIGTERM', () => {
     logger.info('SIGTERM received, shutting down');
+    stopSenderWorker();
     closeDb();
     process.exit(0);
 });

package/dist/queue/outbound-postsend.js

@@ -0,0 +1,77 @@
+// Post-send bookkeeping run by the sender worker after a successful
+// channel send. Kept separate from the worker loop so it's easy to
+// extend (e.g. emit metrics, fire webhooks) without bloating the loop.
+//
+// Today's job:
+//  - Append a row to the message log so Claude sees what the bot
+//    said in future bootstrap context.
+//  - Delete the local file if the outbound row pointed at one and the
+//    path looks like ephemeral outbox content. We trust producers to
+//    only point at files they want unlinked after send.
+import { existsSync, unlinkSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
+import { config } from '../config.js';
+import { addressToExternalId, parseAddress } from '../db/address.js';
+import { logger } from '../logger.js';
+import { append } from '../store/messages.js';
+export async function afterSend(row, sentMsgId) {
+    await persistToMessageLog(row, sentMsgId);
+    maybeUnlinkMedia(row);
+}
+async function persistToMessageLog(row, msgId) {
+    let address;
+    try {
+        address = parseAddress(row.address);
+    }
+    catch {
+        return;
+    }
+    // Message log is currently WA-specific (keyed by JID). Only persist
+    // WA-bound replies for now; multi-channel log unification comes in a
+    // later phase.
+    if (address.channel !== 'wa')
+        return;
+    const jid = addressToExternalId(address);
+    const messageType = row.kind === 'text' ? 'conversation' : `${row.kind}Message`;
+    try {
+        await append({
+            id: `outbound-${row.id}-${msgId}`,
+            jid,
+            direction: 'out',
+            fromMe: true,
+            sender: '',
+            senderNumber: config.owner.number,
+            timestamp: Math.floor(Date.now() / 1000),
+            text: row.text ?? (row.mediaPath ? `[${row.kind}: ${row.mediaPath}]` : ''),
+            messageType,
+            mediaPath: row.mediaPath ?? undefined,
+            mediaType: row.kind === 'text' ? undefined : row.kind,
+        });
+    }
+    catch (err) {
+        logger.warn({ err, outboundId: row.id }, 'failed to append to message log (send already succeeded)');
+    }
+}
+function maybeUnlinkMedia(row) {
+    if (!row.mediaPath)
+        return;
+    // Resolve relative paths the same way the sender worker did when
+    // calling the adapter, so we delete the actual file.
+    const path = isAbsolute(row.mediaPath)
+        ? row.mediaPath
+        : resolve(process.cwd(), row.mediaPath);
+    // Only auto-delete files inside known-ephemeral directories. Inbound
+    // media in storage/media/ has its own retention cron and should not
+    // be touched here. config.storage.mediaDir = inbound media.
+    const inboundMediaDir = resolve(process.cwd(), config.storage.mediaDir);
+    if (path.startsWith(inboundMediaDir)) {
+        return;
+    }
+    try {
+        if (existsSync(path))
+            unlinkSync(path);
+    }
+    catch (err) {
+        logger.warn({ err, path }, 'failed to unlink outbound media file');
+    }
+}

package/dist/queue/outbound.js

@@ -0,0 +1,185 @@
+// Outbound queue helpers. Producers (chat workers, async workers,
+// crons, external triggers) call enqueueOutbound. The sender worker
+// drains via claimNextOutbound + markOutbound{Done,Failed,Retry}.
+//
+// All mutations preserve the claimed_by safety check on completion:
+// only the holder of a claim can mark it done/failed. A slow worker
+// that comes back after TTL-reclaim will harmlessly no-op.
+import { and, asc, eq, isNull, lte, or, sql } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { outbound } from '../db/schema.js';
+// Insert a row, or no-op when the same idempotency_key already exists.
+// Returns the row either way so callers can log/observe.
+export function enqueueOutbound(input) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    // Idempotency: look up first. SQLite has no INSERT ... ON CONFLICT
+    // returning the previous row, so we serve it in two queries inside
+    // a transaction.
+    if (input.idempotencyKey) {
+        const found = db
+            .select()
+            .from(outbound)
+            .where(eq(outbound.idempotencyKey, input.idempotencyKey))
+            .get();
+        if (found)
+            return { inserted: false, row: found };
+    }
+    const inserted = db
+        .insert(outbound)
+        .values({
+        address: input.address,
+        kind: input.kind,
+        text: input.text ?? null,
+        mediaPath: input.mediaPath ?? null,
+        mediaMime: input.mediaMime ?? null,
+        mediaBytes: input.mediaBytes ?? null,
+        quoteMsgId: input.quoteMsgId ?? null,
+        idempotencyKey: input.idempotencyKey ?? null,
+        status: 'pending',
+        attempts: 0,
+        nextAttemptAt: null,
+        lastError: null,
+        claimedBy: null,
+        claimedAt: null,
+        createdAt: now,
+        updatedAt: now,
+    })
+        .returning()
+        .get();
+    return { inserted: true, row: inserted };
+}
+// Atomic claim. Returns the row or null if nothing's ready.
+// Reserves rows whose nextAttemptAt is null (ready immediately) OR in
+// the past (backoff elapsed). Single-statement so two workers can't
+// claim the same row.
+export function claimNextOutbound(workerId) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    // SQLite supports UPDATE ... RETURNING since 3.35.
+    return db.transaction((tx) => {
+        const target = tx
+            .select({ id: outbound.id })
+            .from(outbound)
+            .where(and(eq(outbound.status, 'pending'), or(isNull(outbound.nextAttemptAt), lte(outbound.nextAttemptAt, now))))
+            .orderBy(asc(outbound.id))
+            .limit(1)
+            .get();
+        if (!target)
+            return null;
+        const claimed = tx
+            .update(outbound)
+            .set({
+            status: 'sending',
+            claimedBy: workerId,
+            claimedAt: now,
+            updatedAt: now,
+        })
+            .where(and(eq(outbound.id, target.id), eq(outbound.status, 'pending')))
+            .returning()
+            .get();
+        return claimed ?? null;
+    });
+}
+// Mark done — succeeds only when the row is still owned by the caller.
+// Returns whether the update actually applied.
+export function markOutboundDone(id, workerId) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    const result = db
+        .update(outbound)
+        .set({ status: 'done', updatedAt: now })
+        .where(and(eq(outbound.id, id), eq(outbound.status, 'sending'), eq(outbound.claimedBy, workerId)))
+        .returning({ id: outbound.id })
+        .all();
+    return result.length > 0;
+}
+// Backoff schedule: 1s, 5s, 30s, 2min, give up.
+const BACKOFF_SECONDS = [1, 5, 30, 120];
+const MAX_ATTEMPTS = BACKOFF_SECONDS.length;
+// Transient failure: return to pending with next_attempt_at set, or
+// move to DLQ if attempts exceeded. Caller-owned check applies.
+export function markOutboundRetryOrDlq(id, workerId, errorMessage) {
+    const db = getDb();
+    return db.transaction((tx) => {
+        const row = tx
+            .select()
+            .from(outbound)
+            .where(eq(outbound.id, id))
+            .get();
+        if (!row || row.status !== 'sending' || row.claimedBy !== workerId) {
+            return { retried: false, deadLettered: false };
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const nextAttempts = row.attempts + 1;
+        if (nextAttempts > MAX_ATTEMPTS) {
+            tx.update(outbound)
+                .set({
+                status: 'dlq',
+                attempts: nextAttempts,
+                lastError: errorMessage,
+                claimedBy: null,
+                claimedAt: null,
+                updatedAt: now,
+            })
+                .where(eq(outbound.id, id))
+                .run();
+            return { retried: false, deadLettered: true };
+        }
+        const backoff = BACKOFF_SECONDS[Math.min(row.attempts, BACKOFF_SECONDS.length - 1)];
+        tx.update(outbound)
+            .set({
+            status: 'pending',
+            attempts: nextAttempts,
+            nextAttemptAt: now + backoff,
+            lastError: errorMessage,
+            claimedBy: null,
+            claimedAt: null,
+            updatedAt: now,
+        })
+            .where(eq(outbound.id, id))
+            .run();
+        return { retried: true, deadLettered: false };
+    });
+}
+// Permanent failure (no retry). Used when the error is unrecoverable
+// — e.g. media file missing, malformed address.
+export function markOutboundFailed(id, workerId, errorMessage) {
+    const db = getDb();
+    const now = Math.floor(Date.now() / 1000);
+    const result = db
+        .update(outbound)
+        .set({
+        status: 'failed',
+        lastError: errorMessage,
+        claimedBy: null,
+        claimedAt: null,
+        updatedAt: now,
+    })
+        .where(and(eq(outbound.id, id), eq(outbound.status, 'sending'), eq(outbound.claimedBy, workerId)))
+        .returning({ id: outbound.id })
+        .all();
+    return result.length > 0;
+}
+// Orchestrator helper: reclaim rows whose worker died mid-send.
+// "Stuck in sending past TTL" → return to pending so another worker
+// can pick them up. attempts NOT incremented (the worker may have
+// died before even talking to the channel).
+const CLAIM_TTL_SECONDS = 60;
+export function reclaimStuckOutbound() {
+    const db = getDb();
+    const cutoff = Math.floor(Date.now() / 1000) - CLAIM_TTL_SECONDS;
+    const result = db
+        .update(outbound)
+        .set({
+        status: 'pending',
+        claimedBy: null,
+        claimedAt: null,
+        // intentionally leaving updatedAt as-is so observability can spot reclaims
+        updatedAt: sql `${outbound.updatedAt}`,
+    })
+        .where(and(eq(outbound.status, 'sending'), lte(outbound.claimedAt, cutoff)))
+        .returning({ id: outbound.id })
+        .all();
+    return result.length;
+}