whatsapp_notifier 0.8.1 → 0.9.1

data/docs/CONFIGURATION.md

@@ -0,0 +1,89 @@
+# Configuration reference
+
+Every configuration option and every environment variable, with its type and
+default read from the source. The gem is configured in Ruby; the bundled service
+is configured through environment variables.
+
+## Ruby configuration
+
+Set these in `config/initializers/whatsapp_notifier.rb`:
+
+```ruby
+WhatsAppNotifier.configure do |config|
+  config.bulk_max_recipients = 300
+  # ...
+end
+```
+
+`WhatsAppNotifier.configure` runs `validate!` after the block, so an invalid
+value raises `WhatsAppNotifier::ConfigurationError` at boot.
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `provider` | Symbol | `:web_automation` | Messaging backend. Only `:web_automation` is supported; any other value fails `validate!`. |
+| `web_adapter` | object | `WhatsAppNotifier::WebAdapter.new` | HTTP client that talks to the service. Must respond to `send_message`, `fetch_qr_code`, and `connection_status`. |
+| `web_session_path` | String | `"tmp/whatsapp_notifier/session.json"` | File where the gem stores per-user session pointers. |
+| `bulk_base_delay_seconds` | Float | `1.0` | Base pause between consecutive bulk sends. |
+| `bulk_jitter_seconds` | Float | `0.3` | Upper bound of random jitter added to each bulk pause. |
+| `bulk_max_recipients` | Integer | `500` | Largest batch `deliver_bulk` accepts. Must be positive. |
+| `bulk_max_attempts` | Integer | `3` | Attempts per message during bulk retries. Must be positive. |
+| `bulk_retryable_error_codes` | Array\<Symbol\> | `%i[rate_limited network_error temporary_failure]` | Error codes that make a failed bulk send eligible for retry. |
+| `logger` | Logger | `Logger.new($stdout)` | Logger used for warnings and diagnostics. |
+| `web_automation_enabled` | Boolean | `true` | When false, the provider raises instead of sending. A kill switch. |
+| `warn_on_risky_provider` | Boolean | `true` | Logs a one-time warning that web automation is unofficial. |
+| `authenticate_with` | callable or nil | `nil` | Runs as a `before_action` inside the engine's controllers (for example `-> { authenticate_user! }`). |
+| `current_user_id_resolver` | callable | resolves `current_user.id` | How the engine identifies the current user when talking to the service. |
+| `parent_controller` | String | `"::ApplicationController"` | Class the engine's controllers inherit from, so they pick up your layout and filters. |
+| `on_inbound_message_handler` | callable or nil | `nil` | Optional host hook invoked with each inbound message hash, for push-based integrations that would rather not poll. |
+
+## Ruby-side environment variables
+
+Read by the gem (the adapter, doctor, and CLI):
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `WHATSAPP_NOTIFIER_SERVICE_URL` | `http://127.0.0.1:3001` | Base URL of the service. `https://` URLs are honored natively. |
+| `WHATSAPP_SERVICE_URL` | (unset) | Legacy alias used only when `WHATSAPP_NOTIFIER_SERVICE_URL` is unset. |
+| `WHATSAPP_WEBHOOK_TOKEN` | (unset) | When set, the adapter sends it as the `X-WA-Token` header on media, chats, and history requests, matching the service's gate. |
+| `PUPPETEER_EXECUTABLE_PATH` | (unset) | Path to the Chromium/Chrome binary. Checked by `doctor` and the `service` command. |
+| `WHATSAPP_SESSION_DIR` | `tmp/whatsapp_notifier/.wwebjs_auth` (via `doctor`/CLI) | Session directory the `doctor` check and the `service` launcher use. See the note below. |
+
+## Service environment variables
+
+Read by the bundled Bun service under
+`lib/whatsapp_notifier/services/web_automation`:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `PORT` | `3001` | Port the service listens on. The `service` command's `--port` flag sets this. |
+| `WHATSAPP_SESSION_DIR` | `/whatsapp_data` | Base directory for per-user WhatsApp sessions. See the note below. |
+| `PUPPETEER_EXECUTABLE_PATH` | (Puppeteer default) | Chromium/Chrome binary to launch. |
+| `WHATSAPP_INIT_TIMEOUT_MS` | `90000` | Recycle a client that boots Chromium but never reaches QR or READY. |
+| `WWEBJS_WEB_VERSION` | (library default) | Pin the WhatsApp Web build (for example `2.3000.1023204887`) so a live change on web.whatsapp.com cannot break the client. |
+| `WWEBJS_WEB_VERSION_CACHE_URL` | wa-version template URL | Remote cache location for the pinned web version. |
+| `WHATSAPP_WEBHOOK_URL` | (unset) | If set, the service POSTs each inbound message here instead of relying only on polling. |
+| `WHATSAPP_WEBHOOK_TOKEN` | (unset) | Shared secret sent as `X-WA-Token` on webhook pushes. When set, it also gates `/media`, `/chats`, and `/history`. Set it in production. |
+| `WHATSAPP_MAX_CONCURRENT_INITS` | `3` | Cap on concurrent Chromium launches, so a herd of cold starts cannot exhaust memory. |
+| `WHATSAPP_UNREADY_REAP_MS` | `1800000` (30 min) | Destroy non-ready clients idle at least this long (abandoned pairing screens). Ready clients keep a 72h idle limit. |
+| `WHATSAPP_BROWSER_TIMEOUT_MS` | `60000` | Puppeteer browser launch timeout. |
+| `WHATSAPP_PROTOCOL_TIMEOUT_MS` | `120000` | Puppeteer protocol timeout. |
+| `WHATSAPP_MEDIA_TTL_MS` | `172800000` (48h) | Lifetime of downloaded inbound media before the sweep evicts it. |
+| `WHATSAPP_MEDIA_MAX_BYTES` | `26214400` (25MB) | Per-document download cap. Inline images and voice notes cap at WhatsApp's 16MB ceiling. |
+| `WHATSAPP_MEDIA_MAX_USER_BYTES` | `1073741824` (1GB) | Per-user rolling media cap with LRU eviction. The cap that shapes disk use. |
+| `WHATSAPP_MEDIA_MAX_DISK_BYTES` | `5368709120` (5GB) | Absolute global backstop for total media on disk. |
+
+Malformed numeric values (for example `"50GB"`) fall back to the default rather
+than parsing to `NaN` and disabling a limit.
+
+### Note on the session directory
+
+`WHATSAPP_SESSION_DIR` has two different defaults depending on how the service
+starts:
+
+- Run directly (`bun index.ts`), it defaults to `/whatsapp_data`.
+- Run through `bundle exec whatsapp_notifier service`, the CLI sets it, if unset,
+  to `tmp/whatsapp_notifier/.wwebjs_auth` relative to the current working
+  directory.
+
+In production, set `WHATSAPP_SESSION_DIR` explicitly to a durable mount so logins
+survive restarts and redeploys.

