@tea-agent/loop-agent 0.1.0-fe-test.0

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

@@ -0,0 +1,3137 @@
+/**
+ * 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
+ *   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 { parseAssistantContent } from "./assistant-content.js";
+import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, } from "./tools.js";
+import { buildModelCallableToolSchemas } from "./tool-adapter.js";
+import { cleanChatTitle, acceptedOperationIdFromResult } from "./session-store.js";
+import { hashChatTurnPayload, projectChatToolEventPayload, projectCompactSnapshot, } from "./chat-event-store.js";
+import { THINKING_LEVELS, RuntimeSnapshotUnavailableError, } from "./pi-runtime.js";
+import { ResourcePreferencesError, setSkillAutoInvocationPreference, } from "./resource-preferences-store.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, } from "./pi-console-config.js";
+import { ChatInterviewAdapter, projectChatInterviewState, } from "./interview-adapter.js";
+import { classifyChatCompactionFailure } from "./compaction-errors.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, writeSseEvent } from "../operation-sse.js";
+function turnSummary(turn) {
+    return {
+        turnId: turn.turnId,
+        clientRequestId: turn.clientRequestId ?? null,
+        state: turn.state,
+        ordinal: turn.ordinal,
+        createdAt: turn.createdAt,
+        startedAt: turn.startedAt ?? null,
+        finishedAt: turn.finishedAt ?? null,
+        error: turn.error ?? null,
+        abortRequestedAt: turn.abortRequestedAt ?? null,
+    };
+}
+function isTerminalTurnState(state) {
+    return state === "settled" || state === "aborted" || state === "failed";
+}
+const DEFAULT_ABORT_WAIT_MS = 2_500;
+/** Parse Chat's `<epoch>:<seq>` SSE cursor. Legacy `<sessionId>:<seq>` has
+ * the same wire shape; its prefix intentionally fails the current process
+ * epoch comparison and triggers safe snapshot recovery (M5.1). */
+function parseChatEventCursor(header) {
+    if (!header?.trim())
+        return { epoch: null, seq: 0 };
+    const raw = header.trim();
+    const colon = raw.lastIndexOf(":");
+    const seqPart = colon >= 0 ? raw.slice(colon + 1) : raw;
+    const seq = Number.parseInt(seqPart, 10);
+    return {
+        epoch: colon > 0 ? raw.slice(0, colon) : null,
+        seq: Number.isFinite(seq) && seq >= 0 ? seq : 0,
+    };
+}
+function writeChatSse(res, event) {
+    // Persisted Chat events carry their own eventId (`<epoch>:<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":
+        case "message_end": {
+            const content = parseAssistantContent(event.content);
+            return {
+                kind: event.type,
+                data: {
+                    text: String(event.text ?? ""),
+                    ...(content ? { content } : {}),
+                },
+            };
+        }
+        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": {
+            // Plan A (2026-08-16): surface the accepted-operation link on the live
+            // SSE frame so the frontend semantic event can resolve operation:<id>.
+            const resultOperationId = acceptedOperationIdFromResult(String(event.toolName ?? ""), event.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),
+                    ...(resultOperationId ? { operationId: resultOperationId } : {}),
+                }),
+            };
+        }
+        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;
+    }
+}
+function emitSessionTitle(deps, sessionId, turnId, title, automatic = false) {
+    return deps.events.append(sessionId, turnId, {
+        kind: "session_title",
+        data: { title, ...(automatic ? { automatic: true } : {}) },
+    });
+}
+function shouldEmitPlaceholder(record) {
+    return !record.title &&
+        record.messages.filter((message) => message.role === "user").length === 1
+        ? record.displayTitle
+        : undefined;
+}
+function scheduleAutomaticTitle(deps, input) {
+    void (async () => {
+        try {
+            const generated = await deps.runtime.generateTitle(input.sessionId, input.firstUserText);
+            const title = generated ? cleanChatTitle(generated) : undefined;
+            if (!title)
+                return;
+            const stored = await deps.store.setAutomaticTitle(input.sessionId, title);
+            if (!stored)
+                return;
+            emitSessionTitle(deps, input.sessionId, input.turnId, stored.title, true);
+            // Keep the best-effort Pi mirror inside this detached task's catch
+            // boundary: both synchronous throws and rejected Promises are absorbed
+            // only after durable title/event persistence has completed.
+            await deps.runtime.setSessionName(input.sessionId, stored.title);
+        }
+        catch {
+            // Background title failures must never affect the settled Chat turn.
+        }
+    })();
+}
+/** Guarantee durable terminal events for a turn that ended without the SDK
+ *  emitting them (client abort, pre-prompt persistence failure, runtime
+ *  error). Without `agent_end`, reconnect replay stops mid-turn; without
+ *  `agent_settled`, the single-stream UI keeps idle-grace streaming forever
+ *  (M4.4). Idempotent for normal settled turns that already have both. */
+function ensureAgentEndEvent(deps, sessionId, turnId) {
+    const snap = deps.events.snapshot(sessionId);
+    const hasAgentEnd = snap.some((event) => event.turnId === turnId && event.kind === "agent_end");
+    if (!hasAgentEnd) {
+        deps.events.append(sessionId, turnId, {
+            kind: "agent_end",
+            data: { willRetry: false },
+        });
+    }
+    // Error/abort paths historically only forced agent_end. After the M4 single
+    // stream keeps UI streaming through agent_end for idle grace, a matching
+    // agent_settled is required so state reconcile and the applier both finish.
+    const hasSettled = deps.events
+        .snapshot(sessionId)
+        .some((event) => event.turnId === turnId && event.kind === "agent_settled");
+    if (!hasSettled) {
+        deps.events.append(sessionId, turnId, {
+            kind: "agent_settled",
+            data: {},
+        });
+    }
+}
+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 {};
+    try {
+        return JSON.parse(raw);
+    }
+    catch (error) {
+        // Preserve throw semantics: callers map parse failures to
+        // INVALID_INPUT / 400. The explicit catch keeps malformed JSON from
+        // surfacing as an unhandled SyntaxError.
+        throw error;
+    }
+}
+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 };
+}
+/**
+ * RF-02: map a RuntimeSnapshotUnavailableError (critical snapshot projection
+ * failure — model enumeration / system prompt) to 503 PI_RUNTIME_UNAVAILABLE.
+ * Returns true when the response was sent; other errors keep their existing
+ * 409/500 branches so the mutation/reload semantics never regress.
+ */
+function sendRuntimeUnavailable(res, error) {
+    if (!(error instanceof RuntimeSnapshotUnavailableError))
+        return false;
+    sendJson(res, 503, {
+        ok: false,
+        error: { code: error.code, message: error.message },
+    });
+    return true;
+}
+/**
+ * Map a failed `reopenSession()` result to HTTP status + response error code.
+ * Must stay aligned with `ensureActiveSession` reopen-failure branches so
+ * lazy-reopen routes (prompt/turns/reopen/compact/branch) and readiness
+ * endpoints share one semantic table.
+ *
+ * Business conflicts (TURN_ACTIVE, PI_SESSION_BUSY, model switch, …) are NOT
+ * handled here — only reopen/init readiness failures.
+ */
+function mapReopenSessionFailure(reopen) {
+    if (reopen.code === "NO_SESSION_FILE") {
+        return {
+            status: 404,
+            code: "PI_SESSION_NOT_FOUND",
+            message: reopen.message,
+        };
+    }
+    if (reopen.code === "PI_SESSION_INIT_FAILED") {
+        return {
+            status: 503,
+            code: "PI_SESSION_INIT_FAILED",
+            message: reopen.message,
+        };
+    }
+    return {
+        status: 503,
+        code: "PI_RUNTIME_UNAVAILABLE",
+        message: reopen.message,
+    };
+}
+export async function handleChatCapabilities(_req, res, deps) {
+    const toolSchemas = buildModelCallableToolSchemas();
+    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,
+        // ADR 0011: full Pi tools including bash are default-active.
+        hasBash: true,
+    });
+}
+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 {
+        const snapshot = snapshotInput === undefined ? undefined : projectCompactSnapshot(snapshotInput);
+        // Fast path: durable shell + Console record before full AgentSession ready.
+        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}`,
+                }
+                : {}),
+        });
+        if (!handle.sessionFile) {
+            deps.runtime.dispose(handle.sessionId);
+            sendJson(res, 500, {
+                ok: false,
+                error: {
+                    code: "CHAT_SESSION_CREATE_FAILED",
+                    message: "chat session shell missing sessionFile",
+                },
+            });
+            return;
+        }
+        const session = 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,
+            });
+        // Best-effort: after materialization, patch resolved default model onto the
+        // durable record. Failures stay on the init fence (PI_SESSION_INIT_FAILED).
+        if (typeof deps.runtime.ensureSessionReady === "function") {
+            void deps.runtime
+                .ensureSessionReady(handle.sessionId)
+                .then(async () => {
+                if (typeof deps.runtime.getRuntimeSelection !== "function")
+                    return;
+                const selection = deps.runtime.getRuntimeSelection(handle.sessionId);
+                if (!selection?.model)
+                    return;
+                await deps.store.setRuntimeSelection(handle.sessionId, {
+                    modelProvider: selection.model.provider,
+                    modelId: selection.model.modelId,
+                });
+            })
+                .catch(() => undefined);
+        }
+        sendJson(res, 201, {
+            ok: true,
+            sessionId: handle.sessionId,
+            sessionFile: handle.sessionFile,
+            model: handle.model,
+            session,
+            activeTools: handle.activeTools,
+            hasBash: true,
+            ...(handle.initializing ? { initializing: true } : {}),
+        });
+    }
+    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) {
+                const mapped = mapReopenSessionFailure({
+                    code: reopened.code,
+                    message: reopened.message,
+                });
+                sendJson(res, mapped.status, {
+                    ok: false,
+                    error: { code: mapped.code, message: mapped.message },
+                });
+                return;
+            }
+        }
+        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,
+        eventEpoch: deps.events.epoch(sessionId),
+        session: {
+            ...record,
+            composerDraft,
+            activeTurnId: deps.events.getActiveTurn(sessionId)?.turnId,
+        },
+        hasBash: true,
+        lastEventId: lastEvent?.eventId ?? null,
+        lastEventSeq: lastEvent?.seq ?? 0,
+    });
+}
+/** Lightweight busy-truth endpoint for the client reconcile loop (pi-web
+ *  get_state equivalent): exposes the active turn + the latest turn's durable
+ *  outcome WITHOUT the full message payload, so the UI can poll it on an
+ *  interval / visibility / online without paying for session detail. */
+export async function handleGetChatSessionState(_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;
+    }
+    const active = deps.events.getActiveTurn(sessionId);
+    const latest = deps.events.latestTurn(sessionId);
+    const runtimeFacts = typeof deps.runtime.getSessionBusyFacts === "function"
+        ? deps.runtime.getSessionBusyFacts(sessionId)
+        : {
+            isStreaming: false,
+            isPromptRunning: false,
+            isCompacting: false,
+            isBashRunning: false,
+        };
+    sendJson(res, 200, {
+        ok: true,
+        state: {
+            // Legacy flat fields retained for older clients.
+            activeTurnId: active?.turnId ?? null,
+            activeTurnState: active?.state ?? null,
+            latestTurnId: latest?.turnId ?? null,
+            latestTurnState: latest?.state ?? null,
+            activeTurn: active ? turnSummary(active) : null,
+            latestTurn: latest ? turnSummary(latest) : null,
+            runtime: runtimeFacts,
+        },
+    });
+}
+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: true,
+    });
+}
+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: true,
+        });
+        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) {
+        const mapped = mapReopenSessionFailure({
+            code: result.code,
+            message: result.message,
+        });
+        sendJson(res, mapped.status, {
+            ok: false,
+            error: { code: mapped.code, message: mapped.message },
+        });
+        return;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        sessionId,
+        reopened: true,
+        sessionFile: result.handle.sessionFile,
+        model: result.handle.model,
+        activeTools: result.handle.activeTools,
+        hasBash: true,
+    });
+}
+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) {
+            const mapped = mapReopenSessionFailure({
+                code: reopen.code,
+                message: reopen.message,
+            });
+            sendJson(res, mapped.status, {
+                ok: false,
+                error: { code: mapped.code, message: mapped.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) {
+        if (createdTurn.code === "REQUEST_ID_REUSE_CONFLICT") {
+            sendJson(res, 409, {
+                ok: false,
+                accepted: false,
+                error: {
+                    code: createdTurn.code,
+                    message: createdTurn.message,
+                },
+            });
+            return;
+        }
+        sendJson(res, 409, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "TURN_ACTIVE",
+                message: "上一轮仍在运行，已返回当前 activeTurn；请重新连接或稍后再试。",
+            },
+            activeTurn: turnSummary(createdTurn.activeTurn),
+        });
+        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");
+    let firstUserText;
+    try {
+        const outcome = await runChatTurn({
+            runtime: deps.runtime,
+            store: deps.store,
+            actionContext,
+            sessionId,
+            text,
+            images,
+            signal: ac.signal,
+            onUserMessagePersisted: (record) => {
+                const users = record.messages.filter((message) => message.role === "user");
+                if (users.length !== 1)
+                    return;
+                firstUserText = users[0]?.text;
+                const placeholder = shouldEmitPlaceholder(record);
+                if (!placeholder)
+                    return;
+                const persisted = emitSessionTitle(deps, sessionId, turnId, placeholder);
+                if (!res.writableEnded)
+                    writeChatSse(res, persisted);
+            },
+            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) {
+            ensureAgentEndEvent(deps, sessionId, turnId);
+            deps.events.setTurnState(sessionId, turnId, "aborted", {
+                code: "CLIENT_ABORTED",
+                message: "client disconnected before turn settled",
+            });
+        }
+        else {
+            ensureAgentEndEvent(deps, sessionId, turnId);
+            deps.events.setTurnState(sessionId, turnId, outcome.ok ? "settled" : "failed", outcome.error);
+            if (outcome.ok && firstUserText)
+                scheduleAutomaticTitle(deps, { sessionId, turnId, firstUserText });
+        }
+    }
+    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);
+        ensureAgentEndEvent(deps, sessionId, turnId);
+        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,
+            accepted: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    let body;
+    try {
+        body = await readJsonBody(req);
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    const text = typeof body.text === "string" ? body.text.trim() : "";
+    const clientRequestId = typeof body.clientRequestId === "string" && body.clientRequestId.trim()
+        ? body.clientRequestId.trim()
+        : undefined;
+    let images;
+    try {
+        images = parseChatImages(body.images);
+    }
+    catch (error) {
+        sendJson(res, 400, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "INVALID_ATTACHMENT",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    if (!text) {
+        sendJson(res, 400, {
+            ok: false,
+            accepted: 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,
+                accepted: 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) {
+            const mapped = mapReopenSessionFailure({
+                code: reopen.code,
+                message: reopen.message,
+            });
+            sendJson(res, mapped.status, {
+                ok: false,
+                accepted: false,
+                error: { code: mapped.code, message: mapped.message },
+            });
+            return;
+        }
+    }
+    const actionContext = deps.runtime.actionContext;
+    if (!actionContext) {
+        sendJson(res, 503, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "CHAT_NO_ACTION_CONTEXT",
+                message: "Chat runtime has no operator action context wired",
+            },
+        });
+        return;
+    }
+    const payloadHash = hashChatTurnPayload({ text, images });
+    const created = deps.events.createTurn(sessionId, {
+        clientRequestId,
+        payloadHash,
+    });
+    if (!created.ok) {
+        if (created.code === "REQUEST_ID_REUSE_CONFLICT") {
+            sendJson(res, 409, {
+                ok: false,
+                accepted: false,
+                error: {
+                    code: created.code,
+                    message: created.message,
+                },
+            });
+            return;
+        }
+        sendJson(res, 409, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "TURN_ACTIVE",
+                message: "上一轮仍在运行，已返回当前 activeTurn；请重新连接或稍后再试。",
+            },
+            activeTurn: turnSummary(created.activeTurn),
+        });
+        return;
+    }
+    const turn = created.turn;
+    // Idempotent retry of an already-accepted request: return the same Turn and
+    // never re-run the prompt (even if it already finished).
+    if (created.idempotent) {
+        sendJson(res, 202, {
+            ok: true,
+            accepted: true,
+            idempotent: true,
+            turnId: turn.turnId,
+            ordinal: turn.ordinal,
+            state: turn.state,
+            turn: turnSummary(turn),
+        });
+        return;
+    }
+    const controller = new AbortController();
+    const execution = deps.turnExecutions?.register({
+        sessionId,
+        turnId: turn.turnId,
+        clientRequestId,
+        controller,
+    });
+    deps.events.setTurnState(sessionId, turn.turnId, "running");
+    const running = deps.events.getTurn(sessionId, turn.turnId) ?? {
+        ...turn,
+        state: "running",
+    };
+    sendJson(res, 202, {
+        ok: true,
+        accepted: true,
+        idempotent: false,
+        turnId: running.turnId,
+        ordinal: running.ordinal,
+        state: running.state,
+        turn: turnSummary(running),
+    });
+    // Deliberately detached from the request lifecycle: closing the POST
+    // response cannot abort the prompt; clients follow GET /events instead.
+    // Abort ownership lives in the execution registry (real Stop path).
+    void (async () => {
+        const { runChatTurn } = await import("./session-store.js");
+        let firstUserText;
+        let terminalState = "failed";
+        let terminalError;
+        try {
+            const outcome = await runChatTurn({
+                runtime: deps.runtime,
+                store: deps.store,
+                actionContext,
+                sessionId,
+                text,
+                images,
+                signal: controller.signal,
+                onUserMessagePersisted: (record) => {
+                    const users = record.messages.filter((message) => message.role === "user");
+                    if (users.length !== 1)
+                        return;
+                    firstUserText = users[0]?.text;
+                    const placeholder = shouldEmitPlaceholder(record);
+                    if (placeholder)
+                        emitSessionTitle(deps, sessionId, turn.turnId, placeholder);
+                },
+                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);
+                },
+            });
+            ensureAgentEndEvent(deps, sessionId, turn.turnId);
+            if (controller.signal.aborted) {
+                terminalState = "aborted";
+                terminalError = {
+                    code: "CLIENT_ABORTED",
+                    message: "turn aborted by client",
+                };
+                deps.events.setTurnState(sessionId, turn.turnId, "aborted", terminalError);
+            }
+            else if (outcome.ok) {
+                terminalState = "settled";
+                deps.events.setTurnState(sessionId, turn.turnId, "settled");
+                if (firstUserText)
+                    scheduleAutomaticTitle(deps, {
+                        sessionId,
+                        turnId: turn.turnId,
+                        firstUserText,
+                    });
+            }
+            else {
+                terminalState = "failed";
+                terminalError = outcome.error;
+                deps.events.setTurnState(sessionId, turn.turnId, "failed", outcome.error);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (controller.signal.aborted) {
+                terminalState = "aborted";
+                terminalError = {
+                    code: "CLIENT_ABORTED",
+                    message: "turn aborted by client",
+                };
+                ensureAgentEndEvent(deps, sessionId, turn.turnId);
+                deps.events.setTurnState(sessionId, turn.turnId, "aborted", terminalError);
+            }
+            else {
+                terminalState = "failed";
+                terminalError = { code: "CHAT_TURN_FAILED", message };
+                deps.events.append(sessionId, turn.turnId, {
+                    kind: "error",
+                    data: { message },
+                });
+                ensureAgentEndEvent(deps, sessionId, turn.turnId);
+                deps.events.setTurnState(sessionId, turn.turnId, "failed", terminalError);
+            }
+        }
+        finally {
+            execution?.resolveCompletion({
+                ok: terminalState === "settled",
+                state: terminalState,
+                error: terminalError,
+            });
+            deps.turnExecutions?.clear(sessionId, turn.turnId);
+        }
+    })();
+}
+/** Real server-side abort: invokes Pi session.abort via the execution registry. */
+export async function handleAbortChatTurn(req, res, deps, sessionId, turnId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, {
+            ok: false,
+            accepted: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    const turn = deps.events.getTurn(sessionId, turnId);
+    if (!turn) {
+        sendJson(res, 404, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "NOT_FOUND",
+                message: `chat turn not found: ${turnId}`,
+            },
+        });
+        return;
+    }
+    if (isTerminalTurnState(turn.state)) {
+        sendJson(res, 200, {
+            ok: true,
+            accepted: true,
+            idempotent: true,
+            turn: turnSummary(turn),
+        });
+        return;
+    }
+    const execution = deps.turnExecutions?.get(sessionId, turnId);
+    if (!execution) {
+        // Active durable Turn without process ownership (restart orphan / detached).
+        const closed = deps.events.setTurnState(sessionId, turnId, "failed", {
+            code: "CHAT_TURN_OWNER_LOST",
+            message: "turn ownership lost; cannot abort a turn this process does not own",
+        });
+        sendJson(res, 409, {
+            ok: false,
+            accepted: false,
+            error: {
+                code: "CHAT_TURN_OWNER_LOST",
+                message: "turn ownership lost; cannot abort a turn this process does not own",
+            },
+            turn: closed ? turnSummary(closed) : turnSummary(turn),
+        });
+        return;
+    }
+    deps.events.markAbortRequested?.(sessionId, turnId);
+    if (!execution.controller.signal.aborted)
+        execution.controller.abort();
+    const waited = await (deps.turnExecutions?.waitForCompletion(sessionId, turnId, DEFAULT_ABORT_WAIT_MS) ?? Promise.resolve({ status: "missing" }));
+    if (waited.status === "completed") {
+        const finalTurn = deps.events.getTurn(sessionId, turnId) ??
+            {
+                ...turn,
+                state: waited.outcome.state,
+            };
+        sendJson(res, 200, {
+            ok: true,
+            accepted: true,
+            idempotent: false,
+            turn: turnSummary(finalTurn),
+        });
+        return;
+    }
+    // Timeout or missing completion: keep non-terminal; client reconciles via /state.
+    const pending = deps.events.getTurn(sessionId, turnId) ?? turn;
+    sendJson(res, 202, {
+        ok: false,
+        accepted: false,
+        error: {
+            code: "TURN_ABORT_PENDING",
+            message: "abort requested; turn has not yet reached a terminal state",
+        },
+        turn: turnSummary(pending),
+    });
+}
+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 (`<epoch>:<seq>`). A previous
+    // Console boot/legacy cursor has a different prefix and receives snapshot.
+    const lastEventIdHeader = req.headers["last-event-id"];
+    const cursor = parseChatEventCursor(Array.isArray(lastEventIdHeader) ? lastEventIdHeader[0] : lastEventIdHeader);
+    const replay = deps.events.listFrom(sessionId, cursor);
+    let lastSeq = cursor.seq;
+    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.
+        // The frame carries the ring tail (latestEventId) so the client can resume
+        // the replayed snapshot with a fresh Last-Event-ID (recovery cursor).
+        const retained = deps.events.snapshot(sessionId);
+        writeChatSse(res, {
+            kind: "reconcile",
+            sessionId,
+            reason: replay.error === "CURSOR_EPOCH_MISMATCH"
+                ? "epoch_mismatch"
+                : "cursor_expired",
+            minSeq: replay.minSeq,
+            epoch: replay.epoch,
+            latestTurnId: deps.events.latestTurnId(sessionId),
+            latestEventId: retained.at(-1)?.eventId ?? null,
+        });
+        // Fall back to full retained snapshot so the client can re-render.
+        for (const ev of retained) {
+            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);
+        }
+    }
+    // Delimit retained replay from follow mode. The client uses this marker to
+    // ensure its sole GET /events consumer is ready before POST /turns (M4.1).
+    const retainedTail = deps.events.snapshot(sessionId).at(-1);
+    writeChatSse(res, {
+        kind: "stream_ready",
+        sessionId,
+        epoch: deps.events.epoch(sessionId),
+        latestEventId: retainedTail?.eventId ?? null,
+    });
+    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;
+        }
+    }
+    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 walked = await walkRepoFiles(deps.appData.repoRoot, {
+        skipSensitive: true,
+        maxFiles: 5000,
+        includeDirs: true,
+    });
+    const entries = walked
+        .filter((entry) => !isSensitivePath(entry.repoRelative) &&
+        (!q || entry.repoRelative.toLowerCase().includes(q)))
+        .sort((a, b) => {
+        const aDir = a.repoRelative.endsWith("/");
+        const bDir = b.repoRelative.endsWith("/");
+        if (aDir !== bDir)
+            return aDir ? -1 : 1;
+        return a.repoRelative.localeCompare(b.repoRelative);
+    })
+        .slice(0, 50)
+        .map((entry) => ({
+        path: entry.repoRelative,
+        isDir: entry.repoRelative.endsWith("/"),
+    }));
+    sendJson(res, 200, { ok: true, files: entries });
+}
+export async function handleChatCommands(res, deps, sessionId) {
+    try {
+        const listed = typeof deps.runtime.listSlashCommands === "function"
+            ? await deps.runtime.listSlashCommands(sessionId)
+            : { commands: [] };
+        // Partial single-source failures keep successful commands + compact warning (AC-3).
+        const commands = listed.commands ?? [];
+        const warning = typeof listed.warning === "string" && listed.warning.trim()
+            ? listed.warning.trim().slice(0, 160)
+            : undefined;
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+            ok: true,
+            commands,
+            ...(warning ? { warning } : {}),
+        }));
+    }
+    catch (error) {
+        // Whole-list / readiness failures stay fail-soft with empty commands + warning.
+        res.statusCode = 200;
+        res.setHeader("content-type", "application/json; charset=utf-8");
+        res.end(JSON.stringify({
+            ok: true,
+            commands: [],
+            warning: error instanceof Error ? error.message : "commands unavailable",
+        }));
+    }
+}
+export async function handleRuntimeContext(res, deps, sessionId) {
+    const ensured = await ensureActiveSession(deps, sessionId);
+    if (!ensured.ok) {
+        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+        return;
+    }
+    // AC-03: system prompt comes from the REAL Pi session (agent.state.systemPrompt
+    // fallback chain); resources come from that session's ResourceLoader. The raw
+    // prompt stays server-side; the browser only ever receives the scrubbed +
+    // length-limited projection. RF-02: a critical projection failure is 503
+    // PI_RUNTIME_UNAVAILABLE — never a 500 leak or a fake-empty context.
+    let snapshot;
+    try {
+        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId, {
+            includeRaw: true,
+        });
+    }
+    catch (error) {
+        if (sendRuntimeUnavailable(res, error))
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        sendJson(res, 503, {
+            ok: false,
+            error: {
+                code: "PI_RUNTIME_UNAVAILABLE",
+                message: `chat session not active: ${sessionId}`,
+            },
+        });
+        return;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        context: projectRuntimeContext({
+            systemPrompt: snapshot.systemPrompt.raw ?? "",
+            model: snapshot.selection.model
+                ? {
+                    provider: snapshot.selection.model.provider,
+                    modelId: snapshot.selection.model.id,
+                }
+                : undefined,
+            thinkingLevel: snapshot.selection.thinkingSelection === "auto"
+                ? snapshot.selection.effectiveThinkingLevel
+                : snapshot.selection.thinkingSelection,
+            activeTools: snapshot.activeTools,
+            contextFiles: snapshot.contextFiles,
+            skills: snapshot.skills,
+            extensions: snapshot.extensions,
+            packages: snapshot.packages.map((pkg) => ({
+                name: pkg.spec,
+                source: pkg.spec,
+                scope: pkg.scope,
+                enabled: pkg.enabled,
+                ...(pkg.version ? { version: pkg.version } : {}),
+                ...(pkg.path ? { path: pkg.path } : {}),
+                ...(pkg.cwd ? { cwd: pkg.cwd } : {}),
+                resolved: pkg.resolved,
+                diagnostics: pkg.diagnostics,
+            })),
+            diagnostics: snapshot.diagnostics,
+        }),
+    });
+}
+// Exported for the direct handler-boundary tests (trace binding for
+// vt-route-model-errors); router dispatch behavior is unchanged.
+export async function handleModels(req, res, deps, sessionId) {
+    // AC-01/AC-06: models (and model/thinking mutation) requests reuse the same
+    // activation path. A missing/reopen-failed runtime is a STRUCTURED error —
+    // never a fabricated empty model list.
+    const ensured = await ensureActiveSession(deps, sessionId);
+    if (!ensured.ok) {
+        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+        return;
+    }
+    try {
+        if ((req.method ?? "GET").toUpperCase() === "GET") {
+            let models;
+            try {
+                models = await deps.runtime.listModels(sessionId);
+            }
+            catch (error) {
+                // AC-06: a model-list failure is a STRUCTURED runtime error — never
+                // folded into a fake empty list.
+                sendJson(res, 503, {
+                    ok: false,
+                    error: {
+                        code: "PI_RUNTIME_UNAVAILABLE",
+                        message: error instanceof Error ? error.message : String(error),
+                    },
+                });
+                return;
+            }
+            sendJson(res, 200, {
+                ok: true,
+                models: models.map((model) => ({
+                    provider: model.provider,
+                    id: model.id ?? model.modelId ?? "",
+                    ...(model.name ? { name: model.name } : {}),
+                    hasCredentials: model.hasCredentials,
+                })),
+                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" && (body.thinkingLevel === "auto" || THINKING_LEVELS.includes(body.thinkingLevel))) {
+            const thinkingLevel = deps.runtime.applyThinkingLevel(sessionId, body.thinkingLevel);
+            updated = await deps.store.setRuntimeSelection(sessionId, thinkingLevel === "auto" ? {} : { thinkingLevel });
+        }
+        else {
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "provider/modelId or thinkingLevel is required" } });
+            return;
+        }
+        // Design §5: mutations return the fresh snapshot so the browser can
+        // atomically replace its state (revision increments server-side).
+        // RF-02: the mutation may already be applied server-side, but a failed
+        // snapshot read must surface as 503 PI_RUNTIME_UNAVAILABLE — NOT be
+        // folded into a 409 MODEL_SWITCH_FAILED (the frontend refresh path
+        // re-reads the snapshot to converge on the applied selection).
+        const snapshot = await deps.runtime.getRuntimeSnapshot(sessionId);
+        sendJson(res, 200, { ok: true, session: updated, snapshot });
+    }
+    catch (error) {
+        if (error instanceof RuntimeSnapshotUnavailableError) {
+            sendJson(res, 503, {
+                ok: false,
+                error: { code: error.code, message: error.message },
+            });
+            return;
+        }
+        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;
+}
+/**
+ * Unified session activation (design §2.1 / AC-01): models, runtime snapshot,
+ * reload and model/thinking mutation requests all flow through this path.
+ *
+ * - runtime already holds the session → ok;
+ * - only a persisted record exists → reopen from record.sessionFile;
+ * - no record / missing session file → 404 PI_SESSION_NOT_FOUND;
+ * - SDK reopen failure → 503 PI_RUNTIME_UNAVAILABLE.
+ *
+ * Never fabricates a fresh session or an empty model list.
+ */
+export async function ensureActiveSession(deps, sessionId) {
+    // Wait for create-path materialization before treating the session as missing.
+    if (typeof deps.runtime.ensureSessionReady === "function") {
+        try {
+            await deps.runtime.ensureSessionReady(sessionId);
+            if (deps.runtime.hasSession(sessionId))
+                return { ok: true };
+        }
+        catch (error) {
+            const code = error && typeof error === "object" && "code" in error
+                ? String(error.code ?? "")
+                : "";
+            if (code === "PI_SESSION_INIT_FAILED") {
+                return {
+                    ok: false,
+                    status: 503,
+                    code: "PI_SESSION_INIT_FAILED",
+                    message: error instanceof Error ? error.message : String(error),
+                };
+            }
+            // Not initializing / not found — fall through to reopen path.
+        }
+    }
+    if (deps.runtime.hasSession(sessionId))
+        return { ok: true };
+    const record = await deps.store.get(sessionId);
+    if (!record) {
+        return {
+            ok: false,
+            status: 404,
+            code: "PI_SESSION_NOT_FOUND",
+            message: `chat session not found: ${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) {
+        return { ok: false, ...mapReopenSessionFailure(reopened) };
+    }
+    return { ok: true };
+}
+/**
+ * PATCH /sessions/:id/skills/:resourceId/auto-invocation
+ * Persist repo-scoped preference, then try immediate reloadSession when idle.
+ * Busy sessions keep preferenceSaved=true and reloadApplied=false (no abort).
+ */
+export async function handleSkillAutoInvocation(req, res, deps, sessionId, resourceId) {
+    const gate = gateMutation(req, deps);
+    if (!gate.ok) {
+        sendJson(res, gate.status, {
+            ok: false,
+            error: { code: gate.code, message: gate.message },
+        });
+        return;
+    }
+    const ensured = await ensureActiveSession(deps, sessionId);
+    if (!ensured.ok) {
+        sendJson(res, ensured.status, {
+            ok: false,
+            error: { code: ensured.code, message: ensured.message },
+        });
+        return;
+    }
+    const id = resourceId.trim();
+    if (!id) {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: "resourceId is required",
+            },
+        });
+        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 (typeof body.autoInvocationEnabled !== "boolean") {
+        sendJson(res, 400, {
+            ok: false,
+            error: {
+                code: "INVALID_INPUT",
+                message: "autoInvocationEnabled boolean is required",
+            },
+        });
+        return;
+    }
+    const found = await deps.runtime.findSkillByResourceId(sessionId, id);
+    if (!found) {
+        sendJson(res, 404, {
+            ok: false,
+            error: {
+                code: "PI_SKILL_NOT_FOUND",
+                message: `skill resourceId not in current session inventory: ${id}`,
+            },
+        });
+        return;
+    }
+    const prefsPath = deps.appData.resourcePreferences;
+    if (!prefsPath) {
+        sendJson(res, 500, {
+            ok: false,
+            error: {
+                code: "PI_RESOURCE_PREFERENCES_WRITE_FAILED",
+                message: "resourcePreferences path is not configured",
+            },
+        });
+        return;
+    }
+    try {
+        await setSkillAutoInvocationPreference({
+            filePath: prefsPath,
+            resourceId: id,
+            autoInvocationEnabled: body.autoInvocationEnabled,
+        });
+    }
+    catch (error) {
+        if (error instanceof ResourcePreferencesError) {
+            const status = error.code === "PI_RESOURCE_PREFERENCES_MALFORMED" ? 500 : 500;
+            sendJson(res, status, {
+                ok: false,
+                error: { code: error.code, message: error.message },
+            });
+            return;
+        }
+        sendJson(res, 500, {
+            ok: false,
+            error: {
+                code: "PI_RESOURCE_PREFERENCES_WRITE_FAILED",
+                message: error instanceof Error ? error.message : String(error),
+            },
+        });
+        return;
+    }
+    const reload = await deps.runtime.reloadSession(sessionId);
+    if (!reload.ok) {
+        if (reload.code === "PI_SESSION_BUSY") {
+            // Preference is durable; do not abort the busy turn or pretend reload applied.
+            sendJson(res, 200, {
+                ok: true,
+                preferenceSaved: true,
+                reloadApplied: false,
+                error: { code: reload.code, message: reload.message },
+            });
+            return;
+        }
+        sendJson(res, reload.code === "PI_SESSION_NOT_FOUND" ? 404 : 500, {
+            ok: false,
+            preferenceSaved: true,
+            reloadApplied: false,
+            error: { code: reload.code, message: reload.message },
+        });
+        return;
+    }
+    let snapshot;
+    try {
+        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId);
+    }
+    catch (error) {
+        if (sendRuntimeUnavailable(res, error))
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        sendJson(res, 503, {
+            ok: false,
+            preferenceSaved: true,
+            reloadApplied: true,
+            error: {
+                code: "PI_RUNTIME_UNAVAILABLE",
+                message: `chat session not active after reload: ${sessionId}`,
+            },
+        });
+        return;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        preferenceSaved: true,
+        reloadApplied: true,
+        revision: reload.revision,
+        snapshot,
+    });
+}
+/**
+ * POST /sessions/:id/reload (AC-05 / AC-06): official session.reload() with
+ * structured busy/failure semantics. Never aborts, never silently queues.
+ */
+export async function handleReloadSession(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 ensured = await ensureActiveSession(deps, sessionId);
+    if (!ensured.ok) {
+        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+        return;
+    }
+    const result = await deps.runtime.reloadSession(sessionId);
+    if (!result.ok) {
+        const status = result.code === "PI_SESSION_NOT_FOUND"
+            ? 404
+            : result.code === "PI_SESSION_BUSY"
+                ? 409
+                : result.code === "PI_SESSION_INIT_FAILED"
+                    ? 503
+                    : 500;
+        sendJson(res, status, { ok: false, error: { code: result.code, message: result.message } });
+        return;
+    }
+    // RF-02: the reload succeeded, but a failed snapshot read is still a
+    // structured 503 — never a 200 with fake-empty resources.
+    let snapshot;
+    try {
+        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId);
+    }
+    catch (error) {
+        if (sendRuntimeUnavailable(res, error))
+            return;
+        throw error;
+    }
+    sendJson(res, 200, {
+        ok: true,
+        revision: result.revision,
+        snapshot,
+        resourceCounts: snapshot
+            ? {
+                skills: snapshot.skills.length,
+                extensions: snapshot.extensions.length,
+                packages: snapshot.packages.length,
+                contextFiles: snapshot.contextFiles.length,
+            }
+            : undefined,
+    });
+}
+/**
+ * GET /sessions/:id/runtime-snapshot (AC-01): the unified live snapshot.
+ */
+export async function handleRuntimeSnapshot(_res, res, deps, sessionId) {
+    const ensured = await ensureActiveSession(deps, sessionId);
+    if (!ensured.ok) {
+        sendJson(res, ensured.status, { ok: false, error: { code: ensured.code, message: ensured.message } });
+        return;
+    }
+    // RF-02: a critical snapshot projection failure is 503 PI_RUNTIME_UNAVAILABLE
+    // — never a 200 fake-empty snapshot.
+    let snapshot;
+    try {
+        snapshot = await deps.runtime.getRuntimeSnapshot(sessionId);
+    }
+    catch (error) {
+        if (sendRuntimeUnavailable(res, error))
+            return;
+        throw error;
+    }
+    if (!snapshot) {
+        sendJson(res, 503, {
+            ok: false,
+            error: { code: "PI_RUNTIME_UNAVAILABLE", message: `chat session not active: ${sessionId}` },
+        });
+        return;
+    }
+    sendJson(res, 200, { ok: true, snapshot });
+}
+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) {
+            const mapped = mapReopenSessionFailure({
+                code: reopened.code,
+                message: reopened.message,
+            });
+            sendJson(res, mapped.status, {
+                ok: false,
+                error: { code: mapped.code, message: mapped.message },
+            });
+            return;
+        }
+    }
+    let body = {};
+    try {
+        body = await readJsonBody(req);
+    }
+    catch {
+        sendJson(res, 400, {
+            ok: false,
+            error: { code: "INVALID_INPUT", message: "invalid json body" },
+        });
+        return;
+    }
+    const rawInstructions = typeof body.instructions === "string" ? body.instructions : undefined;
+    const customInstructions = rawInstructions?.trim() || undefined;
+    try {
+        const snapshot = await deps.runtime.compact(sessionId, customInstructions);
+        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) {
+        const classified = classifyChatCompactionFailure(error);
+        sendJson(res, classified.status, {
+            ok: false,
+            error: { code: classified.code, message: classified.message },
+        });
+    }
+}
+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 (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 skillAutoInvocation = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/skills\/([^/]+)\/auto-invocation$/);
+    if (method === "PATCH" && skillAutoInvocation) {
+        await handleSkillAutoInvocation(req, res, deps, decodeURIComponent(skillAutoInvocation[1]), decodeURIComponent(skillAutoInvocation[2]));
+        return true;
+    }
+    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|runtime-snapshot|models|model|reload|commands)$/);
+    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 === "runtime-snapshot" && method === "GET") {
+            await handleRuntimeSnapshot(req, 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;
+        }
+        if (route === "reload" && method === "POST") {
+            await handleReloadSession(req, res, deps, id);
+            return true;
+        }
+        if (route === "commands" && method === "GET") {
+            await handleChatCommands(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 sessionTurnAbort = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/turns\/([^/]+)\/abort$/);
+    if (method === "POST" && sessionTurnAbort) {
+        await handleAbortChatTurn(req, res, deps, decodeURIComponent(sessionTurnAbort[1]), decodeURIComponent(sessionTurnAbort[2]));
+        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 sessionState = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/state$/);
+    if (method === "GET" && sessionState) {
+        await handleGetChatSessionState(req, res, deps, decodeURIComponent(sessionState[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;