mockpit 1.1.0 → 1.2.0

package/dist/server/app.js

@@ -2,11 +2,15 @@ import { Hono } from "hono";
 import { bodyLimit } from "hono/body-limit";
 import { getCookie, setCookie } from "hono/cookie";
 import { streamSSE } from "hono/streaming";
+import { ICON_SIZES, ICON_SVG, themeColor, webManifest } from "./appIcon.js";
+import { ICON_PNG_BASE64 } from "./appIconPng.js";
 import { decodeBase64 } from "./base64.js";
 import { mockDetailView, mockSummaryView, sessionRowView, surfaceRef } from "./apiViews.js";
+import { askNudges } from "./askNudges.js";
 import { EventBus } from "./events.js";
 import { GUIDE_TOPICS, isGuideTopic, renderBriefGuide, unknownTopicMessage, } from "./designGuide.js";
 import { buildFeedbackBatches } from "./feedbackBatch.js";
+import { HANDOFF_NOTE, handoffReady, supersedes } from "./handoff.js";
 import { bundledIconSets, expandIcons, iconCount, isIconName, mayHaveIcons, parseIconSet, resolverFor, } from "./icons.js";
 import { checkProjectKit, KIT_IDS, kitSummaries } from "./kits.js";
 import { checkKnobs, checkKnobValues, discreteChoices } from "./knobs.js";
@@ -20,7 +24,7 @@ import { logMiddleware, writeLog } from "./eventLog.js";
 import { RUN_API } from "./runApi.js";
 import { escapeHtml, renderHtmlPage, renderMermaidPage, renderSandboxedPart, STATIC_ASSET_PREFIX, staticAsset, } from "./surfacePage.js";
 import { DEFAULT_MODE, DEFAULT_THEME_ID, isMode, themeById } from "./themes.js";
-import { BUILTIN_ASK_ID, builtinAsk, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, MAX_ASSET_BYTES, newId, openCount, OTHER_ID, projectFromCwd, reservedAgent, slugify, surfacesByteLength, } from "./types.js";
+import { builtinAsk, DEFAULT_PROJECT, DEFAULT_VARIANT, htmlSurface, isSandboxedSurfaceKind, ATTACHABLE_IMAGE_TYPES, MAX_ASK_IMAGES, MAX_ASSET_BYTES, newId, openCount, OTHER_ID, REACTIONS, projectFromCwd, reservedAgent, slugify, surfacesByteLength, } from "./types.js";
 import { coerceSurfaces, validateSurfaces, } from "./postSurfaces.js";
 const MAX_SURFACE_BYTES = 2 * 1024 * 1024;
 // A held long-poll (watch, the viewer) re-arms rather than pinning a socket
@@ -166,6 +170,12 @@ const MAX_LABEL = 120;
 const MAX_ASKS = 20;
 const MAX_OPTIONS = 20;
 const MAX_DRAFT_COMMENTS = 50;
+const APP_FILES = new Set([
+    "/manifest.webmanifest",
+    "/icon.svg",
+    "/apple-touch-icon.png",
+    ...ICON_SIZES.map((s) => `/icon-${s}.png`),
+]);
 const titleFromSlug = (slug) => slug.replace(/-/g, " ").replace(/^./, (ch) => ch.toUpperCase());
 export function createApp({ store, viewerHtml, setupText, topics = {}, authenticate, authToken, basePath, publicRead, screenshots, version, upgradeCommand, fetchLatestRelease, onEvent, maxHoldConnections = DEFAULT_MAX_HOLD_CONNECTIONS, executor, runLimits, log, }) {
     const app = new Hono();
@@ -331,31 +341,93 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         return value;
     }
     // --- shared flows (used by both the REST API and the MCP endpoint) ---
+    // Sessions with an author=user long-poll held open right now: a waiting
+    // `mockpit watch` is a live agent, whatever its agentActiveAt says.
+    const listening = new Map();
     // User comments the agent has not seen yet ride along on its next write, so
     // agents hear feedback without blocking on the long-poll. The cursor also
     // advances past the agent's own comments to keep reads cheap.
