@lelouchhe/webagent 0.5.1 → 0.7.0

package/lib/routes.js

@@ -10,6 +10,7 @@ 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 { agentCommandToken, resolveAgentCommand } from "./agent-commands.js";
 import { log } from "./log.js";
 const rlog = log.scope("routes");
 const plog = rlog.scope("prompt");
@@ -18,6 +19,7 @@ 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";
+import { HTTP_STATUS } from "./http-status.js";
 const IS_WIN = process.platform === "win32";
 const SAFE_ID = /^[a-zA-Z0-9_-]+$/;
 const MIME = {
@@ -172,7 +174,7 @@ 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" });
+        json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
         return;
     }
     const dir = join(dataDir, "sessions", sessionId, "attachments");
@@ -233,7 +235,7 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
             });
         }
         catch {
-            void finish(400, { error: "Invalid multipart" });
+            void finish(HTTP_STATUS.BAD_REQUEST, { error: "Invalid multipart" });
             return;
         }
         bb.on("file", (fieldName, stream, info) => {
@@ -246,7 +248,9 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
             sawFile = true;
             if (fieldName !== "file") {
                 stream.resume();
-                void finish(400, { error: "Unexpected field name" });
+                void finish(HTTP_STATUS.BAD_REQUEST, {
+                    error: "Unexpected field name",
+                });
                 return;
             }
             fileMime = (info.mimeType || "application/octet-stream").toLowerCase();
@@ -295,22 +299,28 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                     await writeDone;
                     if (aborted) {
                         await cleanupTmp();
-                        await finish(400, { error: "Upload aborted" });
+                        await finish(HTTP_STATUS.BAD_REQUEST, { error: "Upload aborted" });
                         return;
                     }
                     if (limitExceeded) {
                         await cleanupTmp();
-                        await finish(413, { error: "Upload too large" });
+                        await finish(HTTP_STATUS.PAYLOAD_TOO_LARGE, {
+                            error: "Upload too large",
+                        });
                         return;
                     }
                     if (writeError) {
                         await cleanupTmp();
-                        await finish(500, { error: "Upload failed" });
+                        await finish(HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+                            error: "Upload failed",
+                        });
                         return;
                     }
                     if (!sawFile || !tmpPath || !finalPath || !displayName) {
                         await cleanupTmp();
-                        await finish(400, { error: "Missing file part" });
+                        await finish(HTTP_STATUS.BAD_REQUEST, {
+                            error: "Missing file part",
+                        });
                         return;
                     }
                     // Sniff the actual mime from file content (magic bytes + UTF-8
@@ -362,7 +372,7 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                     const fileUrl = deps.attachmentSecret
                         ? `${basePath}?${signAttachmentUrl(basePath, deps.attachmentSecret, 3600)}`
                         : basePath;
-                    await finish(200, {
+                    await finish(HTTP_STATUS.OK, {
                         attachmentId: row.id,
                         displayName: row.name,
                         mimeType: row.mime,
@@ -376,7 +386,9 @@ async function handleAttachmentUpload(req, res, sessionId, deps) {
                 }
                 catch (err) {
                     await cleanupTmp();
-                    await finish(500, { error: errorMessage(err) });
+                    await finish(HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+                        error: errorMessage(err),
+                    });
                 }
             })();
         });
