@lelouchhe/webagent 0.3.0 → 0.4.0

package/lib/routes.js

@@ -1,10 +1,22 @@
-import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir, rename, unlink, realpath } from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { join, extname } from "node:path";
+import { join, extname, basename } from "node:path";
 import { gzipSync } from "node:zlib";
-import { Store } from "./store.js";
-import { errorMessage } from "./types.js";
+import busboy from "busboy";
+import { errorMessage, MessageIngressSchema } from "./types.js";
 import { interruptBashProc } from "./session-manager.js";
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { handleShareRoutes } from "./share/routes.js";
+import { authenticate, isWhitelistedPath } from "./auth-middleware.js";
+import { enrichStoredEventsForDisplay } from "./attachment-labels.js";
+import { log } from "./log.js";
+const rlog = log.scope("routes");
+const plog = rlog.scope("prompt");
+const slog = rlog.scope("session");
+const mlog = rlog.scope("msg");
+import { signAttachmentUrl, verifyAttachmentSig, reSignAttachmentUrlsInJson, } from "./auth.js";
+import { buildContentDisposition, classifyKind, isInlineMime, mimeToExt, normalizeDisplayName, sniffMime, } from "./attachments.js";
 const IS_WIN = process.platform === "win32";
 const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
 const MIME = {
@@ -19,19 +31,91 @@ const MIME = {
     ".gif": "image/gif",
     ".webp": "image/webp",
 };
+/**
+ * HTML entrypoints served by this app. Any new HTML page MUST be registered
+ * here. Tests in `test/html-entrypoints.test.ts`, `test/csp.test.ts` and
+ * `test/inline-assets.test.ts` rely on this list to enforce security
+ * invariants (CSP header, no inline scripts/styles).
+ */
+export const HTML_ENTRYPOINTS = [
+    { urlPath: "/", file: "index.html" },
+    { urlPath: "/login", file: "login.html" },
+    // Share viewer — served by share's own dispatcher at /s/:token
+    // (see src/share/routes.ts → handleViewerHtml). The urlPath here is a
+    // pseudo-path used only by the test invariants (CSP/inline checks); the
+    // real route is /s/:token. Keep both views in sync if either changes.
+    { urlPath: "/s", file: "share-viewer.html" },
+];
+/**
+ * Strict Content-Security-Policy for HTML responses.
+ *
+ *  - default-src 'self': everything same-origin only
+ *  - img-src adds data: + blob: for image-upload preview
+ *  - script-src 'self' (no inline; theme bootstrap is /theme-init.js)
+ *  - style-src 'self' (no inline; login styles live in /styles.css)
+ *  - object-src 'none', frame-ancestors 'none', base-uri 'self', form-action 'self'
+ *  - connect-src 'self' for fetch + EventSource
+ */
+export const CSP_POLICY = [
+    "default-src 'self'",
+    "img-src 'self' data: blob:",
+    "script-src 'self'",
+    "style-src 'self'",
+    "connect-src 'self'",
+    "object-src 'none'",
+    "frame-ancestors 'none'",
+    "base-uri 'self'",
+    "form-action 'self'",
+].join("; ");
 /** Read the full request body as a string. */
 function readBody(req) {
     return new Promise((resolve, reject) => {
         const chunks = [];
         req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => resolve(Buffer.concat(chunks).toString()));
+        req.on("end", () => {
+            resolve(Buffer.concat(chunks).toString());
+        });
         req.on("error", reject);
     });
 }