data/lib/whatsapp_notifier/client.rb

@@ -27,6 +27,10 @@ module WhatsAppNotifier
       provider_for(provider || @configuration.provider).connection_status(metadata: metadata)
     end
 
+    def session_ready?(metadata: {}, provider: nil)
+      provider_for(provider || @configuration.provider).session_ready?(metadata: metadata)
+    end
+
     def fetch_inbound(metadata: {}, provider: nil)
       provider_for(provider || @configuration.provider).fetch_inbound(metadata: metadata)
     end

data/lib/whatsapp_notifier/error_code.rb

@@ -0,0 +1,137 @@
+module WhatsAppNotifier
+  # Stable, machine-readable classification of a failed send.
+  #
+  # Before 0.9.0 every send failure surfaced as error_code :delivery_exception,
+  # so hosts had to fingerprint Result#error_message text to decide whether a
+  # retry was safe. These codes replace that. They are part of the public API
+  # and will not be renamed:
+  #
+  #   :auth_required        session logged out / service refused upfront —
+  #                         nothing was sent
+  #   :not_on_whatsapp      the number has no WhatsApp account
+  #   :invalid_phone        the number is malformed
+  #   :recipient_unresolved the service could not resolve the recipient id
+  #                         (wedged session) — nothing was sent
+  #   :service_unreachable  the TCP connection never opened — nothing was sent
+  #   :timeout              the request went out but the answer never came, so
+  #                         the outcome is UNKNOWN — a retry may double-send
+  #   :rate_limited         the service throttled the send
+  #   :delivery_exception   unclassified; the pre-0.9.0 catch-all, kept as the
+  #                         fallback so hosts keying on it keep working
+  #
+  # The first four plus :service_unreachable are "definitely not sent"; only
+  # :timeout and :delivery_exception leave the outcome ambiguous.
+  module ErrorCode
+    UNCLASSIFIED = :delivery_exception
+
+    ALL = %i[
+      auth_required
+      not_on_whatsapp
+      invalid_phone
+      recipient_unresolved
+      service_unreachable
+      timeout
+      rate_limited
+      delivery_exception
+    ].freeze
+
+    # HTTP status → code, for a non-2xx answer from the service. Checked
+    # first: a status is exact where the body text is a guess. 422 is
+    # deliberately absent — the service 422s a malformed REQUEST (a host bug),
+    # not a bad number, so it falls through to the unclassified catch-all.
+    STATUS_CODES = {
+      401 => :auth_required,
+      403 => :auth_required,
+      429 => :rate_limited
+    }.freeze
+
+    # Exception class name → code. Matched on the name rather than the
+    # constant so this file never has to require net/http or resolve Errno.
+    EXCEPTION_CODES = {
+      "Errno::ECONNREFUSED" => :service_unreachable,
+      "Errno::ECONNRESET" => :service_unreachable,
+      "Errno::EHOSTUNREACH" => :service_unreachable,
+      "Errno::ENETUNREACH" => :service_unreachable,
+      "SocketError" => :service_unreachable,
+      "Net::OpenTimeout" => :service_unreachable,
+      "Net::ReadTimeout" => :timeout,
+      "Net::WriteTimeout" => :timeout,
+      "Timeout::Error" => :timeout
+    }.freeze
+
+    # Codes a service (or a third-party adapter) may hand us directly, folded
+    # into the vocabulary above. Several spellings map to one code because the
+    # Bun service has renamed its own codes across versions.
+    SERVICE_CODES = {
+      "auth_required" => :auth_required,
+      "unauthenticated" => :auth_required,
+      "unauthorized" => :auth_required,
+      "session_expired" => :auth_required,
+      "not_on_whatsapp" => :not_on_whatsapp,
+      "number_not_on_whatsapp" => :not_on_whatsapp,
+      "number_not_registered" => :not_on_whatsapp,
+      "invalid_phone" => :invalid_phone,
+      "invalid_number" => :invalid_phone,
+      "recipient_unresolved" => :recipient_unresolved,
+      "service_unreachable" => :service_unreachable,
+      "timeout" => :timeout,
+      "rate_limited" => :rate_limited,
+      "throttled" => :rate_limited
+    }.freeze
+
+    # Free-text fingerprints, the last resort: whatsapp-web.js failures reach
+    # us as an opaque 500 whose body is the library's own message, so text is
+    # all there is. Order matters — the first match wins.
+    MESSAGE_CODES = [
+      [/\bno lid\b/i, :recipient_unresolved],
+      [/not registered|not on whatsapp|not a valid whatsapp/i, :not_on_whatsapp],
+      [/invalid wid|wid error|invalid (phone|number)/i, :invalid_phone],
+      [/not authenticated|pair via qr|logged out|session expired|unauthorized/i, :auth_required],
+      [/connection refused|failed to open tcp|network is unreachable|no route to host/i, :service_unreachable],
+      [/execution expired|timed out|timeout/i, :timeout],
+      [/rate limit|too many requests/i, :rate_limited]
+    ].freeze
+
+    # Bound on what a service-supplied code may look like before we pass it
+    # through unrecognized: an identifier, not arbitrary text.
+    CODE_SHAPE = /\A[a-z0-9_]{1,64}\z/
+
+    class << self
+      # Classify the exception a transport raised. ServiceError carries the
+      # HTTP status, which beats guessing from the message.
+      def from_exception(exception)
+        status_code = status_code_for(exception)
+        return status_code if status_code
+
+        EXCEPTION_CODES[exception.class.name] || from_message(exception.message)
+      end
+
+      # Classify a failure the transport reported without raising (a 200 body
+      # with success: false).
+      def from_message(text)
+        haystack = text.to_s
+        MESSAGE_CODES.each { |pattern, code| return code if pattern.match?(haystack) }
+        UNCLASSIFIED
+      end
+
+      # Fold a code the service supplied into the vocabulary. Returns nil for
+      # a blank code so callers can fall back to their own classification;
+      # an unrecognized but identifier-shaped code passes through so a newer
+      # service can introduce one without a gem release.
+      def normalize(value)
+        text = value.to_s.strip.downcase
+        return nil if text.empty?
+
+        SERVICE_CODES[text] || (CODE_SHAPE.match?(text) ? text.to_sym : UNCLASSIFIED)
+      end
+
+      private
+
+      def status_code_for(exception)
+        return nil unless exception.respond_to?(:status)
+
+        STATUS_CODES[exception.status.to_i]
+      end
+    end
+  end
+end