-    async function collectFeedback(sessionId) {
+    async function collectFeedback(sessionId, base) {
+        // Touch before reading the cursor: a taker's handOff checks agentActiveAt,
+        // so it can't move this cursor under a read already in flight.
+        await store.touchAgent(sessionId);
         const session = await store.getSession(sessionId);
         if (!session)
             return [];
+        const handedOff = await takeOrphaned(session);
         const fresh = await store.listComments({ sessionId, afterSeq: session.agentSeq });
-        if (fresh.length === 0)
-            return [];
-        await store.markAgentSeen(sessionId, fresh[fresh.length - 1].seq);
-        bus.broadcast({ type: "comment-delivered", sessionId, seq: fresh[fresh.length - 1].seq });
+        if (fresh.length > 0) {
+            await store.markAgentSeen(sessionId, fresh[fresh.length - 1].seq);
+            bus.broadcast({ type: "comment-delivered", sessionId, seq: fresh[fresh.length - 1].seq });
+        }
         const feedback = fresh.filter((cm) => cm.author === "user");
-        return feedback.length > 0 ? await buildFeedbackBatches(store, feedback) : [];
+        return feedbackWithHandoffs(feedback, handedOff, base);
+    }
+    async function feedbackWithHandoffs(own, handedOff, base) {
+        const mine = own.length > 0 ? await buildFeedbackBatches(store, own, base) : [];
+        if (handedOff.length === 0)
+            return mine;
+        const theirs = await buildFeedbackBatches(store, handedOff, base);
+        return [...mine, ...theirs.map((b) => ({ ...b, handoff: HANDOFF_NOTE }))];
+    }
+    // The user comments still owed to sessions `taker` supersedes (handoff.ts),
+    // taken for `taker`: each owner's cursor moves past them in one conditional
+    // write, so delivery stays exactly-once across sessions.
+    async function takeOrphaned(taker) {
+        if (!taker.project)
+            return [];
+        const now = Date.now();
+        const taken = [];
+        for (const owner of await store.listSessions(taker.project)) {
+            if (!supersedes(taker, owner, listening.has(owner.id)))
+                continue;
+            const owed = await store.listComments({ sessionId: owner.id, afterSeq: owner.agentSeq });
+            // Seq order is time order, so the ready comments are a prefix; stop at the
+            // first one still inside its grace and leave the rest owed.
+            let upto = owner.agentSeq;
+            const take = [];
+            for (const c of owed) {
+                if (c.author === "user" && !handoffReady(c, owner, taker, now))
+                    break;
+                upto = c.seq;
+                if (c.author === "user")
+                    take.push(c);
+            }
+            if (take.length === 0)
+                continue;
+            if (!(await store.handOff(owner.id, owner, upto)))
+                continue;
+            bus.broadcast({ type: "comment-delivered", sessionId: owner.id, seq: upto });
+            taken.push(...take);
+        }
+        return taken;
     }
     // Per-comment delivery state for the viewer: `delivered` once the session's
-    // agentSeq has passed the comment. Computed, never stored.
+    // agentSeq has passed the comment. Computed, never stored. `ownerGone` marks
+    // an undelivered user comment whose session a newer one already supersedes,
+    // so the Thread can say the next agent here will get it.
     async function withDelivered(comments) {
-        const cursors = new Map();
+        const sessions = new Map();
         for (const c of comments) {
-            if (!cursors.has(c.sessionId)) {
-                cursors.set(c.sessionId, (await store.getSession(c.sessionId))?.agentSeq ?? 0);
+            if (!sessions.has(c.sessionId))
+                sessions.set(c.sessionId, await store.getSession(c.sessionId));
+        }
+        const gone = new Map();
+        const ownerGone = async (owner) => {
+            if (!gone.has(owner.id)) {
+                const peers = owner.project ? await store.listSessions(owner.project) : [];
+                gone.set(owner.id, peers.some((t) => supersedes(t, owner, listening.has(owner.id))));
             }
+            return gone.get(owner.id);
+        };
+        const out = [];
+        for (const c of comments) {
+            const owner = sessions.get(c.sessionId);
+            const delivered = c.seq <= (owner?.agentSeq ?? 0);
+            const waiting = !delivered && !!owner && c.author === "user" && (await ownerGone(owner));
+            out.push({ ...c, delivered, ...(waiting ? { ownerGone: true } : {}) });
         }
-        return comments.map((c) => ({ ...c, delivered: c.seq <= (cursors.get(c.sessionId) ?? 0) }));
+        return out;
     }
     // The workspace's light/dark choice. Older workspaces stored a theme id under
     // `theme`; that registry is gone, so they start from the default mode.
@@ -669,8 +741,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const out = [];
         for (const [path, config] of Object.entries(knobs)) {
             const n = discreteChoices(config);
-            if (n !== null && n <= 3) {
-                out.push(`knob "${path}" has ${n} discrete options: if each option needs its own render, ask instead (ask with options bound to variants); keep a knob when one render plus a control shows it`);
+            if (n !== null && n >= 2 && n <= 3) {
+                out.push(`knob "${path}": a 2–3 option knob is a choice. Ask with options that \`set\` it.`);
             }
         }
         return out;
@@ -684,35 +756,67 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const names = live(state);
         if (names.length < 2)
             return null;
+        const applies = (a) => a.scope !== "part" && !(a.scope === "state" && a.state !== state);
         const bound = mock.asks.some((a) => {
-            if (a.scope === "part" || (a.scope === "state" && a.state !== state))
+            if (!applies(a))
                 return false;
             const variants = new Set(a.options.map((o) => o.variant));
             return names.every((n) => variants.has(n));
         });
         if (bound)
             return null;
+        const where = state === null ? mock.slug : `${mock.slug} state "${state}"`;
         const key = (list) => [...list].sort().join("\n");
         const states = mock.states.length ? mock.states : [null];
         const wide = states.every((s) => key(live(s)) === key(names));
+        // An ask that already picks between some of these variants is the question:
+        // a second, generic "Which one?" would make the user choose the look twice.
+        // A mock-wide one only fits while every state has the same variants; else a
+        // variant only some states have would leave the others no real choice.
+        const existing = mock.asks.find((a) => applies(a) && a.options.some((o) => o.variant) && (a.scope === "state" || wide));
+        if (existing) {
+            const have = new Set(existing.options.map((o) => o.variant));
+            const missing = names.filter((n) => !have.has(n));
+            const ask = {
+                id: existing.id,
+                text: existing.text,
+                scope: existing.scope,
+                ...(existing.state ? { state: existing.state } : {}),
+                ...(existing.multi ? { multi: true } : {}),
+                options: [
+                    ...existing.options.map((o) => ({
+                        id: o.id,
+                        label: o.label,
+                        ...(o.variant ? { variant: o.variant } : {}),
+                        ...(o.set ? { set: o.set } : {}),
+                    })),
+                    ...missing.map((v) => ({ label: v, variant: v })),
+                ],
+            };
+            return {
+                nudge: `${where}: bind ${missing.map((m) => `"${m}"`).join(", ")} to your existing ask "${existing.id}": call ask with suggestedAsk. Never ask in chat.`,
+                ask,
+            };
+        }
         const options = names.map((v) => ({ label: v, variant: v }));
+        // Not the built-in's reserved id: a stored ask under it would collide with the
+        // built-in the viewer synthesizes once a new variant goes unbound. Nor any id
+        // already taken, which sending this would silently replace.
+        const base = wide ? "look" : `look-${slugify(state ?? "")}`;
+        let id = base;
+        for (let n = 2; mock.asks.some((a) => a.id === id); n++)
+            id = `${base}-${n}`;
         const ask = wide
-            ? { id: BUILTIN_ASK_ID, text: "Which one?", scope: "mock", options }
-            : {
-                id: `${BUILTIN_ASK_ID}-${slugify(state ?? "")}`,
-                text: "Which one?",
-                scope: "state",
-                state,
-                options,
-            };
-        const where = state === null ? mock.slug : `${mock.slug} state "${state}"`;
+            ? { id, text: "Which one?", scope: "mock", options }
+            : { id, text: "Which one?", scope: "state", state, options };
         return {
-            nudge: `${where} has ${names.length} variants and no ask binds them: call ask with suggestedAsk (or your own question with options bound to the variants) so the user can choose in one Send; never ask in chat`,
+            nudge: `${where} has ${names.length} variants and no ask binds them: call ask with suggestedAsk. Never ask in chat.`,
             ask,
         };
     }
     // The answer to every write: what was published, the parts found per state,
-    // what moved since the previous version, and any feedback waiting.
+    // what moved since the previous version, and any feedback waiting — for the
+    // session that wrote, which on a new version may not be the variant's own.
     async function writeResult(mock, post, ctx, extra = {}) {
         const posts = await store.listPosts({ mockId: mock.id });
         const detail = mockDetailView(mock, posts);
@@ -723,7 +827,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             partChanges = diffParts(partsInSurfaces(extra.previous), partsInSurfaces(post.surfaces));
         }
         const warnings = await iconWarnings(mock.project, post.surfaces);
-        const feedback = await collectFeedback(post.sessionId);
+        const feedback = await collectFeedback(extra.writer?.id ?? post.sessionId, ctx.base);
         return ok({
             mock: {
                 id: mock.id,
@@ -947,7 +1051,12 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         announcePost(mock, updated, false);
         if (prompt && ctx.request)
             notifyPublish(mock, updated, prompt, ctx);
-        return writeResult(mock, updated, ctx, { previous: target.surfaces, applied, nudges });
+        return writeResult(mock, updated, ctx, {
+            previous: target.surfaces,
+            applied,
+            nudges,
+            writer: session,
+        });
     }
     // `parts`: new outer html per part ("name" or "name#key"), spliced into the
     // variant's html so a tweak costs the tweak rather than the whole document.
@@ -1231,7 +1340,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             text: added.map((a) => a.text).join(" · "),
             url: mockUrl(ctx.base, mock),
         });
-        const feedback = session ? await collectFeedback(session.id) : [];
+        const feedback = session ? await collectFeedback(session.id, ctx.base) : [];
+        const nudges = askNudges(added, mock.asks);
         return ok({
             mock: mock.slug,
             mockId: mock.id,
@@ -1239,11 +1349,12 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             asks: added,
             open: openCount(mock, posts),
             url: mockUrl(ctx.base, mock),
+            ...(nudges.length ? { nudges } : {}),
             feedback,
         });
     }
     // --- drafts and replies (the user's side; viewer origin only) ---
-    function sanitizePartComments(raw, mock) {
+    function sanitizePartComments(raw, mock, posts) {
         if (raw === undefined || raw === null)
             return [];
         if (!Array.isArray(raw))
@@ -1252,16 +1363,39 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return `at most ${MAX_DRAFT_COMMENTS} comments`;
         const out = [];
         for (const c of raw) {
+            const reaction = c?.reaction;
+            if (reaction !== undefined && !REACTIONS.includes(reaction))
+                return `reaction must be one of ${REACTIONS.join(", ")}`;
             const text = str(c?.text, MAX_COMMENT_TEXT);
-            if (!text)
+            if (!text && !reaction)
                 return "every comment needs text";
             const state = stateArg(c.state) ?? null;
             if (state !== null && !mock.states.includes(state))
                 return `${mock.slug} has no state "${state}"`;
             const part = str(c.part, 200) ?? null;
+            const variant = str(c.variant, 200);
+            if (variant && !posts.some((p) => p.variant === variant && p.state === state))
+                return `${mock.slug} has no variant "${variant}"${state ? ` in "${state}"` : ""}`;
             const a = c.anchor && typeof c.anchor === "object" ? c.anchor : null;
             const anchor = a ? sanitizePartAnchor(a) : undefined;
-            out.push({ part, state, text, ...(anchor ? { anchor } : {}) });
+            const next = {
+                part,
+                state,
+                text: text ?? "",
+                ...(anchor ? { anchor } : {}),
+                ...(reaction ? { reaction: reaction } : {}),
+                ...(variant ? { variant } : {}),
+            };
+            // One reaction per target: a later tap on the same part replaces the earlier one.
+            if (reaction) {
+                const same = out.findIndex((o) => o.reaction &&
+                    o.part === part &&
+                    o.state === state &&
+                    (o.variant ?? null) === (variant ?? null));
+                if (same >= 0)
+                    out.splice(same, 1);
+            }
+            out.push(next);
         }
         return out;
     }
@@ -1274,6 +1408,9 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             : undefined;
         const quote = str(a.quote, 200);
         const selector = str(a.selector, 500);
+        const width = typeof a.width === "number" && Number.isFinite(a.width) && a.width >= 1 && a.width <= 10000
+            ? Math.round(a.width)
+            : undefined;
         if (!offset && !box && !quote && !selector)
             return undefined;
         return {
@@ -1281,6 +1418,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             ...(quote ? { quote } : {}),
             ...(selector ? { selector } : {}),
             ...(box ? { box } : {}),
+            ...(width ? { width } : {}),
         };
     }
     // A stored ask, else the viewer's built-in variant ask under its reserved id.
@@ -1329,6 +1467,37 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         }
         return out;
     }
