yarramate 0.18.0 → 0.19.0

package/dist/adapters/visual/session-server.js

@@ -1,27 +1,46 @@
-import { createHash, createHmac, randomBytes as randomSource, timingSafeEqual, } from 'node:crypto';
-import { lstat, readFile } from 'node:fs/promises';
-import { createServer, } from 'node:http';
-import { basename, extname, join, resolve, sep } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { WebSocketServer } from 'ws';
-import { compileVisualModel, } from './likec4-compiler.js';
-import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, } from './protocol.js';
-import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from './session-store.js';
+import { createHash, createHmac, randomBytes as randomSource, timingSafeEqual, } from "node:crypto";
+import { mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { lstat, readFile } from "node:fs/promises";
+import { createServer, } from "node:http";
+import { basename, extname, join, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020Module from "ajv/dist/2020.js";
+import { WebSocketServer } from "ws";
+import { parse, stringify } from "yaml";
+import { VISUAL_LIMITS, VISUAL_PROTOCOL_VERSION, parseVisualBrowserInput, parseVisualResponse, parseVisualSessionStarted, parseVisualStatus, visualBrowserInputType, } from "./protocol.js";
+import { appendTerminalEvent, appendVisualEvent, appendVisualResponse, createVisualSession, isActionableVisualEvent, recoverVisualSession, removeVisualSession, writeVisualSessionDescriptor, } from "./session-store.js";
+import { loadProjection, evaluateProjection, } from "../../projection.js";
+import { compileWorkspaceWithProfileContext, } from "../../compiler.js";
+import { applyOperations } from "../../apply-command.js";
+import { projectGraphForCanvas } from "../../graph-projection.js";
+import { kindLabelOf } from "../../kind-label.js";
+import { loadWorkspaceManifest, } from "../../workspace.js";
+import visualLayoutSchema from "../../../schema/yarramate-visual-layout.schema.json" with { type: "json" };
+import visualProjectionSchema from "../../../schema/yarramate-projection.schema.json" with { type: "json" };
+// The layout sidecar is adapter-owned presentation state (ADR 0023) that
+// protocol.ts's validators never touch — the browser's own `layout.save`
+// payload is already schema-validated by `parseVisualBrowserInput` before it
+// reaches this module — so this file compiles its own single-purpose
+// validator for the sidecar files it reads directly off disk.
+const Ajv2020 = Ajv2020Module.default;
+const layoutAjv = new Ajv2020({ allErrors: true });
+layoutAjv.addSchema(visualProjectionSchema);
+const validateVisualLayout = layoutAjv.compile(visualLayoutSchema);
 /**
  * Document name reported by diagnostics the server itself raises — a refused
  * frame, a frozen queue, or a transport violation that no protocol document
  * owns.
  */
-export const VISUAL_SERVER_DOCUMENT = 'visual-session-server';
+export const VISUAL_SERVER_DOCUMENT = "visual-session-server";
 /**
  * Returned on every response. The policy admits no external origin at all, so
  * neither a compromised model nor a hostile chat message can reach the network,
  * and the page can be neither framed nor used as a base for relative fetches.
  */
 export const VISUAL_BROWSER_HEADERS = {
-    'Referrer-Policy': 'no-referrer',
-    'X-Content-Type-Options': 'nosniff',
-    'Cache-Control': 'no-store',
+    "Referrer-Policy": "no-referrer",
+    "X-Content-Type-Options": "nosniff",
+    "Cache-Control": "no-store",
 };
 /**
  * This session's content policy. Every source stays `'self'`; the one addition
@@ -42,36 +61,36 @@ export const VISUAL_SERVER_LIMITS = {
     /** Browser sockets one session serves at once. */
     browserConnections: 8,
 };
-export const VISUAL_SOCKET_PATH = '/socket';
-const COOKIE_NAME = 'ym_visual';
+export const VISUAL_SOCKET_PATH = "/socket";
+const COOKIE_NAME = "ym_visual";
 /**
  * Assets are addressed by a single flat, hashed file name. Rejecting every
  * separator here means a traversal never reaches path resolution at all.
  */
 const ASSET_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const CONTENT_TYPES = {
-    '.css': 'text/css; charset=utf-8',
-    '.html': 'text/html; charset=utf-8',
-    '.js': 'text/javascript; charset=utf-8',
-    '.json': 'application/json; charset=utf-8',
-    '.png': 'image/png',
-    '.svg': 'image/svg+xml',
-    '.woff2': 'font/woff2',
+    ".css": "text/css; charset=utf-8",
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".json": "application/json; charset=utf-8",
+    ".png": "image/png",
+    ".svg": "image/svg+xml",
+    ".woff2": "font/woff2",
 };
 /** Response types that finish the agent turn an event opened. */
 const TURN_COMPLETING = {
-    'chat.response': true,
-    'choice.present': true,
-    'handoff.complete': true,
+    "chat.response": true,
+    "choice.present": true,
+    "handoff.complete": true,
     diagnostic: true,
 };
 const TERMINATION_REASONS = {
-    'user-ended': true,
-    'child-failed': true,
-    'browser-timeout': true,
-    'main-cancelled': true,
-    'server-failed': true,
-    'compiler-failed': true,
+    "user-ended": true,
+    "child-failed": true,
+    "browser-timeout": true,
+    "main-cancelled": true,
+    "server-failed": true,
+    "compiler-failed": true,
 };
 /**
  * Which freezes are a runtime failing rather than a session closing.
@@ -82,44 +101,34 @@ const TERMINATION_REASONS = {
  * the reconnect grace's business, so neither ends a session a second time.
  */
 const LIMIT_FREEZE = {
-    'message-bytes': true,
-    'model-bytes': true,
-    'transcript-bytes': true,
-    'pending-events': true,
-    'browser-disconnected': false,
-    'terminal-event': false,
+    "message-bytes": true,
+    "model-bytes": true,
+    "transcript-bytes": true,
+    "pending-events": true,
+    "browser-disconnected": false,
+    "terminal-event": false,
+    // A landed changeset that leaves the workspace unable to recompile is our
+    // own bug, not the reviewer's: the runtime is why the conversation stopped,
+    // same as the byte and queue ceilings above.
+    "recompile-failed": true,
 };
 /** Built browser application, beside the compiled adapter in `dist`. */
-const DEFAULT_ASSET_ROOT = fileURLToPath(new URL('../../visual-app/', import.meta.url));
-/**
- * One promoted candidate as the browser receives it. The export is read back
- * from the candidate directory rather than re-derived, so what the browser
- * draws is exactly the document the trusted compiler wrote.
- */
-const renderCompiled = async (compiled) => ({
-    candidate: compiled.candidate,
-    authority: compiled.authority,
-    initialView: compiled.initialView,
-    views: compiled.views,
-    compiled: JSON.parse(await readFile(compiled.exportPath, 'utf8')),
-});
+const DEFAULT_ASSET_ROOT = fileURLToPath(new URL("../../visual-app/", import.meta.url));
 /**
  * Takes one session terminal, whatever caused it: a reviewer's End, a child
  * that failed, a browser that never came back, a cancelling main agent, or a
  * runtime shutting itself down.
  *
- * The order is the invariant. Input freezes before anything is read; the
- * compiler is cancelled rather than waited out; work already admitted is still
- * allowed to finish; exactly one terminal event is journaled; and the handoff
- * is recovered without deleting anything, so `stop` — and only `stop` — is what
- * removes the session directory.
+ * The order is the invariant. Input freezes before anything is read; work
+ * already admitted is still allowed to finish; exactly one terminal event is
+ * journaled; and the handoff is recovered without deleting anything, so
+ * `stop` — and only `stop` — is what removes the session directory.
  */
 export const terminateVisualSession = (session, reason) => {
     session.terminating ??= (async () => {
-        if (session.lifecycle !== 'stopped')
-            session.lifecycle = 'draining';
-        session.freeze('terminal-event');
-        session.compilerAbort.abort();
+        if (session.lifecycle !== "stopped")
+            session.lifecycle = "draining";
+        session.freeze("terminal-event");
         await session.quiesce();
         // A terminal event that cannot be journaled must not be why a session
         // stays up: `runVisualStart` waits on this to return, so a transition that
@@ -143,8 +152,8 @@ const serverError = (code, message) => new Error(`${code}: ${message}`);
  * `/`, because these diagnostics are published in `visual-diagnostic-result/v1`
  * documents and read back by the one-shot agent clients.
  */
-const serverDiagnostic = (code, message, pointer = '/') => ({
-    severity: 'error',
+const serverDiagnostic = (code, message, pointer = "/") => ({
+    severity: "error",
     code,
     message,
     path: VISUAL_SERVER_DOCUMENT,
@@ -160,14 +169,14 @@ const serverDiagnostic = (code, message, pointer = '/') => ({
 const secretEquals = (expected, presented) => {
     if (presented === undefined)
         return false;
-    const digest = (value) => createHash('sha256').update(value, 'utf8').digest();
+    const digest = (value) => createHash("sha256").update(value, "utf8").digest();
     return timingSafeEqual(digest(expected), digest(presented));
 };
 const cookieValue = (header, name) => {
     if (header === undefined)
         return undefined;
-    for (const part of header.split(';')) {
-        const split = part.indexOf('=');
+    for (const part of header.split(";")) {
+        const split = part.indexOf("=");
         if (split < 0)
             continue;
         if (part.slice(0, split).trim() === name) {
@@ -186,12 +195,12 @@ const isJsonContent = (header) => header !== undefined && /^application\/json\s*
  * instead of a severed connection.
  */
 const readJsonBody = async (incoming, limit) => {
-    if (!isJsonContent(incoming.headers['content-type'])) {
+    if (!isJsonContent(incoming.headers["content-type"])) {
         incoming.resume();
         return {
             ok: false,
             status: 415,
-            message: 'Request body must be application/json',
+            message: "Request body must be application/json",
         };
     }
     const chunks = [];
@@ -216,11 +225,11 @@ const readJsonBody = async (incoming, limit) => {
     try {
         return {
             ok: true,
-            value: JSON.parse(Buffer.concat(chunks).toString('utf8')),
+            value: JSON.parse(Buffer.concat(chunks).toString("utf8")),
         };
     }
     catch {
-        return { ok: false, status: 400, message: 'Request body is not JSON' };
+        return { ok: false, status: 400, message: "Request body is not JSON" };
     }
 };
 /**
@@ -229,16 +238,47 @@ const readJsonBody = async (incoming, limit) => {
  */
 const eventFrom = (input, envelope) => {
     switch (input.type) {
-        case 'chat.message':
+        case "chat.message":
+            return { ...envelope, type: input.type, payload: input.payload };
+        case "choice.selected":
             return { ...envelope, type: input.type, payload: input.payload };
-        case 'choice.selected':
+        case "view.navigate":
             return { ...envelope, type: input.type, payload: input.payload };
-        case 'view.navigate':
+        case "session.end":
             return { ...envelope, type: input.type, payload: input.payload };
-        case 'session.end':
+        case "filter.query":
+            return { ...envelope, type: input.type, payload: input.payload };
+        case "view.save":
+            return { ...envelope, type: input.type, payload: input.payload };
+        case "changeset.commit":
+            return { ...envelope, type: input.type, payload: input.payload };
+        case "layout.save":
             return { ...envelope, type: input.type, payload: input.payload };
     }
 };
+/**
+ * Turns a view title into a schema-valid projection id: lowercase,
+ * hyphen-separated, letter-led. A title with no letters or digits degrades
+ * to "view" rather than producing an id the schema would reject.
+ */
+const slugify = (title) => {
+    const cleaned = title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    if (cleaned.length === 0)
+        return "view";
+    return /^[a-z]/.test(cleaned) ? cleaned : `view-${cleaned}`;
+};
+/** Appends a numeric suffix only when the base id collides with a known view. */
+const uniqueViewId = (base, taken) => {
+    if (!taken.has(base))
+        return base;
+    let suffix = 2;
+    while (taken.has(`${base}-${suffix}`))
+        suffix += 1;
+    return `${base}-${suffix}`;
+};
 /**
  * Serves one authenticated visual session over loopback. The handle owns the
  * session directory it created: `stop` recovers the handoff before deleting it,
@@ -253,9 +293,9 @@ export const startVisualServer = async (options) => {
     const drawHex = (size) => {
         const drawn = randomBytes(size);
         if (drawn.byteLength < size) {
-            throw serverError('YMVS301', `Random source returned ${drawn.byteLength} bytes for a ${size}-byte draw`);
+            throw serverError("YMVS301", `Random source returned ${drawn.byteLength} bytes for a ${size}-byte draw`);
         }
-        return drawn.subarray(0, size).toString('hex');
+        return drawn.subarray(0, size).toString("hex");
     };
     const stamp = () => now().toISOString();
     const session = await createVisualSession(request, {
@@ -268,47 +308,183 @@ export const startVisualServer = async (options) => {
     const cookieSigningKey = drawHex(32);
     // The browser stores only a derived bearer value; the signing key stays in
     // this server process and disappears with the session.
-    const browserAuthenticator = createHmac('sha256', cookieSigningKey)
+    const browserAuthenticator = createHmac("sha256", cookieSigningKey)
         .update(sessionId)
-        .digest('hex');
+        .digest("hex");
     // Not a credential: it authorises inline style for this page, nothing else.
     const styleNonce = drawHex(16);
     const browserHeaders = {
         ...VISUAL_BROWSER_HEADERS,
-        'Content-Security-Policy': visualContentSecurityPolicy(styleNonce),
+        "Content-Security-Policy": visualContentSecurityPolicy(styleNonce),
     };
-    /** Cancels every compile this session runs, including one in flight. */
-    const compilerAbort = new AbortController();
     /** Set once the loopback listener exists; a failed start has to close it. */
     let closeListener;
     // Past this point a session directory exists on disk; a failed start must not
     // leave one behind for the next run to prune, nor a listener for the process
     // to outlive.
     const abandon = async (cause) => {
-        compilerAbort.abort();
         await closeListener?.().catch(() => undefined);
         await removeVisualSession(paths).catch(() => undefined);
         throw cause;
     };
-    const compilation = await compileVisualModel({
-        model: request.initialModel,
-        command: request.compiler,
-        paths,
-        now,
-        signal: compilerAbort.signal,
-    }).catch(abandon);
-    if (!compilation.ok) {
-        const first = compilation.diagnostics[0];
-        return abandon(serverError(first?.code ?? 'YMVS302', `Initial visual model did not compile: ${first?.message ?? 'unknown violation'}`));
-    }
-    let rendered = await renderCompiled(compilation.compiled).catch(abandon);
+    const manifestPath = resolve(options.cwd, ".yarramate/workspace.yaml");
+    // A session with no resolvable workspace manifest has nothing to compile,
+    // filter, or land a `changeset.commit` against, so a missing, unreadable, or
+    // invalid manifest refuses the session outright rather than starting one
+    // nothing can act on.
+    const resolvedWorkspace = await (async () => {
+        try {
+            const manifestSource = readFileSync(manifestPath, "utf8");
+            const loaded = loadWorkspaceManifest({ path: manifestPath, source: manifestSource }, options.cwd);
+            if (loaded.ok)
+                return loaded.workspace;
+        }
+        catch {
+            // Falls through to the same refusal as an invalid manifest below.
+        }
+        return abandon(serverError("YMVS132", `Session requires a resolvable workspace manifest at ${manifestPath}`));
+    })();
+    // Saved views join this list as they are written (see `view.save`), because
+    // a reconnecting browser is handed it in its snapshot and `layout.save`
+    // checks projection ids against it.
+    const views = resolvedWorkspace.projections.flatMap((projectionPath) => {
+        try {
+            const projectionSource = readFileSync(resolve(options.cwd, projectionPath), "utf8");
+            const loaded = loadProjection({
+                path: projectionPath,
+                source: projectionSource,
+            });
+            if (!loaded.ok)
+                return [];
+            const { projection } = loaded;
+            return [
+                {
+                    id: projection.id,
+                    title: projection.presentation?.title ?? projection.id,
+                    description: projection.presentation?.description ?? "",
+                    query: projection.query,
+                    presentation: projection.presentation,
+                },
+            ];
+        }
+        catch {
+            // Skipped projection: session continues with remaining views.
+            return [];
+        }
+    });
+    // Drag positions are adapter-owned presentation state (ADR 0023): never
+    // validated by Core. An invalid or unreadable sidecar is skipped exactly
+    // like a broken saved view above — presentation state must never fail a
+    // session.
+    const layoutDir = resolve(options.cwd, ".yarramate/visual-layout");
+    const layouts = (() => {
+        const built = {};
+        let entries;
+        try {
+            entries = readdirSync(layoutDir);
+        }
+        catch {
+            return built;
+        }
+        for (const entry of entries) {
+            if (extname(entry) !== ".yaml" && extname(entry) !== ".yml")
+                continue;
+            try {
+                const source = readFileSync(join(layoutDir, entry), "utf8");
+                const parsed = parse(source);
+                if (!validateVisualLayout(parsed))
+                    continue;
+                const sidecar = parsed;
+                built[sidecar.projectionId] = sidecar.positions;
+            }
+            catch {
+                // Skipped sidecar: presentation state must never fail a session.
+            }
+        }
+        return built;
+    })();
+    // `request.initialModel.graph` is the caller's compile (`buildVisualModelGraph`,
+    // before invoking `yarramate-visual start`) and is only the fallback below:
+    // `recompileWorkspace` immediately below is the one path that actually fills
+    // `documents`/`vocabulary`, reused for both the initial render and every
+    // later `changeset.commit`.
+    let rendered = {
+        authority: request.initialModel.authority,
+        initialView: request.initialModel.initialView,
+        graph: request.initialModel.graph,
+        documents: [],
+        vocabulary: { conceptKinds: [], relationshipKinds: [] },
+        layouts,
+    };
     const capabilities = {
         chat: request.chatEnabled,
         choices: request.chatEnabled,
         navigation: true,
-        modelReplacement: true,
         transcript: true,
     };
+    let compiledWorkspace;
+    /**
+     * `filter.query` needs a `SemanticGraph`, not the `CanvasGraph` the rendered
+     * model carries — that graph is compiled here, from the same
+     * `resolvedWorkspace` profiles and documents `ask-command.ts` compiles from,
+     * and reused for every query the session receives. A session whose sources
+     * fail to compile has nothing to filter against: `filterMatchedIds`
+     * degrades to an empty match set rather than failing the session.
+     *
+     * This is the single compile path: called once for the initial `rendered`
+     * above and again after every landed `changeset.commit`, it re-reads
+     * sources from disk, reassigns `compiledWorkspace`, rebuilds the
+     * `CanvasGraph`, and reassigns `rendered` — carrying forward `authority`,
+     * `initialView`, and `layouts`, which a document recompile never touches.
+     * Returns whether it compiled, so a post-write failure can freeze the
+     * session instead of serving a stale graph.
+     */
+    const recompileWorkspace = () => {
+        try {
+            const sources = [
+                ...resolvedWorkspace.profiles,
+                ...resolvedWorkspace.documents,
+            ].map((path) => ({
+                path,
+                source: readFileSync(resolve(options.cwd, path), "utf8"),
+            }));
+            const compiled = compileWorkspaceWithProfileContext(sources);
+            if (!compiled.ok) {
+                compiledWorkspace = undefined;
+                return false;
+            }
+            compiledWorkspace = {
+                graph: compiled.graph,
+                profileContext: compiled.profileContext,
+            };
+            const conceptKinds = [
+                ...compiled.profileContext.conceptKindLineages.keys(),
+            ].map((id) => ({ id, label: kindLabelOf(id) }));
+            const relationshipKinds = [
+                ...compiled.profileContext.relationshipKindLineages.keys(),
+            ].map((id) => ({ id, label: kindLabelOf(id) }));
+            rendered = {
+                authority: rendered.authority,
+                initialView: rendered.initialView,
+                graph: projectGraphForCanvas(compiled.graph, compiled.profileContext),
+                documents: resolvedWorkspace.documents,
+                vocabulary: { conceptKinds, relationshipKinds },
+                layouts: rendered.layouts,
+            };
+            return true;
+        }
+        catch {
+            compiledWorkspace = undefined;
+            return false;
+        }
+    };
+    recompileWorkspace();
+    const filterMatchedIds = (query) => {
+        if (compiledWorkspace === undefined)
+            return [];
+        const result = evaluateProjection(compiledWorkspace.graph, { format: "yarramate/projection/v1", id: "ad-hoc", version: "0", query }, compiledWorkspace.profileContext);
+        return result.subjects.map(({ id }) => id);
+    };
     let listening = false;
     let bootstrapSpent = false;
     let agentAttached = false;
@@ -381,7 +557,7 @@ export const startVisualServer = async (options) => {
                 // `server-failed` is the truth of it: not the reviewer, not the child,
                 // but the runtime is why the conversation stopped. Recovery reads that
                 // back as a failed handoff carrying everything the session did accept.
-                await terminateVisualSession(active, 'server-failed');
+                await terminateVisualSession(active, "server-failed");
             }
             finally {
                 // Whatever the journal managed, the child must not be left holding a
@@ -407,8 +583,7 @@ export const startVisualServer = async (options) => {
      */
     const active = {
         paths,
-        lifecycle: 'starting',
-        compilerAbort,
+        lifecycle: "starting",
         freeze,
         quiesce: drainAdmission,
         terminalEvent: { now, randomBytes },
@@ -429,13 +604,13 @@ export const startVisualServer = async (options) => {
      */
     let cancelGrace;
     const armGrace = () => {
-        if (cancelGrace !== undefined || active.lifecycle !== 'running')
+        if (cancelGrace !== undefined || active.lifecycle !== "running")
             return;
         cancelGrace = schedule(async () => {
             cancelGrace = undefined;
-            if (connections.size > 0 || active.lifecycle !== 'running')
+            if (connections.size > 0 || active.lifecycle !== "running")
                 return;
-            await stop('browser-timeout');
+            await stop("browser-timeout");
         }, VISUAL_LIMITS.reconnectMs);
     };
     const disarmGrace = () => {
@@ -446,20 +621,20 @@ export const startVisualServer = async (options) => {
     const recordEvent = (event) => {
         // A session on its way out waits on nobody, and asking past the question
         // is how a reviewer declines to answer it.
-        if (event.type === 'chat.message' || event.type === 'session.end') {
+        if (event.type === "chat.message" || event.type === "session.end") {
             pendingChoice = null;
         }
-        if (event.type === 'session.end')
+        if (event.type === "session.end")
             choicesClosed = true;
-        if (event.type === 'chat.message') {
+        if (event.type === "chat.message") {
             transcript.push({
                 id: event.eventId,
-                speaker: 'reviewer',
+                speaker: "reviewer",
                 text: event.payload.text,
             });
             return;
         }
-        if (event.type !== 'choice.selected')
+        if (event.type !== "choice.selected")
             return;
         if (pendingChoice?.choiceId === event.payload.choiceId)
             pendingChoice = null;
@@ -470,26 +645,26 @@ export const startVisualServer = async (options) => {
             ?.get(event.payload.optionId);
         transcript.push({
             id: event.eventId,
-            speaker: 'reviewer',
+            speaker: "reviewer",
             text: label ?? event.payload.optionId,
         });
     };
     /** An accepted agent response, as the line the reviewer sees. */
     const recordResponse = (response) => {
-        if (response.type === 'choice.present') {
+        if (response.type === "choice.present") {
             if (!choicesClosed)
                 pendingChoice = response.payload;
             choiceLabels.set(response.payload.choiceId, new Map(response.payload.options.map((option) => [option.id, option.label])));
             return;
         }
-        const text = response.type === 'chat.response'
+        const text = response.type === "chat.response"
             ? response.payload.text
-            : response.type === 'handoff.complete'
+            : response.type === "handoff.complete"
                 ? response.payload.summary
                 : undefined;
         if (text === undefined)
             return;
-        transcript.push({ id: response.responseId, speaker: 'agent', text });
+        transcript.push({ id: response.responseId, speaker: "agent", text });
     };
     const snapshot = () => ({
         protocolVersion: VISUAL_PROTOCOL_VERSION,
@@ -502,6 +677,7 @@ export const startVisualServer = async (options) => {
         webSocketUrl,
         model: rendered,
         transcript: [...transcript],
+        views,
         agentTurnOpen: openTurn(),
         pendingChoice,
         styleNonce,
@@ -510,11 +686,11 @@ export const startVisualServer = async (options) => {
     });
     const status = () => {
         const value = {
-            format: 'yarramate/visual-status/v1',
+            format: "yarramate/visual-status/v1",
             protocolVersion: VISUAL_PROTOCOL_VERSION,
             sessionId,
             lifecycle: active.lifecycle,
-            alreadyStopped: active.lifecycle === 'stopped',
+            alreadyStopped: active.lifecycle === "stopped",
             server: { listening, origin },
             browser: {
                 connected: connections.size > 0,
@@ -546,7 +722,7 @@ export const startVisualServer = async (options) => {
         // untrusted input: the agent must never have to parse a broken report.
         const validated = parseVisualStatus(value);
         if (!validated.ok) {
-            throw serverError(validated.diagnostics[0]?.code ?? 'YMVS108', `Session status is invalid: ${validated.diagnostics[0]?.message ?? 'unknown violation'}`);
+            throw serverError(validated.diagnostics[0]?.code ?? "YMVS108", `Session status is invalid: ${validated.diagnostics[0]?.message ?? "unknown violation"}`);
         }
         return value;
     };
@@ -602,22 +778,22 @@ export const startVisualServer = async (options) => {
         }
     };
     const httpServer = createServer();
-    httpServer.on('connection', (socket) => {
+    httpServer.on("connection", (socket) => {
         httpSockets.add(socket);
         unclassifiedHttpSockets.add(socket);
-        socket.on('close', () => {
+        socket.on("close", () => {
             httpSockets.delete(socket);
             unclassifiedHttpSockets.delete(socket);
             stopResponseSockets.delete(socket);
         });
     });
-    httpServer.on('clientError', (_error, socket) => socket.destroy());
+    httpServer.on("clientError", (_error, socket) => socket.destroy());
     const bound = Promise.withResolvers();
-    httpServer.once('error', bound.reject);
+    httpServer.once("error", bound.reject);
     // Loopback only, on a kernel-assigned port: the session is never reachable
     // from another host, and never collides with a well-known service.
-    httpServer.listen(0, '127.0.0.1', () => {
-        httpServer.removeListener('error', bound.reject);
+    httpServer.listen(0, "127.0.0.1", () => {
+        httpServer.removeListener("error", bound.reject);
         bound.resolve();
     });
     await bound.promise.catch(abandon);
@@ -645,23 +821,40 @@ export const startVisualServer = async (options) => {
     const respond = (server, code, body, contentType) => {
         server.writeHead(code, {
             ...browserHeaders,
-            'Content-Type': contentType,
-            'Content-Length': Buffer.byteLength(body),
+            "Content-Type": contentType,
+            "Content-Length": Buffer.byteLength(body),
             // A draining session must not leave a pooled connection behind that
             // outlives its listener.
-            ...(active.lifecycle === 'running' ? {} : { Connection: 'close' }),
+            ...(active.lifecycle === "running" ? {} : { Connection: "close" }),
         });
         server.end(body);
     };
-    const respondJson = (server, code, value) => respond(server, code, JSON.stringify(value), 'application/json; charset=utf-8');
-    const refuse = (server, code, message) => respond(server, code, `${message}\n`, 'text/plain; charset=utf-8');
+    const respondJson = (server, code, value) => respond(server, code, JSON.stringify(value), "application/json; charset=utf-8");
+    const refuse = (server, code, message) => respond(server, code, `${message}\n`, "text/plain; charset=utf-8");
     // ------------------------------------------------------------ browser input
+    /**
+     * What a raw frame claims to be, for a refusal that never got a document.
+     *
+     * Admitting can fail before anything parsed, and the browser is still
+     * holding a control open for whatever it sent. Reading the claim back off
+     * the bytes costs a parse only on the path where admitting already failed.
+     */
+    const claimedBrowserInput = (raw, binary) => {
+        if (binary)
+            return undefined;
+        try {
+            return visualBrowserInputType(JSON.parse(raw.toString()));
+        }
+        catch {
+            return undefined;
+        }
+    };
     const admitBrowserInput = async (socket, raw, binary) => {
         if (binary) {
             sendFrame(socket, {
-                kind: 'rejected',
+                kind: "rejected",
                 diagnostics: [
-                    serverDiagnostic('YMVS303', 'Browser frames must be UTF-8 JSON text'),
+                    serverDiagnostic("YMVS303", "Browser frames must be UTF-8 JSON text"),
                 ],
             });
             return;
@@ -672,53 +865,64 @@ export const startVisualServer = async (options) => {
         }
         catch {
             sendFrame(socket, {
-                kind: 'rejected',
+                kind: "rejected",
                 diagnostics: [
-                    serverDiagnostic('YMVS109', 'Browser frame is not a JSON document'),
+                    serverDiagnostic("YMVS109", "Browser frame is not a JSON document"),
                 ],
             });
             return;
         }
+        // What the frame says it is, before anything has agreed that it is well
+        // formed. A browser holding a control open for this input is told which
+        // one died even when the document that named it is the thing at fault.
+        const refused = visualBrowserInputType(parsed);
         const input = parseVisualBrowserInput(parsed);
         if (!input.ok) {
-            sendFrame(socket, { kind: 'rejected', diagnostics: input.diagnostics });
+            sendFrame(socket, {
+                kind: "rejected",
+                ...(refused === undefined ? {} : { refused }),
+                diagnostics: input.diagnostics,
+            });
             return;
         }
         await admit(async () => {
             // A frame can already be on the chain when a stop begins. Recovery must
             // see a journal nothing is still writing to, so anything that has not
             // been journaled yet is refused rather than raced.
-            if (active.lifecycle !== 'running') {
+            if (active.lifecycle !== "running") {
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     diagnostics: [
-                        serverDiagnostic('YMVS306', `Session is ${active.lifecycle} and no longer accepts input`),
+                        serverDiagnostic("YMVS306", `Session is ${active.lifecycle} and no longer accepts input`),
                     ],
                 });
                 return;
             }
             if (frozen !== undefined) {
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     frozen,
                     diagnostics: [
-                        serverDiagnostic('YMVS304', `Session input is frozen: ${frozen}`),
+                        serverDiagnostic("YMVS304", `Session input is frozen: ${frozen}`),
                     ],
                 });
                 return;
             }
             // A session that was started without a conversation has no chat and no
             // choices to make; the diagram, and moving around it, is all it granted.
-            const granted = input.value.type === 'chat.message'
+            const granted = input.value.type === "chat.message"
                 ? capabilities.chat
-                : input.value.type === 'choice.selected'
+                : input.value.type === "choice.selected"
                     ? capabilities.choices
                     : true;
             if (!granted) {
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     diagnostics: [
-                        serverDiagnostic('YMVS309', `Session did not grant the capability "${input.value.type}" needs`, '/type'),
+                        serverDiagnostic("YMVS309", `Session did not grant the capability "${input.value.type}" needs`, "/type"),
                     ],
                 });
                 return;
@@ -730,15 +934,16 @@ export const startVisualServer = async (options) => {
             // journaled behind a sequence its sender never read.
             if (input.value.lastAcknowledgedSequence > lastSequence) {
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     diagnostics: [
-                        serverDiagnostic('YMVS308', `Browser acknowledged sequence ${input.value.lastAcknowledgedSequence}, past the journal's ${lastSequence}`, '/lastAcknowledgedSequence'),
+                        serverDiagnostic("YMVS308", `Browser acknowledged sequence ${input.value.lastAcknowledgedSequence}, past the journal's ${lastSequence}`, "/lastAcknowledgedSequence"),
                     ],
                 });
                 return;
             }
             const event = eventFrom(input.value, {
-                format: 'yarramate/visual-event/v1',
+                format: "yarramate/visual-event/v1",
                 sessionId,
                 sequence: lastSequence + 1,
                 eventId: drawHex(16),
@@ -746,12 +951,13 @@ export const startVisualServer = async (options) => {
             });
             const actionable = isActionableVisualEvent(event);
             if (actionable && pending.length >= VISUAL_LIMITS.pendingEvents) {
-                freeze('pending-events');
+                freeze("pending-events");
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     frozen,
                     diagnostics: [
-                        serverDiagnostic('YMVS305', `Queue already holds the ${VISUAL_LIMITS.pendingEvents} event maximum`, '/sequence'),
+                        serverDiagnostic("YMVS305", `Queue already holds the ${VISUAL_LIMITS.pendingEvents} event maximum`, "/sequence"),
                     ],
                 });
                 return;
@@ -761,7 +967,8 @@ export const startVisualServer = async (options) => {
                 if (appended.freeze !== undefined)
                     freeze(appended.freeze);
                 sendFrame(socket, {
-                    kind: 'rejected',
+                    kind: "rejected",
+                    refused: input.value.type,
                     ...(frozen === undefined ? {} : { frozen }),
                     diagnostics: appended.diagnostics,
                 });
@@ -774,10 +981,168 @@ export const startVisualServer = async (options) => {
                 pending.push(event);
             // A journaled end is the last input this session takes. The agent still
             // has to see it, so the queue freezes rather than the socket closing.
-            if (event.type === 'session.end')
-                freeze('terminal-event');
+            if (event.type === "session.end")
+                freeze("terminal-event");
+            if (event.type === "filter.query") {
+                // Filtering is a pure read of the compiled workspace: it never asks
+                // the agent anything, so it is answered here directly rather than
+                // through the pending queue a poll would drain.
+                sendFrame(socket, {
+                    kind: "filter-result",
+                    result: {
+                        query: event.payload.query,
+                        matchedIds: filterMatchedIds(event.payload.query),
+                    },
+                });
+                return;
+            }
+            if (event.type === "view.save") {
+                // Saving a view is a pure filesystem write plus schema validation: it
+                // never asks the agent anything, so it is answered here directly
+                // rather than through the pending queue a poll would drain.
+                const existingIds = new Set(views.map((view) => view.id));
+                const id = event.payload.id ??
+                    uniqueViewId(slugify(event.payload.title), existingIds);
+                const presentation = {
+                    ...(event.payload.presentation ?? {}),
+                    title: event.payload.title,
+                    description: event.payload.description,
+                };
+                const candidate = {
+                    format: "yarramate/projection/v1",
+                    id,
+                    version: "1.0",
+                    query: event.payload.query,
+                    presentation,
+                };
+                const path = `.yarramate/projections/${id}.yaml`;
+                const source = stringify(candidate);
+                const loaded = loadProjection({ path, source });
+                if (!loaded.ok) {
+                    sendFrame(socket, {
+                        kind: "view-save-result",
+                        result: { ok: false, diagnostics: loaded.diagnostics },
+                    });
+                    return;
+                }
+                mkdirSync(resolve(options.cwd, ".yarramate/projections"), {
+                    recursive: true,
+                });
+                writeFileSync(resolve(options.cwd, path), source, "utf8");
+                // On disk is not enough: the list handed to a reconnecting browser and
+                // checked by `layout.save` lives here, so an overwrite replaces its
+                // summary in place and a new view joins the end.
+                const summary = {
+                    id,
+                    title: event.payload.title,
+                    description: event.payload.description,
+                    query: event.payload.query,
+                    presentation,
+                };
+                const saved = views.findIndex((view) => view.id === id);
+                if (saved === -1)
+                    views.push(summary);
+                else
+                    views[saved] = summary;
+                sendFrame(socket, {
+                    kind: "view-save-result",
+                    result: { ok: true, id, path },
+                });
+                return;
+            }
+            if (event.type === "changeset.commit") {
+                // Landing a batch is mechanical: Core's `applyOperations` never asks
+                // the agent anything, so it is answered here directly rather than
+                // through the pending queue a poll would drain. This never runs
+                // `git commit` - the user reverts a landed batch with `git revert`.
+                const operationsSource = stringify({
+                    format: "yarramate/operations/v1",
+                    operations: event.payload.operations,
+                });
+                const outcome = applyOperations({ path: "changeset.yaml", source: operationsSource }, { path: manifestPath, source: readFileSync(manifestPath, "utf8") }, options.cwd);
+                if (!outcome.ok) {
+                    // Nothing landed: forward Core's diagnostics verbatim (ADR 0062)
+                    // rather than recompiling or broadcasting anything.
+                    sendFrame(socket, {
+                        kind: "apply-result",
+                        result: { ok: false, diagnostics: outcome.diagnostics },
+                    });
+                    return;
+                }
+                sendFrame(socket, {
+                    kind: "apply-result",
+                    result: { ok: true, result: outcome.result },
+                });
+                if (recompileWorkspace()) {
+                    broadcast({ kind: "model", model: rendered });
+                    return;
+                }
+                // A post-write compile failure is a bug, not a user error: the batch
+                // landed but produced a document Core itself can no longer parse.
+                // The freeze alone only tells the browser input is refused, not why
+                // the graph on screen has gone stale, so a diagnostic response is
+                // journaled alongside it.
+                const diagnosticResponse = {
+                    format: "yarramate/visual-response/v1",
+                    sessionId,
+                    responseId: drawHex(16),
+                    eventId: event.eventId,
+                    type: "diagnostic",
+                    timestamp: stamp(),
+                    payload: {
+                        diagnostics: [
+                            serverDiagnostic("YMVS310", "Workspace failed to recompile after a landed changeset"),
+                        ],
+                    },
+                };
+                const appendedResponse = await appendVisualResponse(paths, diagnosticResponse);
+                if (appendedResponse.ok) {
+                    transcriptBytes = appendedResponse.transcriptBytes;
+                    recordResponse(diagnosticResponse);
+                    broadcast({ kind: "response", response: diagnosticResponse });
+                }
+                else if (appendedResponse.freeze !== undefined) {
+                    freeze(appendedResponse.freeze);
+                }
+                freeze("recompile-failed");
+                return;
+            }
+            if (event.type === "layout.save") {
+                // Saving a drag position is adapter-owned presentation state
+                // (ADR 0023): never routed through `apply`, never validated by Core,
+                // never `git commit`ed. It never asks the agent anything, so it is
+                // answered here directly rather than through the pending queue a
+                // poll would drain.
+                const { projectionId, positions } = event.payload;
+                if (!views.some((view) => view.id === projectionId)) {
+                    sendFrame(socket, {
+                        kind: "layout-save-result",
+                        result: {
+                            ok: false,
+                            message: `"${projectionId}" is not a known view id`,
+                        },
+                    });
+                    return;
+                }
+                const path = `.yarramate/visual-layout/${projectionId}.yaml`;
+                mkdirSync(layoutDir, { recursive: true });
+                writeFileSync(resolve(options.cwd, path), stringify({
+                    format: "yarramate/visual-layout/v1",
+                    projectionId,
+                    positions,
+                }), "utf8");
+                rendered = {
+                    ...rendered,
+                    layouts: { ...rendered.layouts, [projectionId]: positions },
+                };
+                sendFrame(socket, {
+                    kind: "layout-save-result",
+                    result: { ok: true, path },
+                });
+                return;
+            }
             sendFrame(socket, {
-                kind: 'accepted',
+                kind: "accepted",
                 sequence: event.sequence,
                 eventId: event.eventId,
             });
@@ -800,20 +1165,24 @@ export const startVisualServer = async (options) => {
      * the process never handles.
      */
     const journalConnection = (connectionId, closedWith, onJournaled) => admit(async () => {
-        if (active.lifecycle !== 'running' || frozen !== undefined)
+        if (active.lifecycle !== "running" || frozen !== undefined)
             return false;
         const envelope = {
-            format: 'yarramate/visual-event/v1',
+            format: "yarramate/visual-event/v1",
             sessionId,
             sequence: lastSequence + 1,
             eventId: drawHex(16),
             timestamp: stamp(),
         };
         const event = closedWith === undefined
-            ? { ...envelope, type: 'browser.connected', payload: { connectionId } }
+            ? {
+                ...envelope,
+                type: "browser.connected",
+                payload: { connectionId },
+            }
             : {
                 ...envelope,
-                type: 'browser.disconnected',
+                type: "browser.disconnected",
                 payload: { connectionId, code: closedWith },
             };
         const appended = await appendVisualEvent(paths, event);
@@ -831,16 +1200,18 @@ export const startVisualServer = async (options) => {
         const connectionId = drawHex(16);
         let registered = false;
         lastSeenAt = stamp();
-        socket.on('message', (raw, binary) => {
+        socket.on("message", (raw, binary) => {
             // Nothing awaits this handler, so a rejection here would reach the
             // process as an unhandled one and take the runtime down with it. The
             // browser is told its frame failed; the session stays up.
             admitBrowserInput(socket, raw, binary).catch((cause) => {
+                const refused = claimedBrowserInput(raw, binary);
                 try {
                     sendFrame(socket, {
-                        kind: 'rejected',
+                        kind: "rejected",
+                        ...(refused === undefined ? {} : { refused }),
                         diagnostics: [
-                            serverDiagnostic('YMVS307', `Admitting the browser frame failed: ${cause instanceof Error ? cause.message : String(cause)}`),
+                            serverDiagnostic("YMVS307", `Admitting the browser frame failed: ${cause instanceof Error ? cause.message : String(cause)}`),
                         ],
                     });
                 }
@@ -849,17 +1220,17 @@ export const startVisualServer = async (options) => {
                 }
             });
         });
-        socket.on('error', (error) => {
+        socket.on("error", (error) => {
             // ws refuses an oversized frame before buffering it, which is exactly the
             // byte ceiling the protocol calls a freeze.
-            const code = typeof error === 'object' && error !== null && 'code' in error
+            const code = typeof error === "object" && error !== null && "code" in error
                 ? error.code
                 : undefined;
-            if (code === 'WS_ERR_UNSUPPORTED_MESSAGE_LENGTH') {
-                freeze('message-bytes');
+            if (code === "WS_ERR_UNSUPPORTED_MESSAGE_LENGTH") {
+                freeze("message-bytes");
             }
         });
-        socket.on('close', (code) => {
+        socket.on("close", (code) => {
             if (!registered)
                 return;
             connections.delete(connectionId);
@@ -883,19 +1254,19 @@ export const startVisualServer = async (options) => {
                 socket.close(1011);
                 return;
             }
-            sendFrame(socket, { kind: 'ready', snapshot: snapshot() });
+            sendFrame(socket, { kind: "ready", snapshot: snapshot() });
         });
     };
     // ------------------------------------------------------------- agent routes
     const answerPoll = (server, query) => {
-        const raw = query.get('after') ?? '0';
+        const raw = query.get("after") ?? "0";
         const after = Number(raw);
         if (!Number.isSafeInteger(after) || after < 0) {
             refuse(server, 400, `Query "after" must be a sequence, not "${raw}"`);
             return;
         }
         const immediate = takeDelivery(after);
-        if (!immediate.waiting || active.lifecycle !== 'running') {
+        if (!immediate.waiting || active.lifecycle !== "running") {
             respondJson(server, 200, immediate);
             return;
         }
@@ -908,51 +1279,11 @@ export const startVisualServer = async (options) => {
             }, agentPollMs),
         };
         polls.add(poll);
-        server.on('close', () => {
+        server.on("close", () => {
             if (polls.delete(poll))
                 clearTimeout(poll.timer);
         });
     };
-    const replaceModel = async (response) => {
-        const compiled = await compileVisualModel({
-            model: response.payload.model,
-            command: request.compiler,
-            paths,
-            now,
-            signal: compilerAbort.signal,
-        });
-        if (compiled.ok) {
-            rendered = await renderCompiled(compiled.compiled);
-            broadcast({ kind: 'model', model: rendered });
-            return { model: rendered, diagnostics: [] };
-        }
-        // The candidate is discarded and the last good rendering stays live; the
-        // browser learns why from a journaled diagnostic response.
-        const diagnostic = {
-            format: 'yarramate/visual-response/v1',
-            sessionId,
-            responseId: drawHex(16),
-            eventId: response.eventId,
-            type: 'diagnostic',
-            timestamp: stamp(),
-            payload: { diagnostics: compiled.diagnostics },
-        };
-        const appended = await appendVisualResponse(paths, diagnostic);
-        if (appended.ok)
-            transcriptBytes = appended.transcriptBytes;
-        // A journal that refused the explanation is still a journal that reached a
-        // limit, and the limit outlives this response.
-        else if (appended.freeze !== undefined)
-            freeze(appended.freeze);
-        broadcast({ kind: 'response', response: diagnostic });
-        // The diagnostic is the answer to the event the replacement was answering,
-        // and it is the only one that event will get. It retires the turn exactly
-        // as an agent-posted diagnostic would, so the reviewer's next message is
-        // deliverable instead of waiting behind a turn nobody will ever close.
-        markAnswered(diagnostic);
-        completeTurn(diagnostic);
-        return { diagnostics: compiled.diagnostics };
-    };
     /**
      * Events a turn-completing response has already answered.
      *
@@ -1002,7 +1333,7 @@ export const startVisualServer = async (options) => {
             respondJson(server, 409, {
                 accepted: false,
                 diagnostics: [
-                    serverDiagnostic('YMVS126', `Response belongs to session "${response.sessionId}", not "${sessionId}"`, '/sessionId'),
+                    serverDiagnostic("YMVS126", `Response belongs to session "${response.sessionId}", not "${sessionId}"`, "/sessionId"),
                 ],
             });
             return;
@@ -1010,30 +1341,61 @@ export const startVisualServer = async (options) => {
         // The agent cannot hold a conversation a diagram-only session never
         // offered; the browser has nowhere to show one.
         if (!capabilities.chat &&
-            (response.type === 'chat.response' || response.type === 'choice.present')) {
+            (response.type === "chat.response" || response.type === "choice.present")) {
             respondJson(server, 409, {
                 accepted: false,
                 diagnostics: [
-                    serverDiagnostic('YMVS309', `Session did not grant the capability "${response.type}" needs`, '/type'),
+                    serverDiagnostic("YMVS309", `Session did not grant the capability "${response.type}" needs`, "/type"),
                 ],
             });
             return;
         }
+        // A chat filter is a query, not a match set (ADR 0090). The agent states
+        // what to filter by; the runtime evaluates it through `filterMatchedIds`
+        // - the same evaluator, over the same compiled graph, that a `filter.query`
+        // event from the panel goes through - so a chat filter and a panel filter
+        // carrying the same query can never highlight different subjects. The
+        // resolution happens here, before the append, so the transcript records
+        // what the browser was actually shown.
+        let delivered = response;
+        if (response.type === "chat.response" &&
+            response.payload.appliedQuery !== undefined) {
+            const applied = response.payload.appliedQuery;
+            if (applied.matchedIds !== undefined) {
+                respondJson(server, 400, {
+                    accepted: false,
+                    diagnostics: [
+                        serverDiagnostic("YMVS311", "A chat filter states a query and the runtime resolves the match set; send appliedQuery.query without matchedIds", "/payload/appliedQuery/matchedIds"),
+                    ],
+                });
+                return;
+            }
+            delivered = {
+                ...response,
+                payload: {
+                    ...response.payload,
+                    appliedQuery: {
+                        query: applied.query,
+                        matchedIds: filterMatchedIds(applied.query),
+                    },
+                },
+            };
+        }
         const result = await admit(async () => {
             // Same race as a browser frame: a request already on the chain must not
             // append to a session recovery has begun reading.
-            if (active.lifecycle !== 'running') {
+            if (active.lifecycle !== "running") {
                 return {
                     code: 503,
                     body: {
                         accepted: false,
                         diagnostics: [
-                            serverDiagnostic('YMVS306', `Session is ${active.lifecycle} and no longer accepts responses`),
+                            serverDiagnostic("YMVS306", `Session is ${active.lifecycle} and no longer accepts responses`),
                         ],
                     },
                 };
             }
-            const appended = await appendVisualResponse(paths, response);
+            const appended = await appendVisualResponse(paths, delivered);
             if (!appended.ok) {
                 if (appended.freeze !== undefined)
                     freeze(appended.freeze);
@@ -1056,21 +1418,17 @@ export const startVisualServer = async (options) => {
                     },
                 };
             }
-            recordResponse(response);
-            markAnswered(response);
-            broadcast({ kind: 'response', response });
-            const replaced = response.type === 'model.replace'
-                ? await replaceModel(response)
-                : { diagnostics: [] };
-            completeTurn(response);
+            recordResponse(delivered);
+            markAnswered(delivered);
+            broadcast({ kind: "response", response: delivered });
+            completeTurn(delivered);
             return {
                 code: 200,
                 body: {
                     accepted: true,
                     duplicate: false,
                     lastSequence,
-                    ...(replaced.model === undefined ? {} : { model: replaced.model }),
-                    diagnostics: replaced.diagnostics,
+                    diagnostics: [],
                 },
             };
         });
@@ -1083,16 +1441,16 @@ export const startVisualServer = async (options) => {
             refuse(server, body.status, body.message);
             return;
         }
-        const asked = typeof body.value === 'object' && body.value !== null
+        const asked = typeof body.value === "object" && body.value !== null
             ? body.value
             : {};
         const reason = asked.reason;
-        if (typeof reason !== 'string' || TERMINATION_REASONS[reason] !== true) {
-            refuse(server, 400, 'Stop requires a known termination reason');
+        if (typeof reason !== "string" || TERMINATION_REASONS[reason] !== true) {
+            refuse(server, 400, "Stop requires a known termination reason");
             return;
         }
         if (asked.includeTranscript !== undefined &&
-            typeof asked.includeTranscript !== 'boolean') {
+            typeof asked.includeTranscript !== "boolean") {
             refuse(server, 400, 'Stop takes a boolean "includeTranscript" or none');
             return;
         }
@@ -1100,58 +1458,58 @@ export const startVisualServer = async (options) => {
         // teardown. The response that wins the stop does not get to close its
         // concurrent callers before they can observe the same result.
         const closed = await stop(reason, asked.includeTranscript);
-        server.on('finish', () => responseSocket.end());
+        server.on("finish", () => responseSocket.end());
         respondJson(server, 200, closed);
     };
     const serveAgent = async (incoming, server, pathname, query) => {
         // An agent is not a browser. A request carrying an Origin came from a page,
         // which must never be able to spend a leaked agent capability.
         if (incoming.headers.origin !== undefined) {
-            refuse(server, 403, 'Agent routes reject browser-originated requests');
+            refuse(server, 403, "Agent routes reject browser-originated requests");
             return;
         }
         if (!secretEquals(session.agentToken, bearerToken(incoming.headers.authorization))) {
-            refuse(server, 401, 'Agent capability required');
+            refuse(server, 401, "Agent capability required");
             return;
         }
         agentAttached = true;
-        if (pathname === '/api/agent/events') {
-            if (incoming.method !== 'GET')
-                return refuse(server, 405, 'Use GET');
+        if (pathname === "/api/agent/events") {
+            if (incoming.method !== "GET")
+                return refuse(server, 405, "Use GET");
             answerPoll(server, query);
             return;
         }
-        if (pathname === '/api/agent/status') {
-            if (incoming.method !== 'GET')
-                return refuse(server, 405, 'Use GET');
+        if (pathname === "/api/agent/status") {
+            if (incoming.method !== "GET")
+                return refuse(server, 405, "Use GET");
             respondJson(server, 200, status());
             return;
         }
-        if (pathname === '/api/agent/responses') {
-            if (incoming.method !== 'POST')
-                return refuse(server, 405, 'Use POST');
+        if (pathname === "/api/agent/responses") {
+            if (incoming.method !== "POST")
+                return refuse(server, 405, "Use POST");
             await acceptResponse(server, incoming);
             return;
         }
-        if (pathname === '/api/agent/stop') {
-            if (incoming.method !== 'POST')
-                return refuse(server, 405, 'Use POST');
+        if (pathname === "/api/agent/stop") {
+            if (incoming.method !== "POST")
+                return refuse(server, 405, "Use POST");
             await acceptStop(server, incoming);
             return;
         }
-        refuse(server, 404, 'No such route');
+        refuse(server, 404, "No such route");
     };
     // ----------------------------------------------------------- browser routes
     const assetPath = (pathname) => {
-        if (pathname === '/')
-            return join(assetRoot, 'index.html');
-        const prefix = '/assets/';
+        if (pathname === "/")
+            return join(assetRoot, "index.html");
+        const prefix = "/assets/";
         if (!pathname.startsWith(prefix))
             return undefined;
         const name = pathname.slice(prefix.length);
         if (!ASSET_NAME.test(name))
             return undefined;
-        const target = resolve(assetRoot, 'assets', name);
+        const target = resolve(assetRoot, "assets", name);
         // The name cannot carry a separator, so this only confirms what the pattern
         // already guaranteed — which is the point of having both.
         return target.startsWith(`${assetRoot}${sep}`) ? target : undefined;
@@ -1160,26 +1518,26 @@ export const startVisualServer = async (options) => {
         const target = assetPath(pathname);
         const contentType = target === undefined ? undefined : CONTENT_TYPES[extname(target)];
         if (target === undefined || contentType === undefined) {
-            refuse(server, 404, 'No such asset');
+            refuse(server, 404, "No such asset");
             return;
         }
         try {
             // lstat, never stat: a symlink inside the asset root is a link out of it.
             const entry = await lstat(target);
             if (!entry.isFile()) {
-                refuse(server, 404, 'No such asset');
+                refuse(server, 404, "No such asset");
                 return;
             }
             respond(server, 200, await readFile(target), contentType);
         }
         catch {
-            refuse(server, 404, 'No such asset');
+            refuse(server, 404, "No such asset");
         }
     };
     const serveBootstrap = (server, query) => {
-        const key = query.get('key') ?? undefined;
+        const key = query.get("key") ?? undefined;
         if (bootstrapSpent || !secretEquals(session.browserToken, key)) {
-            refuse(server, 403, 'Bootstrap capability is not valid');
+            refuse(server, 403, "Bootstrap capability is not valid");
             return;
         }
         // One-time by construction: the URL capability buys exactly one cookie, and
@@ -1188,70 +1546,70 @@ export const startVisualServer = async (options) => {
         bootstrapSpent = true;
         server.writeHead(303, {
             ...browserHeaders,
-            Location: '/',
-            'Set-Cookie': `${COOKIE_NAME}=${browserAuthenticator}; HttpOnly; SameSite=Strict; Secure; Path=/`,
-            'Content-Length': 0,
+            Location: "/",
+            "Set-Cookie": `${COOKIE_NAME}=${browserAuthenticator}; HttpOnly; SameSite=Strict; Secure; Path=/`,
+            "Content-Length": 0,
         });
         server.end();
     };
     const serveBrowser = async (incoming, server, pathname, query) => {
         const sent = incoming.headers.origin;
         if (sent !== undefined && sent !== origin) {
-            refuse(server, 403, 'Origin is not this session');
+            refuse(server, 403, "Origin is not this session");
             return;
         }
-        if (incoming.method !== 'GET') {
-            refuse(server, 405, 'Use GET');
+        if (incoming.method !== "GET") {
+            refuse(server, 405, "Use GET");
             return;
         }
-        if (pathname === '/bootstrap') {
+        if (pathname === "/bootstrap") {
             serveBootstrap(server, query);
             return;
         }
         if (!secretEquals(browserAuthenticator, cookieValue(incoming.headers.cookie, COOKIE_NAME))) {
-            refuse(server, 401, 'Session cookie required');
+            refuse(server, 401, "Session cookie required");
             return;
         }
-        if (pathname === '/api/session') {
+        if (pathname === "/api/session") {
             respondJson(server, 200, snapshot());
             return;
         }
         await serveAsset(server, pathname);
     };
-    httpServer.on('request', (incoming, server) => {
+    httpServer.on("request", (incoming, server) => {
         const responseSocket = incoming.socket;
         unclassifiedHttpSockets.delete(responseSocket);
-        if ((incoming.url ?? '/').split('?')[0] === '/api/agent/stop') {
+        if ((incoming.url ?? "/").split("?")[0] === "/api/agent/stop") {
             stopResponseSockets.add(responseSocket);
             const releaseResponseSocket = () => {
                 stopResponseSockets.delete(responseSocket);
             };
-            server.once('finish', releaseResponseSocket);
-            server.once('close', releaseResponseSocket);
+            server.once("finish", releaseResponseSocket);
+            server.once("close", releaseResponseSocket);
         }
         void (async () => {
             try {
                 // Rebinding defence: a request that reached this port under any other
                 // name was routed here by something other than the browser we started.
                 if (incoming.headers.host !== authority) {
-                    refuse(server, 403, 'Host is not the bound loopback authority');
+                    refuse(server, 403, "Host is not the bound loopback authority");
                     return;
                 }
-                const [rawPath = '/', rawQuery = ''] = (incoming.url ?? '/').split('?');
+                const [rawPath = "/", rawQuery = ""] = (incoming.url ?? "/").split("?");
                 let pathname;
                 try {
                     pathname = decodeURIComponent(rawPath);
                 }
                 catch {
-                    refuse(server, 400, 'Request target is not a valid URL path');
+                    refuse(server, 400, "Request target is not a valid URL path");
                     return;
                 }
-                if (pathname.includes('\0')) {
-                    refuse(server, 400, 'Request target is not a valid URL path');
+                if (pathname.includes("\0")) {
+                    refuse(server, 400, "Request target is not a valid URL path");
                     return;
                 }
                 const query = new URLSearchParams(rawQuery);
-                if (pathname.startsWith('/api/agent/')) {
+                if (pathname.startsWith("/api/agent/")) {
                     await serveAgent(incoming, server, pathname, query);
                     return;
                 }
@@ -1261,31 +1619,31 @@ export const startVisualServer = async (options) => {
                 if (server.headersSent)
                     server.destroy(cause);
                 else
-                    refuse(server, 500, 'Session server failed');
+                    refuse(server, 500, "Session server failed");
             }
         })();
     });
-    httpServer.on('upgrade', (incoming, socket, head) => {
+    httpServer.on("upgrade", (incoming, socket, head) => {
         const deny = (code, message) => {
             socket.write(`HTTP/1.1 ${code} ${message}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
             socket.destroy();
         };
-        if (active.lifecycle !== 'running')
-            return deny(503, 'Service Unavailable');
+        if (active.lifecycle !== "running")
+            return deny(503, "Service Unavailable");
         if (incoming.headers.host !== authority)
-            return deny(403, 'Forbidden');
+            return deny(403, "Forbidden");
         // An upgrade always carries an Origin, so it is checked without exception.
         if (incoming.headers.origin !== origin)
-            return deny(403, 'Forbidden');
-        const [rawPath = '/'] = (incoming.url ?? '/').split('?');
+            return deny(403, "Forbidden");
+        const [rawPath = "/"] = (incoming.url ?? "/").split("?");
         if (rawPath !== VISUAL_SOCKET_PATH)
-            return deny(404, 'Not Found');
+            return deny(404, "Not Found");
         if (!secretEquals(browserAuthenticator, cookieValue(incoming.headers.cookie, COOKIE_NAME))) {
-            return deny(401, 'Unauthorized');
+            return deny(401, "Unauthorized");
         }
         if (connections.size + browserConnectionReservations >=
             VISUAL_SERVER_LIMITS.browserConnections) {
-            return deny(503, 'Service Unavailable');
+            return deny(503, "Service Unavailable");
         }
         browserConnectionReservations += 1;
         try {
@@ -1310,14 +1668,14 @@ export const startVisualServer = async (options) => {
         const attempt = (async () => {
             // Frozen before anything is torn down: a request already on the wire
             // must not be journaled behind the recovery this stop is about to read.
-            active.lifecycle = 'draining';
+            active.lifecycle = "draining";
             listening = false;
             disarmGrace();
             // Waiting agents are answered before any socket is torn down, so a poll
             // in flight during a stop still receives its non-terminal idle result.
             settleAllPolls();
             for (const socket of connections.values()) {
-                sendFrame(socket, { kind: 'closing', reason });
+                sendFrame(socket, { kind: "closing", reason });
                 socket.close(1001);
             }
             sockets.close();
@@ -1341,7 +1699,7 @@ export const startVisualServer = async (options) => {
             // The transcript is read once, here, and only if this stop asked for it;
             // the same read is what removes the marked root.
             const removed = await removeVisualSession(paths, includeTranscript);
-            active.lifecycle = 'stopped';
+            active.lifecycle = "stopped";
             const outcome = {
                 reason,
                 alreadyStopped: false,
@@ -1369,7 +1727,7 @@ export const startVisualServer = async (options) => {
     let started;
     try {
         await writeVisualSessionDescriptor(paths, {
-            format: 'yarramate/visual-session-descriptor/v1',
+            format: "yarramate/visual-session-descriptor/v1",
             protocolVersion: VISUAL_PROTOCOL_VERSION,
             sessionId,
             origin,
@@ -1379,7 +1737,7 @@ export const startVisualServer = async (options) => {
             createdAt: stamp(),
         });
         started = {
-            format: 'yarramate/visual-session-started/v1',
+            format: "yarramate/visual-session-started/v1",
             protocolVersion: VISUAL_PROTOCOL_VERSION,
             sessionId,
             authority: request.authority,
@@ -1395,12 +1753,12 @@ export const startVisualServer = async (options) => {
         };
         const validated = parseVisualSessionStarted(started);
         if (!validated.ok) {
-            throw serverError(validated.diagnostics[0]?.code ?? 'YMVS102', `Started session is invalid: ${validated.diagnostics[0]?.message ?? 'unknown violation'}`);
+            throw serverError(validated.diagnostics[0]?.code ?? "YMVS102", `Started session is invalid: ${validated.diagnostics[0]?.message ?? "unknown violation"}`);
         }
     }
     catch (cause) {
         return abandon(cause);
     }
-    active.lifecycle = 'running';
+    active.lifecycle = "running";
     return { started, closed, status, stop: (reason) => stop(reason) };
 };