@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/dist/daemon/main.js

@@ -0,0 +1,802 @@
+// pi-mailbridge daemon — process entry.
+//
+// Boot order matters:
+//   1. load config, surface warnings
+//   2. resolve the shared secret (also the HTTP bearer token)
+//   3. start the HTTP service (so /health answers while IMAP is still dialling)
+//   4. catch-up scan, then the IDLE watcher
+//
+// Single-instance: a lock file in the state directory, not the port. The port is still checked
+// (EADDRINUSE exits 0), but two processes that disagree about `daemon.port` - a per-process
+// PI_MAILBRIDGE_PORT, or the config edited while one is running - would otherwise start two
+// daemons, two IMAP watchers, on one state directory whose stores have no cross-process lock.
+//
+// Modes:
+//   (none)          run the daemon
+//   --check         validate config + secrets + token command, touch no mail
+//   --setup         write a config from an address (headless equivalent of /mailbridge setup)
+//   --auth          run the OAuth device-code flow
+//   --prime         move the UID cursor to the newest message
+//   --smoke         send one real mail, then open the folder and count
+//   --print-token   print the shared secret (for scripts and tests)
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { statePath } from "../store/paths.js";
+import { assertStateReadable } from "../store/schema.js";
+import { dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { loadConfig, hasUsableMailConfig, shortHostname, REPAIRED_PREFIX, } from "../core/config.js";
+import { configPath } from "../store/paths.js";
+import { buildSetupConfig, discoverDomain, domainOf } from "../core/discover.js";
+import { ensureSecret } from "../store/secret.js";
+import { readMode, scanningEnabled } from "../store/mode-store.js";
+import { createScanQueue } from "./scan-queue.js";
+import { sendMail } from "../core/mailer.js";
+import { captureDeliveredMessageId } from "../core/sent-index.js";
+import { createCommandTokenProvider } from "../core/oauth.js";
+import { createOpenidClient } from "../core/oauth-openid.js";
+import { buildTokenProvider } from "../core/token-source.js";
+import { fileTokenStore } from "../store/oauth-store.js";
+import { scanAndProcess } from "./process.js";
+import { applyUidValidity, createSourceProxy } from "./source-proxy.js";
+import { createRegistry } from "../store/registry.js";
+import { createImapWatcher } from "./watcher.js";
+import { createImapflowFactory } from "./imapflow.js";
+import { createDaemonService } from "./service.js";
+import { runSmoke } from "../core/smoke.js";
+import { runSetup } from "../core/setup.js";
+import { listPending } from "../store/pending-store.js";
+import { advanceCursor, isPrimed, markPrimed, readCursor } from "../store/uid-cursor.js";
+import { alreadyPrimedMessage, runPrime } from "../core/prime.js";
+import { packageVersion } from "../core/version.js";
+import { API_VERSION } from "./api.js";
+import { recordOutbound } from "../store/threads.js";
+import { tokenFromSubject } from "../core/token.js";
+const EXIT_CONFIG = 2;
+const EXIT_AUTH = 3;
+const EXIT_NETWORK = 4;
+// ---------------------------------------------------------------------------
+// Token supply
+// ---------------------------------------------------------------------------
+/**
+ * Pick the token source for this installation.
+ *
+ * Precedence: built-in device-code OAuth2 (self-refreshing) -> a configured
+ * command -> none (LOGIN auth). Returning `undefined` is not an error: it means
+ * the account does not use XOAUTH2.
+ */
+/**
+ * `--auth`: approve the device grant once and persist the refresh token.
+ * Prints the URL and code, waits for approval, then exits.
+ */
+async function login(config) {
+    if (!config.oauth?.issuer || !config.oauth.clientId) {
+        log("oauth.issuer and oauth.clientId are required for device login — see docs/OAUTH.md");
+        return EXIT_CONFIG;
+    }
+    const client = await createOpenidClient(config.oauth);
+    // Start the grant and show the human what to do BEFORE waiting on them.
+    const authorization = await client.deviceAuthorization();
+    process.stdout.write(`\nApprove this login:\n  ${authorization.verificationUri}\n`);
+    if (authorization.userCode)
+        process.stdout.write(`Code: ${authorization.userCode}\n`);
+    process.stdout.write("\nWaiting for approval…\n");
+    try {
+        const tokens = await client.pollDeviceAuthorization();
+        if (!tokens.refreshToken) {
+            log("the provider returned no refresh_token — add offline_access to oauth.scope");
+            return EXIT_AUTH;
+        }
+        fileTokenStore().write({
+            refreshToken: tokens.refreshToken,
+            accessToken: tokens.accessToken,
+            expiresAt: tokens.expiresAt,
+        });
+    }
+    catch (error) {
+        log(`login failed: ${error.message}`);
+        return EXIT_AUTH;
+    }
+    log("authorised; refresh token stored");
+    return 0;
+}
+/**
+ * `--smoke`: prove the real account works, both directions, without pi.
+ *
+ *   1. resolve a token (LOGIN or OAuth2)
+ *   2. send one mail over SMTP
+ *   3. open the IMAP folder and count messages
+ *
+ * Deliberately does NOT touch the cursor, the journal, or any pending record, so a
+ * smoke test can never disturb real deliveries.
+ */
+async function smoke(config) {
+    const tokenProvider = await buildTokenProvider(config);
+    const result = await runSmoke(config, {
+        ...(tokenProvider ? { getAccessToken: () => tokenProvider.getToken() } : {}),
+    });
+    for (const step of result.steps) {
+        log(`${step.step} ${step.ok ? "ok" : "FAILED"}: ${step.detail}`);
+        if (step.hint)
+            log(`  hint: ${step.hint}`);
+    }
+    if (!result.ok)
+        return EXIT_AUTH;
+    log("smoke ok: both directions work");
+    return 0;
+}
+/**
+ * `--prime`: move the UID cursor to the newest message without reading anything.
+ *
+ * Without this, the first scan walks the entire existing mailbox: it fetches and
+ * parses every message looking for a routing token. Nothing is stored and nothing
+ * is marked seen, but on a mailbox that also carries personal mail that is both
+ * slow and more exposure than a notification bridge needs. Priming says "watch
+ * from now on".
+ *
+ * First run only: after that the cursor is the thing that makes mail visible, and
+ * moving it forward would silently skip replies that arrived while nothing scanned.
+ */
+async function prime(config) {
+    const tokenProvider = await buildTokenProvider(config);
+    const getAccessToken = tokenProvider ? () => tokenProvider.getToken() : undefined;
+    const client = await createImapflowFactory({ ...(getAccessToken ? { getAccessToken } : {}) })(config, { idleRenewMs: config.tuning.idleRenewMs });
+    try {
+        const plan = await runPrime(config, {
+            openMailbox: async (cfg) => {
+                await client.connect();
+                await client.mailboxOpen(cfg.mail.imap.folder || "INBOX");
+                return {
+                    search: () => client.search({ uid: "1:*" }, { uid: true }),
+                    close: async () => client.logout(),
+                };
+            },
+            readCursor: () => readCursor(process.env),
+            isPrimed: () => isPrimed(process.env),
+            markPrimed: () => markPrimed(process.env),
+            advanceCursor: (uid) => {
+                advanceCursor(process.env, uid);
+            },
+        });
+        if (!plan.ok) {
+            log(alreadyPrimedMessage(plan.currentUid));
+            return EXIT_CONFIG;
+        }
+        log(`primed: cursor set to uid ${plan.highest} (${plan.count} existing message(s) will not be read)`);
+        return 0;
+    }
+    catch (error) {
+        log(`prime failed: ${error.message}`);
+        return EXIT_AUTH;
+    }
+    finally {
+        try {
+            await client.logout();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+/**
+ * One daemon per state directory, whatever port it thinks it owns.
+ *
+ * `wx` makes the create atomic; the pid inside lets a later process tell a live holder from a
+ * crash. A holder that is gone is stolen, so a killed daemon does not lock the machine out.
+ */
+function acquireDaemonLock(env) {
+    const path = statePath(env, "daemon.lock");
+    const take = () => {
+        try {
+            mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+            writeFileSync(path, String(process.pid), { flag: "wx", mode: 0o600 });
+            return {
+                ok: true,
+                release: () => {
+                    // Only remove our own: a stolen lock belongs to someone else now.
+                    try {
+                        if (readFileSync(path, "utf8").trim() === String(process.pid))
+                            unlinkSync(path);
+                    }
+                    catch {
+                        /* already gone */
+                    }
+                },
+            };
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const first = take();
+    if (first)
+        return first;
+    let holder = 0;
+    try {
+        holder = Number(readFileSync(path, "utf8").trim());
+    }
+    catch {
+        /* unreadable: treat as stale */
+    }
+    const alive = holder > 0 && holder !== process.pid && (() => {
+        try {
+            process.kill(holder, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    })();
+    if (alive)
+        return { ok: false, pid: holder };
+    // Stale: the holder is gone (a crash, or a reboot with a leftover file). Steal it by
+    // RENAMING it aside, not unlinking it: an unlink plus a retake lets two stealers both win -
+    // B unlinks the corpse, creates its own lock, then C unlinks *B's live lock* and creates
+    // its own. A rename is atomic, so exactly one stealer gets the file; the winner verifies it
+    // took the corpse it judged dead, and puts back anything that is not.
+    const aside = `${path}.${process.pid}.stale`;
+    try {
+        renameSync(path, aside);
+    }
+    catch {
+        // Someone else moved it first; try again from the top once.
+        const retry = take();
+        return retry ?? { ok: false, pid: holder };
+    }
+    let moved = Number.NaN;
+    try {
+        moved = Number(readFileSync(aside, "utf8").trim());
+    }
+    catch {
+        /* unreadable */
+    }
+    if (moved !== holder) {
+        // The file changed between the liveness check and our rename: restore it untouched and
+        // report the current holder rather than stealing a live lock.
+        try {
+            renameSync(aside, path);
+        }
+        catch {
+            /* if we cannot put it back, leave it aside; the next start will judge it */
+        }
+        const retry = take();
+        return retry ?? { ok: false, pid: Number.isFinite(moved) ? moved : holder };
+    }
+    try {
+        unlinkSync(aside);
+    }
+    catch {
+        /* already gone */
+    }
+    const second = take();
+    return second ?? { ok: false, pid: holder };
+}
+function argValue(argv, flag) {
+    const index = argv.indexOf(flag);
+    if (index < 0)
+        return undefined;
+    const next = argv[index + 1];
+    return next && !next.startsWith("--") ? next : undefined;
+}
+/**
+ * `--setup <pi-address> [--to <your-address>] [--force]` — the headless twin of
+ * `/mailbridge setup`. Shares core/setup.ts, so behaviour cannot drift.
+ */
+async function setup(argv) {
+    const address = argValue(argv, "--setup");
+    if (!address) {
+        log("usage: --setup <pi-address> [--to <your-address>] [--force]");
+        return EXIT_CONFIG;
+    }
+    const to = argValue(argv, "--to");
+    const result = await runSetup({ address, ...(to ? { to } : {}), force: argv.includes("--force") });
+    for (const step of result.steps)
+        log(step);
+    if (result.next)
+        log(`next: ${result.next}`);
+    return result.ok ? 0 : EXIT_CONFIG;
+}
+function log(message) {
+    // Timestamped: a live review had to read TCP counters to prove the poll was running, because
+    // the log carried no time and empty scans are silent.
+    console.error(`pi-mailbridge: ${new Date().toISOString().slice(0, 19)}Z ${message}`);
+}
+/**
+ * `--check`: report every problem distinctly and exit with a code a supervisor
+ * can act on. Never touches mail.
+ */
+/**
+ * Problems `--check` reports, without the network or the log side-effects.
+ * Exported so the combination rules can be tested.
+ */
+export function checkProblems(config) {
+    const problems = [];
+    const add = (problem) => {
+        if (!problems.includes(problem))
+            problems.push(problem);
+    };
+    // config.warnings already covers missing host/user/to and an empty allowlist. A repaired
+    // malformed section is reported but is not a reason to refuse to start: the daemon runs.
+    for (const warning of config.warnings)
+        if (!warning.startsWith(REPAIRED_PREFIX))
+            add(warning);
+    if (!hasUsableMailConfig(config)) {
+        add("mail.imap.host / mail.imap.user / mail.smtp.host / mail.to must all be set");
+    }
+    // Same check as /mailbridge check: one address plus DMARC means every reply is rejected
+    // on providers that stamp no Authentication-Results on self-addressed mail. This is the
+    // headless path a supervisor runs, so it must not stay silent.
+    if (config.security.allowSelfReplies && config.security.requireDmarcPass) {
+        add("security.allowSelfReplies is on but security.requireDmarcPass is too — providers that do not " +
+            "stamp Authentication-Results on self-addressed mail will reject every reply (dmarc-missing)");
+    }
+    return problems;
+}
+async function check(config) {
+    let code = 0;
+    const problems = checkProblems(config);
+    const add = (problem) => {
+        if (!problems.includes(problem))
+            problems.push(problem);
+    };
+    if (config.mail.imap.authType === "XOAUTH2" || config.mail.smtp.authType === "XOAUTH2") {
+        const hasOAuth = Boolean(config.oauth?.issuer && config.oauth?.clientId);
+        const command = config.mail.smtp.tokenCommand ?? config.mail.imap.tokenCommand ?? [];
+        if (hasOAuth) {
+            const stored = fileTokenStore().read();
+            if (stored?.refreshToken) {
+                log("oauth: refresh token present");
+            }
+            else {
+                add("oauth is configured but no refresh token yet — run `/mailbridge auth` in pi (or `pi-mailbridge --auth`)");
+                code = EXIT_AUTH;
+            }
+        }
+        else if (command.length === 0) {
+            add("XOAUTH2 selected but neither oauth.* nor tokenCommand is configured");
+            code = EXIT_AUTH;
+        }
+        else {
+            const provider = createCommandTokenProvider({ command });
+            try {
+                await provider.getToken();
+                log(`token command ok (${command[0]})`);
+            }
+            catch (error) {
+                add(error.message);
+                code = EXIT_AUTH;
+            }
+        }
+    }
+    if (config.security.requireDmarcPass && !config.security.trustedAuthservId) {
+        log("note: security.trustedAuthservId unset — trusting the topmost Authentication-Results header");
+    }
+    try {
+        ensureSecret();
+        log("shared secret ok");
+    }
+    catch (error) {
+        add(`secret: ${error.message}`);
+        code = code || EXIT_CONFIG;
+    }
+    for (const problem of problems)
+        log(`  ! ${problem}`);
+    if (problems.length === 0)
+        log("config ok");
+    return code || (problems.length > 0 ? EXIT_CONFIG : 0);
+}
+/** The config file's mtime, or 0 when there is no file. */
+function configStamp(env = process.env) {
+    try {
+        return statSync(configPath(env), { throwIfNoEntry: false })?.mtimeMs ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+async function run(initialConfig, initialStamp) {
+    const token = ensureSecret().toString("base64url");
+    // Mutable refs: /reload swaps both without recreating the HTTP service.
+    let currentConfig = initialConfig;
+    let currentWatcher;
+    let tokenProvider;
+    let service;
+    const getAccessToken = () => (tokenProvider ? tokenProvider.getToken() : Promise.reject(new Error("no token provider")));
+    // A stable MailSource the service can hold across reloads.
+    // One registry for the process: the service uses it for decisions, and the UIDVALIDITY
+    // reset releases the slots of records it drops.
+    const registry = createRegistry();
+    // Built once; every call reads the live watcher, which /reload swaps.
+    const sourceProxy = createSourceProxy({ watcher: () => currentWatcher, env: process.env });
+    let reportedModeOff = false;
+    // Last scan outcome, surfaced on /health so `/mailbridge status` can answer "why did my
+    // reply not arrive?" - the reasons were already computed, just never shown.
+    // When the running config was read. The extension compares this with the config file's
+    // mtime: a session that attaches to an already-running daemon must not inherit a config
+    // the daemon read before the user changed it.
+    // The mtime of the file this config came from, taken BEFORE it was read, so a write in
+    // the gap is still detected as newer.
+    let configLoadedAt = initialStamp;
+    /** Periodic catch-up timer (armed at the end of run()). */
+    let pollHandle;
+    let lastCheckedAt;
+    let lastScan;
+    const scanOnce = createScanQueue((why) => scanNow(why));
+    function formatReasons(reasons) {
+        const parts = Object.entries(reasons)
+            .filter(([, n]) => n > 0)
+            .sort((a, b) => b[1] - a[1])
+            .map(([reason, n]) => `${reason}=${n}`);
+        return parts.length ? parts.join(" ") : "no reasons";
+    }
+    async function scanNow(why) {
+        // `off` must actually close the channel, not just stop the mail coming back.
+        // While mode is off nothing is fetched or persisted and the cursor stays put, so
+        // turning `/mailbridge on` back on processes what arrived meanwhile.
+        // Stamped before the gate: "last checked" answers "is the poll loop alive", and while
+        // mode is off it is the only thing it can honestly mean. Leaving it stale made a quiet
+        // off period look identical to a dead poll loop - the symptom this line exists to show.
+        lastCheckedAt = Date.now();
+        if (!scanningEnabled(readMode(process.env))) {
+            if (!reportedModeOff) {
+                reportedModeOff = true;
+                log(`${why}: email mode is off - not scanning`);
+            }
+            return;
+        }
+        reportedModeOff = false;
+        const before = new Set(listPending().map((r) => r.uid));
+        try {
+            const result = await scanAndProcess(currentConfig, {
+                source: sourceProxy,
+                secret: ensureSecret(),
+                onDropped: (sessionId) => registry.release(sessionId),
+            });
+            // Keep the last scan that actually saw mail. Overwriting it with every empty
+            // catch-up scan made the "why did my reply not arrive" panel a few seconds old on a
+            // mailbox that receives anything else.
+            if (result.examined > 0) {
+                lastScan = {
+                    at: Date.now(),
+                    examined: result.examined,
+                    persisted: result.persisted,
+                    rejected: result.rejected,
+                    reasons: result.reasons,
+                };
+            }
+            if (result.persisted > 0) {
+                // Name the reasons even on a partial success: "rejected 1" alone leaves the user
+                // unable to tell which reply was dropped and why.
+                log(`${why}: persisted ${result.persisted} of ${result.examined} (rejected ${result.rejected}: ${formatReasons(result.reasons)})`);
+                for (const record of listPending()) {
+                    if (!before.has(record.uid))
+                        service.broadcast({ type: "delivery", pending: record });
+                }
+            }
+            else if (result.examined > 0) {
+                // Name the reasons: "nothing for us" is what makes a missing reply undebuggable.
+                log(`${why}: examined ${result.examined}, nothing for us (${formatReasons(result.reasons)})`);
+            }
+        }
+        catch (error) {
+            // A scan failure must not kill the daemon: the cursor did not advance, so
+            // the next IDLE event or catch-up retries the same UIDs.
+            log(`${why}: scan failed: ${error.message}`);
+        }
+    }
+    const armPoll = () => {
+        // Clearing first makes this callable from /reload: setting the interval to 0 leaves no
+        // tick to re-read it, so without an external re-arm a later `/reload` could never turn
+        // the safety net back on.
+        if (pollHandle !== undefined)
+            clearTimeout(pollHandle);
+        pollHandle = undefined;
+        // Read the interval on every tick so `/reload` can change it, and reuse the same mode
+        // rule the scanner uses rather than spelling it out again.
+        const scanEveryMs = Math.max(0, currentConfig.daemon.scanIntervalSecs ?? 60) * 1000;
+        if (scanEveryMs === 0)
+            return;
+        pollHandle = setTimeout(() => {
+            pollHandle = undefined;
+            if (scanningEnabled(readMode(process.env)) && currentWatcher?.isHealthy())
+                void scanOnce("poll");
+            armPoll();
+        }, scanEveryMs);
+        pollHandle.unref?.();
+    };
+    let reloadInFlight;
+    async function doReload(pass = 0) {
+        const previous = currentConfig;
+        const previousProvider = tokenProvider;
+        const previousStamp = configLoadedAt;
+        // Stamped at entry: if the file changes while this reload runs, the caller(s) joined to
+        // it must not be told their newer config is in force.
+        const startedFrom = configStamp();
+        try {
+            await currentWatcher?.stop();
+            configLoadedAt = startedFrom;
+            currentConfig = loadConfig();
+            tokenProvider = await buildTokenProvider(currentConfig);
+            const watcher = await startWatcher(currentConfig);
+            // start() does not throw on a refused connect - it arms a reconnect - so ask the
+            // watcher whether it is actually connected before calling the reload a success.
+            if (!watcher.isHealthy()) {
+                // The config was re-read; the connection is what failed, and the watcher is
+                // retrying. Report it rather than calling the reload clean.
+                log("reloaded config, but IMAP did not connect (check the password/host)");
+                armPoll();
+                return { ok: true, warning: "config reloaded, but IMAP did not connect" };
+            }
+            // Someone wrote the config while we were re-dialling (a `/mailbridge setup` that
+            // joined this reload, for instance). One extra pass so they get a reload that
+            // started after their write - otherwise mail keeps going to the address they
+            // just replaced until the next session notices.
+            if (pass === 0 && configStamp() > startedFrom)
+                return doReload(1);
+            log("reloaded config and restarted the watcher");
+            armPoll();
+            return { ok: true };
+        }
+        catch (error) {
+            // Do not leave the daemon holding a config whose watcher never started - nor a token
+            // provider built for credentials that were just rolled back.
+            currentConfig = previous;
+            tokenProvider = previousProvider;
+            configLoadedAt = previousStamp;
+            try {
+                await startWatcher(previous);
+                log(`reload failed (${error.message}); kept the previous config`);
+            }
+            catch {
+                log(`reload failed (${error.message}); previous watcher could not restart either`);
+            }
+            return { ok: false, error: error.message };
+        }
+    }
+    async function startWatcher(config) {
+        const watcher = createImapWatcher(config, {
+            factory: createImapflowFactory({ getAccessToken: tokenProvider ? getAccessToken : undefined }),
+            callbacks: {
+                onReady: () => {
+                    // UIDs are only meaningful within one UIDVALIDITY. A recreated or migrated
+                    // folder renumbers from 1; without this the high-water cursor would skip
+                    // every future message, with "examined 0" as the only symptom.
+                    // `currentWatcher` is assigned before start(), so it is this watcher here.
+                    const outcome = applyUidValidity(process.env, currentWatcher, (sessionId) => registry.release(sessionId));
+                    if (outcome.reset) {
+                        log(`mailbox UIDVALIDITY changed to ${outcome.validity}; cursor reset and ${outcome.dropped} queued record(s) dropped - re-reading from the start`);
+                    }
+                    else if (outcome.dropped > 0) {
+                        // No reset needed, but records from a previous numbering were still stuck in
+                        // the queue (a crash between the cursor write and the drop). Say so.
+                        log(`${outcome.dropped} queued record(s) from an earlier UID space dropped`);
+                    }
+                    log("imap ready; running catch-up scan");
+                    void scanOnce("catch-up");
+                },
+                onMail: () => {
+                    void scanOnce("idle");
+                },
+                onError: (error, delay) => log(`imap error (${error.message}); reconnecting in ${delay}ms`),
+            },
+        });
+        // Assign BEFORE starting: `start()` fires onReady, and the catch-up scan it
+        // triggers reads through sourceProxy. With the assignment after `await`, every
+        // catch-up scan failed with "imap watcher not started" and mail that arrived
+        // while the daemon was down was only picked up on the next IDLE event.
+        currentWatcher = watcher;
+        await watcher.start();
+        return watcher;
+    }
+    tokenProvider = await buildTokenProvider(initialConfig);
+    service = createDaemonService({
+        // The service must see the CURRENT config: /reload swaps it, and a stale recipient
+        // would keep mailing the previous address after a documented re-setup.
+        getConfig: () => currentConfig,
+        registry,
+        config: initialConfig,
+        token,
+        source: sourceProxy,
+        send: async (message) => {
+            const provider = tokenProvider;
+            return sendWithCapture(message, (current) => sendMail(currentConfig, current, {
+                ...(provider ? { getAccessToken: () => provider.getToken() } : {}),
+                // Lets a revoked grant be refreshed once instead of failing the notification.
+                ...(provider ? { provider } : {}),
+            }), {
+                sentFolder: currentConfig.mail.imap.sentFolder,
+                capture: (mintedId, subject, sessionId) => captureDeliveredMessageId({
+                    config: currentConfig,
+                    mintedId,
+                    subject,
+                    sessionId,
+                    ...(provider ? { getAccessToken: () => provider.getToken() } : {}),
+                }),
+                onMissed: () => log("could not read the sent copy back; the reply chain may not match this mail"),
+            });
+        },
+        onSent: ({ messageId, subject, sessionId }) => {
+            if (!messageId)
+                return;
+            // The sender knows the session; parsing it back out of the subject only works
+            // for legacy signed tokens, because production subjects carry a short route id.
+            // That bug silently disabled both threading and the reply-chain fallback.
+            const parsed = sessionId ? { sessionId, device: currentConfig.device.name } : tokenFromSubject(subject, ensureSecret());
+            if (!parsed)
+                return;
+            recordOutbound(process.env, {
+                messageId,
+                sessionId: parsed.sessionId,
+                ...(parsed.device ? { device: parsed.device } : {}),
+                subject,
+            });
+        },
+        // Lets `/mailbridge restart` replace the process, not just its config, so an
+        // updated package actually takes effect.
+        shutdown: (reason) => {
+            void shutdown(reason ?? "shutdown requested");
+        },
+        // Always carry the freshness stamp: on a quiet mailbox `lastScan` is absent, and the
+        // panel then said "(none yet)" while the daemon was happily polling.
+        scanSummary: () => ({ ...(lastScan ?? {}), ...(lastCheckedAt ? { checkedAt: lastCheckedAt } : {}) }),
+        version: packageVersion(import.meta.url),
+        apiVersion: API_VERSION,
+        log,
+        // The file's mtime, not a clock reading: comparing mtime to mtime has no clock coupling.
+        configLoadedAt: () => configLoadedAt,
+        imapHealthy: () => currentWatcher?.isHealthy() ?? false,
+        // Re-open the channel: process what arrived while mode was off, and retry anything a
+        // full queue refused. Safe to call when nothing changed (an empty scan is cheap).
+        onModeChange: (mode) => {
+            // Only "on" needs work; "off" simply stops the next scan from doing anything.
+            if (mode === "on" && currentWatcher)
+                void scanOnce("mode-on");
+        },
+        idleTimeoutMs: (currentConfig.daemon.idleTimeoutSecs ?? 120) * 1000,
+        // `/mailbridge setup` / `auth` write new config or tokens; pick them up here.
+        // One reload at a time: two sessions noticing the same stale config must not each
+        // stop and redial the watcher.
+        reload: () => (reloadInFlight ??= doReload().finally(() => (reloadInFlight = undefined))),
+    });
+    service.server.on("error", (error) => {
+        if (error.code === "EADDRINUSE") {
+            log(`another daemon already owns port ${currentConfig.daemon.port}; exiting`);
+            process.exit(0);
+        }
+        log(`http server failed: ${error.message}`);
+        process.exit(1);
+    });
+    // Refuse a state directory written by a newer build before touching it: a load-time throw
+    // inside a request or a scan would surface late and repeatedly.
+    try {
+        assertStateReadable(process.env);
+    }
+    catch (error) {
+        log(error.message);
+        process.exit(EXIT_CONFIG);
+    }
+    const lock = acquireDaemonLock(process.env);
+    if (!lock.ok) {
+        log(`another daemon is already running (pid ${lock.pid}); exiting`);
+        process.exit(0);
+    }
+    const { port, host } = await service.listen();
+    log(`listening on http://${host}:${port}`);
+    // Register shutdown handlers BEFORE dialling IMAP: a SIGTERM during a slow
+    // DNS/TLS dial must still shut down cleanly.
+    let stopping = false;
+    const shutdown = async (signal) => {
+        if (stopping)
+            return;
+        stopping = true;
+        log(`${signal}: shutting down`);
+        lock.release();
+        if (pollHandle !== undefined)
+            clearTimeout(pollHandle);
+        await currentWatcher?.stop();
+        await service.close();
+        process.exit(0);
+    };
+    process.on("SIGTERM", () => void shutdown("SIGTERM"));
+    process.on("SIGINT", () => void shutdown("SIGINT"));
+    await startWatcher(currentConfig);
+    armPoll();
+    // Safety net: an IDLE that never fires (a provider that does not push, or a connection that
+    // silently stopped idling) would strand every reply until something else triggered a scan.
+    // A catch-up sweep costs one SEARCH that usually returns nothing. Observed live: a Hotmail
+    // reply sat unseen while the daemon reported "imap: connected".
+}
+/**
+ * Send, then read the delivered Message-ID back.
+ *
+ * The order is the point: the provider appends the Sent copy asynchronously (QQ took 20-30 s
+ * in one measurement), and an earlier version that captured first recorded the *previous*
+ * notification's id against this session. Extracted so a test can hold that order.
+ */
+export async function sendWithCapture(message, send, deps) {
+    const sent = await send(message);
+    if (message.sessionId && message.messageId && deps.sentFolder) {
+        // Fire-and-forget: the notification never fails because the bookkeeping could not be read.
+        void deps
+            .capture(message.messageId, message.subject, message.sessionId)
+            .then((id) => {
+            if (!id)
+                deps.onMissed?.();
+        })
+            .catch(() => deps.onMissed?.());
+    }
+    return sent;
+}
+export async function main() {
+    const argv = process.argv.slice(2);
+    // Stamp before reading: a write landing between the read and a later Date.now() would
+    // otherwise be invisible to the freshness check.
+    const startupStamp = configStamp();
+    let config = loadConfig();
+    // A daemon spawned by a session is told the port that session probed, so it cannot bind a
+    // different one from its own env and leave the session reporting "unreachable".
+    const portArg = argValue(argv, "--port");
+    if (portArg !== undefined) {
+        const port = Number(portArg);
+        if (Number.isInteger(port) && port >= 1 && port <= 65_535) {
+            config = { ...config, daemon: { ...config.daemon, port } };
+        }
+    }
+    if (argv.includes("--print-token")) {
+        process.stdout.write(`${ensureSecret().toString("base64url")}\n`);
+        return;
+    }
+    if (argv.includes("--check")) {
+        process.exitCode = await check(config);
+        return;
+    }
+    if (argv.includes("--setup")) {
+        process.exitCode = await setup(argv);
+        return;
+    }
+    if (argv.includes("--auth")) {
+        process.exitCode = await login(config);
+        return;
+    }
+    if (argv.includes("--prime")) {
+        process.exitCode = await prime(config);
+        return;
+    }
+    if (argv.includes("--smoke")) {
+        for (const warning of config.warnings)
+            log(`warning: ${warning}`);
+        process.exitCode = await smoke(config);
+        return;
+    }
+    if (!hasUsableMailConfig(config)) {
+        for (const warning of config.warnings)
+            log(`  ! ${warning}`);
+        log("mail config incomplete — run with --check for details");
+        process.exit(EXIT_CONFIG);
+    }
+    for (const warning of config.warnings)
+        log(`warning: ${warning}`);
+    await run(config, startupStamp);
+}
+// `import.meta.url` is a URL and `process.argv[1]` is a path: comparing them as strings fails
+// for any install directory with a space or non-ASCII character (and for a symlinked package),
+// where this file would then run nothing and exit 0 - the unit looks started and is dead.
+function isEntryPoint() {
+    const invoked = process.argv[1];
+    if (!invoked)
+        return false;
+    try {
+        return realpathSync(invoked) === realpathSync(fileURLToPath(import.meta.url));
+    }
+    catch (error) {
+        // A silent `false` here is a process that does nothing and exits 0 - under the unit's
+        // ExecStartPre that reads as success. Say why instead.
+        log(`cannot resolve the entry point (${error.message})`);
+        return false;
+    }
+}
+if (isEntryPoint()) {
+    main().catch((error) => {
+        log(`fatal: ${error instanceof Error ? error.message : String(error)}`);
+        process.exit(1);
+    });
+}