@yadsh/dsh-qa-surface 0.1.1 → 0.3.0

package/lib/client/QaSessionController.js

@@ -1,80 +1,85 @@
-import { projectTranscript } from "./QaTranscriptAdapter.js";
-const EMPTY_STATE = Object.freeze({
-    phase: "idle",
-    sessionId: null,
-    messages: Object.freeze([]),
-    error: null,
-    canSend: false,
-    canStop: false,
-});
-function waitFor(source, predicate, timeoutMs) {
-    const current = source.getSnapshot();
-    if (predicate(current))
-        return Promise.resolve(current);
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const timeout = {};
-        let unsubscribe = () => undefined;
-        const finish = (value) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timeout.id !== undefined)
-                clearTimeout(timeout.id);
-            unsubscribe();
-            resolve(value);
-        };
-        unsubscribe = source.subscribe(() => {
-            const next = source.getSnapshot();
-            if (predicate(next))
-                finish(next);
-        });
-        // Tolerate observable implementations that notify synchronously while a
-        // subscriber is being installed, and close that subscription afterward.
-        if (settled) {
-            unsubscribe();
-            return;
-        }
-        const afterSubscribe = source.getSnapshot();
-        if (predicate(afterSubscribe)) {
-            finish(afterSubscribe);
-            return;
-        }
-        timeout.id = setTimeout(() => {
-            if (settled)
-                return;
-            settled = true;
-            unsubscribe();
-            reject(new Error("Timed out waiting for the DSH runtime."));
-        }, timeoutMs);
-    });
+function bytesToBase64(bytes) {
+    let binary = "";
+    for (let index = 0; index < bytes.length; index += 0x8000) {
+        binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000));
+    }
+    return btoa(binary);
 }
