whatsapp_notifier 0.7.0 → 0.8.0

data/lib/whatsapp_notifier/services/web_automation/inbound.ts

@@ -1,14 +1,17 @@
-// Inbound capture core (v0.4.0)
+// Inbound capture core (v0.4.0; two-way since v0.8.0)
 //
 // Pure, testable logic for the two-way layer. Kept separate from index.ts so
 // it can be unit-tested without booting a whatsapp-web.js Client.
 //
-// Policy: surface real inbound 1:1 messages (phone @c.us or privacy-id @lid)
-// — dropping our own messages, groups (@g.us), status broadcasts, and non-text
-// system events (e2e_notification, call_log, revoked, …) that carry no real
-// reply. Captured messages buffer in an in-memory queue drained by GET
-// /inbound/:userId (at-least-once; the host dedupes on messageId and decides
-// relevance by matching the resolved phone to its own recipient records).
+// Policy: surface real 1:1 messages in BOTH directions (phone @c.us or
+// privacy-id @lid) — customer replies AND messages the operator sends from
+// the WhatsApp app itself (fromMe), so host threads show whole conversations.
+// Groups (@g.us), status broadcasts, and non-text system events
+// (e2e_notification, call_log, revoked, …) that carry no real reply are
+// dropped. Captured messages buffer in an in-memory queue drained by GET
+// /inbound/:userId (at-least-once; the host dedupes on messageId — which also
+// eats the fromMe echo of its own /send calls — and decides relevance by
+// matching the resolved phone to its own recipient records).
 
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
@@ -29,6 +32,11 @@ export interface InboundMsg {
     mediaFilename?: string;
     mediaSize?: number;
     senderName?: string;
+    // 0.8.0 two-way capture. Present ONLY on operator-sent messages (fromMe),
+    // where `to` carries the counterparty (customer) chat id the host threads
+    // on. Inbound payloads keep the exact pre-0.8.0 shape.
+    fromMe?: boolean;
+    to?: string;
 }
 
 // Media verdict merged into the payload by captureInbound — structurally
@@ -113,11 +121,62 @@ export function drainInbound(userId: string): InboundMsg[] {
     return q;
 }
 
-// Sanity filter for a real inbound 1:1 reply. Accepts both phone-number chats
-// (@c.us) and privacy-id chats (@lid — newer WhatsApp delivers replies from an
-// @lid). Drops own messages, groups (@g.us) and status (@broadcast). The host
-// app decides relevance by matching the resolved phone to its own records, so
-// we no longer gate on the per-send allowlist (which was unreliable).
+// ── Self-send echo registry ──
+//
+// Every POST /send fires its own fromMe message_create echo. Letting that
+// echo run the capture pipeline is pure waste: a media send re-downloads the
+// attachment it just uploaded (up to the 30s download budget on the sending
+// Chromium) and stores bytes nobody will ever fetch against the per-user
+// media cap — at campaign scale those phantom copies churn the cap, evicting
+// REAL customer inbound media the operator still wants. The echo's payload is
+// redundant too: the /send response already handed the host this exact
+// messageId, and the host's id-dedupe would discard the echo anyway — so a
+// registry hit is suppressed ENTIRELY (no media resolution, no enqueue, no
+// webhook), which also closes the host-side echo-beats-response adopt race
+// for same-process sends. Messages NOT in the registry (typed on the phone,
+// or replayed by the reconnect backfill) flow through unchanged.
+//
+// Best-effort by design: the registry is in-memory, so an echo landing after
+// a service restart (or one that fires before /send finishes registering the
+// id) flows through — the host's id-dedupe catches it, harmless. Bounded per
+// user and TTL'd because echoes land within seconds of the send; the limits
+// only have to outlive the echo lag, not the conversation.
+export const SELF_SEND_MAX = 200;
+export const SELF_SEND_TTL_MS = 10 * 60 * 1000;
+
+// userId → (messageId → expiry epoch ms). Maps iterate in insertion order,
+// so the first key is always the oldest send — eviction is O(evicted).
+const selfSendIds = new Map<string, Map<string, number>>();
+
+export function rememberSelfSend(userId: string, messageId: string, nowMs = Date.now()) {
+    let ids = selfSendIds.get(userId);
+    if (!ids) { ids = new Map(); selfSendIds.set(userId, ids); }
+    ids.set(messageId, nowMs + SELF_SEND_TTL_MS);
+    while (ids.size > SELF_SEND_MAX) {
+        ids.delete(ids.keys().next().value as string);
+    }
+}
+
+export function isSelfSend(userId: string, messageId: string, nowMs = Date.now()): boolean {
+    const ids = selfSendIds.get(userId);
+    const expiry = ids && ids.get(messageId);
+    if (expiry === undefined) return false;
+    if (nowMs > expiry) {
+        ids!.delete(messageId); // expired — forget it so the map stays lean
+        return false;
+    }
+    return true;
+}
+
+// Sanity filter for a real 1:1 message in either direction. Accepts both
+// phone-number chats (@c.us) and privacy-id chats (@lid — newer WhatsApp
+// delivers replies from an @lid). The jid gate always validates the
+// COUNTERPARTY: the customer is at `from` on inbound but at `to` on
+// operator-sent (fromMe) messages — gating fromMe on `from` (the operator's
+// own jid, always @c.us) would let group/status posts through. Groups
+// (@g.us) and status (@broadcast) are dropped. The host app decides relevance
+// by matching the resolved phone to its own records, so we no longer gate on
+// the per-send allowlist (which was unreliable).
 // Real human/content message types. Anything else (e2e_notification,
 // notification_template, call_log, revoked, protocol, gp2, …) is a system event
 // with no body and must NOT be surfaced as a reply.
