@shiyuphan/follow-me 0.1.1 → 0.3.0

package/dist/src/server.js

@@ -1,9 +1,12 @@
 import { createHash, randomBytes } from "node:crypto";
 import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { createServer } from "node:http";
-import { isAbsolute, join } from "node:path";
+import { homedir } from "node:os";
+import { basename, isAbsolute, join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { isPlanVersion } from "./plan.js";
+import { isReplyId, parseComment, parseDraft, parseNewDecision, parseNewReply, } from "./comments.js";
+import { isConcernId, isPlanVersion } from "./plan.js";
+import { renderReport, reportItems } from "./prompt.js";
 import { isLockToken } from "./session.js";
 /** The requested port is taken; host.ts decides whether that is our server or a stranger. */
 export class PortInUseError extends Error {
@@ -20,16 +23,19 @@ export class RegistrationError extends Error {
 }
 /** GET /api/health answers with this, so a CLI can tell our server from another program. */
 export const HEALTH_APP = "follow-me";
-const UI_DIR = new URL("../ui/", import.meta.url);
-const STATIC_FILES = new Map([
-    ["/app.js", { file: "app.js", type: "text/javascript; charset=utf-8" }],
-    ["/playback.js", { file: "playback.js", type: "text/javascript; charset=utf-8" }],
-    ["/style.css", { file: "style.css", type: "text/css; charset=utf-8" }],
+/** The page Vite builds from ui/ into ui/dist; `npm run build` makes it. */
+const UI_DIR = new URL("../ui/dist/", import.meta.url);
+/** Hashed bundles under /assets/ and the few flat files of ui/public at the root. */
+const STATIC_FILE = /^\/((?:assets\/)?[\w-]+(?:\.[\w-]+)*\.(js|css|woff2|svg))$/;
+const STATIC_TYPES = new Map([
+    ["js", "text/javascript; charset=utf-8"],
+    ["css", "text/css; charset=utf-8"],
+    ["woff2", "font/woff2"],
+    ["svg", "image/svg+xml"],
 ]);
 const MAX_BODY_BYTES = 1_000_000;
 const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
 const COMMENT_ID = /^c_[a-z2-7]{6}$/;
-const UNIT_ID = /^[hfm]_[0-9a-f]{12}(~\d+)?$/;
 const SESSION_ID = /^[0-9a-f]{12}$/;
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -37,15 +43,6 @@ function isRecord(value) {
 function isCommentId(value) {
     return typeof value === "string" && COMMENT_ID.test(value);
 }
-function isUnitId(value) {
-    return typeof value === "string" && UNIT_ID.test(value);
-}
-function isRepoPath(value) {
-    return typeof value === "string" && value.length > 0;
-}
-function isIndex(value) {
-    return typeof value === "number" && Number.isInteger(value) && value >= 0;
-}
 export function isSessionId(value) {
     return typeof value === "string" && SESSION_ID.test(value);
 }
@@ -59,50 +56,6 @@ export function sessionIdOf(dir) {
 export function sessionPath(id) {
     return `/s/${id}/`;
 }
-function parseAnchor(raw) {
-    if (!isRecord(raw))
-        return null;
-    const commit = raw["commit"];
-    switch (raw["kind"]) {
-        case "plan":
-            return { kind: "plan" };
-        case "message":
-            return isIndex(commit) ? { kind: "message", commit } : null;
-        case "position":
-            return isIndex(commit) ? { kind: "position", commit } : null;
-        case "hunk": {
-            const unit = raw["unit"];
-            const changes = raw["changes"];
-            if (!isIndex(commit) || !isUnitId(unit))
-                return null;
-            if (changes === null)
-                return { kind: "hunk", unit, commit, changes: null };
-            if (!Array.isArray(changes) || !changes.every(isIndex))
-                return null;
-            return { kind: "hunk", unit, commit, changes };
-        }
-        default:
-            return null;
-    }
-}
-/** The one place untrusted JSON becomes a Comment. Returns null when any field is wrong. */
-export function parseComment(raw) {
-    if (!isRecord(raw))
-        return null;
-    const { id, body, createdAt } = raw;
-    const context = raw["context"];
-    const anchor = parseAnchor(raw["anchor"]);
-    if (!isCommentId(id) || !anchor || !isRecord(context))
-        return null;
-    const { commitMessage, path } = context;
-    if (typeof commitMessage !== "string" || typeof body !== "string")
-        return null;
-    if (typeof createdAt !== "string")
-        return null;
-    if (path !== null && !isRepoPath(path))
-        return null;
-    return { id, anchor, context: { commitMessage, path }, body, createdAt };
-}
 /** The one place untrusted JSON becomes a Registration. */
 export function parseRegistration(raw) {
     if (!isRecord(raw))
@@ -121,25 +74,26 @@ export function parseRegistration(raw) {
 function draftPath(reviewsDir, version) {
     return join(reviewsDir, `v${version}.draft.json`);
 }
-/** Comments autosaved by an unfinished review of this version, or none. */
-export async function loadDraftComments(reviewsDir, version) {
+/** What an unfinished review of this version autosaved, or nothing. */
+export async function loadDraft(reviewsDir, version) {
     let text;
     try {
         text = await readFile(draftPath(reviewsDir, version), "utf8");
     }
     catch (error) {
-        if (isRecord(error) && error["code"] === "ENOENT")
-            return [];
+        if (isRecord(error) && error["code"] === "ENOENT") {
+            return { comments: [], concerns: [], resolved: [], excluded: { comments: [], concerns: [] } };
+        }
         throw error;
     }
-    const raw = JSON.parse(text);
-    const list = isRecord(raw) ? raw["comments"] : null;
-    if (!Array.isArray(list))
+    const draft = parseDraft(JSON.parse(text));
+    if (typeof draft === "string")
         throw new Error(`malformed review draft for v${version}`);
-    return list.flatMap((item) => {
-        const comment = parseComment(item);
-        return comment ? [comment] : [];
-    });
+    return draft;
+}
+/** Comments autosaved by an unfinished review of this version, or none. */
+export async function loadDraftComments(reviewsDir, version) {
+    return (await loadDraft(reviewsDir, version)).comments;
 }
 async function writeAtomic(path, text) {
     // The pid lets `follow-me clean` tell an abandoned temp file from one being written.
@@ -184,6 +138,17 @@ function sendJson(res, status, body) {
     res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
     res.end(JSON.stringify(body));
 }
+/** An integer query parameter within [min, max], else the default when absent; bad is a 400. */
+function queryInt(url, name, min, max, fallback) {
+    const raw = url.searchParams.get(name);
+    if (raw === null)
+        return fallback;
+    const n = Number(raw);
+    if (raw === "" || !Number.isInteger(n) || n < min) {
+        throw new HttpError(400, `${name} must be an integer of at least ${min}`);
+    }
+    return Math.min(n, max);
+}
 function sendHtml(res, status, html) {
     res.writeHead(status, {
         "content-type": "text/html; charset=utf-8",
@@ -194,15 +159,47 @@ function sendHtml(res, status, html) {
 function escapeHtml(text) {
     return text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
 }
-function indexPage(sessions) {
-    const rows = sessions.map((s) => {
-        const what = s.mode === "walk" ? "code review" : `review of plan v${s.version}`;
+/** "just now", "5 min ago", "2 h ago" or "3 days ago". */
+export function ago(ms) {
+    const minutes = Math.floor(ms / 60_000);
+    if (minutes < 1)
+        return "just now";
+    if (minutes < 60)
+        return `${minutes} min ago`;
+    const hours = Math.floor(minutes / 60);
+    if (hours < 24)
+        return `${hours} h ago`;
+    const days = Math.floor(hours / 24);
+    return `${days} day${days === 1 ? "" : "s"} ago`;
+}
+function tildePath(path) {
+    const home = homedir();
+    return path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path;
+}
+function indexPage(rows, now) {
+    const items = rows.map(({ summary: s, openedAt }) => {
+        const mode = s.mode === "walk"
+            ? '<span class="mode walk">code review</span>'
+            : `<span class="mode split">plan review v${s.version}</span>`;
         const count = `${s.comments} comment${s.comments === 1 ? "" : "s"}`;
-        return `      <li><a href="${s.url}">${escapeHtml(s.branch)}</a> <span class="muted">${what} · ${count} · ${escapeHtml(s.repo)}</span></li>`;
+        const repo = escapeHtml(basename(s.repo));
+        return `      <li>
+        <a class="session" href="${s.url}"><span class="repo">${repo}</span> <span class="branch">${escapeHtml(s.branch)}</span></a>
+        ${mode}
+        <span class="muted">${count} · opened ${ago(now - openedAt)}</span>
+        <span class="path muted">${escapeHtml(tildePath(s.repo))}</span>
+      </li>`;
     });
-    const body = rows.length === 0
-        ? '    <p class="muted">No sessions. Run follow-me review or follow-me walk in a repo.</p>'
-        : `    <ul class="session-index">\n${rows.join("\n")}\n    </ul>`;
+    const body = items.length === 0
+        ? `    <section class="empty">
+      <h1>No sessions yet</h1>
+      <p>Ask your coding agent to review a branch with follow-me. Each review opens here.</p>
+      <p><a href="https://github.com/phanshiyu/follow-me#readme">How follow-me works</a></p>
+    </section>`
+        : `    <h1>Sessions</h1>
+    <ul class="session-index">
+${items.join("\n")}
+    </ul>`;
     return `<!doctype html>
 <html lang="en">
   <head>
@@ -213,109 +210,464 @@ function indexPage(sessions) {
     <link rel="stylesheet" href="/style.css" />
   </head>
   <body class="index">
-    <h1>follow-me sessions</h1>
+    <header class="topbar"><strong>follow-me</strong></header>
+    <main class="index-main">
 ${body}
+    </main>
   </body>
 </html>
 `;
 }
-/** One hosted review: its comments, its autosave chain, and how it ends. */
-function hostSession(id, registration, loaded) {
+async function readUi(dir, name) {
+    try {
+        return await readFile(fileURLToPath(new URL(name, dir)));
+    }
+    catch (error) {
+        if (isRecord(error) && error["code"] === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+const NOT_BUILT = `<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="color-scheme" content="light dark" /><title>follow-me</title></head><body style="font-family: system-ui; max-width: 40rem; margin: 4rem auto; padding: 0 1rem"><h1>The review page is not built</h1><p>This follow-me runs from a checkout without <code>ui/dist</code>. Run <code>npm run build</code> (or <code>npm run ui:build</code>) in the checkout, then reload.</p></body></html>
+`;
+function viewOf(registration, loaded, draft) {
     const { state, reviewsDir } = loaded;
-    const comments = new Map(state.comments.map((c) => [c.id, c]));
-    const unitIds = new Set(state.units.map((u) => u.id));
-    const draftFile = draftPath(reviewsDir, state.version);
-    const reviewFile = join(reviewsDir, `v${state.version}.json`);
+    return {
+        registration,
+        loaded,
+        comments: new Map(state.comments.map((c) => [c.id, c])),
+        decisions: new Map(draft.concerns.map((d) => [d.concern, d])),
+        resolved: new Set(draft.resolved),
+        excludedComments: new Set(draft.excluded.comments),
+        excludedConcerns: new Set(draft.excluded.concerns),
+        unitIds: new Set(state.units.map((u) => u.id)),
+        hunkRows: new Map(state.units.flatMap((u) => u.kind === "hunk" ? [[u.id, u.body.length]] : [])),
+        concernIds: new Set(state.commits.flatMap((c) => (c.concerns ?? []).map((k) => k.id))),
+        draftFile: draftPath(reviewsDir, state.version),
+        reviewFile: join(reviewsDir, `v${state.version}.json`),
+    };
+}
+function withReplies(comment, replies) {
+    const { replies: _dropped, ...rest } = comment;
+    return replies === undefined || replies.length === 0 ? rest : { ...rest, replies };
+}
+function mintReplyId(taken) {
+    for (;;) {
+        let id = "r_";
+        for (const byte of randomBytes(6))
+            id += BASE32.charAt(byte % 32);
+        if (isReplyId(id) && !taken.has(id))
+            return id;
+    }
+}
+/**
+ * What the agent may see of the log: a pending flag is held back with everything said about it,
+ * and reaches the agent as an ordinary "comment" event when the reviewer submits.
+ */
+function forAgent(log) {
+    const held = new Set();
+    const out = [];
+    for (const event of log) {
+        if (event.type === "comment" || event.type === "comment-updated") {
+            const { comment } = event;
+            if (comment.pending === true) {
+                held.add(comment.id);
+                continue;
+            }
+            if (held.delete(comment.id))
+                out.push({ ...event, type: "comment" });
+            else
+                out.push(event);
+        }
+        else if (event.type === "comment-deleted") {
+            if (!held.delete(event.id))
+                out.push(event);
+        }
+        else if (event.type === "reply") {
+            if (!held.has(event.commentId))
+                out.push(event);
+        }
+        else
+            out.push(event);
+    }
+    return out;
+}
+const DEFAULT_POLL_MS = 25_000;
+const MAX_POLL_MS = 60_000;
+const STREAM_PING_MS = 15_000;
+/** One hosted review: its comments, its event log, its autosave chain, and how it ends. */
+function hostSession(id, registration, loaded, draft, load) {
+    const openedAt = Date.now();
+    let view = viewOf(registration, loaded, draft);
     let finish = () => { };
     const done = new Promise((resolve) => {
         finish = resolve;
     });
+    // The append-only log a watcher long-polls. seq is the position, counted from 1.
+    const events = [];
+    const waiters = new Set();
+    const listeners = new Set();
+    const emit = (body) => {
+        events.push({ ...body, seq: events.length + 1 });
+        for (const wake of [...waiters])
+            wake();
+        for (const listener of [...listeners])
+            listener();
+    };
+    const seen = (agent) => (agent ? forAgent(events) : events);
+    const waitForEvents = (since, timeoutMs, signal, agent) => new Promise((resolve) => {
+        const news = () => seen(agent).filter((e) => e.seq > since);
+        const answer = () => resolve({ seq: events.length, events: news() });
+        if (news().length > 0 || timeoutMs === 0 || signal.aborted)
+            return answer();
+        const wake = () => {
+            if (news().length === 0 && !signal.aborted)
+                return;
+            clearTimeout(timer);
+            waiters.delete(wake);
+            signal.removeEventListener("abort", wake);
+            answer();
+        };
+        const timer = setTimeout(() => {
+            waiters.delete(wake);
+            signal.removeEventListener("abort", wake);
+            answer();
+        }, timeoutMs);
+        waiters.add(wake);
+        signal.addEventListener("abort", wake);
+    });
     let ending = false;
+    let swapping = false;
+    const open = () => {
+        if (ending)
+            throw new HttpError(409, "this review is already ending");
+        if (swapping)
+            throw new HttpError(409, "the session is switching plan versions; try again");
+    };
+    /** The exclusions as stored, or null when nothing is excluded. */
+    const excludedOf = () => view.excludedComments.size + view.excludedConcerns.size === 0
+        ? null
+        : { comments: [...view.excludedComments], concerns: [...view.excludedConcerns] };
     // Writes are chained so two rapid edits never race on the same file.
     let writes = Promise.resolve();
     const saveDraft = () => {
+        const { state } = view.loaded;
+        const file = view.draftFile;
+        const concerns = [...view.decisions.values()];
+        const resolved = [...view.resolved];
+        const excluded = excludedOf();
         const snapshot = JSON.stringify({
             schema: "follow-me/review-draft@1",
             planVersion: state.version,
-            comments: [...comments.values()],
+            comments: [...view.comments.values()],
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
+            ...(excluded === null ? {} : { excluded }),
         }, null, 2);
+        const dir = view.loaded.reviewsDir;
         writes = writes.then(async () => {
-            await mkdir(reviewsDir, { recursive: true });
-            await writeAtomic(draftFile, `${snapshot}\n`);
+            await mkdir(dir, { recursive: true });
+            await writeAtomic(file, `${snapshot}\n`);
         });
         return writes;
     };
-    const accept = (comment) => {
-        if (!comment)
-            throw new HttpError(400, "malformed comment");
-        const { anchor } = comment;
-        if (anchor.kind !== "plan" && anchor.commit >= state.commits.length) {
+    const accept = (parsed) => {
+        if (typeof parsed === "string")
+            throw new HttpError(400, `malformed comment: ${parsed}`);
+        if (!COMMENT_ID.test(parsed.id))
+            throw new HttpError(400, "malformed comment: bad id");
+        const { anchor } = parsed;
+        if (anchor.kind !== "plan" && anchor.commit >= view.loaded.state.commits.length) {
             throw new HttpError(400, "anchor commit out of range");
         }
-        if (anchor.kind === "hunk" && !unitIds.has(anchor.unit)) {
+        if (anchor.kind === "hunk" && !view.unitIds.has(anchor.unit)) {
             throw new HttpError(400, "anchor names an unknown unit");
         }
-        return comment;
+        if (anchor.kind === "hunk" && anchor.offsets !== undefined) {
+            const rows = view.hunkRows.get(anchor.unit);
+            if (rows === undefined)
+                throw new HttpError(400, "anchor.offsets names a unit without rows");
+            if (anchor.offsets.some((o) => o >= rows)) {
+                throw new HttpError(400, `anchor.offsets is out of range, the unit has ${rows} rows`);
+            }
+        }
+        return parsed;
     };
+    /** Clears `pending` on every held flag at once and tells the agent what it missed. */
+    const release = () => {
+        const held = [...view.comments.values()].filter((c) => c.pending === true);
+        if (held.length === 0)
+            return 0;
+        emit({ type: "submitted" });
+        for (const comment of held) {
+            const { pending: _held, ...open } = comment;
+            view.comments.set(comment.id, open);
+            emit({ type: "comment", comment: open });
+        }
+        return held.length;
+    };
+    const review = () => {
+        const concerns = [...view.decisions.values()];
+        const resolved = [...view.resolved];
+        const excluded = excludedOf();
+        return {
+            schema: "follow-me/review@1",
+            mode: view.loaded.state.mode,
+            planVersion: view.loaded.state.version,
+            planHash: view.loaded.state.planHash,
+            endedAt: new Date().toISOString(),
+            comments: [...view.comments.values()].filter((c) => c.pending !== true),
+            ...(concerns.length === 0 ? {} : { concerns }),
+            ...(resolved.length === 0 ? {} : { resolved }),
+            ...(excluded === null ? {} : { excluded }),
+        };
+    };
+    const report = (finished) => {
+        const { state } = view.loaded;
+        const units = new Map(state.units.map((u) => [u.id, u]));
+        return renderReport(finished, state.commits, units, {
+            branch: state.anchor.branch,
+            responses: [],
+        });
+    };
+    /** Writes reviews/vN.json and its report once, and removes the autosave. */
+    const writeReview = async (finished) => {
+        await writes;
+        await mkdir(view.loaded.reviewsDir, { recursive: true });
+        await writeAtomic(view.reviewFile, `${JSON.stringify(finished, null, 2)}\n`);
+        await writeAtomic(view.reviewFile.replace(/\.json$/, ".md"), report(finished));
+        await rm(view.draftFile, { force: true });
+        return view.reviewFile;
+    };
+    const hasWork = () => view.comments.size > 0 || view.decisions.size > 0;
     return {
         id,
-        registration,
         done,
+        openedAt,
+        get registration() {
+            return view.registration;
+        },
         summary: () => ({
             id,
             url: sessionPath(id),
-            repo: loaded.repo,
-            branch: state.anchor.branch,
-            mode: state.mode,
-            version: state.version,
-            comments: comments.size,
+            repo: view.loaded.repo,
+            branch: view.loaded.state.anchor.branch,
+            mode: view.loaded.state.mode,
+            version: view.loaded.state.version,
+            comments: view.comments.size,
+            openedAt: new Date(openedAt).toISOString(),
         }),
-        snapshot: () => ({ ...state, comments: [...comments.values()] }),
+        snapshot: () => ({
+            ...view.loaded.state,
+            comments: [...view.comments.values()],
+            concerns: [...view.decisions.values()],
+            resolved: [...view.resolved],
+            excluded: { comments: [...view.excludedComments], concerns: [...view.excludedConcerns] },
+            seq: events.length,
+            previous: view.loaded.previous,
+        }),
+        /** Events after `since`, now and as they happen, until unfollowed or the review ends. */
+        latest: () => events.length,
+        follow: (since, send, stop, agent) => {
+            if (since > events.length) {
+                throw new HttpError(409, `since ${since} is ahead of this session's log (${events.length})`);
+            }
+            let last = since;
+            const flush = () => {
+                for (const event of seen(agent).filter((e) => e.seq > last)) {
+                    send(event);
+                    last = event.seq;
+                    if (event.type === "ended") {
+                        listeners.delete(flush);
+                        stop();
+                        return;
+                    }
+                }
+            };
+            listeners.add(flush);
+            flush();
+            return () => listeners.delete(flush);
+        },
+        poll: (since, timeoutMs, signal, agent) => {
+            if (since > events.length) {
+                throw new HttpError(409, `since ${since} is ahead of this session's log (${events.length})`);
+            }
+            return waitForEvents(since, timeoutMs, signal, agent);
+        },
+        report: () => report(review()),
+        reportItems: () => {
+            const { state } = view.loaded;
+            const units = new Map(state.units.map((u) => [u.id, u]));
+            return reportItems(review(), state.commits, units, {
+                branch: state.anchor.branch,
+                responses: [],
+            });
+        },
         add: async (raw) => {
+            open();
             if (!isRecord(raw))
                 throw new HttpError(400, "malformed comment");
-            const commentId = mintCommentId(new Set(comments.keys()));
-            const comment = accept(parseComment({ ...raw, id: commentId, createdAt: new Date().toISOString() }));
-            comments.set(commentId, comment);
+            const commentId = mintCommentId(new Set(view.comments.keys()));
+            const comment = withReplies(accept(parseComment({ ...raw, id: commentId, createdAt: new Date().toISOString() })), undefined);
+            view.comments.set(commentId, comment);
+            emit({ type: "comment", comment });
             await saveDraft();
             return commentId;
         },
         put: async (target, raw) => {
-            const comment = accept(parseComment(raw));
-            if (comment.id !== target)
+            open();
+            const parsed = withReplies(accept(parseComment(raw)), undefined);
+            if (parsed.id !== target)
                 throw new HttpError(400, "comment id does not match the URL");
-            comments.set(comment.id, comment);
+            // Replies belong to the conversation, not to the page's copy of the comment.
+            const comment = withReplies(parsed, view.comments.get(target)?.replies);
+            view.comments.set(comment.id, comment);
+            emit({ type: "comment-updated", comment });
             await saveDraft();
             return comment;
         },
         remove: async (target) => {
-            if (!comments.delete(target))
+            open();
+            const gone = view.comments.get(target);
+            if (gone === undefined)
+                throw new HttpError(404, "no such comment");
+            view.comments.delete(target);
+            view.excludedComments.delete(gone.id);
+            emit({ type: "comment-deleted", id: gone.id });
+            await saveDraft();
+        },
+        reply: async (target, raw) => {
+            open();
+            const comment = view.comments.get(target);
+            if (comment === undefined)
                 throw new HttpError(404, "no such comment");
+            const parsed = parseNewReply(raw);
+            if (typeof parsed === "string")
+                throw new HttpError(400, `malformed reply: ${parsed}`);
+            const taken = new Set([...view.comments.values()].flatMap((c) => c.replies ?? []).map((r) => r.id));
+            const reply = {
+                id: mintReplyId(taken),
+                ...parsed,
+                createdAt: new Date().toISOString(),
+            };
+            view.comments.set(comment.id, { ...comment, replies: [...(comment.replies ?? []), reply] });
+            emit({ type: "reply", commentId: comment.id, reply });
+            await saveDraft();
+            return reply.id;
+        },
+        decide: async (target, raw) => {
+            open();
+            if (!isConcernId(target) || !view.concernIds.has(target)) {
+                throw new HttpError(404, "no such concern in this plan");
+            }
+            const parsed = parseNewDecision(target, raw);
+            if (typeof parsed === "string")
+                throw new HttpError(400, `malformed decision: ${parsed}`);
+            const decision = { ...parsed, decidedAt: new Date().toISOString() };
+            view.decisions.set(target, decision);
+            const { concern: concernId, ...rest } = decision;
+            emit({ type: "concern", concernId, ...rest });
+            await saveDraft();
+            return decision;
+        },
+        /** Leaves a comment or an agent concern out of the hand-off, or puts it back. */
+        exclude: async (raw) => {
+            open();
+            const body = isRecord(raw) ? raw : {};
+            const { comment, concern, excluded } = body;
+            if (typeof excluded !== "boolean" || (comment === undefined) === (concern === undefined)) {
+                throw new HttpError(400, "expected { comment } or { concern }, and { excluded: boolean }");
+            }
+            if (comment !== undefined) {
+                if (!isCommentId(comment) || !view.comments.has(comment)) {
+                    throw new HttpError(404, "no such comment");
+                }
+                if (excluded)
+                    view.excludedComments.add(comment);
+                else
+                    view.excludedComments.delete(comment);
+            }
+            else {
+                if (!isConcernId(concern) || !view.concernIds.has(concern)) {
+                    throw new HttpError(404, "no such concern in this plan");
+                }
+                if (excluded)
+                    view.excludedConcerns.add(concern);
+                else
+                    view.excludedConcerns.delete(concern);
+            }
             await saveDraft();
+            return { comments: [...view.excludedComments], concerns: [...view.excludedConcerns] };
         },
-        /** Writes reviews/vN.json exactly once and releases the session's lock. */
+        /** Releases every held flag in one go; the reviewer pressed Submit. */
+        submit: async () => {
+            open();
+            const released = release();
+            await saveDraft();
+            return { released };
+        },
+        resolve: async (raw) => {
+            open();
+            const body = isRecord(raw) ? raw : {};
+            const target = body["comment"];
+            const asked = view.loaded.previous?.comments.find((c) => c.id === target);
+            if (asked === undefined || typeof body["resolved"] !== "boolean") {
+                throw new HttpError(400, "expected { comment: <id of a question of the previous version>, resolved }");
+            }
+            if (body["resolved"])
+                view.resolved.add(asked.id);
+            else
+                view.resolved.delete(asked.id);
+            emit({ type: "resolved", commentId: asked.id, resolved: body["resolved"] });
+            await saveDraft();
+            return [...view.resolved];
+        },
+        /**
+         * Moves the session to a newer frozen plan under the same id and URL. The new version loads
+         * first, so a plan that no longer fits leaves the old one untouched; then the old version's
+         * review is finalized if anything was said, and the comment set starts fresh.
+         */
+        swap: async (version, hash) => {
+            open();
+            const { state } = view.loaded;
+            if (version === state.version) {
+                if (hash === state.planHash)
+                    return;
+                throw new HttpError(409, `plan v${version} is already open with another hash`);
+            }
+            if (version < state.version) {
+                throw new HttpError(409, `plan v${version} is older than the open v${state.version}`);
+            }
+            swapping = true;
+            try {
+                await writes;
+                const next = await load({ ...view.registration, version, hash, lockToken: null }, view.loaded.release);
+                release();
+                if (hasWork())
+                    await writeReview(review());
+                else
+                    await rm(view.draftFile, { force: true });
+                view = viewOf({ ...view.registration, version, hash }, next, await loadDraft(next.reviewsDir, version));
+                emit({ type: "version", version, hash });
+            }
+            finally {
+                swapping = false;
+            }
+        },
+        /** Writes reviews/vN.json and vN.md exactly once and releases the session's lock. */
         end: async () => {
-            if (ending)
-                throw new HttpError(409, "this review is already ending");
+            open();
             ending = true;
-            await writes;
-            const review = {
-                schema: "follow-me/review@1",
-                mode: state.mode,
-                planVersion: state.version,
-                planHash: state.planHash,
-                endedAt: new Date().toISOString(),
-                comments: [...comments.values()],
-            };
-            await mkdir(reviewsDir, { recursive: true });
-            await writeAtomic(reviewFile, `${JSON.stringify(review, null, 2)}\n`);
-            await rm(draftFile, { force: true });
-            loaded.release();
-            return { review, file: reviewFile };
+            release();
+            const finished = review();
+            const file = await writeReview(finished);
+            view.loaded.release();
+            emit({ type: "ended", review: file });
+            return { review: finished, file };
         },
-        finish: (review) => finish(review),
+        finish: (finished) => finish(finished),
         abandon: () => {
-            loaded.release();
+            view.loaded.release();
             finish(null);
         },
     };
@@ -329,6 +681,7 @@ function sameRegistration(a, b) {
  * itself once it has had no session for idleMs.
  */
 export function startServer(opts) {
+    const uiDir = opts.uiDir ?? UI_DIR;
     const registry = new Map();
     const pending = new Map();
     let boundPort = 0;
@@ -380,7 +733,9 @@ export function startServer(opts) {
             return { summary: existing.summary(), done: existing.done };
         }
         clearTimeout(idleTimer);
-        const loading = opts.load(registration).then((loaded) => hostSession(id, registration, loaded));
+        const loading = opts
+            .load(registration, null)
+            .then(async (loaded) => hostSession(id, registration, loaded, await loadDraft(loaded.reviewsDir, loaded.state.version), opts.load));
         pending.set(id, loading);
         try {
             const session = await loading;
@@ -408,16 +763,30 @@ export function startServer(opts) {
         if (origin !== undefined && origin !== `http://${host}`)
             throw new HttpError(403, "bad origin");
         const method = req.method ?? "GET";
-        const path = new URL(req.url ?? "/", "http://localhost").pathname;
-        const asset = method === "GET" ? STATIC_FILES.get(path) : undefined;
-        if (asset) {
-            const bytes = await readFile(fileURLToPath(new URL(asset.file, UI_DIR)));
-            res.writeHead(200, { "content-type": asset.type, "cache-control": "no-store" });
+        const url = new URL(req.url ?? "/", "http://localhost");
+        const path = url.pathname;
+        const asset = method === "GET" ? STATIC_FILE.exec(path) : null;
+        if (asset !== null) {
+            const [, name = "", ext = ""] = asset;
+            const bytes = await readUi(uiDir, name);
+            if (bytes === null)
+                throw new HttpError(404, "not found");
+            // Vite hashes every name under assets/, so those never change under the same URL.
+            const cache = name.startsWith("assets/") ? "max-age=31536000, immutable" : "no-store";
+            res.writeHead(200, {
+                "content-type": STATIC_TYPES.get(ext) ?? "text/plain",
+                "cache-control": cache,
+            });
             res.end(bytes);
             return;
         }
-        if (method === "GET" && path === "/")
-            return sendHtml(res, 200, indexPage(sessions()));
+        if (method === "GET" && path === "/") {
+            const rows = [...registry.values()].map((h) => ({
+                summary: h.summary(),
+                openedAt: h.openedAt,
+            }));
+            return sendHtml(res, 200, indexPage(rows, Date.now()));
+        }
         if (method === "GET" && path === "/api/health") {
             return sendJson(res, 200, { app: HEALTH_APP, pid: process.pid });
         }
@@ -440,15 +809,79 @@ export function startServer(opts) {
             res.end();
             return;
         }
-        if (method === "GET" && rest === "/") {
+        if (method === "GET" && (rest === "/" || rest === "/report")) {
             if (!isSessionId(rawId) || !registry.has(rawId)) {
-                return sendHtml(res, 404, '<!doctype html><title>follow-me</title><p>This session ended or never existed. <a href="/">All sessions</a></p>\n');
+                return sendHtml(res, 404, '<!doctype html><html lang="en"><head><meta charset="utf-8" /><meta name="color-scheme" content="light dark" /><title>follow-me</title><link rel="stylesheet" href="/style.css" /></head><body class="index"><header class="topbar"><strong>follow-me</strong></header><main class="index-main"><section class="empty"><h1>This session has ended</h1><p>It finished, or it never existed. <a href="/">All sessions</a></p></section></main></body></html>\n');
             }
-            return sendHtml(res, 200, await readFile(fileURLToPath(new URL("index.html", UI_DIR)), "utf8"));
+            const page = await readUi(uiDir, "index.html");
+            return page === null ? sendHtml(res, 503, NOT_BUILT) : sendHtml(res, 200, page.toString());
         }
         const session = hosted(rawId);
         if (method === "GET" && rest === "/api/state")
             return sendJson(res, 200, session.snapshot());
+        if (method === "GET" && rest === "/api/events/stream") {
+            const header = Number(req.headers["last-event-id"]);
+            const resume = Number.isInteger(header) && header > 0 ? header : 0;
+            const since = Math.max(queryInt(url, "since", 0, Number.MAX_SAFE_INTEGER, 0), resume);
+            if (since > session.latest())
+                throw new HttpError(409, "since is ahead of this session's log");
+            res.writeHead(200, {
+                "content-type": "text/event-stream; charset=utf-8",
+                "cache-control": "no-cache",
+                connection: "keep-alive",
+            });
+            res.write(": follow-me\n\n");
+            const ping = setInterval(() => res.write(": ping\n\n"), STREAM_PING_MS);
+            const unfollow = session.follow(since, (event) => res.write(`id: ${event.seq}\ndata: ${JSON.stringify(event)}\n\n`), () => res.end(), url.searchParams.get("audience") === "agent");
+            res.on("close", () => {
+                clearInterval(ping);
+                unfollow();
+            });
+            return;
+        }
+        if (method === "GET" && rest === "/api/events") {
+            const abort = new AbortController();
+            res.on("close", () => abort.abort());
+            const since = queryInt(url, "since", 0, Number.MAX_SAFE_INTEGER, 0);
+            const timeout = queryInt(url, "timeout", 0, MAX_POLL_MS, DEFAULT_POLL_MS);
+            const agent = url.searchParams.get("audience") === "agent";
+            return sendJson(res, 200, await session.poll(since, timeout, abort.signal, agent));
+        }
+        if (method === "GET" && rest === "/api/report" && url.searchParams.get("format") === "json") {
+            return sendJson(res, 200, session.reportItems());
+        }
+        if (method === "GET" && rest === "/api/report") {
+            res.writeHead(200, { "content-type": "text/markdown; charset=utf-8" });
+            res.end(session.report());
+            return;
+        }
+        if (method === "POST" && rest === "/api/version") {
+            const body = await readJson(req);
+            const version = isRecord(body) ? body["version"] : undefined;
+            const hash = isRecord(body) ? body["hash"] : undefined;
+            if (!isPlanVersion(version) || typeof hash !== "string" || hash === "") {
+                throw new HttpError(400, "expected { version, hash }");
+            }
+            await session.swap(version, hash);
+            return sendJson(res, 200, session.summary());
+        }
+        if (method === "POST" && rest === "/api/submit") {
+            return sendJson(res, 200, await session.submit());
+        }
+        if (method === "POST" && rest === "/api/excluded") {
+            return sendJson(res, 200, await session.exclude(await readJson(req)));
+        }
+        if (method === "POST" && rest === "/api/resolved") {
+            return sendJson(res, 200, { resolved: await session.resolve(await readJson(req)) });
+        }
+        const replies = /^\/api\/comments\/([^/]+)\/replies$/.exec(rest ?? "")?.[1];
+        if (replies !== undefined && method === "POST") {
+            return sendJson(res, 201, { id: await session.reply(replies, await readJson(req)) });
+        }
+        const concern = /^\/api\/concerns\/([^/]+)$/.exec(rest ?? "")?.[1];
+        if (concern !== undefined && method === "POST") {
+            return sendJson(res, 200, await session.decide(concern, await readJson(req)));
+        }
         if (method === "POST" && rest === "/api/comments") {
             return sendJson(res, 201, { id: await session.add(await readJson(req)) });
         }