-/** The only module that couples QA behavior to DSH Session/client APIs. */
+import { QaPolicyAttestationError } from "./attestation.js";
+import { QaChatIndex } from "./chat-index.js";
+import { SessionAssetRepository } from "./session-assets.js";
+import { createQaSession } from "./create-session.js";
+import { attestQaPolicy } from "./session-admission.js";
+import { QaHostSourceBridge } from "./session-sources.js";
+import { QA_SESSION_IDLE_STATE } from "./types.js";
+import { waitFor } from "./wait-for.js";
+import { QA_REGENERATE_MARKER } from "./QaTranscriptAdapter.js";
+import { projectBoundSessionState } from "./project-session-state.js";
+import { projectTurnSources } from "./turn-sources.js";
+const CONFIGURATION_ERROR = "Настройки помощника недоступны.";
+/**
+ * The only module that couples QA behavior to DSH Session/client APIs. It owns
+ * the chat lifecycle state machine; the observable wait, browser-local chat
+ * bookkeeping and policy-attestation details live in their own modules.
+ */
 export class QaSessionController {
     listeners = new Set();
     sessions;
     api;
+    conversation;
     connection;
     config;
-    storage;
+    secureSessionRemote;
+    sourceApi;
+    chats;
+    accounts;
+    /** Per-chat attachment URL cache; blob URLs die with the chat binding. */
+    assets = new SessionAssetRepository();
     timeoutMs;
-    state = EMPTY_STATE;
+    streamIntervalMs;
+    state = QA_SESSION_IDLE_STATE;
     session;
+    conversationBinding;
     unsubscribeSession;
+    unsubscribeChat;
     unsubscribeConnection;
     ensuring;
+    materializing;
     operationError = null;
     admissionPending = false;
+    policyReady = false;
+    drafting = false;
+    streamFlushTimer;
+    /** The chat session to return to when a subagent view closes. */
+    chatSessionId = null;
+    viewingSubagent = null;
     connectedOnce;
     disposed = false;
     generation = 0;
+    chatsRevision = 0;
+    /** Host-side provenance of the bound chat, merged into the projection. */
+    hostSources;
     constructor(options) {
         this.sessions = options.sessions;
         this.api = options.api;
+        this.conversation = options.conversation;
         this.connection = options.connection;
         this.config = options.config;
-        this.storage = options.storage;
+        this.secureSessionRemote = options.secureSession;
+        this.sourceApi =
+            options.sourceApi ??
+                {
+                    sources: async () => ({ ok: true, value: [] }),
+                    readSourceFile: async () => ({
+                        ok: false,
+                        error: "unavailable",
+                    }),
+                };
+        this.chats = new QaChatIndex(options.storage, `${options.config.session.storageKey}:v1:${options.config.route.path}`);
+        this.accounts = options.accounts;
+        this.hostSources = new QaHostSourceBridge(this.sourceApi, () => this.accounts?.token() ?? "");
         this.timeoutMs = options.timeoutMs ?? 15_000;
+        this.streamIntervalMs = options.streamIntervalMs ?? 66;
         this.connectedOnce = this.connection.getSnapshot() !== undefined;
         this.unsubscribeConnection = this.connection.subscribe(() => {
             if (this.connection.getSnapshot() !== undefined)
@@ -97,25 +102,65 @@ export class QaSessionController {
         this.ensuring = operation;
         return operation;
     }
-    async send(text) {
+    async send(text, images = []) {
         const prompt = text.trim();
-        if (prompt === "" || this.session === undefined || !this.state.canSend) {
+        if ((prompt === "" && images.length === 0) || !this.state.canSend) {
             return false;
         }
         if (prompt.startsWith("/")) {
-            this.operationError =
-                "Slash commands are not available in this assistant view.";
+            this.operationError = "Команды со слешем недоступны в режиме помощника.";
             this.publish();
             return false;
         }
+        if (this.session === undefined) {
+            // A draft chat materializes its session only now: nothing was created
+            // when the user pressed "New chat", so the first prompt pays for it.
+            if (!this.drafting || this.materializing !== undefined)
+                return false;
+            if (!(await this.materializeDraft()) || this.session === undefined) {
+                return false;
+            }
+        }
         this.operationError = null;
+        const step = await this.attestPolicy();
+        if (step.kind === "stale") {
+            // The user moved to another chat while the proof was pending; that
+            // binding attests through its own flow and must not receive a prompt
+            // meant for the old one.
+            return false;
+        }
+        let attestedId = step.kind === "ok" ? step.sessionId : null;
+        if (attestedId === null) {
+            attestedId = await this.recoverForSend();
+            if (attestedId === null)
+                return false;
+        }
+        // Nothing can interleave between the last await and here, so matching the
+        // attested id proves the prompt rides exactly the session it proved.
+        const target = this.session;
+        if (this.disposed ||
+            target === undefined ||
+            String(target.sessionId) !== attestedId) {
+            return false;
+        }
         this.admissionPending = true;
         this.publish();
         try {
-            const result = await this.session.prompt([{ type: "text", text: prompt }], "queue");
+            const content = [
+                ...(prompt === "" ? [] : [{ type: "text", text: prompt }]),
+                ...images.map((image) => ({
+                    type: "image",
+                    mediaType: image.mediaType,
+                    data: image.data,
+                    name: image.name,
+                })),
+            ];
+            const result = await target.prompt(content, "queue");
+            if (this.session !== target)
+                return false;
             if (!result.ok) {
                 this.admissionPending = false;
-                this.operationError = "Your message could not be sent.";
+                this.operationError = "Не удалось отправить сообщение.";
                 this.publish();
                 return false;
             }
@@ -125,27 +170,52 @@ export class QaSessionController {
         catch (error) {
             this.admissionPending = false;
             console.error("dsh-qa-surface: prompt failed", error);
-            this.operationError = "Your message could not be sent.";
-            this.publish();
+            if (this.session === target) {
+                this.operationError = "Не удалось отправить сообщение.";
+                this.publish();
+            }
             return false;
         }
     }
+    /**
+     * Ask for a fresh variant of the previous answer. The session has no
+     * truncation seam, so this sends the hidden regeneration instruction as an
+     * ordinary prompt: the model produces a follow-up turn, the projection
+     * hides the marker message, and the consecutive turns read as variants of
+     * the original question (switched in the surface).
+     */
+    async regenerate() {
+        return this.send(QA_REGENERATE_MARKER);
+    }
     async stop() {
-        if (this.session === undefined || !this.state.canStop)
+        const target = this.session;
+        if (target === undefined || !this.state.canStop)
             return;
         try {
-            const result = await this.session.cancel();
+            const result = await target.cancel();
+            if (this.session !== target)
+                return;
             if (!result.ok)
-                this.operationError = "The response could not be stopped.";
+                this.operationError = "Не удалось остановить ответ.";
         }
         catch (error) {
             console.error("dsh-qa-surface: stop failed", error);
-            this.operationError = "The response could not be stopped.";
+            if (this.session !== target)
+                return;
+            this.operationError = "Не удалось остановить ответ.";
         }
         this.publish();
     }
-    async reset() {
-        if (this.config.session.policy === "fixed")
+    /**
+     * Enter the "new chat" draft: show an empty composer without creating any
+     * session. Nothing appears in the chat list and no Host session is spent
+     * until the first prompt is actually sent, which materializes the session
+     * lazily ({@link materializeDraft}). Fixed-policy deployments cannot draft.
+     */
+    async startDraft() {
+        if (this.disposed ||
+            this.config.session.policy === "fixed" ||
+            (this.config.lockdown.enabled && !this.config.lockdown.allowSessionReset))
             return;
         const previous = this.session;
         if (previous?.getSnapshot().running === true) {
@@ -153,44 +223,253 @@ export class QaSessionController {
                 await previous.cancel();
             }
             catch (error) {
-                console.error("dsh-qa-surface: stop before reset failed", error);
+                console.error("dsh-qa-surface: stop before draft failed", error);
             }
         }
+        this.drafting = true;
+        this.unbind();
+        this.operationError = null;
+        this.admissionPending = false;
+        this.policyReady = false;
+        this.state = {
+            ...QA_SESSION_IDLE_STATE,
+            chatsRevision: this.chatsRevision,
+        };
+        this.publish();
+    }
+    /**
+     * Turn the current draft into a real attested session. Runs inside the
+     * send flow; concurrent sends share one materialization. A refusal here is
+     * reported at once — a fresh session's first attestation is the
+     * deployment's only chance to learn the reason.
+     */
+    materializeDraft() {
+        if (this.materializing !== undefined)
+            return this.materializing;
         const operation = ++this.generation;
+        const attempt = (async () => {
+            try {
+                await this.waitForConnection();
+                const id = await createQaSession({
+                    sessions: this.sessions,
+                    api: this.api,
+                    config: this.config,
+                });
+                if (this.disposed || operation !== this.generation)
+                    return false;
+                await this.bind(id);
+                if (this.disposed || operation !== this.generation)
+                    return false;
+                this.drafting = false;
+                if (this.config.session.policy === "browser-persistent") {
+                    this.chats.saveActive(id);
+                }
+                return true;
+            }
+            catch (error) {
+                if (this.disposed || operation !== this.generation)
+                    return false;
+                this.fail(this.operationError === CONFIGURATION_ERROR
+                    ? this.operationError
+                    : "Не удалось начать чат.", error);
+                return false;
+            }
+        })();
+        this.materializing = attempt;
+        this.publish();
+        // `attempt` never rejects: every failure path is caught and reports false.
+        void attempt.then(() => {
+            if (this.materializing === attempt)
+                this.materializing = undefined;
+        });
+        return attempt;
+    }
+    /**
+     * Open one of this browser's indexed chats. The id must be present in the
+     * host session list and pass policy attestation; an unknown id is forgotten
+     * from the index. Fixed-policy deployments cannot switch.
+     */
+    async switchTo(sessionId) {
+        if (this.disposed || this.config.session.policy === "fixed")
+            return;
+        if (this.session !== undefined &&
+            String(this.session.sessionId) === sessionId)
+            return;
+        const operation = ++this.generation;
+        this.drafting = false;
+        this.viewingSubagent = null;
         this.unbind();
         this.operationError = null;
         this.admissionPending = false;
-        this.state = { ...EMPTY_STATE, phase: "creating" };
+        this.policyReady = false;
+        this.state = {
+            ...QA_SESSION_IDLE_STATE,
+            chatsRevision: this.chatsRevision,
+            phase: "creating",
+        };
         this.emit();
         try {
             await this.waitForConnection();
-            const id = await this.createSession();
+            const list = await waitFor(this.sessions.list, (snapshot) => snapshot.phase === "ready", this.timeoutMs);
+            if (this.disposed || operation !== this.generation)
+                return;
+            if (!Object.hasOwn(list.byId, sessionId)) {
+                this.forgetChat(sessionId);
+                throw new Error("Этот чат больше недоступен.");
+            }
+            await this.bind(sessionId);
             if (this.disposed || operation !== this.generation)
                 return;
-            this.persist(id);
-            await this.bind(id);
+            this.chats.saveActive(sessionId);
         }
         catch (error) {
-            this.fail("Unable to start a new chat.", error);
+            // A newer operation superseded this switch: its own outcome governs.
+            if (this.disposed || operation !== this.generation)
+                return;
+            this.fail(this.operationError === CONFIGURATION_ERROR
+                ? this.operationError
+                : "Не удалось открыть этот чат.", error);
+        }
+    }
+    /**
+     * Watch a subagent's transcript live. The binding is read-only by
+     * construction: no attestation runs (attestation admits sending, and the
+     * composer stays disabled here), the chat index is untouched, and
+     * {@link closeSubagent} returns to the chat the panel was opened from.
+     */
+    async viewSubagent(id, title) {
+        if (this.disposed)
+            return;
+        if (this.viewingSubagent !== null &&
+            this.viewingSubagent.id === id &&
+            this.session !== undefined) {
+            return;
+        }
+        const operation = ++this.generation;
+        this.drafting = false;
+        this.viewingSubagent = { id, title };
+        this.unbind();
+        this.operationError = null;
+        this.admissionPending = false;
+        this.policyReady = false;
+        this.state = {
+            ...QA_SESSION_IDLE_STATE,
+            chatsRevision: this.chatsRevision,
+            viewingSubagent: this.viewingSubagent,
+            phase: "creating",
+        };
+        this.emit();
+        try {
+            await this.waitForConnection();
+            await this.bind(id, { attest: false, track: false, report: false });
+        }
+        catch (error) {
+            // A newer operation superseded this view request: leave its state alone.
+            if (this.disposed || operation !== this.generation)
+                return;
+            this.viewingSubagent = null;
+            this.fail("Не удалось открыть транскрипт субагента.", error);
+        }
+        if (this.disposed || operation !== this.generation)
+            return;
+    }
+    /** Leave the subagent transcript and re-open the chat it was launched from. */
+    async closeSubagent() {
+        const chat = this.chatSessionId;
+        if (chat === null)
+            return;
+        await this.switchTo(chat);
+    }
+    /** This browser's chat ids: the owned list when accounts are on, else the
+     * local index. Both intersect the host session list at projection time. */
+    chatIds() {
+        const owned = this.accounts?.ownedIds() ?? [];
+        if (owned.length === 0)
+            return this.chats.chatIds();
+        const local = this.chats.chatIds();
+        return [...new Set([...owned, ...local])];
+    }
+    /** The bound session id, or null while no chat is bound. */
+    activeSessionId() {
+        return this.session === undefined ? null : String(this.session.sessionId);
+    }
+    /**
+     * Resolve one durable image attachment of the bound session into a
+     * browser-usable URL. Resolutions are cached per chat in the asset
+     * repository (attachment ids repeat across chats) and revoked when the chat
+     * is unbound; failures surface as broken views and retry on demand.
+     */
+    async readImage(attachmentId) {
+        if (this.session === undefined)
+            throw new Error("no bound session");
+        const sessionId = String(this.session.sessionId);
+        return this.assets.resolve(sessionId, attachmentId, (id) => this.readAttachmentUrl(id));
+    }
+    async readAttachmentUrl(attachmentId) {
+        const session = this.session;
+        if (session === undefined)
+            throw new Error("no bound session");
+        const result = await session.readAttachment(attachmentId);
+        if (!result.ok) {
+            throw new Error(`${result.error.code}: ${result.error.message}`);
+        }
+        const { attachment, data } = result.value;
+        if (typeof URL.createObjectURL !== "function") {
+            return `data:${attachment.mediaType};base64,${bytesToBase64(data)}`;
+        }
+        return URL.createObjectURL(new Blob([Uint8Array.from(data).buffer], {
+            type: attachment.mediaType,
+        }));
+    }
+    /**
+     * Remove one chat from this browser's index. Deleting the chat that is
+     * currently open also forgets the persisted id and starts a fresh attested
+     * session (when the deployment allows session resets); the Host-side
+     * session itself is not touched — no host deletion seam exists.
+     */
+    async deleteChat(id) {
+        this.forgetChat(id);
+        this.chatsRevision += 1;
+        if (this.activeSessionId() === id &&
+            this.config.session.policy !== "fixed") {
+            // No replacement session is created: deleting the open chat falls back
+            // to a draft, and the next prompt materializes a fresh one. The stale
+            // persisted id is dropped so a reload cannot resurrect the deleted chat.
+            this.chats.clearActive();
+            await this.startDraft();
+            return;
         }
+        this.publish();
+    }
+    /** Drop one chat id from this browser's index. */
+    forgetChat(sessionId) {
+        this.chats.forgetChat(sessionId);
     }
     dispose() {
         if (this.disposed)
             return;
         this.disposed = true;
         this.generation += 1;
+        this.clearStreamFlush();
         this.unsubscribeConnection();
         this.unbind();
+        this.assets.dispose();
         this.listeners.clear();
     }
     async ensureSessionNow() {
         const operation = ++this.generation;
-        this.state = { ...EMPTY_STATE, phase: "creating" };
+        this.drafting = false;
+        this.state = {
+            ...QA_SESSION_IDLE_STATE,
+            chatsRevision: this.chatsRevision,
+            phase: "creating",
+        };
         this.emit();
         try {
             await this.waitForConnection();
             const list = await waitFor(this.sessions.list, (snapshot) => snapshot.phase === "ready", this.timeoutMs);
             let id = null;
+            let restored = false;
             if (this.config.session.policy === "fixed") {
                 id = this.config.session.fixedSessionId;
                 if (id === null || !Object.hasOwn(list.byId, id)) {
@@ -198,56 +477,138 @@ export class QaSessionController {
                 }
             }
             else if (this.config.session.policy === "browser-persistent") {
-                const stored = this.readPersisted();
+                const stored = this.chats.activeId();
                 if (stored !== null && Object.hasOwn(list.byId, stored)) {
                     id = stored;
+                    restored = true;
                 }
                 else if (stored !== null) {
-                    this.clearPersisted();
+                    this.chats.clearActive();
                 }
             }
             if (id === null) {
-                id = await this.createSession();
-                if (this.config.session.policy === "browser-persistent")
-                    this.persist(id);
+                id = await createQaSession({
+                    sessions: this.sessions,
+                    api: this.api,
+                    config: this.config,
+                });
             }
             if (this.disposed || operation !== this.generation)
                 return;
-            await this.bind(id);
+            // A restored id's first bind stays quiet: the recovery path below may
+            // replace it. A freshly created session must report a refusal at once —
+            // it is the deployment's only chance to learn the reason.
+            try {
+                await this.bind(id, { report: !restored });
+            }
+            catch (error) {
+                // A stale restore must not start its recovery ladder against a newer
+                // operation; rethrow for the generation-guarded outer catch.
+                if (this.disposed || operation !== this.generation)
+                    throw error;
+                if (!restored ||
+                    this.config.session.policy !== "browser-persistent" ||
+                    !(error instanceof QaPolicyAttestationError)) {
+                    throw error;
+                }
+                // A stored id is only a hint. If Host refuses that session under the
+                // current QA policy (for example after the configured preset changes),
+                // forget it and bootstrap one fresh, policy-attested session instead.
+                this.unbind();
+                this.operationError = null;
+                this.chats.clearActive();
+                id = await createQaSession({
+                    sessions: this.sessions,
+                    api: this.api,
+                    config: this.config,
+                });
+                if (this.disposed || operation !== this.generation)
+                    return;
+                await this.bind(id);
+            }
+            if (this.disposed || operation !== this.generation)
+                return;
+            if (this.config.session.policy === "browser-persistent") {
+                this.chats.saveActive(id);
+            }
         }
         catch (error) {
-            this.fail("Unable to start a chat.", error);
+            // A newer operation superseded this bootstrap: its own outcome governs.
+            if (this.disposed || operation !== this.generation)
+                return;
+            this.fail(this.operationError === CONFIGURATION_ERROR
+                ? this.operationError
+                : "Не удалось начать чат.", error);
         }
     }
-    async createSession() {
-        const response = await this.api.create({
-            ...(this.config.session.workspaceId === null
-                ? {}
-                : { workspaceId: this.config.session.workspaceId }),
-            ...(this.config.session.agentPreset === null
-                ? {}
-                : { agentPreset: this.config.session.agentPreset }),
-        });
-        if (!response.result.ok)
-            throw new Error(response.result.error.code);
-        const id = String(response.result.value.sessionId);
-        await waitFor(this.sessions.list, (snapshot) => Object.hasOwn(snapshot.byId, id), this.timeoutMs);
-        if (this.config.session.provider !== null &&
-            this.config.session.model !== null) {
-            const selected = await this.api.selectModel({
-                sessionId: id,
-                provider: this.config.session.provider,
-                model: this.config.session.model,
-                ...(this.config.session.reasoningEffort === null
-                    ? {}
-                    : { reasoningEffort: this.config.session.reasoningEffort }),
+    /**
+     * Recovery ladder after a refused send-time attestation. The prompt was
+     * never admitted, so nothing here can duplicate it. Step 1 re-opens the
+     * session: a Host that idled the agent out dismantles its tool view, and
+     * re-opening re-materializes it. Step 2 — when that refused session is
+     * still blank (it never received the prompt, so there is nothing to lose) —
+     * starts a fresh attested session instead. A session with history is left
+     * alone: recreating it would silently drop the conversation. Returns the
+     * attested session id, or null when nothing was attested.
+     */
+    async recoverForSend() {
+        const id = this.session === undefined ? null : String(this.session.sessionId);
+        if (id === null ||
+            this.disposed ||
+            this.config.session.policy === "fixed") {
+            return null;
+        }
+        const operation = ++this.generation;
+        this.unbind();
+        this.admissionPending = false;
+        this.policyReady = false;
+        this.state = { ...this.state, phase: "creating" };
+        this.emit();
+        try {
+            await this.waitForConnection();
+            try {
+                await this.bind(id);
+                if (this.disposed || operation !== this.generation)
+                    return null;
+                if (this.policyReady)
+                    return id;
+            }
+            catch (error) {
+                if (!(error instanceof QaPolicyAttestationError))
+                    throw error;
+                if (this.disposed || operation !== this.generation)
+                    return null;
+            }
+            if (this.session !== undefined && !this.session.getSnapshot().blank) {
+                this.fail(CONFIGURATION_ERROR, new QaPolicyAttestationError());
+                return null;
+            }
+            this.unbind();
+            this.chats.clearActive();
+            const created = await createQaSession({
+                sessions: this.sessions,
+                api: this.api,
+                config: this.config,
             });
-            if (!selected.result.ok)
-                throw new Error(selected.result.error.code);
+            if (this.disposed || operation !== this.generation)
+                return null;
+            await this.bind(created);
+            if (this.disposed || operation !== this.generation)
+                return null;
+            this.chats.saveActive(created);
+            return this.policyReady ? created : null;
+        }
+        catch (error) {
+            if (this.disposed || operation !== this.generation)
+                return null;
+            this.fail(this.operationError === CONFIGURATION_ERROR
+                ? this.operationError
+                : "Не удалось открыть этот чат.", error);
+            return null;
         }
-        return id;
     }
-    async bind(id) {
+    async bind(id, options = {}) {
+        const { report = true, attest = true, track = true } = options;
         this.sessions.open(id);
         let binding = this.sessions.binding(id);
         if (binding === undefined) {
@@ -258,26 +619,108 @@ export class QaSessionController {
             throw new Error("Session binding is unavailable.");
         this.unbind();
         this.session = binding.session;
+        this.conversationBinding = this.conversation.binding(id);
+        this.policyReady = false;
         this.unsubscribeSession = binding.session.subscribe(() => {
             this.admissionPending = false;
             this.operationError = null;
-            this.publish();
+            this.publishSessionUpdate();
+        });
+        // Subscribing the Chat target activates it, so the assembled transcript
+        // (nodes, partials, running calls) materializes for the projection.
+        this.unsubscribeChat = this.conversationBinding
+            .target("chat")
+            .subscribe(() => {
+            this.publishSessionUpdate();
         });
+        await waitFor(binding.session, (snapshot) => snapshot.openState === "open" || snapshot.openState === "error", this.timeoutMs);
+        if (binding.session.getSnapshot().openState !== "open") {
+            throw new Error("Session binding could not be opened.");
+        }
+        if (attest) {
+            const step = await this.attestPolicy(report);
+            if (step.kind !== "ok")
+                throw new QaPolicyAttestationError();
+        }
+        if (track) {
+            this.chatSessionId = String(this.session.sessionId);
+            this.viewingSubagent = null;
+            this.chats.addChat(String(this.session.sessionId));
+            this.accounts?.onSessionCreated(String(this.session.sessionId));
+        }
         this.publish();
     }
     unbind() {
+        this.clearStreamFlush();
         this.unsubscribeSession?.();
         this.unsubscribeSession = undefined;
+        this.unsubscribeChat?.();
+        this.unsubscribeChat = undefined;
+        this.conversationBinding = undefined;
+        if (this.session !== undefined) {
+            // Leaving the chat retires its attachment URLs; a later re-bind
+            // re-resolves them from the durable store.
+            this.assets.release(String(this.session.sessionId));
+        }
         this.session = undefined;
+        this.hostSources.reset();
         this.admissionPending = false;
+        this.policyReady = false;
     }
     waitForConnection() {
         return waitFor(this.connection, (description) => description !== undefined, this.timeoutMs);
     }
+    /**
+     * Project one session notification. A running turn's frames arrive at
+     * animation-frame cadence, so re-projections are spaced at least
+     * {@link streamIntervalMs} apart: the first frame of a window projects at
+     * once and further frames are absorbed (the memoized render path replays
+     * nothing, so absorbing a frame only defers it). Everything outside a
+     * running turn - phase flips, errors, turn completion - projects
+     * immediately.
+     */
+    publishSessionUpdate() {
+        if (this.streamIntervalMs <= 0 ||
+            this.session?.getSnapshot().running !== true) {
+            this.clearStreamFlush();
+            this.publish();
+            return;
+        }
+        if (this.streamFlushTimer !== undefined)
+            return;
+        this.publish();
+        this.streamFlushTimer = setTimeout(() => {
+            this.streamFlushTimer = undefined;
+        }, this.streamIntervalMs);
+    }
+    clearStreamFlush() {
+        if (this.streamFlushTimer === undefined)
+            return;
+        clearTimeout(this.streamFlushTimer);
+        this.streamFlushTimer = undefined;
+    }
     publish() {
         if (this.disposed)
             return;
         const connected = this.connection.getSnapshot() !== undefined;
+        if (this.drafting && this.session === undefined) {
+            // Draft state: an empty writable composer without a bound session. The
+            // session list is untouched — nothing exists until the first send.
+            const materializing = this.materializing !== undefined;
+            this.state = {
+                ...QA_SESSION_IDLE_STATE,
+                phase: materializing
+                    ? "creating"
+                    : !connected && this.connectedOnce
+                        ? "reconnecting"
+                        : "idle",
+                error: this.operationError,
+                canSend: connected && !materializing,
+                chatsRevision: this.chatsRevision,
+            };
+            this.emit();
+            return;
+        }
         if (this.session === undefined) {
             this.state = {
                 ...this.state,
@@ -288,75 +731,90 @@ export class QaSessionController {
             return;
         }
         const snapshot = this.session.getSnapshot();
-        const blocked = snapshot.pending.length > 0;
-        const error = this.operationError ??
-            (blocked
-                ? "This request requires an interaction that is not available in this assistant view."
-                : snapshot.removed || snapshot.openState === "error"
-                    ? "This chat is no longer available."
-                    : null);
-        const phase = !connected
-            ? "reconnecting"
-            : blocked
-                ? "blocked"
-                : snapshot.removed || snapshot.openState === "error"
-                    ? "error"
-                    : snapshot.openState !== "open"
-                        ? "creating"
-                        : snapshot.running || this.admissionPending
-                            ? "running"
-                            : "ready";
-        this.state = {
-            phase,
-            sessionId: String(this.session.sessionId),
-            messages: projectTranscript(snapshot, {
-                showToolActivity: this.config.ui.showToolActivity,
-            }),
-            error,
-            canSend: connected && phase === "ready",
-            canStop: connected && snapshot.running && this.config.ui.showStop && !blocked,
-        };
+        const sessionId = String(this.session.sessionId);
+        const conversationSnapshot = this.conversationBinding?.snapshot.getSnapshot();
+        const projectedSourceBundles = projectTurnSources(conversationSnapshot, sessionId, this.config.session.cwd ?? undefined);
+        const sourceBundles = this.hostSources.merge(projectedSourceBundles);
+        if (!snapshot.running) {
+            void this.hostSources.refresh(sessionId, () => this.publish());
+        }
+        this.state = projectBoundSessionState({
+            connected,
+            sessionId,
+            sessionSnapshot: snapshot,
+            conversationSnapshot,
+            sourceBundles,
+            // Ownership is chat-level: every user message of a foreign chat
+            // carries its owner's name when an admin reads it.
+            author: this.accounts?.messageAuthorOf(sessionId),
+            operationError: this.operationError,
+            policyReady: this.policyReady,
+            admissionPending: this.admissionPending,
+            chatsRevision: this.chatsRevision,
+            viewingSubagent: this.viewingSubagent,
+            config: this.config,
+        });
         this.emit();
     }
     fail(message, error) {
-        console.error("dsh-qa-surface: session operation failed", error);
+        // Policy attestation refusals already logged their precise reason; a
+        // second stack trace for the wrapper error is only console noise.
+        if (!(error instanceof QaPolicyAttestationError)) {
+            console.error("dsh-qa-surface: session operation failed", error);
+        }
         if (this.disposed)
             return;
         this.operationError = message;
         this.state = {
-            ...EMPTY_STATE,
+            ...QA_SESSION_IDLE_STATE,
             phase: "error",
             error: message,
+            chatsRevision: this.chatsRevision,
         };
         this.emit();
     }
-    storageKey() {
-        return `${this.config.session.storageKey}:v1:${this.config.route.path}:session`;
-    }
-    readPersisted() {
-        try {
-            const value = this.storage?.getItem(this.storageKey())?.trim() ?? "";
-            return value === "" ? null : value;
-        }
-        catch {
-            return null;
+    /**
+     * Attest the currently bound session. `ok` carries the session id the proof
+     * was issued for; `stale` means the binding changed while the request was
+     * in flight, so nothing was written — the newer binding manages its own
+     * attestation; `refused` is a genuine admission refusal of this binding.
+     */
+    async attestPolicy(reportFailure = true) {
+        const session = this.session;
+        if (session === undefined)
+            return { kind: "refused" };
+        const sessionId = String(session.sessionId);
+        if (!this.config.lockdown.enabled) {
+            this.policyReady = true;
+            return { kind: "ok", sessionId };
         }
-    }
-    persist(id) {
-        try {
-            this.storage?.setItem(this.storageKey(), id);
-        }
-        catch {
-            // A denied localStorage write must not prevent a real DSH session.
-        }
-    }
-    clearPersisted() {
-        try {
-            this.storage?.removeItem(this.storageKey());
+        this.policyReady = false;
+        this.publish();
+        const outcome = await attestQaPolicy({
+            secureSession: this.secureSessionRemote,
+            token: this.accounts?.token() ?? "",
+            sessionId,
+            lockdown: this.config.lockdown,
+            report: reportFailure,
+        });
+        if (this.session !== session)
+            return { kind: "stale" };
+        if (outcome.ok) {
+            this.policyReady = true;
+            this.operationError = null;
+            this.publish();
+            return { kind: "ok", sessionId };
         }
-        catch {
-            // A denied localStorage removal is harmless; the id is revalidated later.
+        if (outcome.authRequired) {
+            // The identity expired or was rotated: back to the gate instead of
+            // the generic configuration error.
+            this.accounts?.onAuthRequired();
+            return { kind: "refused" };
         }
+        this.policyReady = false;
+        this.operationError = CONFIGURATION_ERROR;
+        this.publish();
+        return { kind: "refused" };
     }
     emit() {
         for (const listener of this.listeners)