@@ -126,9 +185,9 @@ const TEXTUAL_TYPES = new Set([
 ]);
 
 export function shouldCapture(userId: string, msg: any): boolean {
-    if (!msg || msg.fromMe) return false;
-    const from: string = msg.from || '';
-    if (!from.endsWith('@c.us') && !from.endsWith('@lid')) return false;
+    if (!msg) return false;
+    const counterparty: string = (msg.fromMe ? msg.to : msg.from) || '';
+    if (!counterparty.endsWith('@c.us') && !counterparty.endsWith('@lid')) return false;
     if (msg.isStatus) return false;
     if (msg.type && !TEXTUAL_TYPES.has(msg.type)) return false; // drop system events
     return true;
@@ -136,13 +195,26 @@ export function shouldCapture(userId: string, msg: any): boolean {
 
 export function normalizeInbound(msg: any, media?: InboundMediaInfo): InboundMsg {
     const from: string = msg.from || '';
+    const to: string = msg.to || '';
+    // The fallback id keys on the COUNTERPARTY (the customer): on fromMe the
+    // `from` is the operator's own jid, shared by every chat — id-less
+    // operator messages to different customers in the same second must not
+    // collide in the host's dedupe.
+    const counterparty = msg.fromMe ? to : from;
     const inbound: InboundMsg = {
         from,
         body: msg.body || '',
-        messageId: (msg.id && msg.id._serialized) || `${from}-${msg.timestamp}`,
+        messageId: (msg.id && msg.id._serialized) || `${counterparty}-${msg.timestamp}`,
         timestamp: msg.timestamp || Math.floor(Date.now() / 1000),
         type: msg.type || 'chat'
     };
+    // fromMe/to are added ONLY for operator-sent messages — like the media
+    // keys below, inbound payloads keep the exact pre-0.8.0 shape so older
+    // hosts stay byte-compatible and newer ones key-gate on fromMe presence.
+    if (msg.fromMe) {
+        inbound.fromMe = true;
+        inbound.to = to;
+    }
     // Media keys are added ONLY for media messages so text payloads keep the
     // exact 0.6.0 five-field shape (hosts key-gate on hasMedia presence).
     if (msg.hasMedia) inbound.hasMedia = true;
@@ -165,6 +237,10 @@ export interface CaptureDeps {
 export async function processInbound(userId: string, msg: any, deps: CaptureDeps) {
     if (!shouldCapture(userId, msg)) return;
 
+    // Operator-sent messages take their own (shorter) path: no sender to
+    // resolve, and the chat is keyed by the counterparty at msg.to.
+    if (msg.fromMe) return processOwnMessage(userId, msg, deps);
+
     // One best-effort contact lookup feeds both the sender's display name
     // and the @lid phone resolution. Failure must never drop the message —
     // unless the sender is an unresolvable @lid (handled below).
@@ -212,6 +288,48 @@ export async function processInbound(userId: string, msg: any, deps: CaptureDeps
     if (deps.push) deps.push(userId, inbound);
 }
 
+// Operator-sent (fromMe) leg of the pipeline. The senderName contact lookup
+// is skipped on purpose: the "sender" is the operator themself, so the name
+// adds nothing and the lookup costs a puppeteer roundtrip per message. Media
+// resolution, enqueue and webhook are the SAME as inbound — operator photos/
+// documents sync through the existing GET /media path under the same caps.
+async function processOwnMessage(userId: string, msg: any, deps: CaptureDeps) {
+    // The echo of our own /send: suppress entirely — no media resolution, no
+    // enqueue, no webhook (see the self-send registry above for why).
+    // rememberTarget is skipped too: /send already allowlisted this recipient.
+    const messageId = msg.id && msg.id._serialized;
+    if (messageId && isSelfSend(userId, messageId)) return;
+
+    const to: string = msg.to || '';
+    // An @lid counterparty carries no phone number the host can thread on,
+    // and unlike inbound there is no contact handle to resolve it through
+    // (msg.getContact() resolves the SENDER — here, the operator). Rare in
+    // practice: operator-initiated chats are keyed by the phone @c.us. Drop
+    // with a log rather than forward an unmatchable body.
+    if (to.endsWith('@lid')) {
+        console.log(`Dropping fromMe message to unresolved @lid chat for ${userId}`);
+        return;
+    }
+
+    // Same kept-message-earns-the-download rule as inbound: every resolver
+    // failure mode reports 'unavailable' instead of throwing.
+    let media: InboundMediaInfo | undefined;
+    if (msg.hasMedia) {
+        media = await deps.resolveMedia(userId, msg);
+    }
+
+    const inbound = normalizeInbound(msg, media);
+
+    // A fromMe message to a brand-new number means the operator opened the
+    // conversation in the WhatsApp app — allowlist the chat exactly like
+    // /send does for its recipients, so the reconnect backfill can replay
+    // this conversation after a disconnect window too.
+    rememberTarget(userId, to);
+
+    enqueueInbound(userId, inbound);
+    if (deps.push) deps.push(userId, inbound);
+}
+
 // Minimal slice of whatsapp-web.js Client that backfill needs — a seam so the
 // replay loop can be tested without booting a real client.
 export interface ChatLike {
@@ -267,10 +385,14 @@ export async function backfillTargets(
 export function clearInbound(userId: string) {
     inboundQueues.delete(userId);
     outboundTargets.delete(userId);
+    // Self-send echo ids belong to the old pairing too — and suppression must
+    // never leak across a re-pair (however unlikely an id collision is).
+    selfSendIds.delete(userId);
 }
 
 // Test helper: wipe in-memory state between examples.
 export function resetInboundState() {
     inboundQueues.clear();
     outboundTargets.clear();
+    selfSendIds.clear();
 }

data/lib/whatsapp_notifier/services/web_automation/index.ts

@@ -16,11 +16,14 @@ import {
     InboundMsg,
     configureInbound,
     rememberTarget,
+    rememberSelfSend,
     backfillTargets,
+    resolveChat,
     drainInbound,
     clearInbound,
     processInbound
 } from './inbound';
+import { chatsResponse, historyResponse, refetchResponse, HistoryDeps, RefetchDeps } from './history';
 import {
     configureMedia,
     resolveMediaForMessage,
@@ -29,6 +32,7 @@ import {
     mediaGetResponse,
     mediaDeleteResponse
 } from './media';
+import { sentMessageId } from './send';
 
 const app = new Hono();
 const port = Number(process.env.PORT || 3001);
@@ -114,8 +118,10 @@ async function captureInbound(userId: string, msg: any) {
 async function backfillInbound(userId: string, client: Client) {
     // On reconnect, replay recent messages ONLY from chats we actually messaged
     // (the per-send allowlist) so a disconnect window doesn't drop a reply —
-    // without scraping every personal conversation on the linked number. Live
-    // replies are covered by the message_create handler; this is just recovery.
+    // without scraping every personal conversation on the linked number.
+    // fetchMessages returns BOTH directions, so operator-app (fromMe) messages
+    // typed during the window recover too. Live traffic is covered by the
+    // message_create handler; this is just recovery.
     await backfillTargets(userId, client, captureInbound);
 }
 
@@ -195,6 +201,8 @@ async function waitForClientReady(clientData: ClientData, timeoutMs = 30000): Pr
     throw new Error('Client not ready: WhatsApp Web store did not initialize in time');
 }
 
+// Resolves to the sent whatsapp-web.js Message so /send can hand the real
+// message id back to the host (the echo-dedupe key for two-way capture).
 async function sendMessageWithRetry(client: Client, clientData: ClientData, chatId: string, message: string, mediaUrl?: string | null) {
     const maxAttempts = 5;
 
@@ -206,12 +214,10 @@ async function sendMessageWithRetry(client: Client, clientData: ClientData, chat
             if (mediaUrl) {
                 const { MessageMedia } = require('whatsapp-web.js');
                 const media = await MessageMedia.fromUrl(mediaUrl);
-                await client.sendMessage(chatId, media, { caption: message });
-            } else {
-                await client.sendMessage(chatId, message);
+                return await client.sendMessage(chatId, media, { caption: message });
             }
 
-            return;
+            return await client.sendMessage(chatId, message);
         } catch (error) {
             console.error(`Send attempt ${attempt}/${maxAttempts} failed for chat ${chatId}:`, error);
 
@@ -302,10 +308,13 @@ async function getOrCreateClient(userId: string): Promise<ClientData> {
         backfillInbound(userId, client).catch((e) => console.error(`Backfill failed for ${userId}`, e));
     });
 
-    // Capture inbound replies. Only 'message_create' — it fires reliably for
-    // every message across linked/multi-device sessions (plain 'message'
-    // silently never fires on some). shouldCapture drops our own sends (fromMe)
-    // + groups/status; the queue dedupes on message_id on the Rails side.
+    // Capture BOTH directions of every 1:1 chat. Only 'message_create' — it
+    // fires reliably for every message across linked/multi-device sessions
+    // (plain 'message' silently never fires on some) and, unlike 'message',
+    // also fires for operator-sent (fromMe) messages, which the host threads
+    // as the other half of the conversation since 0.8.0. shouldCapture drops
+    // groups/status; the host dedupes on message_id — including the fromMe
+    // echo of its own /send calls.
     client.on('message_create', (msg) => captureInbound(userId, msg));
 
     client.on('authenticated', () => {
@@ -537,13 +546,21 @@ app.post('/send/:userId', async (c) => {
 
     try {
         const chatId = to.includes('@c.us') ? to : `${to}@c.us`;
-        await sendMessageWithRetry(data.client, data, chatId, message, mediaUrl);
+        const sent = await sendMessageWithRetry(data.client, data, chatId, message, mediaUrl);
 
         // Record the recipient so their replies survive a reconnect backfill.
         rememberTarget(userId, chatId);
 
         data.lastUsed = Date.now();
-        return c.json({ success: true });
+        // messageId is the echo-dedupe key: this send fires its own fromMe
+        // message_create, which the host must match by id (see send.ts).
+        const messageId = sentMessageId(sent);
+        // Register the id so the echo is suppressed service-side (no media
+        // re-download, no queue slot, no webhook — see inbound.ts). Best
+        // effort: an echo that already fired before sendMessage resolved
+        // flows through, and the host's id-dedupe catches it.
+        if (messageId) rememberSelfSend(userId, messageId);
+        return c.json({ success: true, messageId });
     } catch (error: any) {
         console.error(`Send error for user ${userId}:`, error);
         return c.json({ success: false, error: error.message }, 500);
@@ -574,6 +591,58 @@ app.get('/media/:userId/:messageId', (c) =>
 app.delete('/media/:userId/:messageId', (c) =>
     mediaDeleteResponse(c.req.param('userId'), c.req.param('messageId'), c.req.header('X-WA-Token'), WEBHOOK_TOKEN));
 
+// ── Chat history (history.ts) ──
+//
+// Shared deps for the two history routes: the SAME pairing fast-reject and
+// client accessor /send uses (never any other initialization path), plus
+// inbound.ts's chat resolver + reconnect allowlist.
+const historyDeps: HistoryDeps = {
+    hasPaired: (userId) => hasPairedSession(userId, clients, sessionDirForUser),
+    getClient: getOrCreateClient,
+    resolveChat,
+    rememberTarget
+};
+
+// GET /chats/:userId — list the paired number's 1:1 chats (discovery for the
+// host's old-conversation sync). Token-gated like /media; paired+ready gated
+// like /send; capped at the newest 500 (see history.ts).
+app.get('/chats/:userId', (c) =>
+    chatsResponse(c.req.param('userId'), c.req.header('X-WA-Token'), WEBHOOK_TOKEN, historyDeps));
+
+// POST /history/:userId { chatId, limit } — replay one chat's history through
+// the live-capture normalizer and return it DIRECTLY in the response (no
+// queue, no webhook — the host ingests synchronously). History media is
+// marked unavailable by design, never downloaded (see history.ts).
+app.post('/history/:userId', async (c) =>
+    historyResponse(
+        c.req.param('userId'),
+        await c.req.json().catch(() => ({})),
+        c.req.header('X-WA-Token'),
+        WEBHOOK_TOKEN,
+        historyDeps
+    ));
+
+// POST /media/:userId/refetch { messageId, chatId } — WhatsApp tap-to-download.
+// The host calls this when an operator opens an evicted/expired media bubble:
+// re-pull THAT message's bytes on demand, store them (cap re-enforced), and
+// report ready so the host can GET /media as usual. Token-gated + paired-ready
+// gated like /history; media no longer upstream → 404 'gone'. Reuses the live
+// resolveMediaForMessage pipeline (per-message size cap + 30s timeout).
+const refetchDeps: RefetchDeps = {
+    ...historyDeps,
+    getMessageById: (client, messageId) => client.getMessageById(messageId),
+    resolveMedia: (userId, msg) => resolveMediaForMessage(userId, msg)
+};
+
+app.post('/media/:userId/refetch', async (c) =>
+    refetchResponse(
+        c.req.param('userId'),
+        await c.req.json().catch(() => ({})),
+        c.req.header('X-WA-Token'),
+        WEBHOOK_TOKEN,
+        refetchDeps
+    ));
+
 
 console.log(`Starting Multi-User WhatsApp service (Bun Native) on port ${port}...`);
 

data/lib/whatsapp_notifier/services/web_automation/media.test.ts

@@ -16,6 +16,9 @@ import {
     mediaTtlMs,
     maxDocumentBytes,
     maxDiskBytes,
+    maxUserBytes,
+    userDirBytes,
+    enforceUserCap,
     downloadPolicy,
     sweepExpired,
     resolveMediaForMessage,
@@ -29,7 +32,7 @@ const root = mkdtempSync(join(tmpdir(), 'wa-media-'));
 let mediaRoot: string;
 let caseId = 0;
 
-const ENV_KEYS = ['WHATSAPP_MEDIA_TTL_MS', 'WHATSAPP_MEDIA_MAX_BYTES', 'WHATSAPP_MEDIA_MAX_DISK_BYTES'];
+const ENV_KEYS = ['WHATSAPP_MEDIA_TTL_MS', 'WHATSAPP_MEDIA_MAX_BYTES', 'WHATSAPP_MEDIA_MAX_DISK_BYTES', 'WHATSAPP_MEDIA_MAX_USER_BYTES'];
 const savedEnv: Record<string, string | undefined> = {};
 
 beforeEach(() => {
@@ -282,10 +285,12 @@ test('malformed limit envs fall back to the defaults instead of NaN', () => {
     process.env.WHATSAPP_MEDIA_TTL_MS = '2 days';
     process.env.WHATSAPP_MEDIA_MAX_BYTES = 'garbage';
     process.env.WHATSAPP_MEDIA_MAX_DISK_BYTES = '50GB';
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '1 gig';
 
     expect(mediaTtlMs()).toBe(48 * 60 * 60 * 1000);
     expect(maxDocumentBytes()).toBe(25 * 1024 * 1024);
     expect(maxDiskBytes()).toBe(5 * 1024 * 1024 * 1024);
+    expect(maxUserBytes()).toBe(1024 * 1024 * 1024);
 
     // The guards stay live: the document cap still rejects oversize media...
     expect(downloadPolicy('document', 25 * 1024 * 1024 + 1))
@@ -296,13 +301,151 @@ test('malformed limit envs fall back to the defaults instead of NaN', () => {
     expect(sweepExpired(Date.now() + 48 * 60 * 60 * 1000 + 1000)).toBe(1);
 });
 
-test('downloadPolicy refuses a download that would blow the disk cap', () => {
-    expect(maxDiskBytes()).toBe(5 * 1024 * 1024 * 1024);
+// The per-user cap is now enforced post-write by eviction, so downloadPolicy
+// NEVER skips a download on disk grounds — a user is never starved. Even with
+// a tiny disk cap and a near-full disk, the policy still says download (the
+// post-write enforceUserCap rolls the oldest off instead).
+test('downloadPolicy never refuses on disk grounds (per-user eviction replaces starvation)', () => {
     process.env.WHATSAPP_MEDIA_MAX_DISK_BYTES = '12';
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '12';
     writeMedia(USER, 'taken', bytes('1234567890'), { mime: 'image/png' }); // 10 bytes used
 
     expect(downloadPolicy('image', 2)).toEqual({ download: true });
-    expect(downloadPolicy('image', 3)).toEqual({ download: false, reason: 'disk_full' });
+    expect(downloadPolicy('image', 3)).toEqual({ download: true });  // would-blow-disk still allowed
+    expect(downloadPolicy('image', INLINE_MEDIA_MAX_BYTES)).toEqual({ download: true }); // up to the per-message cap
+
+    // ...but the per-MESSAGE size gate still rejects oversize media.
+    expect(downloadPolicy('image', INLINE_MEDIA_MAX_BYTES + 1)).toEqual({ download: false, reason: 'too_large' });
+});
+
+// ── maxUserBytes / userDirBytes / enforceUserCap (per-user rolling cap) ──
+
+// Backdate a stored item's capturedAt so the oldest-first eviction order is
+// deterministic regardless of write timing (sub-ms writes share a clock).
+function backdate(userId: string, messageId: string, capturedAt: number) {
+    const p = mediaPaths(userId, messageId)!;
+    const sidecar = JSON.parse(readFileSync(p.metaPath, 'utf8'));
+    sidecar.capturedAt = capturedAt;
+    writeFileSync(p.metaPath, JSON.stringify(sidecar));
+}
+
+test('maxUserBytes defaults to 1GB', () => {
+    expect(maxUserBytes()).toBe(1024 * 1024 * 1024);
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '2048';
+    expect(maxUserBytes()).toBe(2048);
+});
+
+test('userDirBytes counts only that user payloads, sidecars excluded', () => {
+    writeMedia(USER, 'm1', bytes('12345'), { mime: 'image/png' });
+    writeMedia(USER, 'm2', bytes('1234567890'), { mime: 'image/png' });
+    writeMedia('7', 'other', bytes('123'), { mime: 'image/png' });
+
+    expect(userDirBytes(USER)).toBe(15);   // 5 + 10, sidecar JSON not counted
+    expect(userDirBytes('7')).toBe(3);     // scoped per user
+    expect(userDirBytes('never')).toBe(0); // no dir yet
+    expect(userDirBytes('..')).toBe(0);    // unsanitizable id
+});
+
+// Writing past 1GB (here: a tiny cap) evicts THAT user's OLDEST media, oldest
+// first, until they fit — the new media survives. Stored under a generous cap
+// and backdated to fix the age order, then enforced under the tight cap so the
+// eviction is deterministic (not at the mercy of the inline write hook).
+test('writing past the user cap evicts the user oldest media first', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '1000'; // generous: no inline eviction
+    writeMedia(USER, 'm1', bytes('12345'), { mime: 'image/png' }); backdate(USER, 'm1', 1); // 5
+    writeMedia(USER, 'm2', bytes('12345'), { mime: 'image/png' }); backdate(USER, 'm2', 2); // 5
+    writeMedia(USER, 'm3', bytes('12345'), { mime: 'image/png' }); backdate(USER, 'm3', 3); // 5
+    expect(mediaDiskBytes()).toBe(15);
+
+    // Tighten to 12 and enforce: 15 > 12 → evict the oldest (m1, 5) → 10 ≤ 12.
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '12';
+    expect(enforceUserCap(USER)).toBe(1);
+
+    expect(mediaExists(USER, 'm1')).toBeNull();        // oldest gone
+    expect(mediaExists(USER, 'm2')).not.toBeNull();
+    expect(mediaExists(USER, 'm3')).not.toBeNull();
+    expect(userDirBytes(USER)).toBe(10);
+    expect(mediaDiskBytes()).toBe(10);                 // global total kept honest
+});
+
+test('enforceUserCap evicts multiple oldest items when the dir blows well past the cap', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '1000'; // generous during the writes
+    writeMedia(USER, 'a', bytes('111'), { mime: 'image/png' }); backdate(USER, 'a', 1); // 3
+    writeMedia(USER, 'b', bytes('222'), { mime: 'image/png' }); backdate(USER, 'b', 2); // 3
+    writeMedia(USER, 'c', bytes('3333333333'), { mime: 'image/png' }); backdate(USER, 'c', 3); // 10
+
+    // 16 bytes, cap 6 → evict a (3) → 13, evict b (3) → 10, evict c (10) → 0.
+    // Even the single 10-byte file exceeds the cap, so the loop empties the dir.
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '6';
+    expect(enforceUserCap(USER)).toBe(3);
+    expect(userDirBytes(USER)).toBe(0);
+    expect(mediaDiskBytes()).toBe(0);
+});
+
+test('enforceUserCap evicts one user without touching another (independent caps)', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '1000'; // generous during the writes
+    writeMedia(USER, 'a', bytes('111'), { mime: 'image/png' }); backdate(USER, 'a', 1); // 3
+    writeMedia(USER, 'b', bytes('222'), { mime: 'image/png' }); backdate(USER, 'b', 2); // 3
+    writeMedia('7', 'x', bytes('12345'), { mime: 'image/png' }); backdate('7', 'x', 1); // 5
+    writeMedia('7', 'y', bytes('12345'), { mime: 'image/png' }); backdate('7', 'y', 2); // +5 = 10
+
+    // Cap 6: USER (6 bytes) is exactly at the cap → no eviction; user 7 (10) is over.
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '6';
+    expect(enforceUserCap(USER)).toBe(0);
+    expect(mediaExists(USER, 'a')).not.toBeNull();
+    expect(mediaExists(USER, 'b')).not.toBeNull();
+
+    // User 7 over cap evicts only user 7 oldest; USER untouched.
+    expect(enforceUserCap('7')).toBe(1);
+    expect(mediaExists('7', 'x')).toBeNull();     // user 7 oldest gone
+    expect(mediaExists('7', 'y')).not.toBeNull();
+    expect(userDirBytes(USER)).toBe(6);           // the other user is intact
+});
+
+test('enforceUserCap is a no-op for a user under the cap, an empty dir and bad ids', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '100';
+    writeMedia(USER, 'm1', bytes('12345'), { mime: 'image/png' });
+
+    expect(enforceUserCap(USER)).toBe(0);         // under cap
+    expect(mediaExists(USER, 'm1')).not.toBeNull();
+    expect(enforceUserCap('never-stored')).toBe(0); // no dir
+    expect(enforceUserCap('..')).toBe(0);           // unsanitizable id
+});
+
+// NaN cap → enforceUserCap must still use the 1GB default, never treat NaN as
+// "0, evict everything" or "Infinity, never evict via a broken comparison".
+test('enforceUserCap falls back to the 1GB default on a malformed cap env', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = 'one gigabyte';
+    writeMedia(USER, 'm1', bytes('12345'), { mime: 'image/png' });
+
+    expect(maxUserBytes()).toBe(1024 * 1024 * 1024);
+    expect(enforceUserCap(USER)).toBe(0);         // 5 bytes ≪ 1GB → nothing evicted
+    expect(mediaExists(USER, 'm1')).not.toBeNull();
+});
+
+// The post-write hook: writeMedia itself enforces the cap, so a caller that
+// just writes (no explicit enforceUserCap) still rolls the oldest off. Here
+// capturedAt ties on the shared clock, so the eviction falls back to file
+// mtime ordering — the regression that proves the mtime path works.
+test('writeMedia enforces the cap inline, falling back to mtime order on a clock tie', () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '12';
+    const first = mediaPaths(USER, 'm1')!;
+    writeMedia(USER, 'm1', bytes('12345'), { mime: 'image/png' });
+    // Make m1 unambiguously older by mtime AND drop its sidecar capturedAt so
+    // the age source falls back to mtime.
+    const sidecar = JSON.parse(readFileSync(first.metaPath, 'utf8'));
+    delete sidecar.capturedAt;
+    writeFileSync(first.metaPath, JSON.stringify(sidecar));
+    const past = (Date.now() - 60000) / 1000;
+    utimesSync(first.dataPath, past, past);
+
+    writeMedia(USER, 'm2', bytes('12345'), { mime: 'image/png' }); // 10 ≤ 12 → no eviction
+    writeMedia(USER, 'm3', bytes('12345'), { mime: 'image/png' }); // 15 > 12 → evict oldest (m1)
+
+    expect(mediaExists(USER, 'm1')).toBeNull();
+    expect(mediaExists(USER, 'm2')).not.toBeNull();
+    expect(mediaExists(USER, 'm3')).not.toBeNull();
+    expect(userDirBytes(USER)).toBe(10);
 });
 
 // ── sweepExpired ──
@@ -425,13 +568,24 @@ test('resolveMediaForMessage re-checks the real byte size after download', async
     expect(mediaExists(USER, MSG_ID)).toBeNull();
 });
 
-test('resolveMediaForMessage reports disk_full when the actual bytes blow the cap', async () => {
-    process.env.WHATSAPP_MEDIA_MAX_DISK_BYTES = '12';
-    writeMedia(USER, 'taken', bytes('12345678'), { mime: 'image/png' }); // 8 used
-    // Unknown declared size sails through the pre-check; the 10 real bytes don't fit.
+// The download always succeeds now; the per-user cap is honoured AFTER the
+// write by evicting the user's oldest, so the new media is always available.
+test('resolveMediaForMessage stores the new media and evicts the oldest under the cap', async () => {
+    process.env.WHATSAPP_MEDIA_MAX_USER_BYTES = '12';
+    // An older payload (backdated so it is unambiguously the oldest).
+    writeMedia(USER, 'oldest', bytes('12345678'), { mime: 'image/png' }); // 8 used
+    const oldPaths = mediaPaths(USER, 'oldest')!;
+    const sidecar = JSON.parse(readFileSync(oldPaths.metaPath, 'utf8'));
+    sidecar.capturedAt = 1; // ancient
+    writeFileSync(oldPaths.metaPath, JSON.stringify(sidecar));
+
+    // 10 real bytes arrive → 18 > 12 → the oldest (8) is rolled off, leaving 10.
     const msg = mediaMsg({}, { size: undefined });
     expect(await resolveMediaForMessage(USER, msg))
-        .toEqual({ mediaStatus: 'unavailable', mediaError: 'disk_full' });
+        .toEqual({ mediaStatus: 'available', mediaMime: 'image/jpeg', mediaFilename: 'beach.jpg', mediaSize: 10 });
+    expect(mediaExists(USER, MSG_ID)).not.toBeNull();   // new media kept
+    expect(mediaExists(USER, 'oldest')).toBeNull();     // oldest evicted
+    expect(mediaDiskBytes()).toBe(10);
 });
 
 test('resolveMediaForMessage maps undefined download results to expired', async () => {
@@ -473,6 +627,18 @@ test('resolveMediaForMessage falls back to the from-timestamp message id', async
     expect(mediaExists(USER, '919999000001@c.us-1717000000')).not.toBeNull();
 });
 
+// The fallback must mirror normalizeInbound's COUNTERPARTY keying: on fromMe
+// the `from` is the operator's own jid, shared by every chat — keying on it
+// stores the bytes under an id the wire never advertised (host GET 404s) and
+// collides two same-second sends to different customers on the same path.
+test('resolveMediaForMessage keys the fromMe fallback id on the counterparty', async () => {
+    const msg = mediaMsg({ id: undefined, fromMe: true, from: '919000000001@c.us', to: '919999000002@c.us' });
+    const verdict = await resolveMediaForMessage(USER, msg);
+    expect(verdict.mediaStatus).toBe('available');
+    expect(mediaExists(USER, '919999000002@c.us-1717000000')).not.toBeNull();   // keyed on `to`…
+    expect(mediaExists(USER, '919000000001@c.us-1717000000')).toBeNull();       // …never the operator
+});
+
 test('resolveMediaForMessage fills mime/filename gaps and omits a missing filename', async () => {
     const msg = mediaMsg(
         { downloadMedia: async () => ({ data: Buffer.from('x').toString('base64') }) },