@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/src/core/config.ts

@@ -0,0 +1,373 @@
+// Layered configuration. Later layers win; invalid values are reported rather
+// than thrown, so a typo never takes a session down mid-run.
+
+import { existsSync, readFileSync } from "node:fs"
+import { hostname } from "node:os"
+
+import { configPath } from "../store/paths.ts"
+
+export interface ImapConfig {
+	host: string
+	port: number
+	secure: boolean
+	user: string
+	password: string
+	folder: string
+	/** "XOAUTH2" needs a token command (Outlook). "LOGIN" uses an app password. */
+	authType?: "LOGIN" | "XOAUTH2"
+	/** argv whose stdout is an access token. Required when authType is XOAUTH2. */
+	tokenCommand?: string[]
+	/**
+	 * Folder holding mail we sent. When set, the daemon reads the just-sent copy back and
+	 * records the Message-ID the provider actually delivered - some providers (QQ) replace the
+	 * one we stamp, which silently breaks the reply-chain fallback.
+	 */
+	sentFolder?: string
+}
+
+export interface SmtpConfig {
+	host: string
+	port: number
+	secure: boolean
+	user: string
+	password: string
+	/** "XOAUTH2" needs an OAuth broker; "LOGIN" is a provider app password. */
+	authType?: "LOGIN" | "XOAUTH2"
+	/** argv whose stdout is an access token. Required when authType is XOAUTH2. */
+	tokenCommand?: string[]
+}
+
+export interface ResolvedConfig {
+	mail: { imap: ImapConfig; smtp: SmtpConfig; to: string }
+	/** Who this daemon is: named in settle mails, stored on the routing record. */
+	device: { name: string }
+	/**
+	 * Device-code OAuth2, provider-agnostic. When present it is preferred over
+	 * `tokenCommand` for XOAUTH2, because it refreshes itself and needs no external
+	 * broker. See core/oauth-device.ts.
+	 */
+	oauth?: { issuer: string; clientId: string; clientSecret?: string; scope: string }
+	security: {
+		allowFrom: string[]
+		requireDmarcPass: boolean
+		/** Only AR headers whose authserv-id equals this are trusted. See SECURITY.md §2.1. */
+		trustedAuthservId?: string
+		/**
+		 * Accept a reply whose subject token was lost, by matching `In-Reply-To` /
+		 * `References` against Message-IDs we minted. Default true; see SECURITY.md.
+		 */
+		allowHeaderThreading?: boolean
+		/**
+		 * Allow the pi mailbox and the human to be the same address (one personal
+		 * Hotmail/Gmail account). A self-addressed message still has to be an actual
+		 * reply, i.e. carry In-Reply-To. Default false.
+		 */
+		allowSelfReplies?: boolean
+		tokenTtlHours: number
+	}
+	daemon: {
+		host: string
+		port: number
+		/** Grace period after the last ping before exiting. Default 120. */
+		idleTimeoutSecs?: number
+		/** Safety-net catch-up scan cadence, so a silent IDLE cannot strand a reply. Default 60; 0 disables. */
+		scanIntervalSecs?: number
+	}
+	notify: {
+		onSettled: boolean
+		debounceMs: number
+		notifyOnAborted: boolean
+		/** Total bytes of files attached to one notification, before base64 encoding. */
+		maxAttachmentMb: number
+	}
+	tuning: { idleRenewMs: number; backoffInitialMs: number; backoffMaxMs: number }
+	/** Human-readable problems found while loading; surfaced by `/mailbridge`. */
+	warnings: string[]
+}
+
+/** Marks a warning produced by repairing a malformed section: the config still works. */
+export const REPAIRED_PREFIX = "repaired: "
+
+const DEFAULTS: Omit<ResolvedConfig, "warnings"> = {
+	mail: {
+		imap: { host: "", port: 993, secure: true, user: "", password: "", folder: "INBOX" },
+		smtp: { host: "", port: 465, secure: true, user: "", password: "", authType: "LOGIN" },
+		to: "",
+	},
+	device: { name: "" }, // resolved below: hostname() unless configured
+	security: {
+		allowFrom: [],
+		requireDmarcPass: true,
+		allowHeaderThreading: true,
+		allowSelfReplies: false,
+		tokenTtlHours: 30 * 24,
+	},
+	daemon: { host: "127.0.0.1", port: 4177, idleTimeoutSecs: 120, scanIntervalSecs: 60 },
+	notify: {
+		onSettled: true,
+		debounceMs: 10_000,
+		notifyOnAborted: false,
+		// 18 MB raw is about 24 MB once base64-encoded, under the 25 MB ceiling that Gmail and
+		// Outlook.com enforce. A provider that allows more (QQ: 50 MB) can raise it.
+		maxAttachmentMb: 18,
+	},
+	tuning: {
+		idleRenewMs: 25 * 60 * 1000,
+		backoffInitialMs: 1000,
+		backoffMaxMs: 60_000,
+	},
+}
+
+function isRecord(v: unknown): v is Record<string, unknown> {
+	return typeof v === "object" && v !== null && !Array.isArray(v)
+}
+
+/** First label of the hostname, lowercased: `dev-box-7.local` -> `dev-box-7`. */
+export function shortHostname(): string {
+	try {
+		const full = hostname().toLowerCase()
+		return full.split(".")[0] || "unknown-device"
+	} catch {
+		return "unknown-device"
+	}
+}
+
+/** Parse a token command from env: JSON array, or comma-separated argv. */
+function parseArgv(raw: string): string[] {
+	const trimmed = raw.trim()
+	if (trimmed.startsWith("[")) {
+		try {
+			const parsed = JSON.parse(trimmed)
+			if (Array.isArray(parsed)) return parsed.map(String)
+		} catch {
+			/* fall through to comma splitting */
+		}
+	}
+	return trimmed
+		.split(",")
+		.map((s) => s.trim())
+		.filter(Boolean)
+}
+
+/** Shallow-by-section merge: enough for this config shape, and predictable. */
+function merge(base: any, over: any): any {
+	if (!isRecord(base) || !isRecord(over)) return over ?? base
+	const out: Record<string, unknown> = { ...base }
+	for (const [k, v] of Object.entries(over)) {
+		out[k] = isRecord(v) && isRecord(base[k]) ? merge(base[k], v) : v
+	}
+	return out
+}
+
+function readJson(path: string, warnings: string[]): Record<string, unknown> {
+	if (!existsSync(path)) return {}
+	try {
+		const parsed = JSON.parse(readFileSync(path, "utf8"))
+		return isRecord(parsed) ? parsed : {}
+	} catch (error) {
+		warnings.push(`${path}: ${(error as Error).message}`)
+		return {}
+	}
+}
+
+function envOverrides(env: NodeJS.ProcessEnv): Record<string, unknown> {
+	const o: Record<string, unknown> = {}
+	const set = (path: string[], value: unknown) => {
+		if (value === undefined) return
+		let cur = o
+		for (const key of path.slice(0, -1)) {
+			cur[key] ??= {}
+			cur = cur[key] as Record<string, unknown>
+		}
+		cur[path[path.length - 1]!] = value
+	}
+	set(["mail", "imap", "host"], env.PI_MAILBRIDGE_IMAP_HOST)
+	set(["mail", "imap", "user"], env.PI_MAILBRIDGE_IMAP_USER)
+	set(["mail", "imap", "password"], env.PI_MAILBRIDGE_IMAP_PASS)
+	set(["mail", "smtp", "host"], env.PI_MAILBRIDGE_SMTP_HOST)
+	set(["mail", "smtp", "user"], env.PI_MAILBRIDGE_SMTP_USER)
+	set(["mail", "smtp", "password"], env.PI_MAILBRIDGE_SMTP_PASS)
+	set(["mail", "to"], env.PI_MAILBRIDGE_TO)
+	set(["daemon", "port"], env.PI_MAILBRIDGE_PORT)
+	set(["device", "name"], env.PI_MAILBRIDGE_DEVICE)
+	// Token commands are argv lists; accept JSON or a comma-separated argv.
+	if (env.PI_MAILBRIDGE_IMAP_TOKEN_CMD) set(["mail", "imap", "tokenCommand"], parseArgv(env.PI_MAILBRIDGE_IMAP_TOKEN_CMD))
+	if (env.PI_MAILBRIDGE_SMTP_TOKEN_CMD) set(["mail", "smtp", "tokenCommand"], parseArgv(env.PI_MAILBRIDGE_SMTP_TOKEN_CMD))
+	return o
+}
+
+export function loadConfig(env: NodeJS.ProcessEnv = process.env): ResolvedConfig {
+	const warnings: string[] = []
+	let cfg: any = DEFAULTS
+	cfg = merge(cfg, readJson(configPath(env), warnings))
+	cfg = merge(cfg, envOverrides(env))
+	const resolved: ResolvedConfig = { ...cfg, warnings }
+
+	// Every check below dereferences these sections, and loadConfig's contract is that it never
+	// throws. A JSON `null` is not a record, and the env merge runs after the file merge - so a
+	// null section can come back as a *partial* record (e.g. `{"daemon": null}` plus
+	// A daemon env var over a null section leaves a record with no host and no port, which would bind an
+	// ephemeral port and drop the single-instance guard). Repair by filling the defaults
+	// underneath whatever survived, rather than replacing it.
+	const sections = resolved as unknown as Record<string, unknown>
+	for (const key of Object.keys(DEFAULTS) as (keyof typeof DEFAULTS)[]) {
+		const section = sections[key]
+		const defaults = DEFAULTS[key] as Record<string, unknown>
+		if (!isRecord(section)) {
+			warnings.push(`${REPAIRED_PREFIX}${key} must be an object — using the defaults`)
+			sections[key] = structuredClone(defaults)
+			continue
+		}
+		const repaired: Record<string, unknown> = { ...defaults, ...section }
+		// The schema nests exactly one level (mail.imap, mail.smtp).
+		for (const [sub, subDefaults] of Object.entries(defaults)) {
+			if (!isRecord(subDefaults)) continue
+			const value = section[sub]
+			if (!isRecord(value)) {
+				warnings.push(`${REPAIRED_PREFIX}${key}.${sub} must be an object — using the defaults`)
+				repaired[sub] = structuredClone(subDefaults)
+			} else {
+				repaired[sub] = { ...subDefaults, ...value }
+			}
+		}
+		sections[key] = repaired
+	}
+
+	// Device identity: a short, stable name so a notification says which machine
+	// the session is on. Hostname is the sensible default; it can be overridden
+	// when hostnames are opaque (e.g. `dev-box-7`).
+	const configuredDevice = String(resolved.device?.name ?? "").trim()
+	resolved.device = { name: configuredDevice || shortHostname() }
+
+	// Validation that must not throw in-process.
+	// allowFrom is checked with .length below, which a string also satisfies - and then
+	// every message throws in the allowlist check, killing the scan silently forever.
+	const rawAllow: unknown = resolved.security?.allowFrom
+	if (!Array.isArray(rawAllow)) {
+		warnings.push("security.allowFrom must be an array of addresses — ignoring it (fail closed)")
+		resolved.security = { ...resolved.security, allowFrom: [] }
+	} else {
+		resolved.security = { ...resolved.security, allowFrom: rawAllow.map((v) => String(v).trim()).filter(Boolean) }
+	}
+
+	// A quoted or non-numeric delay silently disables debouncing (setTimeout coerces it).
+	const rawDebounce: unknown = resolved.notify?.debounceMs
+	const debounce = typeof rawDebounce === "number" ? rawDebounce : Number.NaN
+	if (!Number.isFinite(debounce) || debounce < 0) {
+		if (rawDebounce !== undefined) warnings.push("notify.debounceMs must be a non-negative number — using 10000")
+		resolved.notify = { ...resolved.notify, debounceMs: 10_000 }
+	}
+
+	// `listen("abc")` is a UNIX socket path in Node, and a float is not a port. The env var is
+	// documented, and injected as a string, so coerce it rather than trusting it.
+	const rawPort: unknown = resolved.daemon.port
+	const port = typeof rawPort === "number" ? rawPort : Number(rawPort)
+	if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+		if (rawPort !== undefined) warnings.push("daemon.port must be an integer 1-65535 — using 4177")
+		resolved.daemon = { ...resolved.daemon, port: 4177 }
+	} else {
+		resolved.daemon = { ...resolved.daemon, port }
+	}
+
+	// Attachments are encoded ~4/3, and an over-limit send fails at the provider with the whole
+	// notification lost. Keep the default under the 25 MB Gmail/Outlook ceiling; cap the ceiling
+	// at what the largest common provider (QQ: 50 MB) accepts.
+	const rawMaxMb: unknown = resolved.notify.maxAttachmentMb
+	if (rawMaxMb !== undefined) {
+		const mb = typeof rawMaxMb === "number" ? rawMaxMb : Number.NaN
+		if (!Number.isFinite(mb) || mb < 1 || mb > 45) {
+			warnings.push("notify.maxAttachmentMb must be a number between 1 and 45 — using 18")
+			resolved.notify = { ...resolved.notify, maxAttachmentMb: 18 }
+		} else {
+			resolved.notify = { ...resolved.notify, maxAttachmentMb: mb }
+		}
+	}
+
+	// A zero or NaN idle timeout makes the daemon exit ~1 s after the first ping, which looks
+	// like a crash-loop; a NaN token TTL makes a route never expire. Both fail closed. The floor
+	// is 3x the session poll interval: a timeout shorter than the ping period reaps the daemon
+	// between ticks, so it would flap instead of serving.
+	const rawIdle: unknown = resolved.daemon.idleTimeoutSecs
+	const idle = typeof rawIdle === "number" ? rawIdle : Number.NaN
+	if (!Number.isFinite(idle) || idle < 30) {
+		if (rawIdle !== undefined) {
+			warnings.push("daemon.idleTimeoutSecs must be at least 30 (three poll intervals) — using 120")
+		}
+		resolved.daemon = { ...resolved.daemon, idleTimeoutSecs: 120 }
+	}
+
+	const rawTtl: unknown = resolved.security.tokenTtlHours
+	const ttl = typeof rawTtl === "number" ? rawTtl : Number.NaN
+	if (!Number.isFinite(ttl) || ttl < 1) {
+		if (rawTtl !== undefined) warnings.push("security.tokenTtlHours must be a positive number — using 720")
+		resolved.security = { ...resolved.security, tokenTtlHours: 30 * 24 }
+	}
+
+	// A negative, null or non-numeric interval would silently disable the safety net.
+	// `Number(null)` is 0, which would read as "the user disabled the sweep" — only a real
+	// number counts.
+	const rawInterval: unknown = resolved.daemon.scanIntervalSecs
+	if (rawInterval !== undefined) {
+		const n = typeof rawInterval === "number" ? rawInterval : Number.NaN
+		if (!Number.isFinite(n) || n < 0) {
+			warnings.push("daemon.scanIntervalSecs must be a non-negative number — using 60")
+			resolved.daemon = { ...resolved.daemon, scanIntervalSecs: 60 }
+		} else {
+			resolved.daemon = { ...resolved.daemon, scanIntervalSecs: n }
+		}
+	}
+
+	const imap = resolved.mail.imap
+	if (!imap.host || !imap.user) warnings.push("mail.imap.host and mail.imap.user are required")
+	if (!resolved.mail.to) warnings.push("mail.to is required")
+	// Setup validates this now; a hand-edited config still can be a typo, and every notification
+	// would go nowhere while the daemon reported itself healthy.
+	else if (!String(resolved.mail.to).includes("@")) {
+		warnings.push("mail.to does not look like an email address — notifications cannot be delivered")
+	}
+	if (resolved.security.allowFrom.length === 0) {
+		warnings.push("security.allowFrom is empty — every sender will be rejected (fail closed)")
+	}
+	// An unset authserv-id is a legitimate configuration now: authorization falls
+	// back to the topmost Authentication-Results header. Reported as a note by
+	// `--check`, not as a warning, because it is not a problem. Never a hard failure.
+	// XOAUTH2 needs exactly one token source: a built-in device-code flow or a command.
+	for (const side of ["imap", "smtp"] as const) {
+		const account = resolved.mail[side]
+		if (account.authType !== "XOAUTH2") continue
+		const hasCommand = Boolean(account.tokenCommand?.length)
+		const hasOAuth = Boolean(resolved.oauth?.issuer && resolved.oauth?.clientId)
+		if (!hasCommand && !hasOAuth) {
+			warnings.push(
+				`mail.${side}.authType is XOAUTH2 but neither mail.${side}.tokenCommand nor oauth.issuer/oauth.clientId is set`,
+			)
+		}
+		if (hasOAuth && /(partner\.microsoftonline\.cn|chinacloudapi\.cn)/i.test(resolved.oauth?.issuer ?? "")) {
+			warnings.push(
+				"oauth.issuer points at the Azure China (21Vianet) sovereign cloud — apps registered there cannot authenticate against global Outlook.com; use login.microsoftonline.com",
+			)
+		}
+		if (hasOAuth && !/\boffline_access\b/.test(resolved.oauth?.scope ?? "")) {
+			warnings.push("oauth.scope should include offline_access, otherwise no refresh token is issued")
+		}
+		if (account.password) {
+			warnings.push(`mail.${side}.password is set but authType is XOAUTH2 — the password will be ignored`)
+		}
+	}
+
+	// A LOGIN account with no password cannot authenticate, and saying "config ok"
+	// in that state sends the user straight into a confusing smoke failure.
+	for (const side of ["imap", "smtp"] as const) {
+		const account = resolved.mail[side]
+		if (account.authType !== "XOAUTH2" && !account.password) {
+			warnings.push(
+				`mail.${side}.password is empty — paste the provider's app password there (QQ/163 call it 授权码)`,
+			)
+		}
+	}
+	return resolved
+}
+
+export function hasUsableMailConfig(c: ResolvedConfig): boolean {
+	return Boolean(c.mail.imap.host && c.mail.imap.user && c.mail.smtp.host && c.mail.to)
+}