data/lib/whatsapp_notifier/errors.rb

@@ -2,4 +2,25 @@ module WhatsAppNotifier
   class Error < StandardError; end
   class ConfigurationError < Error; end
   class DeliveryError < Error; end
+
+  # Raised when the service answers a non-2xx. Carries the HTTP status so
+  # callers classify on the status instead of re-parsing the message text.
+  #
+  # Subclasses RuntimeError, NOT WhatsAppNotifier::Error: before 0.9.0 this
+  # was a bare `raise "service request failed (...)"`, so hosts wrote
+  # `rescue RuntimeError` around media fetches and status polls. Hanging it
+  # off Error instead would silently stop those rescues from firing and turn
+  # a handled 5xx into an unhandled one.
+  #
+  # The message keeps its pre-0.9.0 wording ("service request failed (401):
+  # ...") for the same reason — hosts that fingerprinted that string keep
+  # matching while they migrate to Result#error_code.
+  class ServiceError < RuntimeError
+    attr_reader :status
+
+    def initialize(message, status: nil)
+      super(message)
+      @status = status
+    end
+  end
 end

data/lib/whatsapp_notifier/providers/base.rb

@@ -19,6 +19,24 @@ module WhatsAppNotifier
         raise NotImplementedError, "#{self.class.name} does not support status checking"
       end
 
