@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.1

package/src/daemon/main.ts

@@ -0,0 +1,832 @@
+// 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.ts"
+import { assertStateReadable } from "../store/schema.ts"
+import { dirname } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import {
+	loadConfig,
+	hasUsableMailConfig,
+	shortHostname,
+	REPAIRED_PREFIX,
+	type ResolvedConfig,
+} from "../core/config.ts"
+import { configPath } from "../store/paths.ts"
+import { buildSetupConfig, discoverDomain, domainOf } from "../core/discover.ts"
+import { ensureSecret } from "../store/secret.ts"
+import { readMode, scanningEnabled } from "../store/mode-store.ts"
+import { createScanQueue } from "./scan-queue.ts"
+import { sendMail } from "../core/mailer.ts"
+import { captureDeliveredMessageId } from "../core/sent-index.ts"
+import { createCommandTokenProvider } from "../core/oauth.ts"
+import { createOpenidClient } from "../core/oauth-openid.ts"
+import { buildTokenProvider } from "../core/token-source.ts"
+import { fileTokenStore } from "../store/oauth-store.ts"
+import { scanAndProcess } from "./process.ts"
+import { applyUidValidity, createSourceProxy } from "./source-proxy.ts"
+import { createRegistry } from "../store/registry.ts"
+import { createImapWatcher, type ImapWatcher } from "./watcher.ts"
+import { createImapflowFactory } from "./imapflow.ts"
+import { createDaemonService, type DaemonService } from "./service.ts"
+import type { MailSource } from "./process.ts"
+import { runSmoke } from "../core/smoke.ts"
+import { runSetup } from "../core/setup.ts"
+import { listPending } from "../store/pending-store.ts"
+import { advanceCursor, isPrimed, markPrimed, readCursor } from "../store/uid-cursor.ts"
+import { alreadyPrimedMessage, runPrime } from "../core/prime.ts"
+import { packageVersion } from "../core/version.ts"
+import { API_VERSION } from "./api.ts"
+import { recordOutbound } from "../store/threads.ts"
+import { tokenFromSubject } from "../core/token.ts"
+
+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: ResolvedConfig): Promise<number> {
+	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 as 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: ResolvedConfig): Promise<number> {
+	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: ResolvedConfig): Promise<number> {
+	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: ResolvedConfig) => {
+				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: number) => {
+				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 as 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: NodeJS.ProcessEnv): { ok: true; release: () => void } | { ok: false; pid: number } {
+	const path = statePath(env, "daemon.lock")
+	const take = (): { ok: true; release: () => void } | undefined => {
+		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 as NodeJS.ErrnoException).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: string[], flag: string): string | undefined {
+	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: string[]): Promise<number> {
+	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: string): void {
+	// 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: ResolvedConfig): string[] {
+	const problems: string[] = []
+	const add = (problem: string) => {
+		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: ResolvedConfig): Promise<number> {
+	let code = 0
+	const problems = checkProblems(config)
+	const add = (problem: string) => {
+		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 as 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 as 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: NodeJS.ProcessEnv = process.env): number {
+	try {
+		return statSync(configPath(env), { throwIfNoEntry: false })?.mtimeMs ?? 0
+	} catch {
+		return 0
+	}
+}
+
+async function run(initialConfig: ResolvedConfig, initialStamp: number): Promise<void> {
+	const token = ensureSecret().toString("base64url")
+
+	// Mutable refs: /reload swaps both without recreating the HTTP service.
+	let currentConfig = initialConfig
+	let currentWatcher: ImapWatcher | undefined
+	let tokenProvider: Awaited<ReturnType<typeof buildTokenProvider>>
+	let service: DaemonService
+
+	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: MailSource = 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: ReturnType<typeof setTimeout> | undefined
+	let lastCheckedAt: number | undefined
+	let lastScan: { at: number; examined: number; persisted: number; rejected: number; reasons: Record<string, number> } | undefined
+	const scanOnce = createScanQueue((why) => scanNow(why))
+
+	function formatReasons(reasons: Record<string, number>): string {
+		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: string): Promise<void> {
+		// `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 as Error).message}`)
+		}
+	}
+
+	const armPoll = (): void => {
+		// 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: Promise<{ ok: boolean; error?: string; warning?: string }> | undefined
+
+	async function doReload(pass = 0): Promise<{ ok: boolean; error?: string; warning?: string }> {
+		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 as Error).message}); kept the previous config`)
+			} catch {
+				log(`reload failed (${(error as Error).message}); previous watcher could not restart either`)
+			}
+			return { ok: false, error: (error as Error).message }
+		}
+	}
+
+	async function startWatcher(config: ResolvedConfig): Promise<ImapWatcher> {
+		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?: string) => {
+			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: NodeJS.ErrnoException) => {
+		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 as 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: string) => {
+		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<M extends { messageId?: string; sessionId?: string; subject: string }, R>(
+	message: M,
+	send: (message: M) => Promise<R>,
+	deps: {
+		sentFolder?: string
+		capture: (mintedId: string, subject: string, sessionId: string) => Promise<string | undefined>
+		onMissed?: () => void
+	},
+): Promise<R> {
+	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(): Promise<void> {
+	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(): boolean {
+	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 as Error).message})`)
+		return false
+	}
+}
+
+if (isEntryPoint()) {
+	main().catch((error: unknown) => {
+		log(`fatal: ${error instanceof Error ? error.message : String(error)}`)
+		process.exit(1)
+	})
+}