wazap-mcp 0.9.2 → 0.9.5

package/README.md

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 22 tools any MCP client can
+chats, messages, media, contacts, groups — behind 23 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -101,13 +101,14 @@ The `skills/` folder follows the [Agent Skills](https://agentskills.io) format,
 | Tool | Kind | What it does |
 | --- | --- | --- |
 | `learn` | read | The guide to every tool, id format and error code. Call it first. |
-| `get_status` | read | Connection status, sync state, linked account, versions, data dir. |
+| `get_status` | read | Connection status, sync state, linked account, named-contact count, versions, data dir. |
 | `list_chats` | read | Conversations newest-first; filter `all`/`unread`/`groups`/`individual`/`archived`. |
 | `read_messages` | read | Messages in a chat; `before` pages further back, pulling older history from the phone. |
-| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. |
+| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. `include_system` adds WhatsApp's own notices. |
 | `search_messages` | read | Text search across the locally held messages. |
 | `get_message` | read | One message in full, with its quoted message and reactions. |
 | `search_contacts` | read | Find contacts by name or number. |
+| `sync_contacts` | read | Fetch the phone's address book from WhatsApp again, when names are missing. |
 | `get_contact` | read | Name, number, about text, profile picture. |
 | `get_group_info` | read | Participants, admins, announcement mode, invite link (when you are admin). |
 | `download_media` | read | Save an attachment to disk; small images also come back inline. |
@@ -186,14 +187,32 @@ created `0700` with credentials written `0600`:
   history/      per-chat message history, so a restart is not amnesia
   store.json    chat-list snapshot
   server.lock   pid of the running server
+  daemon.json   loopback endpoint a second wazap bridges to
   .env          optional settings, see .env.example
 ```
 
 Credential writes go to a temp file and are renamed into place, so killing the
 process mid-write cannot leave you re-linking your phone.
 
-One server per data directory: a second `wazap serve` on the same directory
-exits with code 2 and tells you the pid of the one already running.
+## Several clients at once
+
+Claude Desktop, Claude Code and Cursor each launch their own `wazap`. WhatsApp
+allows one socket per linked device, so they share one session instead of
+fighting over it. The first `wazap` on a data directory owns the session and
+opens an MCP endpoint on `127.0.0.1`; every later one bridges to it over that
+endpoint. There is nothing to configure, and no client can tell the difference.
+The owner publishes `<data-dir>/daemon.json` (`0600`) with its pid, its port
+and the token a bridge authenticates with.
+
+A bridge serves whatever the owner exposes, so an owner started `--read-only`
+makes every client read-only, whatever flags that client was launched with.
+
+When the owner exits, the bridges exit with it, and the next `wazap` a client
+starts becomes the new owner.
+
+`WAZAP_NO_SHARE=1` opts out: a second `wazap` on the same directory exits with
+code 2 naming the pid of the one already running. An explicit `--http` is a
+server of its own rather than a bridge, and is refused the same way.
 
 ## Read-only mode
 
@@ -289,6 +308,10 @@ Flags beat environment variables, which beat `<data-dir>/.env`.
 - **`@lid` ids.** Newer accounts are addressed by a privacy id rather than a
   phone number. wazap translates them back to phone numbers when it has learned
   the mapping, and passes the `@lid` through when it has not.
+- **Names come from the phone's address book.** WhatsApp delivers it as an app
+  state sync, and only to a connection asking for it from scratch. If contacts
+  read as phone numbers and `get_status` shows `contacts_named: 0`, ask for it
+  again with the `sync_contacts` tool or `wazap contacts resync`.
 - **Your phone must stay reachable.** A linked device stops receiving once the
   phone has been offline long enough; `get_status` says so in `hint`.
 

package/dist/auth-state.js

@@ -117,3 +117,28 @@ export function readLinkedAccount(dir) {
 export function clearAuth(dir) {
     rmSync(dir, { recursive: true, force: true });
 }
+const APP_STATE_SYNC_VERSION = "app-state-sync-version";
+/**
+ * The same auth state with the app state sync journal held at zero: reads of it
+ * find nothing and writes to it are dropped, every other key type untouched.
+ *
+ * WhatsApp delivers the phone's address book to a companion as `contactAction`
+ * mutations in the app state sync, once per stored collection version. Whichever
+ * socket saves those versions consumes that one delivery; every later connection
+ * resyncs from the version it left behind and receives nothing. The login socket
+ * has no store to put contacts in, so it must leave the journal for the service
+ * that follows.
+ */
+export function withoutAppStateSync(state) {
+    return {
+        creds: state.creds,
+        keys: {
+            get: async (type, ids) => type === APP_STATE_SYNC_VERSION ? {} : state.keys.get(type, ids),
+            set: async (data) => {
+                const rest = { ...data };
+                delete rest[APP_STATE_SYNC_VERSION];
+                await state.keys.set(rest);
+            },
+        },
+    };
+}

package/dist/bridge.js

@@ -0,0 +1,64 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, CallToolResultSchema, ListToolsRequestSchema, ListToolsResultSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { WAZAP_VERSION } from "./config.js";
+import { readDaemon } from "./daemon.js";
+import { log } from "./logger.js";
+const HEARTBEAT_MS = 1_000;
+/**
+ * Serve this client from the session another process already owns: an MCP server
+ * on our stdio, every tool call forwarded to the daemon's loopback endpoint and
+ * its answer returned untouched.
+ *
+ * `daemonFile` is here because the heartbeat re-reads the sidecar, and DaemonInfo
+ * carries no path.
+ */
+export async function runBridge(daemon, daemonFile) {
+    let left = false;
+    /** Exit 1 so the client restarts us, and the restart becomes the new daemon. */
+    const leave = (reason) => {
+        if (left)
+            return;
+        left = true;
+        log(`${reason}, exiting so the next start can own the session`);
+        process.exit(1);
+    };
+    const client = new Client({ name: "wazap-bridge", version: WAZAP_VERSION });
+    await client.connect(new StreamableHTTPClientTransport(new URL(`http://127.0.0.1:${daemon.port}/mcp`), {
+        requestInit: { headers: { Authorization: `Bearer ${daemon.token}` } },
+    }));
+    const caps = client.getServerCapabilities() ?? {};
+    const server = new Server(client.getServerVersion() ?? { name: "wazap", version: daemon.version }, {
+        // Only what we forward: the daemon has no resources or prompts, and we have
+        // no handler for them.
+        capabilities: { tools: caps.tools ?? {} },
+        instructions: client.getInstructions(),
+    });
+    server.setRequestHandler(ListToolsRequestSchema, (req) => client.request({ method: "tools/list", params: req.params }, ListToolsResultSchema));
+    server.setRequestHandler(CallToolRequestSchema, (req) => client.request({ method: "tools/call", params: req.params }, CallToolResultSchema));
+    client.onclose = () => leave(`the session holder (pid ${daemon.pid}) closed the connection`);
+    client.onerror = () => leave(`lost the connection to the session holder (pid ${daemon.pid})`);
+    // A dead daemon does not close the client: the transport retries its stream and
+    // reports nothing, measured. So the liveness of the pid is ours to watch.
+    const heartbeat = setInterval(() => {
+        if (readDaemon(daemonFile)?.pid !== daemon.pid) {
+            leave(`the session holder (pid ${daemon.pid}) gave up the session`);
+            return;
+        }
+        try {
+            process.kill(daemon.pid, 0);
+        }
+        catch {
+            leave(`the session holder (pid ${daemon.pid}) is gone`);
+        }
+    }, HEARTBEAT_MS);
+    heartbeat.unref();
+    await server.connect(new StdioServerTransport());
+    log(`sharing the WhatsApp session held by pid ${daemon.pid}`);
+    // Our own client leaving is not a failure. The upstream stream holds the event
+    // loop open, so without this the bridge outlives the client it was started for.
+    process.stdin.on("end", () => process.exit(0));
+    process.stdin.on("close", () => process.exit(0));
+}