+      # True when the paired session can actually send right now. Wraps
+      # #connection_status so hosts stop reimplementing the same
+      # "authenticated == true, rescue transport errors to false" check — a
+      # status endpoint the host cannot reach means sends can't succeed
+      # either, so an unreachable service reads as not-ready.
+      #
+      # ConfigurationError is deliberately NOT swallowed: that is a boot-time
+      # mistake in the host, and answering `false` would quietly park every
+      # send behind a "session down" backoff instead of surfacing it.
+      def session_ready?(metadata: {})
+        status = connection_status(metadata: metadata)
+        status.is_a?(Hash) && status[:authenticated] == true
+      rescue ConfigurationError
+        raise
+      rescue StandardError => e
+        configuration.logger&.warn("[WhatsAppNotifier] session_ready? failed: #{e.message}")
+        false
+      end
     end
   end
 end

data/lib/whatsapp_notifier/providers/web_automation.rb

@@ -17,19 +17,22 @@ module WhatsAppNotifier
         response = adapter.send_message(payload: payload, session: session)
         persist_session(response.fetch(:session, {}), payload.fetch(:metadata, {}))
 
+        success = response.fetch(:success)
         Result.new(
-          success: response.fetch(:success),
+          success: success,
           provider: :web_automation,
           message_id: response[:message_id],
-          error_code: response[:error_code],
+          error_code: error_code_for(success, response),
           error_message: response[:error_message],
           wait_seconds: response[:wait_seconds],
           metadata: response.fetch(:metadata, {})
         )
       rescue StandardError => e
-        Result.new(success: false, provider: :web_automation, error_code: :delivery_exception, error_message: e.message)
+        Result.new(success: false, provider: :web_automation,
+                   error_code: ErrorCode.from_exception(e), error_message: e.message)
       end
 
