@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/src/core/reply-parse.ts

@@ -0,0 +1,153 @@
+// Reply parsing: turn a raw mail body into the single line of human intent.
+//
+// Quoted-text stripping is the fragile part of any email bridge — every client
+// quotes differently. The approach here is deliberately blunt: cut at the first
+// recognizable quote boundary and accept the remainder. Being clever (nested
+// quoting, locale heuristics) loses more than it gains.
+//
+// Outbound mail instructs the human to reply *above* the quoted text, so the
+// top of the body is the answer.
+
+/** Markers that begin a quoted/original section. Matched case-insensitively. */
+const QUOTE_BOUNDARIES: RegExp[] = [
+	// "On Tue, 3 Jun 2025 at 09:12, pi <pi@example.com> wrote:"
+	/^\s*On\b.{0,200}\bwrote:\s*$/i,
+	// Outlook / web clients
+	/^\s*-{2,}\s*Original Message\s*-{2,}\s*$/i,
+	// QQ Mail web (Chinese UI) - the primary client for the primary target users:
+	// "------------------ 原始邮件 ------------------" and its 163/126 cousins.
+	/^\s*-{2,}\s*原始邮件\s*-{2,}\s*$/,
+	/^\s*-{2,}\s*原邮件\s*-{2,}\s*$/,
+	// "在 2025年6月3日 09:12，pi <pi@example.com> 写道："
+	/^\s*在\s.{0,120}写道[：:]\s*$/,
+	// "发件人: pi <pi@example.com>" (QQ/163 header block)
+	/^\s*发件人[：:]\s*.+$/,
+	/^\s*_{10,}\s*$/,
+	/^\s*From:\s.+$/i,
+	// "> " quoted block start (BEFORE the boundary scan strips lines)
+	/^\s*>/,
+	// Forwarded-message banner
+	/^\s*-{2,}\s*Forwarded message\s*-{2,}\s*$/i,
+	// Mobile clients
+	/^\s*Sent from my\b/i,
+	// Outlook mobile app signature, in either the English or the Chinese build.
+	/^\s*(?:获取|Get)\s*Outlook\s*for\s+(?:Android|iOS|iPhone|iPad)\b/i,
+]
+
+/** Signature delimiter per RFC 3676 §4.3 — "dash dash space". */
+const SIGNATURE_DELIM = /^--\s*$/
+
+function normalizeNewlines(text: string): string {
+	return text.replace(/\r\n?/g, "\n")
+}
+
+/**
+ * Strip quoted text and signature from a reply body.
+ *
+ * Returns the top-of-mail content, or `""` when the message carried nothing
+ * new (e.g. the body was entirely quoted). Callers must treat `""` as "no
+ * instruction" and reject — re-injecting the quoted original into the agent
+ * would just replay the agent's own output back at it.
+ */
+export function stripQuoted(raw: string): string {
+	if (!raw) return ""
+	const text = normalizeNewlines(raw)
+	const lines = text.split("\n")
+	const kept: string[] = []
+
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i]!
+		if (SIGNATURE_DELIM.test(line)) break
+		if (QUOTE_BOUNDARIES.some((re) => re.test(line))) break
+		kept.push(line)
+	}
+
+	// Drop trailing blank lines.
+	while (kept.length > 0 && kept[kept.length - 1]!.trim() === "") kept.pop()
+
+	return kept.join("\n").trim()
+}
+
+export interface HeaderLike {
+	from?: string
+	subject?: string
+	/** Every `Authentication-Results` value, in the order received (top first). */
+	authResults?: string[]
+	/** `Message-ID` of this message. Used to recognise our own mail when it comes back. */
+	messageId?: string
+	/** Marker header we stamp on every notification; its presence alone means "ours". */
+	piMailbridge?: string
+	/** `In-Reply-To`, the message this one directly answers. */
+	inReplyTo?: string
+	/** `References`, the ancestor chain. */
+	references?: string[]
+	/** `Auto-Submitted`, `Precedence`, `X-Auto-Response-Suppress`, `List-Id`. */
+	autoSubmitted?: string
+	precedence?: string
+	autoResponseSuppress?: string
+	listId?: string
+}
+
+/**
+ * Reduce `"Name" <User@Example.COM>` to `user@example.com`.
+ * Handles bare addresses, angle-addresses, and display names containing commas.
+ */
+export function normalizeAddress(input: string | undefined | null): string | undefined {
+	if (!input) return undefined
+	const angle = /<([^<>]+)>\s*$/.exec(input)
+	const candidate = (angle?.[1] ?? input).trim()
+	// Anything with whitespace left is a display name we could not parse.
+	if (!candidate || /\s/.test(candidate)) return undefined
+	if (!/^[^@\s]+@[^@\s]+$/.test(candidate)) return undefined
+	return candidate.toLowerCase()
+}
+
+/**
+ * Is this message machine-generated? Replying to one of these is how mail loops
+ * start (out-of-office → us → out-of-office → …).
+ */
+export function isAutoGenerated(headers: HeaderLike): boolean {
+	const auto = headers.autoSubmitted?.trim().toLowerCase()
+	if (auto && auto !== "no") return true
+	const prec = headers.precedence?.trim().toLowerCase()
+	if (prec === "bulk" || prec === "junk" || prec === "list") return true
+	// Not "any non-empty value": Outlook and corporate gateways stamp this header on ordinary
+	// mail too, and treating presence as machine-generated rejected genuine replies.
+	const suppress = headers.autoResponseSuppress?.trim().toLowerCase() ?? ""
+	if (/\b(oof|autoreply|auto_reply|dr|rn|nrn)\b/.test(suppress)) return true
+	if (headers.listId?.trim()) return true
+	return false
+}
+
+/**
+ * Find the `Authentication-Results` header that our own relay added.
+ *
+ * Headers are prepended as a message traverses MTAs, so the TOPMOST
+ * `Authentication-Results` is the one the final hop (your provider) wrote on
+ * delivery. A sender that includes a forged header ends up *below* it, which is
+ * why topmost-wins defeats header forgery — see docs/SECURITY.md §2.1.
+ *
+ * `authservId` pins it further when a provider writes one. It is optional
+ * because Microsoft's consumer relay emits bare headers with no authserv-id
+ * (`Authentication-Results: spf=pass ...; dmarc=pass ...`), and requiring a match
+ * there would reject every piece of genuine mail.
+ */
+export function findTrustedAuthResults(headers: HeaderLike, authservId?: string): string | undefined {
+	const values = headers.authResults ?? []
+	if (values.length === 0) return undefined
+
+	const wanted = authservId?.trim().toLowerCase()
+	if (!wanted) return values[0] // topmost = the delivering relay's
+
+	for (const value of values) {
+		const id = /^\s*([^\s;]+)/.exec(value)?.[1]?.toLowerCase()
+		if (id === wanted) return value
+	}
+	// Pinned but absent: do not silently fall back to an unverified header.
+	return undefined
+}
+
+/** `dmarc=pass` inside a specific AR header value. */
+export function dmarcPasses(authResultsValue: string): boolean {
+	return /\bdmarc\s*=\s*pass\b/i.test(authResultsValue)
+}