@@ -395,7 +407,7 @@ export function createRequestHandler(deps) {
             if (!isWhitelistedPath(method, path)) {
                 const result = authenticate(req.headers, deps.authStore);
                 if (!result.ok) {
-                    res.writeHead(401, {
+                    res.writeHead(HTTP_STATUS.UNAUTHORIZED, {
                         "Content-Type": "application/json",
                         "WWW-Authenticate": "Bearer",
                     });
@@ -427,7 +439,7 @@ export function createRequestHandler(deps) {
             res.setHeader("Content-Type", "application/json");
             // GET /api/v1 — discovery endpoint
             if (url === "/api/v1" && req.method === "GET") {
-                json(res, 200, {
+                json(res, HTTP_STATUS.OK, {
                     version: "v1",
                     endpoints: {
                         sessions: "/api/v1/sessions",
@@ -452,7 +464,7 @@ export function createRequestHandler(deps) {
             }
             // --- GET /api/v1/config ---
             if (url === "/api/v1/config" && req.method === "GET") {
-                json(res, 200, {
+                json(res, HTTP_STATUS.OK, {
                     configOptions: sessions?.cachedConfigOptions ?? [],
                     cancelTimeout: deps.limits.cancel_timeout ?? 0,
                     recentPathsLimit: deps.limits.recent_paths ?? 10,
@@ -469,12 +481,12 @@ export function createRequestHandler(deps) {
                     limit: isNaN(limit) ? 0 : limit,
                     ttlDays,
                 });
-                json(res, 200, paths);
+                json(res, HTTP_STATUS.OK, paths);
                 return;
             }
             // GET /api/v1/version
             if (url === "/api/v1/version" && req.method === "GET") {
-                json(res, 200, {
+                json(res, HTTP_STATUS.OK, {
                     server: deps.serverVersion ?? "unknown",
                     agent: sessions?.agentInfo ?? null,
                 });
@@ -484,10 +496,10 @@ export function createRequestHandler(deps) {
             if (url === "/api/v1/auth/verify" && req.method === "GET") {
                 const principal = principalByRequest.get(req);
                 if (!principal) {
-                    json(res, 401, { error: "Unauthorized" });
+                    json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
                     return;
                 }
-                json(res, 200, {
+                json(res, HTTP_STATUS.OK, {
                     ok: true,
                     name: principal.name,
                     scope: principal.scope,
@@ -498,18 +510,20 @@ export function createRequestHandler(deps) {
             if (url === "/api/v1/sse-ticket" && req.method === "POST") {
                 const principal = principalByRequest.get(req);
                 if (!principal) {
-                    json(res, 401, { error: "Unauthorized" });
+                    json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
                     return;
                 }
                 if (!deps.ticketStore) {
-                    json(res, 501, { error: "SSE not available" });
+                    json(res, HTTP_STATUS.NOT_IMPLEMENTED, {
+                        error: "SSE not available",
+                    });
                     return;
                 }
                 const ticket = deps.ticketStore.mint({
                     tokenName: principal.name,
                     scope: principal.scope,
                 });
-                json(res, 200, { ticket, expiresIn: 60 });
+                json(res, HTTP_STATUS.OK, { ticket, expiresIn: 60 });
                 return;
             }
             // --- Token management (admin scope) ---
@@ -519,7 +533,7 @@ export function createRequestHandler(deps) {
             if (url === "/api/v1/tokens" && req.method === "GET") {
                 const principal = principalByRequest.get(req);
                 if (!deps.authStore || !principal) {
-                    json(res, 401, { error: "Unauthorized" });
+                    json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
                     return;
                 }
                 const all = deps.authStore.list();
@@ -533,18 +547,18 @@ export function createRequestHandler(deps) {
                     lastUsedAt: t.lastUsedAt,
                     isSelf: t.name === principal.name,
                 }));
-                json(res, 200, list);
+                json(res, HTTP_STATUS.OK, 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" });
+                    json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
                     return;
                 }
                 if (principal.scope !== "admin") {
-                    json(res, 403, { error: "Forbidden" });
+                    json(res, HTTP_STATUS.FORBIDDEN, { error: "Forbidden" });
                     return;
                 }
                 let body;
@@ -552,13 +566,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 const name = typeof body.name === "string" ? body.name : "";
                 try {
                     const created = await deps.authStore.addToken(name, "api");
-                    json(res, 201, {
+                    json(res, HTTP_STATUS.CREATED, {
                         token: created.token,
                         name: created.record.name,
                         scope: created.record.scope,
@@ -567,10 +581,10 @@ export function createRequestHandler(deps) {
                 catch (err) {
                     const msg = errorMessage(err);
                     if (/already exists|duplicate/i.test(msg)) {
-                        json(res, 409, { error: msg });
+                        json(res, HTTP_STATUS.CONFLICT, { error: msg });
                     }
                     else {
-                        json(res, 400, { error: msg });
+                        json(res, HTTP_STATUS.BAD_REQUEST, { error: msg });
                     }
                 }
                 return;
@@ -580,33 +594,35 @@ export function createRequestHandler(deps) {
             if (tokenDelMatch && req.method === "DELETE") {
                 const principal = principalByRequest.get(req);
                 if (!deps.authStore || !principal) {
-                    json(res, 401, { error: "Unauthorized" });
+                    json(res, HTTP_STATUS.UNAUTHORIZED, { error: "Unauthorized" });
                     return;
                 }
                 if (principal.scope !== "admin") {
-                    json(res, 403, { error: "Forbidden" });
+                    json(res, HTTP_STATUS.FORBIDDEN, { error: "Forbidden" });
                     return;
                 }
                 const name = decodeURIComponent(tokenDelMatch[1]);
                 if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
-                    json(res, 400, { error: "Invalid token name" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid token name" });
                     return;
                 }
                 if (name === principal.name) {
-                    json(res, 400, { error: "Cannot revoke the token you are using" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        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" });
+                        json(res, HTTP_STATUS.NOT_FOUND, { error: "Token not found" });
                         return;
                     }
-                    res.writeHead(204);
+                    res.writeHead(HTTP_STATUS.NO_CONTENT);
                     res.end();
                 }
                 catch (err) {
-                    json(res, 400, { error: errorMessage(err) });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: errorMessage(err) });
                 }
                 return;
             }
@@ -614,19 +630,23 @@ export function createRequestHandler(deps) {
             if (url === "/api/v1/bridge/reload" && req.method === "POST") {
                 const bridge = getBridge?.();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 if (bridge.reloading) {
-                    json(res, 409, { error: "Already reloading" });
+                    json(res, HTTP_STATUS.CONFLICT, { error: "Already reloading" });
                     return;
                 }
                 try {
                     await bridge.restart(sessions, titleService);
-                    json(res, 200, { ok: true });
+                    json(res, HTTP_STATUS.OK, { ok: true });
                 }
                 catch (err) {
-                    json(res, 500, { error: errorMessage(err) });
+                    json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+                        error: errorMessage(err),
+                    });
                 }
                 return;
             }
@@ -636,7 +656,7 @@ export function createRequestHandler(deps) {
             if (permListMatch && req.method === "GET") {
                 const sessionId = decodeURIComponent(permListMatch[1]);
                 const perms = sessions?.getPendingPermissions(sessionId) ?? [];
-                json(res, 200, perms);
+                json(res, HTTP_STATUS.OK, perms);
                 return;
             }
             // POST /api/v1/sessions/:id/permissions/:reqId
@@ -649,16 +669,18 @@ export function createRequestHandler(deps) {
                     return;
                 const perm = sessions?.pendingPermissions.get(requestId);
                 if (!perm) {
-                    json(res, 404, { error: "Permission not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Permission not found" });
                     return;
                 }
                 if (perm.sessionId !== sessionId) {
-                    json(res, 400, { error: "Session ID mismatch" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Session ID mismatch" });
                     return;
                 }
                 const bridge = getBridge?.();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 let body;
@@ -666,11 +688,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.optionId && !body.denied) {
-                    json(res, 400, { error: "Provide optionId or denied:true" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Provide optionId or denied:true",
+                    });
                     return;
                 }
                 const denied = Boolean(body.denied);
@@ -699,8 +723,8 @@ export function createRequestHandler(deps) {
                     void deps.pushService.sendClose(`sess-${perm.sessionId}-perm-${requestId}`);
                 }
                 const okBody = { ok: true };
-                saveClientOpResult(store, opId, sessionId, 200, okBody);
-                json(res, 200, okBody);
+                saveClientOpResult(store, opId, sessionId, HTTP_STATUS.OK, okBody);
+                json(res, HTTP_STATUS.OK, okBody);
                 return;
             }
             // --- POST /api/v1/sessions/:id/cancel ---
@@ -709,12 +733,14 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(cancelMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const bridge = getBridge?.();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
@@ -739,8 +765,8 @@ export function createRequestHandler(deps) {
                     sessions.state.armCancelSafety(sessionId, cancelTimeout);
                 sessions?.syncBusy(sessionId);
                 const okBody = { ok: true };
-                saveClientOpResult(store, opId, sessionId, 200, okBody);
-                json(res, 200, okBody);
+                saveClientOpResult(store, opId, sessionId, HTTP_STATUS.OK, okBody);
+                json(res, HTTP_STATUS.OK, okBody);
                 return;
             }
             // --- GET /api/v1/sessions/:id/status ---
@@ -749,12 +775,12 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(statusMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const busyKind = sessions?.getBusyKind(sessionId) ?? null;
                 const pendingPerms = sessions?.getPendingPermissions(sessionId) ?? [];
-                json(res, 200, {
+                json(res, HTTP_STATUS.OK, {
                     busy: busyKind != null,
                     busyKind,
                     pendingPermissions: pendingPerms,
@@ -771,20 +797,37 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(snapshotMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 if (!sessions) {
-                    json(res, 503, { error: "Session manager not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Session manager not available",
+                    });
                     return;
                 }
+                const bridge = getBridge?.();
+                if (bridge && !sessions.liveSessions.has(sessionId)) {
+                    try {
+                        // Command discovery happens during session/load. Snapshot is the
+                        // authoritative hydration boundary, so it must join any in-flight
+                        // restore before reading the per-session command state.
+                        await sessions.ensureResumed(bridge, sessionId);
+                    }
+                    catch {
+                        json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                            error: "Failed to restore session",
+                        });
+                        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, {
+                json(res, HTTP_STATUS.OK, {
                     version: 1,
                     seq: runtimeState.seq,
                     session: {
@@ -797,6 +840,7 @@ export function createRequestHandler(deps) {
                         lastEventSeq,
                     },
                     runtime: runtimeState.runtime,
+                    agentCommands: sessions.getAgentCommands(sessionId),
                 }, req);
                 return;
             }
@@ -809,32 +853,36 @@ export function createRequestHandler(deps) {
                 if (!session) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 404,
+                        status: HTTP_STATUS.NOT_FOUND,
                         reason: "session_not_found",
                         opId: requestOpId,
                     });
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const bridge = getBridge?.();
                 if (!bridge) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 503,
+                        status: HTTP_STATUS.SERVICE_UNAVAILABLE,
                         reason: "agent_not_ready",
                         opId: requestOpId,
                     });
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 if (!sessions) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 503,
+                        status: HTTP_STATUS.SERVICE_UNAVAILABLE,
                         reason: "session_manager_unavailable",
                         opId: requestOpId,
                     });
-                    json(res, 503, { error: "Session manager not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Session manager not available",
+                    });
                     return;
                 }
                 const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
@@ -847,12 +895,12 @@ export function createRequestHandler(deps) {
                 catch (err) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 500,
+                        status: HTTP_STATUS.INTERNAL_SERVER_ERROR,
                         reason: "resume_failed",
                         opId,
                         error: errorMessage(err),
                     });
-                    json(res, 500, {
+                    json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
                         error: `Failed to resume session: ${err instanceof Error ? err.message : String(err)}`,
                     });
                     return;
@@ -862,12 +910,15 @@ export function createRequestHandler(deps) {
                 if (busyKind) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 409,
+                        status: HTTP_STATUS.CONFLICT,
                         reason: "session_busy",
                         opId,
                         busyKind,
                     });
-                    json(res, 409, { error: "Session is busy", busyKind });
+                    json(res, HTTP_STATUS.CONFLICT, {
+                        error: "Session is busy",
+                        busyKind,
+                    });
                     return;
                 }
                 let body;
@@ -877,17 +928,17 @@ export function createRequestHandler(deps) {
                 catch {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 400,
+                        status: HTTP_STATUS.BAD_REQUEST,
                         reason: "invalid_json",
                         opId,
                     });
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.text) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 400,
+                        status: HTTP_STATUS.BAD_REQUEST,
                         reason: "missing_text",
                         opId,
                         textLength: 0,
@@ -895,7 +946,9 @@ export function createRequestHandler(deps) {
                             ? body.attachments.length
                             : undefined,
                     });
-                    json(res, 400, { error: "Missing required field: text" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: text",
+                    });
                     return;
                 }
                 // Validate attachment shape: client must NEVER supply uri/data/path,
@@ -906,12 +959,14 @@ export function createRequestHandler(deps) {
                     if (!Array.isArray(attachments)) {
                         logPromptRejectBeforeSave({
                             sessionId,
-                            status: 400,
+                            status: HTTP_STATUS.BAD_REQUEST,
                             reason: "attachments_not_array",
                             opId,
                             textLength: body.text.length,
                         });
-                        json(res, 400, { error: "attachments must be an array" });
+                        json(res, HTTP_STATUS.BAD_REQUEST, {
+                            error: "attachments must be an array",
+                        });
                         return;
                     }
                     for (const raw of attachments) {
@@ -924,13 +979,15 @@ export function createRequestHandler(deps) {
                             typeof att.mimeType !== "string") {
                             logPromptRejectBeforeSave({
                                 sessionId,
-                                status: 400,
+                                status: HTTP_STATUS.BAD_REQUEST,
                                 reason: "invalid_attachment_entry",
                                 opId,
                                 textLength: body.text.length,
                                 attachmentCount: attachments.length,
                             });
-                            json(res, 400, { error: "Invalid attachment entry" });
+                            json(res, HTTP_STATUS.BAD_REQUEST, {
+                                error: "Invalid attachment entry",
+                            });
                             return;
                         }
                         if (typeof att.uri === "string" ||
@@ -940,19 +997,41 @@ export function createRequestHandler(deps) {
                             typeof att.height === "number") {
                             logPromptRejectBeforeSave({
                                 sessionId,
-                                status: 400,
+                                status: HTTP_STATUS.BAD_REQUEST,
                                 reason: "client_supplied_attachment_data",
                                 opId,
                                 textLength: body.text.length,
                                 attachmentCount: attachments.length,
                             });
-                            json(res, 400, {
+                            json(res, HTTP_STATUS.BAD_REQUEST, {
                                 error: "Client must not supply uri/data/path/width/height",
                             });
                             return;
                         }
                     }
                 }
+                let agentText = body.text;
+                if (body.text.startsWith("//")) {
+                    const resolved = resolveAgentCommand(body.text, sessions.getAgentCommands(sessionId).commands);
+                    if (!resolved) {
+                        const command = agentCommandToken(body.text);
+                        logPromptRejectBeforeSave({
+                            sessionId,
+                            status: HTTP_STATUS.UNPROCESSABLE_CONTENT,
+                            reason: "unknown_command",
+                            opId,
+                            textLength: body.text.length,
+                            attachmentCount: attachments?.length,
+                        });
+                        json(res, HTTP_STATUS.UNPROCESSABLE_CONTENT, {
+                            error: "Unknown command",
+                            command,
+                            prefix: "//",
+                        });
+                        return;
+                    }
+                    agentText = resolved.agentText;
+                }
                 // 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
@@ -1010,7 +1089,7 @@ export function createRequestHandler(deps) {
                 sessions.activePrompts.add(sessionId);
                 sessions.syncBusy(sessionId);
                 bridge
-                    .prompt(sessionId, body.text, attachments)
+                    .prompt(sessionId, agentText, attachments)
                     .catch((err) => {
                     plog.error("error", { sessionId, error: err });
                 })
@@ -1019,8 +1098,8 @@ export function createRequestHandler(deps) {
                     sessions.syncBusy(sessionId);
                 });
                 const acceptedBody = { status: "accepted" };
-                saveClientOpResult(store, opId, sessionId, 202, acceptedBody);
-                json(res, 202, acceptedBody);
+                saveClientOpResult(store, opId, sessionId, HTTP_STATUS.ACCEPTED, acceptedBody);
+                json(res, HTTP_STATUS.ACCEPTED, acceptedBody);
                 return;
             }
             // --- POST /api/v1/sessions/:id/bash ---
@@ -1029,15 +1108,17 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(bashMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 if (!sessions) {
-                    json(res, 503, { error: "Session manager not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Session manager not available",
+                    });
                     return;
                 }
                 if (sessions.runningBashProcs.has(sessionId)) {
-                    json(res, 409, {
+                    json(res, HTTP_STATUS.CONFLICT, {
                         error: "A bash command is already running in this session",
                     });
                     return;
@@ -1047,11 +1128,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.command) {
-                    json(res, 400, { error: "Missing required field: command" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: command",
+                    });
                     return;
                 }
                 const cwd = sessions.getSessionCwd(sessionId);
@@ -1128,7 +1211,7 @@ export function createRequestHandler(deps) {
                     };
                     sseManager.broadcast(bashErrEvent);
                 });
-                json(res, 202, { status: "accepted" });
+                json(res, HTTP_STATUS.ACCEPTED, { status: "accepted" });
                 return;
             }
             // --- POST /api/v1/sessions/:id/bash/cancel ---
@@ -1137,27 +1220,32 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(bashCancelMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 interruptBashProc(sessions?.runningBashProcs.get(sessionId));
-                json(res, 200, { ok: true });
+                json(res, HTTP_STATUS.OK, { ok: true });
                 return;
             }
             // --- PUT /api/v1/sessions/:id/{model,mode,reasoning-effort} ---
-            const configPutMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/(model|mode|reasoning-effort)\/?$/);
+            // --- PUT /api/v1/sessions/:id/config/:configId ---
+            const legacyConfigPutMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/(model|mode|reasoning-effort)\/?$/);
+            const genericConfigPutMatch = url.match(/^\/api\/v1\/sessions\/([^/]+)\/config\/([^/]+)\/?$/);
+            const configPutMatch = legacyConfigPutMatch ?? genericConfigPutMatch;
             if (configPutMatch && req.method === "PUT") {
                 const sessionId = decodeURIComponent(configPutMatch[1]);
-                const configPath = configPutMatch[2];
-                const configId = configPath === "reasoning-effort" ? "reasoning_effort" : configPath;
+                const configPath = decodeURIComponent(configPutMatch[2]);
+                const configId = configPath.replace(/-/g, "_");
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const bridge = getBridge?.();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 let body;
@@ -1165,17 +1253,21 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
-                if (!body.value) {
-                    json(res, 400, { error: "Missing required field: value" });
+                if (body.value === undefined) {
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: value",
+                    });
                     return;
                 }
                 try {
                     const configOptions = await bridge.setConfigOption(sessionId, configId, body.value);
                     for (const opt of configOptions) {
-                        store.updateSessionConfig(sessionId, opt.id, opt.currentValue);
+                        if (typeof opt.currentValue === "string") {
+                            store.updateSessionConfig(sessionId, opt.id, opt.currentValue);
+                        }
                     }
                     sseManager.broadcast({
                         type: "config_option_update",
@@ -1188,10 +1280,10 @@ export function createRequestHandler(deps) {
                         configId,
                         value: body.value,
                     });
-                    json(res, 200, { configOptions });
+                    json(res, HTTP_STATUS.OK, { configOptions });
                 }
                 catch (err) {
-                    json(res, 500, {
+                    json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
                         error: `Failed to set ${configId}: ${err instanceof Error ? err.message : String(err)}`,
                     });
                 }
@@ -1203,7 +1295,7 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(titlePutMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 let body;
@@ -1211,11 +1303,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.value) {
-                    json(res, 400, { error: "Missing required field: value" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: value",
+                    });
                     return;
                 }
                 store.updateSessionTitle(sessionId, body.value);
@@ -1230,7 +1324,7 @@ export function createRequestHandler(deps) {
                     title: body.value,
                 };
                 sseManager.broadcast(titleEvent);
-                json(res, 200, { title: body.value });
+                json(res, HTTP_STATUS.OK, { title: body.value });
                 return;
             }
             // --- Session CRUD: /api/v1/sessions/:id ---
@@ -1243,7 +1337,7 @@ export function createRequestHandler(deps) {
                 if (req.method === "GET") {
                     const session = store.getSession(sessionId);
                     if (!session) {
-                        json(res, 404, { error: "Session not found" });
+                        json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                         return;
                     }
                     // Start resume in background (non-blocking) so the client gets metadata fast.
@@ -1272,7 +1366,9 @@ export function createRequestHandler(deps) {
                                         reasoning_effort: cur.reasoning_effort,
                                     };
                                     const override = stored[opt.id];
-                                    return override ? { ...opt, currentValue: override } : opt;
+                                    return override && "options" in opt
+                                        ? { ...opt, currentValue: override }
+                                        : opt;
                                 });
                                 sseManager.broadcast({
                                     type: "config_option_update",
@@ -1339,12 +1435,14 @@ export function createRequestHandler(deps) {
                                     reasoning_effort: freshSession.reasoning_effort,
                                 };
                                 const override = stored[opt.id];
-                                return override ? { ...opt, currentValue: override } : opt;
+                                return override && "options" in opt
+                                    ? { ...opt, currentValue: override }
+                                    : opt;
                             });
                             return opts;
                         })()
                         : [];
-                    json(res, 200, {
+                    json(res, HTTP_STATUS.OK, {
                         id: freshSession.id,
                         cwd: freshSession.cwd,
                         title: freshSession.title,
@@ -1359,7 +1457,7 @@ export function createRequestHandler(deps) {
                 if (req.method === "DELETE") {
                     const session = store.getSession(sessionId);
                     if (!session) {
-                        json(res, 404, { error: "Session not found" });
+                        json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                         return;
                     }
                     if (sessions) {
@@ -1369,7 +1467,7 @@ export function createRequestHandler(deps) {
                         store.deleteSession(sessionId);
                     }
                     sseManager.broadcast({ type: "session_deleted", sessionId });
-                    res.writeHead(204);
+                    res.writeHead(HTTP_STATUS.NO_CONTENT);
                     res.end();
                     return;
                 }
@@ -1378,11 +1476,15 @@ export function createRequestHandler(deps) {
             if (url === "/api/v1/sessions" && req.method === "POST") {
                 const bridge = getBridge?.();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
                     return;
                 }
                 if (!sessions) {
-                    json(res, 503, { error: "Session manager not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Session manager not available",
+                    });
                     return;
                 }
                 let body;
@@ -1390,7 +1492,7 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 const source = body.source ?? "auto";
@@ -1403,6 +1505,7 @@ export function createRequestHandler(deps) {
                         cwd: session?.cwd,
                         title: session?.title,
                         configOptions,
+                        agentCommands: sessions.getAgentCommands(sessionId),
                     };
                     sseManager.broadcast(sessionCreatedEvent);
                     // ACP's session_created event fires before inheritance runs, so
@@ -1414,21 +1517,22 @@ export function createRequestHandler(deps) {
                             configOptions,
                         });
                     }
-                    json(res, 201, {
+                    json(res, HTTP_STATUS.CREATED, {
                         id: sessionId,
                         cwd: session?.cwd ?? body.cwd,
                         title: session?.title ?? null,
                         source: session?.source ?? source,
                         configOptions,
+                        agentCommands: sessions.getAgentCommands(sessionId),
                     });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
                     if (msg.includes("does not exist")) {
-                        json(res, 400, { error: msg });
+                        json(res, HTTP_STATUS.BAD_REQUEST, { error: msg });
                     }
                     else {
-                        json(res, 500, { error: msg });
+                        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: msg });
                     }
                 }
                 return;
@@ -1450,7 +1554,7 @@ export function createRequestHandler(deps) {
                     : undefined;
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 // Flush pending buffers so their content becomes part of the event list.
@@ -1511,7 +1615,7 @@ export function createRequestHandler(deps) {
                     envelope.total = total;
                     envelope.hasMore = hasMore;
                 }
-                json(res, 200, envelope, req);
+                json(res, HTTP_STATUS.OK, envelope, req);
                 return;
             }
             // --- SSE stream endpoints ---
@@ -1525,13 +1629,15 @@ export function createRequestHandler(deps) {
                     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" });
+                        json(res, HTTP_STATUS.UNAUTHORIZED, {
+                            error: "Invalid or expired ticket",
+                        });
                         return;
                     }
                     tokenName = principal.tokenName;
                 }
                 const clientId = sseManager.generateClientId();
-                res.writeHead(200, {
+                res.writeHead(HTTP_STATUS.OK, {
                     "Content-Type": "text/event-stream",
                     "Cache-Control": "no-cache",
                     Connection: "keep-alive",
@@ -1560,18 +1666,20 @@ export function createRequestHandler(deps) {
                     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" });
+                        json(res, HTTP_STATUS.UNAUTHORIZED, {
+                            error: "Invalid or expired ticket",
+                        });
                         return;
                     }
                     tokenName = principal.tokenName;
                 }
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const clientId = sseManager.generateClientId();
-                res.writeHead(200, {
+                res.writeHead(HTTP_STATUS.OK, {
                     "Content-Type": "text/event-stream",
                     "Cache-Control": "no-cache",
                     Connection: "keep-alive",
@@ -1623,12 +1731,14 @@ export function createRequestHandler(deps) {
             if (imgUploadMatch && req.method === "POST") {
                 const sessionId = decodeURIComponent(imgUploadMatch[1]);
                 if (!SAFE_ID.test(sessionId)) {
-                    json(res, 400, { error: "Invalid session ID" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid session ID" });
                     return;
                 }
                 const ctype = req.headers["content-type"] ?? "";
                 if (!ctype.toLowerCase().startsWith("multipart/form-data")) {
-                    json(res, 400, { error: "Expected multipart/form-data" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Expected multipart/form-data",
+                    });
                     return;
                 }
                 await handleAttachmentUpload(req, res, sessionId, deps);
@@ -1651,14 +1761,16 @@ export function createRequestHandler(deps) {
                     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.writeHead(HTTP_STATUS.UNAUTHORIZED, {
+                            "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.writeHead(HTTP_STATUS.FORBIDDEN);
                     res.end("Forbidden");
                     return;
                 }
@@ -1679,11 +1791,11 @@ export function createRequestHandler(deps) {
                         const disposition = isInlineMime(mime) ? "inline" : "attachment";
                         headers["Content-Disposition"] = buildContentDisposition(disposition, row.name);
                     }
-                    res.writeHead(200, headers);
+                    res.writeHead(HTTP_STATUS.OK, headers);
                     res.end(fileData);
                 }
                 catch {
-                    res.writeHead(404);
+                    res.writeHead(HTTP_STATUS.NOT_FOUND);
                     res.end("Not found");
                 }
                 return;
@@ -1702,7 +1814,7 @@ export function createRequestHandler(deps) {
                     raw = await readBody(req);
                 }
                 catch {
-                    json(res, 400, { error: "Failed to read body" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Failed to read body" });
                     return;
                 }
                 let parsed;
@@ -1710,12 +1822,12 @@ export function createRequestHandler(deps) {
                     parsed = JSON.parse(raw);
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 const validation = MessageIngressSchema.safeParse(parsed);
                 if (!validation.success) {
-                    json(res, 400, {
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
                         error: "Invalid body",
                         issues: validation.error.issues,
                     });
@@ -1727,7 +1839,7 @@ export function createRequestHandler(deps) {
                     const targetSid = input.to.slice("session:".length);
                     const session = store.getSession(targetSid);
                     if (!session) {
-                        json(res, 400, { error: "session_not_found" });
+                        json(res, HTTP_STATUS.BAD_REQUEST, { error: "session_not_found" });
                         return;
                     }
                     sessions?.flushBuffers(targetSid);
@@ -1763,8 +1875,8 @@ export function createRequestHandler(deps) {
                         sess_id: targetSid.slice(0, 8),
                     });
                     const boundBody = { id, delivered: "session" };
-                    saveClientOpResult(store, opId, "__ingress__", 200, boundBody);
-                    json(res, 200, boundBody);
+                    saveClientOpResult(store, opId, "__ingress__", HTTP_STATUS.OK, boundBody);
+                    json(res, HTTP_STATUS.OK, boundBody);
                     return;
                 }
                 // Unbound: to=user → rows in `messages` table
@@ -1810,13 +1922,13 @@ export function createRequestHandler(deps) {
                     from_ref: input.from_ref,
                 });
                 const unboundBody = { id, delivered: "pending" };
-                saveClientOpResult(store, opId, "__ingress__", 200, unboundBody);
-                json(res, 200, unboundBody);
+                saveClientOpResult(store, opId, "__ingress__", HTTP_STATUS.OK, unboundBody);
+                json(res, HTTP_STATUS.OK, unboundBody);
                 return;
             }
             // GET /api/v1/messages — list unprocessed
             if (url === "/api/v1/messages" && req.method === "GET") {
-                json(res, 200, { messages: store.listUnprocessed() });
+                json(res, HTTP_STATUS.OK, { messages: store.listUnprocessed() });
                 return;
             }
             // /api/v1/messages/:id... — GET single, POST :id/consume, POST :id/ack, DELETE :id
@@ -1832,7 +1944,7 @@ export function createRequestHandler(deps) {
                     }
                     catch (err) {
                         if (/message not found/.test(errorMessage(err))) {
-                            json(res, 404, { error: "Message not found" });
+                            json(res, HTTP_STATUS.NOT_FOUND, { error: "Message not found" });
                             return;
                         }
                         throw err;
@@ -1850,7 +1962,7 @@ export function createRequestHandler(deps) {
                         sess_id: out.sessionId.slice(0, 8),
                         already_consumed: out.alreadyConsumed,
                     });
-                    json(res, 200, {
+                    json(res, HTTP_STATUS.OK, {
                         sessionId: out.sessionId,
                         alreadyConsumed: out.alreadyConsumed,
                     });
@@ -1864,28 +1976,28 @@ export function createRequestHandler(deps) {
                     const id = decodeURIComponent((ackPost ?? idOnly)[1]);
                     const changes = store.deleteMessage(id);
                     if (changes === 0) {
-                        json(res, 404, { error: "Message not found" });
+                        json(res, HTTP_STATUS.NOT_FOUND, { 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 });
+                    json(res, HTTP_STATUS.OK, { 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" });
+                        json(res, HTTP_STATUS.NOT_FOUND, { error: "Message not found" });
                         return;
                     }
-                    json(res, 200, row);
+                    json(res, HTTP_STATUS.OK, row);
                     return;
                 }
             }
-            json(res, 404, { error: "Not found" });
+            json(res, HTTP_STATUS.NOT_FOUND, { error: "Not found" });
             return;
         }
         // --- Beta API routes ---
@@ -1894,12 +2006,16 @@ export function createRequestHandler(deps) {
             // POST /api/beta/prompt — quick one-shot prompt (create temp session + send)
             if (url === "/api/beta/prompt" && req.method === "POST") {
                 if (!sessions || !getBridge) {
-                    json(res, 503, { error: "Agent not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not available",
+                    });
                     return;
                 }
                 const bridge = getBridge();
                 if (!bridge) {
-                    json(res, 503, { error: "Agent not available" });
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not available",
+                    });
                     return;
                 }
                 let body;
@@ -1907,18 +2023,20 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 const text = body.text;
                 if (!text || typeof text !== "string") {
-                    json(res, 400, { error: "Missing required field: text" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: text",
+                    });
                     return;
                 }
                 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 });
+                json(res, HTTP_STATUS.ACCEPTED, { sessionId, streamUrl });
                 // Fire-and-forget: send the prompt asynchronously, tracking busy state
                 sessions.activePrompts.add(sessionId);
                 sessions.syncBusy(sessionId);
@@ -1954,7 +2072,7 @@ export function createRequestHandler(deps) {
                 const clientKnown = sseManager.clients.has(clientId) ||
                     deps.clientRegistry?.get(clientId) !== undefined;
                 if (!clientKnown) {
-                    json(res, 404, { error: "Client not found" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Client not found" });
                     return;
                 }
                 let body;
@@ -1962,11 +2080,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (typeof body.visible !== "boolean") {
-                    json(res, 400, { error: "Missing or invalid 'visible' field" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing or invalid 'visible' field",
+                    });
                     return;
                 }
                 // sessionId patch semantics: absent = preserve, null = clear,
@@ -2013,23 +2133,25 @@ export function createRequestHandler(deps) {
                         }
                     }
                 }
-                json(res, 200, { ok: true });
+                json(res, HTTP_STATUS.OK, { ok: true });
                 return;
             }
             // --- Push notification routes ---
             // GET /api/beta/push/vapid-key
             if (url === "/api/beta/push/vapid-key" && req.method === "GET") {
                 if (!deps.pushService) {
-                    json(res, 404, { error: "Push not configured" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Push not configured" });
                     return;
                 }
-                json(res, 200, { publicKey: deps.pushService.getPublicKey() });
+                json(res, HTTP_STATUS.OK, {
+                    publicKey: deps.pushService.getPublicKey(),
+                });
                 return;
             }
             // POST /api/beta/push/subscribe
             if (url === "/api/beta/push/subscribe" && req.method === "POST") {
                 if (!deps.pushService) {
-                    json(res, 404, { error: "Push not configured" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Push not configured" });
                     return;
                 }
                 const chunks = [];
@@ -2040,11 +2162,13 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(Buffer.concat(chunks).toString());
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.endpoint || !body.keys?.auth || !body.keys.p256dh) {
-                    json(res, 400, { error: "Missing endpoint or keys (auth, p256dh)" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing endpoint or keys (auth, p256dh)",
+                    });
                     return;
                 }
                 store.saveSubscription(body.endpoint, body.keys.auth, body.keys.p256dh);
@@ -2052,13 +2176,13 @@ export function createRequestHandler(deps) {
                 if (body.clientId && deps.pushService) {
                     deps.pushService.registerClient(body.clientId, body.endpoint);
                 }
-                json(res, 201, { ok: true });
+                json(res, HTTP_STATUS.CREATED, { ok: true });
                 return;
             }
             // POST /api/beta/push/register-client — associate clientId with push endpoint
             if (url === "/api/beta/push/register-client" && req.method === "POST") {
                 if (!deps.pushService) {
-                    json(res, 404, { error: "Push not configured" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Push not configured" });
                     return;
                 }
                 const chunks = [];
@@ -2069,21 +2193,23 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(Buffer.concat(chunks).toString());
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (!body.clientId || !body.endpoint) {
-                    json(res, 400, { error: "Missing clientId or endpoint" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing clientId or endpoint",
+                    });
                     return;
                 }
                 deps.pushService.registerClient(body.clientId, body.endpoint);
-                json(res, 200, { ok: true });
+                json(res, HTTP_STATUS.OK, { ok: true });
                 return;
             }
             // POST /api/beta/push/unsubscribe
             if (url === "/api/beta/push/unsubscribe" && req.method === "POST") {
                 if (!deps.pushService) {
-                    json(res, 404, { error: "Push not configured" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Push not configured" });
                     return;
                 }
                 const chunks = [];
@@ -2094,16 +2220,16 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(Buffer.concat(chunks).toString());
                 }
                 catch {
-                    json(res, 400, { error: "Invalid JSON" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
                     return;
                 }
                 if (body.endpoint) {
                     store.removeSubscription(body.endpoint);
                 }
-                json(res, 200, { ok: true });
+                json(res, HTTP_STATUS.OK, { ok: true });
                 return;
             }
-            json(res, 404, { error: "Not found" });
+            json(res, HTTP_STATUS.NOT_FOUND, { error: "Not found" });
             return;
         }
         // --- Static files ---
@@ -2113,7 +2239,7 @@ export function createRequestHandler(deps) {
             staticPath = "/" + htmlEntry.file;
         const filePath = join(deps.publicDir, staticPath);
         if (!filePath.startsWith(deps.publicDir)) {
-            res.writeHead(403);
+            res.writeHead(HTTP_STATUS.FORBIDDEN);
             res.end("Forbidden");
             return;
         }
@@ -2136,11 +2262,11 @@ export function createRequestHandler(deps) {
             // CSP applies to HTML entrypoints (where script/style execute).
             if (htmlEntry)
                 headers["Content-Security-Policy"] = CSP_POLICY;
-            res.writeHead(200, headers);
+            res.writeHead(HTTP_STATUS.OK, headers);
             res.end(data);
         }
         catch {
-            res.writeHead(404);
+            res.writeHead(HTTP_STATUS.NOT_FOUND);
             res.end("Not found");
         }
     };