+/**
+ * client-server-split M2: idempotency helpers for mutating REST.
+ * Frontend generates a UUID per user-initiated action and sends it as
+ * `X-Client-Op-Id`. Replays (after SSE/network reconnect) return the
+ * cached response instead of re-executing side effects. Missing header →
+ * non-idempotent path (back-compat for curl / older clients).
+ */
+function getClientOpId(req) {
+    const v = req.headers["x-client-op-id"];
+    if (typeof v === "string" && v.length > 0 && v.length <= 128)
+        return v;
+    return null;
+}
+function tryReplayClientOp(req, res, store, sessionId) {
+    const opId = getClientOpId(req);
+    if (!opId)
+        return { opId: null, replayed: false };
+    const cached = store.getClientOp(sessionId, opId);
+    if (cached &&
+        typeof cached === "object" &&
+        "status" in cached &&
+        "body" in cached) {
+        json(res, cached.status, cached.body, req);
+        return { opId, replayed: true };
+    }
+    return { opId, replayed: false };
+}
+function saveClientOpResult(store, opId, sessionId, status, body) {
+    if (!opId)
+        return;
+    store.saveClientOp(sessionId, opId, { status, body });
+}
 /** Send a JSON response, gzip-compressed when the client supports it. */
 function json(res, status, data, req) {
     const body = JSON.stringify(data);
-    if (req && body.length > 1024 && (req.headers["accept-encoding"] || "").includes("gzip")) {
+    if (req &&
+        body.length > 1024 &&
+        (req.headers["accept-encoding"] ?? "").includes("gzip")) {
         const compressed = gzipSync(body);
         res.writeHead(status, {
             "Content-Type": "application/json",
@@ -45,10 +129,274 @@ function json(res, status, data, req) {
         res.end(body);
     }
 }
+/** Per-request principal storage. WeakMap keeps it tied to the request lifetime
+ *  without monkey-patching IncomingMessage or relying on `any`. */
+const principalByRequest = new WeakMap();
+export function getPrincipal(req) {
+    return principalByRequest.get(req);
+}
+/**
+ * Multipart upload handler. Streams the `file` field straight to disk under
+ * <data_dir>/sessions/<sid>/attachments/<uuid>.<ext>.tmp, atomic-renames on
+ * success, deletes on any failure path. Inserts an attachments row with the
+ * resolved realpath so the bridge / permission interceptor can match it
+ * later.
+ *
+ * Wire format expected:
+ *   - Content-Type: multipart/form-data; boundary=...
+ *   - One file field named `file` (additional file fields are rejected).
+ *   - Optional text fields are ignored — displayName comes from the file
+ *     part's filename header, classification comes from its content-type.
+ */
+async function handleAttachmentUpload(req, res, sessionId, deps) {
+    const { store, dataDir, limits, sessions } = deps;
+    const fileUploadLimit = limits.file_upload ?? 52_428_800;
+    if (!store.getSession(sessionId)) {
+        json(res, 404, { error: "Session not found" });
+        return;
+    }
+    const dir = join(dataDir, "sessions", sessionId, "attachments");
+    await mkdir(dir, { recursive: true });
+    const uploadId = randomUUID();
+    let tmpPath = null;
+    let finalPath = null;
+    let bytesWritten = 0;
+    let fileMime = "";
+    let fileExt = "bin";
+    let displayName = null;
+    let kind = "file";
+    let limit = Math.max(limits.image_upload, fileUploadLimit);
+    let limitExceeded = false;
+    let sawFile = false;
+    let aborted = false;
+    let writeError = null;
+    let resolved = false;
+    // Resolves when the write stream backing the file part has flushed and
+    // closed. busboy's `close` can fire before fs has finished writing the
+    // last chunk to disk, so we must await this before renaming the .tmp.
+    let writeDone = Promise.resolve();
+    // Single-shot response. We only ever respond to the request once even
+    // though multiple busboy callbacks could converge on the same outcome
+    // (e.g. file-too-large + close-after-finish).
+    const respond = (status, body) => {
+        if (resolved)
+            return;
+        resolved = true;
+        json(res, status, body);
+    };
+    const cleanupTmp = async () => {
+        if (tmpPath) {
+            await unlink(tmpPath).catch(() => { });
+            tmpPath = null;
+        }
+    };
+    return new Promise((resolveOuter) => {
+        const finish = async (status, body) => {
+            respond(status, body);
+            resolveOuter();
+        };
+        let bb;
+        try {
+            bb = busboy({
+                headers: req.headers,
+                defParamCharset: "utf8",
+                limits: {
+                    // We enforce the size cap manually via per-file byte tracking
+                    // (so we can pick the right cap based on classified kind and
+                    // emit a 413 the moment we cross the line). Cap files = 1
+                    // and field count = 16 as belt-and-suspenders.
+                    files: 1,
+                    fields: 16,
+                    fieldNameSize: 100,
+                    fieldSize: 1024,
+                },
+            });
+        }
+        catch {
+            void finish(400, { error: "Invalid multipart" });
+            return;
+        }
+        bb.on("file", (fieldName, stream, info) => {
+            if (sawFile) {
+                // Extra file part — drain and ignore (busboy `files: 1` should
+                // already prevent this, but be defensive).
+                stream.resume();
+                return;
+            }
+            sawFile = true;
+            if (fieldName !== "file") {
+                stream.resume();
+                void finish(400, { error: "Unexpected field name" });
+                return;
+            }
+            fileMime = (info.mimeType || "application/octet-stream").toLowerCase();
+            kind = classifyKind(fileMime);
+            limit = kind === "image" ? limits.image_upload : fileUploadLimit;
+            fileExt = mimeToExt(fileMime);
+            displayName = info.filename ? normalizeDisplayName(info.filename) : null;
+            displayName ??= kind === "image" ? "image" : "file";
+            tmpPath = join(dir, `${uploadId}.${fileExt}.tmp`);
+            finalPath = join(dir, `${uploadId}.${fileExt}`);
+            const ws = createWriteStream(tmpPath);
+            writeDone = new Promise((resolveWs) => {
+                ws.on("close", () => {
+                    resolveWs();
+                });
+            });
+            stream.on("data", (chunk) => {
+                bytesWritten += chunk.length;
+                if (bytesWritten > limit) {
+                    limitExceeded = true;
+                    stream.unpipe(ws);
+                    ws.destroy();
+                    stream.resume();
+                    // Abort the whole busboy pipeline. We respond on `close`.
+                    req.unpipe(bb);
+                    req.resume();
+                }
+            });
+            stream.on("error", (err) => {
+                writeError = err;
+            });
+            ws.on("error", (err) => {
+                writeError = err;
+            });
+            stream.pipe(ws);
+        });
+        bb.on("error", (err) => {
+            writeError = err instanceof Error ? err : new Error(String(err));
+        });
+        req.on("aborted", () => {
+            aborted = true;
+        });
+        bb.on("close", () => {
+            void (async () => {
+                try {
+                    await writeDone;
+                    if (aborted) {
+                        await cleanupTmp();
+                        await finish(400, { error: "Upload aborted" });
+                        return;
+                    }
+                    if (limitExceeded) {
+                        await cleanupTmp();
+                        await finish(413, { error: "Upload too large" });
+                        return;
+                    }
+                    if (writeError) {
+                        await cleanupTmp();
+                        await finish(500, { error: "Upload failed" });
+                        return;
+                    }
+                    if (!sawFile || !tmpPath || !finalPath || !displayName) {
+                        await cleanupTmp();
+                        await finish(400, { error: "Missing file part" });
+                        return;
+                    }
+                    // Sniff the actual mime from file content (magic bytes + UTF-8
+                    // text fallback). Clients lie about Content-Type — browsers send
+                    // application/octet-stream for any extension the OS doesn't know
+                    // (.clj, .lua, .rs, ...), and ACP agents (Copilot CLI) refuse to
+                    // read attachments tagged octet-stream. The sniffed mime wins
+                    // silently; we override fileMime / kind / extension / final path
+                    // before insertAttachment so DB and disk reflect reality.
+                    const head = await readFile(tmpPath).catch(() => Buffer.alloc(0));
+                    const headSlice = head.subarray(0, 4096);
+                    const sniffed = await sniffMime(headSlice);
+                    if (sniffed !== fileMime) {
+                        fileMime = sniffed;
+                        kind = classifyKind(fileMime);
+                        const newExt = mimeToExt(fileMime);
+                        if (newExt !== fileExt) {
+                            fileExt = newExt;
+                            const newTmp = join(dir, `${uploadId}.${fileExt}.tmp`);
+                            if (newTmp !== tmpPath) {
+                                await rename(tmpPath, newTmp);
+                                tmpPath = newTmp;
+                            }
+                            finalPath = join(dir, `${uploadId}.${fileExt}`);
+                        }
+                    }
+                    await rename(tmpPath, finalPath);
+                    const rp = await realpath(finalPath);
+                    const row = store.insertAttachment({
+                        id: uploadId,
+                        sessionId,
+                        kind,
+                        name: displayName,
+                        mime: fileMime,
+                        size: bytesWritten,
+                        realpath: rp,
+                    });
+                    // Invalidate the per-session attachment label cache so the
+                    // next egress (SSE broadcast or replay) sees this new row.
+                    sessions?.invalidateLabelCache(sessionId);
+                    const fileName = `${row.id}.${fileExt}`;
+                    const basePath = `/api/v1/sessions/${sessionId}/attachments/${fileName}`;
+                    // 1h signed URL — long enough that the browser holds the rendered
+                    // image in <img> cache for the full session lifetime, short enough
+                    // that a leaked URL (screenshot, link share) expires within the day.
+                    const fileUrl = deps.attachmentSecret
+                        ? `${basePath}?${signAttachmentUrl(basePath, deps.attachmentSecret, 3600)}`
+                        : basePath;
+                    await finish(200, {
+                        attachmentId: row.id,
+                        displayName: row.name,
+                        mimeType: row.mime,
+                        size: row.size,
+                        kind: row.kind,
+                        path: `sessions/${sessionId}/attachments/${fileName}`,
+                        url: fileUrl,
+                    });
+                }
+                catch (err) {
+                    await cleanupTmp();
+                    await finish(500, { error: errorMessage(err) });
+                }
+            })();
+        });
+        req.pipe(bb);
+    });
+}
 export function createRequestHandler(deps) {
     const { store, sessions, getBridge, sseManager, titleService } = deps;
+    // eslint-disable-next-line complexity -- TODO: refactor main route handler into smaller handlers
     return async (req, res) => {
         const url = req.url ?? "/";
+        // --- Auth gate: any /api/** outside whitelist requires Bearer ---
+        if (deps.authStore && url.startsWith("/api/")) {
+            const path = url.split("?")[0] ?? url;
+            const method = req.method ?? "GET";
+            if (!isWhitelistedPath(method, path)) {
+                const result = authenticate(req.headers, deps.authStore);
+                if (!result.ok) {
+                    res.writeHead(401, {
+                        "Content-Type": "application/json",
+                        "WWW-Authenticate": "Bearer",
+                    });
+                    res.end(JSON.stringify({ error: "Unauthorized", reason: result.reason }));
+                    return;
+                }
+                principalByRequest.set(req, result.principal);
+            }
+        }
+        // Share routes — early dispatch so /s/* and /api/v1/shares* claim
+        // their URL space before the generic /api/v1 branch. When
+        // `shareConfig.enabled === false` handleShareRoutes is a no-op.
+        // The auth gate above has already enforced Bearer on owner endpoints
+        // (/api/v1/sessions/:id/share*, /api/v1/shares); viewer endpoints
+        // (/s/:token, /api/v1/shared/:token/events) must be whitelisted in
+        // auth-middleware.ts so they remain public.
+        if (deps.shareConfig &&
+            (await handleShareRoutes(req, res, {
+                store,
+                sessions,
+                config: deps.shareConfig,
+                dataDir: deps.dataDir,
+                publicDir: deps.publicDir,
+            }))) {
+            return;
+        }
         // --- API routes ---
         if (url === "/api/v1" || url.startsWith("/api/v1/")) {
             res.setHeader("Content-Type", "application/json");
@@ -69,7 +417,9 @@ export function createRequestHandler(deps) {
                 return;
             }
             // GET /api/v1/sessions
-            if (url.startsWith("/api/v1/sessions") && !url.slice("/api/v1/sessions".length).match(/^\//) && req.method === "GET") {
+            if (url.startsWith("/api/v1/sessions") &&
+                !url.slice("/api/v1/sessions".length).match(/^\//) &&
+                req.method === "GET") {
                 const params = new URLSearchParams(url.split("?")[1] ?? "");
                 const source = params.get("source") ?? undefined;
                 res.end(JSON.stringify(store.listSessions(source ? { source } : undefined)));
@@ -105,6 +455,136 @@ export function createRequestHandler(deps) {
                 });
                 return;
             }
+            // GET /api/v1/auth/verify — token validation probe
+            if (url === "/api/v1/auth/verify" && req.method === "GET") {
+                const principal = principalByRequest.get(req);
+                if (!principal) {
+                    json(res, 401, { error: "Unauthorized" });
+                    return;
+                }
+                json(res, 200, {
+                    ok: true,
+                    name: principal.name,
+                    scope: principal.scope,
+                });
+                return;
+            }
+            // POST /api/v1/sse-ticket — mint short-lived ticket for EventSource
+            if (url === "/api/v1/sse-ticket" && req.method === "POST") {
+                const principal = principalByRequest.get(req);
+                if (!principal) {
+                    json(res, 401, { error: "Unauthorized" });
+                    return;
+                }
+                if (!deps.ticketStore) {
+                    json(res, 501, { error: "SSE not available" });
+                    return;
+                }
+                const ticket = deps.ticketStore.mint({
+                    tokenName: principal.name,
+                    scope: principal.scope,
+                });
+                json(res, 200, { ticket, expiresIn: 60 });
+                return;
+            }
+            // --- Token management (admin scope) ---
+            // GET /api/v1/tokens — list tokens.
+            // admin: full list. api: own token only (self-row, so the slash
+            // menu can show the user's own metadata without leaking peers).
+            if (url === "/api/v1/tokens" && req.method === "GET") {
+                const principal = principalByRequest.get(req);
+                if (!deps.authStore || !principal) {
+                    json(res, 401, { error: "Unauthorized" });
+                    return;
+                }
+                const all = deps.authStore.list();
+                const visible = principal.scope === "admin"
+                    ? all
+                    : all.filter((t) => t.name === principal.name);
+                const list = visible.map((t) => ({
+                    name: t.name,
+                    scope: t.scope,
+                    createdAt: t.createdAt,
+                    lastUsedAt: t.lastUsedAt,
+                    isSelf: t.name === principal.name,
+                }));
+                json(res, 200, list);
+                return;
+            }
+            // POST /api/v1/tokens — create new api-scope token, return raw value once
+            if (url === "/api/v1/tokens" && req.method === "POST") {
+                const principal = principalByRequest.get(req);
+                if (!deps.authStore || !principal) {
+                    json(res, 401, { error: "Unauthorized" });
+                    return;
+                }
+                if (principal.scope !== "admin") {
+                    json(res, 403, { error: "Forbidden" });
+                    return;
+                }
+                let body;
+                try {
+                    body = JSON.parse(await readBody(req));
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON" });
+                    return;
+                }
+                const name = typeof body.name === "string" ? body.name : "";
+                try {
+                    const created = await deps.authStore.addToken(name, "api");
+                    json(res, 201, {
+                        token: created.token,
+                        name: created.record.name,
+                        scope: created.record.scope,
+                    });
+                }
+                catch (err) {
+                    const msg = errorMessage(err);
+                    if (/already exists|duplicate/i.test(msg)) {
+                        json(res, 409, { error: msg });
+                    }
+                    else {
+                        json(res, 400, { error: msg });
+                    }
+                }
+                return;
+            }
+            // DELETE /api/v1/tokens/:name — revoke
+            const tokenDelMatch = url.match(/^\/api\/v1\/tokens\/([^/?]+)\/?$/);
+            if (tokenDelMatch && req.method === "DELETE") {
+                const principal = principalByRequest.get(req);
+                if (!deps.authStore || !principal) {
+                    json(res, 401, { error: "Unauthorized" });
+                    return;
+                }
+                if (principal.scope !== "admin") {
+                    json(res, 403, { error: "Forbidden" });
+                    return;
+                }
+                const name = decodeURIComponent(tokenDelMatch[1]);
+                if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
+                    json(res, 400, { error: "Invalid token name" });
+                    return;
+                }
+                if (name === principal.name) {
+                    json(res, 400, { error: "Cannot revoke the token you are using" });
+                    return;
+                }
+                try {
+                    const ok = await deps.authStore.revokeToken(name);
+                    if (!ok) {
+                        json(res, 404, { error: "Token not found" });
+                        return;
+                    }
+                    res.writeHead(204);
+                    res.end();
+                }
+                catch (err) {
+                    json(res, 400, { error: errorMessage(err) });
+                }
+                return;
+            }
             // --- POST /api/v1/bridge/reload ---
             if (url === "/api/v1/bridge/reload" && req.method === "POST") {
                 const bridge = getBridge?.();
@@ -139,6 +619,9 @@ export function createRequestHandler(deps) {
             if (permActionMatch && req.method === "POST") {
                 const sessionId = decodeURIComponent(permActionMatch[1]);
                 const requestId = decodeURIComponent(permActionMatch[2]);
+                const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
+                if (replayed)
+                    return;
                 const perm = sessions?.pendingPermissions.get(requestId);
                 if (!perm) {
                     json(res, 404, { error: "Permission not found" });
@@ -165,25 +648,34 @@ export function createRequestHandler(deps) {
                     json(res, 400, { error: "Provide optionId or denied:true" });
                     return;
                 }
-                const denied = !!body.denied;
+                const denied = Boolean(body.denied);
                 const optionId = body.optionId ?? "deny";
-                const optionName = perm.options.find(o => o.optionId === optionId)?.label ?? optionId;
+                const optionName = perm.options.find((o) => o.optionId === optionId)?.label ?? optionId;
                 if (denied) {
-                    await bridge.denyPermission(requestId);
+                    bridge.denyPermission(requestId);
                 }
                 else {
-                    await bridge.resolvePermission(requestId, optionId);
+                    bridge.resolvePermission(requestId, optionId);
                 }
                 sessions.pendingPermissions.delete(requestId);
+                sessions.syncPendingPermissions(sessionId);
                 // Store event and broadcast (same type so SSE drops are recoverable via sync)
                 const permEventData = { requestId, optionName, denied };
-                store.saveEvent(perm.sessionId, "permission_response", { ...permEventData, optionId });
+                store.saveEvent(perm.sessionId, "permission_response", { ...permEventData, optionId }, { from_ref: "user" });
                 sseManager.broadcast({
                     type: "permission_response",
                     sessionId: perm.sessionId,
                     ...permEventData,
                 });
-                json(res, 200, { ok: true });
+                // Cross-device banner recall: close the permission banner on
+                // every subscribed endpoint now that the permission has been
+                // handled by this client.
+                if (deps.pushService) {
+                    void deps.pushService.sendClose(`sess-${perm.sessionId}-perm-${requestId}`);
+                }
+                const okBody = { ok: true };
+                saveClientOpResult(store, opId, sessionId, 200, okBody);
+                json(res, 200, okBody);
                 return;
             }
             // --- POST /api/v1/sessions/:id/cancel ---
@@ -200,6 +692,9 @@ export function createRequestHandler(deps) {
                     json(res, 503, { error: "Agent not ready yet" });
                     return;
                 }
+                const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
+                if (replayed)
+                    return;
                 // Kill running bash process if any
                 const proc = sessions?.runningBashProcs.get(sessionId);
                 if (proc) {
@@ -211,7 +706,16 @@ export function createRequestHandler(deps) {
                     await bridge.cancel(sessionId);
                     sessions.activePrompts.delete(sessionId);
                 }
-                json(res, 200, { ok: true });
+                // Arm backend safety net: if prompt_done doesn't arrive within the
+                // configured timeout, force-clear busy so the UI unstalls. Replaces
+                // the old frontend-side cancel timer.
+                const cancelTimeout = deps.limits.cancel_timeout ?? 0;
+                if (sessions && cancelTimeout > 0)
+                    sessions.state.armCancelSafety(sessionId, cancelTimeout);
+                sessions?.syncBusy(sessionId);
+                const okBody = { ok: true };
+                saveClientOpResult(store, opId, sessionId, 200, okBody);
+                json(res, 200, okBody);
                 return;
             }
             // --- GET /api/v1/sessions/:id/status ---
@@ -232,6 +736,45 @@ export function createRequestHandler(deps) {
                 });
                 return;
             }
+            // --- GET /api/v1/sessions/:id/snapshot ---
+            // client-server-split M1: single source of truth for "what state is
+            // this session in right now". Frontend calls this on connect / reconnect
+            // / after long backgrounding, then applies incremental `state_patch`
+            // SSE events.
+            const snapshotMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/snapshot\/?$/);
+            if (snapshotMatch && req.method === "GET") {
+                const sessionId = decodeURIComponent(snapshotMatch[1]);
+                const session = store.getSession(sessionId);
+                if (!session) {
+                    json(res, 404, { error: "Session not found" });
+                    return;
+                }
+                if (!sessions) {
+                    json(res, 503, { error: "Session manager not available" });
+                    return;
+                }
+                // Make sure runtime reflects the current activePrompts/bash state even
+                // if no patch has been emitted yet for this session.
+                sessions.syncBusy(sessionId);
+                sessions.syncPendingPermissions(sessionId);
+                const runtimeState = sessions.state.getState(sessionId);
+                const lastEventSeq = store.getLastEventSeq(sessionId);
+                json(res, 200, {
+                    version: 1,
+                    seq: runtimeState.seq,
+                    session: {
+                        id: session.id,
+                        title: session.title,
+                        cwd: session.cwd,
+                        model: session.model,
+                        mode: session.mode,
+                        createdAt: session.created_at,
+                        lastEventSeq,
+                    },
+                    runtime: runtimeState.runtime,
+                }, req);
+                return;
+            }
             // --- POST /api/v1/sessions/:id/prompt ---
             const promptMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/prompt\/?(\?.*)?$/);
             if (promptMatch && req.method === "POST") {
@@ -250,12 +793,17 @@ export function createRequestHandler(deps) {
                     json(res, 503, { error: "Session manager not available" });
                     return;
                 }
+                const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
+                if (replayed)
+                    return;
                 // Ensure session is live in ACP before prompting (awaits in-flight resume)
                 try {
                     await sessions.ensureResumed(bridge, sessionId);
                 }
                 catch (err) {
-                    json(res, 500, { error: `Failed to resume session: ${err instanceof Error ? err.message : String(err)}` });
+                    json(res, 500, {
+                        error: `Failed to resume session: ${err instanceof Error ? err.message : String(err)}`,
+                    });
                     return;
                 }
                 // Check if session is busy
@@ -276,28 +824,101 @@ export function createRequestHandler(deps) {
                     json(res, 400, { error: "Missing required field: text" });
                     return;
                 }
-                // Store user_message event (strip base64 data, keep only path + mimeType)
-                const storedImages = body.images?.map(i => ({ path: i.path, mimeType: i.mimeType }));
-                store.saveEvent(sessionId, "user_message", { text: body.text, ...(storedImages?.length && { images: storedImages }) });
+                // Validate attachment shape: client must NEVER supply uri/data/path,
+                // only the four canonical fields. Anything else → 400 immediately so
+                // we don't even hand it to the dispatcher fallback.
+                const attachments = body.attachments;
+                if (attachments) {
+                    if (!Array.isArray(attachments)) {
+                        json(res, 400, { error: "attachments must be an array" });
+                        return;
+                    }
+                    for (const raw of attachments) {
+                        const att = raw;
+                        if (!att ||
+                            typeof att !== "object" ||
+                            (att.kind !== "image" && att.kind !== "file") ||
+                            typeof att.attachmentId !== "string" ||
+                            typeof att.displayName !== "string" ||
+                            typeof att.mimeType !== "string") {
+                            json(res, 400, { error: "Invalid attachment entry" });
+                            return;
+                        }
+                        if (typeof att.uri === "string" ||
+                            typeof att.data === "string" ||
+                            typeof att.path === "string") {
+                            json(res, 400, {
+                                error: "Client must not supply uri/data/path",
+                            });
+                            return;
+                        }
+                    }
+                }
+                // Stored shape mirrors the wire shape PLUS a server-derived `path`
+                // for renderers. The path is the unsigned base URL
+                // (`/api/v1/sessions/<sid>/attachments/<filename>`); reSign on
+                // egress (history GET + SSE broadcast) appends a fresh `?sig=&exp=`.
+                // Renderers use it to mount `<img>` (kind=image) or `<a>` (kind=file).
+                // Refs whose attachment row is missing are dropped (defense — the
+                // dispatcher's [attachment removed] fallback covers that case).
+                const storedAttachments = attachments?.flatMap((a) => {
+                    const row = store.getAttachment(sessionId, a.attachmentId);
+                    if (!row)
+                        return [];
+                    const fileName = basename(row.realpath);
+                    return [
+                        {
+                            kind: a.kind,
+                            attachmentId: a.attachmentId,
+                            displayName: a.displayName,
+                            mimeType: a.mimeType,
+                            path: `/api/v1/sessions/${sessionId}/attachments/${fileName}`,
+                        },
+                    ];
+                });
+                store.saveEvent(sessionId, "user_message", {
+                    text: body.text,
+                    ...(storedAttachments?.length
+                        ? { attachments: storedAttachments }
+                        : {}),
+                }, { from_ref: "user" });
                 store.updateSessionLastActive(sessionId);
                 store.touchRecentPath(session.cwd);
-                const userMsgEvent = { type: "user_message", sessionId, text: body.text, images: storedImages };
+                const userMsgEvent = {
+                    type: "user_message",
+                    sessionId,
+                    text: body.text,
+                    attachments: storedAttachments,
+                };
                 sseManager.broadcast(userMsgEvent);
                 // Generate title (fire-and-forget)
-                if (titleService && sessions && !sessions.sessionHasTitle.has(sessionId)) {
+                if (titleService &&
+                    sessions && // eslint-disable-line @typescript-eslint/no-unnecessary-condition -- optional dep
+                    !sessions.sessionHasTitle.has(sessionId)) {
                     titleService.generate(bridge, body.text, sessionId, (title) => {
-                        const titleEvent = { type: "session_title_updated", sessionId, title };
+                        const titleEvent = {
+                            type: "session_title_updated",
+                            sessionId,
+                            title,
+                        };
                         sseManager.broadcast(titleEvent);
                     });
                 }
                 // Fire prompt asynchronously (don't await — response is 202)
                 sessions.activePrompts.add(sessionId);
-                bridge.prompt(sessionId, body.text, body.images).catch((err) => {
-                    console.error(`[prompt] error for ${sessionId}:`, err);
-                }).finally(() => {
+                sessions.syncBusy(sessionId);
+                bridge
+                    .prompt(sessionId, body.text, attachments)
+                    .catch((err) => {
+                    plog.error("error", { sessionId, error: err });
+                })
+                    .finally(() => {
                     sessions.activePrompts.delete(sessionId);
+                    sessions.syncBusy(sessionId);
                 });
-                json(res, 202, { status: "accepted" });
+                const acceptedBody = { status: "accepted" };
+                saveClientOpResult(store, opId, sessionId, 202, acceptedBody);
+                json(res, 202, acceptedBody);
                 return;
             }
             // --- POST /api/v1/sessions/:id/bash ---
@@ -314,7 +935,9 @@ export function createRequestHandler(deps) {
                     return;
                 }
                 if (sessions.runningBashProcs.has(sessionId)) {
-                    json(res, 409, { error: "A bash command is already running in this session" });
+                    json(res, 409, {
+                        error: "A bash command is already running in this session",
+                    });
                     return;
                 }
                 let body;
@@ -330,11 +953,19 @@ export function createRequestHandler(deps) {
                     return;
                 }
                 const cwd = sessions.getSessionCwd(sessionId);
-                store.saveEvent(sessionId, "bash_command", { command: body.command });
-                const bashCmdEvent = { type: "bash_command", sessionId, command: body.command };
+                store.saveEvent(sessionId, "bash_command", { command: body.command }, { from_ref: "user" });
+                const bashCmdEvent = {
+                    type: "bash_command",
+                    sessionId,
+                    command: body.command,
+                };
                 sseManager.broadcast(bashCmdEvent);
-                const shell = IS_WIN ? (process.env.COMSPEC || "cmd.exe") : (process.env.SHELL || "bash");
-                const shellArgs = IS_WIN ? ["/s", "/c", body.command] : ["-c", body.command];
+                const shell = IS_WIN
+                    ? (process.env.COMSPEC ?? "cmd.exe")
+                    : (process.env.SHELL ?? "bash");
+                const shellArgs = IS_WIN
+                    ? ["/s", "/c", body.command]
+                    : ["-c", body.command];
                 const child = spawn(shell, shellArgs, {
                     cwd,
                     detached: !IS_WIN,
@@ -342,6 +973,7 @@ export function createRequestHandler(deps) {
                     stdio: ["ignore", "pipe", "pipe"],
                 });
                 sessions.runningBashProcs.set(sessionId, child);
+                sessions.syncBusy(sessionId);
                 let output = "";
                 let outputTruncated = false;
                 const limit = deps.limits.bash_output;
@@ -357,23 +989,41 @@ export function createRequestHandler(deps) {
                     else {
                         output = (output + text).slice(-limit);
                     }
-                    const bashOutEvent = { type: "bash_output", sessionId, text, stream };
+                    const bashOutEvent = {
+                        type: "bash_output",
+                        sessionId,
+                        text,
+                        stream,
+                    };
                     sseManager.broadcast(bashOutEvent);
                 };
                 child.stdout.on("data", onData("stdout"));
                 child.stderr.on("data", onData("stderr"));
                 child.on("close", (code, signal) => {
                     sessions.runningBashProcs.delete(sessionId);
+                    sessions.syncBusy(sessionId);
                     const stored = outputTruncated ? "[truncated]\n" + output : output;
-                    store.saveEvent(sessionId, "bash_result", { output: stored, code, signal });
-                    const bashDoneEvent = { type: "bash_done", sessionId, code, signal };
+                    store.saveEvent(sessionId, "bash_result", { output: stored, code, signal }, { from_ref: "system" });
+                    const bashDoneEvent = {
+                        type: "bash_done",
+                        sessionId,
+                        code,
+                        signal,
+                    };
                     sseManager.broadcast(bashDoneEvent);
                 });
                 child.on("error", (err) => {
                     sessions.runningBashProcs.delete(sessionId);
+                    sessions.syncBusy(sessionId);
                     const errMsg = errorMessage(err);
-                    store.saveEvent(sessionId, "bash_result", { output: errMsg, code: -1, signal: null });
-                    const bashErrEvent = { type: "bash_done", sessionId, code: -1, signal: null, error: errMsg };
+                    store.saveEvent(sessionId, "bash_result", { output: errMsg, code: -1, signal: null }, { from_ref: "system" });
+                    const bashErrEvent = {
+                        type: "bash_done",
+                        sessionId,
+                        code: -1,
+                        signal: null,
+                        error: errMsg,
+                    };
                     sseManager.broadcast(bashErrEvent);
                 });
                 json(res, 202, { status: "accepted" });
@@ -425,12 +1075,23 @@ export function createRequestHandler(deps) {
                     for (const opt of configOptions) {
                         store.updateSessionConfig(sessionId, opt.id, opt.currentValue);
                     }
-                    sseManager.broadcast({ type: "config_option_update", sessionId, configOptions });
-                    sseManager.broadcast({ type: "config_set", sessionId, configId, value: body.value });
+                    sseManager.broadcast({
+                        type: "config_option_update",
+                        sessionId,
+                        configOptions,
+                    });
+                    sseManager.broadcast({
+                        type: "config_set",
+                        sessionId,
+                        configId,
+                        value: body.value,
+                    });
                     json(res, 200, { configOptions });
                 }
                 catch (err) {
-                    json(res, 500, { error: `Failed to set ${configId}: ${err instanceof Error ? err.message : String(err)}` });
+                    json(res, 500, {
+                        error: `Failed to set ${configId}: ${err instanceof Error ? err.message : String(err)}`,
+                    });
                 }
                 return;
             }
@@ -460,8 +1121,12 @@ export function createRequestHandler(deps) {
                     sessions.sessionHasTitle.add(sessionId);
                 const bridge = getBridge?.();
                 if (titleService && bridge)
-                    titleService.cancel(sessionId, bridge);
-                const titleEvent = { type: "session_title_updated", sessionId, title: body.value };
+                    void titleService.cancel(sessionId, bridge);
+                const titleEvent = {
+                    type: "session_title_updated",
+                    sessionId,
+                    title: body.value,
+                };
                 sseManager.broadcast(titleEvent);
                 json(res, 200, { title: body.value });
                 return;
@@ -479,53 +1144,112 @@ export function createRequestHandler(deps) {
                         json(res, 404, { error: "Session not found" });
                         return;
                     }
-                    // Start resume in background (non-blocking) so the client gets metadata fast
+                    // Start resume in background (non-blocking) so the client gets metadata fast.
+                    // BUT: if cache is cold (cold-restart case), block on resume up to 8s so
+                    // configOptions returns inline. This eliminates the race where the
+                    // post-resume `config_option_update` broadcast can arrive before the
+                    // client's SSE is fully wired up — a flake observed on slow CI runners.
                     const wasLive = sessions?.liveSessions.has(sessionId) ?? true;
+                    let resumePromise = null;
                     if (sessions && getBridge && !wasLive) {
                         const bridge = getBridge();
                         if (bridge) {
-                            const resumePromise = sessions.ensureResumed(bridge, sessionId);
+                            resumePromise = sessions.ensureResumed(bridge, sessionId);
+                            // Broadcast config_option_update too, so any OTHER client viewing
+                            // the same session (whose own GET may have raced and returned cold)
+                            // also picks up the warm values.
+                            resumePromise
+                                .then(() => {
+                                const cur = store.getSession(sessionId);
+                                if (!cur || !sessions.cachedConfigOptions.length)
+                                    return;
+                                const opts = sessions.cachedConfigOptions.map((opt) => {
+                                    const stored = {
+                                        model: cur.model,
+                                        mode: cur.mode,
+                                        reasoning_effort: cur.reasoning_effort,
+                                    };
+                                    const override = stored[opt.id];
+                                    return override ? { ...opt, currentValue: override } : opt;
+                                });
+                                sseManager.broadcast({
+                                    type: "config_option_update",
+                                    sessionId,
+                                    configOptions: opts,
+                                });
+                            })
+                                .catch(() => { });
                             // Auto-retry if the last turn was interrupted (must wait for resume)
                             const hasInterrupted = store.hasInterruptedTurn(sessionId);
                             if (hasInterrupted) {
                                 // Optimistically mark busy so concurrent POST sees the session as active
                                 sessions.activePrompts.add(sessionId);
-                                resumePromise.then(() => {
+                                sessions.syncBusy(sessionId);
+                                void resumePromise
+                                    .then(() => {
                                     if (!sessions.autoRetryIfNeeded(bridge, sessionId)) {
                                         // Retry not needed after all — release the optimistic lock
                                         sessions.activePrompts.delete(sessionId);
+                                        sessions.syncBusy(sessionId);
                                     }
-                                }).catch(() => {
+                                })
+                                    .catch(() => {
                                     sessions.activePrompts.delete(sessionId);
+                                    sessions.syncBusy(sessionId);
                                 });
                             }
                             else {
                                 resumePromise.catch((err) => {
-                                    console.error(`[session] background resume failed for ${sessionId.slice(0, 8)}…:`, err);
+                                    slog.error("background resume failed", {
+                                        sessionId: sessionId.slice(0, 8) + "…",
+                                        error: err,
+                                    });
                                 });
                             }
                         }
                     }
-                    const configOptions = sessions ? (() => {
-                        // Build configOptions from cached + stored overrides
-                        const opts = sessions.cachedConfigOptions.map(opt => {
-                            const stored = { model: session.model, mode: session.mode, reasoning_effort: session.reasoning_effort };
-                            const override = stored[opt.id];
-                            return override ? { ...opt, currentValue: override } : opt;
+                    // If cache is cold and we kicked off a resume, wait briefly so the
+                    // GET response includes warm configOptions. Bounded to 8s — past that
+                    // we fall back to returning empty configOptions and rely on the
+                    // broadcast above. The frontend retries (re-fetches) on broadcast.
+                    if (resumePromise && !sessions?.cachedConfigOptions.length) {
+                        let timer = null;
+                        const timeoutPromise = new Promise((resolve) => {
+                            timer = setTimeout(resolve, 8000);
                         });
-                        return opts;
-                    })() : [];
-                    const busyKind = sessions?.getBusyKind(sessionId) ?? null;
+                        await Promise.race([
+                            resumePromise.finally(() => {
+                                if (timer)
+                                    clearTimeout(timer);
+                            }),
+                            timeoutPromise,
+                        ]).catch(() => { });
+                    }
+                    // Re-read session in case resume mutated stored config
+                    const freshSession = store.getSession(sessionId) ?? session;
+                    const configOptions = sessions
+                        ? (() => {
+                            // Build configOptions from cached + stored overrides
+                            const opts = sessions.cachedConfigOptions.map((opt) => {
+                                const stored = {
+                                    model: freshSession.model,
+                                    mode: freshSession.mode,
+                                    reasoning_effort: freshSession.reasoning_effort,
+                                };
+                                const override = stored[opt.id];
+                                return override ? { ...opt, currentValue: override } : opt;
+                            });
+                            return opts;
+                        })()
+                        : [];
                     json(res, 200, {
-                        id: session.id,
-                        cwd: session.cwd,
-                        title: session.title,
-                        source: session.source,
-                        model: session.model,
-                        mode: session.mode,
+                        id: freshSession.id,
+                        cwd: freshSession.cwd,
+                        title: freshSession.title,
+                        source: freshSession.source,
+                        model: freshSession.model,
+                        mode: freshSession.mode,
                         configOptions,
-                        busy: busyKind != null,
-                        busyKind,
                     }, req);
                     return;
                 }
@@ -582,7 +1306,11 @@ export function createRequestHandler(deps) {
                     // ACP's session_created event fires before inheritance runs, so
                     // broadcast final configOptions so SSE clients get the inherited values.
                     if (configOptions.length) {
-                        sseManager.broadcast({ type: "config_option_update", sessionId, configOptions });
+                        sseManager.broadcast({
+                            type: "config_option_update",
+                            sessionId,
+                            configOptions,
+                        });
                     }
                     json(res, 201, {
                         id: sessionId,
@@ -607,14 +1335,17 @@ export function createRequestHandler(deps) {
             const eventsMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/events(\?.*)?$/);
             if (eventsMatch && req.method === "GET") {
                 const sessionId = decodeURIComponent(eventsMatch[1]);
-                const params = new URLSearchParams(eventsMatch[2]?.slice(1) ?? "");
+                const queryPart = eventsMatch[2];
+                const params = new URLSearchParams(queryPart ? queryPart.slice(1) : "");
                 const excludeThinking = params.get("thinking") === "0";
                 const afterRaw = params.get("after");
                 const afterSeq = afterRaw != null ? Number(afterRaw) : undefined;
                 const beforeRaw = params.get("before");
                 const beforeSeq = beforeRaw != null ? Number(beforeRaw) : undefined;
                 const limitRaw = params.get("limit");
-                const limit = limitRaw != null ? Math.max(1, Math.min(10000, Number(limitRaw))) : undefined;
+                const limit = limitRaw != null
+                    ? Math.max(1, Math.min(10000, Number(limitRaw)))
+                    : undefined;
                 const session = store.getSession(sessionId);
                 if (!session) {
                     json(res, 404, { error: "Session not found" });
@@ -635,15 +1366,45 @@ export function createRequestHandler(deps) {
                         sessions.flushAssistantBuffer(sessionId);
                     }
                 }
-                const events = store.getEvents(sessionId, { excludeThinking, afterSeq, beforeSeq, limit });
+                const events = store.getEvents(sessionId, {
+                    excludeThinking,
+                    afterSeq,
+                    beforeSeq,
+                    limit,
+                });
+                // Replace internal uuid attachment paths with `<name> [#<id4>]`
+                // labels at egress (CLAUDE.md "Attachment label egress
+                // rewrite"). DB rows still hold raw paths.
+                if (sessions) {
+                    enrichStoredEventsForDisplay(events, sessions.getLabelMap(sessionId));
+                }
+                // Re-sign image URLs at egress so 1h-old stored URLs become valid
+                // again — the user can reload history days later and images still
+                // resolve. Mutates `data` in-place; safe because store.getEvents
+                // returns fresh records.
+                if (deps.attachmentSecret) {
+                    for (const ev of events) {
+                        if (typeof ev.data === "string" &&
+                            ev.data.includes("/attachments/")) {
+                            ev.data = reSignAttachmentUrlsInJson(ev.data, deps.attachmentSecret);
+                        }
+                    }
+                }
                 const envelope = {
                     events,
-                    streaming: { thinking: streamingThinking, assistant: streamingAssistant },
+                    streaming: {
+                        thinking: streamingThinking,
+                        assistant: streamingAssistant,
+                    },
                 };
                 if (limit != null) {
                     const total = store.getEventCount(sessionId, { excludeThinking });
                     const hasMore = events.length > 0
-                        ? (store.getEvents(sessionId, { excludeThinking, beforeSeq: events[0].seq, limit: 1 }).length > 0)
+                        ? store.getEvents(sessionId, {
+                            excludeThinking,
+                            beforeSeq: events[0].seq,
+                            limit: 1,
+                        }).length > 0
                         : false;
                     envelope.total = total;
                     envelope.hasMore = hasMore;
@@ -654,32 +1415,54 @@ export function createRequestHandler(deps) {
             // --- SSE stream endpoints ---
             // GET /api/v1/events/stream — global SSE stream
             if (url.startsWith("/api/v1/events/stream") && req.method === "GET") {
-                if (!deps.sseManager) {
-                    json(res, 501, { error: "SSE not available" });
-                    return;
+                // Ticket-based auth (EventSource cannot send Authorization header).
+                // When authStore is configured, every SSE connection MUST present a
+                // valid single-use ticket from POST /api/v1/sse-ticket.
+                let tokenName;
+                if (deps.authStore) {
+                    const ticket = new URLSearchParams(url.split("?")[1] ?? "").get("ticket") ?? "";
+                    const principal = deps.ticketStore?.consume(ticket);
+                    if (!principal) {
+                        json(res, 401, { error: "Invalid or expired ticket" });
+                        return;
+                    }
+                    tokenName = principal.tokenName;
                 }
-                const sseManager = deps.sseManager;
                 const clientId = sseManager.generateClientId();
                 res.writeHead(200, {
                     "Content-Type": "text/event-stream",
                     "Cache-Control": "no-cache",
-                    "Connection": "keep-alive",
+                    Connection: "keep-alive",
                 });
-                const client = { id: clientId, res };
+                const client = {
+                    id: clientId,
+                    res,
+                    tokenName,
+                };
                 sseManager.add(client);
                 // Send connected event
-                sseManager.sendEvent(client, { type: "connected", clientId });
+                sseManager.sendEvent(client, {
+                    type: "connected",
+                    clientId,
+                    debugLevel: deps.debugLevel ?? "off",
+                });
+                sseManager.writeHeartbeat(client);
                 return;
             }
             // GET /api/v1/sessions/:id/events/stream — per-session SSE stream
             const sseSessionMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/events\/stream(\?.*)?$/);
             if (sseSessionMatch && req.method === "GET") {
-                if (!deps.sseManager) {
-                    json(res, 501, { error: "SSE not available" });
-                    return;
-                }
-                const sseManager = deps.sseManager;
                 const sessionId = decodeURIComponent(sseSessionMatch[1]);
+                let tokenName;
+                if (deps.authStore) {
+                    const ticket = new URLSearchParams(url.split("?")[1] ?? "").get("ticket") ?? "";
+                    const principal = deps.ticketStore?.consume(ticket);
+                    if (!principal) {
+                        json(res, 401, { error: "Invalid or expired ticket" });
+                        return;
+                    }
+                    tokenName = principal.tokenName;
+                }
                 const session = store.getSession(sessionId);
                 if (!session) {
                     json(res, 404, { error: "Session not found" });
@@ -689,12 +1472,22 @@ export function createRequestHandler(deps) {
                 res.writeHead(200, {
                     "Content-Type": "text/event-stream",
                     "Cache-Control": "no-cache",
-                    "Connection": "keep-alive",
+                    Connection: "keep-alive",
                 });
-                const client = { id: clientId, res, sessionId };
+                const client = {
+                    id: clientId,
+                    res,
+                    sessionId,
+                    tokenName,
+                };
                 sseManager.add(client);
                 // Send connected event
-                sseManager.sendEvent(client, { type: "connected", clientId });
+                sseManager.sendEvent(client, {
+                    type: "connected",
+                    clientId,
+                    debugLevel: deps.debugLevel ?? "off",
+                });
+                sseManager.writeHeartbeat(client);
                 // Replay events from Last-Event-ID if provided
                 const lastEventId = req.headers["last-event-id"];
                 if (lastEventId) {
@@ -703,7 +1496,10 @@ export function createRequestHandler(deps) {
                         const events = store.getEvents(sessionId, { afterSeq });
                         for (const evt of events) {
                             try {
-                                sseManager.sendEvent(client, { type: evt.type, ...JSON.parse(evt.data) }, evt.seq);
+                                sseManager.sendEvent(client, {
+                                    type: evt.type,
+                                    ...JSON.parse(evt.data),
+                                }, evt.seq);
                             }
                             catch {
                                 // Skip malformed event data
@@ -713,69 +1509,75 @@ export function createRequestHandler(deps) {
                 }
                 return;
             }
-            // --- Images (session-scoped) ---
-            // POST /api/v1/sessions/:id/images
-            const imgUploadMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/images\/?$/);
+            // --- Attachments (session-scoped) ---
+            // POST /api/v1/sessions/:id/attachments — multipart/form-data upload.
+            //
+            // Wire format: a single `file` field. busboy streams chunks straight
+            // to <data_dir>/sessions/<sid>/attachments/<uuid>.<ext>.tmp; on close
+            // we atomic-rename to the final name and insert an attachments row.
+            // Aborts / mid-stream errors / oversize / wrong field name all leave
+            // the .tmp removed before responding.
+            const imgUploadMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/attachments\/?$/);
             if (imgUploadMatch && req.method === "POST") {
                 const sessionId = decodeURIComponent(imgUploadMatch[1]);
                 if (!SAFE_ID.test(sessionId)) {
                     json(res, 400, { error: "Invalid session ID" });
                     return;
                 }
-                // Enforce upload size limit
-                const contentLength = parseInt(req.headers["content-length"] ?? "0", 10);
-                if (contentLength > deps.limits.image_upload) {
-                    json(res, 413, { error: "Upload too large" });
+                const ctype = req.headers["content-type"] ?? "";
+                if (!ctype.toLowerCase().startsWith("multipart/form-data")) {
+                    json(res, 400, { error: "Expected multipart/form-data" });
                     return;
                 }
-                const chunks = [];
-                let totalSize = 0;
-                for await (const chunk of req) {
-                    totalSize += chunk.length;
-                    if (totalSize > deps.limits.image_upload) {
-                        json(res, 413, { error: "Upload too large" });
-                        return;
-                    }
-                    chunks.push(chunk);
-                }
-                let body;
-                try {
-                    body = JSON.parse(Buffer.concat(chunks).toString());
-                }
-                catch {
-                    json(res, 400, { error: "Invalid JSON" });
-                    return;
-                }
-                const { data, mimeType } = body;
-                const ext = mimeType.split("/")[1]?.replace("jpeg", "jpg") ?? "png";
-                const seq = Date.now();
-                const fileName = `${seq}.${ext}`;
-                const relPath = `images/${sessionId}/${fileName}`;
-                const absPath = join(deps.dataDir, relPath);
-                await mkdir(join(deps.dataDir, "images", sessionId), { recursive: true });
-                await writeFile(absPath, Buffer.from(data, "base64"));
-                const imgUrl = `/api/v1/sessions/${sessionId}/images/${fileName}`;
-                json(res, 200, { path: relPath, url: imgUrl });
+                await handleAttachmentUpload(req, res, sessionId, deps);
                 return;
             }
-            // GET /api/v1/sessions/:id/images/:file
-            const imgGetMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/images\/([^/?]+)\/?$/);
+            // GET /api/v1/sessions/:id/attachments/:file — serve a previously
+            // uploaded attachment. Mime + displayName are looked up from the
+            // attachments table so the response carries the original filename
+            // (RFC 5987) and the per-mime inline/attachment disposition.
+            const imgGetMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/attachments\/([^/?]+)(\?.*)?$/);
             if (imgGetMatch && req.method === "GET") {
                 const sessionId = decodeURIComponent(imgGetMatch[1]);
                 const file = decodeURIComponent(imgGetMatch[2]);
-                const filePath = join(deps.dataDir, "images", sessionId, file);
-                if (!filePath.startsWith(join(deps.dataDir, "images"))) {
+                // When secret is configured, GET requires sig+exp in query — there
+                // is no Bearer fallback because <img src=...> / <a href=...> can't
+                // carry headers. Verify before any disk I/O.
+                if (deps.attachmentSecret) {
+                    const params = new URLSearchParams(url.split("?")[1] ?? "");
+                    const sig = params.get("sig") ?? "";
+                    const exp = params.get("exp") ?? "";
+                    const basePath = `/api/v1/sessions/${sessionId}/attachments/${file}`;
+                    if (!verifyAttachmentSig(basePath, exp, sig, deps.attachmentSecret)) {
+                        res.writeHead(401, { "Content-Type": "application/json" });
+                        res.end(JSON.stringify({ error: "Unauthorized" }));
+                        return;
+                    }
+                }
+                const filePath = join(deps.dataDir, "sessions", sessionId, "attachments", file);
+                if (!filePath.startsWith(join(deps.dataDir, "sessions"))) {
                     res.writeHead(403);
                     res.end("Forbidden");
                     return;
                 }
+                // Look up the row to recover the original mime + display name.
+                // Pre-attachments-table uploads (none in v0.4+) would miss here;
+                // we degrade gracefully to extension-based mime.
+                const row = store.getAttachmentByFile(sessionId, file);
                 try {
                     const fileData = await readFile(filePath);
-                    const ext = extname(filePath);
-                    res.writeHead(200, {
-                        "Content-Type": MIME[ext] ?? "application/octet-stream",
+                    const mime = row?.mime ??
+                        (MIME[extname(filePath)] || "application/octet-stream");
+                    const headers = {
+                        "Content-Type": mime,
                         "Cache-Control": "public, max-age=31536000, immutable",
-                    });
+                        "X-Content-Type-Options": "nosniff",
+                    };
+                    if (row) {
+                        const disposition = isInlineMime(mime) ? "inline" : "attachment";
+                        headers["Content-Disposition"] = buildContentDisposition(disposition, row.name);
+                    }
+                    res.writeHead(200, headers);
                     res.end(fileData);
                 }
                 catch {
@@ -784,6 +1586,203 @@ export function createRequestHandler(deps) {
                 }
                 return;
             }
+            // --- Inbox messages (Stage B primitive) ---
+            // POST /api/v1/messages — create ingress message
+            if (url === "/api/v1/messages" && req.method === "POST") {
+                // client-server-split M2: idempotency for the ingress message
+                // creator. /messages has no real session id, so we scope the
+                // cache under the synthetic key "__ingress__".
+                const { opId, replayed } = tryReplayClientOp(req, res, store, "__ingress__");
+                if (replayed)
+                    return;
+                let raw;
+                try {
+                    raw = await readBody(req);
+                }
+                catch {
+                    json(res, 400, { error: "Failed to read body" });
+                    return;
+                }
+                let parsed;
+                try {
+                    parsed = JSON.parse(raw);
+                }
+                catch {
+                    json(res, 400, { error: "Invalid JSON" });
+                    return;
+                }
+                const validation = MessageIngressSchema.safeParse(parsed);
+                if (!validation.success) {
+                    json(res, 400, {
+                        error: "Invalid body",
+                        issues: validation.error.issues,
+                    });
+                    return;
+                }
+                const input = validation.data;
+                const id = `msg-${randomUUID().replace(/-/g, "").slice(0, 16)}`;
+                if (input.to.startsWith("session:")) {
+                    const targetSid = input.to.slice("session:".length);
+                    const session = store.getSession(targetSid);
+                    if (!session) {
+                        json(res, 400, { error: "session_not_found" });
+                        return;
+                    }
+                    sessions?.flushBuffers(targetSid);
+                    const data = {
+                        message_id: id,
+                        from_ref: input.from_ref,
+                        from_label: input.from_label ?? null,
+                        title: input.title,
+                        body: input.body,
+                        cwd: input.cwd ?? null,
+                    };
+                    store.saveEvent(targetSid, "message", data, {
+                        from_ref: input.from_ref,
+                    });
+                    sseManager.broadcast({
+                        type: "message",
+                        sessionId: targetSid,
+                        ...data,
+                    });
+                    if (deps.pushService) {
+                        void deps.pushService.sendForMessage({
+                            id,
+                            to: input.to,
+                            body: input.body,
+                            from_label: input.from_label,
+                            from_ref: input.from_ref,
+                            deliver: input.deliver,
+                            dedup_key: input.dedup_key ?? null,
+                        });
+                    }
+                    mlog.info("ingress bound", {
+                        msg_id: id,
+                        sess_id: targetSid.slice(0, 8),
+                    });
+                    const boundBody = { id, delivered: "session" };
+                    saveClientOpResult(store, opId, "__ingress__", 200, boundBody);
+                    json(res, 200, boundBody);
+                    return;
+                }
+                // Unbound: to=user → rows in `messages` table
+                const dedupKey = input.dedup_key ?? null;
+                if (dedupKey) {
+                    const prior = store.findBySupersede(input.to, dedupKey);
+                    if (prior) {
+                        store.deleteMessage(prior.id);
+                        mlog.info("dedup_key supersede", {
+                            to: input.to,
+                            dedup_key: dedupKey,
+                            old_msg_id: prior.id,
+                            new_msg_id: id,
+                        });
+                    }
+                }
+                store.createMessage({
+                    id,
+                    from_ref: input.from_ref,
+                    from_label: input.from_label ?? null,
+                    to_ref: input.to,
+                    deliver: input.deliver,
+                    dedup_key: dedupKey,
+                    title: input.title,
+                    body: input.body,
+                    cwd: input.cwd ?? null,
+                    created_at: Date.now(),
+                });
+                sseManager.broadcast({ type: "message_created", messageId: id });
+                if (deps.pushService) {
+                    void deps.pushService.sendForMessage({
+                        id,
+                        to: input.to,
+                        body: input.body,
+                        from_label: input.from_label,
+                        from_ref: input.from_ref,
+                        deliver: input.deliver,
+                        dedup_key: dedupKey,
+                    });
+                }
+                mlog.info("ingress unbound", {
+                    msg_id: id,
+                    from_ref: input.from_ref,
+                });
+                const unboundBody = { id, delivered: "pending" };
+                saveClientOpResult(store, opId, "__ingress__", 200, unboundBody);
+                json(res, 200, unboundBody);
+                return;
+            }
+            // GET /api/v1/messages — list unprocessed
+            if (url === "/api/v1/messages" && req.method === "GET") {
+                json(res, 200, { messages: store.listUnprocessed() });
+                return;
+            }
+            // /api/v1/messages/:id... — GET single, POST :id/consume, POST :id/ack, DELETE :id
+            if (url.startsWith("/api/v1/messages/")) {
+                const tail = url.slice("/api/v1/messages/".length);
+                const consumeMatch = tail.match(/^([^/?]+)\/consume\/?$/);
+                if (consumeMatch && req.method === "POST") {
+                    const id = decodeURIComponent(consumeMatch[1]);
+                    const newSid = randomUUID();
+                    let out;
+                    try {
+                        out = store.consumeMessageTx(id, { sessionId: newSid });
+                    }
+                    catch (err) {
+                        if (/message not found/.test(errorMessage(err))) {
+                            json(res, 404, { error: "Message not found" });
+                            return;
+                        }
+                        throw err;
+                    }
+                    sseManager.broadcast({
+                        type: "message_consumed",
+                        messageId: id,
+                        sessionId: out.sessionId,
+                    });
+                    if (!out.alreadyConsumed && deps.pushService) {
+                        void deps.pushService.sendClose(id);
+                    }
+                    mlog.info("consume", {
+                        msg_id: id,
+                        sess_id: out.sessionId.slice(0, 8),
+                        already_consumed: out.alreadyConsumed,
+                    });
+                    json(res, 200, {
+                        sessionId: out.sessionId,
+                        alreadyConsumed: out.alreadyConsumed,
+                    });
+                    return;
+                }
+                const ackPost = tail.match(/^([^/?]+)\/ack\/?$/);
+                const idOnly = tail.match(/^([^/?]+)\/?$/);
+                const isAck = (ackPost !== null && req.method === "POST") ||
+                    (idOnly !== null && req.method === "DELETE");
+                if (isAck) {
+                    const id = decodeURIComponent((ackPost ?? idOnly)[1]);
+                    const changes = store.deleteMessage(id);
+                    if (changes === 0) {
+                        json(res, 404, { error: "Message not found" });
+                        return;
+                    }
+                    sseManager.broadcast({ type: "message_acked", messageId: id });
+                    if (deps.pushService)
+                        void deps.pushService.sendClose(id);
+                    mlog.info("ack", { msg_id: id });
+                    json(res, 200, { ok: true });
+                    return;
+                }
+                if (idOnly && req.method === "GET") {
+                    const id = decodeURIComponent(idOnly[1]);
+                    const row = store.getMessage(id);
+                    if (!row) {
+                        json(res, 404, { error: "Message not found" });
+                        return;
+                    }
+                    json(res, 200, row);
+                    return;
+                }
+            }
             json(res, 404, { error: "Not found" });
             return;
         }
@@ -814,34 +1813,45 @@ export function createRequestHandler(deps) {
                     json(res, 400, { error: "Missing required field: text" });
                     return;
                 }
-                const cwd = body.cwd || undefined;
+                const cwd = typeof body.cwd === "string" ? body.cwd : undefined;
                 const { sessionId } = await sessions.createSession(bridge, cwd, undefined, "auto");
                 const streamUrl = `/api/v1/sessions/${sessionId}/events/stream`;
                 json(res, 202, { sessionId, streamUrl });
                 // Fire-and-forget: send the prompt asynchronously, tracking busy state
                 sessions.activePrompts.add(sessionId);
+                sessions.syncBusy(sessionId);
                 // Generate title (fire-and-forget)
                 if (titleService && !sessions.sessionHasTitle.has(sessionId)) {
                     titleService.generate(bridge, text, sessionId, (title) => {
-                        const titleEvent = { type: "session_title_updated", sessionId, title };
+                        const titleEvent = {
+                            type: "session_title_updated",
+                            sessionId,
+                            title,
+                        };
                         sseManager.broadcast(titleEvent);
                     });
                 }
-                bridge.prompt(sessionId, text)
+                bridge
+                    .prompt(sessionId, text)
                     .catch(() => { })
-                    .finally(() => sessions.activePrompts.delete(sessionId));
+                    .finally(() => {
+                    sessions.activePrompts.delete(sessionId);
+                    sessions.syncBusy(sessionId);
+                });
                 return;
             }
             // POST /api/beta/clients/:clientId/visibility
             const visMatch = url.match(/^\/api\/beta\/clients\/([^/]+)\/visibility$/);
             if (visMatch && req.method === "POST") {
-                if (!deps.sseManager) {
-                    json(res, 501, { error: "SSE not available" });
-                    return;
-                }
-                const sseManager = deps.sseManager;
                 const clientId = decodeURIComponent(visMatch[1]);
-                if (!sseManager.clients.has(clientId)) {
+                // Trust boundary: accept if the client is (a) currently connected
+                // via SSE, or (b) known to the ClientRegistry (populated on /hello,
+                // persists across SSE disconnect). Registry check fixes the
+                // pagehide-beacon race where iOS PWA suspension drops the SSE TCP
+                // connection before the beacon egresses.
+                const clientKnown = sseManager.clients.has(clientId) ||
+                    deps.clientRegistry?.get(clientId) !== undefined;
+                if (!clientKnown) {
                     json(res, 404, { error: "Client not found" });
                     return;
                 }
@@ -857,11 +1867,42 @@ export function createRequestHandler(deps) {
                     json(res, 400, { error: "Missing or invalid 'visible' field" });
                     return;
                 }
-                // If push service is available, update visibility and session
+                // sessionId patch semantics: absent = preserve, null = clear,
+                // string = replace. Zod can't distinguish omitted from explicit
+                // null after parse, so branch on raw body key.
+                const hasSessionIdKey = Object.prototype.hasOwnProperty.call(body, "sessionId");
+                let sessionIdPatch;
+                if (!hasSessionIdKey) {
+                    sessionIdPatch = undefined;
+                }
+                else if (body.sessionId === null) {
+                    sessionIdPatch = null;
+                }
+                else if (typeof body.sessionId === "string" &&
+                    body.sessionId.length > 0) {
+                    sessionIdPatch = body.sessionId;
+                }
+                else {
+                    sessionIdPatch = null;
+                }
                 if (deps.pushService) {
-                    deps.pushService.setClientVisibility(clientId, body.visible);
-                    if (typeof body.sessionId === "string" && body.sessionId) {
-                        deps.pushService.setClientSession(clientId, body.sessionId);
+                    const { becameVisibleForSession } = deps.pushService.updateClient(clientId, {
+                        visible: body.visible,
+                        sessionId: sessionIdPatch,
+                    });
+                    // Edge-triggered only: heartbeat refreshes repeat the same
+                    // (visible:true, sessionId:X) POST every 15s — firing sendClose
+                    // on each would hammer banner recall. Only the first such
+                    // transition after a change should recall stale banners.
+                    if (becameVisibleForSession) {
+                        void deps.pushService.sendClose(`sess-${becameVisibleForSession}-done`);
+                        if (sessions) {
+                            for (const perm of sessions.pendingPermissions.values()) {
+                                if (perm.sessionId === becameVisibleForSession) {
+                                    void deps.pushService.sendClose(`sess-${becameVisibleForSession}-perm-${perm.requestId}`);
+                                }
+                            }
+                        }
                     }
                 }
                 json(res, 200, { ok: true });
@@ -894,11 +1935,12 @@ export function createRequestHandler(deps) {
                     json(res, 400, { error: "Invalid JSON" });
                     return;
                 }
-                if (!body.endpoint || !body.keys?.auth || !body.keys?.p256dh) {
+                if (!body.endpoint || !body.keys?.auth || !body.keys.p256dh) {
                     json(res, 400, { error: "Missing endpoint or keys (auth, p256dh)" });
                     return;
                 }
                 store.saveSubscription(body.endpoint, body.keys.auth, body.keys.p256dh);
+                // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- defensive
                 if (body.clientId && deps.pushService) {
                     deps.pushService.registerClient(body.clientId, body.endpoint);
                 }
@@ -957,7 +1999,11 @@ export function createRequestHandler(deps) {
             return;
         }
         // --- Static files ---
-        const filePath = join(deps.publicDir, url === "/" ? "/index.html" : url);
+        let staticPath = url;
+        const htmlEntry = HTML_ENTRYPOINTS.find((e) => e.urlPath === staticPath);
+        if (htmlEntry)
+            staticPath = "/" + htmlEntry.file;
+        const filePath = join(deps.publicDir, staticPath);
         if (!filePath.startsWith(deps.publicDir)) {
             res.writeHead(403);
             res.end("Forbidden");
@@ -966,7 +2012,19 @@ export function createRequestHandler(deps) {
         try {
             const data = await readFile(filePath);
             const ext = extname(filePath);
-            res.writeHead(200, { "Content-Type": MIME[ext] ?? "application/octet-stream" });
+            const base = filePath.slice(filePath.lastIndexOf("/") + 1);
+            const isHashedAsset = /\.[A-Za-z0-9_-]{8,}\.(js|css)$/.test(base);
+            const cacheControl = isHashedAsset
+                ? "public, max-age=31536000, immutable"
+                : "no-cache";
+            const headers = {
+                "Content-Type": MIME[ext] ?? "application/octet-stream",
+                "Cache-Control": cacheControl,
+            };
+            // CSP applies to HTML entrypoints (where script/style execute).
+            if (htmlEntry)
+                headers["Content-Security-Policy"] = CSP_POLICY;
+            res.writeHead(200, headers);
             res.end(data);
         }
         catch {