package/src/core/sent-index.ts

@@ -0,0 +1,164 @@
+// Record the Message-ID the provider actually delivered.
+//
+// We mint a Message-ID and stamp it, but some providers (QQ among them) replace it on
+// submission: a live test showed our `<uuid@qq.com>` stored in the Sent folder as
+// `<tencent_…@qq.com>`, and the human's reply carried the tencent id in In-Reply-To.
+//
+// The reply-chain fallback matches In-Reply-To against ids we recorded, so on such a provider
+// it never matches - the subject tag is the only remaining route.
+//
+// The just-sent copy is found by the `X-Pi-Mailbridge-Id` header, which carries the id we
+// minted. Two things learned the hard way (a live review caught both):
+//   - the copy is appended *after* the send completes, so this must run after it, and must
+//     retry: QQ took 20-30 s in one measurement;
+//   - matching on the marker header alone records a *different* notification's id when two
+//     sessions send close together, which routes a reply into the wrong session.
+
+import type { ResolvedConfig } from "./config.ts"
+import { recordOutbound } from "../store/threads.ts"
+
+export interface SentLookupClient {
+	connect(): Promise<void>
+	mailboxOpen(path: string): Promise<unknown>
+	search(query: Record<string, unknown>, options?: { uid?: boolean }): Promise<number[]>
+	fetchOne(uid: number, query: Record<string, unknown>, options?: { uid?: boolean }): Promise<unknown>
+	logout(): Promise<void>
+}
+
+/** Look back far enough to see a send that is still being appended. */
+const CAPTURE_WINDOW_MS = 30 * 60_000
+/** How many recent sent messages to inspect per attempt. */
+const CAPTURE_SCAN = 20
+/** Backoff between attempts: providers append asynchronously. */
+const DEFAULT_RETRY_DELAYS_MS = [2_000, 5_000, 15_000, 30_000, 30_000, 30_000] as const
+
+export interface CaptureOptions {
+	config: ResolvedConfig
+	/** The id we minted and stamped into `X-Pi-Mailbridge-Id`. */
+	mintedId: string
+	sessionId: string
+	subject: string
+	env?: NodeJS.ProcessEnv
+	/** XOAUTH2 accounts need a token for this connection too, exactly like the watcher. */
+	getAccessToken?: () => Promise<string>
+	/** Injected for tests. */
+	connect?: () => Promise<SentLookupClient>
+	record?: typeof recordOutbound
+	retryDelaysMs?: readonly number[]
+	sleep?: (ms: number) => Promise<void>
+}
+
+/** Pull the first `Message-ID:` out of a header block. */
+export function messageIdFromHeaders(headers: string): string | undefined {
+	const unfolded = headers.replace(/\r?\n[ \t]+/g, " ")
+	for (const line of unfolded.split(/\r?\n/)) {
+		const match = /^message-id:\s*<([^>]+)>/i.exec(line.trim())
+		if (match) return match[1]!.trim()
+	}
+	return undefined
+}
+
+/** `X-Pi-Mailbridge-Id: <uuid@domain>` — normalised, without angle brackets. */
+export function stampedIdFromHeaders(headers: string): string | undefined {
+	const unfolded = headers.replace(/\r?\n[ \t]+/g, " ")
+	for (const line of unfolded.split(/\r?\n/)) {
+		const match = /^x-pi-mailbridge-id:\s*<?([^>\s]+)>?/i.exec(line.trim())
+		if (match) return match[1]!.trim()
+	}
+	return undefined
+}
+
+/**
+ * Read the just-sent message back from the Sent folder and record its Message-ID for the
+ * session. Best-effort: a failure never fails the send, and one capture runs at a time.
+ */
+export async function captureDeliveredMessageId(options: CaptureOptions): Promise<string | undefined> {
+	const folder = options.config.mail.imap.sentFolder
+	if (!folder) return undefined
+	return serialise(options.mintedId, () => attempt(options, folder))
+}
+
+/**
+ * One capture in flight at a time, and identical requests share it.
+ *
+ * A burst of notifications must not open one connection each, and a capture can hold the
+ * queue for a minute; coalescing means a repeated request for the same minted id costs
+ * nothing extra.
+ */
+let queue: Promise<unknown> = Promise.resolve()
+const inFlightByMintedId = new Map<string, Promise<string | undefined>>()
+
+function serialise<T>(key: string, run: () => Promise<T>): Promise<T> {
+	const existing = inFlightByMintedId.get(key)
+	if (existing) return existing as Promise<T>
+	const next = queue.then(run, run)
+	queue = next.catch(() => undefined)
+	inFlightByMintedId.set(key, next as Promise<string | undefined>)
+	next.catch(() => undefined).finally(() => inFlightByMintedId.delete(key))
+	return next
+}
+
+async function attempt(options: CaptureOptions, folder: string): Promise<string | undefined> {
+	const env = options.env ?? process.env
+	const sleep = options.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)))
+	const delays = options.retryDelaysMs ?? DEFAULT_RETRY_DELAYS_MS
+	const connect = options.connect ?? (await defaultConnect(options.config, options.getAccessToken))
+	const wanted = options.mintedId.replace(/[<>]/g, "")
+
+	let client: SentLookupClient | undefined
+	try {
+		client = await connect()
+		await client.mailboxOpen(folder)
+		for (const delay of delays) {
+			if (delay > 0) await sleep(delay)
+			const since = new Date(Date.now() - CAPTURE_WINDOW_MS)
+			const uids = await client.search({ since }, { uid: true })
+			if (!uids.length) continue
+			const newestFirst = uids.slice().sort((a, b) => b - a).slice(0, CAPTURE_SCAN)
+			for (const uid of newestFirst) {
+				const fetched = (await client.fetchOne(uid, { source: true }, { uid: true })) as
+					| { source?: Buffer }
+					| false
+					| undefined
+				if (!fetched || !fetched.source) continue
+				const head = (fetched.source.toString("utf8").split(/\r?\n\r?\n/)[0] ?? "").replace(/\r?\n[ \t]+/g, " ")
+				// Only the copy of the message we just sent: the header carries our minted id.
+				if (stampedIdFromHeaders(head) !== wanted) continue
+				const messageId = messageIdFromHeaders(head)
+				if (!messageId) continue
+				;(options.record ?? recordOutbound)(env, {
+					messageId,
+					sessionId: options.sessionId,
+					...(options.config.device.name ? { device: options.config.device.name } : {}),
+					subject: options.subject,
+				})
+				return messageId
+			}
+		}
+		return undefined
+	} catch {
+		return undefined
+	} finally {
+		await client?.logout().catch(() => undefined)
+	}
+}
+
+async function defaultConnect(
+	config: ResolvedConfig,
+	getAccessToken?: () => Promise<string>,
+): Promise<() => Promise<SentLookupClient>> {
+	const { createImapflowFactory } = await import("../daemon/imapflow.ts")
+	return async () => {
+		const client = await createImapflowFactory({ ...(getAccessToken ? { getAccessToken } : {}) })(config, {
+			idleRenewMs: config.tuning.idleRenewMs,
+		})
+		try {
+			await client.connect()
+		} catch (error) {
+			// Do not leak the socket of a client whose connect failed.
+			await client.logout().catch(() => undefined)
+			throw error
+		}
+		return client as unknown as SentLookupClient
+	}
+}