+    // askId → attached image ids: known asks, ids of stored raster images only,
+    // deduped and capped, empty lists dropped.
+    async function sanitizeAskImages(raw, mock, posts, key) {
+        if (raw === undefined || raw === null)
+            return {};
+        if (typeof raw !== "object" || Array.isArray(raw))
+            return `"${key}" must be an object`;
+        const out = {};
+        for (const [askId, value] of Object.entries(raw)) {
+            if (!askById(mock, posts, askId))
+                return `${mock.slug} has no ask "${askId}"`;
+            if (!Array.isArray(value) || value.some((id) => typeof id !== "string")) {
+                return `${key} "${askId}" must be a list of asset ids`;
+            }
+            const ids = [...new Set(value)];
+            if (ids.length > MAX_ASK_IMAGES) {
+                return `${key} "${askId}" takes at most ${MAX_ASK_IMAGES} images`;
+            }
+            for (const id of ids) {
+                const asset = await store.getAsset(id);
+                if (!asset)
+                    return `asset "${id}" not found`;
+                if (!ATTACHABLE_IMAGE_TYPES.has(asset.contentType)) {
+                    return `asset "${id}" is not an attachable image`;
+                }
+            }
+            if (ids.length)
+                out[askId] = ids;
+        }
+        return out;
+    }
     function sanitizeMix(raw, posts) {
         if (raw === undefined || raw === null)
             return {};
@@ -1348,7 +1517,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     }
     // A draft, validated against the mock as it is now: unknown asks, options,
     // variants, knob paths or out-of-range values are refused, never stored.