+
       def scan_qr(metadata: {})
         raise ConfigurationError, "web automation provider is disabled" unless configuration.web_automation_enabled
 
@@ -127,6 +130,14 @@ module WhatsAppNotifier
 
       private
 
+      # A code the adapter supplied wins; otherwise classify from the error
+      # text, which is all a ≤ 0.8.x service gives us. Successes carry no code.
+      def error_code_for(success, response)
+        return nil if success
+
+        response[:error_code] || ErrorCode.from_message(response[:error_message])
+      end
+
       def session_for(metadata)
         user_id = metadata[:user_id]
         return @store.load unless user_id

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

@@ -20,7 +20,14 @@ import {
     type HistoryDeps,
     type RefetchDeps
 } from './history';
-import { configureInbound, loadTargets, resetInboundState, type ChatLike } from './inbound';
+import {
+    configureInbound,
+    loadTargets,
+    resetInboundState,
+    rememberLidAlias,
+    resolveLidAlias,
+    type ChatLike
+} from './inbound';
 import {
     configureMedia,
     resetMediaState,
@@ -231,6 +238,44 @@ test('replayHistory returns oldest-first even when the chat yields newest-first'
     expect(history.map((m) => m.messageId)).toEqual(['m1', 'm2', 'm3']);
 });
 
