@lelouchhe/webagent 0.6.0 → 0.8.0

package/lib/routes.js

@@ -4,12 +4,13 @@ import { join, extname, basename } from "node:path";
 import { gzipSync } from "node:zlib";
 import busboy from "busboy";
 import { errorMessage, MessageIngressSchema } from "./types.js";
-import { interruptBashProc } from "./session-manager.js";
+import { interruptBashProc, InvalidSessionDirectoryError, } from "./session-manager.js";
 import { randomUUID } from "node:crypto";
 import { createWriteStream } from "node:fs";
 import { handleShareRoutes } from "./share/routes.js";
 import { authenticate, isWhitelistedPath } from "./auth-middleware.js";
 import { enrichStoredEventsForDisplay } from "./attachment-labels.js";
+import { agentCommandToken, resolveAgentCommand } from "./agent-commands.js";
 import { log } from "./log.js";
 const rlog = log.scope("routes");
 const plog = rlog.scope("prompt");
@@ -18,8 +19,15 @@ 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_-]+$/;
+function broadcastInboxCount(store, sseManager) {
+    sseManager.broadcastGlobal({
+        type: "inbox_count_changed",
+        pendingCount: store.countUnprocessed(),
+    });
+}
 const MIME = {
     ".html": "text/html; charset=utf-8",
     ".js": "application/javascript; charset=utf-8",
@@ -172,7 +180,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 +241,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 +254,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 +305,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 +378,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 +392,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 +413,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 +445,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 +470,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 +487,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 +502,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 +516,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 +539,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 +553,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 +572,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 +587,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 +600,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 +636,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 +662,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 +675,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 +694,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 +729,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,38 +739,88 @@ export function createRequestHandler(deps) {
                 const sessionId = decodeURIComponent(cancelMatch[1]);
                 const session = store.getSession(sessionId);
                 if (!session) {
-                    json(res, 404, { error: "Session not found" });
-                    return;
-                }
-                const bridge = getBridge?.();
-                if (!bridge) {
-                    json(res, 503, { error: "Agent not ready yet" });
+                    json(res, HTTP_STATUS.NOT_FOUND, { error: "Session not found" });
                     return;
                 }
                 const { opId, replayed } = tryReplayClientOp(req, res, store, sessionId);
                 if (replayed)
                     return;
+                const hadAgentPrompt = sessions?.activePrompts.has(sessionId) ?? false;
+                const hadPendingPrompt = sessions?.cancelPendingPromptSubmission(sessionId) ?? false;
+                const hadBash = sessions?.runningBashProcs.has(sessionId) ?? false;
+                if (!hadAgentPrompt && !hadPendingPrompt && !hadBash) {
+                    const idleBody = { ok: true, status: "idle" };
+                    saveClientOpResult(store, opId, sessionId, HTTP_STATUS.OK, idleBody);
+                    json(res, HTTP_STATUS.OK, idleBody);
+                    return;
+                }
+                const cancelledPromptId = hadAgentPrompt
+                    ? (sessions?.state.getState(sessionId).runtime.busy?.promptId ?? null)
+                    : null;
                 // Kill running bash process if any
                 const proc = sessions?.runningBashProcs.get(sessionId);
                 if (proc) {
-                    interruptBashProc(proc);
-                    sessions.runningBashProcs.delete(sessionId);
+                    const force = sessions.interruptedBashProcs.has(proc);
+                    interruptBashProc(proc, force);
+                    sessions.interruptedBashProcs.add(proc);
+                }
+                const bridge = hadAgentPrompt ? getBridge?.() : null;
+                if (hadAgentPrompt && !bridge) {
+                    json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                        error: "Agent not ready yet",
+                    });
+                    return;
                 }
