@tea-agent/loop-agent 0.33.7-beta.0 → 0.34.1

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

@@ -6,24 +6,23 @@
  *   GET  /sessions/:id          — fetch session metadata + messages
  *   POST /sessions/:id/prompt   — SSE stream: send a prompt, stream events
  *   GET  /sessions/:id/events   — SSE stream: (re)connect to live events
- *   GET  /capabilities          — Chat tool surface + instruction skills
+ *   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 { createHash } from "node:crypto";
 import { OPERATOR_CHAT_ALLOWED_TOOLS, OPERATOR_CHAT_DENIED_TOOLS, OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS, } from "./tools.js";
-import { OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS, OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS, OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS, composeInstructionSkillsPrompt, loadOperatorChatInstructionSkills, } from "./instruction-skills.js";
 import { buildModelCallableToolSchemas } from "./tool-adapter.js";
+import { cleanChatTitle } from "./session-store.js";
 import { projectChatToolEventPayload, projectCompactSnapshot, } from "./chat-event-store.js";
-import { THINKING_LEVELS, composeOperatorChatSystemPrompt, } from "./pi-runtime.js";
+import { THINKING_LEVELS, RuntimeSnapshotUnavailableError, } from "./pi-runtime.js";
 import { ComposerDraftStore } from "./composer-draft-store.js";
 import { walkRepoFiles } from "./repo-walk.js";
 import { isSensitivePath, scrubSecrets } from "./explore-tools.js";
 import { listRepoDirectory, readRepoPreview, RepoBrowserError, } from "./repo-browser.js";
 import { projectRuntimeContext } from "./runtime-context.js";