-    function sanitizeDraft(raw, mock, posts, base) {
+    async function sanitizeDraft(raw, mock, posts, base) {
         const pick = (key) => (raw?.[key] !== undefined ? raw[key] : base?.[key]);
         const answers = sanitizeAnswers(pick("answers"), mock, posts);
         if (typeof answers === "string")
@@ -1359,7 +1528,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const tuned = checkKnobValues(pick("tuned"), mock, posts, "tuned");
         if (!tuned.ok)
             return tuned.error;
-        const comments = sanitizePartComments(pick("comments"), mock);
+        const comments = sanitizePartComments(pick("comments"), mock, posts);
         if (typeof comments === "string")
             return comments;
         const others = sanitizeAskTexts(pick("others"), mock, posts, "others");
@@ -1368,6 +1537,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const notes = sanitizeAskTexts(pick("notes"), mock, posts, "notes");
         if (typeof notes === "string")
             return notes;
+        const otherImages = await sanitizeAskImages(pick("otherImages"), mock, posts, "otherImages");
+        if (typeof otherImages === "string")
+            return otherImages;
+        const noteImages = await sanitizeAskImages(pick("noteImages"), mock, posts, "noteImages");
+        if (typeof noteImages === "string")
+            return noteImages;
+        for (const askId of Object.keys(otherImages))
+            others[askId] ??= "";
+        for (const askId of Object.keys(noteImages))
+            notes[askId] ??= "";
         for (const askId of Object.keys(others)) {
             const ask = askById(mock, posts, askId);
             if (!ask?.multi && answers[askId] !== undefined)
@@ -1385,6 +1564,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             comments,
             others,
             notes,
+            ...(Object.keys(otherImages).length ? { otherImages } : {}),
+            ...(Object.keys(noteImages).length ? { noteImages } : {}),
             updatedAt: new Date().toISOString(),
         };
     }
@@ -1406,7 +1587,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        const draft = sanitizeDraft(body, mock, posts, null);
+        const draft = await sanitizeDraft(body, mock, posts, null);
         if (typeof draft === "string")
             return fail(400, draft);
         await store.putDraft(mock.id, draft);
@@ -1491,13 +1672,22 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (answer !== undefined || other !== undefined) {
             delete next.answer;
             delete next.other;
+            delete next.otherImages;
             if (answer !== undefined)
                 next.answer = answer;
             if (other !== undefined)
                 next.other = other;
+            const images = draft.otherImages?.[a.id];
+            if (other !== undefined && images)
+                next.otherImages = images;
         }
-        if (note !== undefined)
+        if (note !== undefined) {
             next.note = note;
+            delete next.noteImages;
+            const images = draft.noteImages?.[a.id];
+            if (images)
+                next.noteImages = images;
+        }
         return next;
     }
     // Send: the user's one batched answer becomes one kind:"reply" comment on the