-                // Cancel agent prompt
-                if (sessions?.activePrompts.has(sessionId)) {
+                // ACP cancel is a notification, not an acknowledgement. Keep the
+                // prompt active until its prompt response supplies the terminal stop
+                // reason, and allow repeated requests to resend the notification.
+                if (hadAgentPrompt && sessions && bridge) {
+                    const previousCancelStatus = sessions.state.getState(sessionId).runtime.busy?.cancelStatus ??
+                        null;
+                    rlog.info("cancel requested", {
+                        sessionId: sessionId.slice(0, 8),
+                        retry: previousCancelStatus !== null,
+                        previousStatus: previousCancelStatus,
+                    });
                     await bridge.cancel(sessionId);
-                    sessions.activePrompts.delete(sessionId);
+                    const busy = sessions.state.getState(sessionId).runtime.busy;
+                    const stillCancellingSamePrompt = sessions.activePrompts.has(sessionId) &&
+                        busy?.kind === "agent" &&
+                        busy.promptId === cancelledPromptId;
+                    if (stillCancellingSamePrompt) {
+                        sessions.state.markCancelRequested(sessionId);
+                    }
                 }
-                // Arm backend safety net: if prompt_done doesn't arrive within the
-                // configured timeout, force-clear busy so the UI unstalls. Replaces
-                // the old frontend-side cancel timer.
+                // If prompt_done does not arrive, expose the lack of acknowledgement
+                // instead of pretending the prompt stopped.
                 const cancelTimeout = deps.limits.cancel_timeout ?? 0;
-                if (sessions && cancelTimeout > 0)
+                const busyAfterCancel = sessions?.state.getState(sessionId).runtime.busy;
+                const cancelPending = hadAgentPrompt &&
+                    sessions?.activePrompts.has(sessionId) === true &&
+                    busyAfterCancel?.kind === "agent" &&
+                    busyAfterCancel.promptId === cancelledPromptId;
+                if (cancelPending && cancelTimeout > 0)
                     sessions.state.armCancelSafety(sessionId, cancelTimeout);
                 sessions?.syncBusy(sessionId);
-                const okBody = { ok: true };
-                saveClientOpResult(store, opId, sessionId, 200, okBody);
-                json(res, 200, okBody);
+                const workPending = cancelPending || hadBash;
+                const replacementPromptActive = hadAgentPrompt &&
+                    ((sessions?.activePrompts.has(sessionId) === true &&
+                        busyAfterCancel?.kind === "agent" &&
+                        busyAfterCancel.promptId !== cancelledPromptId) ||
+                        sessions?.pendingPromptSubmissions.has(sessionId) === true);
+                const status = workPending || replacementPromptActive
+                    ? HTTP_STATUS.ACCEPTED
+                    : HTTP_STATUS.OK;
+                const okBody = {
+                    ok: true,
+                    status: workPending
+                        ? "cancelling"
+                        : replacementPromptActive
+                            ? "superseded"
+                            : "cancelled",
+                };
+                saveClientOpResult(store, opId, sessionId, status, okBody);
+                json(res, status, okBody);
                 return;
             }
             // --- GET /api/v1/sessions/:id/status ---
@@ -749,12 +829,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 +851,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 +894,7 @@ export function createRequestHandler(deps) {
                         lastEventSeq,
                     },
                     runtime: runtimeState.runtime,
+                    agentCommands: sessions.getAgentCommands(sessionId),
                 }, req);
                 return;
             }
@@ -809,65 +907,101 @@ 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);
                 if (replayed)
                     return;
+                const promptSubmissionId = sessions.reservePromptSubmission(sessionId);
+                if (promptSubmissionId === null) {
+                    const busyKind = sessions.getBusyKind(sessionId);
+                    logPromptRejectBeforeSave({
+                        sessionId,
+                        status: HTTP_STATUS.CONFLICT,
+                        reason: "session_busy",
+                        opId,
+                        busyKind: busyKind ?? undefined,
+                    });
+                    json(res, HTTP_STATUS.CONFLICT, {
+                        error: "Session is busy",
+                        busyKind,
+                    });
+                    return;
+                }
+                const requestState = { aborted: false };
+                const isRequestAborted = () => requestState.aborted;
+                const abortPromptSubmission = () => {
+                    requestState.aborted = true;
+                    sessions.releasePromptSubmission(sessionId, promptSubmissionId);
+                };
+                res.once("finish", () => {
+                    sessions.releasePromptSubmission(sessionId, promptSubmissionId);
+                });
+                req.once("aborted", abortPromptSubmission);
+                res.once("close", () => {
+                    if (!res.writableEnded)
+                        abortPromptSubmission();
+                });
                 // Ensure session is live in ACP before prompting (awaits in-flight resume)
                 try {
                     await sessions.ensureResumed(bridge, sessionId);
                 }
                 catch (err) {
+                    if (isRequestAborted())
+                        return;
                     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;
                 }
