@lelouchhe/webagent 0.4.0 → 0.5.1

package/lib/config.js

@@ -3,6 +3,13 @@ import { parse as parseTOML } from "smol-toml";
 import { z } from "zod";
 export const ConfigSchema = z.object({
     port: z.number().int().positive().default(6800),
+    // Network interface to bind. Default "127.0.0.1" = loopback only
+    // (no LAN exposure). Set to "0.0.0.0" to listen on all IPv4
+    // interfaces, "::" for IPv6/dual-stack, or a specific NIC IP
+    // (e.g. "192.168.1.10") to bind one interface on a multi-homed
+    // host. Note: "localhost" works but resolves via DNS and may
+    // pick IPv6 (`::1`) over IPv4 — prefer the explicit IP form.
+    host: z.string().default("127.0.0.1"),
     data_dir: z.string().default("data"),
     default_cwd: z.string().default(process.cwd()),
     public_dir: z.string().default("dist"),
@@ -35,7 +42,7 @@ export const ConfigSchema = z.object({
     }),
     // [title] — title generation sub-session configuration.
     //
-    // `model` is an array of case-insensitive substring patterns. When the
+    // `models` is an array of case-insensitive substring patterns. When the
     // title sub-session is created, we look at the model list the agent
     // reports (ACP `availableModels`) and pick the first model whose id
     // matches any pattern in order. Match → call `setConfigOption` with
@@ -50,17 +57,17 @@ export const ConfigSchema = z.object({
     //   - "flash"      → Google Gemini (gemini-*-flash)
     //   - "lite"       → Cohere, generic
     //
-    // Set `model = []` to disable substring matching entirely and always
+    // Set `models = []` to disable substring matching entirely and always
     // inherit the agent's default model. To pin one specific model, pass a
-    // single-element array: `model = ["claude-haiku-4.5"]`.
+    // single-element array: `models = ["claude-haiku-4.5"]`.
     title: z
         .object({
-        model: z
+        models: z
             .array(z.string())
             .default(["haiku", "flash-lite", "nano", "mini", "flash", "lite"]),
     })
         .default({
-        model: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
+        models: ["haiku", "flash-lite", "nano", "mini", "flash", "lite"],
     }),
     // [debug] — frontend log level.
     // level ∈ off | debug | info | warn | error. Default "off".

package/lib/image-dimensions.js

@@ -0,0 +1,64 @@
+function valid(width, height) {
+    if (!Number.isInteger(width) || !Number.isInteger(height))
+        return null;
+    if (width <= 0 || height <= 0)
+        return null;
+    return { width, height };
+}
+export function readImageDimensions(buf) {
+    return (readPngDimensions(buf) ?? readGifDimensions(buf) ?? readJpegDimensions(buf));
+}
+function readPngDimensions(buf) {
+    // PNG: signature + IHDR width/height at fixed offsets.
+    if (buf.length >= 24 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47 &&
+        buf.toString("ascii", 12, 16) === "IHDR") {
+        return valid(buf.readUInt32BE(16), buf.readUInt32BE(20));
+    }
+    return null;
+}
+function readGifDimensions(buf) {
+    // GIF87a/GIF89a: logical screen width/height, little-endian.
+    if (buf.length >= 10 &&
+        (buf.toString("ascii", 0, 6) === "GIF87a" ||
+            buf.toString("ascii", 0, 6) === "GIF89a")) {
+        return valid(buf.readUInt16LE(6), buf.readUInt16LE(8));
+    }
+    return null;
+}
+function isJpegSofMarker(marker) {
+    return ((marker >= 0xc0 && marker <= 0xc3) ||
+        (marker >= 0xc5 && marker <= 0xc7) ||
+        (marker >= 0xc9 && marker <= 0xcb) ||
+        (marker >= 0xcd && marker <= 0xcf));
+}
+function readJpegDimensions(buf) {
+    // JPEG: scan marker segments until a SOF marker carrying dimensions.
+    if (buf.length >= 4 && buf[0] === 0xff && buf[1] === 0xd8) {
+        let offset = 2;
+        while (offset + 3 < buf.length) {
+            if (buf[offset] !== 0xff) {
+                offset++;
+                continue;
+            }
+            while (offset < buf.length && buf[offset] === 0xff)
+                offset++;
+            const marker = buf[offset++];
+            if (marker === 0xd9 || marker === 0xda)
+                break;
+            if (offset + 1 >= buf.length)
+                break;
+            const length = buf.readUInt16BE(offset);
+            if (length < 2 || offset + length > buf.length)
+                break;
+            if (isJpegSofMarker(marker) && length >= 7) {
+                return valid(buf.readUInt16BE(offset + 5), buf.readUInt16BE(offset + 3));
+            }
+            offset += length;
+        }
+    }
+    return null;
+}

package/lib/model-picker.js

@@ -0,0 +1,17 @@
+/** Find the first available model whose id matches any pattern. */
+export function pickModelByPatterns(configOptions, patterns) {
+    const normalized = patterns
+        .map((p) => p.trim().toLowerCase())
+        .filter((p) => p.length > 0);
+    if (normalized.length === 0)
+        return null;
+    const modelOpt = configOptions.find((c) => c.id === "model");
+    if (!modelOpt || modelOpt.options.length === 0)
+        return null;
+    for (const pattern of normalized) {
+        const hit = modelOpt.options.find((o) => o.value.toLowerCase().includes(pattern));
+        if (hit)
+            return hit.value;
+    }
+    return null;
+}

package/lib/preflight.js

@@ -120,52 +120,71 @@ function checkAgent(agentCmd) {
     };
 }
 /**
- * Probe whether `port` can be bound on 0.0.0.0 (matching what
- * `server.listen` actually uses). Listens, then closes immediately.
- * There's a tiny race window between close and the real
- * server.listen() — that's fine for diagnostics: the goal is a friendly
- * "port already in use" hint, not a hard guarantee.
+ * Probe whether `host:port` can be bound (matching what `server.listen`
+ * actually uses). Listens, then closes immediately. There's a tiny
+ * race window between close and the real server.listen() — that's
+ * fine for diagnostics: the goal is a friendly hint, not a hard
+ * guarantee.
  *
  * Port 0 means "let the OS pick"; we treat it as always-free.
+ *
+ * Probing the same host as the real server matters: a foreign
+ * listener on 0.0.0.0:PORT occupies 127.0.0.1:PORT too (more-specific
+ * bind fails when wildcard already bound), so binding the configured
+ * host catches conflicts and surfaces EADDRNOTAVAIL when the user
+ * typo'd an IP that isn't on any local interface.
  */
-async function checkPort(port) {
-    if (port === 0) {
-        return { ok: true, name: "port", detail: "0 (OS-assigned)" };
-    }
-    // Probe must bind to the same address family as the real server
-    // (server.ts uses "0.0.0.0"). Probing 127.0.0.1 lets a foreign
-    // listener on 0.0.0.0:PORT slip past preflight and only surface as
-    // EADDRINUSE during the real server.listen() — exactly the case
-    // we're trying to catch.
+async function checkPort(port, host) {
+    const label = `${host}:${port}`;
+    // port=0 still gets probed: the OS picks any free port, but bind can
+    // still fail with EADDRNOTAVAIL if `host` isn't on any local
+    // interface — that's exactly the typo we want to catch.
     const result = await new Promise((settle) => {
         const probe = createServer();
         probe.once("error", (err) => {
             settle({ code: err.code ?? "unknown" });
         });
-        probe.listen(port, "0.0.0.0", () => {
+        probe.listen(port, host, () => {
+            const addr = probe.address();
+            const assigned = typeof addr === "object" && addr ? addr.port : port;
             probe.close(() => {
-                settle({});
+                settle({ assigned });
             });
         });
     });
     if (!result.code) {
-        return { ok: true, name: "port", detail: String(port) };
+        if (port === 0) {
+            return {
+                ok: true,
+                name: "port",
+                detail: `${host}:0 (OS-assigned → ${result.assigned})`,
+            };
+        }
+        return { ok: true, name: "port", detail: label };
     }
     if (result.code === "EADDRINUSE") {
         return {
             ok: false,
             name: "port",
-            detail: `${port} (in use)`,
-            hint: `port ${port} is already in use (EADDRINUSE).\nfind the owner: ${process.platform === "win32"
+            detail: `${label} (in use)`,
+            hint: `${label} is already in use (EADDRINUSE).\nfind the owner: ${process.platform === "win32"
                 ? `netstat -ano | findstr :${port}`
                 : `lsof -nP -iTCP:${port} -sTCP:LISTEN`}\nor change \`port\` in config.toml to a free port.`,
         };
     }
+    if (result.code === "EADDRNOTAVAIL") {
+        return {
+            ok: false,
+            name: "port",
+            detail: `${label} (${result.code})`,
+            hint: `cannot bind ${label}: ${result.code}\nthe host '${host}' is not assigned to any local interface.\ncheck \`host\` in config.toml — typical values are "127.0.0.1" (loopback) or "0.0.0.0" (all interfaces).`,
+        };
+    }
     return {
         ok: false,
         name: "port",
-        detail: `${port} (${result.code})`,
-        hint: `cannot bind port ${port}: ${result.code}\ncheck firewall / permissions, or change \`port\` in config.toml.`,
+        detail: `${label} (${result.code})`,
+        hint: `cannot bind ${label}: ${result.code}\ncheck firewall / permissions, or change \`host\`/\`port\` in config.toml.`,
     };
 }
 /**
@@ -179,7 +198,7 @@ export async function runPreflight(opts) {
     checks.push(checkDataDir(opts.data_dir));
     const agent = checkAgent(opts.agent_cmd);
     checks.push(agent);
-    checks.push(await checkPort(opts.port));
+    checks.push(await checkPort(opts.port, opts.host));
     for (const c of checks) {
         if (c.ok)
             printOk(c);

package/lib/push-service.js

@@ -46,18 +46,14 @@ export function isAppleEndpoint(endpoint) {
     return host === "web.push.apple.com" || host.endsWith(".push.apple.com");
 }
 function emptyClientState() {
-    return { visible: false, sessionId: null, endpoint: null, visibleSince: 0 };
+    return { endpoint: null };
 }
 export class PushService {
     store;
     vapidKeys;
     /**
-     * Consolidated per-client state. Previously 3 separate Maps
-     * (clientVisibility/clientEndpoints/clientSessions) which drifted under
-     * partial updates. v2 merges them; `visibleSince` stamps when the client
-     * transitioned to visible so the server can TTL-expire "ghost" visibility
-     * records left by iOS PWA process suspension (where the client never gets
-     * to POST visible:false).
+     * Per-client transport state — only the push endpoint. Visibility lives
+     * in ClientRegistry as of Plan C Step 4.
      */
     clients = new Map();
     /** endpoint → consecutive failure count (absent or 0 = healthy) */
@@ -65,7 +61,8 @@ export class PushService {
     globalVisibilitySuppression;
     visibilityTtlMs;
     now;
-    constructor(store, dataDir, vapidSubject, options = {}) {
+    clientRegistry;
+    constructor(store, dataDir, vapidSubject, options) {
         this.store = store;
         this.vapidKeys = this.loadOrGenerateKeys(dataDir);
         webpush.setVapidDetails(vapidSubject, this.vapidKeys.publicKey, this.vapidKeys.privateKey);
@@ -73,6 +70,7 @@ export class PushService {
             options.globalVisibilitySuppression ?? true;
         this.visibilityTtlMs = options.visibilityTtlMs ?? 60_000;
         this.now = options.now ?? (() => Date.now());
+        this.clientRegistry = options.clientRegistry;
     }
     // ---------------------------------------------------------------------------
     // VAPID keys
@@ -123,43 +121,18 @@ export class PushService {
         return { kind: "notify", title, body, tag, data: { sessionId } };
     }
     // ---------------------------------------------------------------------------
-    // Client visibility tracking
+    // Endpoint mapping (transport-only as of Plan C Step 4)
     // ---------------------------------------------------------------------------
     /**
-     * Atomic consolidated setter. All visibility/session/endpoint updates
-     * should route through here. Callers distinguish "preserve" from "clear"
-     * by omitting the key vs passing `null`. Returns an edge flag so the
-     * caller can fire edge-triggered side effects (e.g. sendClose) without
-     * double-firing on every heartbeat refresh.
+     * Set the push endpoint for a client. Identity-layer state (visibility,
+     * active session) goes through ClientRegistry.setVisibility, not here.
      */
     updateClient(clientId, patch) {
         const prev = this.clients.get(clientId) ?? emptyClientState();
-        const wasVisibleForSession = prev.visible && prev.sessionId != null ? prev.sessionId : null;
         const next = { ...prev };
-        if (patch.visible !== undefined) {
-            next.visible = patch.visible;
-            next.visibleSince = patch.visible ? this.now() : 0;
-        }
-        if (patch.sessionId !== undefined)
-            next.sessionId = patch.sessionId;
         if (patch.endpoint !== undefined)
             next.endpoint = patch.endpoint;
-        const becameVisibleForSession = next.visible &&
-            next.sessionId != null &&
-            next.sessionId !== wasVisibleForSession
-            ? next.sessionId
-            : null;
-        // Any transition into "visible + session X" restarts the TTL clock,
-        // including a session-switch that arrives without an explicit
-        // visible:true in the patch (e.g. a session_created POST that only
-        // carries sessionId). Otherwise the TTL would keep counting from the
-        // previous session's first-visible moment and could prematurely
-        // declare the newly-focused session "stale".
-        if (becameVisibleForSession) {
-            next.visibleSince = this.now();
-        }
         this.clients.set(clientId, next);
-        return { becameVisibleForSession };
     }
     /**
      * Read-only snapshot for tests and diagnostics. Do NOT mutate the
@@ -168,40 +141,29 @@ export class PushService {
     getClientState(clientId) {
         return this.clients.get(clientId) ?? null;
     }
-    /** @deprecated Shim: prefer `updateClient({ visible })`. */
-    setClientVisibility(clientId, visible) {
-        this.updateClient(clientId, { visible });
-    }
-    /** @deprecated Shim: prefer `updateClient({ sessionId })`. */
-    setClientSession(clientId, sessionId) {
-        this.updateClient(clientId, { sessionId });
-    }
-    /** @deprecated Shim: prefer `updateClient({ endpoint })`. */
     registerClient(clientId, endpoint) {
         this.updateClient(clientId, { endpoint });
     }
     removeClient(clientId) {
         this.clients.delete(clientId);
+        // Disconnect also wipes identity-layer state so visibility queries don't
+        // leak past the SSE lifetime. Production calls removeClient on SSE close
+        // (see sse-manager); tests expect the same.
+        this.clientRegistry.remove(clientId);
     }
     hasVisibleClient() {
-        const now = this.now();
-        for (const s of this.clients.values()) {
-            if (s.visible && now - s.visibleSince <= this.visibilityTtlMs)
-                return true;
-        }
-        return false;
+        return this.clientRegistry.hasAnyVisibleClient();
     }
     /** Check if a specific endpoint has at least one visible (non-stale) client. */
     isEndpointVisible(endpoint) {
-        const now = this.now();
-        for (const s of this.clients.values()) {
+        // Identity (visible) comes from registry, transport (endpoint↔clientId)
+        // stays with pushService.clients.
+        const reg = this.clientRegistry;
+        for (const [clientId, s] of this.clients) {
             if (s.endpoint !== endpoint)
                 continue;
-            if (!s.visible)
-                continue;
-            if (now - s.visibleSince > this.visibilityTtlMs)
-                continue;
-            return true;
+            if (reg.isClientVisible(clientId))
+                return true;
         }
         return false;
     }
@@ -219,17 +181,7 @@ export class PushService {
     isSessionVisibleToAnyClient(sessionId) {
         if (!this.globalVisibilitySuppression)
             return false;
-        const now = this.now();
-        for (const s of this.clients.values()) {
-            if (!s.visible)
-                continue;
-            if (s.sessionId !== sessionId)
-                continue;
-            if (now - s.visibleSince > this.visibilityTtlMs)
-                continue;
-            return true;
-        }
-        return false;
+        return this.clientRegistry.isSessionVisibleToAnyClient(sessionId);
     }
     // ---------------------------------------------------------------------------
     // High-level: decide whether to push, and if so, send

package/lib/routes.js

@@ -17,6 +17,7 @@ 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";
+import { readImageDimensions } from "./image-dimensions.js";
 const IS_WIN = process.platform === "win32";
 const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
 const MIME = {
@@ -30,6 +31,8 @@ const MIME = {
     ".jpeg": "image/jpeg",
     ".gif": "image/gif",
     ".webp": "image/webp",
+    ".woff2": "font/woff2",
+    ".wasm": "application/wasm",
 };
 /**
  * HTML entrypoints served by this app. Any new HTML page MUST be registered
@@ -51,7 +54,10 @@ export const HTML_ENTRYPOINTS = [
  *
  *  - 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)
+ *  - script-src 'self' 'wasm-unsafe-eval' (no inline; theme bootstrap is
+ *    /theme-init.js. 'wasm-unsafe-eval' is the narrow CSP3 token that
+ *    permits WebAssembly.instantiate() WITHOUT re-enabling eval()/Function;
+ *    needed by any wasm consumer.)
  *  - 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
@@ -59,7 +65,7 @@ export const HTML_ENTRYPOINTS = [
 export const CSP_POLICY = [
     "default-src 'self'",
     "img-src 'self' data: blob:",
-    "script-src 'self'",
+    "script-src 'self' 'wasm-unsafe-eval'",
     "style-src 'self'",
     "connect-src 'self'",
     "object-src 'none'",
@@ -91,6 +97,20 @@ function getClientOpId(req) {
         return v;
     return null;
 }
+function logPromptRejectBeforeSave(fields) {
+    plog.warn("rejected before save", {
+        sessionId: fields.sessionId.slice(0, 8),
+        status: fields.status,
+        reason: fields.reason,
+        ...(fields.opId ? { opId: fields.opId } : {}),
+        ...(fields.textLength != null ? { textLength: fields.textLength } : {}),
+        ...(fields.attachmentCount != null
+            ? { attachmentCount: fields.attachmentCount }
+            : {}),
+        ...(fields.busyKind ? { busyKind: fields.busyKind } : {}),
+        ...(fields.error ? { error: fields.error } : {}),
+    });
+}
 function tryReplayClientOp(req, res, store, sessionId) {
     const opId = getClientOpId(req);
     if (!opId)
@@ -317,6 +337,7 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                             finalPath = join(dir, `${uploadId}.${fileExt}`);
                         }
                     }
+                    const imageDimensions = kind === "image" ? readImageDimensions(head) : null;
                     await rename(tmpPath, finalPath);
                     const rp = await realpath(finalPath);
                     const row = store.insertAttachment({
@@ -327,6 +348,8 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                         mime: fileMime,
                         size: bytesWritten,
                         realpath: rp,
+                        width: imageDimensions?.width ?? null,
+                        height: imageDimensions?.height ?? null,
                     });
                     // Invalidate the per-session attachment label cache so the
                     // next egress (SSE broadcast or replay) sees this new row.
@@ -344,6 +367,8 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                         displayName: row.name,
                         mimeType: row.mime,
                         size: row.size,
+                        width: row.width,
+                        height: row.height,
                         kind: row.kind,
                         path: `sessions/${sessionId}/attachments/${fileName}`,
                         url: fileUrl,
@@ -779,17 +804,36 @@ export function createRequestHandler(deps) {
             const promptMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/prompt\/?(\?.*)?$/);
             if (promptMatch && req.method === "POST") {
                 const sessionId = decodeURIComponent(promptMatch[1]);
+                const requestOpId = getClientOpId(req);
                 const session = store.getSession(sessionId);
                 if (!session) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 404,
+                        reason: "session_not_found",
+                        opId: requestOpId,
+                    });
                     json(res, 404, { error: "Session not found" });
                     return;
                 }
                 const bridge = getBridge?.();
                 if (!bridge) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 503,
+                        reason: "agent_not_ready",
+                        opId: requestOpId,
+                    });
                     json(res, 503, { error: "Agent not ready yet" });
                     return;
                 }
                 if (!sessions) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 503,
+                        reason: "session_manager_unavailable",
+                        opId: requestOpId,
+                    });
                     json(res, 503, { error: "Session manager not available" });
                     return;
                 }
@@ -801,6 +845,13 @@ export function createRequestHandler(deps) {
                     await sessions.ensureResumed(bridge, sessionId);
                 }
                 catch (err) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 500,
+                        reason: "resume_failed",
+                        opId,
+                        error: errorMessage(err),
+                    });
                     json(res, 500, {
                         error: `Failed to resume session: ${err instanceof Error ? err.message : String(err)}`,
                     });
@@ -809,6 +860,13 @@ export function createRequestHandler(deps) {
                 // Check if session is busy
                 const busyKind = sessions.getBusyKind(sessionId);
                 if (busyKind) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 409,
+                        reason: "session_busy",
+                        opId,
+                        busyKind,
+                    });
                     json(res, 409, { error: "Session is busy", busyKind });
                     return;
                 }
@@ -817,10 +875,26 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 400,
+                        reason: "invalid_json",
+                        opId,
+                    });
                     json(res, 400, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.text) {
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: 400,
+                        reason: "missing_text",
+                        opId,
+                        textLength: 0,
+                        attachmentCount: Array.isArray(body.attachments)
+                            ? body.attachments.length
+                            : undefined,
+                    });
                     json(res, 400, { error: "Missing required field: text" });
                     return;
                 }
@@ -830,6 +904,13 @@ export function createRequestHandler(deps) {
                 const attachments = body.attachments;
                 if (attachments) {
                     if (!Array.isArray(attachments)) {
+                        logPromptRejectBeforeSave({
+                            sessionId,
+                            status: 400,
+                            reason: "attachments_not_array",
+                            opId,
+                            textLength: body.text.length,
+                        });
                         json(res, 400, { error: "attachments must be an array" });
                         return;
                     }
@@ -841,14 +922,32 @@ export function createRequestHandler(deps) {
                             typeof att.attachmentId !== "string" ||
                             typeof att.displayName !== "string" ||
                             typeof att.mimeType !== "string") {
+                            logPromptRejectBeforeSave({
+                                sessionId,
+                                status: 400,
+                                reason: "invalid_attachment_entry",
+                                opId,
+                                textLength: body.text.length,
+                                attachmentCount: attachments.length,
+                            });
                             json(res, 400, { error: "Invalid attachment entry" });
                             return;
                         }
                         if (typeof att.uri === "string" ||
                             typeof att.data === "string" ||
-                            typeof att.path === "string") {
+                            typeof att.path === "string" ||
+                            typeof att.width === "number" ||
+                            typeof att.height === "number") {
+                            logPromptRejectBeforeSave({
+                                sessionId,
+                                status: 400,
+                                reason: "client_supplied_attachment_data",
+                                opId,
+                                textLength: body.text.length,
+                                attachmentCount: attachments.length,
+                            });
                             json(res, 400, {
-                                error: "Client must not supply uri/data/path",
+                                error: "Client must not supply uri/data/path/width/height",
                             });
                             return;
                         }
@@ -873,6 +972,9 @@ export function createRequestHandler(deps) {
                             displayName: a.displayName,
                             mimeType: a.mimeType,
                             path: `/api/v1/sessions/${sessionId}/attachments/${fileName}`,
+                            ...(row.width != null && row.height != null
+                                ? { width: row.width, height: row.height }
+                                : {}),
                         },
                     ];
                 });
@@ -1885,21 +1987,27 @@ export function createRequestHandler(deps) {
                 else {
                     sessionIdPatch = null;
                 }
-                if (deps.pushService) {
-                    const { becameVisibleForSession } = deps.pushService.updateClient(clientId, {
+                if (deps.clientRegistry) {
+                    // setVisibility no-ops on unknown clients; auto-register here so
+                    // SSE-only clients (which haven't sent /hello yet) still take
+                    // effect. The trust boundary above already gated on identity.
+                    if (!deps.clientRegistry.get(clientId)) {
+                        deps.clientRegistry.register(clientId, { capabilities: [] });
+                    }
+                    const { becameVisibleFor } = deps.clientRegistry.setVisibility(clientId, {
                         visible: body.visible,
-                        sessionId: sessionIdPatch,
+                        active: 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 (becameVisibleFor && deps.pushService) {
+                        void deps.pushService.sendClose(`sess-${becameVisibleFor}-done`);
                         if (sessions) {
                             for (const perm of sessions.pendingPermissions.values()) {
-                                if (perm.sessionId === becameVisibleForSession) {
-                                    void deps.pushService.sendClose(`sess-${becameVisibleForSession}-perm-${perm.requestId}`);
+                                if (perm.sessionId === becameVisibleFor) {
+                                    void deps.pushService.sendClose(`sess-${becameVisibleFor}-perm-${perm.requestId}`);
                                 }
                             }
                         }
@@ -2014,7 +2122,11 @@ export function createRequestHandler(deps) {
             const ext = extname(filePath);
             const base = filePath.slice(filePath.lastIndexOf("/") + 1);
             const isHashedAsset = /\.[A-Za-z0-9_-]{8,}\.(js|css)$/.test(base);
-            const cacheControl = isHashedAsset
+            // `/lib/**` is vendored third-party content pinned by upstream SHA in
+            // package metadata — treat as immutable just like content-hashed bundles.
+            // Avoids re-downloading multi-hundred-KB wasm on every consumer init.
+            const isVendoredLib = staticPath.startsWith("/lib/");
+            const cacheControl = isHashedAsset || isVendoredLib
                 ? "public, max-age=31536000, immutable"
                 : "no-cache";
             const headers = {