package/dist/cli.js

@@ -1,22 +1,26 @@
+import { randomBytes } from "node:crypto";
 import { mkdirSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { setTimeout as sleep } from "node:timers/promises";
 import makeWASocket, { DisconnectReason, } from "baileys";
 import qrcode from "qrcode";
 import qrcodeTerminal from "qrcode-terminal";
-import { clearAuth, readLinkedAccount, useAtomicAuthState } from "./auth-state.js";
+import { clearAuth, readLinkedAccount, useAtomicAuthState, withoutAppStateSync, } from "./auth-state.js";
 import { banner } from "./banner.js";
+import { runBridge } from "./bridge.js";
 import { BAILEYS_VERSION, WAZAP_VERSION, paths } from "./config.js";
 import { connectNext } from "./connect.js";
+import { decideRole, readDaemon, removeDaemon, writeDaemon } from "./daemon.js";
 import { checkLine, checkLines, runChecks } from "./doctor.js";
 import { RELINK_FIX, WazapError, asWazapError } from "./errors.js";
 import { normalizePhone } from "./ids.js";
 import { lockHolder, releaseLock, writeLock } from "./lock.js";
 import { log, logError, say } from "./logger.js";
 import { formatAge } from "./messages.js";
-import { runHttp, runStdio } from "./server.js";
+import { RateLimiter } from "./ratelimit.js";
+import { runHttp, runStdio, startLoopbackEndpoint } from "./server.js";
 import { applyWrites } from "./settings.js";
-import { bold, box, brand, humanLayout, dim, fail, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
+import { bold, box, brand, humanLayout, dim, fail, fix, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
 import { WA_BROWSER, WhatsAppService } from "./whatsapp.js";
 const LOGIN_TIMEOUT_MS = 120_000;
 const LIVE_TIMEOUT_MS = 15_000;
@@ -30,6 +34,8 @@ const SETTLED_STATUSES = [
 ];
 const LOGOUT_TIMEOUT_MS = 10_000;
 const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "localhost"];
+/** Bind addresses a loopback bridge can still reach; the wildcards include 127.0.0.1. */
+const SHAREABLE_HOSTS = [...LOOPBACK_HOSTS, "0.0.0.0", "::"];
 const SILENT_LOGGER = {
     level: "silent",
     child: () => SILENT_LOGGER,
@@ -49,6 +55,11 @@ export async function runStatus(config) {
     catch {
         unreadable = true;
     }
+    // A sidecar outliving the process that wrote it is stale, so only the lock
+    // holder's own record counts as a session being shared.
+    const serverPid = lockHolder(p.lockFile);
+    const daemon = readDaemon(p.daemonFile);
+    const sharing = daemon !== null && daemon.pid === serverPid ? { pid: daemon.pid, port: daemon.port } : null;
     const report = {
         data_dir: config.dataDir,
         linked: account !== null,
@@ -56,7 +67,8 @@ export async function runStatus(config) {
         account,
         wazap_version: WAZAP_VERSION,
         baileys_version: BAILEYS_VERSION,
-        server_pid: lockHolder(p.lockFile),
+        server_pid: serverPid,
+        daemon: sharing,
         checks: await runChecks(config),
     };
     if (config.live)
@@ -89,9 +101,16 @@ function plainStatus(report) {
     else {
         lines.push("linked: no");
     }
-    lines.push(`wazap: ${report.wazap_version}`, `baileys: ${report.baileys_version}`, report.server_pid === null ? "server: not running" : `server: running (pid ${report.server_pid})`, "", "checks:", ...report.checks.map(checkLine));
+    lines.push(`wazap: ${report.wazap_version}`, `baileys: ${report.baileys_version}`, `server: ${serverState(report)}`, "", "checks:", ...report.checks.map(checkLine));
     return lines;
 }
+/** The one place the sidecar becomes words, so the two renderers cannot drift. */
+function serverState(report) {
+    if (report.server_pid === null)
+        return "not running";
+    const shared = report.daemon === null ? "" : `, sharing on 127.0.0.1:${report.daemon.port}`;
+    return `running (pid ${report.server_pid}${shared})`;
+}
 const LABEL_WIDTH = 8;
 function row(label, value) {
     return `${dim(label.padEnd(LABEL_WIDTH))}  ${value}`;
@@ -106,7 +125,7 @@ function richStatus(report) {
         `${bold(`wazap ${report.wazap_version}`)}${dim(` · baileys ${report.baileys_version}`)}`,
         row("data dir", tilde(report.data_dir)),
         row("account", account),
-        row("server", report.server_pid === null ? "not running" : `running (pid ${report.server_pid})`),
+        row("server", serverState(report)),
         "",
         ...report.checks.flatMap(checkLines),
     ];
@@ -120,15 +139,29 @@ function liveLines(live) {
         `live: last message ${live.last_message_age ?? "unknown"}`,
     ];
 }
+/**
+ * Hold the session for a one-shot command: null once the lock is ours, otherwise
+ * the pid that owns it. The claim only fails while the file exists, so a lost
+ * race is looked up again rather than reported as a missing pid.
+ */
+function takeSessionLock(lockFile) {
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const running = lockHolder(lockFile);
+        if (running !== null)
+            return running;
+        if (writeLock(lockFile))
+            return null;
+    }
+    throw new WazapError("WHATSAPP_ERROR", `Could not take the session lock in ${lockFile}.`, "Run the command again");
+}
 /** One process owns the session, so a probe only runs when no server holds the lock. */
 async function runLiveProbe(config) {
     const p = paths(config.dataDir);
-    const running = lockHolder(p.lockFile);
+    // The probe owns the session for as long as it runs, exactly like the server.
+    const running = takeSessionLock(p.lockFile);
     if (running !== null) {
-        throw new WazapError("WHATSAPP_ERROR", `A server (pid ${running}) already owns this session.`, "Ask it through your MCP client instead: call get_status");
+        throw new WazapError("WHATSAPP_ERROR", `A server (pid ${running}) already owns this session.`, "use get_status through your client, or wazap status");
     }
-    // The probe owns the session for as long as it runs, exactly like the server.
-    writeLock(p.lockFile);
     const wa = new WhatsAppService(config);
     const deadline = Date.now() + LIVE_TIMEOUT_MS;
     try {
@@ -161,6 +194,53 @@ async function runLiveProbe(config) {
         releaseLock(p.lockFile);
     }
 }
+/**
+ * `wazap contacts resync`. One process owns the session, so this refuses while a
+ * server holds it rather than fighting for the socket: that server has the
+ * sync_contacts tool, which does the same thing.
+ */
+export async function runContacts(config) {
+    if (config.args[0] !== "resync") {
+        say(fail(`Unknown contacts command "${config.args[0]}".`));
+        say(fix("Run `wazap contacts resync`"));
+        process.exit(2);
+    }
+    const p = paths(config.dataDir);
+    const running = takeSessionLock(p.lockFile);
+    if (running !== null) {
+        say(fail(`wazap is running (pid ${running}).`));
+        say(fix("ask your agent for the sync_contacts tool, or stop the server and run this again"));
+        process.exit(1);
+    }
+    const wa = new WhatsAppService(config);
+    const spin = spinner("Asking WhatsApp for your address book…");
+    try {
+        await wa.start();
+        const deadline = Date.now() + LIVE_TIMEOUT_MS;
+        let probe = wa.getStatus();
+        while (!SETTLED_STATUSES.includes(probe.status) && Date.now() < deadline) {
+            await sleep(250);
+            probe = wa.getStatus();
+        }
+        const result = await wa.syncContacts();
+        spin.stop(result.named_after > result.named_before
+            ? ok(`${result.named_after} contacts have a name (was ${result.named_before})`)
+            : result.named_after > 0
+                ? ok(`Already up to date: ${result.named_after} contacts have a name`)
+                : warn("WhatsApp sent no names at all. The phone has no saved contacts for these people."));
+    }
+    catch (err) {
+        const failure = asWazapError(err);
+        spin.stop(fail(failure.message));
+        if (failure.fix)
+            say(fix(failure.fix));
+        process.exitCode = 1;
+    }
+    finally {
+        await wa.stop();
+        releaseLock(p.lockFile);
+    }
+}
 /** Bare `wazap` at a terminal: where you stand, and the one command to run next. */
 export async function runGreet(config) {
     say(banner());
@@ -181,22 +261,45 @@ export async function runGreet(config) {
 }
 export async function runServe(config) {
     const p = paths(config.dataDir);
-    const running = lockHolder(p.lockFile);
-    if (running !== null) {
-        say(fail(`wazap is already running (pid ${running}) using ${config.dataDir}. Stop it first or use --data-dir.`));
-        process.exit(2);
+    // Losing the atomic claim means another `serve` won it, and the next pass finds
+    // its sidecar and becomes a bridge onto it.
+    let claimed = false;
+    for (let attempt = 0; attempt < 5; attempt++) {
+        const role = await decideRole(config, p);
+        if (role.kind === "refuse") {
+            say(fail(role.message));
+            process.exit(2);
+        }
+        if (role.kind === "bridge") {
+            await runBridge(role.daemon, p.daemonFile);
+            return;
+        }
+        // Loopback with no token only gets runHttp's warning; off-loopback is refused.
+        if (config.transport === "http" && !config.readToken && !LOOPBACK_HOSTS.includes(config.httpHost)) {
+            say(fail(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`));
+            process.exit(1);
+        }
+        mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
+        if (writeLock(p.lockFile)) {
+            claimed = true;
+            break;
+        }
     }
-    // Loopback with no token only gets runHttp's warning; off-loopback is refused.
-    if (config.transport === "http" && !config.readToken && !LOOPBACK_HOSTS.includes(config.httpHost)) {
-        say(fail(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`));
-        process.exit(1);
+    if (!claimed) {
+        say(fail(`Another wazap keeps taking ${config.dataDir} as this one starts. Run it again.`));
+        process.exit(2);
     }
-    mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
-    writeLock(p.lockFile);
-    process.on("exit", () => releaseLock(p.lockFile));
+    process.on("exit", () => {
+        removeDaemon(p.daemonFile);
+        releaseLock(p.lockFile);
+    });
     const wa = new WhatsAppService(config);
-    const shutdown = (signal) => {
-        log(`received ${signal}, shutting down`);
+    let stopping = false;
+    const shutdown = (reason) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log(`received ${reason}, shutting down`);
         // A wedged socket must not cost the user a kill -9; the lock goes on "exit".
         setTimeout(() => process.exit(0), 3_000).unref();
         void wa.stop().finally(() => process.exit(0));
@@ -206,10 +309,31 @@ export async function runServe(config) {
     // Connecting in the background: MCP startup never waits on WhatsApp, and the
     // tools answer NOT_LINKED until a session exists.
     wa.start().catch((err) => logError("whatsapp start", err));
-    if (config.transport === "http")
-        await runHttp(wa, config);
-    else
-        await runStdio(wa, config);
+    const token = config.share ? randomBytes(32).toString("hex") : null;
+    // One bucket for the process, not per endpoint: a bridge writing through the
+    // loopback endpoint spends from the same allowance as the daemon's own client.
+    const limiter = new RateLimiter(config.rateLimitPerMinute);
+    if (config.transport === "http") {
+        const port = await runHttp(wa, config, limiter, token === null ? undefined : { token, write: true });
+        // Off-loopback binds get no sidecar: a bridge on this machine could not reach them.
+        if (token !== null && SHAREABLE_HOSTS.includes(config.httpHost)) {
+            writeDaemon(p.daemonFile, { pid: process.pid, port, token, version: WAZAP_VERSION });
+        }
+        return;
+    }
+    if (token !== null) {
+        const port = await startLoopbackEndpoint(wa, config, token, limiter);
+        writeDaemon(p.daemonFile, { pid: process.pid, port, token, version: WAZAP_VERSION });
+    }
+    await runStdio(wa, config, limiter);
+    if (token === null)
+        return;
+    // The loopback endpoint keeps the event loop alive, so stdin EOF no longer ends
+    // the process on its own. When the daemon's own client goes away the daemon goes
+    // with it, rather than lingering for bridges. Registered after runStdio, so the
+    // transport is already reading and "end" fires.
+    process.stdin.on("end", () => shutdown("stdin end"));
+    process.stdin.on("close", () => shutdown("stdin close"));
 }
 export function stepper(total) {
     let n = 0;
@@ -239,13 +363,11 @@ export async function runLogin(config) {
  */
 export async function linkAndSync(config, announce = () => { }) {
     const p = paths(config.dataDir);
-    const running = lockHolder(p.lockFile);
+    const running = takeSessionLock(p.lockFile);
     if (running !== null) {
         say(fail(`wazap is running (pid ${running}). Stop it first (or quit the client that launched it), then run this again.`));
         process.exit(1);
     }
-    mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
-    writeLock(p.lockFile);
     const release = () => releaseLock(p.lockFile);
     const onInterrupt = () => {
         release();
@@ -505,10 +627,16 @@ async function linkSession(authDir, opts) {
             if (expired)
                 throw timedOut();
             const { state, saveCreds } = await useAtomicAuthState(authDir);
+            // This socket pairs and nothing else. It has no store, so anything it
+            // syncs is thrown away — and WhatsApp sends the history and the address
+            // book once. Refusing the history keeps it out of Baileys' sync state
+            // machine, which is what would otherwise bump `accountSyncCounter` and
+            // leave the service permanently past its own first sync.
             const sock = makeWASocket({
-                auth: state,
+                auth: withoutAppStateSync(state),
                 browser: WA_BROWSER,
                 markOnlineOnConnect: false,
+                shouldSyncHistoryMessage: () => false,
                 logger: SILENT_LOGGER,
             });
             current = sock;

package/dist/config.js

@@ -15,6 +15,7 @@ export function paths(dataDir) {
         historyDir: join(dataDir, "history"),
         storeFile: join(dataDir, "store.json"),
         lockFile: join(dataDir, "server.lock"),
+        daemonFile: join(dataDir, "daemon.json"),
         envFile: join(dataDir, ".env"),
         qrFile: join(dataDir, "qr.png"),
     };
@@ -28,6 +29,7 @@ const COMMAND_ARGS = {
     logout: [0],
     connect: [1],
     config: [0, 2],
+    contacts: [1],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -119,6 +121,7 @@ export function parseCli(argv = process.argv.slice(2)) {
             httpPort: values.port ? asInt(values.port, 8766) : asInt(process.env.WAZAP_PORT, 8766),
             readToken: (process.env.WAZAP_READ_TOKEN ?? "").trim() || null,
             writeToken: (process.env.WAZAP_WRITE_TOKEN ?? "").trim() || null,
+            share: !asBool(process.env.WAZAP_NO_SHARE, false),
             rateLimitPerMinute: asInt(process.env.WAZAP_RATE_LIMIT, 20),
             sources: {
                 // Resolved before dotenv runs, so the data dir's own .env cannot name it.

package/dist/daemon.js

@@ -0,0 +1,101 @@
+import { chmodSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { lockHolder } from "./lock.js";
+function isPositiveInt(value) {
+    return typeof value === "number" && Number.isInteger(value) && value > 0;
+}
+/** The sidecar another process left behind, or null if it is missing, corrupt or the wrong shape. */
+export function readDaemon(file) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null)
+        return null;
+    const { pid, port, token, version } = parsed;
+    if (!isPositiveInt(pid) || !isPositiveInt(port))
+        return null;
+    if (typeof token !== "string" || token === "")
+        return null;
+    if (typeof version !== "string" || version === "")
+        return null;
+    return { pid, port, token, version };
+}
+export function writeDaemon(file, info) {
+    mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
+    // Written aside and renamed in: a bridge polling for the sidecar reads either
+    // the old record or the new one, never half a token. The mode argument only
+    // applies when a file is created, so the chmod covers a leftover temp file
+    // from an earlier run keeping looser permissions.
+    const temp = `${file}.${process.pid}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(info, null, 2)}\n`, { mode: 0o600 });
+    chmodSync(temp, 0o600);
+    renameSync(temp, file);
+}
+/** Remove the sidecar, but only if it is still ours. */
+export function removeDaemon(file) {
+    try {
+        if (readDaemon(file)?.pid !== process.pid)
+            return;
+        unlinkSync(file);
+    }
+    catch {
+        /* already gone */
+    }
+}
+/** Liveness of the loopback endpoint recorded in a sidecar. Never throws. */
+export async function daemonHealthy(port, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: controller.signal });
+        if (!res.ok)
+            return false;
+        const body = await res.json();
+        return typeof body === "object" && body !== null && body.ok === true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+const ROLE_TIMEOUT_MS = 3_000;
+const ROLE_POLL_MS = 100;
+/**
+ * Who we are for this data dir: the process that owns the session, a bridge onto
+ * the one that already does, or neither. The lock is re-read every pass because
+ * the winner of a simultaneous start needs a moment to bind its port and publish
+ * the sidecar, and because a winner that crashes frees the lock mid-loop.
+ */
+export async function decideRole(config, p) {
+    const deadline = Date.now() + ROLE_TIMEOUT_MS;
+    for (;;) {
+        const running = lockHolder(p.lockFile);
+        if (running === null)
+            return { kind: "daemon" };
+        // An explicit --http asks for an HTTP server of its own, not a stdio bridge.
+        if (config.share === false || config.transport === "http") {
+            return {
+                kind: "refuse",
+                message: `wazap is already running (pid ${running}) using ${config.dataDir}. Stop it first or use --data-dir.`,
+            };
+        }
+        const info = readDaemon(p.daemonFile);
+        if (info !== null && info.pid === running && (await daemonHealthy(info.port, 2_000))) {
+            return { kind: "bridge", daemon: info };
+        }
+        if (Date.now() >= deadline) {
+            return {
+                kind: "refuse",
+                message: `wazap is running (pid ${running}) but is not sharing its session (older version?). Stop it and start again.`,
+            };
+        }
+        await sleep(ROLE_POLL_MS);
+    }
+}

package/dist/ids.js

@@ -11,6 +11,27 @@ export function normalizePhone(input) {
 export function isGroupId(jid) {
     return jid.endsWith("@g.us");
 }
+/**
+ * Jids that address nobody: the status feed, the `0@s.whatsapp.net` pseudo-chat
+ * WhatsApp files its own notices under, and anything malformed. They must never
+ * reach a chat list, a digest or the store.
+ *
+ * Stated as what to refuse rather than what to keep, so a jid kind wazap has
+ * not met yet — a broadcast list, a channel — still reaches the user instead of
+ * being silently swallowed, and a stored one is never purged.
+ */
+export function isNoiseJid(jid) {
+    const at = jid.lastIndexOf("@");
+    if (at === -1)
+        return true;
+    const user = jid.slice(0, at);
+    const domain = jid.slice(at + 1).toLowerCase();
+    if (domain === "broadcast")
+        return user.toLowerCase() === "status";
+    if (domain === "s.whatsapp.net" || domain === "c.us")
+        return /^0+$/.test(user) || !/^\d+$/.test(user);
+    return user === "";
+}
 /**
  * Canonicalize anything a caller may pass as a chat id.
  * Individuals become `<digits>@s.whatsapp.net`, groups stay `<id>@g.us`.

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { BANNER } from "./banner.js";
-import { runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
+import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
 import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
 import { CLIENT_NAMES, runConnect } from "./connect.js";
 import { runSetup } from "./setup.js";
@@ -16,6 +16,7 @@ Usage:
   wazap setup [--agent] [--client <name>]                  Link, connect your client and finish, in one command
   wazap connect <client> [--dry-run]                       Register wazap with an MCP client
   wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
+  wazap contacts resync                                    Fetch the phone's address book from WhatsApp again
   wazap status [--live] [--json]                           Check the install, the session and the server
   wazap logout                                             Unlink and delete local credentials
 
@@ -42,7 +43,7 @@ Options:
 
 Environment: WAZAP_DATA_DIR, WAZAP_READ_ONLY, WAZAP_SYNC_FULL_HISTORY, WAZAP_PERSIST_HISTORY,
 WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_RATE_LIMIT,
-WAZAP_NO_UPDATE_CHECK.
+WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK.
 An optional <data-dir>/.env is loaded if present.`;
 async function main() {
     const invocation = parseCli();
@@ -75,6 +76,9 @@ async function main() {
         case "config":
             runConfig(config);
             return;
+        case "contacts":
+            await runContacts(config);
+            return;
         case "status":
             await runStatus(config);
             return;