package/src/core/settle.ts

@@ -0,0 +1,179 @@
+// Settle notification: the email you get when the agent stops.
+//
+// Three rules earn this module its existence:
+//   1. It fires on `agent_settled` only. `agent_end` precedes retries,
+//      compaction and queued follow-ups, so mailing there would send you a
+//      "finished" message for work that is still running.
+//   2. It is debounced. Settle → you type again → settle would otherwise mail
+//      you a half-finished answer.
+//   3. An aborted settle (Escape) is not "finished" and is skipped by default.
+
+import type { Mode } from "../store/mode-store.ts"
+import { stampSubject } from "./token.ts"
+
+export interface SettleContext {
+	sessionId: string
+	sessionName?: string
+	/** Machine the session is running on. Named in subject and body. */
+	device?: string
+	cwd: string
+	/** Completed turns in this session, when known. */
+	turns?: number
+	/** The assistant's last text, when known. */
+	lastAssistantText?: string
+}
+
+export const REPLY_HINT = "Reply above this line to continue the session."
+
+/**
+ * Subject: which session, on which device, with the routing id that makes the
+ * reply land back here. Both facts are in the subject because that is all a
+ * notification preview shows on a phone, tablet or another PC.
+ */
+export function buildSettleSubject(
+	context: SettleContext,
+	secret: Buffer,
+	tag?: string,
+	tokenTtlHours?: number,
+): string {
+	const label = context.sessionName?.trim() || context.cwd.split("/").filter(Boolean).pop() || "session"
+	const device = context.device?.trim()
+	const where = device ? ` @ ${device}` : ""
+	const body = `pi: ${label}${where} is waiting for you`
+	// A short local id keeps the subject readable; the signed token remains the
+	// fallback for callers that have no store to register against.
+	if (tag) return `[pi:${tag}] ${body}`
+	return stampSubject(context.sessionId, body, secret, {
+		...(device ? { device } : {}),
+		...(tokenTtlHours === undefined ? {} : { ttlHours: tokenTtlHours }),
+	})
+}
+
+/** Cap on the quoted agent text, so a long answer cannot become a 200-line email. */
+export const MAX_BODY_CHARS = 4_000
+
+function quoteAnswer(text: string | undefined): string {
+	const trimmed = text?.trim()
+	if (!trimmed) return "(the agent produced no text this turn)"
+	if (trimmed.length <= MAX_BODY_CHARS) return trimmed
+	return `${trimmed.slice(0, MAX_BODY_CHARS)}\n\n…truncated (${trimmed.length - MAX_BODY_CHARS} more characters)`
+}
+
+/** Plain-text body. Deliberately boring: it must survive arbitrary mail clients. */
+export function buildSettleBody(context: SettleContext): string {
+	const lines: string[] = []
+	lines.push(quoteAnswer(context.lastAssistantText))
+	lines.push("")
+	lines.push("--")
+	if (context.device?.trim()) lines.push(`device: ${context.device.trim()}`)
+	// Only name the session when it has a name; otherwise this line repeated the id.
+	if (context.sessionName?.trim()) lines.push(`session: ${context.sessionName.trim()}`)
+	lines.push(`session id: ${context.sessionId}`)
+	lines.push(`project: ${context.cwd}`)
+	if (typeof context.turns === "number") lines.push(`turns: ${context.turns}`)
+	lines.push("")
+	lines.push(REPLY_HINT)
+	return lines.join("\n")
+}
+
+export interface SettleNotifyConfig {
+	onSettled: boolean
+	debounceMs: number
+	notifyOnAborted: boolean
+	/** Lifetime of the fallback signed token; routing ids use the same value. */
+	tokenTtlHours?: number
+}
+
+export interface SettleNotifierDeps {
+	mode: () => Mode
+	/** Current session context, or undefined when there is no session. */
+	context: () => SettleContext | undefined
+	send: (message: { to: string; subject: string; text: string }) => Promise<void>
+	secret: () => Buffer
+	config: SettleNotifyConfig
+	timers: {
+		setTimeout(handler: () => void, ms: number): unknown
+		clearTimeout(handle: unknown): void
+	}
+	onError?: (error: Error) => void
+	/** Mint a short routing id for this notification. Falls back to a signed token. */
+	tagFor?: (context: SettleContext) => string | undefined
+}
+
+export type SettleOutcome = "scheduled" | "mode-off" | "aborted" | "disabled" | "no-context"
+
+export interface SettleNotifier {
+	/** Call from `agent_settled`. Returns why it did or did not schedule. */
+	settled(event?: { aborted?: boolean }): SettleOutcome
+	/** Send any pending notification immediately (tests, shutdown). */
+	flush(): Promise<void>
+	/** True while a debounced send is waiting. */
+	isPending(): boolean
+	/** Drop a pending send without sending (session shutdown). */
+	cancel(): void
+}
+
+export function createSettleNotifier(deps: SettleNotifierDeps): SettleNotifier {
+	let handle: unknown
+	let pendingContext: SettleContext | undefined
+
+	async function deliver(context: SettleContext): Promise<void> {
+		const secret = deps.secret()
+		try {
+			await deps.send({
+				to: "", // the daemon fills in mail.to
+				subject: buildSettleSubject(context, secret, deps.tagFor?.(context), deps.config.tokenTtlHours),
+				text: buildSettleBody(context),
+			})
+		} catch (error) {
+			deps.onError?.(error instanceof Error ? error : new Error(String(error)))
+		}
+	}
+
+	function cancel(): void {
+		if (handle !== undefined) {
+			deps.timers.clearTimeout(handle)
+			handle = undefined
+		}
+		pendingContext = undefined
+	}
+
+	return {
+		settled(event) {
+			if (deps.mode() !== "on") return "mode-off"
+			if (event?.aborted && !deps.config.notifyOnAborted) return "aborted"
+			if (!deps.config.onSettled) return "disabled"
+
+			const context = deps.context()
+			if (!context) return "no-context"
+
+			// Debounce: a later settle replaces the earlier one entirely.
+			cancel()
+			pendingContext = context
+			const delay = Math.max(0, deps.config.debounceMs)
+			handle = deps.timers.setTimeout(() => {
+				handle = undefined
+				const pending = pendingContext
+				pendingContext = undefined
+				// The mode can change during the debounce (a `/mailbridge off` typed at t+4s, a
+				// timer firing at t+10s). Scheduling proved nothing about when it fires.
+				if (pending && deps.mode() === "on") void deliver(pending)
+			}, delay)
+			return "scheduled"
+		},
+
+		async flush() {
+			const context = pendingContext
+			cancel()
+			// The same gate the debounce callback applies, for the same reason: the mode can have
+			// been turned off during the window, and a flush must not bypass that.
+			if (context && deps.mode() === "on") await deliver(context)
+		},
+
+		isPending() {
+			return pendingContext !== undefined
+		},
+
+		cancel,
+	}
+}