@@ -1510,7 +1700,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (isResult(mock))
             return mock;
         const posts = await store.listPosts({ mockId: mock.id });
-        const draft = sanitizeDraft(body ?? {}, mock, posts, mock.draft);
+        const draft = await sanitizeDraft(body ?? {}, mock, posts, mock.draft);
         if (typeof draft === "string")
             return fail(400, draft);
         const text = str(body?.text, MAX_COMMENT_TEXT);
@@ -1540,6 +1730,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             comments: draft.comments,
             ...(Object.keys(draft.others ?? {}).length ? { others: draft.others } : {}),
             ...(Object.keys(draft.notes ?? {}).length ? { notes: draft.notes } : {}),
+            ...(draft.otherImages ? { otherImages: draft.otherImages } : {}),
+            ...(draft.noteImages ? { noteImages: draft.noteImages } : {}),
             ...(text ? { text } : {}),
             ...(decision ? { decision } : {}),
         };
@@ -1865,7 +2057,7 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     }
     // The agent's plain-text message in a mock's thread. Stored as text and
     // rendered as a text node, never as HTML. A write, so feedback rides along.
-    async function sayFlow(ref, body) {
+    async function sayFlow(ref, body, ctx) {
         if (!body || typeof body !== "object")
             return fail(400, "invalid JSON body");
         const text = typeof body.message === "string" ? str(body.message, MAX_COMMENT_TEXT) : undefined;
@@ -1889,10 +2081,15 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (!comment)
             return fail(404, "session not found");
         announceComment(comment);
-        return ok({ feedback: await collectFeedback(comment.sessionId) }, 201);
+        return ok({ feedback: await collectFeedback(comment.sessionId, ctx.base) }, 201);
     }
     // Long-poll: resolves as soon as a matching comment lands, or at timeout.
     async function waitForComments(q, signal) {
+        // The agent listening for its feedback: it is alive, and it may take
+        // replies owed to a session it superseded (handoff.ts).
+        const listener = q.agent && q.author === "user" ? q.sessionId : undefined;
+        if (listener)
+            await store.touchAgent(listener);
         // An author=user session wait with no explicit cursor resumes from the
         // session's agentSeq — "where the agent left off" lives server-side so the
         // CLI, both MCP transports, and piggyback share one exactly-once stream.
@@ -1900,12 +2097,19 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         if (afterSeq === undefined && q.author === "user" && q.sessionId) {
             afterSeq = (await store.getSession(q.sessionId))?.agentSeq;
         }
+        const takeOrphanedFor = async (id) => {
+            const taker = id ? await store.getSession(id) : null;
+            return taker ? await takeOrphaned(taker) : [];
+        };
+        let handedOff = await takeOrphanedFor(listener);
         const query = { sessionId: q.sessionId, mockId: q.mockId, postId: q.postId, afterSeq };
         const matches = (list) => q.author ? list.filter((cm) => cm.author === q.author) : list;
         const wait = Math.min(Math.max(q.waitSeconds, 0), MAX_WAIT_SECONDS);
         let all = await store.listComments(query);
         let comments = matches(all);
-        if (comments.length === 0 && wait > 0) {
+        if (comments.length === 0 && handedOff.length === 0 && wait > 0) {
+            if (listener)
+                listening.set(listener, (listening.get(listener) ?? 0) + 1);
             await new Promise((resolve) => {
                 const timer = setTimeout(done, wait * 1000);
                 const unsubscribe = bus.subscribe((event) => {
@@ -1934,10 +2138,20 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     resolve();
                 }
             });
+            if (listener) {
+                const n = (listening.get(listener) ?? 1) - 1;
+                if (n > 0)
+                    listening.set(listener, n);
+                else
+                    listening.delete(listener);
+            }
             // A caller that gave up can't receive this batch, so delivering it would
             // advance the cursor past feedback no agent ever saw.
             if (signal?.aborted)
-                return { comments: [], lastSeq: afterSeq ?? 0 };
+                return { comments: [], lastSeq: afterSeq ?? 0, handedOff: [] };
+            if (listener)
+                await store.touchAgent(listener);
+            handedOff = await takeOrphanedFor(listener);
             all = await store.listComments(query);
             comments = matches(all);
         }
@@ -1950,13 +2164,13 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             await store.markAgentSeen(q.sessionId, lastSeq);
             bus.broadcast({ type: "comment-delivered", sessionId: q.sessionId, seq: lastSeq });
         }
-        return { comments, lastSeq };
+        return { comments, lastSeq, handedOff };
     }
     // The watch long-poll's answer: comments plus the batched feedback built
     // from them.
-    async function listenFlow(q, signal) {
-        const result = await waitForComments({ ...q, agent: true }, signal);
-        const feedback = await buildFeedbackBatches(store, result.comments);
+    async function listenFlow(q, base, signal) {
+        const { handedOff, ...result } = await waitForComments({ ...q, agent: true }, signal);
+        const feedback = await feedbackWithHandoffs(result.comments, handedOff, base);
         return ok({ ...result, feedback });
     }
     // What the user is doing right now, per mock: derived from the SSE registry
@@ -1976,14 +2190,14 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     });
     // The feedback verb: never blocks. Takes what the session has not heard yet
     // (the same cursor as piggyback and watch) plus `pending` for the project.
-    async function feedbackFlow(query) {
+    async function feedbackFlow(query, ctx) {
         if (typeof query.session !== "string" || !query.session) {
             return fail(400, 'provide "session": the session id a write returned');
         }
         const session = await store.getSession(query.session);
         if (!session)
             return fail(404, `session "${query.session}" not found`);
-        const { comments } = await waitForComments({
+        const { comments, handedOff } = await waitForComments({
             sessionId: session.id,
             author: "user",
             waitSeconds: 0,
@@ -1991,13 +2205,14 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         });
         const project = str(query.project, MAX_TITLE) ?? session.project ?? undefined;
         return ok({
-            feedback: await buildFeedbackBatches(store, comments),
+            feedback: await feedbackWithHandoffs(comments, handedOff, ctx.base),
             pending: await Promise.all((await store.listMocks(project)).map(async (m) => pendingOf(m, await store.listPosts({ mockId: m.id })))),
         });
     }
     // Store an uploaded blob. An explicit session is validated and a missing one
-    // is auto-created so an upload can precede the first publish. The asset's
-    // data is dropped from the result (it's bytes).
+    // is auto-created so an upload can precede the first publish. An image the
+    // user attaches names its mock instead, and belongs to the session that mock
+    // replies to. The asset's data is dropped from the result (it's bytes).
     async function uploadAsset(input) {
         if (input.data.byteLength === 0)
             return { error: "empty upload", status: 400 };
@@ -2005,6 +2220,19 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return { error: `asset exceeds ${MAX_ASSET_BYTES} bytes`, status: 413 };
         }
         let sessionId = input.session;
+        if (input.mock !== undefined) {
+            if (!ATTACHABLE_IMAGE_TYPES.has(input.contentType)) {
+                return { error: "attach a png, jpeg, webp or gif image", status: 415 };
+            }
+            const mock = await store.getMock(input.mock);
+            if (!mock)
+                return { error: `mock "${input.mock}" not found`, status: 404 };
+            const posts = await store.listPosts({ mockId: mock.id });
+            const latest = [...posts].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt))[0];
+            sessionId = mock.sessionId ?? latest?.sessionId;
+            if (!sessionId)
+                return { error: `${mock.slug} has no agent session`, status: 409 };
+        }
         if (sessionId && !(await store.getSession(sessionId))) {
             return { error: `session "${sessionId}" not found`, status: 404 };
         }
@@ -2062,6 +2290,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
             return next();
         if (path.startsWith(STATIC_ASSET_PREFIX))
             return next();
+        // The installable-app files carry no workspace data, and a browser may
+        // fetch them without the cookie; the manifest adds the key only for a
+        // caller that already holds it.
+        if (APP_FILES.has(path))
+            return next();
         const key = c.req.query("key");
         if (key === authToken) {
             setCookie(c, "mockpit_key", authToken, {
@@ -2135,6 +2368,21 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         ].join("");
         return injectHead(text, `<script>${config}</script>`);
     };
+    // The tags that make the viewer installable to a home screen. `use-credentials`
+    // sends the cookie with the manifest fetch, which browsers otherwise omit.
+    const withAppHead = (request, mode) => (text) => {
+        const base = escapeHtml(requestBasePath(request));
+        return injectHead(text, [
+            `<link rel="manifest" href="${base}/manifest.webmanifest" crossorigin="use-credentials">`,
+            `<link rel="icon" href="${base}/icon.svg" type="image/svg+xml">`,
+            `<link rel="apple-touch-icon" href="${base}/apple-touch-icon.png">`,
+            `<meta name="theme-color" content="${themeColor(mode)}">`,
+            `<meta name="mobile-web-app-capable" content="yes">`,
+            `<meta name="apple-mobile-web-app-capable" content="yes">`,
+            `<meta name="apple-mobile-web-app-title" content="mockpit">`,
+            `<meta name="apple-mobile-web-app-status-bar-style" content="default">`,
+        ].join("\n"));
+    };
     // --- viewer pages ---
     // Link previews for a mock page: the first open variant's first surface,
     // with every pixel-affecting input pinned in the image URL so the Worker can
@@ -2175,13 +2423,42 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         // sandboxed surface documents at /s/:id are *meant* to be framed and carry
         // their own `sandbox` CSP header instead, so they never pass through here.
         c.header("Content-Security-Policy", "frame-ancestors 'self'");
-        const html = withDocumentTitle(withViewerConfig(withOrigin(viewerHtml, { req: { url: c.req.url } }), c.req.raw, !!publicRead && !isAuthenticated(c), opts.title), opts.title);
+        const html = withAppHead(c.req.raw, await workspaceMode())(withDocumentTitle(withViewerConfig(withOrigin(viewerHtml, { req: { url: c.req.url } }), c.req.raw, !!publicRead && !isAuthenticated(c), opts.title), opts.title));
         if (!opts.preview)
             return html;
         const { mock, post } = opts.preview;
         return injectHead(html, mockPreviewHead(mock, post, c.req.raw, await workspaceMode(), version ?? "dev"));
     };
     app.get("/", async (c) => c.html(await configuredViewerHtml(c)));
+    // --- the installable app: manifest and icons ---
+    app.get("/manifest.webmanifest", async (c) => {
+        // A tokened workspace bakes the key into start_url for a caller that holds
+        // it (the viewer links the manifest with credentials), so a home-screen
+        // launch, which may not share the browser's cookies, signs itself in.
+        const keyed = !!authToken && isAuthenticated(c);
+        const manifest = webManifest(await workspaceMode(), keyed ? `./?key=${encodeURIComponent(authToken)}` : "./");
+        c.header("Content-Type", "application/manifest+json; charset=utf-8");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", keyed ? "private, no-store" : "no-cache");
+        return c.body(JSON.stringify(manifest));
+    });
+    app.get("/icon.svg", (c) => {
+        c.header("Content-Type", "image/svg+xml");
+        // Our own art, but SVG is a document: opened top-level it runs at this origin.
+        c.header("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; sandbox");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", "public, max-age=86400");
+        return c.body(ICON_SVG);
+    });
+    const iconPng = (size) => (c) => {
+        c.header("Content-Type", "image/png");
+        c.header("X-Content-Type-Options", "nosniff");
+        c.header("Cache-Control", "public, max-age=86400");
+        return c.body(decodeBase64(ICON_PNG_BASE64[size]).buffer);
+    };
+    for (const size of ICON_SIZES)
+        app.get(`/icon-${size}.png`, iconPng(size));
+    app.get("/apple-touch-icon.png", iconPng(180));
     // The engine reads the project/mock out of the URL itself; these render the
     // same shell as "/".
     app.get("/project/:name", async (c) => c.html(await configuredViewerHtml(c, { title: c.req.param("name") })));
@@ -2229,8 +2506,11 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         const cwd = str(body.cwd, 4096);
         const key = str(body.key, MAX_TITLE);
         const existing = key ? await store.getSessionByKey(key) : null;
-        if (existing)
-            return c.json(existing, 200);
+        if (existing) {
+            // A resumed conversation is that agent back, not a new one superseding it.
+            await store.touchAgent(existing.id);
+            return c.json((await store.getSession(existing.id)) ?? existing, 200);
+        }
         const session = await store.createSession({
             agent: str(body.agent, MAX_TITLE) ?? "agent",
             title: str(body.title, MAX_TITLE),
@@ -2301,8 +2581,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
     app.post("/api/mocks/:id/reply", async (c) => send(c, await replyFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
     app.post("/api/mocks/:id/restore", async (c) => send(c, await restoreFlow(c.req.param("id"), await jsonBody(c))));
     app.post("/api/mocks/:id/variants/:postId/restore", async (c) => send(c, await restoreVersionFlow(c.req.param("id"), c.req.param("postId"), await jsonBody(c), flowCtx(c))));
-    app.post("/api/mocks/:id/say", async (c) => send(c, await sayFlow(c.req.param("id"), await jsonBody(c))));
-    app.get("/api/feedback", async (c) => send(c, await feedbackFlow({ session: c.req.query("session"), project: c.req.query("project") })));
+    app.post("/api/mocks/:id/say", async (c) => send(c, await sayFlow(c.req.param("id"), await jsonBody(c), flowCtx(c))));
+    app.get("/api/feedback", async (c) => send(c, await feedbackFlow({ session: c.req.query("session"), project: c.req.query("project") }, flowCtx(c))));
     // --- comments ---
     app.post("/api/comments", async (c) => send(c, await commentFlow(await jsonBody(c), flowCtx(c))));
     app.delete("/api/comments/:id", async (c) => {
@@ -2367,8 +2647,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         query.agent = isAgentRead;
         const respond = async (signal) => {
             if (isAgentRead)
-                return send(c, await listenFlow(query, signal));
-            const result = await waitForComments(query, signal);
+                return send(c, await listenFlow(query, flowCtx(c).base, signal));
+            const { handedOff: _none, ...result } = await waitForComments(query, signal);
             return c.json({ ...result, comments: await withDelivered(result.comments) });
         };
         if (waitSeconds <= 0)
@@ -2935,11 +3215,16 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
                     kind: isAssetKind(kindQ) ? kindQ : undefined,
                     session: c.req.query("session"),
                     agent: c.req.query("agent"),
+                    mock: c.req.query("mock"),
                 };
         }
         catch (err) {
             return c.json({ error: err instanceof Error ? err.message : "invalid upload" }, 400);
         }
+        // An attachment on a mock is the user's, so only the viewer may make one.
+        if (body.mock !== undefined && !flowCtx(c).viewer) {
+            return c.json({ error: "only the viewer can attach images to a mock" }, 403);
+        }
         const result = await uploadAsset(body);
         if ("error" in result)
             return c.json({ error: result.error }, result.status);
@@ -3100,8 +3385,8 @@ export function createApp({ store, viewerHtml, setupText, topics = {}, authentic
         get: (ref, query) => getMockFlow(ref, query),
         ask: (ref, body, ctx) => askFlow(ref, body, ctx),
         exportMock: (ref, query, ctx) => exportFlow(ref, query, ctx),
-        say: (ref, body) => sayFlow(ref, body),
-        feedback: (query) => feedbackFlow(query),
+        say: (ref, body, ctx) => sayFlow(ref, body, ctx),
+        feedback: (query, ctx) => feedbackFlow(query, ctx),
     };
     const guide = (project, topic) => topic ? (topics[topic] ?? "") : briefFor(project);
     // --- run: an agent script over the same flows (server/run.ts) ---