+// fromMe items in an @lid-keyed chat: the host requested this history by the
+// phone @c.us, and fetchMessages only returns THIS chat's messages — so the
+// requested id IS the @lid's phone. Same prod chat shape as the live-capture
+// bug (125417440686124@lid): without resolution these were unmatchable.
+test('replayHistory resolves fromMe @lid counterparties to the requested chat id and learns the alias', async () => {
+    const LID = '125417440686124@lid';
+    const history = await replayHistory('h1', chatWith([
+        msg({ body: 'customer says hi', timestamp: 1 }),
+        msg({
+            fromMe: true, from: OPERATOR, to: LID, body: 'Yes cool',
+            id: { _serialized: 'op1' }, timestamp: 2
+        })
+    ]), 50, CUST);
+
+    expect(history.length).toBe(2);
+    expect(history[0].from).toBe(CUST);                              // inbound leg untouched
+    expect(history[1]).toMatchObject({ fromMe: true, to: CUST, body: 'Yes cool' });
+    expect(resolveLidAlias('h1', LID)).toBe(CUST); // learned → live fromMe capture resolves too
+});
+
+test('replayHistory falls back to the learned alias map and skips unresolvable fromMe @lid items', async () => {
+    const LID = '125417440686124@lid';
+
+    // No requested chat id (test seam) but a learned alias → resolved.
+    rememberLidAlias('h2', LID, CUST);
+    const withAlias = await replayHistory('h2', chatWith([
+        msg({ fromMe: true, from: OPERATOR, to: LID, id: { _serialized: 'op1' } })
+    ]), 50);
+    expect(withAlias.length).toBe(1);
+    expect(withAlias[0].to).toBe(CUST);
+
+    // Neither → skipped: never forward an unmatchable counterparty.
+    const unresolved = await replayHistory('h3', chatWith([
+        msg({ fromMe: true, from: OPERATOR, to: LID, id: { _serialized: 'op2' } })
+    ]), 50);
+    expect(unresolved).toEqual([]);
+});
+
 test('replayHistory passes the limit through and tolerates a non-array result', async () => {
     let seenLimit = 0;
     await replayHistory('1', chatWith([], ({ limit }) => { seenLimit = limit; }), 37);
@@ -398,6 +443,28 @@ test('historyResponse replays the chat, clamps the limit and allowlists the chat
     expect(data.lastUsed).toBeGreaterThan(0);
 });
 
+// End-to-end shape of the prod incident: the host asks for a phone whose chat
+// is @lid-keyed (getChatById fails → index.ts's contact fallback resolves it),
+// and the replayed fromMe items must come back threaded on that phone.
+test('historyResponse resolves fromMe @lid items in an @lid-keyed chat to the requested phone', async () => {
+    const LID = '125417440686124@lid';
+    const deps = depsWith(readyClient(), {
+        resolveChat: async () => chatWith([
+            msg({ fromMe: true, from: OPERATOR, to: LID, body: 'No still not', id: { _serialized: 'op1' } })
+        ])
+    });
+
+    const res = await historyResponse('h9', { chatId: CUST }, undefined, undefined, deps);
+
+    expect(res.status).toBe(200);
+    const payload = await res.json();
+    expect(payload.messages).toEqual([{
+        from: OPERATOR, to: CUST, fromMe: true, body: 'No still not',
+        messageId: 'op1', timestamp: 1717000000, type: 'chat'
+    }]);
+    expect(resolveLidAlias('h9', LID)).toBe(CUST);
+});
+
 test('historyResponse defaults the limit to 50 when the body omits it', async () => {
     let seenLimit = 0;
     const data = readyClient({

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

@@ -13,7 +13,9 @@ import {
     InboundMediaInfo,
     ChatLike,
     shouldCapture,
-    normalizeInbound
+    normalizeInbound,
+    resolveLidAlias,
+    rememberLidAlias
 } from './inbound';
 import { verifyMediaToken, MediaResolution, sanitizeId } from './media';
 
@@ -96,12 +98,37 @@ export function historyMediaInfo(): InboundMediaInfo {
 // host threads whole conversations. Messages failing shouldCapture (system
 // events, status, group posts) are skipped. Returned oldest-first so the
 // host can ingest in thread order.
-export async function replayHistory(userId: string, chat: ChatLike, limit: number): Promise<InboundMsg[]> {
+//
+// fromMe items in an @lid-keyed chat carry the @lid at `to` — unmatchable
+// host-side, exactly the live-capture bug. requestedChatId is the @c.us id
+// the host asked POST /history for (normalizeHistoryChatId enforces the
+// suffix), and fetchMessages only ever returns THIS chat's messages, so that
+// id IS the @lid's phone: resolve with it and learn the alias — which is also
+// how a restarted service can relearn mappings (and backfill previously
+// dropped operator messages) without waiting for the customer to write.
+// Without it (test seam) the learned map is the fallback; what neither
+// resolves is skipped — the same never-forward-an-unmatchable-counterparty
+// rule as the live fromMe leg.
+export async function replayHistory(
+    userId: string,
+    chat: ChatLike,
+    limit: number,
+    requestedChatId?: string
+): Promise<InboundMsg[]> {
     const msgs = await chat.fetchMessages({ limit });
-    return (Array.isArray(msgs) ? msgs : [])
-        .filter((m) => shouldCapture(userId, m))
-        .map((m) => normalizeInbound(m, m.hasMedia ? historyMediaInfo() : undefined))
-        .sort((a, b) => a.timestamp - b.timestamp);
+    const out: InboundMsg[] = [];
+    for (const m of (Array.isArray(msgs) ? msgs : [])) {
+        if (!shouldCapture(userId, m)) continue;
+        const inbound = normalizeInbound(m, m.hasMedia ? historyMediaInfo() : undefined);
+        if (inbound.fromMe && inbound.to && inbound.to.endsWith('@lid')) {
+            const resolved = requestedChatId || resolveLidAlias(userId, inbound.to);
+            if (!resolved) continue;
+            if (requestedChatId) rememberLidAlias(userId, inbound.to, requestedChatId);
+            inbound.to = resolved;
+        }
+        out.push(inbound);
+    }
+    return out.sort((a, b) => a.timestamp - b.timestamp);
 }
 
 // ── Route responses ──
@@ -193,7 +220,7 @@ export async function historyResponse(
         const chat = await deps.resolveChat(gate.client, chatId);
         if (!chat) return deny(404, 'chat not found');
 
-        const messages = await replayHistory(userId, chat, clampHistoryLimit(body && body.limit));
+        const messages = await replayHistory(userId, chat, clampHistoryLimit(body && body.limit), chatId);
 
         // A synced chat is a conversation of record: allowlist it like a /send
         // recipient so disconnect-window replies to it backfill on reconnect.

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

@@ -10,6 +10,7 @@ import {
     loadTargets,
     rememberTarget,
     rememberLidAlias,
+    resolveLidAlias,
     rememberSelfSend,
     isSelfSend,
     resolveChat,
@@ -158,13 +159,17 @@ test('rememberLidAlias stores the @lid chat id for a known target', () => {
     expect(loadTargets('la1').has(CUST)).toBe(true);
 });
 
-test('rememberLidAlias ignores unknown senders and non-@lid raw ids', () => {
+test('rememberLidAlias keeps unknown senders off the allowlist and skips non-@lid raw ids', () => {
     rememberTarget('la2', CUST);
 
     rememberLidAlias('la2', '999@lid', '918888000000@c.us'); // resolved not a target
     rememberLidAlias('la2', CUST, CUST);                     // raw is already @c.us
 
     expect(loadTargets('la2')).toEqual(new Set([CUST]));
+    // The mapping itself IS learned for the unknown sender (the fromMe leg
+    // needs it regardless of the allowlist), but never for a non-@lid raw id.
+    expect(resolveLidAlias('la2', '999@lid')).toBe('918888000000@c.us');
+    expect(resolveLidAlias('la2', CUST)).toBeUndefined();
 });
 
 // backfill resolves chats directly, then via contact, and skips dead targets
@@ -414,11 +419,11 @@ test('processInbound resolves media for operator-sent media messages', async ()
     expect(drained[0].mediaSize).toBe(10);
 });
 
-// An @lid counterparty on fromMe has no phone the host can thread on and no
-// contact handle to resolve it through (getContact resolves the sender — the
-// operator). Dropped with a log, before any download — same disk-hygiene rule
-// as the inbound @lid drop.
-test('processInbound drops a fromMe message to an @lid chat before any download', async () => {
+// An @lid counterparty on fromMe that resolves through NEITHER the learned
+// alias map NOR the live contact lookup (here: a message with no client
+// handle at all) stays dropped with a log, before any download — same
+// disk-hygiene rule as the inbound @lid drop.
+test('processInbound drops a fromMe message to an unresolvable @lid chat before any download', async () => {
     let resolveCalls = 0;
     const m = mediaMsg({ fromMe: true, from: OPERATOR, to: LID_FROM });
 
@@ -431,6 +436,115 @@ test('processInbound drops a fromMe message to an @lid chat before any download'
     expect(loadTargets('fm4').size).toBe(0); // an unmatchable chat earns no allowlist slot
 });
 
+// ── fromMe @lid resolution (the two-way rollout blocker) ──
+//
+// Prod evidence 2026-07-10, chat 125417440686124@lid: customer messages in
+// the chat resolved to the phone and flowed, while EVERY operator-phone
+// message hit the unconditional drop. Resolution order: learned alias map →
+// one live getContactById(<@lid>) lookup (the same call the inbound leg is
+// proven on) → logged drop.
+
+test('processInbound resolves a fromMe @lid counterparty from the learned alias map', async () => {
+    // The customer wrote earlier — the inbound leg learned the alias.
+    rememberLidAlias('fl1', LID_FROM, CUST);
+
+    let contactLookups = 0;
+    const m = msg({
+        fromMe: true, from: OPERATOR, to: LID_FROM, body: 'Yes cool',
+        client: { getContactById: async () => { contactLookups += 1; return { number: '919999000001' }; } }
+    });
+
+    const pushed: InboundMsg[] = [];
+    await processInbound('fl1', m, {
+        resolveMedia: async () => ({ mediaStatus: 'available' as const }),
+        push: (_u, inbound) => pushed.push(inbound)
+    });
+
+    const drained = drainInbound('fl1');
+    expect(drained.length).toBe(1);
+    expect(drained[0].fromMe).toBe(true);
+    expect(drained[0].to).toBe(CUST);                    // resolved phone, not the @lid
+    expect(drained[0].body).toBe('Yes cool');
+    expect(pushed).toEqual(drained);                     // webhook saw the same payload
+    expect(contactLookups).toBe(0);                      // map hit → no puppeteer roundtrip
+    expect(loadTargets('fl1').has(CUST)).toBe(true);     // allowlisted like any fromMe counterparty
+    expect(loadTargets('fl1').has(LID_FROM)).toBe(true); // the chat's REAL key joins the allowlist too
+});
+
+test('processInbound live-resolves a fromMe @lid chat and learns the alias for next time', async () => {
+    const seenIds: string[] = [];
+    const m = msg({
+        fromMe: true, from: OPERATOR, to: LID_FROM, body: 'No still not',
+        client: { getContactById: async (id: string) => { seenIds.push(id); return { number: '919999000001' }; } }
+    });
+
+    await processInbound('fl2', m, { resolveMedia: async () => ({ mediaStatus: 'available' as const }) });
+
+    const drained = drainInbound('fl2');
+    expect(drained.length).toBe(1);
+    expect(drained[0].to).toBe(CUST);
+    expect(seenIds).toEqual([LID_FROM]);                   // the inbound leg's exact lookup, by the @lid
+    expect(resolveLidAlias('fl2', LID_FROM)).toBe(CUST);   // learned → the next message is a map hit
+});
+
+test('live resolution trusts contact.id.user only when the contact id is phone-keyed', async () => {
+    // No `number`, but a @c.us-keyed contact id carries the phone at id.user.
+    const good = msg({
+        fromMe: true, from: OPERATOR, to: LID_FROM,
+        client: { getContactById: async () => ({ id: { user: '919999000001', _serialized: CUST } }) }
+    });
+    await processInbound('fl3', good, { resolveMedia: async () => ({ mediaStatus: 'available' as const }) });
+    expect(drainInbound('fl3')[0].to).toBe(CUST);
+
+    // An @lid-keyed contact id must NOT mint a bogus "phone" out of the
+    // privacy id's own digits — that message is unresolvable and dropped.
+    const bogus = msg({
+        fromMe: true, from: OPERATOR, to: LID_FROM, id: { _serialized: 'b1' },
+        client: { getContactById: async () => ({ id: { user: '125417440686124', _serialized: LID_FROM } }) }
+    });
+    await processInbound('fl4', bogus, { resolveMedia: async () => ({ mediaStatus: 'available' as const }) });
+    expect(drainInbound('fl4')).toEqual([]);
+    expect(resolveLidAlias('fl4', LID_FROM)).toBeUndefined();
+});
+
+test('processInbound still drops a fromMe @lid message when the live lookup throws', async () => {
+    let resolveCalls = 0;
+    const m = mediaMsg({
+        fromMe: true, from: OPERATOR, to: LID_FROM,
+        client: { getContactById: async () => { throw new Error('contact store not hydrated'); } }
+    });
+
+    await processInbound('fl5', m, {
+        resolveMedia: async () => { resolveCalls += 1; return { mediaStatus: 'available' as const }; }
+    });
+
+    expect(resolveCalls).toBe(0);                // dropped BEFORE any download
+    expect(drainInbound('fl5')).toEqual([]);
+    expect(loadTargets('fl5').size).toBe(0);
+});
+
+test('rememberLidAlias persists the @lid → phone mapping across a restart', () => {
+    rememberLidAlias('al1', LID_FROM, CUST);
+    expect(resolveLidAlias('al1', LID_FROM)).toBe(CUST);
+
+    const file = join(dirFor('al1'), 'lid_aliases.json');
+    expect(existsSync(file)).toBe(true);
+    expect(JSON.parse(readFileSync(file, 'utf8'))).toEqual({ [LID_FROM]: CUST });
+
+    resetInboundState(); // the restart: drop in-memory cache → must reload from disk
+    configureInbound(dirFor);
+    expect(resolveLidAlias('al1', LID_FROM)).toBe(CUST);
+});
+
+test('clearInbound drops the cached alias map so a re-pair cannot inherit old mappings', () => {
+    rememberLidAlias('al2', LID_FROM, CUST);
+    // Logout wipes the session dir (incl. lid_aliases.json) from disk...
+    rmSync(dirFor('al2'), { recursive: true, force: true });
+    // ...but without clearInbound the in-memory cache would still resolve.
+    clearInbound('al2');
+    expect(resolveLidAlias('al2', LID_FROM)).toBeUndefined();
+});
+
 // ── Self-send echo suppression ──
 //
 // Every /send fires its own fromMe message_create echo. A registry hit must