@tea-agent/loop-agent 0.22.0 → 0.24.0

package/dist/worker/console/chat/routes.js

@@ -0,0 +1,1646 @@
+/**
+ * Operator Chat — HTTP route handlers (plan W7 / W8 backend).
+ *
+ * Routes (all under /api/operator/v1/chat):
+ *   POST /sessions              — create a new Chat session
+ *   GET  /sessions/:id          — fetch session metadata + messages
+ *   POST /sessions/:id/prompt   — SSE stream: send a prompt, stream events
+ *   GET  /sessions/:id/events   — SSE stream: (re)connect to live events
+ *   GET  /capabilities          — Chat tool surface + instruction skills
+ *   DELETE /sessions/:id        — dispose a Chat session
+ *
+ * Mutation routes go through the Console mutation gate (boot token + Origin).
+ * Read routes (GET capabilities / sessions) are open to loopback.
+ */
+import { createHash } from "node:crypto";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, } from "./tools.js";
+import { OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS, OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS, OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS, composeInstructionSkillsPrompt, loadOperatorChatInstructionSkills, } from "./instruction-skills.js";
+import { buildModelCallableToolSchemas } from "./tool-adapter.js";
+import { projectChatToolEventPayload, projectCompactSnapshot, } from "./chat-event-store.js";
+import { THINKING_LEVELS } from "./pi-runtime.js";
+import { ComposerDraftStore } from "./composer-draft-store.js";
+import { walkRepoFiles } from "./repo-walk.js";
+import { isSensitivePath, scrubSecrets } from "./explore-tools.js";
+import { listRepoDirectory, readRepoPreview, RepoBrowserError, } from "./repo-browser.js";
+import { projectRuntimeContext } from "./runtime-context.js";
+import { patchModelsConfig, readModelsConfig, readPackageInventory, readSkillPreferences, writeSkillPreferences, } from "./pi-console-config.js";
+import { ChatInterviewAdapter, projectChatInterviewState } from "./interview-adapter.js";
+import { evaluateMutationGate, isMutationMethod, } from "../security.js";
+import { dispatchOperatorAction } from "../operator-actions.js";
+import { makeHumanGateCard } from "./human-gate-card.js";
+import { ContractApplyReceiptStore } from "./contract-apply-receipt-store.js";
+import { projectTaskContext } from "./context-panel.js";
+import { contractApplyPayloadHash, issueHumanGateToken, verifyHumanGateToken } from "../human-gate-token.js";
+import { sendJson } from "../routes.js";
+import { openSseResponse, parseLastEventId, writeSseEvent, } from "../operation-sse.js";
+function writeChatSse(res, event) {
+    // Persisted Chat events carry their own eventId (<sessionId>:<seq>); write
+    // it as the SSE `id:` frame so the browser tracks Last-Event-ID for reconnect.
+    if ("seq" in event && event.eventId) {
+        res.write(`id: ${event.eventId}\n`);
+    }
+    res.write(`event: ${event.kind}\n`);
+    res.write(`data: ${JSON.stringify(event)}\n\n`);
+}
+/** Map a runtime ChatTurnEvent to the persisted event-store partial.
+ *
+ * Returns undefined for heartbeat (not persisted — keep-alive only). */
+function turnEventToStorePartial(event) {
+    switch (event.type) {
+        case "agent_start":
+            return { kind: "agent_start", data: {} };
+        case "message_update":
+            return { kind: "message_update", data: { text: String(event.text ?? "") } };
+        case "message_end":
+            return { kind: "message_end", data: { text: String(event.text ?? "") } };
+        case "usage":
+            return { kind: "usage", data: (event.usage ?? {}) };
+        case "tool_call":
+            return {
+                kind: "tool_call",
+                data: projectChatToolEventPayload({
+                    kind: "tool_call",
+                    toolCallId: String(event.toolCallId ?? ""),
+                    toolName: String(event.toolName ?? ""),
+                    value: event.args,
+                }),
+            };
+        case "tool_result":
+            return {
+                kind: "tool_result",
+                data: projectChatToolEventPayload({
+                    kind: "tool_result",
+                    toolCallId: String(event.toolCallId ?? ""),
+                    toolName: String(event.toolName ?? ""),
+                    value: event.result,
+                    isError: Boolean(event.isError),
+                }),
+            };
+        case "agent_end":
+            return {
+                kind: "agent_end",
+                data: { willRetry: Boolean(event.willRetry) },
+            };
+        case "agent_settled":
+            return { kind: "agent_settled", data: {} };
+        case "error":
+            return { kind: "error", data: { message: String(event.message ?? "") } };
+        default:
+            return undefined;
+    }
+}
+async function readJsonBody(req, maxBytes = 2 * 1024 * 1024) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buf.length;
+        if (total > maxBytes) {
+            throw new Error(`request body exceeds ${maxBytes} bytes`);
+        }
+        chunks.push(buf);
+    }
+    if (chunks.length === 0)
+        return {};
+    const raw = Buffer.concat(chunks).toString("utf8");
+    if (!raw.trim())
+        return {};
+    return JSON.parse(raw);
+}
+const IMAGE_MIME_TYPES = new Set(["image/png", "image/jpeg", "image/gif", "image/webp"]);
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const MAX_TOTAL_IMAGE_BYTES = 20 * 1024 * 1024;
+const MAX_IMAGES = 4;
+export function parseChatImages(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > MAX_IMAGES)
+        throw new Error(`images must be an array with at most ${MAX_IMAGES} items`);
+    let total = 0;
+    return value.map((item, index) => {
+        if (!item || typeof item !== "object")
+            throw new Error(`images[${index}] is invalid`);
+        const record = item;
+        if (record.type !== "image" || typeof record.mimeType !== "string" || !IMAGE_MIME_TYPES.has(record.mimeType))
+            throw new Error(`images[${index}] must be a supported raster image`);
+        if (typeof record.data !== "string" || !record.data || !/^[A-Za-z0-9+/]+={0,2}$/.test(record.data) || record.data.length % 4 !== 0)
+            throw new Error(`images[${index}] data must be valid base64`);
+        const bytes = Buffer.from(record.data, "base64");
+        const textProbe = bytes.subarray(0, Math.min(bytes.length, 64 * 1024)).toString("utf8");
+        if (scrubSecrets(textProbe).redactions.length > 0)
+            throw new Error(`images[${index}] contains secret-shaped content`);
+        if (bytes.length > MAX_IMAGE_BYTES)
+            throw new Error(`images[${index}] exceeds ${MAX_IMAGE_BYTES} bytes`);
+        total += bytes.length;
+        if (total > MAX_TOTAL_IMAGE_BYTES)
+            throw new Error(`images exceed ${MAX_TOTAL_IMAGE_BYTES} total bytes`);
+        return { type: "image", mimeType: record.mimeType, data: bytes.toString("base64") };
+    });
+}
+function gateMutation(req, deps) {
+    const failure = evaluateMutationGate(req, {
+        bootToken: deps.bootToken.value,
+        confirmationToken: deps.bootToken.confirmationToken,
+        consoleOrigin: deps.getConsoleOrigin(),
+        allowNonLoopbackAccess: deps.allowNonLoopbackAccess,
+    });
+    if (failure) {
+        return {
+            ok: false,
+            status: failure.status,
+            code: failure.code,
+            message: failure.message,
+        };
+    }
+    return { ok: true };
+}
+export async function handleChatCapabilities(_req, res, deps) {
+    const toolSchemas = buildModelCallableToolSchemas();
+    const skills = await loadOperatorChatInstructionSkills(deps.skillsDir);
+    sendJson(res, 200, {
+        ok: true,
+        schemaVersion: 1,
+        allowedTools: OPERATOR_CHAT_ALLOWED_TOOLS,
+        deniedTools: OPERATOR_CHAT_DENIED_TOOLS,
+        deniedOperatorActions: OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS,
+        tools: toolSchemas,
+        instructionSkills: {
+            allowed: OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS,
+            loaded: skills.loaded.map((s) => ({
+                name: s.name,
+                description: s.description,
+                charCount: s.charCount,
+            })),
+            failures: skills.failures,
+            skipped: skills.skipped,
+            promptFragmentCharCount: composeInstructionSkillsPrompt(skills.loaded).length,
+        },
+        // M0-A: bare bash is removed; safe-read/safe-grep enforce the repo and
+        // secret boundaries instead.
+        hasBash: false,
+    });
+}
+export async function handleCreateChatSession(req, res, deps) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, {
+            ok: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    if ("clientRequestId" in body || "requestIndex" in body) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "operation idempotency ownership cannot be copied" } });
+        return;
+    }
+    const provider = typeof body.modelProvider === "string" ? body.modelProvider : undefined;
+    const modelId = typeof body.modelId === "string" ? body.modelId : undefined;
+    const snapshotInput = body.snapshot;
+    if (snapshotInput !== undefined && (!snapshotInput || typeof snapshotInput !== "object" || snapshotInput.schemaVersion !== 1 || typeof snapshotInput.summary !== "string" || !snapshotInput.summary)) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_SNAPSHOT", message: "valid OperatorContextSnapshotV1 is required" } });
+        return;
+    }
+    try {
+        deps.runtime.setDisabledInstructionSkills(await readSkillPreferences(deps.appData));
+        const snapshot = snapshotInput === undefined ? undefined : projectCompactSnapshot(snapshotInput);
+        const handle = await deps.runtime.createSession({
+            ...(provider && modelId ? { model: { provider, modelId } } : {}),
+            ...(snapshot ? { systemPromptSuffix: `Read-only initial Operator context snapshot; this is not runtime rollback.\n${snapshot.summary}` } : {}),
+        });
+        await deps.store.create({
+            sessionId: handle.sessionId,
+            sessionFile: handle.sessionFile,
+            modelProvider: handle.model?.provider,
+            modelId: handle.model?.modelId,
+        });
+        if (snapshot)
+            deps.events.append(handle.sessionId, `${handle.sessionId}:snapshot`, { kind: "compact", data: snapshot });
+        sendJson(res, 201, {
+            ok: true,
+            sessionId: handle.sessionId,
+            sessionFile: handle.sessionFile,
+            model: handle.model,
+            activeTools: handle.activeTools,
+            hasBash: false,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        sendJson(res, 500, {
+            ok: false,
+            error: { code: "CHAT_SESSION_CREATE_FAILED", message },
+        });
+    }
+}
+export async function handleForkChatSession(req, res, deps, sourceSessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (deps.events.getActiveTurn(sourceSessionId)) {
+        sendJson(res, 409, { ok: false, error: { code: "TURN_ACTIVE", message: "cannot fork an active turn" } });
+        return;
+    }
+    const source = await deps.store.get(sourceSessionId);
+    if (!source) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sourceSessionId}` } });
+        return;
+    }
+    try {
+        const handle = await deps.runtime.forkSession({ sourceSessionFile: source.sessionFile ?? "", ...(source.modelProvider && source.modelId ? { model: { provider: source.modelProvider, modelId: source.modelId } } : {}) });
+        await deps.store.forkFrom({ sourceSessionId, targetSessionId: handle.sessionId, targetSessionFile: handle.sessionFile });
+        const copied = deps.events.forkContextRefs({ sourceSessionId, targetSessionId: handle.sessionId, targetTurnId: `${handle.sessionId}:fork` });
+        await deps.operationLinker.recoverSession(handle.sessionId);
+        sendJson(res, 201, { ok: true, sessionId: handle.sessionId, forkedFrom: sourceSessionId, copiedContextRefs: copied.copiedCount, warnings: ["已发生的 task/DAG/Worker mutation 不会撤销或重放。", "operation idempotency / clientRequestId ownership 不会复制到新会话。"] });
+    }
+    catch (error) {
+        sendJson(res, 409, { ok: false, error: { code: "SESSION_FORK_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleBranchChatSession(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (deps.events.getActiveTurn(sessionId)) {
+        sendJson(res, 409, { ok: false, error: { code: "TURN_ACTIVE", message: "cannot branch an active turn" } });
+        return;
+    }
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+        return;
+    }
+    try {
+        if (!deps.runtime.hasSession(sessionId)) {
+            const reopened = await deps.runtime.reopenSession({ sessionId, sessionFile: record.sessionFile });
+            if (!reopened.ok)
+                throw new Error(reopened.message);
+        }
+        const body = await readJsonBody(req);
+        if ("clientRequestId" in body || "requestIndex" in body)
+            throw new Error("operation idempotency ownership cannot be copied");
+        const current = deps.runtime.getBranchContext(sessionId);
+        const branchFromEntryId = typeof body.branchFromEntryId === "string" ? body.branchFromEntryId : current.leafId;
+        if (!branchFromEntryId)
+            throw new Error("branchFromEntryId is required");
+        const result = await deps.runtime.branchSession({ sessionId, branchFromEntryId, ...(typeof body.summary === "string" && body.summary ? { summary: body.summary } : {}) });
+        sendJson(res, 200, { ok: true, ...result, note: "仅影响后续 LLM 上下文，未持久化第二历史" });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "SESSION_BRANCH_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleSwitchMainlineChatSession(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    try {
+        deps.runtime.switchToMainline(sessionId);
+        sendJson(res, 200, { ok: true, sessionId, active: "mainline" });
+    }
+    catch (error) {
+        sendJson(res, 409, { ok: false, error: { code: "MAINLINE_SWITCH_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleGetChatSession(_req, res, deps, sessionId) {
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, {
+            ok: false,
+            error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` },
+        });
+        return;
+    }
+    await deps.operationLinker.recoverSession(sessionId);
+    const composerDraft = await new ComposerDraftStore(deps.appData).get(sessionId);
+    const snapshot = deps.events.snapshot(sessionId);
+    const lastEvent = snapshot.at(-1);
+    sendJson(res, 200, {
+        ok: true,
+        session: {
+            ...record,
+            composerDraft,
+            activeTurnId: deps.events.getActiveTurn(sessionId)?.turnId,
+        },
+        hasBash: false,
+        lastEventId: lastEvent?.eventId ?? null,
+        lastEventSeq: lastEvent?.seq ?? 0,
+    });
+}
+export async function handleListChatSessions(_req, res, deps) {
+    const sessions = await deps.store.list({ includeArchived: true });
+    sendJson(res, 200, {
+        ok: true,
+        schemaVersion: 2,
+        sessions: sessions.map((session) => ({
+            ...session,
+            activeTurnId: deps.events.getActiveTurn(session.sessionId)?.turnId,
+        })),
+        hasBash: false,
+    });
+}
+export async function handlePatchChatSession(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    try {
+        const body = await readJsonBody(req);
+        let record;
+        if (typeof body.title === "string")
+            record = await deps.store.rename(sessionId, body.title);
+        else if (body.state === "active" || body.state === "archived") {
+            record = await deps.store.setState(sessionId, body.state);
+        }
+        else {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "title or state(active|archived) is required" } });
+            return;
+        }
+        sendJson(res, 200, { ok: true, session: record });
+    }
+    catch (error) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleReopenChatSession(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+        return;
+    }
+    if (deps.runtime.hasSession(sessionId)) {
+        sendJson(res, 200, { ok: true, sessionId, reopened: false, alreadyActive: true, hasBash: false });
+        return;
+    }
+    const result = await deps.runtime.reopenSession({
+        sessionId,
+        sessionFile: record.sessionFile,
+        ...(record.modelProvider && record.modelId
+            ? { model: { provider: record.modelProvider, modelId: record.modelId } }
+            : {}),
+    });
+    if (!result.ok) {
+        sendJson(res, 409, { ok: false, error: { code: result.code, message: result.message } });
+        return;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        sessionId,
+        reopened: true,
+        sessionFile: result.handle.sessionFile,
+        model: result.handle.model,
+        activeTools: result.handle.activeTools,
+        hasBash: false,
+    });
+}
+export async function handleChatPrompt(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, {
+            ok: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    let images;
+    try {
+        images = parseChatImages(body.images);
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_ATTACHMENT", message: error instanceof Error ? error.message : String(error) } });
+        return;
+    }
+    if (!text) {
+        sendJson(res, 400, {
+            ok: false,
+            error: { code: "INVALID_INPUT", message: "text is required" },
+        });
+        return;
+    }
+    if (!deps.runtime.hasSession(sessionId)) {
+        // M1-S04/S05: lazily reopen a persisted session that is no longer in
+        // memory (Console restart / browser refresh). Fail-closed when there is
+        // no durable record or no Pi session file — we never silently create a
+        // fresh session under the same id, which would lose prior context.
+        const record = await deps.store.get(sessionId);
+        if (!record) {
+            sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+            return;
+        }
+        const reopen = await deps.runtime.reopenSession({
+            sessionId,
+            sessionFile: record.sessionFile,
+            ...(record.modelProvider && record.modelId
+                ? { model: { provider: record.modelProvider, modelId: record.modelId } }
+                : {}),
+        });
+        if (!reopen.ok) {
+            sendJson(res, 409, { ok: false, error: { code: reopen.code, message: reopen.message } });
+            return;
+        }
+    }
+    const actionContext = deps.runtime.actionContext;
+    if (!actionContext) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "CHAT_NO_ACTION_CONTEXT",
+                message: "Chat runtime has no operator action context wired",
+            },
+        });
+        return;
+    }
+    // Acquire the per-session active-turn lease (T01/T16). The compatibility
+    // prompt SSE route uses the same durable Turn resource as POST /turns.
+    const createdTurn = deps.events.createTurn(sessionId);
+    if (!createdTurn.ok) {
+        sendJson(res, 409, {
+            ok: false,
+            error: {
+                code: "TURN_ACTIVE",
+                message: `chat turn already active: ${createdTurn.activeTurn.turnId}`,
+            },
+        });
+        return;
+    }
+    const turnId = createdTurn.turn.turnId;
+    deps.events.setTurnState(sessionId, turnId, "running");
+    // Stream events via SSE. Each event is FIRST persisted to the chat event
+    // ring (so a reconnect via GET /events can resume by Last-Event-ID), THEN
+    // framed with its eventId as the SSE `id:` line.
+    openSseResponse(res);
+    const ac = new AbortController();
+    let closed = false;
+    let abortedByClient = false;
+    // Prefer response close: after the request body is fully read, browser abort
+    // of an SSE response typically emits res.close, not req.close.
+    res.once("close", () => {
+        if (res.writableEnded)
+            return;
+        closed = true;
+        abortedByClient = true;
+        ac.abort();
+    });
+    // Lazily import to avoid circular module load.
+    const { runChatTurn } = await import("./session-store.js");
+    try {
+        const outcome = await runChatTurn({
+            runtime: deps.runtime,
+            store: deps.store,
+            actionContext,
+            sessionId,
+            text,
+            images,
+            signal: ac.signal,
+            onOperationAccepted: (accepted) => deps.operationLinker.link({
+                sessionId,
+                turnId,
+                toolCallId: accepted.toolCallId,
+                operationId: accepted.operationId,
+            }),
+            onEvent: (event) => {
+                if (closed)
+                    return;
+                if (event.type === "tool_result" && event.toolName === "prepareDagConfirmation" && !event.isError) {
+                    const result = event.result;
+                    const confirmationId = result?.confirmation?.confirmationId;
+                    if (confirmationId)
+                        void ctxConfirmationCard(deps, sessionId, turnId, confirmationId);
+                }
+                if (event.type === "tool_result" && event.toolName === "prepareMutationGate" && !event.isError) {
+                    const result = event.result;
+                    if (result?.receiptId)
+                        void ctxMutationGateCard(deps, sessionId, result.receiptId);
+                }
+                // heartbeat is a keep-alive: write it as an SSE comment frame (":\n\n")
+                // which proxies/browsers treat as traffic but clients ignore as data.
+                // It is NOT persisted (no real state change).
+                if (event.type === "heartbeat") {
+                    if (!res.writableEnded)
+                        res.write(": heartbeat\n\n");
+                    return;
+                }
+                const partial = turnEventToStorePartial(event);
+                if (!partial)
+                    return;
+                const persisted = deps.events.append(sessionId, turnId, partial);
+                if (!res.writableEnded)
+                    writeChatSse(res, persisted);
+            },
+        });
+        if (abortedByClient || ac.signal.aborted) {
+            deps.events.setTurnState(sessionId, turnId, "aborted", {
+                code: "CLIENT_ABORTED",
+                message: "client disconnected before turn settled",
+            });
+        }
+        else {
+            deps.events.setTurnState(sessionId, turnId, outcome.ok ? "settled" : "failed", outcome.error);
+        }
+    }
+    catch (error) {
+        // runChatTurn should not reject (it catches runtime.prompt failures
+        // internally and returns {ok:false}), but a pre-prompt persistence failure
+        // (e.g. store.appendMessage for the user message) CAN throw after the SSE
+        // stream is already open. Persist + emit an error event so a reconnecting
+        // client also sees the failure (not just the original requester).
+        const message = error instanceof Error ? error.message : String(error);
+        deps.events.setTurnState(sessionId, turnId, abortedByClient || ac.signal.aborted ? "aborted" : "failed", {
+            code: abortedByClient || ac.signal.aborted ? "CLIENT_ABORTED" : "CHAT_TURN_FAILED",
+            message,
+        });
+        if (!closed) {
+            const persisted = deps.events.append(sessionId, turnId, {
+                kind: "error",
+                data: { message },
+            });
+            if (!res.writableEnded)
+                writeChatSse(res, persisted);
+        }
+    }
+    finally {
+        // Guarantee the SSE stream is terminated regardless of outcome so the
+        // connection never hangs (regression: previously a rejected promise left
+        // res open and the client waited indefinitely).
+        if (!closed && !res.writableEnded) {
+            res.end();
+        }
+    }
+}
+/**
+ * Resource-oriented turn start (M1-T02/T15): acknowledge quickly, while the
+ * Pi prompt continues independently of this HTTP response and publishes to the
+ * persisted event ring consumed by GET /events.
+ */
+export async function handleCreateChatTurn(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: error instanceof Error ? error.message : String(error) } });
+        return;
+    }
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    let images;
+    try {
+        images = parseChatImages(body.images);
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_ATTACHMENT", message: error instanceof Error ? error.message : String(error) } });
+        return;
+    }
+    if (!text) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "text is required" } });
+        return;
+    }
+    if (!deps.runtime.hasSession(sessionId)) {
+        const record = await deps.store.get(sessionId);
+        if (!record) {
+            sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+            return;
+        }
+        const reopen = await deps.runtime.reopenSession({
+            sessionId,
+            sessionFile: record.sessionFile,
+            ...(record.modelProvider && record.modelId
+                ? { model: { provider: record.modelProvider, modelId: record.modelId } }
+                : {}),
+        });
+        if (!reopen.ok) {
+            sendJson(res, 409, { ok: false, error: { code: reopen.code, message: reopen.message } });
+            return;
+        }
+    }
+    const actionContext = deps.runtime.actionContext;
+    if (!actionContext) {
+        sendJson(res, 503, { ok: false, error: { code: "CHAT_NO_ACTION_CONTEXT", message: "Chat runtime has no operator action context wired" } });
+        return;
+    }
+    const created = deps.events.createTurn(sessionId);
+    if (!created.ok) {
+        sendJson(res, 409, {
+            ok: false,
+            error: { code: "TURN_ACTIVE", message: `chat turn already active: ${created.activeTurn.turnId}` },
+        });
+        return;
+    }
+    const turn = created.turn;
+    deps.events.setTurnState(sessionId, turn.turnId, "running");
+    sendJson(res, 202, { ok: true, turnId: turn.turnId, ordinal: turn.ordinal, state: "running" });
+    // Deliberately detached from the request lifecycle: closing the POST
+    // response cannot abort the prompt; clients follow GET /events instead.
+    void (async () => {
+        const { runChatTurn } = await import("./session-store.js");
+        try {
+            const outcome = await runChatTurn({
+                runtime: deps.runtime,
+                store: deps.store,
+                actionContext,
+                sessionId,
+                text,
+                images,
+                onOperationAccepted: (accepted) => deps.operationLinker.link({
+                    sessionId,
+                    turnId: turn.turnId,
+                    toolCallId: accepted.toolCallId,
+                    operationId: accepted.operationId,
+                }),
+                onEvent: (event) => {
+                    if (event.type === "heartbeat")
+                        return;
+                    const partial = turnEventToStorePartial(event);
+                    if (partial)
+                        deps.events.append(sessionId, turn.turnId, partial);
+                },
+            });
+            deps.events.setTurnState(sessionId, turn.turnId, outcome.ok ? "settled" : "failed", outcome.error);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            deps.events.append(sessionId, turn.turnId, { kind: "error", data: { message } });
+            deps.events.setTurnState(sessionId, turn.turnId, "failed", {
+                code: "CHAT_TURN_FAILED",
+                message,
+            });
+        }
+    })();
+}
+export async function handleGetChatTurn(_req, res, deps, sessionId, turnId) {
+    const turn = deps.events.getTurn(sessionId, turnId);
+    if (!turn) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat turn not found: ${turnId}` } });
+        return;
+    }
+    sendJson(res, 200, { ok: true, turn });
+}
+export async function handleChatEventsStream(req, res, deps, sessionId) {
+    // Read routes (capabilities/sessions GET) are open to loopback; the events
+    // stream is a READ and does NOT require the mutation gate, but we still need
+    // the boot cookie so only the Console browser can poll a live session.
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+        return;
+    }
+    await deps.operationLinker.recoverSession(sessionId);
+    openSseResponse(res);
+    // Resume from the client's last seen eventId (Last-Event-ID header, T04).
+    const lastEventIdHeader = req.headers["last-event-id"];
+    const afterSeq = parseLastEventId(Array.isArray(lastEventIdHeader) ? lastEventIdHeader[0] : lastEventIdHeader);
+    const replay = deps.events.listFrom(sessionId, afterSeq);
+    let lastSeq = afterSeq;
+    if ("error" in replay) {
+        // Cursor aged out of the bounded ring (T07 fence): tell the client to
+        // reconcile from a fresh snapshot rather than render a gap as if current.
+        writeChatSse(res, {
+            kind: "reconcile",
+            sessionId,
+            reason: "cursor_expired",
+            minSeq: replay.minSeq,
+            latestTurnId: deps.events.latestTurnId(sessionId),
+        });
+        // Fall back to full retained snapshot so the client can re-render.
+        for (const ev of deps.events.snapshot(sessionId)) {
+            writeChatSse(res, ev);
+            lastSeq = Math.max(lastSeq, ev.seq);
+        }
+    }
+    else {
+        for (const ev of replay.events) {
+            writeChatSse(res, ev);
+            lastSeq = Math.max(lastSeq, ev.seq);
+        }
+    }
+    let closed = false;
+    res.once("close", () => {
+        closed = true;
+    });
+    // Follow live appends for a short window so a reconnect that lands while a
+    // turn is still streaming continues to receive new events (T05). If nothing
+    // arrives within the follow window we close the stream idempotently; the
+    // client re-opens GET /events and resumes from its tracked Last-Event-ID.
+    const FOLLOW_WINDOW_MS = 25_000;
+    const IDLE_CLOSE_MS = 12_000;
+    const unsub = deps.events.subscribe(sessionId, (ev) => {
+        if (closed || res.writableEnded)
+            return;
+        if (ev.seq <= lastSeq)
+            return; // already sent during replay
+        writeChatSse(res, ev);
+        lastSeq = ev.seq;
+    });
+    const startedAt = Date.now();
+    const tick = setInterval(() => {
+        if (closed || res.writableEnded) {
+            clearInterval(tick);
+            return;
+        }
+        const elapsed = Date.now() - startedAt;
+        // Emit a keep-alive comment so proxies/browsers don't drop the idle stream.
+        res.write(": keepalive\n\n");
+        if (elapsed >= FOLLOW_WINDOW_MS) {
+            clearInterval(tick);
+            unsub();
+            if (!res.writableEnded)
+                res.end();
+        }
+    }, IDLE_CLOSE_MS);
+    // If the client disconnects before the window elapses, clean up.
+    res.once("close", () => {
+        clearInterval(tick);
+        unsub();
+    });
+}
+export async function handleDeleteChatSession(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, {
+            ok: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    deps.runtime.dispose(sessionId);
+    deps.operationLinker.clearSession(sessionId);
+    deps.events.clear(sessionId);
+    const removed = await deps.store.remove(sessionId);
+    await new ComposerDraftStore(deps.appData).remove(sessionId);
+    if (!removed) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+        return;
+    }
+    sendJson(res, 200, { ok: true, sessionId, disposed: true, removed: true });
+}
+export async function handleGetTaskContext(_res, res, deps, sessionId) {
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    const events = deps.events.snapshot(sessionId);
+    const context = projectTaskContext(events);
+    const latest = events.at(-1);
+    sendJson(res, 200, {
+        ok: true,
+        context,
+        lastSeq: latest?.seq ?? 0,
+        lastEventId: latest?.eventId,
+    });
+}
+async function handleComposerDraft(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        const body = await readJsonBody(req, 70 * 1024);
+        const text = typeof body.text === "string" ? body.text : "";
+        await new ComposerDraftStore(deps.appData).save(sessionId, text);
+        sendJson(res, 200, { ok: true });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleRepoBrowser(res, deps, kind, rawPath) {
+    try {
+        const data = kind === "tree"
+            ? await listRepoDirectory(deps.appData.repoRoot, rawPath)
+            : await readRepoPreview(deps.appData.repoRoot, rawPath);
+        sendJson(res, 200, { ok: true, data });
+    }
+    catch (error) {
+        const failure = error instanceof RepoBrowserError
+            ? error
+            : new RepoBrowserError(500, "READ_FAILED", error instanceof Error ? error.message : String(error));
+        sendJson(res, failure.status, { ok: false, error: { code: failure.code, message: failure.message } });
+    }
+}
+async function handlePiConfig(req, res, deps, resource) {
+    try {
+        if (resource === "models") {
+            const agentDir = await deps.runtime.getAgentDir();
+            if (req.method === "GET")
+                sendJson(res, 200, { ok: true, data: await readModelsConfig(agentDir) });
+            else {
+                const gate = gateMutation(req, deps);
+                if (!gate.ok) {
+                    sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+                    return;
+                }
+                const body = await readJsonBody(req);
+                sendJson(res, 200, { ok: true, data: await patchModelsConfig(agentDir, body) });
+            }
+            return;
+        }
+        if (resource === "packages") {
+            sendJson(res, 200, { ok: true, data: { packages: await readPackageInventory(await deps.runtime.getAgentDir(), deps.appData.repoRoot), mutationSupported: false } });
+            return;
+        }
+        if (req.method === "GET") {
+            const disabledNames = await readSkillPreferences(deps.appData);
+            const loaded = await loadOperatorChatInstructionSkills(deps.skillsDir);
+            sendJson(res, 200, { ok: true, data: {
+                    allowed: OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.map((name) => {
+                        const skill = loaded.loaded.find((item) => item.name === name);
+                        return {
+                            name,
+                            description: skill?.description ?? "",
+                            contentHash: skill
+                                ? createHash("sha256").update(skill.bodyText).digest("hex")
+                                : undefined,
+                        };
+                    }),
+                    conditional: OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS,
+                    denied: OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS,
+                    disabledNames,
+                } });
+        }
+        else {
+            const gate = gateMutation(req, deps);
+            if (!gate.ok) {
+                sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+                return;
+            }
+            const body = await readJsonBody(req);
+            const disabledNames = await writeSkillPreferences(deps.appData, Array.isArray(body.disabledNames) ? body.disabledNames.filter((name) => typeof name === "string") : []);
+            deps.runtime.setDisabledInstructionSkills(disabledNames);
+            sendJson(res, 200, { ok: true, data: { disabledNames, appliesTo: "new-sessions" } });
+        }
+    }
+    catch (error) {
+        const failure = error;
+        sendJson(res, failure.status ?? 400, { ok: false, error: { code: failure.code ?? "INVALID_INPUT", message: failure.message } });
+    }
+}
+async function handleChatFiles(res, deps, sessionId, query) {
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    const q = query.trim().toLowerCase();
+    const files = (await walkRepoFiles(deps.appData.repoRoot, { skipSensitive: true, maxFiles: 5000 }))
+        .map((entry) => entry.repoRelative).filter((file) => !isSensitivePath(file) && (!q || file.toLowerCase().includes(q)))
+        .sort((a, b) => a.localeCompare(b)).slice(0, 50).map((path) => ({ path }));
+    sendJson(res, 200, { ok: true, files });
+}
+async function handleRuntimeContext(res, deps, sessionId) {
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, { ok: false });
+        return;
+    }
+    const skills = await loadOperatorChatInstructionSkills(deps.skillsDir);
+    const selection = deps.runtime.getRuntimeSelection(sessionId);
+    sendJson(res, 200, { ok: true, context: projectRuntimeContext({ systemPrompt: "Operator Chat isolated system prompt", skills: skills.loaded, model: selection.model ?? (record.modelProvider && record.modelId ? { provider: record.modelProvider, modelId: record.modelId } : undefined), thinkingLevel: selection.thinkingLevel ?? record.thinkingLevel, activeTools: selection.activeTools }) });
+}
+async function handleModels(req, res, deps, sessionId) {
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        if ((req.method ?? "GET").toUpperCase() === "GET") {
+            sendJson(res, 200, { ok: true, models: await deps.runtime.listModels(sessionId), thinkingLevels: THINKING_LEVELS });
+            return;
+        }
+        const gate = gateMutation(req, deps);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return;
+        }
+        const body = await readJsonBody(req);
+        let updated;
+        if (typeof body.provider === "string" && typeof body.modelId === "string") {
+            const model = await deps.runtime.applyModel(sessionId, { provider: body.provider, modelId: body.modelId });
+            updated = await deps.store.setRuntimeSelection(sessionId, { modelProvider: model.provider, modelId: model.modelId });
+        }
+        else if (typeof body.thinkingLevel === "string" && THINKING_LEVELS.includes(body.thinkingLevel)) {
+            const thinkingLevel = deps.runtime.applyThinkingLevel(sessionId, body.thinkingLevel);
+            updated = await deps.store.setRuntimeSelection(sessionId, { thinkingLevel });
+        }
+        else {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "provider/modelId or thinkingLevel is required" } });
+            return;
+        }
+        sendJson(res, 200, { ok: true, session: updated });
+    }
+    catch (error) {
+        sendJson(res, 409, { ok: false, error: { code: "MODEL_SWITCH_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function requireChatSession(res, deps, sessionId) {
+    if (await deps.store.get(sessionId))
+        return true;
+    sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+    return false;
+}
+async function handleLinkWorkspaceOperation(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        const body = await readJsonBody(req);
+        const operationId = typeof body.operationId === "string" ? body.operationId.trim() : "";
+        if (!operationId) {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "operationId is required" } });
+            return;
+        }
+        const operations = deps.runtime.actionContext?.operations;
+        if (!operations || !await operations.get(operationId)) {
+            sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `operation not found: ${operationId}` } });
+            return;
+        }
+        await deps.operationLinker.link({ sessionId, turnId: deps.events.latestTurnId(sessionId) ?? "workspace", toolCallId: `workspace-${operationId}`, operationId });
+        sendJson(res, 200, { ok: true });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleStartInterview(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        const body = await readJsonBody(req);
+        const taskId = typeof body.taskId === "string" ? body.taskId.trim() : "";
+        if (!taskId) {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "taskId is required" } });
+            return;
+        }
+        const adapter = new ChatInterviewAdapter(deps.appData, deps.events);
+        const state = await adapter.start({ operatorSessionId: sessionId, taskId, ...(typeof body.title === "string" ? { title: body.title } : {}), ...(body.initialDraft && typeof body.initialDraft === "object" ? { initialDraft: body.initialDraft } : {}) });
+        sendJson(res, 201, { ok: true, ...projectChatInterviewState(state) });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INTERVIEW_START_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleAnswerInterview(req, res, deps, sessionId, interviewSessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        const body = await readJsonBody(req);
+        const questionId = typeof body.questionId === "string" ? body.questionId : "";
+        const response = typeof body.response === "string" ? body.response : "";
+        if (!questionId || !response) {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "questionId and response are required" } });
+            return;
+        }
+        const state = await new ChatInterviewAdapter(deps.appData, deps.events).answer({ operatorSessionId: sessionId, interviewSessionId, questionId, response, ...(typeof body.text === "string" ? { text: body.text } : {}) });
+        sendJson(res, 200, { ok: true, ...projectChatInterviewState(state) });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "INTERVIEW_ANSWER_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleGetInterviewFact(res, deps, sessionId, interviewSessionId, fact) {
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    const state = await new ChatInterviewAdapter(deps.appData, deps.events).get(interviewSessionId);
+    if (!state || state.interview.operatorSessionId !== sessionId) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `interview session not found: ${interviewSessionId}` } });
+        return;
+    }
+    const projected = projectChatInterviewState(state);
+    sendJson(res, 200, { ok: true, [fact]: projected[fact] });
+}
+async function ctxConfirmationCard(deps, sessionId, turnId, confirmationId) {
+    const confirmation = await deps.runtime.actionContext?.confirmations.get(confirmationId);
+    if (!confirmation)
+        return;
+    const taskId = String(confirmation.taskContractBinding.taskId ?? "");
+    appendHumanGateCard(deps, sessionId, makeHumanGateCard({
+        cardId: `dag-${confirmationId}`,
+        gateType: "dag-run",
+        state: confirmation.state === "confirmed" ? "confirmed" : "prepared",
+        taskId,
+        confirmationId,
+        expiresAt: confirmation.expiresAt,
+        inspectHref: `/inspect/?taskId=${encodeURIComponent(taskId)}#/`,
+        humanGateToken: confirmation.humanGateToken,
+        displayOnlyChallenges: ["source", "writer-scope", "verification", "human-gates"],
+        contractRevision: confirmation.taskContractBinding.revision,
+    }));
+    void turnId;
+}
+async function ctxMutationGateCard(deps, sessionId, receiptId) {
+    const { MutationGateReceiptStore } = await import("../mutation-gate-receipt-store.js");
+    const store = new MutationGateReceiptStore(deps.appData);
+    const receipt = await store.get(receiptId);
+    if (!receipt)
+        return;
+    appendHumanGateCard(deps, sessionId, makeHumanGateCard({
+        cardId: `mutation-${receipt.receiptId}`,
+        gateType: "mutation",
+        state: "prepared",
+        taskId: receipt.action,
+        receiptId: receipt.receiptId,
+        expiresAt: receipt.expiresAt,
+        humanGateToken: receipt.humanGateToken,
+        inspectHref: `/inspect/#/`,
+    }));
+}
+function actionResultBody(result) {
+    const body = result.body;
+    return (body.result && typeof body.result === "object" ? body.result : body);
+}
+function appendHumanGateCard(deps, sessionId, card) {
+    deps.events.append(sessionId, deps.events.latestTurnId(sessionId) ?? "human-gate", {
+        kind: "human-gate-card",
+        data: card,
+    });
+}
+async function liveContractBinding(ctx, taskId) {
+    const draft = await ctx.drafts.get(taskId);
+    if (!draft)
+        throw new Error(`draft not found: ${taskId}`);
+    const shown = await dispatchOperatorAction(ctx, { action: "contractShow", actionParams: { taskId } });
+    if (shown.kind === "error")
+        throw new Error("contractShow failed");
+    const result = actionResultBody(shown);
+    const state = result.state;
+    const revision = state?.ref?.revision ?? 0;
+    const expectedObservedHash = state?.observedCanonicalHash ?? "0".repeat(64);
+    return { taskId, revision, canonicalHash: state?.ref?.canonicalHash ?? expectedObservedHash, draftSha256: draft.draftSha256, expectedObservedHash };
+}
+async function handleContractApplyHumanGate(req, res, deps, sessionId, step) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    const ctx = deps.runtime.actionContext;
+    if (!ctx) {
+        sendJson(res, 503, { ok: false, error: { code: "CHAT_NO_ACTION_CONTEXT", message: "Chat runtime has no operator action context wired" } });
+        return;
+    }
+    try {
+        const body = await readJsonBody(req);
+        const receipts = new ContractApplyReceiptStore(deps.appData);
+        if (step === "prepare") {
+            const taskId = typeof body.taskId === "string" ? body.taskId.trim() : "";
+            if (!taskId)
+                throw new Error("taskId is required");
+            const binding = await liveContractBinding(ctx, taskId);
+            const expiresAt = new Date(Date.now() + 30 * 60_000).toISOString();
+            const receiptId = `apply_${crypto.randomUUID()}`;
+            const humanGateToken = issueHumanGateToken({ confirmationId: receiptId, payloadHash: contractApplyPayloadHash(binding), expiresAt }, deps.bootToken.confirmationToken);
+            const receipt = await receipts.prepare({ receiptId, operatorSessionId: sessionId, ...binding, expiresAt, humanGateToken });
+            const card = makeHumanGateCard({ cardId: `contract-${receipt.receiptId}`, gateType: "contract-apply", state: "prepared", taskId, receiptId: receipt.receiptId, expiresAt, humanGateToken, contractRevision: binding.revision, contractDiffSummary: `revision ${binding.revision}; draft ${binding.draftSha256.slice(0, 12)}; observed ${binding.expectedObservedHash.slice(0, 12)}`, inspectHref: `/inspect/?taskId=${encodeURIComponent(taskId)}#/` });
+            appendHumanGateCard(deps, sessionId, card);
+            sendJson(res, 201, { ok: true, card });
+            return;
+        }
+        const receiptId = typeof body.receiptId === "string" ? body.receiptId : "";
+        const receipt = await receipts.get(receiptId);
+        if (!receipt || receipt.operatorSessionId !== sessionId) {
+            sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: "contract apply receipt not found" } });
+            return;
+        }
+        const current = await liveContractBinding(ctx, receipt.taskId);
+        const check = verifyHumanGateToken(body.humanGateToken, { confirmationId: receipt.receiptId, payloadHash: contractApplyPayloadHash(current) }, deps.bootToken.confirmationToken);
+        if (!check.ok) {
+            sendJson(res, 403, { ok: false, error: { code: check.code, message: check.message } });
+            return;
+        }
+        const reserved = await receipts.tryReserve(receiptId);
+        if (!reserved.ok) {
+            sendJson(res, reserved.code === "NOT_FOUND" ? 404 : reserved.code === "EXPIRED" ? 410 : 409, {
+                ok: false,
+                error: { code: reserved.code, message: reserved.message },
+            });
+            return;
+        }
+        if (!reserved.reserved) {
+            const operationId = reserved.receipt.operationId;
+            const card = makeHumanGateCard({
+                cardId: `contract-${receiptId}`,
+                gateType: "contract-apply",
+                state: "dispatched",
+                taskId: receipt.taskId,
+                receiptId,
+                expiresAt: receipt.expiresAt,
+                contractRevision: receipt.revision,
+                operationId,
+                inspectHref: operationId
+                    ? `/inspect/?operationId=${encodeURIComponent(operationId)}#/`
+                    : `/inspect/?taskId=${encodeURIComponent(receipt.taskId)}#/`,
+            });
+            appendHumanGateCard(deps, sessionId, card);
+            sendJson(res, 202, {
+                ok: true,
+                card,
+                result: operationId
+                    ? { operationId, state: "accepted", action: "contractApply", clientRequestId: `chat-apply-${receiptId}` }
+                    : { state: reserved.reason },
+            });
+            return;
+        }
+        const clientRequestId = typeof body.clientRequestId === "string" && body.clientRequestId.trim()
+            ? body.clientRequestId.trim()
+            : `chat-apply-${receiptId}`;
+        const result = await dispatchOperatorAction(ctx, {
+            action: "contractApply",
+            actionParams: {
+                taskId: receipt.taskId,
+                expectedRevision: receipt.revision,
+                expectedObservedHash: receipt.expectedObservedHash,
+            },
+            clientRequestId,
+        });
+        if (result.kind === "error") {
+            await receipts.releaseToPrepared(receiptId);
+            sendJson(res, result.status, result.body);
+            return;
+        }
+        const operationId = result.kind === "accepted" ? result.body.operationId : undefined;
+        await receipts.markDispatched(receiptId, operationId);
+        const card = makeHumanGateCard({ cardId: `contract-${receiptId}`, gateType: "contract-apply", state: "dispatched", taskId: receipt.taskId, receiptId, expiresAt: receipt.expiresAt, contractRevision: receipt.revision, operationId, inspectHref: operationId ? `/inspect/?operationId=${encodeURIComponent(operationId)}#/` : `/inspect/?taskId=${encodeURIComponent(receipt.taskId)}#/` });
+        appendHumanGateCard(deps, sessionId, card);
+        if (operationId)
+            await deps.operationLinker.link({ sessionId, turnId: deps.events.latestTurnId(sessionId) ?? "human-gate", toolCallId: "human-contract-apply", operationId });
+        sendJson(res, result.status, { ok: true, card, result: actionResultBody(result) });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "HUMAN_GATE_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleDagHumanGate(req, res, deps, sessionId, step) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    const ctx = deps.runtime.actionContext;
+    if (!ctx) {
+        sendJson(res, 503, { ok: false, error: { code: "CHAT_NO_ACTION_CONTEXT", message: "Chat runtime has no operator action context wired" } });
+        return;
+    }
+    try {
+        const body = await readJsonBody(req);
+        const action = step === "prepare" ? "prepareDagConfirmation" : step === "confirm" ? "confirmDagConfirmation" : "runDag";
+        const result = await dispatchOperatorAction(ctx, {
+            action,
+            actionParams: body,
+            clientRequestId: typeof body.clientRequestId === "string" ? body.clientRequestId : `chat-${sessionId}-${Date.now()}`,
+        });
+        if (result.kind === "error") {
+            sendJson(res, result.status, result.body);
+            return;
+        }
+        const projected = actionResultBody(result);
+        const confirmation = (projected.confirmation ?? await ctx.confirmations.get(String(body.confirmationId ?? "")));
+        const confirmationId = String(confirmation?.confirmationId ?? body.confirmationId ?? "");
+        const taskBinding = confirmation?.taskContractBinding;
+        const taskId = String(taskBinding?.taskId ?? body.taskId ?? "");
+        const state = step === "prepare" ? "prepared" : step === "confirm" ? "confirmed" : "dispatched";
+        const operationId = result.kind === "accepted" ? result.body.operationId : undefined;
+        const dagText = typeof body.dagText === "string" ? body.dagText : typeof body.dagJson === "string" ? body.dagJson : "";
+        let dagSpine;
+        try {
+            const parsed = JSON.parse(dagText);
+            dagSpine = parsed.nodes?.map((node) => String(node.id ?? "")).filter(Boolean);
+        }
+        catch { /* display summary is optional */ }
+        const card = makeHumanGateCard({
+            cardId: `dag-${confirmationId}`,
+            gateType: "dag-run",
+            state,
+            taskId,
+            confirmationId,
+            expiresAt: String(confirmation?.expiresAt ?? new Date().toISOString()),
+            inspectHref: operationId ? `/inspect/?operationId=${encodeURIComponent(operationId)}#/` : `/inspect/?taskId=${encodeURIComponent(taskId)}#/`,
+            ...(confirmation?.humanGateToken ? { humanGateToken: confirmation.humanGateToken } : {}),
+            displayOnlyChallenges: Array.isArray(projected.requiredChallenges) ? projected.requiredChallenges.map(String) : undefined,
+            contractRevision: typeof taskBinding?.revision === "number" ? taskBinding.revision : undefined,
+            dagSpine,
+            operationId,
+        });
+        appendHumanGateCard(deps, sessionId, card);
+        if (operationId)
+            await deps.operationLinker.link({ sessionId, turnId: deps.events.latestTurnId(sessionId) ?? "human-gate", toolCallId: `human-${step}`, operationId });
+        sendJson(res, result.status, { ok: true, card, result: projected });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "HUMAN_GATE_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+async function handleMutationHumanGate(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!(await requireChatSession(res, deps, sessionId)))
+        return;
+    const ctx = deps.runtime.actionContext;
+    if (!ctx) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "CHAT_NO_ACTION_CONTEXT",
+                message: "Chat runtime has no operator action context wired",
+            },
+        });
+        return;
+    }
+    try {
+        const body = await readJsonBody(req);
+        const receiptId = typeof body.receiptId === "string" ? body.receiptId : "";
+        const { MutationGateReceiptStore } = await import("../mutation-gate-receipt-store.js");
+        const store = new MutationGateReceiptStore(deps.appData);
+        const receipt = await store.get(receiptId);
+        if (!receipt || receipt.operatorSessionId !== ctx.operatorSessionId) {
+            sendJson(res, 404, {
+                ok: false,
+                error: { code: "NOT_FOUND", message: "mutation gate receipt not found" },
+            });
+            return;
+        }
+        const result = await dispatchOperatorAction(ctx, {
+            action: receipt.action,
+            actionParams: {
+                ...receipt.actionParams,
+                confirmationId: receipt.receiptId,
+                humanGateToken: body.humanGateToken ?? receipt.humanGateToken,
+            },
+            clientRequestId: `chat-mutation-${receipt.receiptId}`,
+        });
+        if (result.kind === "error") {
+            sendJson(res, result.status, result.body);
+            return;
+        }
+        const operationId = result.kind === "accepted" ? result.body.operationId : undefined;
+        const card = makeHumanGateCard({
+            cardId: `mutation-${receiptId}`,
+            gateType: "mutation",
+            state: "dispatched",
+            taskId: receipt.action,
+            receiptId,
+            expiresAt: receipt.expiresAt,
+            operationId,
+            inspectHref: operationId
+                ? `/inspect/?operationId=${encodeURIComponent(operationId)}#/`
+                : `/inspect/#/`,
+        });
+        appendHumanGateCard(deps, sessionId, card);
+        if (operationId) {
+            await deps.operationLinker.link({
+                sessionId,
+                turnId: deps.events.latestTurnId(sessionId) ?? "human-gate",
+                toolCallId: "human-mutation-apply",
+                operationId,
+            });
+        }
+        sendJson(res, result.status, { ok: true, card, result: actionResultBody(result) });
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "HUMAN_GATE_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+    }
+}
+async function handleConfirmTaskKind(req, res, deps, sessionId, interviewSessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (!await requireChatSession(res, deps, sessionId))
+        return;
+    try {
+        const body = await readJsonBody(req);
+        if (typeof body.taskKind !== "string" || !body.taskKind.trim()) {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "taskKind is required" } });
+            return;
+        }
+        const state = await new ChatInterviewAdapter(deps.appData, deps.events).confirmTaskKind({ operatorSessionId: sessionId, interviewSessionId, taskKind: body.taskKind });
+        sendJson(res, 200, { ok: true, ...projectChatInterviewState(state) });
+    }
+    catch (error) {
+        sendJson(res, 400, { ok: false, error: { code: "TASK_KIND_CONFIRM_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleChatCompact(req, res, deps, sessionId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+        return;
+    }
+    if (deps.events.getActiveTurn(sessionId)) {
+        sendJson(res, 409, { ok: false, error: { code: "TURN_ACTIVE", message: "cannot compact an active turn" } });
+        return;
+    }
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `chat session not found: ${sessionId}` } });
+        return;
+    }
+    if (!deps.runtime.hasSession(sessionId)) {
+        const reopened = await deps.runtime.reopenSession({ sessionId, sessionFile: record.sessionFile, ...(record.modelProvider && record.modelId ? { model: { provider: record.modelProvider, modelId: record.modelId } } : {}) });
+        if (!reopened.ok) {
+            sendJson(res, 409, { ok: false, error: { code: reopened.code, message: reopened.message } });
+            return;
+        }
+    }
+    try {
+        const snapshot = await deps.runtime.compact(sessionId);
+        const event = deps.events.append(sessionId, deps.events.latestTurnId(sessionId) ?? `${sessionId}:compact`, { kind: "compact", data: snapshot });
+        sendJson(res, 200, { ok: true, snapshot, eventId: event.eventId });
+    }
+    catch (error) {
+        sendJson(res, 409, { ok: false, error: { code: "COMPACTION_FAILED", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+export async function handleChatMessages(res, deps, sessionId, url) {
+    try {
+        const limit = Number(url.searchParams.get("limit") ?? 30);
+        const page = await deps.store.listMessages(sessionId, { limit: Number.isFinite(limit) ? limit : 30, beforeId: url.searchParams.get("beforeId") ?? undefined });
+        sendJson(res, 200, { ok: true, ...page });
+    }
+    catch (error) {
+        sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: error instanceof Error ? error.message : String(error) } });
+    }
+}
+/**
+ * Dispatch a chat HTTP request. Returns true if handled.
+ * Mounted under /api/operator/v1/chat/*.
+ */
+export async function handleChatRequest(req, res, deps, pathname) {
+    if (!deps)
+        return false;
+    if (!pathname.startsWith("/api/operator/v1/chat/") && !pathname.startsWith("/api/operator/v1/pi/"))
+        return false;
+    const method = (req.method ?? "GET").toUpperCase();
+    const url = new URL(req.url ?? "/", "http://localhost");
+    if (pathname === "/api/operator/v1/pi/models-config/test" && method === "POST") {
+        const gate = gateMutation(req, deps);
+        if (!gate.ok) {
+            sendJson(res, gate.status, { ok: false, error: { code: gate.code, message: gate.message } });
+            return true;
+        }
+        try {
+            const body = await readJsonBody(req);
+            if (typeof body.provider !== "string" || typeof body.modelId !== "string")
+                throw new Error("provider and modelId are required");
+            sendJson(res, 200, { ok: true, data: await deps.runtime.testConfiguredModel({ provider: body.provider, modelId: body.modelId }) });
+        }
+        catch (error) {
+            sendJson(res, 400, { ok: false, error: { code: "MODEL_TEST_FAILED", message: error instanceof Error ? error.message : String(error) } });
+        }
+        return true;
+    }
+    if (pathname === "/api/operator/v1/pi/models-config" && (method === "GET" || method === "PATCH")) {
+        await handlePiConfig(req, res, deps, "models");
+        return true;
+    }
+    if (pathname === "/api/operator/v1/pi/packages" && method === "GET") {
+        await handlePiConfig(req, res, deps, "packages");
+        return true;
+    }
+    if (pathname === "/api/operator/v1/chat/instruction-skills" && method === "GET") {
+        await handlePiConfig(req, res, deps, "skills");
+        return true;
+    }
+    if (pathname === "/api/operator/v1/chat/instruction-skills/preferences" && method === "PUT") {
+        await handlePiConfig(req, res, deps, "skills");
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/operator/v1/chat/capabilities") {
+        await handleChatCapabilities(req, res, deps);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/operator/v1/chat/repo/tree") {
+        await handleRepoBrowser(res, deps, "tree", url.searchParams.get("path") ?? "");
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/operator/v1/chat/repo/file") {
+        const filePath = url.searchParams.get("path");
+        if (!filePath)
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_PATH", message: "path is required" } });
+        else
+            await handleRepoBrowser(res, deps, "file", filePath);
+        return true;
+    }
+    if (method === "GET" && pathname === "/api/operator/v1/chat/sessions") {
+        await handleListChatSessions(req, res, deps);
+        return true;
+    }
+    const interviewStart = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/interviews$/);
+    if (method === "POST" && interviewStart) {
+        await handleStartInterview(req, res, deps, decodeURIComponent(interviewStart[1]));
+        return true;
+    }
+    const interviewAnswer = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/interviews\/([^/]+)\/answers$/);
+    if (method === "POST" && interviewAnswer) {
+        await handleAnswerInterview(req, res, deps, decodeURIComponent(interviewAnswer[1]), decodeURIComponent(interviewAnswer[2]));
+        return true;
+    }
+    const interviewFact = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/interviews\/([^/]+)\/(draft|assessment)$/);
+    if (method === "GET" && interviewFact) {
+        await handleGetInterviewFact(res, deps, decodeURIComponent(interviewFact[1]), decodeURIComponent(interviewFact[2]), interviewFact[3]);
+        return true;
+    }
+    const taskKindConfirm = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/interviews\/([^/]+)\/task-kind\/confirm$/);
+    if (method === "POST" && taskKindConfirm) {
+        await handleConfirmTaskKind(req, res, deps, decodeURIComponent(taskKindConfirm[1]), decodeURIComponent(taskKindConfirm[2]));
+        return true;
+    }
+    const contractHumanGate = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/human-gate\/contract-apply(?:\/(prepare))?$/);
+    if (method === "POST" && contractHumanGate) {
+        await handleContractApplyHumanGate(req, res, deps, decodeURIComponent(contractHumanGate[1]), contractHumanGate[2] ? "prepare" : "apply");
+        return true;
+    }
+    const dagHumanGate = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/human-gate\/dag-(prepare|confirm|run)$/);
+    if (method === "POST" && dagHumanGate) {
+        await handleDagHumanGate(req, res, deps, decodeURIComponent(dagHumanGate[1]), dagHumanGate[2]);
+        return true;
+    }
+    const mutationHumanGate = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/human-gate\/mutation-apply$/);
+    if (method === "POST" && mutationHumanGate) {
+        await handleMutationHumanGate(req, res, deps, decodeURIComponent(mutationHumanGate[1]));
+        return true;
+    }
+    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|models|model)$/);
+    if (m4Route) {
+        const id = decodeURIComponent(m4Route[1]);
+        const route = m4Route[2];
+        if (route === "draft" && method === "PUT") {
+            await handleComposerDraft(req, res, deps, id);
+            return true;
+        }
+        if (route === "files" && method === "GET") {
+            await handleChatFiles(res, deps, id, url.searchParams.get("q") ?? "");
+            return true;
+        }
+        if (route === "runtime-context" && method === "GET") {
+            await handleRuntimeContext(res, deps, id);
+            return true;
+        }
+        if (route === "models" && method === "GET") {
+            await handleModels(req, res, deps, id);
+            return true;
+        }
+        if (route === "model" && method === "POST") {
+            await handleModels(req, res, deps, id);
+            return true;
+        }
+    }
+    const sessionMainline = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/branch\/mainline$/);
+    if (method === "POST" && sessionMainline) {
+        await handleSwitchMainlineChatSession(req, res, deps, decodeURIComponent(sessionMainline[1]));
+        return true;
+    }
+    const sessionFork = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/fork$/);
+    if (method === "POST" && sessionFork) {
+        await handleForkChatSession(req, res, deps, decodeURIComponent(sessionFork[1]));
+        return true;
+    }
+    const sessionBranch = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/branch$/);
+    if (method === "POST" && sessionBranch) {
+        await handleBranchChatSession(req, res, deps, decodeURIComponent(sessionBranch[1]));
+        return true;
+    }
+    const sessionReopen = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/reopen$/);
+    if (method === "POST" && sessionReopen) {
+        await handleReopenChatSession(req, res, deps, decodeURIComponent(sessionReopen[1]));
+        return true;
+    }
+    const sessionTurn = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/turns$/);
+    if (method === "POST" && sessionTurn) {
+        await handleCreateChatTurn(req, res, deps, decodeURIComponent(sessionTurn[1]));
+        return true;
+    }
+    const sessionTurnDetail = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/turns\/([^/]+)$/);
+    if (method === "GET" && sessionTurnDetail) {
+        await handleGetChatTurn(req, res, deps, decodeURIComponent(sessionTurnDetail[1]), decodeURIComponent(sessionTurnDetail[2]));
+        return true;
+    }
+    const operationLink = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/operation-links$/);
+    if (method === "POST" && operationLink) {
+        await handleLinkWorkspaceOperation(req, res, deps, decodeURIComponent(operationLink[1]));
+        return true;
+    }
+    const sessionCompact = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/compact$/);
+    if (method === "POST" && sessionCompact) {
+        await handleChatCompact(req, res, deps, decodeURIComponent(sessionCompact[1]));
+        return true;
+    }
+    const sessionMessages = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/messages$/);
+    if (method === "GET" && sessionMessages) {
+        await handleChatMessages(res, deps, decodeURIComponent(sessionMessages[1]), url);
+        return true;
+    }
+    const sessionPrompt = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/prompt$/);
+    if (method === "POST" && sessionPrompt) {
+        await handleChatPrompt(req, res, deps, decodeURIComponent(sessionPrompt[1]));
+        return true;
+    }
+    const sessionContext = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/context$/);
+    if (method === "GET" && sessionContext) {
+        await handleGetTaskContext(req, res, deps, decodeURIComponent(sessionContext[1]));
+        return true;
+    }
+    const sessionEvents = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/events$/);
+    if (method === "GET" && sessionEvents) {
+        await handleChatEventsStream(req, res, deps, decodeURIComponent(sessionEvents[1]));
+        return true;
+    }
+    const sessionMatch = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)$/);
+    if (sessionMatch) {
+        const id = decodeURIComponent(sessionMatch[1]);
+        if (method === "GET") {
+            await handleGetChatSession(req, res, deps, id);
+            return true;
+        }
+        if (method === "PATCH") {
+            await handlePatchChatSession(req, res, deps, id);
+            return true;
+        }
+        if (method === "DELETE") {
+            await handleDeleteChatSession(req, res, deps, id);
+            return true;
+        }
+    }
+    if (method === "POST" && pathname === "/api/operator/v1/chat/sessions") {
+        await handleCreateChatSession(req, res, deps);
+        return true;
+    }
+    if (isMutationMethod(method)) {
+        // Already gated above for known routes; unknown mutation routes 404.
+        sendJson(res, 404, {
+            ok: false,
+            error: { code: "NOT_FOUND", message: `unknown chat route: ${pathname}` },
+        });
+        return true;
+    }
+    sendJson(res, 404, { ok: false, error: { code: "NOT_FOUND", message: `unknown chat route: ${pathname}` } });
+    return true;
+}
+// Re-export for route wiring; writeSseEvent kept for parity with operation-sse.
+void writeSseEvent;