@yadsh/dsh-qa-surface 0.1.1 → 0.2.0

package/lib/client/QaSessionController.js

@@ -1,80 +1,59 @@
-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, attestationHint, attestationReasonOf, proofMatchesConfig, } from "./attestation.js";
+import { QaChatIndex } from "./chat-index.js";
+import { QA_SESSION_IDLE_STATE } from "./types.js";
+import { waitFor } from "./wait-for.js";
+import { projectSources } from "./QaTranscriptAdapter.js";
+import { projectTranscript, QA_REGENERATE_MARKER, } from "./QaTranscriptAdapter.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;
     connection;
     config;
-    storage;
+    secureSessionRemote;
+    chats;
     timeoutMs;
-    state = EMPTY_STATE;
+    streamIntervalMs;
+    state = QA_SESSION_IDLE_STATE;
     session;
     unsubscribeSession;
     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;
     constructor(options) {
         this.sessions = options.sessions;
         this.api = options.api;
         this.connection = options.connection;
         this.config = options.config;
-        this.storage = options.storage;
+        this.secureSessionRemote = options.secureSession;
+        this.chats = new QaChatIndex(options.storage, `${options.config.session.storageKey}:v1:${options.config.route.path}`);
         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 +76,48 @@ 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;
+        let attested = await this.attestPolicy();
+        if (!attested) {
+            attested = await this.recoverForSend();
+            if (!attested)
+                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 this.session.prompt(content, "queue");
             if (!result.ok) {
                 this.admissionPending = false;
-                this.operationError = "Your message could not be sent.";
+                this.operationError = "Не удалось отправить сообщение.";
                 this.publish();
                 return false;
             }
@@ -125,27 +127,45 @@ 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.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)
             return;
         try {
             const result = await this.session.cancel();
             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.";
+            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 +173,226 @@ 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 this.createSession();
+                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) {
+                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;
-            this.persist(id);
-            await this.bind(id);
+            if (!Object.hasOwn(list.byId, sessionId)) {
+                this.forgetChat(sessionId);
+                throw new Error("Этот чат больше недоступен.");
+            }
+            await this.bind(sessionId);
+            if (this.disposed || operation !== this.generation)
+                return;
+            this.chats.saveActive(sessionId);
+        }
+        catch (error) {
+            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) {
-            this.fail("Unable to start a new chat.", error);
+            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 indexed chat ids, most recently used first. */
+    chatIds() {
+        return this.chats.chatIds();
+    }
+    /** 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. The caller caches; failures surface as broken views.
+     */
+    async readImage(attachmentId) {
+        if (this.session === undefined)
+            throw new Error("no bound session");
+        const result = await this.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.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,40 +400,133 @@ 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);
             }
             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) {
+                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 this.createSession();
+                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(this.operationError === CONFIGURATION_ERROR
+                ? this.operationError
+                : "Не удалось начать чат.", error);
+        }
+    }
+    /**
+     * 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.
+     */
+    async recoverForSend() {
+        const id = this.session === undefined ? null : String(this.session.sessionId);
+        if (id === null ||
+            this.disposed ||
+            this.config.session.policy === "fixed") {
+            return false;
+        }
+        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 false;
+                if (this.policyReady)
+                    return true;
+            }
+            catch (error) {
+                if (!(error instanceof QaPolicyAttestationError))
+                    throw error;
+                if (this.disposed || operation !== this.generation)
+                    return false;
+            }
+            if (this.session !== undefined && !this.session.getSnapshot().blank) {
+                this.fail(CONFIGURATION_ERROR, new QaPolicyAttestationError());
+                return false;
+            }
+            this.unbind();
+            this.chats.clearActive();
+            const created = await this.createSession();
+            if (this.disposed || operation !== this.generation)
+                return false;
+            await this.bind(created);
+            if (this.disposed || operation !== this.generation)
+                return false;
+            this.chats.saveActive(created);
+            return this.policyReady;
         }
         catch (error) {
-            this.fail("Unable to start a chat.", error);
+            this.fail(this.operationError === CONFIGURATION_ERROR
+                ? this.operationError
+                : "Не удалось открыть этот чат.", error);
+            return false;
         }
     }
     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 }),