package/src/core/setup.ts

@@ -0,0 +1,139 @@
+// Setup: address in, runnable config out.
+//
+// Shared by `/mailbridge setup` (inside pi) and `--setup` (headless), so the two
+// entry points cannot drift. It writes the config file and reports what it did;
+// it never starts a process and never prompts.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs"
+import { dirname } from "node:path"
+
+import { shortHostname } from "./config.ts"
+import { buildSetupConfig, discoverDomain, domainOf, type Discovered } from "./discover.ts"
+import { configPath } from "../store/paths.ts"
+
+export interface SetupOptions {
+	address: string
+	/** Where the human reads mail. Defaults to `address` (single-mailbox mode). */
+	to?: string
+	/** Overwrite an existing config. */
+	force?: boolean
+	env?: NodeJS.ProcessEnv
+	fetchImpl?: typeof fetch
+}
+
+export interface SetupResult {
+	ok: boolean
+	/** Human-readable progress, in order. */
+	steps: string[]
+	/** Where the config was written, when it was. */
+	path?: string
+	discovered?: Discovered
+	/** The exact next action, or the reason it failed. */
+	next?: string
+}
+
+export async function runSetup(options: SetupOptions): Promise<SetupResult> {
+	const env = options.env ?? process.env
+	const steps: string[] = []
+	const address = options.address.trim()
+	const to = (options.to ?? address).trim()
+
+	const domain = domainOf(address)
+	if (!domain) return { ok: false, steps: [`not an email address: ${address}`] }
+	if (!domain.includes(".")) {
+		return {
+			ok: false,
+			steps: [`"${domain}" is not a domain — it has no dot`],
+			next: `addresses need a full domain — write something@${domain}.com`,
+		}
+	}
+
+	// The human's address is where every notification goes and the only sender the allowlist
+	// accepts. A typo here is a config that mails nowhere and rejects every reply, so check it
+	// rather than writing it.
+	if (!domainOf(to)) {
+		return { ok: false, steps: [`not an email address: ${to}`], next: "pass `to <your-address>`" }
+	}
+
+	const target = configPath(env)
+	// A device name is an identity, not a mail setting: `force` must not rename the machine,
+	// because records already scanned under the old name would never be offered again.
+	const previousDevice = (() => {
+		try {
+			const parsed = JSON.parse(readFileSync(target, "utf8")) as { device?: { name?: unknown } }
+			const name = parsed?.device?.name
+			return typeof name === "string" && name.trim() ? name.trim() : undefined
+		} catch {
+			return undefined
+		}
+	})()
+
+	if (existsSync(target) && !options.force) {
+		return {
+			ok: false,
+			steps: [`${target} already exists`],
+			path: target,
+			next: "run `/mailbridge setup … force` to overwrite",
+		}
+	}
+
+	steps.push(`discovering ${domain}…`)
+	const discovered = await discoverDomain(domain, options.fetchImpl ? { fetchImpl: options.fetchImpl } : {})
+	if (!discovered) {
+		return {
+			ok: false,
+			steps: [...steps, `no published mail settings for ${domain}`],
+			next: "the domain is not in the autoconfig database; write config.json by hand (config.example.json)",
+		}
+	}
+
+	steps.push(`imap ${discovered.imap.host}:${discovered.imap.port} (${discovered.imap.secure ? "TLS" : "STARTTLS"})`)
+	steps.push(`smtp ${discovered.smtp.host}:${discovered.smtp.port} (${discovered.smtp.secure ? "TLS" : "STARTTLS"})`)
+	steps.push(`auth ${discovered.authType}${discovered.provider !== "other" ? ` (${discovered.provider})` : ""}`)
+
+	const built = buildSetupConfig(address, to, discovered)
+	const config = {
+		...built,
+		device: { name: previousDevice ?? shortHostname() },
+		daemon: { host: "127.0.0.1", port: 4177 },
+		notify: { onSettled: true, debounceMs: 10_000, notifyOnAborted: false },
+		tuning: { idleRenewMs: 25 * 60 * 1000, backoffInitialMs: 1000, backoffMaxMs: 60_000 },
+	}
+
+	mkdirSync(dirname(target), { recursive: true, mode: 0o700 })
+	// Written atomically: an automatic reload can read this file at any moment, and a torn
+	// write parses as {} (readJson falls back to defaults), which would silently replace the
+	// user's config with an empty mailbox.
+	const tmp = `${target}.${process.pid}.tmp`
+	writeFileSync(tmp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 })
+	renameSync(tmp, target)
+	steps.push(`wrote ${target}`)
+
+	if (built.security.allowSelfReplies) {
+		steps.push(`one mailbox for both roles — replies from ${to} are accepted only when they are real replies`)
+		steps.push(
+			"if this mailbox has other addresses that reach it (a QQ number, a foxmail alias), add each " +
+				"one to security.allowFrom - the allowlist matches the exact address you reply from",
+		)
+		steps.push(
+			"if the mailbox already has mail you do not want the agent to read, run /mailbridge prime " +
+				"before your first /mailbridge on",
+		)
+		steps.push(
+			"DMARC checks are off for this shape: a message from your address to the same address is " +
+				"delivered by your own provider and may carry no Authentication-Results header, so requiring " +
+				"one rejects every reply. The sender allowlist and the self-echo guards still apply.",
+		)
+	}
+
+	return {
+		ok: true,
+		steps,
+		path: target,
+		discovered,
+		next:
+			discovered.authType === "XOAUTH2"
+				? "put your app client id in the oauth block, then `/mailbridge auth`"
+				: "put the account app password (QQ/163 call it 授权码) in the mail block, then `/mailbridge smoke`",
+	}
+}