ftown-bridge 0.19.1 → 0.19.2

package/dist/local-api-server.js

@@ -1,14 +1,13 @@
 import { createServer } from 'node:http';
 import { EventEmitter } from 'node:events';
 import { timingSafeEqual } from 'node:crypto';
-import { createMailMessage } from './mail-store.js';
-import { buildSessionCommand } from './agent-commands.js';
-import { createLoop, deleteLoop, getLoop, listLoops, mutateLoopRuntime, updateLoop } from './loop-store.js';
-import { deleteLoopRunRecords, listLoopRunRecordsWithFallback } from './loop-run-store.js';
-import { validateLoopDraft, validateLoopPatch } from './loop-validation.js';
+import { MailDeliveryService, sanitizeMessageText } from './mail-delivery.js';
+import { LoopController } from './loop-controller.js';
+import { SessionController } from './session-controller.js';
 import { registerSessionConversation, resolveSessionIdByConversation, resolveSessionIdFromHookPayload, } from './session-registry.js';
-import { createFtownSession, parseCreateSessionBody, ProviderAuthMissingError, WorkingDirMissingError, } from './create-ftown-session.js';
+import { createFtownSession, deriveRelaunchCommand, parseCreateSessionBody, ProviderAuthMissingError, WorkingDirMissingError, } from './create-ftown-session.js';
 import { removeFtownSession } from './remove-ftown-session.js';