+        const created = await this.sessions.create({
+            ...(this.config.session.workspaceId !== null
+                ? { workspaceId: this.config.session.workspaceId }
+                : this.config.session.cwd !== null
+                    ? { cwd: this.config.session.cwd }
+                    : {}),
         });
-        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);
+        const id = String(created);
+        if (this.config.session.agentPreset !== null) {
+            const selectedPreset = await this.api.selectAgentPreset({
+                sessionId: id,
+                agentPreset: this.config.session.agentPreset,
+            });
+            if (!selectedPreset.result.ok) {
+                throw new Error(selectedPreset.result.error.code);
+            }
+            this.sessions.noteAgentPreset(id, this.config.session.agentPreset);
+        }
         if (this.config.session.provider !== null &&
             this.config.session.model !== null) {
             const selected = await this.api.selectModel({
@@ -247,7 +542,8 @@ export class QaSessionController {
         }
         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 +554,88 @@ export class QaSessionController {
             throw new Error("Session binding is unavailable.");
         this.unbind();
         this.session = binding.session;
+        this.policyReady = false;
         this.unsubscribeSession = binding.session.subscribe(() => {
             this.admissionPending = false;
             this.operationError = null;
-            this.publish();
+            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 && !(await this.attestPolicy(report))) {
+            throw new QaPolicyAttestationError();
+        }
+        if (track) {
+            this.chatSessionId = String(this.session.sessionId);
+            this.viewingSubagent = null;
+            this.chats.addChat(String(this.session.sessionId));
+        }
         this.publish();
     }
     unbind() {
+        this.clearStreamFlush();
         this.unsubscribeSession?.();
         this.unsubscribeSession = undefined;
         this.session = undefined;
         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,
@@ -291,9 +649,9 @@ export class QaSessionController {
         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"
@@ -311,51 +669,75 @@ export class QaSessionController {
             sessionId: String(this.session.sessionId),
             messages: projectTranscript(snapshot, {
                 showToolActivity: this.config.ui.showToolActivity,
+                showReasoning: this.config.ui.showReasoning,
             }),
             error,
-            canSend: connected && phase === "ready",
+            canSend: connected && phase === "ready" && this.policyReady,
             canStop: connected && snapshot.running && this.config.ui.showStop && !blocked,
+            chatsRevision: this.chatsRevision,
+            sources: projectSources(snapshot),
+            viewingSubagent: this.viewingSubagent,
         };
         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;
-        }
-    }
-    persist(id) {
-        try {
-            this.storage?.setItem(this.storageKey(), id);
-        }
-        catch {
-            // A denied localStorage write must not prevent a real DSH session.
+    async attestPolicy(reportFailure = true) {
+        if (this.session === undefined)
+            return false;
+        if (!this.config.lockdown.enabled) {
+            this.policyReady = true;
+            return true;
         }
-    }
-    clearPersisted() {
+        this.policyReady = false;
+        this.publish();
+        // One precise console diagnostic per refusal: the coarse Host reason code
+        // plus an operator hint. The QA-facing message stays generic by design.
+        const reject = (reason) => {
+            if (reportFailure) {
+                console.error(`dsh-qa-surface: policy attestation failed (reason: ${reason ?? "unknown"}). ${attestationHint(reason)}`);
+            }
+            this.policyReady = false;
+            this.operationError = CONFIGURATION_ERROR;
+            this.publish();
+            return false;
+        };
         try {
-            this.storage?.removeItem(this.storageKey());
+            const result = await this.secureSessionRemote(String(this.session.sessionId));
+            if (!result.ok) {
+                return reject(attestationReasonOf(result.error));
+            }
+            if (!proofMatchesConfig(result.value, this.config.lockdown, String(this.session.sessionId))) {
+                return reject("proof-mismatch");
+            }
+            this.policyReady = true;
+            this.operationError = null;
+            this.publish();
+            return true;
         }
-        catch {
-            // A denied localStorage removal is harmless; the id is revalidated later.
+        catch (error) {
+            if (reportFailure) {
+                console.error("dsh-qa-surface: policy attestation request failed", error);
+            }
+            this.policyReady = false;
+            this.operationError = CONFIGURATION_ERROR;
+            this.publish();
+            return false;
         }
     }
     emit() {