-import { patchModelsConfig, readModelsConfig, readPackageInventory, readSkillPreferences, writeSkillPreferences, } from "./pi-console-config.js";
+import { 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";
@@ -33,9 +32,24 @@ import { ContractApplyReceiptStore } from "./contract-apply-receipt-store.js";
 import { projectTaskContext } from "./context-panel.js";
 import { contractApplyPayloadHash, issueHumanGateToken, verifyHumanGateToken, } from "../human-gate-token.js";
 import { sendJson } from "../routes.js";
-import { openSseResponse, parseLastEventId, writeSseEvent, } from "../operation-sse.js";
+import { openSseResponse, writeSseEvent } from "../operation-sse.js";
+/** 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 (<sessionId>:<seq>); write
+    // 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`);
@@ -93,21 +107,65 @@ function turnEventToStorePartial(event) {
             return undefined;
     }
 }
-/** Guarantee a durable terminal event for a turn that ended without the SDK
- *  emitting agent_end (client abort, pre-prompt persistence failure, runtime
- *  error). Without it, a reconnect replay stops at agent_start and the UI stays
- *  streaming forever. Idempotent: normal settled turns already carry the SDK's
- *  agent_end in the ring, so they are skipped. */
+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 already = deps.events
-        .snapshot(sessionId)
-        .some((event) => event.turnId === turnId && event.kind === "agent_end");
-    if (!already) {
+    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 = [];
@@ -198,9 +256,53 @@ function gateMutation(req, deps) {
     }
     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();
-    const skills = await loadOperatorChatInstructionSkills(deps.skillsDir);
     sendJson(res, 200, {
         ok: true,
         schemaVersion: 1,
@@ -208,18 +310,6 @@ export async function handleChatCapabilities(_req, res, deps) {
         deniedTools: OPERATOR_CHAT_DENIED_TOOLS,
         deniedOperatorActions: OPERATOR_CHAT_DENIED_OPERATOR_ACTIONS,
         tools: toolSchemas,
-        instructionSkills: {
-            allowed: OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS,
-            loaded: skills.loaded.map((s) => ({
-                name: s.name,
-                description: s.description,
-                charCount: s.charCount,
-            })),
-            failures: skills.failures,
-            skipped: skills.skipped,
-            promptFragmentCharCount: composeInstructionSkillsPrompt(skills.loaded)
-                .length,
-        },
         // ADR 0011: full Pi tools including bash are default-active.
         hasBash: true,
     });
@@ -276,10 +366,8 @@ export async function handleCreateChatSession(req, res, deps) {
         return;
     }
     try {
-        deps.runtime.setDisabledInstructionSkills(await readSkillPreferences(deps.appData));
-        const snapshot = snapshotInput === undefined
-            ? undefined
-            : projectCompactSnapshot(snapshotInput);
+        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
@@ -288,7 +376,18 @@ export async function handleCreateChatSession(req, res, deps) {
                 }
                 : {}),
         });
-        await deps.store.create({
+        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,
@@ -299,13 +398,33 @@ export async function handleCreateChatSession(req, res, deps) {
                 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) {
@@ -415,8 +534,17 @@ export async function handleBranchChatSession(req, res, deps, sessionId) {
                 sessionId,
                 sessionFile: record.sessionFile,
             });
-            if (!reopened.ok)
-                throw new Error(reopened.message);
+            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)
@@ -491,6 +619,7 @@ export async function handleGetChatSession(_req, res, deps, sessionId) {
     const lastEvent = snapshot.at(-1);
     sendJson(res, 200, {
         ok: true,
+        eventEpoch: deps.events.epoch(sessionId),
         session: {
             ...record,
             composerDraft,
@@ -618,9 +747,13 @@ export async function handleReopenChatSession(req, res, deps, sessionId) {
             : {}),
     });
     if (!result.ok) {
-        sendJson(res, 409, {
+        const mapped = mapReopenSessionFailure({
+            code: result.code,
+            message: result.message,
+        });
+        sendJson(res, mapped.status, {
             ok: false,
-            error: { code: result.code, message: result.message },
+            error: { code: mapped.code, message: mapped.message },
         });
         return;
     }
@@ -703,9 +836,13 @@ export async function handleChatPrompt(req, res, deps, sessionId) {
                 : {}),
         });
         if (!reopen.ok) {
-            sendJson(res, 409, {
+            const mapped = mapReopenSessionFailure({
+                code: reopen.code,
+                message: reopen.message,
+            });
+            sendJson(res, mapped.status, {
                 ok: false,
-                error: { code: reopen.code, message: reopen.message },
+                error: { code: mapped.code, message: mapped.message },
             });
             return;
         }
@@ -754,6 +891,7 @@ export async function handleChatPrompt(req, res, deps, sessionId) {
     });
     // Lazily import to avoid circular module load.
     const { runChatTurn } = await import("./session-store.js");
+    let firstUserText;
     try {
         const outcome = await runChatTurn({
             runtime: deps.runtime,
@@ -763,6 +901,18 @@ export async function handleChatPrompt(req, res, deps, 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,
@@ -813,6 +963,8 @@ export async function handleChatPrompt(req, res, deps, sessionId) {
         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) {
@@ -917,9 +1069,13 @@ export async function handleCreateChatTurn(req, res, deps, sessionId) {
                 : {}),
         });
         if (!reopen.ok) {
-            sendJson(res, 409, {
+            const mapped = mapReopenSessionFailure({
+                code: reopen.code,
+                message: reopen.message,
+            });
+            sendJson(res, mapped.status, {
                 ok: false,
-                error: { code: reopen.code, message: reopen.message },
+                error: { code: mapped.code, message: mapped.message },
             });
             return;
         }
@@ -958,6 +1114,7 @@ export async function handleCreateChatTurn(req, res, deps, sessionId) {
     // response cannot abort the prompt; clients follow GET /events instead.
     void (async () => {
         const { runChatTurn } = await import("./session-store.js");
+        let firstUserText;
         try {
             const outcome = await runChatTurn({
                 runtime: deps.runtime,
@@ -966,6 +1123,15 @@ export async function handleCreateChatTurn(req, res, deps, sessionId) {
                 sessionId,
                 text,
                 images,
+                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,
@@ -982,6 +1148,8 @@ export async function handleCreateChatTurn(req, res, deps, sessionId) {
             });
             ensureAgentEndEvent(deps, sessionId, turn.turnId);
             deps.events.setTurnState(sessionId, turn.turnId, outcome.ok ? "settled" : "failed", outcome.error);
+            if (outcome.ok && firstUserText)
+                scheduleAutomaticTitle(deps, { sessionId, turnId: turn.turnId, firstUserText });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -1025,23 +1193,31 @@ export async function handleChatEventsStream(req, res, deps, sessionId) {
     }
     await deps.operationLinker.recoverSession(sessionId);
     openSseResponse(res);
-    // Resume from the client's last seen eventId (Last-Event-ID header, T04).
+    // 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 afterSeq = parseLastEventId(Array.isArray(lastEventIdHeader) ? lastEventIdHeader[0] : lastEventIdHeader);
-    const replay = deps.events.listFrom(sessionId, afterSeq);
-    let lastSeq = afterSeq;
+    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: "cursor_expired",
+            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 deps.events.snapshot(sessionId)) {
+        for (const ev of retained) {
             writeChatSse(res, ev);
             lastSeq = Math.max(lastSeq, ev.seq);
         }
@@ -1052,6 +1228,15 @@ export async function handleChatEventsStream(req, res, deps, sessionId) {
             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;
@@ -1211,47 +1396,6 @@ async function handlePiConfig(req, res, deps, resource) {
             });
             return;
         }
-        if (req.method === "GET") {
-            const disabledNames = await readSkillPreferences(deps.appData);
-            const loaded = await loadOperatorChatInstructionSkills(deps.skillsDir);
-            sendJson(res, 200, {
-                ok: true,
-                data: {
-                    allowed: OPERATOR_CHAT_ALLOWED_INSTRUCTION_SKILLS.map((name) => {
-                        const skill = loaded.loaded.find((item) => item.name === name);
-                        return {
-                            name,
-                            description: skill?.description ?? "",
-                            contentHash: skill
-                                ? createHash("sha256").update(skill.bodyText).digest("hex")
-                                : undefined,
-                        };
-                    }),
-                    conditional: OPERATOR_CHAT_WORKFLOW_CONDITIONAL_SKILLS,
-                    denied: OPERATOR_CHAT_DENIED_INSTRUCTION_SKILLS,
-                    disabledNames,
-                },
-            });
-        }
-        else {
-            const gate = gateMutation(req, deps);
-            if (!gate.ok) {
-                sendJson(res, gate.status, {
-                    ok: false,
-                    error: { code: gate.code, message: gate.message },
-                });
-                return;
-            }
-            const body = await readJsonBody(req);
-            const disabledNames = await writeSkillPreferences(deps.appData, Array.isArray(body.disabledNames)
-                ? body.disabledNames.filter((name) => typeof name === "string")
-                : []);
-            deps.runtime.setDisabledInstructionSkills(disabledNames);
-            sendJson(res, 200, {
-                ok: true,
-                data: { disabledNames, appliesTo: "new-sessions" },
-            });
-        }
     }
     catch (error) {
         const failure = error;
@@ -1279,94 +1423,148 @@ async function handleChatFiles(res, deps, sessionId, query) {
         .map((path) => ({ path }));
     sendJson(res, 200, { ok: true, files });
 }
-async function handleRuntimeContext(res, deps, sessionId) {
-    const record = await deps.store.get(sessionId);
-    if (!record) {
-        sendJson(res, 404, { ok: false });
+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;
     }
-    const skills = await loadOperatorChatInstructionSkills(deps.skillsDir);
-    const selection = deps.runtime.getRuntimeSelection(sessionId);
-    const skillFragment = composeInstructionSkillsPrompt(skills.loaded);
-    const systemPrompt = composeOperatorChatSystemPrompt({ skillFragment });
     sendJson(res, 200, {
         ok: true,
         context: projectRuntimeContext({
-            systemPrompt,
-            skills: skills.loaded.map((skill) => ({
-                name: skill.name,
-                description: skill.description,
-                charCount: skill.charCount,
-                bodyText: skill.bodyText,
+            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,
             })),
-            model: selection.model ??
-                (record.modelProvider && record.modelId
-                    ? { provider: record.modelProvider, modelId: record.modelId }
-                    : undefined),
-            thinkingLevel: selection.thinkingLevel ?? record.thinkingLevel,
-            activeTools: selection.activeTools,
+            diagnostics: snapshot.diagnostics,
         }),
     });
 }
-async function handleModels(req, res, deps, sessionId) {
-    if (!(await requireChatSession(res, deps, sessionId)))
+// 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: await deps.runtime.listModels(sessionId),
+                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 },
-            });
+            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,
-            });
+            const model = await deps.runtime.applyModel(sessionId, { provider: body.provider, modelId: body.modelId });
+            updated = await deps.store.setRuntimeSelection(sessionId, { modelProvider: model.provider, modelId: model.modelId });
         }
-        else if (typeof body.thinkingLevel === "string" &&
-            THINKING_LEVELS.includes(body.thinkingLevel)) {
+        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,
-            });
+            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",
-                },
-            });
+            sendJson(res, 400, { ok: false, error: { code: "INVALID_INPUT", message: "provider/modelId or thinkingLevel is required" } });
             return;
         }
-        sendJson(res, 200, { ok: true, session: updated });
+        // 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) {
-        sendJson(res, 409, {
-            ok: false,
-            error: {
-                code: "MODEL_SWITCH_FAILED",
-                message: error instanceof Error ? error.message : String(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) {
@@ -1381,6 +1579,144 @@ async function requireChatSession(res, deps, 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 };
+}
+/**
+ * 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) {
@@ -2060,9 +2396,13 @@ export async function handleChatCompact(req, res, deps, sessionId) {
                 : {}),
         });
         if (!reopened.ok) {
-            sendJson(res, 409, {
+            const mapped = mapReopenSessionFailure({
+                code: reopened.code,
+                message: reopened.message,
+            });
+            sendJson(res, mapped.status, {
                 ok: false,
-                error: { code: reopened.code, message: reopened.message },
+                error: { code: mapped.code, message: mapped.message },
             });
             return;
         }
@@ -2153,16 +2493,6 @@ export async function handleChatRequest(req, res, deps, pathname) {
         await handlePiConfig(req, res, deps, "packages");
         return true;
     }
-    if (pathname === "/api/operator/v1/chat/instruction-skills" &&
-        method === "GET") {
-        await handlePiConfig(req, res, deps, "skills");
-        return true;
-    }
-    if (pathname === "/api/operator/v1/chat/instruction-skills/preferences" &&
-        method === "PUT") {
-        await handlePiConfig(req, res, deps, "skills");
-        return true;
-    }
     if (method === "GET" && pathname === "/api/operator/v1/chat/capabilities") {
         await handleChatCapabilities(req, res, deps);
         return true;
@@ -2221,7 +2551,7 @@ export async function handleChatRequest(req, res, deps, pathname) {
         await handleMutationHumanGate(req, res, deps, decodeURIComponent(mutationHumanGate[1]));
         return true;
     }
-    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|models|model)$/);
+    const m4Route = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/(draft|files|runtime-context|runtime-snapshot|models|model|reload)$/);
     if (m4Route) {
         const id = decodeURIComponent(m4Route[1]);
         const route = m4Route[2];
@@ -2237,6 +2567,10 @@ export async function handleChatRequest(req, res, deps, pathname) {
             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;
@@ -2245,6 +2579,10 @@ export async function handleChatRequest(req, res, deps, pathname) {
             await handleModels(req, res, deps, id);
             return true;
         }
+        if (route === "reload" && method === "POST") {
+            await handleReloadSession(req, res, deps, id);
+            return true;
+        }
     }
     const sessionMainline = pathname.match(/^\/api\/operator\/v1\/chat\/sessions\/([^/]+)\/branch\/mainline$/);
     if (method === "POST" && sessionMainline) {