@dumbmice/pi-mailbridge 0.0.0-stage → 0.1.0

package/dist/extension.js

@@ -0,0 +1,1233 @@
+// pi-mailbridge — pi extension entry.
+//
+// Everything here runs INSIDE the agent process. The mailbox is not touched: the
+// daemon owns IMAP, and this file talks to it over loopback.
+//
+// Dependencies are injectable so the registration surface (which events, which
+// commands, which tools) and the settle behaviour can be asserted with a fake
+// `pi`, no daemon and no mailbox.
+import { statSync } from "node:fs";
+import { Type } from "@sinclair/typebox";
+import { loadConfig, hasUsableMailConfig } from "./core/config.js";
+import { shouldReloadConfig } from "./core/config-freshness.js";
+import { configPath } from "./store/paths.js";
+import { ensureSecret, readSecret } from "./store/secret.js";
+import { formatScan } from "./core/status.js";
+import { createSettleNotifier } from "./core/settle.js";
+import { createDeliveryRunner } from "./core/deliveries.js";
+import { toUserContent } from "./core/attachments.js";
+import { parseMailCommand } from "./core/mail-command.js";
+import { API_VERSION, apiCompatible } from "./daemon/api.js";
+import { probeHealth, probeHealthDetail } from "./daemon/spawn.js";
+import { resolveDaemonScript } from "./daemon/script.js";
+import { daemonBaseUrl, ensureDaemon, createDaemonClient } from "./daemon/spawn.js";
+import { parseMailbridgeCommand, USAGE } from "./core/commands.js";
+import { runSetup } from "./core/setup.js";
+import { runSmoke } from "./core/smoke.js";
+import { buildTokenProvider } from "./core/token-source.js";
+import { createOpenidClient } from "./core/oauth-openid.js";
+import { createDeviceCodeProvider } from "./core/oauth-device.js";
+import { fileTokenStore } from "./store/oauth-store.js";
+import { ensureRouteForSession, registerRoute } from "./store/routes.js";
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+const POLL_MS = 10_000;
+/** How often the poll may try to start a dead daemon. */
+const RESPAWN_BACKOFF_MS = 60_000;
+/** How often to ask a healthy daemon which build it is. */
+const VERSION_CHECK_MS = 60_000;
+const defaultTimers = {
+    setTimeout: (handler, ms) => setTimeout(handler, ms),
+    clearTimeout: (handle) => clearTimeout(handle),
+};
+export default function mailbridge(pi, deps = {}) {
+    const env = deps.env ?? process.env;
+    const load = deps.loadConfig ?? (() => loadConfig(env));
+    let config = load();
+    /** The address the current client was built with; may lag `config` after a port edit. */
+    let clientBase;
+    const secretFn = deps.secret ?? (() => readSecret(env));
+    const timers = deps.timers ?? defaultTimers;
+    const pollMs = deps.pollMs ?? POLL_MS;
+    let ctx;
+    /** Set by stopPolling(): a tick already in flight must not touch the daemon. */
+    let pollPaused = false;
+    /** The tick that may be inside an await right now; see trackTick/settleTick. */
+    let tickInFlight;
+    let client;
+    let runner;
+    let pollHandle;
+    let notifier;
+    /** Mirror of the daemon's global mode. Default off: never mail unprompted. */
+    let emailMode = "off";
+    /** Stable id for this pi process, used for claims and for liveness pings. */
+    const instanceId = `pi-${process.pid}`;
+    /** Throttle for respawning a daemon that exited for idleness. */
+    let lastRespawnAttempt = 0;
+    /** Throttles the post-update daemon replacement; a failed respawn must not loop. */
+    let lastVersionCheck = 0;
+    /** Set when the daemon rejects our bearer: said once, not every poll tick. */
+    let tokenRejected = false;
+    /** Set when a respawn still spoke another protocol: only a new pi session can fix that. */
+    let protocolStuck = false;
+    // Computed per use, not once: `config` is replaced whenever a /mailbridge command
+    // reloads it, and a frozen URL means editing daemon.port leaves every probe (including
+    // /mailbridge restart, the documented remedy) dialling the old port forever.
+    const currentBaseUrl = () => daemonBaseUrl(config.daemon.port, config.daemon.host);
+    /**
+     * Last assistant text and turn count from the session branch.
+     *
+     * Without this the notification body is just a placeholder — and the point of the
+     * email is to read the answer from whatever device you happen to be on. Branch
+     * entries are `{ type: "message", message: { role, content } }`; assistant
+     * content is `(TextContent | ThinkingContent | ToolCall)[]`, so only `text`
+     * parts are joined (thinking and tool calls are not the answer).
+     */
+    function readSessionSnapshot(manager) {
+        const branch = manager.getBranch?.() ?? [];
+        let lastAssistantText;
+        let turns = 0;
+        for (let i = branch.length - 1; i >= 0; i--) {
+            const entry = branch[i];
+            if (entry?.type !== "message" || entry.message?.role !== "assistant")
+                continue;
+            turns++;
+            if (lastAssistantText)
+                continue;
+            const content = entry.message.content;
+            if (typeof content === "string" && content.trim()) {
+                lastAssistantText = content.trim();
+                continue;
+            }
+            if (!Array.isArray(content))
+                continue;
+            const text = content
+                .filter((part) => {
+                const p = part;
+                return p?.type === "text" && typeof p.text === "string";
+            })
+                .map((part) => part.text)
+                .join("\n")
+                .trim();
+            if (text)
+                lastAssistantText = text;
+        }
+        return { ...(lastAssistantText ? { lastAssistantText } : {}), ...(turns > 0 ? { turns } : {}) };
+    }
+    function sessionContext() {
+        if (!ctx)
+            return undefined;
+        const sessionId = ctx.sessionManager.getSessionId();
+        // `getSessionName()` is the documented method; `getName` never existed.
+        const name = ctx.sessionManager.getSessionName?.() ?? ctx.sessionManager.getName?.();
+        return {
+            sessionId,
+            ...(name ? { sessionName: name } : {}),
+            device: config.device.name,
+            cwd: ctx.cwd,
+            ...readSessionSnapshot(ctx.sessionManager),
+        };
+    }
+    /**
+     * Park the loop.
+     *
+     * Clearing the timer is not enough on its own: a tick that entered just before this call is
+     * already inside `tick()`, and it would find the daemon this command is stopping, respawn it,
+     * and manufacture the "still answering" evidence the command is measuring. The flag makes a
+     * tick in flight a no-op.
+     */
+    function stopPolling() {
+        pollPaused = true;
+        if (pollHandle !== undefined) {
+            timers.clearTimeout(pollHandle);
+            pollHandle = undefined;
+        }
+    }
+    function startPolling() {
+        stopPolling();
+        pollPaused = false;
+        schedulePoll();
+    }
+    /**
+     * Start a tick, and remember it while it runs.
+     *
+     * A pause cannot stop a tick that is already inside an await - and one of those awaits spawns
+     * a daemon. The command that parks the loop waits for the tick it interrupted instead, so the
+     * daemon that tick started is on the port before the command looks at it.
+     */
+    function trackTick(running) {
+        tickInFlight = running;
+        // `.then(clear, clear)`: a rejecting tick must not surface as an unhandled rejection.
+        void running.then(() => {
+            if (tickInFlight === running)
+                tickInFlight = undefined;
+        }, () => {
+            if (tickInFlight === running)
+                tickInFlight = undefined;
+        });
+    }
+    /**
+     * Wait for an interrupted tick, bounded. Returns true when the budget ran out first.
+     *
+     * The budget has to exceed what a tick can spend inside `ensureDaemon` (a spawn, then probes
+     * for `waitMs`), or the join expires exactly in the window it exists to cover. The timer is
+     * cleared and uses the injected clock: a leaked five-second timer per command would keep the
+     * process alive for nothing.
+     */
+    async function settleTick() {
+        const running = tickInFlight;
+        if (running === undefined)
+            return false;
+        // A real timer, not the injected (fake) clock: it bounds a wait on another promise, so
+        // nothing else can resolve it. Cleared below, so it never outlives the command.
+        let handle;
+        const expired = new Promise((resolve) => {
+            handle = setTimeout(() => resolve(true), deps.joinTickMs ?? 8_000);
+        });
+        try {
+            return await Promise.race([running.then(() => false), expired]);
+        }
+        finally {
+            if (handle !== undefined)
+                clearTimeout(handle);
+        }
+    }
+    /**
+     * Arm the timer without touching `pollPaused`.
+     *
+     * For callers inside an await - `replaceOutdatedDaemon` runs within a command that parked the
+     * loop, and clearing the pause there would un-park it from underneath.
+     */
+    function schedulePoll() {
+        const tick = async () => {
+            if (pollPaused)
+                return;
+            try {
+                // Heartbeat: the daemon exits when every session stops pinging, so a quiet
+                // daemon is a stopping daemon.
+                const ping = client ? await client.ping(instanceId) : undefined;
+                // Checked again after the await: a tick that entered before `stopPolling()` was
+                // suspended right here, and with the client nulled by the command it would read as
+                // "dead daemon" and respawn inside the wait that is measuring the port.
+                if (pollPaused)
+                    return;
+                if (!client || (ping && !ping.ok)) {
+                    // No client is not only "dead daemon": it can also be "a daemon on another
+                    // protocol that this session never managed to replace". Only the no-client case
+                    // is checked here - with a live client, a failed ping means it is gone, and the
+                    // protocol is the else-branch's business.
+                    if (!client && (await replaceOutdatedDaemon()))
+                        return;
+                    if (pollPaused)
+                        return;
+                    // The daemon exited for idleness (or crashed). Nothing else would bring it
+                    // back for this session, so the poll becomes the supervisor.
+                    const now = Date.now();
+                    if (now - lastRespawnAttempt > (deps.respawnBackoffMs ?? RESPAWN_BACKOFF_MS)) {
+                        lastRespawnAttempt = now;
+                        const healthy = await ensureDaemonSafe();
+                        // The spawn itself can take seconds. A paused tick that returns here has
+                        // already created the daemon the restart is about to measure.
+                        if (pollPaused)
+                            return;
+                        if (healthy) {
+                            // A settle waiting on its debounce is the one mail this product exists
+                            // to send. startRuntime() rebuilds the notifier, so flush the old one
+                            // after the client is live again - never cancel it.
+                            await replaceRuntime();
+                        }
+                    }
+                    // Fall through to the reschedule below: returning here is what stopped the
+                    // poll loop permanently after a single failed ping.
+                }
+                else {
+                    // After `pi update` the daemon can still be running the previous build: it
+                    // mints nothing and resolves nothing, so every reply after the upgrade would
+                    // be rejected with the cursor already past it. Replace it once the build
+                    // differs, throttled so a failing respawn cannot loop.
+                    if (await replaceOutdatedDaemon())
+                        return;
+                    if (pollPaused)
+                        return;
+                    const mode = await client?.mode();
+                    if (pollPaused)
+                        return;
+                    if (mode?.ok)
+                        emailMode = mode.data.mode === "on" ? "on" : "off";
+                    // `/mailbridge off` closes the channel: no claim, no injection while it is off.
+                    // Anything already queued stays pending and is delivered on the next
+                    // `on`, which is why the docs say so explicitly.
+                    if (emailMode === "on")
+                        await runner?.drain();
+                }
+            }
+            catch {
+                /* drain already swallows; a poll must never throw into the runtime */
+            }
+            finally {
+                // Re-arm whenever this session is alive - not only when a runner exists: a
+                // daemon replacement clears the runner for a moment, and tying the loop to it
+                // stopped polling exactly when the daemon was missing.
+                if (ctx && pollHandle === undefined && !pollPaused) {
+                    pollHandle = timers.setTimeout(() => {
+                        pollHandle = undefined;
+                        trackTick(tick());
+                    }, pollMs);
+                }
+            }
+        };
+        // Clearing first: arming twice leaves the previous handle live and untracked, so both
+        // fire and the next re-arm adds a third. (Unreachable from the two current callers, which
+        // always run with no handle - this keeps it that way if a third appears.)
+        if (pollHandle !== undefined) {
+            timers.clearTimeout(pollHandle);
+            pollHandle = undefined;
+        }
+        pollHandle = timers.setTimeout(() => {
+            pollHandle = undefined;
+            trackTick(tick());
+        }, pollMs);
+    }
+    // ---- lifecycle ---------------------------------------------------------
+    /**
+     * Is the running daemon this build? Returns true when it replaced one.
+     *
+     * The extension and the daemon are separate processes with separate lifetimes: `pi update`
+     * reloads this module while the daemon keeps executing what it started with. A version it
+     * cannot resolve routing ids against is worse than no daemon, because replies are consumed.
+     */
+    async function replaceOutdatedDaemon(known) {
+        // Once a respawn has proved the mismatch is not ours to fix, stop trying.
+        if (protocolStuck)
+            return false;
+        if (Date.now() - lastVersionCheck < (deps.versionCheckMs ?? VERSION_CHECK_MS))
+            return false;
+        lastVersionCheck = Date.now();
+        // No client yet (a fresh session that found a daemon from another install) is exactly the
+        // case this must handle: use what the spawn probe already saw, or ask the daemon directly.
+        // `undefined` means *nothing answered* - the dead-daemon path owns that, and treating it as
+        // a protocol mismatch would "replace" a daemon that is not there instead of respawning it.
+        const health = client ? await client.health() : undefined;
+        let theirs = known?.incompatible ? (known.apiVersion ?? 0) : known?.apiVersion;
+        if (theirs === undefined && health?.ok)
+            theirs = health.data.apiVersion ?? 0;
+        if (theirs === undefined && !client) {
+            // No client and no client to ask: ask the port. `ok:false` (nothing answered) stays
+            // undefined so the dead-daemon path keeps ownership of a daemon that is not there.
+            const found = await probeDetail({ baseUrl: clientBase ?? currentBaseUrl() });
+            if (found.ok)
+                theirs = found.apiVersion ?? 0;
+        }
+        if (theirs === undefined || apiCompatible(API_VERSION, theirs))
+            return false;
+        // The awaits above can take seconds; a command may have parked the loop in the meantime.
+        if (pollPaused)
+            return false;
+        ctx?.ui.notify(`mailbridge: replacing the running daemon (protocol ${theirs ?? "0"} → ${API_VERSION})`, "info");
+        // To stop it we need a client, even if this session has no runtime yet.
+        const stopping = client ?? buildClient();
+        await stopping?.shutdown().catch(() => undefined);
+        client = undefined;
+        runner = undefined;
+        // `/shutdown` answers before it closes the listener, so an immediate probe finds the
+        // dying daemon and "reuses" it - the replacement then reports success while the old
+        // protocol is still being served. Wait for the port to stop answering.
+        await waitForPortToClose(clientBase ?? currentBaseUrl());
+        // Stopped, and parked: the command that parked the loop owns the respawn, and spawning
+        // here would hand it the survivor it is measuring.
+        if (pollPaused)
+            return false;
+        // A failed respawn must not end the poll loop: with `runner` gone, a re-arm tied to it
+        // would stop the only thing that notices the daemon is missing.
+        const ensured = await ensureDaemonDetailed();
+        if (pollPaused)
+            return false;
+        if (!ensured.healthy || !(await replaceRuntime())) {
+            ctx?.ui.notify(ensured.incompatible
+                ? `mailbridge: the daemon is still on protocol ${ensured.apiVersion ?? "0"} (this session: ${API_VERSION}) — /mailbridge restart forces it`
+                : `mailbridge: the daemon did not come back after the update${ensured.error ? ` (${ensured.error})` : ""} — retrying, and /mailbridge restart forces it`, "warning");
+            return true;
+        }
+        // If the respawn brought back another protocol again, this session is older than the
+        // package on disk. Replacing forever would kill the bridge once a minute, silently.
+        const after = await client?.health();
+        if (after?.ok && !apiCompatible(API_VERSION, after.data.apiVersion)) {
+            protocolStuck = true;
+            ctx?.ui.notify(`mailbridge: this pi session speaks protocol ${API_VERSION} and the installed daemon speaks ` +
+                `${after.data.apiVersion ?? "0"} — restart pi to load the matching extension`, "error");
+            return true;
+        }
+        schedulePoll();
+        return true;
+    }
+    const probe = deps.probeHealth ?? probeHealth;
+    const probeDetail = deps.probeHealthDetail ??
+        (deps.probeHealth
+            ? async (options) => 
+            // A seam that only says "something answers" cannot also say "and it is protocol 0",
+            // so it means the protocol this build speaks - otherwise every such stub looks
+            // like an outdated daemon and gets shut down.
+            ({ ok: await deps.probeHealth(options), apiVersion: API_VERSION })
+            : probeHealthDetail);
+    // The pi manifest points at this TypeScript file inside the installed package, so the daemon
+    // beside it must be the compiled build wherever one exists (Node refuses type stripping in
+    // node_modules). See daemon/script.ts.
+    const daemonScript = () => resolveDaemonScript(import.meta.url);
+    /**
+     * Wait for the listener to close, bounded, and report whether something still answers.
+     *
+     * `/shutdown` answers before it closes: the handler releases the lock, stops the watcher and
+     * logs out of IMAP first, so a wedged connection keeps `/health` alive well past the reply.
+     * The return value is the *last* probe, so a caller does not ask a second time.
+     */
+    async function waitForPortToClose(base) {
+        const deadline = Date.now() + (deps.stopWaitMs ?? 5_000);
+        while (Date.now() < deadline && (await probe({ baseUrl: base }))) {
+            await new Promise((resolve) => setTimeout(resolve, 100));
+        }
+        return probe({ baseUrl: base });
+    }
+    /**
+     * Build the client, notifier and delivery runner. Called on session_start and again
+     * if the poll tick finds the daemon gone, so a session recovers without a reload.
+     */
+    /**
+     * Rebuild the runtime, carrying a debounced settle across the gap.
+     *
+     * Every replacement path (dead daemon, version mismatch, /mailbridge restart) needs the same
+     * three steps, and each used to do them itself - which is why the same dropped-notification
+     * bug had to be fixed three times. It lives here now.
+     */
+    async function replaceRuntime() {
+        const stale = notifier;
+        notifier = undefined;
+        if (!(await startRuntime()))
+            return false;
+        await stale?.flush().catch(() => undefined);
+        return true;
+    }
+    /** A client for the current base URL, or undefined when there is no secret yet. */
+    function buildClient(secret = secretFn()) {
+        if (!secret)
+            return undefined;
+        const token = secret.toString("base64url");
+        const makeClient = deps.makeClient ??
+            ((base, tok) => createDaemonClient({ baseUrl: base, token: tok, device: config.device.name }));
+        return makeClient(clientBase ?? currentBaseUrl(), token);
+    }
+    async function startRuntime() {
+        const current = ctx;
+        if (!current)
+            return false;
+        const secret = secretFn();
+        if (!secret)
+            return false;
+        clientBase = currentBaseUrl();
+        client = buildClient(secret);
+        if (!client)
+            return false;
+        const active = client;
+        const initialMode = await active.mode();
+        // A session_shutdown can land during that await. Without this the runtime is rebuilt
+        // around a dead ctx: the poll keeps pinging and the daemon's idle exit can never fire.
+        if (!ctx) {
+            client = undefined;
+            return false;
+        }
+        // A 401 is not "the mode is off": the daemon rejected this session's bearer, which means a
+        // rotated/removed `secret.key`. Flipping the mirror to "off" there silently stopped every
+        // notification and drain, and the poll then respawned a daemon that kept rejecting us.
+        if (!initialMode.ok && initialMode.status === 401 && !tokenRejected) {
+            tokenRejected = true;
+            ctx.ui.notify("mailbridge: the daemon rejected this session's bearer token — restart pi (or /mailbridge restart) to load the current secret", "error");
+        }
+        if (initialMode.ok)
+            emailMode = initialMode.data.mode === "on" ? "on" : "off";
+        notifier = createSettleNotifier({
+            mode: () => emailMode,
+            context: sessionContext,
+            send: async (message) => {
+                const sent = await active.send({
+                    subject: message.subject,
+                    text: message.text,
+                    // Exempt from the notification budget: a burst of `notify_user` mail must not
+                    // be able to silence "your agent is waiting".
+                    kind: "settle",
+                    ...(ctx ? { cwd: ctx.cwd, sessionId: ctx.sessionManager.getSessionId() } : {}),
+                });
+                // A non-ok result used to be discarded here, so a refused or timed-out send
+                // vanished: no toast, no log, no retry. Throwing routes it to onError.
+                // `sent === undefined` means there is no client at all; reporting that as a
+                // success would make "nothing was sent" indistinguishable from "sent".
+                if (!sent)
+                    throw new Error("send failed (daemon unavailable)");
+                if (!sent.ok) {
+                    throw new Error(sent.code === "send_budget"
+                        ? "notification budget exhausted (10 a minute)"
+                        : `send failed (${sent.code ?? sent.status})`);
+                }
+            },
+            secret: () => secret,
+            config: { ...config.notify, tokenTtlHours: config.security.tokenTtlHours },
+            tagFor: (context) => ensureRouteForSession({
+                sessionId: context.sessionId,
+                ...(context.device ? { device: context.device } : {}),
+                subject: `pi: ${context.sessionName ?? context.cwd}`,
+                ttlHours: config.security.tokenTtlHours,
+                env,
+            }),
+            timers,
+            onError: (error) => ctx?.ui.notify(`mailbridge: could not send (${error.message})`, "warning"),
+        });
+        runner = createDeliveryRunner({
+            client: {
+                // Pass every argument through. This adapter has silently dropped one before
+                // (uidValidity), which disabled the stale-space guard on the only production
+                // client while the store's own test stayed green.
+                claim: (uid, id, uidValidity) => active.claim(uid, id, uidValidity),
+                ack: (uid, id, sessionId, uidValidity) => active.ack(uid, id, sessionId, uidValidity),
+                pending: () => active.pending(),
+            },
+            instanceId,
+            sessionId: () => ctx?.sessionManager.getSessionId(),
+            stillDelivering: () => emailMode === "on",
+            inject: async (body, record) => {
+                // A command by mail runs the same handler the prompt would, and then there is
+                // nothing to inject: the human asked for an action, not for the agent to read a
+                // sentence. Anything we do not run here stays a message, so a quoted "/mailbridge off" or a
+                // refused "/mailbridge setup" is never executed by accident.
+                const command = parseMailCommand(body);
+                if (command) {
+                    const handler = commandHandlers.get(command.name);
+                    if (handler && !ctx) {
+                        // The session is tearing down. Throwing keeps the record pending so the
+                        // command runs in a live session; falling through would inject the
+                        // command text into a dead session and then ack it, consuming the mail.
+                        throw new Error("no active session for a command reply");
+                    }
+                    if (handler && ctx) {
+                        // A command that throws must NOT propagate: deliveries treats an inject
+                        // failure as "retry later" and never acks, so the same command would run
+                        // again every poll tick - and `/mailbridge smoke` would send a real mail
+                        // each time. The command was handled either way; say it failed and let
+                        // the delivery be acked.
+                        try {
+                            await handler(command.args, ctx);
+                        }
+                        catch (error) {
+                            ctx.ui.notify(`mailbridge: /${command.name} from mail failed: ${error.message}`, "error");
+                        }
+                        return;
+                    }
+                }
+                const content = toUserContent(body, record.attachments ?? []);
+                // A reply is text from a human, never a command. With template expansion on, pi
+                // dispatches a message starting with "/" as an extension command and never gives
+                // it to the model - so a reply of "/mailbridge off" would run a command, return without a
+                // turn, and the runner would ack and \Seen it. The human would believe the agent
+                // had read it.
+                pi.sendUserMessage(content, { deliverAs: "followUp", expandPromptTemplates: false });
+            },
+            onError: (error) => ctx?.ui.notify(`mailbridge: reply not delivered (${error.message})`, "warning"),
+        });
+        // Ping before the first drain: a drain of several replies can outlast the idle window,
+        // and the daemon reaps itself when no ping arrives in that time. A client without ping
+        // (tests, older shape) is not a reason to skip the drain.
+        try {
+            await active.ping(instanceId);
+        }
+        catch {
+            /* the drain below is what decides */
+        }
+        // Catch-up on connect, but only when the channel is actually open: `off` must not
+        // be bypassed by a session starting up.
+        if (emailMode === "on")
+            await runner.drain();
+        // Same reason as above, after the drain's awaits.
+        if (!ctx) {
+            client = undefined;
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Tell a pre-existing daemon to re-read its config when the file is newer than the
+     * config it loaded. Best-effort: a failure here must not block the session.
+     */
+    async function reloadIfStale() {
+        if (!client)
+            return;
+        try {
+            const health = await client.health();
+            if (!health.ok)
+                return;
+            const loadedAt = health.data.configLoadedAt;
+            const mtime = statSync(configPath(env), { throwIfNoEntry: false })?.mtimeMs ?? null;
+            if (!shouldReloadConfig({ configLoadedAt: loadedAt, configMtimeMs: mtime }))
+                return;
+            const reloaded = await client.reload();
+            // Never silent: this is the path that decides which address the agent's mail goes
+            // to, so a refused reload (daemon kept the old config) must be visible.
+            if (!reloaded.ok) {
+                ctx?.ui.notify("mailbridge: the daemon could not reload its config — run /mailbridge restart", "warning");
+            }
+            else if (reloaded.data.warning) {
+                ctx?.ui.notify(`mailbridge: ${reloaded.data.warning}`, "warning");
+            }
+        }
+        catch {
+            /* best effort: a stale config is not a reason to fail the session */
+        }
+    }
+    async function ensureDaemonSafe() {
+        return (await ensureDaemonDetailed()).healthy;
+    }
+    /**
+     * Spawn-or-reuse, keeping the reason. `incompatible` means something answered but spoke
+     * another protocol - the replacement path, not the dead-daemon path.
+     */
+    async function ensureDaemonDetailed() {
+        if (deps.ensureDaemon) {
+            const result = await deps.ensureDaemon(currentBaseUrl(), daemonScript());
+            return typeof result === "boolean" ? { healthy: result } : result;
+        }
+        return ensureDaemon({ baseUrl: currentBaseUrl(), scriptPath: daemonScript(), env });
+    }
+    pi.on("session_start", async (_event, c) => {
+        ctx = c;
+        // Spawning a daemon that is guaranteed to exit (no mailbox configured) would just
+        // cost five seconds on every session start, so check the mailbox first.
+        if (!hasUsableMailConfig(config)) {
+            c.ui.notify("mailbridge: no mailbox configured — run /mailbridge setup <pi-address> to <your-address>", "warning");
+            return;
+        }
+        // The daemon owns secret.key, but waiting for a daemon that only this code can start
+        // is a deadlock: on a machine that has never run it, the key does not exist yet and
+        // every session would bail out here. Mint it instead (first-writer-wins, 0600).
+        if (!secretFn()) {
+            try {
+                ensureSecret(env);
+            }
+            catch (error) {
+                c.ui.notify(`mailbridge: could not create the shared secret (${error.message})`, "error");
+                return;
+            }
+        }
+        protocolStuck = false;
+        tokenRejected = false;
+        const ensured = await ensureDaemonDetailed();
+        if (!ensured.healthy) {
+            c.ui.notify(ensured.incompatible
+                ? "mailbridge: the running daemon speaks another protocol — restarting it"
+                : `mailbridge: daemon not reachable${ensured.error ? ` (${ensured.error})` : ""}; replies will not arrive`, "warning");
+            // An incompatible daemon is the replacement path, not a dead one. It succeeds or it
+            // does not; either way this session must not then build a runtime on top of it.
+            if (ensured.incompatible) {
+                await replaceOutdatedDaemon(ensured);
+                // Success re-arms the poll itself; a failure must too, or the session sits with no
+                // runtime and no loop while the toast says it is retrying.
+                if (ctx)
+                    startPolling();
+                return;
+            }
+            // Keep polling even with no runtime: the tick retries the spawn, which is the only
+            // automatic recovery a session has.
+            if (ctx)
+                startPolling();
+            return;
+        }
+        if (!(await startRuntime())) {
+            if (ctx)
+                startPolling();
+            return;
+        }
+        startPolling();
+        // A daemon that was already running may have read the config before the user edited
+        // it (hand-edited config.json, headless --setup). Re-read it rather than mailing the
+        // address they just replaced - but do NOT block the session on an IMAP redial, which
+        // can take imapflow's full connect timeout when the new config is wrong.
+        void reloadIfStale();
+    });
+    // The ONLY settle signal. `agent_end` is deliberately not registered: pi may
+    // still retry, compact or run queued follow-ups after it.
+    pi.on("agent_settled", (event) => {
+        notifier?.settled({ aborted: event["aborted"] === true });
+    });
+    pi.on("session_shutdown", async () => {
+        // A settle inside the debounce window is a notification the user asked for; dropping it
+        // because pi is closing makes a one-shot run (`pi -p`) mail nothing at all. The daemon
+        // outlives us for the idle timeout, so the send can still land.
+        await notifier?.flush().catch(() => undefined);
+        notifier?.cancel();
+        // Release our liveness slot so an idle daemon can exit promptly rather than
+        // waiting out the grace period.
+        void client?.bye(instanceId);
+        stopPolling();
+        client = undefined;
+        runner = undefined;
+        ctx = undefined;
+    });
+    // ---- commands ----------------------------------------------------------
+    async function setMode(mode, c) {
+        // No client means this session never built a runtime (it started before a config
+        // existed). Writing mode.json alone would report ON with no notifier and no runner - the
+        // documented "copy config.example.json yourself" path lands here.
+        if (!client && (await startRuntime()) && !pollPaused)
+            startPolling();
+        const viaDaemon = client ? await client.setMode(mode) : undefined;
+        if (viaDaemon?.ok) {
+            emailMode = mode;
+            c.ui.notify(mode === "on" ? "mailbridge: email mode ON" : "mailbridge: email mode OFF", "info");
+            return;
+        }
+        // No daemon: fall back to the local file so the mode change is never a silent no-op.
+        const { writeMode } = await import("./store/mode-store.js");
+        writeMode(env, mode);
+        // The settle notifier reads this mirror, not the file. Without it the command reports
+        // ON while every notification is dropped as "mode off".
+        emailMode = mode;
+        c.ui.notify(`mailbridge: email mode ${mode.toUpperCase()} (daemon unreachable, stored locally)`, "warning");
+    }
+    // The same handlers back both the in-pi command and a command arriving as a mail reply, so
+    // the mode subcommands cannot drift between mail and prompt.
+    const commandHandlers = new Map();
+    const registerCommand = (name, description, handler) => {
+        commandHandlers.set(name, handler);
+        pi.registerCommand(name, { description, handler });
+    };
+    registerCommand("mailbridge", "Status, on/off, setup, check, auth, smoke, restart", async (args, c) => {
+        // Re-read config on every command. It can change underneath us: `--setup`
+        // run from a shell, or an edit to config.json, would otherwise leave the
+        // command surface reporting stale settings until pi restarts.
+        config = load();
+        const parsed = parseMailbridgeCommand(args);
+        const ensureRuntime = async (ui) => {
+            if (client)
+                return true;
+            if (!secretFn()) {
+                try {
+                    ensureSecret(env);
+                }
+                catch (error) {
+                    ui.notify(`mailbridge: could not create the shared secret (${error.message})`, "error");
+                    return false;
+                }
+            }
+            if (!(await ensureDaemonSafe())) {
+                ui.notify("mailbridge: daemon not reachable; replies will not arrive", "warning");
+                return false;
+            }
+            if (!(await startRuntime()))
+                return false;
+            // The loop may be parked by a command that owns it; its own finally re-arms.
+            if (!pollPaused)
+                startPolling();
+            return true;
+        };
+        const statusReport = async () => {
+            const secret = secretFn();
+            const health = client ? await client.health() : undefined;
+            // No client in *this* session is not the same as no daemon on the port.
+            const alive = health?.ok ? true : await probe({ baseUrl: clientBase ?? currentBaseUrl() });
+            const pending = client ? await client.pending() : undefined;
+            // The daemon is a separate process with its own lifetime; after `pi update` it can
+            // be an older build, so name it here rather than making the user read /health.
+            const daemonVersion = health?.ok ? (health.data.version ?? "unknown") : "unknown";
+            // The protocol is what matters; the package version is diagnostic.
+            const build = health?.ok
+                ? apiCompatible(API_VERSION, health.data.apiVersion)
+                    ? ` — daemon version ${daemonVersion}, protocol ${health.data.apiVersion}`
+                    : ` — daemon protocol ${health.data.apiVersion ?? "0"}, this session is ${API_VERSION} (replacing it)`
+                : "";
+            c.ui.notify([
+                `daemon: ${health?.ok ? "healthy" : alive ? "running, but not attached to this session" : "unreachable"} (${clientBase ?? currentBaseUrl()})${build}`,
+                `device: ${config.device.name}`,
+                `mode: ${health?.ok ? health.data.mode : "(unknown)"}`,
+                `imap: ${health?.ok ? health.data.imap ?? "unknown" : "(unknown)"}`,
+                `session: ${ctx?.sessionManager.getSessionId() ?? "(none)"}`,
+                `secret: ${secret ? "present" : "missing"}`,
+                `mailbox: ${config.mail.to || "(unset)"}`,
+                `allowlist: ${config.security.allowFrom.join(", ") || "(empty — denies all)"}`,
+                `pending replies: ${pending?.ok ? pending.data.pending.length : "?"}`,
+                // From the same response: /pending reports what it did not offer.
+                ...(pending?.ok && (pending.data.withheld ?? 0) > 0
+                    ? [
+                        `held for another device: ${pending.data.withheld} (a renamed device.name, or a copied state directory; see docs/ARCHITECTURE.md)`,
+                    ]
+                    : []),
+                ...formatScan(health?.ok ? (health.data.lastScan ?? null) : null),
+            ].join("\n"), "info");
+        };
+        switch (parsed.sub) {
+            case "on":
+                return void (await setMode("on", c));
+            case "off":
+                return void (await setMode("off", c));
+            case "help":
+                return void c.ui.notify(USAGE, "info");
+            case "status":
+                return void (await statusReport());
+            case "setup": {
+                if (!parsed.address)
+                    return void c.ui.notify(`setup needs an address\n\n${USAGE}`, "warning");
+                const result = await runSetup({
+                    address: parsed.address,
+                    ...(parsed.to ? { to: parsed.to } : {}),
+                    force: parsed.force,
+                    env,
+                });
+                config = load(); // pick up what was just written
+                const reloaded = client ? await client.reload() : undefined;
+                c.ui.notify([
+                    ...result.steps,
+                    result.next ? `next: ${result.next}` : "",
+                    client ? (reloaded?.ok ? "daemon reloaded" : "daemon did not reload — run /mailbridge restart") : "",
+                ]
+                    .filter(Boolean)
+                    .join("\n"), result.ok ? "info" : "error");
+                // A session that started before the config existed has no runtime yet.
+                if (result.ok && !client) {
+                    const started = await ensureRuntime(c.ui);
+                    c.ui.notify(started
+                        ? "daemon started — /mailbridge smoke, then /mailbridge on"
+                        : "config written, but the daemon did not start — /mailbridge restart", started ? "info" : "warning");
+                }
+                return;
+            }
+            case "check": {
+                // Mint rather than advise: "start the daemon once" is unfollowable in the only
+                // state where this is missing.
+                let secret = secretFn();
+                let mintedSecret = false;
+                if (!secret) {
+                    try {
+                        secret = ensureSecret(env);
+                        mintedSecret = Boolean(secret);
+                    }
+                    catch {
+                        /* reported below */
+                    }
+                }
+                const problems = [...config.warnings];
+                if (config.security.allowSelfReplies && config.security.requireDmarcPass) {
+                    problems.push("allowSelfReplies is on but requireDmarcPass is too: providers that do not stamp " +
+                        "Authentication-Results on self-addressed mail will reject every reply (dmarc-missing)");
+                }
+                if (!secret)
+                    problems.push("shared secret missing and could not be created");
+                // A running daemon caches the bearer token from startup, so a freshly minted key
+                // is rejected until it restarts. Say so; "config ok" would be a lie.
+                else if (mintedSecret)
+                    problems.push("created a new shared secret — restart the daemon so it uses it");
+                const usesOAuth = config.mail.imap.authType === "XOAUTH2" || config.mail.smtp.authType === "XOAUTH2";
+                if (config.oauth && !usesOAuth) {
+                    problems.push("oauth is configured but neither account uses XOAUTH2 — it would be ignored");
+                }
+                if (usesOAuth) {
+                    const oauthConfigured = Boolean(config.oauth?.issuer && config.oauth.clientId);
+                    const hasToken = Boolean(fileTokenStore(env).read()?.refreshToken);
+                    const hasCommand = Boolean((config.mail.smtp.tokenCommand ?? config.mail.imap.tokenCommand ?? []).length);
+                    if (oauthConfigured && !hasToken)
+                        problems.push("oauth configured but not authorised — /mailbridge auth");
+                    if (!oauthConfigured && !hasCommand)
+                        problems.push("XOAUTH2 needs oauth.* or a tokenCommand");
+                }
+                c.ui.notify(problems.length ? problems.map((p) => `! ${p}`).join("\n") : "config ok — run /mailbridge smoke to prove it", problems.length ? "warning" : "info");
+                return;
+            }
+            case "auth": {
+                if (!config.oauth?.issuer || !config.oauth.clientId) {
+                    return void c.ui.notify("oauth.issuer and oauth.clientId are required — run /mailbridge setup first", "error");
+                }
+                if (config.oauth.clientId.startsWith("<")) {
+                    return void c.ui.notify("oauth.clientId is still the placeholder — register an app (docs/OAUTH.md)", "error");
+                }
+                try {
+                    const oauthClient = await createOpenidClient(config.oauth);
+                    const authorization = await oauthClient.deviceAuthorization();
+                    c.ui.notify([
+                        "Approve this login on any device, then wait here:",
+                        authorization.verificationUri,
+                        authorization.userCode ? `code: ${authorization.userCode}` : "",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"), "info");
+                    // Poll in the background so the TUI stays usable.
+                    void oauthClient
+                        .pollDeviceAuthorization()
+                        .then(async (tokens) => {
+                        if (!tokens.refreshToken) {
+                            c.ui.notify("no refresh_token returned — add offline_access to oauth.scope", "error");
+                            return;
+                        }
+                        fileTokenStore(env).write({
+                            refreshToken: tokens.refreshToken,
+                            accessToken: tokens.accessToken,
+                            expiresAt: tokens.expiresAt,
+                        });
+                        const reloaded = client ? await client.reload() : undefined;
+                        c.ui.notify(`authorised; refresh token stored${reloaded?.ok ? ", daemon reloaded" : ""}`, "info");
+                    })
+                        .catch((error) => c.ui.notify(`login failed: ${error.message}`, "error"));
+                }
+                catch (error) {
+                    c.ui.notify(`login failed: ${error.message}`, "error");
+                }
+                return;
+            }
+            case "smoke": {
+                try {
+                    // Reload first: smoke is the documented "does it work?" step after editing
+                    // the password, and the daemon holds the config it started with. Without
+                    // this, smoke passes (it reads the file) while /send keeps using the old
+                    // empty password and the first notification fails.
+                    const reloaded = client ? await client.reload() : undefined;
+                    if (client && reloaded?.ok !== true) {
+                        c.ui.notify("daemon did not reload; run /mailbridge restart", "warning");
+                    }
+                    else if (reloaded?.ok && reloaded.data.warning) {
+                        c.ui.notify(`mailbridge: ${reloaded.data.warning}`, "warning");
+                    }
+                    config = load();
+                    const provider = await buildTokenProvider(config, env);
+                    const result = await runSmoke(config, {
+                        ...(provider ? { getAccessToken: () => provider.getToken() } : {}),
+                    });
+                    c.ui.notify([
+                        ...result.steps.map((s) => `${s.step} ${s.ok ? "ok" : "FAILED"}: ${s.detail}`),
+                        ...result.steps.filter((s) => s.hint).map((s) => `hint: ${s.hint}`),
+                    ].join("\n"), result.ok ? "info" : "error");
+                }
+                catch (error) {
+                    c.ui.notify(`smoke failed: ${error.message}`, "error");
+                }
+                return;
+            }
+            case "prime": {
+                // First run only: the cursor is what makes mail visible, so moving it after
+                // the bridge has been watching would skip replies that arrived unscanned.
+                let imap;
+                try {
+                    const provider = await buildTokenProvider(config, env);
+                    const { createImapflowFactory } = await import("./daemon/imapflow.js");
+                    const { advanceCursor, isPrimed, markPrimed, readCursor } = await import("./store/uid-cursor.js");
+                    const { alreadyPrimedMessage, runPrime } = await import("./core/prime.js");
+                    const imapClient = await createImapflowFactory({
+                        ...(provider ? { getAccessToken: () => provider.getToken() } : {}),
+                    })(config, { idleRenewMs: config.tuning.idleRenewMs });
+                    imap = imapClient;
+                    const plan = await runPrime(config, {
+                        openMailbox: async (cfg) => {
+                            await imapClient.connect();
+                            await imapClient.mailboxOpen(cfg.mail.imap.folder || "INBOX");
+                            return {
+                                search: () => imapClient.search({ uid: "1:*" }, { uid: true }),
+                                close: async () => imapClient.logout(),
+                            };
+                        },
+                        readCursor: () => readCursor(env),
+                        isPrimed: () => isPrimed(env),
+                        markPrimed: () => markPrimed(env),
+                        advanceCursor: (uid) => {
+                            advanceCursor(env, uid);
+                        },
+                    });
+                    if (!plan.ok) {
+                        c.ui.notify(alreadyPrimedMessage(plan.currentUid), "warning");
+                        return;
+                    }
+                    const reloaded = client ? await client.reload() : undefined;
+                    c.ui.notify(`primed: cursor at uid ${plan.highest}; ${plan.count} existing message(s) will not be read${reloaded?.ok ? ", daemon reloaded" : ""}`, "info");
+                }
+                catch (error) {
+                    c.ui.notify(`prime failed: ${error.message}`, "error");
+                }
+                finally {
+                    // A connect that succeeded before mailboxOpen threw would otherwise leak the
+                    // connection. logout is idempotent; the CLI does the same.
+                    await imap?.logout().catch(() => undefined);
+                }
+                return;
+            }
+            case "restart": {
+                // A config reload cannot replace running code, so after an update the
+                // daemon would keep executing the old version. Stop the process and let
+                // the supervisor start a fresh one.
+                // Park the poll first. It runs every ten seconds and the wait below lasts up to
+                // five, so a tick landing inside it would hear the dying daemon's ping fail,
+                // spawn or attach a replacement, and make `survivor` true - reporting a failure
+                // for the restart this command just performed. Every exit below re-arms it.
+                stopPolling();
+                let joinExpired = false;
+                try {
+                    // A tick already past every pause check may be inside a spawn. Wait for it, so
+                    // the daemon it started is on the port before this command looks.
+                    joinExpired = await settleTick();
+                    // To stop it we need a client even when this session has no runtime yet - the
+                    // same rule the protocol replacement follows, and the remedy its own warning
+                    // names.
+                    const stopping = client ?? buildClient();
+                    // `ok` only means it acknowledged, and a 401 or a timeout means nothing was
+                    // confirmed at all - so none of them decides the outcome. `status: 0` with a
+                    // network code is a fetch that never got a reply (refused, or the process died
+                    // first): not a failure to stop, and the commonest way to run this command.
+                    let nothingToStop = false;
+                    let survivor = false;
+                    let rejected = false;
+                    let refusedBase;
+                    if (stopping) {
+                        const result = await stopping.shutdown().catch(() => undefined);
+                        nothingToStop = Boolean(result && !result.ok && result.status === 0 && result.code === "network");
+                        // A 401 is not a wedged daemon: retrying cannot help until it exits, and the
+                        // advice below has to say so. Only 401: the daemon has no 403 (service.ts
+                        // answers 401 for a bad bearer), so a 403 would be something else on the port.
+                        rejected = Boolean(result && !result.ok && result.status === 401);
+                        if (rejected) {
+                            // It answered on the client's base, which may not be the configured one
+                            // after a `daemon.port` edit: remember that separately, then check
+                            // whether it was still there once the stop had its chance.
+                            refusedBase = clientBase ?? currentBaseUrl();
+                        }
+                        client = undefined;
+                        runner = undefined;
+                        // Whether something still answers here is the only evidence that a restart did
+                        // or did not happen, and `ensureDaemon` would happily reuse a survivor.
+                        // `clientBase` follows the client, which may predate a `daemon.port` edit;
+                        // the daemon this command starts will be on the configured one.
+                        survivor = await waitForPortToClose(currentBaseUrl());
+                    }
+                    // A 401 proves only that something answered *then*. If it exited inside the
+                    // stop window, the restart worked and must not be reported as a failure.
+                    // One probe per base: when the refusing base *is* the configured port, `survivor`
+                    // already answers this, and asking twice can disagree.
+                    const refusalBase = refusedBase ?? currentBaseUrl();
+                    const rejectionSurvived = rejected
+                        ? refusalBase === currentBaseUrl()
+                            ? survivor
+                            : await probe({ baseUrl: refusalBase })
+                        : false;
+                    const ensured = await ensureDaemonDetailed();
+                    if (ensured.healthy) {
+                        // Cleared before the rebuild: the rebuild is what reads the key again, so a
+                        // rejection after it must be able to say so. A daemon that still cannot be
+                        // reached never gets here, and keeps both latches.
+                        tokenRejected = false;
+                        protocolStuck = false;
+                        lastRespawnAttempt = 0;
+                        // One rebuild, through the helper: it captures the notifier that holds a
+                        // debounced settle, rebuilds, and flushes. Calling ensureRuntime first would
+                        // overwrite that notifier and lose the settle.
+                        if (!secretFn()) {
+                            try {
+                                ensureSecret(env);
+                            }
+                            catch {
+                                /* reported by the toast below */
+                            }
+                        }
+                        const attached = await replaceRuntime();
+                        if (!attached) {
+                            c.ui.notify(stopping
+                                ? "daemon restarted, but this session could not attach — run /mailbridge restart again"
+                                : "the daemon is up, but this session could not attach — run /mailbridge restart again", "warning");
+                            return;
+                        }
+                    }
+                    // Tell the user what happened, not what was attempted: an answering daemon that
+                    // was never stopped is not a restart.
+                    let message;
+                    let level = "info";
+                    if (rejected && rejectionSurvived) {
+                        // First: it explains a failed respawn (the rejecting daemon holds the lock,
+                        // so the new one exits 0) and it is the only advice that works.
+                        level = "error";
+                        message =
+                            "the daemon rejected this session's key, so it could not be stopped — stop it (or let it idle out) and start pi again";
+                    }
+                    else if (!ensured.healthy) {
+                        level = "error";
+                        message = ensured.incompatible
+                            ? `daemon is still on another protocol (${ensured.apiVersion ?? "0"} → ${API_VERSION}) — close pi and start it again`
+                            : `daemon did not come back${ensured.error ? ` (${ensured.error})` : ""} — run /mailbridge restart again`;
+                    }
+                    else if (survivor && joinExpired) {
+                        // The poll was still starting a daemon when the budget ran out, so the thing
+                        // on the port may be its spawn rather than something that survived the stop.
+                        level = "warning";
+                        message = "the poll was still starting a daemon when this ran — run /mailbridge restart again";
+                    }
+                    else if (survivor && nothingToStop) {
+                        // The stop was refused, yet something answers: either the connection failed
+                        // between the two processes or a supervisor restarted it. Not a failure, but
+                        // "with the current code" is not something this session can claim.
+                        level = "warning";
+                        message =
+                            "the old daemon was already gone, but something is still serving its port — try again, or close pi if it keeps answering";
+                    }
+                    else if (survivor) {
+                        // `ok:true` is not proof of exit: a shutdown that is still logging out of IMAP
+                        // keeps answering, and so does a timeout. Only the port can say.
+                        level = "error";
+                        message = "a daemon is still answering after the stop request — try again, or close pi if it keeps answering";
+                    }
+                    else if (!stopping && ensured.started) {
+                        // First run: no key existed, so there was nothing to stop, and this call is
+                        // what created both. Reporting that as a warning would greet every headless
+                        // setup with a caveat about a daemon that never existed.
+                        message = "daemon started with the current code";
+                    }
+                    else if (!stopping) {
+                        // No key and no client when the stop was tried, and a daemon was already
+                        // there - so this session cannot say what it was serving. State the
+                        // observation, not a cause: it may have minted its key a moment ago.
+                        level = "warning";
+                        message =
+                            "a daemon was already up, but this session had no key when it tried to stop anything — stop it and run this again";
+                    }
+                    else {
+                        message = nothingToStop
+                            ? "the old daemon was already gone; a new one is up with the current code"
+                            : "daemon restarted with the current code";
+                    }
+                    c.ui.notify(message, level);
+                }
+                finally {
+                    // One arm for every exit, including a thrown one: parking the loop must never
+                    // outlive the command that parked it.
+                    startPolling();
+                }
+                return;
+            }
+        }
+    });
+    // ---- agent-facing tools ------------------------------------------------
+    pi.registerTool({
+        name: "request_decision",
+        label: "Request decision",
+        description: "Email the user a decision request and end the turn. Use only when email mode is on and you cannot proceed without the user's choice.",
+        parameters: Type.Object({
+            subject: Type.String({ description: "Short subject line" }),
+            question: Type.String({ description: "The decision, with enough context to answer from a phone" }),
+            options: Type.Optional(Type.Array(Type.String())),
+            recommendation: Type.Optional(Type.String()),
+        }),
+        async execute(_id, params, _signal, _update, c) {
+            if (!client || !runner) {
+                return { content: [{ type: "text", text: "Mailbridge daemon is not reachable; ask in the terminal instead." }], details: {} };
+            }
+            const mode = await client.mode();
+            if (!mode.ok || mode.data.mode !== "on") {
+                return { content: [{ type: "text", text: "Email mode is off — ask in the terminal." }], details: {} };
+            }
+            const sessionId = c.sessionManager.getSessionId();
+            const reserved = await client.register(sessionId);
+            if (!reserved.ok) {
+                return { content: [{ type: "text", text: "Another decision is already outstanding for this session." }], details: {} };
+            }
+            if (reserved.data.alreadyPending) {
+                return { content: [{ type: "text", text: "A decision is already outstanding for this session; not mailing twice." }], details: {} };
+            }
+            // The slot is reserved above. Everything from here must either send the mail or free
+            // the reservation: a leaked slot answers "already outstanding" for the rest of the
+            // session, because re-registering refreshes its TTL.
+            let sent = false;
+            try {
+                const secret = secretFn();
+                if (!secret)
+                    return { content: [{ type: "text", text: "Mailbridge secret missing." }], details: {} };
+                const options = params["options"] ?? [];
+                const recommendation = params["recommendation"];
+                const body = [
+                    String(params["question"] ?? ""),
+                    options.length ? `\noptions:\n${options.map((o) => `- ${o}`).join("\n")}` : "",
+                    recommendation ? `\nrecommendation: ${recommendation}` : "",
+                    "\n",
+                    "--",
+                    "Reply above this line with your answer.",
+                ].join("\n");
+                const tag = ensureRouteForSession({
+                    sessionId,
+                    device: config.device.name,
+                    subject: String(params["subject"] ?? "pi: decision"),
+                    ttlHours: config.security.tokenTtlHours,
+                    env,
+                });
+                const outcome = await client.send({
+                    kind: "decision",
+                    subject: `[pi:${tag}] ${String(params["subject"] ?? "pi: decision")}`,
+                    text: body,
+                    cwd: c.cwd,
+                    sessionId,
+                });
+                if (!outcome.ok) {
+                    const why = outcome.code === "send_budget"
+                        ? "Could not send the email: the notification budget is exhausted (10 a minute); ask in the terminal instead"
+                        : "Could not send the email; ask in the terminal instead";
+                    return { content: [{ type: "text", text: why }], details: {} };
+                }
+                sent = true;
+            }
+            catch (error) {
+                return {
+                    content: [{ type: "text", text: `Could not email the decision (${error.message}); ask in the terminal.` }],
+                    details: {},
+                };
+            }
+            finally {
+                // Free only a reservation that never produced a mail.
+                if (!sent)
+                    await client.release(sessionId).catch(() => undefined);
+            }
+            return { content: [{ type: "text", text: "Emailed the decision. End your turn and wait for the reply." }], details: {} };
+        },
+    });
+    pi.registerTool({
+        name: "notify_user",
+        label: "Notify user",
+        description: "Send the user a one-way email update. Does not end the turn and does not wait for a reply.",
+        parameters: Type.Object({ subject: Type.String(), message: Type.String() }),
+        async execute(_id, params, _signal, _update) {
+            if (!client)
+                return { content: [{ type: "text", text: "Mailbridge daemon is not reachable." }], details: {} };
+            const mode = await client.mode();
+            if (!mode.ok || mode.data.mode !== "on") {
+                return { content: [{ type: "text", text: "Email mode is off." }], details: {} };
+            }
+            const secret = secretFn();
+            if (!secret)
+                return { content: [{ type: "text", text: "Mailbridge secret missing." }], details: {} };
+            // No session means no session to route back to: minting a route for "" would be
+            // dead state that the scanner treats as no-route anyway.
+            const context = sessionContext();
+            if (!context?.sessionId) {
+                return { content: [{ type: "text", text: "No active session to attach this notification to." }], details: {} };
+            }
+            const tag = ensureRouteForSession({
+                sessionId: context.sessionId,
+                device: config.device.name,
+                subject: String(params["subject"] ?? "pi: update"),
+                ttlHours: config.security.tokenTtlHours,
+                env,
+            });
+            const sent = await client.send({
+                subject: `[pi:${tag}] ${String(params["subject"] ?? "pi: update")}`,
+                text: String(params["message"] ?? ""),
+                ...((sessionContext()?.cwd ?? undefined) ? { cwd: sessionContext().cwd } : {}),
+                ...(sessionContext()?.sessionId ? { sessionId: sessionContext().sessionId } : {}),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: sent.ok
+                            ? "Sent."
+                            : sent.code === "send_budget"
+                                ? "Not sent: the notification budget is exhausted (10 a minute)."
+                                : "Could not send.",
+                    },
+                ],
+                details: {},
+            };
+        },
+    });
+}