package/src/core/deliveries.ts

@@ -0,0 +1,233 @@
+// Delivery runner — the extension side of claim → inject → ack.
+//
+// Invariants, in order of importance:
+//
+//   1. Never inject a delivery for another session. The token already routed it;
+//      this is the second check, and it is cheap.
+//   2. Never ack a delivery that was not injected. Acking early would mark the
+//      mail seen and drop the record, losing the human's reply.
+//   3. Never inject the same UID twice *in this process*, even if the ack failed
+//      — a reconnect replays /pending, and a duplicate injection is worse than a
+//      stale seen-flag.
+//   4. A failed claim (another instance owns it) is not an error: leave it alone.
+//
+// The runner is deliberately synchronous-per-delivery: mail replies are serial and
+// ordering them keeps the transcript readable.
+
+import type { PendingRecord } from "../store/pending-store.ts"
+
+/** The daemon calls this runner needs. `createDaemonClient` satisfies it. */
+export type ClientResult<T> = { ok: true; data: T } | { ok: false; status: number; code?: string }
+
+export interface DeliveryClient {
+	claim(uid: number, instanceId: string, uidValidity?: number): Promise<ClientResult<{ ok: boolean }>>
+	ack(uid: number, instanceId: string, sessionId?: string, uidValidity?: number): Promise<ClientResult<{ ok: boolean }>>
+	pending(): Promise<ClientResult<{ pending: PendingRecord[] }>>
+}
+
+export type DeliveryOutcome =
+	| "injected"
+	| "already-injected"
+	| "foreign-session"
+	| "claimed-by-other"
+	| "inject-failed"
+	| "claim-unconfirmed"
+	| "stale-space"
+	| "foreign-device"
+	| "not-found"
+
+export interface DeliveryRunnerDeps {
+	client: DeliveryClient
+	/** Stable id for this pi process; the daemon uses it for claim exclusivity. */
+	instanceId: string
+	/** Current session id, or undefined when there is no session. */
+	sessionId: () => string | undefined
+	/** Inject into the live session. Throw to signal failure (do not ack). */
+	inject: (body: string, record: PendingRecord) => Promise<void>
+	onError?: (error: Error, record: PendingRecord) => void
+	/**
+	 * Is delivery still wanted? Checked between records, so `/mailbridge off` arriving as a
+	 * reply stops the batch it came in: the records behind it stay pending (unclaimed, unseen)
+	 * and are delivered when the mode goes back on, instead of landing in a session the human
+	 * just asked to leave alone.
+	 */
+	stillDelivering?: () => boolean
+}
+
+export interface DeliveryRunner {
+	handle(record: PendingRecord): Promise<DeliveryOutcome>
+	/** Replay everything the daemon still holds. Used on connect and reconnect. */
+	drain(): Promise<DeliveryOutcome[]>
+	/** Test/diagnostic: uids injected by this runner. */
+	injectedUids(): number[]
+}
+
+/** In-flight drains, shared across runner instances in this process. */
+const inFlightByInstance = new Map<string, Promise<DeliveryOutcome[]>>()
+
+/**
+ * UIDs already injected, per instance.
+ *
+ * Per instance, not per runner object: a rebuilt runtime (a respawn, or a new session in
+ * the same pi process after session_shutdown) constructs a new runner while the claim key -
+ * the pid - stays the same. A per-runner set let the rebuilt runner re-inject a reply whose
+ * ack had failed, which is the one failure this design cannot undo.
+ */
+const injectedByInstance = new Map<string, Set<string>>()
+/** A process has one instanceId; this only guards against a pathological caller. */
+const MAX_INSTANCE_SETS = 8
+/** Cap per instance, like the journal: one key per injected message, oldest dropped. */
+const MAX_INJECTED_PER_INSTANCE = 5_000
+
+/** UIDs are only unique within a UIDVALIDITY, so the key must carry it. */
+function injectionKey(record: { uid: number; uidValidity?: number }): string {
+	return `${record.uidValidity ?? ""}:${record.uid}`
+}
+
+function injectedFor(instanceId: string): Set<string> {
+	let set = injectedByInstance.get(instanceId)
+	if (!set) {
+		set = new Set<string>()
+		injectedByInstance.set(instanceId, set)
+		if (injectedByInstance.size > MAX_INSTANCE_SETS) {
+			const oldest = injectedByInstance.keys().next().value
+			// Never evict the caller's own set: losing it would let this instance re-inject.
+			if (oldest !== undefined && oldest !== instanceId) injectedByInstance.delete(oldest)
+		}
+	}
+	return set
+}
+
+export function createDeliveryRunner(deps: DeliveryRunnerDeps): DeliveryRunner {
+	/** Stale-space refusals already reported, so a stuck record does not log every poll. */
+	const reported = new Set<string>()
+	const injected = (): Set<string> => injectedFor(deps.instanceId)
+
+	async function handle(record: PendingRecord): Promise<DeliveryOutcome> {
+		if (injected().has(injectionKey(record))) {
+			// Injected earlier but possibly not acked: a single failed /ack used to pin the
+			// record for the process lifetime, leaking a queue slot, leaving \Seen unset and
+			// the journal unwritten - and after a restart (new pid, new instance) the same
+			// instruction would be injected again. The ack is idempotent, so retry it.
+			try {
+				const retried = await deps.client.ack(record.uid, deps.instanceId, record.sessionId, record.uidValidity)
+				// A retry that keeps failing is the same silent leak as a first ack that
+				// failed: surface it rather than looping quietly.
+				if (!retried.ok && retried.status !== 404) {
+					deps.onError?.(new Error(`ack retry failed (${retried.code ?? retried.status})`), record)
+				}
+			} catch (error) {
+				deps.onError?.(error instanceof Error ? error : new Error(String(error)), record)
+			}
+			return "already-injected"
+		}
+
+		const mine = deps.sessionId()
+		if (!mine || record.sessionId !== mine) return "foreign-session"
+
+		const claim = await deps.client.claim(record.uid, deps.instanceId, record.uidValidity)
+		if (!claim.ok) {
+			// Expected when another instance won the race; the daemon answers 409.
+			if (claim.code === "claimed-by-other") return "claimed-by-other"
+			// The record belongs to a UID numbering the mailbox has left. It cannot be delivered
+			// and is dropped at the next connect; say so once rather than retrying in silence
+			// every poll tick.
+			if (claim.code === "stale-space") {
+				const key = injectionKey(record)
+				if (!reported.has(key)) {
+					reported.add(key)
+					deps.onError?.(new Error("reply belongs to an earlier UID space; it will be dropped"), record)
+				}
+				return "stale-space"
+			}
+			// A record this daemon does not own (another machine's, or one stamped under a
+			// device name that has since changed) cannot be delivered by retrying. Say it once:
+			// silence here is how a queued reply is lost without a trace.
+			if (claim.code === "foreign-device") {
+				const key = injectionKey(record)
+				if (!reported.has(key)) {
+					reported.add(key)
+					deps.onError?.(
+						new Error("reply was scanned under another device name; it will not be delivered here"),
+						record,
+					)
+				}
+				return "foreign-device"
+			}
+			// Only a definite 404 means the record is gone. Anything else - a timeout, a
+			// network error, a rotated secret (401) - leaves the outcome unknown, and calling
+			// that "not-found" is the same lie in a different costume. It self-heals (the
+			// claim TTL expires, the next drain re-claims), but the diagnostic must not mislead.
+			if (claim.status === 404) return "not-found"
+			return "claim-unconfirmed"
+		}
+
+		try {
+			await deps.inject(record.body, record)
+		} catch (error) {
+			// Do NOT ack: the delivery must stay pending so it is retried.
+			deps.onError?.(error instanceof Error ? error : new Error(String(error)), record)
+			return "inject-failed"
+		}
+
+		// Record before acking: if the ack fails we still refuse to inject twice.
+		const set = injected()
+		set.add(injectionKey(record))
+		// Bounded like the journal. Evicting an entry whose ack never landed would let it be
+		// injected again, so this is a last resort, not a free trade.
+		while (set.size > MAX_INJECTED_PER_INSTANCE) {
+			const oldest = set.values().next().value
+			if (oldest === undefined) break
+			set.delete(oldest)
+		}
+
+		try {
+			const ackResult = await deps.client.ack(record.uid, deps.instanceId, record.sessionId, record.uidValidity)
+			if (!ackResult.ok) {
+				// Injected but not acked: the record will be re-offered on reconnect and
+				// the `injected` set will absorb it. Surface it — a silent ack failure
+				// hides a growing pending queue.
+				deps.onError?.(new Error(`ack failed (${ackResult.code ?? ackResult.status})`), record)
+			}
+		} catch (error) {
+			// Injected but not acked: same handling as above.
+			deps.onError?.(error instanceof Error ? error : new Error(String(error)), record)
+		}
+
+		return "injected"
+	}
+
+	return {
+		handle,
+		injectedUids: () => [...injected()].map((key) => Number(key.split(":")[1])),
+
+		async drain() {
+			// One drain at a time. The claim registry is keyed per pid, so two overlapping
+			// drains in this process would both be granted the same uid and inject twice -
+			// and a duplicate injection cannot be undone.
+			// Keyed by instanceId, not by this runner object: a respawn builds a new runner
+			// while the claim key (the pid) stays the same, so a per-object flag would let an
+			// old runner's drain overlap a new one's.
+			const running = inFlightByInstance.get(deps.instanceId)
+			if (running) return running
+			const attempt = (async () => {
+				try {
+					const result = await deps.client.pending()
+					if (!result.ok) return []
+					const outcomes: DeliveryOutcome[] = []
+					for (const record of result.data.pending) {
+						// Re-checked every record: a reply that turns the mode off is in this very
+						// batch, and everything after it must wait.
+						if (deps.stillDelivering && !deps.stillDelivering()) break
+						outcomes.push(await handle(record))
+					}
+					return outcomes
+				} finally {
+					inFlightByInstance.delete(deps.instanceId)
+				}
+			})()
+			inFlightByInstance.set(deps.instanceId, attempt)
+			return attempt
+		},
+	}
+}