-                // Check if session is busy
-                const busyKind = sessions.getBusyKind(sessionId);
-                if (busyKind) {
+                if (isRequestAborted() ||
+                    sessions.isPromptSubmissionCancelled(promptSubmissionId)) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 409,
-                        reason: "session_busy",
+                        status: HTTP_STATUS.CONFLICT,
+                        reason: "prompt_cancelled_before_start",
                         opId,
-                        busyKind,
                     });
-                    json(res, 409, { error: "Session is busy", busyKind });
+                    json(res, HTTP_STATUS.CONFLICT, {
+                        error: "Prompt was cancelled before start",
+                    });
                     return;
                 }
                 let body;
@@ -875,19 +1009,28 @@ export function createRequestHandler(deps) {
                     body = JSON.parse(await readBody(req));
                 }
                 catch {
+                    if (isRequestAborted())
+                        return;
                     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 (isRequestAborted() ||
+                    sessions.isPromptSubmissionCancelled(promptSubmissionId)) {
+                    json(res, HTTP_STATUS.CONFLICT, {
+                        error: "Prompt was cancelled before start",
+                    });
                     return;
                 }
                 if (!body.text) {
                     logPromptRejectBeforeSave({
                         sessionId,
-                        status: 400,
+                        status: HTTP_STATUS.BAD_REQUEST,
                         reason: "missing_text",
                         opId,
                         textLength: 0,
@@ -895,7 +1038,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 +1051,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 +1071,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 +1089,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
@@ -978,8 +1149,10 @@ export function createRequestHandler(deps) {
                         },
                     ];
                 });
+                const eventClientOpId = opId ?? randomUUID();
                 store.saveEvent(sessionId, "user_message", {
                     text: body.text,
+                    clientOpId: eventClientOpId,
                     ...(storedAttachments?.length
                         ? { attachments: storedAttachments }
                         : {}),
@@ -990,6 +1163,7 @@ export function createRequestHandler(deps) {
                     type: "user_message",
                     sessionId,
                     text: body.text,
+                    clientOpId: eventClientOpId,
                     attachments: storedAttachments,
                 };
                 sseManager.broadcast(userMsgEvent);
@@ -1007,20 +1181,27 @@ export function createRequestHandler(deps) {
                     });
                 }
                 // Fire prompt asynchronously (don't await — response is 202)
+                sessions.releasePromptSubmission(sessionId, promptSubmissionId, false);
                 sessions.activePrompts.add(sessionId);
                 sessions.syncBusy(sessionId);
+                const promptId = sessions.state.getState(sessionId).runtime.busy?.promptId ??
+                    undefined;
                 bridge
-                    .prompt(sessionId, body.text, attachments)
+                    .prompt(sessionId, agentText, attachments, promptId)
                     .catch((err) => {
                     plog.error("error", { sessionId, error: err });
                 })
                     .finally(() => {
+                    // A turn that outlived its own supersession must not clear the
+                    // busy state of the turn that replaced it.
+                    if (!sessions.isCurrentPrompt(sessionId, promptId))
+                        return;
                     sessions.activePrompts.delete(sessionId);
                     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 +1210,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 +1230,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 +1313,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,11 +1322,11 @@ 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} ---
@@ -1155,12 +1340,14 @@ export function createRequestHandler(deps) {
                 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;
@@ -1168,11 +1355,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 === undefined) {
-                    json(res, 400, { error: "Missing required field: value" });
+                    json(res, HTTP_STATUS.BAD_REQUEST, {
+                        error: "Missing required field: value",
+                    });
                     return;
                 }
                 try {
@@ -1193,10 +1382,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)}`,
                     });
                 }
@@ -1208,7 +1397,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;
@@ -1216,11 +1405,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);
@@ -1235,7 +1426,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 ---
@@ -1248,7 +1439,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.
@@ -1353,7 +1544,7 @@ export function createRequestHandler(deps) {
                             return opts;
                         })()
                         : [];
-                    json(res, 200, {
+                    json(res, HTTP_STATUS.OK, {
                         id: freshSession.id,
                         cwd: freshSession.cwd,
                         title: freshSession.title,
@@ -1368,7 +1559,13 @@ 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 && sessions.getBusyKind(sessionId) !== null) {
+                        json(res, HTTP_STATUS.CONFLICT, {
+                            error: "Cancel active work before deleting the session",
+                        });
                         return;
                     }
                     if (sessions) {
@@ -1378,20 +1575,25 @@ 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;
                 }
             }
             // POST /api/v1/sessions (create new session)
             if (url === "/api/v1/sessions" && req.method === "POST") {
+                const clientOpId = getClientOpId(req);
                 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;
@@ -1399,7 +1601,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";
@@ -1412,6 +1614,8 @@ export function createRequestHandler(deps) {
                         cwd: session?.cwd,
                         title: session?.title,
                         configOptions,
+                        agentCommands: sessions.getAgentCommands(sessionId),
+                        clientOpId: clientOpId ?? undefined,
                     };
                     sseManager.broadcast(sessionCreatedEvent);
                     // ACP's session_created event fires before inheritance runs, so
@@ -1423,21 +1627,23 @@ 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),
+                        clientOpId: clientOpId ?? undefined,
                     });
                 }
                 catch (err) {
                     const msg = err instanceof Error ? err.message : String(err);
-                    if (msg.includes("does not exist")) {
-                        json(res, 400, { error: msg });
+                    if (err instanceof InvalidSessionDirectoryError) {
+                        json(res, HTTP_STATUS.BAD_REQUEST, { error: msg });
                     }
                     else {
-                        json(res, 500, { error: msg });
+                        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, { error: msg });
                     }
                 }
                 return;
@@ -1459,7 +1665,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.
@@ -1468,14 +1674,15 @@ export function createRequestHandler(deps) {
                 let streamingThinking = false;
                 let streamingAssistant = false;
                 if (sessions) {
-                    if (sessions.thinkingBuffers.has(sessionId)) {
-                        streamingThinking = true;
-                        sessions.flushThinkingBuffer(sessionId);
-                    }
-                    if (sessions.assistantBuffers.has(sessionId)) {
-                        streamingAssistant = true;
-                        sessions.flushAssistantBuffer(sessionId);
-                    }
+                    const runtimeStreaming = sessions.state.peekStreaming(sessionId);
+                    streamingThinking =
+                        runtimeStreaming.thinking ||
+                            Boolean(sessions.thinkingBuffers.get(sessionId));
+                    streamingAssistant =
+                        runtimeStreaming.assistant ||
+                            Boolean(sessions.assistantBuffers.get(sessionId));
+                    sessions.flushThinkingBuffer(sessionId);
+                    sessions.flushAssistantBuffer(sessionId);
                 }
                 const events = store.getEvents(sessionId, {
                     excludeThinking,
@@ -1520,7 +1727,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 ---
@@ -1534,13 +1741,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",
@@ -1556,6 +1765,7 @@ export function createRequestHandler(deps) {
                     type: "connected",
                     clientId,
                     debugLevel: deps.debugLevel ?? "off",
+                    pendingCount: store.countUnprocessed(),
                 });
                 sseManager.writeHeartbeat(client);
                 return;
@@ -1569,18 +1779,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",
@@ -1597,6 +1809,7 @@ export function createRequestHandler(deps) {
                     type: "connected",
                     clientId,
                     debugLevel: deps.debugLevel ?? "off",
+                    pendingCount: store.countUnprocessed(),
                 });
                 sseManager.writeHeartbeat(client);
                 // Replay events from Last-Event-ID if provided
@@ -1632,12 +1845,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);
@@ -1660,14 +1875,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;
                 }
@@ -1688,11 +1905,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;
@@ -1711,7 +1928,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;
@@ -1719,12 +1936,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,
                     });
@@ -1736,7 +1953,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);
@@ -1772,8 +1989,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
@@ -1803,6 +2020,7 @@ export function createRequestHandler(deps) {
                     created_at: Date.now(),
                 });
                 sseManager.broadcast({ type: "message_created", messageId: id });
+                broadcastInboxCount(store, sseManager);
                 if (deps.pushService) {
                     void deps.pushService.sendForMessage({
                         id,
@@ -1819,13 +2037,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
@@ -1834,23 +2052,58 @@ export function createRequestHandler(deps) {
                 const consumeMatch = tail.match(/^([^/?]+)\/consume\/?$/);
                 if (consumeMatch && req.method === "POST") {
                     const id = decodeURIComponent(consumeMatch[1]);
-                    const newSid = randomUUID();
+                    let inheritFromSessionId;
+                    try {
+                        const rawBody = await readBody(req);
+                        if (rawBody) {
+                            const body = JSON.parse(rawBody);
+                            if (body.inheritFromSessionId !== undefined &&
+                                typeof body.inheritFromSessionId !== "string") {
+                                json(res, HTTP_STATUS.BAD_REQUEST, {
+                                    error: "inheritFromSessionId must be a string",
+                                });
+                                return;
+                            }
+                            inheritFromSessionId = body.inheritFromSessionId;
+                        }
+                    }
+                    catch {
+                        json(res, HTTP_STATUS.BAD_REQUEST, { error: "Invalid JSON" });
+                        return;
+                    }
+                    const bridge = getBridge?.();
+                    if (!sessions || !bridge) {
+                        json(res, HTTP_STATUS.SERVICE_UNAVAILABLE, {
+                            error: "Agent not available",
+                        });
+                        return;
+                    }
                     let out;
                     try {
-                        out = store.consumeMessageTx(id, { sessionId: newSid });
+                        out = await sessions.consumeMessage(bridge, id, inheritFromSessionId);
                     }
                     catch (err) {
-                        if (/message not found/.test(errorMessage(err))) {
-                            json(res, 404, { error: "Message not found" });
+                        if (err instanceof InvalidSessionDirectoryError) {
+                            json(res, HTTP_STATUS.BAD_REQUEST, {
+                                error: err.message,
+                            });
                             return;
                         }
-                        throw err;
+                        json(res, HTTP_STATUS.INTERNAL_SERVER_ERROR, {
+                            error: errorMessage(err),
+                        });
+                        return;
+                    }
+                    if (!out) {
+                        json(res, HTTP_STATUS.NOT_FOUND, { error: "Message not found" });
+                        return;
                     }
                     sseManager.broadcast({
                         type: "message_consumed",
                         messageId: id,
                         sessionId: out.sessionId,
                     });
+                    broadcastInboxCount(store, sseManager);
                     if (!out.alreadyConsumed && deps.pushService) {
                         void deps.pushService.sendClose(id);
                     }
@@ -1859,7 +2112,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,
                     });
@@ -1873,28 +2126,29 @@ 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 });
+                    broadcastInboxCount(store, sseManager);
                     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 ---
@@ -1903,12 +2157,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;
@@ -1916,18 +2174,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);
@@ -1942,10 +2202,14 @@ export function createRequestHandler(deps) {
                         sseManager.broadcast(titleEvent);
                     });
                 }
+                const betaPromptId = sessions.state.getState(sessionId).runtime.busy?.promptId ??
+                    undefined;
                 bridge
-                    .prompt(sessionId, text)
+                    .prompt(sessionId, text, undefined, betaPromptId)
                     .catch(() => { })
                     .finally(() => {
+                    if (!sessions.isCurrentPrompt(sessionId, betaPromptId))
+                        return;
                     sessions.activePrompts.delete(sessionId);
                     sessions.syncBusy(sessionId);
                 });
@@ -1963,7 +2227,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;
@@ -1971,11 +2235,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,
@@ -2022,23 +2288,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 = [];
@@ -2049,11 +2317,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);
@@ -2061,13 +2331,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 = [];
@@ -2078,21 +2348,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 = [];
@@ -2103,26 +2375,26 @@ 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 ---
-        let staticPath = url;
+        let staticPath = url.split("?")[0] ?? url;
         const htmlEntry = HTML_ENTRYPOINTS.find((e) => e.urlPath === staticPath);
         if (htmlEntry)
             staticPath = "/" + htmlEntry.file;
         const filePath = join(deps.publicDir, staticPath);
         if (!filePath.startsWith(deps.publicDir)) {
-            res.writeHead(403);
+            res.writeHead(HTTP_STATUS.FORBIDDEN);
             res.end("Forbidden");
             return;
         }
@@ -2145,11 +2417,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");
         }
     };