+import { collectSessionUsage } from './usage-collector.js';
 import { toWireSession } from './session-wire.js';
 function jsonResponse(res, status, data) {
     res.writeHead(status, { 'Content-Type': 'application/json' });
@@ -84,38 +83,6 @@ function extractBearer(req) {
     return null;
 }
 const MAX_MESSAGE_LENGTH = 2000;
-const MAX_MAIL_BODY_LENGTH = 64 * 1024;
-const MAX_MAIL_WAIT_SECONDS = 30;
-const MAIL_NUDGE_DELAY_MS = 5_000;
-// Hooked agents (claude/codex and claude flavors) get mail through their Stop
-// pump; the nudge is only a safety net for them, so wait much longer before
-// typing into their pane — fast nudges race the pump and queue stale prompts.
-const MAIL_NUDGE_DELAY_HOOKED_MS = 60_000;
-const HOOKED_SHELL_TYPES = new Set([
-    'claude', 'codex', 'zai', 'kimi', 'deepseek', 'fireworks',
-]);
-const MAIL_NUDGE_MIN_INTERVAL_MS = 30_000;
-// While an agent is mid-turn its Stop hook pump delivers mail at turn end, so
-// nudging would only queue a stale prompt; re-check periodically in case the
-// turn never reaches Stop, and ignore busy markers old enough to be a crash.
-const MAIL_NUDGE_BUSY_RECHECK_MS = 60_000;
-const AGENT_BUSY_STALE_MS = 30 * 60_000;
-const MAIL_TYPES = ['message', 'task', 'result', 'escalation'];
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-// Messages are sanitized to a single line, so a delayed plain CR submits everywhere.
-// (ESC+CR reads as Alt+Enter — insert newline — on current Claude Code.)
-function submitSuffixFor(_shellType) {
-    return '\r';
-}
-// Strip control chars and collapse whitespace so a message cannot inject keystrokes.
-function sanitizeMessageText(text) {
-    return text
-        .replace(/[\u0000-\u001f\u007f]/g, ' ')
-        .replace(/\s+/g, ' ')
-        .trim();
-}
 function getQueryInt(url, name, defaultValue) {
     const val = url.searchParams.get(name);
     if (!val)
@@ -130,21 +97,18 @@ export class LocalApiServer extends EventEmitter {
     centrifugo = null;
     terminalManager = null;
     sessionDeps = null;
-    mailStore = null;
-    mailWaiters = new Map();
-    nudgeTimers = new Map();
-    pendingNudgeFrom = new Map();
-    lastNudgeAt = new Map();
-    agentBusySince = new Map();
+    mail = new MailDeliveryService();
     loopApi = null;
     userId = '';
     authToken = '';
     port = 0;
+    loopController = null;
+    sessionController = null;
     setAuthToken(token) {
         this.authToken = token;
     }
     setMailStore(mailStore) {
-        this.mailStore = mailStore;
+        this.mail.setMailStore(mailStore);
     }
     setDependencies(store, runner, centrifugo, userId, terminalManager) {
         this.store = store;
@@ -152,12 +116,62 @@ export class LocalApiServer extends EventEmitter {
         this.centrifugo = centrifugo;
         this.userId = userId;
         this.terminalManager = terminalManager ?? null;
+        this.mail.setStore(store);
+        this.mail.setRunner(runner);
+        this.invalidateControllers();
     }
     setSessionFactory(deps) {
         this.sessionDeps = deps;
+        this.invalidateControllers();
     }
     setLoopApi(deps) {
         this.loopApi = deps;
+        this.invalidateControllers();
+    }
+    /** Controllers are lazy snapshots of the injected deps; rebuild on re-wiring. */
+    invalidateControllers() {
+        this.loopController = null;
+        this.sessionController = null;
+    }
+    /**
+     * Transport-agnostic loop operations (shared with the Centrifugo RPC switch
+     * in index.ts). Null until setDependencies + setLoopApi have both run —
+     * index.ts wires them in one synchronous block, so no request can observe a
+     * half-wired server.
+     */
+    getLoopController() {
+        if (this.loopController)
+            return this.loopController;
+        const { store, runner, centrifugo, userId, loopApi } = this;
+        if (!store || !runner || !centrifugo || !userId || !loopApi)
+            return null;
+        this.loopController = new LoopController({
+            bridgeId: loopApi.bridgeId,
+            scheduler: loopApi.scheduler,
+            isSessionRunning: (sid) => runner.isRunning(sid),
+            publishLoopUpdate: (loop) => centrifugo.publishLoopUpdate(userId, loop),
+            publishLoopRemoved: (loopId) => centrifugo.publishLoopRemoved(userId, loopId),
+            listWireSessions: async () => (await store.listSessions()).map(toWireSession),
+            loadTerminalLog: (sid) => store.loadTerminalLog(sid),
+        });
+        return this.loopController;
+    }
+    /** Transport-agnostic session operations (shared with the RPC switch). */
+    getSessionController() {
+        if (this.sessionController)
+            return this.sessionController;
+        const { store, runner, centrifugo, userId } = this;
+        if (!store || !runner || !centrifugo || !userId)
+            return null;
+        this.sessionController = new SessionController({
+            store,
+            runner,
+            publishSessionUpdate: (session) => centrifugo.publishSessionUpdate(userId, session),
+            removeSession: (id, options) => removeFtownSession({ store, runner, centrifugo, userId }, id, options),
+            collectUsage: (session) => collectSessionUsage(session),
+            ...(this.sessionDeps ? { sessionFactory: this.sessionDeps } : {}),
+        });
+        return this.sessionController;
     }
     async start() {
         return new Promise((resolve, reject) => {
@@ -189,12 +203,7 @@ export class LocalApiServer extends EventEmitter {
         return this.server;
     }
     stop() {
-        for (const timer of this.nudgeTimers.values())
-            clearTimeout(timer);
-        this.nudgeTimers.clear();
-        for (const waiter of [...this.mailWaiters.values()])
-            waiter.deliver([]);
-        this.mailWaiters.clear();
+        this.mail.stop();
         if (this.server) {
             this.server.close();
             this.server = null;
@@ -245,7 +254,7 @@ export class LocalApiServer extends EventEmitter {
         }
         // GET /api/sessions
         if (path === '/api/sessions' && req.method === 'GET') {
-            const sessions = await this.store.listSessions();
+            const sessions = await (this.getSessionController()?.list() ?? this.store.listSessions());
             jsonResponse(res, 200, { sessions: sessions.map(toWireSession) });
             return;
         }
@@ -271,8 +280,13 @@ export class LocalApiServer extends EventEmitter {
                 });
                 return;
             }
+            const controller = this.getSessionController();
+            if (!controller) {
+                jsonResponse(res, 503, { error: 'Session factory not ready' });
+                return;
+            }
             try {
-                const session = await createFtownSession(this.sessionDeps, input);
+                const session = await controller.create(input);
                 jsonResponse(res, 201, { session: toWireSession(session) });
             }
             catch (err) {
@@ -320,154 +334,80 @@ export class LocalApiServer extends EventEmitter {
             jsonResponse(res, 200, { sessionId });
             return;
         }
-        // GET /api/loops — local CLI/skill parity with list_loops RPC.
-        if (path === '/api/loops' && req.method === 'GET') {
-            jsonResponse(res, 200, { loops: listLoops() });
-            return;
-        }
-        // POST /api/loops — create a loop owned by this bridge.
-        if (path === '/api/loops' && req.method === 'POST') {
-            if (!this.loopApi || !this.centrifugo || !this.userId) {
-                jsonResponse(res, 503, { error: 'Loop API not ready' });
-                return;
-            }
-            const body = await parseBody(req);
-            const payload = { ...body, bridgeId: this.loopApi.bridgeId };
-            const error = validateLoopDraft(payload);
-            if (error) {
-                jsonResponse(res, 400, { error });
-                return;
-            }
-            const draft = {
-                name: payload.name.trim(),
-                bridgeId: this.loopApi.bridgeId,
-                schedule: payload.schedule,
-                harness: payload.harness,
-                workdir: payload.workdir,
-                task: payload.task,
-                model: payload.model,
-                enabled: payload.enabled,
-                overlapPolicy: payload.overlapPolicy,
-                retention: payload.retention,
-                preflight: payload.preflight,
-                postflight: payload.postflight,
-                maxRuntimeMs: payload.maxRuntimeMs,
-                group: payload.group,
-            };
-            try {
-                const loop = createLoop(draft);
-                await this.centrifugo.publishLoopUpdate(this.userId, loop);
-                jsonResponse(res, 201, { loop });
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                jsonResponse(res, 400, { error: message });
-            }
-            return;
-        }
         const loopMatch = path.match(/^\/api\/loops\/([^/]+)$/);
         const loopRunNowMatch = path.match(/^\/api\/loops\/([^/]+)\/run-now$/);
         const loopRunsMatch = path.match(/^\/api\/loops\/([^/]+)\/runs$/);
-        // GET /api/loops/:id
-        if (loopMatch && req.method === 'GET') {
-            const loop = getLoop(loopMatch[1]);
-            if (!loop) {
-                jsonResponse(res, 404, { error: 'Loop not found' });
-                return;
-            }
-            jsonResponse(res, 200, { loop });
-            return;
-        }
-        // PATCH /api/loops/:id
-        if (loopMatch && req.method === 'PATCH') {
-            if (!this.centrifugo || !this.userId) {
+        const isLoopRoute = path === '/api/loops' || Boolean(loopMatch) || Boolean(loopRunNowMatch) || Boolean(loopRunsMatch);
+        if (isLoopRoute) {
+            const loops = this.getLoopController();
+            if (!loops) {
                 jsonResponse(res, 503, { error: 'Loop API not ready' });
                 return;
             }
-            const loopId = loopMatch[1];
-            const body = await parseBody(req);
-            const patch = body;
-            const error = validateLoopPatch(patch);
-            if (error) {
-                jsonResponse(res, 400, { error });
+            // GET /api/loops — local CLI/skill parity with list_loops RPC.
+            if (path === '/api/loops' && req.method === 'GET') {
+                jsonResponse(res, 200, { loops: loops.list() });
                 return;
             }
-            try {
-                const loop = updateLoop(loopId, patch);
-                if (!loop) {
-                    jsonResponse(res, 404, { error: 'Loop not found' });
+            // POST /api/loops — create a loop owned by this bridge.
+            if (path === '/api/loops' && req.method === 'POST') {
+                const body = await parseBody(req);
+                const result = await loops.create(body);
+                if (!result.ok) {
+                    jsonResponse(res, 400, { error: result.message });
                     return;
                 }
-                await this.centrifugo.publishLoopUpdate(this.userId, loop);
-                jsonResponse(res, 200, { loop });
-            }
-            catch (err) {
-                const message = err instanceof Error ? err.message : String(err);
-                jsonResponse(res, 400, { error: message });
-            }
-            return;
-        }
-        // DELETE /api/loops/:id
-        if (loopMatch && req.method === 'DELETE') {
-            if (!this.loopApi || !this.centrifugo || !this.userId) {
-                jsonResponse(res, 503, { error: 'Loop API not ready' });
+                jsonResponse(res, 201, { loop: result.loop });
                 return;
             }
-            const loopId = loopMatch[1];
-            const existingLoop = getLoop(loopId);
-            const removed = deleteLoop(loopId);
-            if (removed) {
-                if (existingLoop)
-                    this.loopApi.scheduler.onLoopDeleted(existingLoop);
-                deleteLoopRunRecords(loopId);
-                await this.centrifugo.publishLoopRemoved(this.userId, loopId);
+            // GET /api/loops/:id
+            if (loopMatch && req.method === 'GET') {
+                const result = loops.get(loopMatch[1]);
+                if (!result.ok) {
+                    jsonResponse(res, 404, { error: result.message });
+                    return;
+                }
+                jsonResponse(res, 200, { loop: result.loop });
+                return;
             }
-            jsonResponse(res, 200, { removed, loopId });
-            return;
-        }
-        // POST /api/loops/:id/run-now
-        if (loopRunNowMatch && req.method === 'POST') {
-            if (!this.loopApi || !this.runner || !this.centrifugo || !this.userId) {
-                jsonResponse(res, 503, { error: 'Loop API not ready' });
+            // PATCH /api/loops/:id
+            if (loopMatch && req.method === 'PATCH') {
+                const body = await parseBody(req);
+                const result = await loops.update(loopMatch[1], body);
+                if (!result.ok) {
+                    jsonResponse(res, result.code === 'not_found' ? 404 : 400, { error: result.message });
+                    return;
+                }
+                jsonResponse(res, 200, { loop: result.loop });
                 return;
             }
-            const loopId = loopRunNowMatch[1];
-            const loop = getLoop(loopId);
-            if (!loop) {
-                jsonResponse(res, 404, { error: 'Loop not found', fired: false, reason: 'not_found' });
+            // DELETE /api/loops/:id
+            if (loopMatch && req.method === 'DELETE') {
+                const loopId = loopMatch[1];
+                const { removed } = await loops.delete(loopId);
+                jsonResponse(res, 200, { removed, loopId });
                 return;
             }
-            if (loop.overlapPolicy === 'skip' &&
-                loop.lastStatus === 'running' &&
-                loop.lastSessionId &&
-                this.runner.isRunning(loop.lastSessionId)) {
-                jsonResponse(res, 200, { fired: false, reason: 'overlap' });
+            // POST /api/loops/:id/run-now
+            if (loopRunNowMatch && req.method === 'POST') {
+                const outcome = await loops.runNow(loopRunNowMatch[1]);
+                if (!outcome.fired) {
+                    if (outcome.reason === 'not_found') {
+                        jsonResponse(res, 404, { error: 'Loop not found', fired: false, reason: 'not_found' });
+                        return;
+                    }
+                    jsonResponse(res, 200, { fired: false, reason: 'overlap' });
+                    return;
+                }
+                jsonResponse(res, 200, { fired: true, loop: outcome.loop });
                 return;
             }
-            // Reload-check-write via mutateLoopRuntime: if the loop was deleted
-            // between the getLoop() above and this write, this returns null and
-            // nothing is written/published — a stale in-memory snapshot must never
-            // be upserted back, or a deleted loop resurrects.
-            const updated = mutateLoopRuntime(loopId, (l) => {
-                l.runNowRequested = true;
-                l.updatedAt = new Date().toISOString();
-            });
-            if (!updated) {
-                jsonResponse(res, 404, { error: 'Loop not found', fired: false, reason: 'not_found' });
+            // GET /api/loops/:id/runs
+            if (loopRunsMatch && req.method === 'GET') {
+                jsonResponse(res, 200, { runs: await loops.runs(loopRunsMatch[1]) });
                 return;
             }
-            await this.centrifugo.publishLoopUpdate(this.userId, updated);
-            this.loopApi.scheduler.kick();
-            jsonResponse(res, 200, { fired: true, loop: updated });
-            return;
-        }
-        // GET /api/loops/:id/runs
-        if (loopRunsMatch && req.method === 'GET') {
-            const loopId = loopRunsMatch[1];
-            const store = this.store;
-            const sessions = (await store.listSessions()).map(toWireSession);
-            const runs = await listLoopRunRecordsWithFallback(loopId, sessions, (sessionId) => store.loadTerminalLog(sessionId));
-            jsonResponse(res, 200, { runs });
+            jsonResponse(res, 404, { error: 'Not found' });
             return;
         }
         const sessionMatch = path.match(/^\/api\/sessions\/([^/]+)$/);
@@ -479,10 +419,11 @@ export class LocalApiServer extends EventEmitter {
         const sessionInboxMatch = path.match(/^\/api\/sessions\/([^/]+)\/inbox$/);
         const sessionResizeMatch = path.match(/^\/api\/sessions\/([^/]+)\/resize$/);
         const sessionRunningMatch = path.match(/^\/api\/sessions\/([^/]+)\/running$/);
+        const sessionUsageMatch = path.match(/^\/api\/sessions\/([^/]+)\/usage$/);
         // GET /api/sessions/:id
         if (sessionMatch && req.method === 'GET') {
             const sessionId = sessionMatch[1];
-            const session = await this.store.loadSession(sessionId);
+            const session = await (this.getSessionController()?.get(sessionId) ?? this.store.loadSession(sessionId));
             if (!session) {
                 jsonResponse(res, 404, { error: 'Session not found' });
                 return;
@@ -493,16 +434,17 @@ export class LocalApiServer extends EventEmitter {
         // DELETE /api/sessions/:id — remove the session (archived as a tombstone)
         if (sessionMatch && req.method === 'DELETE') {
             const sessionId = sessionMatch[1];
-            if (!this.runner || !this.centrifugo || !this.userId) {
+            const controller = this.getSessionController();
+            if (!controller) {
                 jsonResponse(res, 503, { error: 'Server not ready' });
                 return;
             }
-            const session = await this.store.loadSession(sessionId);
+            const session = await controller.get(sessionId);
             if (!session) {
                 jsonResponse(res, 404, { error: 'Session not found' });
                 return;
             }
-            await removeFtownSession({ store: this.store, runner: this.runner, centrifugo: this.centrifugo, userId: this.userId }, sessionId);
+            await controller.remove(sessionId);
             jsonResponse(res, 200, { removed: true, sessionId });
             return;
         }
@@ -542,27 +484,12 @@ export class LocalApiServer extends EventEmitter {
             const parentSessionId = tombstone.parentSessionId
                 ? (await this.store.loadSession(tombstone.parentSessionId)) ? tombstone.parentSessionId : undefined
                 : undefined;
-            // Custom-command sessions (command override at create time) must rerun
+            // Custom-command tombstones (command override at create time) must rerun
             // their command verbatim — the builder would silently swap in a stock
-            // claude session. Builder-generated commands are rebuilt instead so the
-            // tombstone's agent session id is injected as --resume (matching
-            // resurrectSession's heuristic).
-            const builderDefault = buildSessionCommand({
-                shellType: tombstone.shellType,
-                workingDir: tombstone.workingDir,
-                model: tombstone.model,
-            });
-            const builderResume = buildSessionCommand({
-                shellType: tombstone.shellType,
-                workingDir: tombstone.workingDir,
-                model: tombstone.model,
-                claudeSessionId: tombstone.claudeSessionId,
-                cursorSessionId: tombstone.cursorSessionId,
-                codexSessionId: tombstone.codexSessionId,
-            });
-            const isCustomCommand = Boolean(tombstone.command)
-                && tombstone.command !== builderDefault
-                && tombstone.command !== builderResume;
+            // claude session. Builder-generated commands are rebuilt by
+            // createFtownSession instead, so the tombstone's agent session id is
+            // injected as --resume. The classification lives in the session module.
+            const { isCustom: isCustomCommand } = deriveRelaunchCommand(tombstone);
             try {
                 const session = await createFtownSession(this.sessionDeps, {
                     command: isCustomCommand ? tombstone.command : undefined,
@@ -599,56 +526,30 @@ export class LocalApiServer extends EventEmitter {
             }
             return;
         }
-        // PATCH /api/sessions/:id
+        // PATCH /api/sessions/:id — rename and/or reparent
         if (sessionMatch && req.method === 'PATCH') {
             const sessionId = sessionMatch[1];
             const body = await parseBody(req);
             const name = body.name;
             const hasParentField = Object.prototype.hasOwnProperty.call(body, 'parentSessionId');
-            const rawParent = body.parentSessionId;
             if (name === undefined && !hasParentField) {
                 jsonResponse(res, 400, { error: 'Nothing to update' });
                 return;
             }
-            const session = await this.store.loadSession(sessionId);
-            if (!session) {
-                jsonResponse(res, 404, { error: 'Session not found' });
+            const controller = this.getSessionController();
+            if (!controller) {
+                jsonResponse(res, 503, { error: 'Server not ready' });
                 return;
             }
-            if (name !== undefined) {
-                if (typeof name !== 'string' || !name) {
-                    jsonResponse(res, 400, { error: 'Invalid name' });
-                    return;
-                }
-                session.name = name;
-            }
-            if (hasParentField) {
-                if (rawParent === null || rawParent === '' || rawParent === undefined) {
-                    session.parentSessionId = undefined;
-                }
-                else if (typeof rawParent !== 'string') {
-                    jsonResponse(res, 400, { error: 'Invalid parentSessionId' });
-                    return;
-                }
-                else if (rawParent === sessionId) {
-                    jsonResponse(res, 400, { error: 'Session cannot be its own parent' });
-                    return;
-                }
-                else {
-                    const proposed = await this.store.loadSession(rawParent);
-                    if (!proposed) {
-                        jsonResponse(res, 400, { error: 'Parent session not found' });
-                        return;
-                    }
-                    session.parentSessionId = proposed.parentSessionId ?? proposed.id;
-                }
-            }
-            session.updatedAt = new Date().toISOString();
-            await this.store.saveSession(session);
-            if (this.centrifugo && this.userId) {
-                await this.centrifugo.publishSessionUpdate(this.userId, session);
+            const result = await controller.update(sessionId, {
+                ...(name === undefined ? {} : { name }),
+                ...(hasParentField ? { parent: { value: body.parentSessionId } } : {}),
+            });
+            if (!result.ok) {
+                jsonResponse(res, result.code === 'not_found' ? 404 : 400, { error: result.message });
+                return;
             }
-            jsonResponse(res, 200, { session: toWireSession(session) });
+            jsonResponse(res, 200, { session: toWireSession(result.session) });
             return;
         }
         // GET /api/sessions/:id/screen
@@ -801,7 +702,7 @@ export class LocalApiServer extends EventEmitter {
                 if (fromSession)
                     sender = fromSession.name || from.slice(0, 8);
             }
-            const wrote = await this.injectPtyLine(session, sender, text);
+            const wrote = await this.mail.injectPtyLine(session, sender, text);
             if (!wrote) {
                 jsonResponse(res, 409, { error: 'Session not running' });
                 return;
@@ -841,6 +742,21 @@ export class LocalApiServer extends EventEmitter {
             jsonResponse(res, 200, { resized: true });
             return;
         }
+        // GET /api/sessions/:id/usage — per-session token/cost usage
+        if (sessionUsageMatch && req.method === 'GET') {
+            const controller = this.getSessionController();
+            if (!controller) {
+                jsonResponse(res, 503, { error: 'Server not ready' });
+                return;
+            }
+            const result = await controller.usage(sessionUsageMatch[1]);
+            if (!result.ok) {
+                jsonResponse(res, 404, { error: result.message });
+                return;
+            }
+            jsonResponse(res, 200, { usage: result.usage });
+            return;
+        }
         // GET /api/sessions/:id/running
         if (sessionRunningMatch && req.method === 'GET') {
             const sessionId = sessionRunningMatch[1];
@@ -855,25 +771,8 @@ export class LocalApiServer extends EventEmitter {
         }
         jsonResponse(res, 404, { error: 'Not found' });
     }
-    // Plain shells would execute the message as a command; deliver it as a quoted no-op
-    // (`: '...'`) — interactive zsh has no '#' comments by default.
-    async injectPtyLine(session, sender, text) {
-        if (!this.runner)
-            return false;
-        const isAgent = session.shellType && session.shellType !== 'shell';
-        const line = isAgent
-            ? `[ftown msg from ${sender}] ${text}`
-            : `: '[ftown msg from ${sender}] ${text.replace(/'/g, '')}'`;
-        if (!this.runner.write(session.id, line))
-            return false;
-        // Composer TUIs detect pastes by input arrival rate; the submit CR must come well
-        // after that window or it is treated as a pasted newline.
-        await delay(600);
-        this.runner.write(session.id, submitSuffixFor(session.shellType));
-        return true;
-    }
     async handleInboxPost(req, res, sessionId) {
-        if (!this.store || !this.mailStore) {
+        if (!this.store || !this.mail.isReady()) {
             jsonResponse(res, 503, { error: 'Mail store not ready' });
             return;
         }
@@ -883,182 +782,39 @@ export class LocalApiServer extends EventEmitter {
             return;
         }
         const body = await parseBody(req);
-        const text = body.body;
-        if (typeof text !== 'string' || !text.trim()) {
-            jsonResponse(res, 400, { error: 'Missing body' });
+        const result = await this.mail.acceptMail(session, body);
+        if (!result.ok) {
+            jsonResponse(res, 400, { error: result.error });
             return;
         }
-        if (text.length > MAX_MAIL_BODY_LENGTH) {
-            jsonResponse(res, 400, { error: `Body too long (max ${MAX_MAIL_BODY_LENGTH} chars)` });
-            return;
-        }
-        let type = 'message';
-        if (body.type !== undefined) {
-            if (typeof body.type !== 'string' || !MAIL_TYPES.includes(body.type)) {
-                jsonResponse(res, 400, { error: `Invalid type (expected one of: ${MAIL_TYPES.join(', ')})` });
-                return;
-            }
-            type = body.type;
-        }
-        const from = typeof body.from === 'string' && body.from.trim() ? body.from.trim() : 'external';
-        const fromName = typeof body.fromName === 'string' && body.fromName.trim() ? body.fromName.trim() : undefined;
-        const threadId = typeof body.threadId === 'string' && body.threadId.trim() ? body.threadId.trim() : undefined;
-        const msg = createMailMessage({ from, fromName, to: session.id, type, threadId, body: text });
-        await this.mailStore.append(msg);
-        const waiter = this.mailWaiters.get(session.id);
-        if (waiter) {
-            const undelivered = await this.mailStore.listUndelivered(session.id);
-            const marked = await this.mailStore.markDelivered(session.id, undelivered.map((m) => m.id), 'poll');
-            waiter.deliver(marked);
-        }
-        else {
-            const nudgeDelay = HOOKED_SHELL_TYPES.has(session.shellType ?? 'claude')
-                ? MAIL_NUDGE_DELAY_HOOKED_MS
-                : MAIL_NUDGE_DELAY_MS;
-            this.scheduleMailNudge(session.id, fromName ?? from, nudgeDelay);
-        }
-        jsonResponse(res, 201, { id: msg.id });
+        jsonResponse(res, 201, { id: result.id });
     }
     async handleInboxGet(res, sessionId, url) {
-        if (!this.store || !this.mailStore) {
+        if (!this.store || !this.mail.isReady()) {
             jsonResponse(res, 503, { error: 'Mail store not ready' });
             return;
         }
-        const mailStore = this.mailStore;
         const session = await this.store.loadSession(sessionId);
         if (!session) {
             jsonResponse(res, 404, { error: 'Session not found' });
             return;
         }
-        const wait = Math.min(getQueryInt(url, 'wait', 0), MAX_MAIL_WAIT_SECONDS);
-        const peek = getQueryInt(url, 'peek', 0) === 1;
-        const all = url.searchParams.get('all') === '1';
-        const limit = getQueryInt(url, 'limit', 50);
-        if (peek) {
-            const messages = all
-                ? await mailStore.listAll(session.id, limit)
-                : await mailStore.listUndelivered(session.id);
-            jsonResponse(res, 200, { messages });
-            return;
-        }
-        // The listen window is earned, not universal: a session with no mail
-        // relationships (no parent, no children, not an orchestrator) gets an
-        // instant stop instead of holding its Stop hook open for `wait` seconds.
-        // Late mail for everyone is still covered by the idle nudge.
-        let effectiveWait = wait;
-        if (wait > 0 && !(await this.participatesInMail(session))) {
-            effectiveWait = 0;
-        }
-        const undelivered = await mailStore.listUndelivered(session.id);
-        if (undelivered.length > 0 || effectiveWait <= 0) {
-            const marked = await mailStore.markDelivered(session.id, undelivered.map((m) => m.id), effectiveWait > 0 ? 'poll' : 'drain');
-            jsonResponse(res, 200, { messages: marked });
-            return;
-        }
-        // Long poll: hold until mail arrives or `wait` seconds elapse. One waiter
-        // per session — a newer waiter resolves the previous one with [].
-        const existing = this.mailWaiters.get(session.id);
-        if (existing)
-            existing.deliver([]);
-        let settled = false;
-        const waiter = {
-            deliver: (messages) => {
-                if (settled)
-                    return;
-                settled = true;
-                clearTimeout(timer);
-                if (this.mailWaiters.get(session.id) === waiter) {
-                    this.mailWaiters.delete(session.id);
-                }
-                jsonResponse(res, 200, { messages });
-            },
-        };
-        const timer = setTimeout(() => {
-            // Guard each async step on settled: once the client disconnects (or a new
-            // waiter replaced this one) we must not mark messages delivered — they
-            // would be lost without ever reaching a session.
-            if (settled || this.mailWaiters.get(session.id) !== waiter)
-                return;
-            mailStore
-                .listUndelivered(session.id)
-                .then((pending) => {
-                if (settled || pending.length === 0)
-                    return [];
-                return mailStore.markDelivered(session.id, pending.map((m) => m.id), 'poll');
-            })
-                .then((marked) => waiter.deliver(marked))
-                .catch(() => waiter.deliver([]));
-        }, effectiveWait * 1000);
-        this.mailWaiters.set(session.id, waiter);
-        res.on('close', () => {
-            if (this.mailWaiters.get(session.id) !== waiter)
-                return;
-            settled = true;
-            clearTimeout(timer);
-            this.mailWaiters.delete(session.id);
+        const result = await this.mail.readMail(session, {
+            wait: getQueryInt(url, 'wait', 0),
+            peek: getQueryInt(url, 'peek', 0) === 1,
+            all: url.searchParams.get('all') === '1',
+            limit: getQueryInt(url, 'limit', 50),
         });
-    }
-    // Debounced wake-up for mail that no long-poll consumed: after 5s, if it is still
-    // undelivered and the session is running, inject a one-line pointer to the
-    // harness mail command. At most one nudge per session per 30s; senders coalesce.
-    scheduleMailNudge(sessionId, fromLabel, delayMs = MAIL_NUDGE_DELAY_MS) {
-        this.pendingNudgeFrom.set(sessionId, fromLabel);
-        if (this.nudgeTimers.has(sessionId))
-            return;
-        const timer = setTimeout(() => {
-            this.nudgeTimers.delete(sessionId);
-            this.fireMailNudge(sessionId).catch((err) => {
-                console.error('[LocalApiServer] Mail nudge failed:', err instanceof Error ? err.message : String(err));
-            });
-        }, delayMs);
-        timer.unref();
-        this.nudgeTimers.set(sessionId, timer);
-    }
-    /** A session earns the Stop-hook listen window only if mail can plausibly
-     *  arrive: it has a parent, has children, was marked an orchestrator, or has
-     *  exchanged mail before. */
-    async participatesInMail(session) {
-        if (session.parentSessionId)
-            return true;
-        if (session.env?.FTOWN_ORCHESTRATOR === '1')
-            return true;
-        if (!this.store || !this.mailStore)
-            return false;
-        const sessions = await this.store.listSessions();
-        if (sessions.some((s) => s.parentSessionId === session.id))
-            return true;
-        const history = await this.mailStore.listAll(session.id, 1);
-        return history.length > 0;
-    }
-    async fireMailNudge(sessionId) {
-        if (!this.store || !this.mailStore || !this.runner)
-            return;
-        const fromLabel = this.pendingNudgeFrom.get(sessionId) ?? 'ftown';
-        const undelivered = await this.mailStore.listUndelivered(sessionId);
-        if (undelivered.length === 0) {
-            this.pendingNudgeFrom.delete(sessionId);
+        if (result.kind === 'immediate') {
+            jsonResponse(res, 200, { messages: result.messages });
             return;
         }
-        const busySince = this.agentBusySince.get(sessionId);
-        if (busySince !== undefined && Date.now() - busySince < AGENT_BUSY_STALE_MS) {
-            this.scheduleMailNudge(sessionId, fromLabel, MAIL_NUDGE_BUSY_RECHECK_MS);
-            return;
-        }
-        const sinceLast = Date.now() - (this.lastNudgeAt.get(sessionId) ?? 0);
-        if (sinceLast < MAIL_NUDGE_MIN_INTERVAL_MS) {
-            // Rate-limited: retry once the window reopens (mail may still be unread).
-            this.scheduleMailNudge(sessionId, fromLabel, MAIL_NUDGE_MIN_INTERVAL_MS - sinceLast);
-            return;
-        }
-        this.pendingNudgeFrom.delete(sessionId);
-        if (!this.runner.isRunning(sessionId))
-            return;
-        const session = await this.store.loadSession(sessionId);
-        if (!session)
-            return;
-        this.lastNudgeAt.set(sessionId, Date.now());
-        const text = sanitizeMessageText(`You have new ftown mail from ${fromLabel} — run \`~/.ftown/bin/ftown-harness mail read\` to read it.`);
-        await this.injectPtyLine(session, 'ftown-mail', text);
+        // Long poll: the promise resolves when mail arrives or the wait elapses.
+        // On client disconnect abandon the waiter — the promise then never resolves
+        // and no response is written (the socket is gone anyway).
+        res.on('close', result.abandon);
+        const messages = await result.messages;
+        jsonResponse(res, 200, { messages });
     }
     handleHook(req, res) {
         const chunks = [];
@@ -1086,10 +842,10 @@ export class LocalApiServer extends EventEmitter {
                     return;
                 }
                 if (hookEventName === 'UserPromptSubmit' || hookEventName === 'PreToolUse' || hookEventName === 'PostToolUse') {
-                    this.agentBusySince.set(ftownSessionId, Date.now());
+                    this.mail.markAgentBusy(ftownSessionId);
                 }
                 else if (hookEventName === 'Stop' || hookEventName === 'SessionEnd') {
-                    this.agentBusySince.delete(ftownSessionId);
+                    this.mail.markAgentIdle(ftownSessionId);
                 }
                 const conversationId = payload.conversation_id;
                 // Workspace attribution may belong to a foreign agent running in the