@shiyuphan/follow-me 0.7.1 → 0.8.0

package/README.md

@@ -78,6 +78,9 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![Coverage while reading: gutter bars mark covered, partly covered and uncovered lines, with counts per commit, per file and for the branch, and a popover listing the test that ran a line](assets/screenshots/coverage.png)
 *Coverage while reading. Your agent runs the tests with coverage and passes the lcov to `follow-me coverage`; follow-me never runs anything. Bars show covered, partly covered and uncovered lines, `x` jumps to the next uncovered line, and clicking a bar lists the tests that ran it.*
 
+![A state machine reply: each state is marked by whether a test reached it, and clicking a state jumps to its code](assets/screenshots/state-machine.png)
+*Your agent offers what it can draw, like "a state machine for this guard", as chips under the commit. Tap one and it answers with the diagram, each state marked by whether a test reached it. Click a state to jump to its code.*
+
 ![A diagram opened in the lightbox at full size](assets/screenshots/diagram.png)
 *Diagrams sit full width under the commit or reply they explain, and open full size on click.*
 

package/dist/src/cli.js

@@ -3,14 +3,15 @@ import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { changedLines, LcovError, parseLcov, parseLocArg, recordRun, runOf, tipPlacer, totalOf, } from "./coverage.js";
+import { mapOffTip, parseStateMap } from "./comments.js";
+import { changedLines, LcovError, PREVIEW_LINES, parseLcov, parseLocArg, recordRun, runOf, tipPlacer, totalOf, } from "./coverage.js";
 import { definitionIndex, isIdentifier } from "./definition.js";
-import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
-import { BranchRefusedError, branchHead, GitError, isOwnWork, pathsAt, pathsChanged, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postCoverage, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { DiffParseError, formatUnitRef, isRepoPath, isUnitId, splitLines } from "./diff.js";
+import { BranchRefusedError, blobsAt, branchHead, GitError, isOwnWork, pathsAt, pathsChanged, signing, treeOf, writeBranch, } from "./git.js";
+import { fetchCarried, fetchComments, fetchReport, fetchWaitingOffers, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postCoverage, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { findSkillDir, InstallError, runInstall, runUninstall, syncSkills, } from "./install.js";
 import { naiveDraft } from "./naive.js";
-import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
+import { isCommentId, isConcernId, isFields, OFFERS_PER_COMMIT, OFFERS_PER_PLAN, serializePlanFile, validatePlan, } from "./plan.js";
 import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownDefinitions, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
 import { BranchMovedError, cleanSessions, coverageAt, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
@@ -31,9 +32,10 @@ prints what they flagged or asked. It is interactive: do what its "next:" line s
 again until it prints the report.
 
 Other commands:
-  reply <commentId> --body <text> [--diagram <file>]
+  reply <commentId> --body <text> [--diagram <file> [--map <file>]]
                                             answer under a comment on the page; the diagram is
-                                            Mermaid source
+                                            Mermaid source, the map JSON tying its states to
+                                            tip lines
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked
   show <h_…|c_…|k_…|path:line[@n|@base]|name>
@@ -42,8 +44,9 @@ Other commands:
                                             is defined, instead of reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
-  coverage <lcov> [--test <id> [--at <path:line>]]
-                                            record a test run taken at the tip for the page
+  coverage <lcov> [--test <id> [--at <path:line>]] [--reset]
+                                            record a test run taken at the tip for the page;
+                                            --reset alone clears it before per-test runs
 
 help --all lists every command.`;
 const USAGE = `usage: follow-me <command> [options]
@@ -86,9 +89,10 @@ Interactive loop (while the review page is open):
                                             reports the end of the review. Your own replies are
                                             left out. --follow streams every event until the
                                             review ends instead of stopping at the first
-  reply <commentId> --body <text> [--diagram <file>]
+  reply <commentId> --body <text> [--diagram <file> [--map <file>]]
                                             answer under a comment on the page; the diagram is
-                                            Mermaid source
+                                            Mermaid source, the map JSON tying its states to
+                                            tip lines
   explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
                                             start a thread on the page without being asked;
                                             --lines are change lines of the unit, commits count
@@ -107,11 +111,12 @@ Interactive loop (while the review page is open):
                                             line in both voices, then questions with answers;
                                             --json lists the items to post to a merge request
                                             (path, lines, severity, body, thread, excluded)
-  coverage <lcov> [--test <id> [--at <path:line>]] [--branch <name>]
+  coverage <lcov> [--test <id> [--at <path:line>]] [--reset] [--branch <name>]
                                             record the lcov of a test run at the branch tip;
                                             refuses when a covered file in the working tree
                                             differs from the tip. A plain run replaces the last;
-                                            --test runs add one test each, --at is where it is
+                                            --test runs add one test each, --at is where it is.
+                                            --reset starts fresh; alone it clears the last run
   apply, while the page is open, swaps it to the new plan version in place, same URL.
 
 Old names, still working:
@@ -291,6 +296,12 @@ function formatIssue(issue) {
             return `$.commits[${issue.commit}]: concern: ${issue.reason}`;
         case "too-many-concerns":
             return `${issue.unit} has more than one concern, in commits ${issue.commits.join(" and ")}; keep the one that matters`;
+        case "bad-offer":
+            return `$.commits[${issue.commit}]: offer: ${issue.reason}`;
+        case "too-many-offers":
+            return issue.commit === null
+                ? `the plan has ${issue.count} offers; at most ${OFFERS_PER_PLAN}, and most plans need none`
+                : `$.commits[${issue.commit}] has ${issue.count} offers; at most ${OFFERS_PER_COMMIT} per commit`;
         case "final-mismatch": {
             const tip = issue.expected ? `${issue.expected.mode} ${issue.expected.blob}` : "absent";
             return `${show(issue.path)}: the last commit has ${issue.got}, the tip has ${tip}`;
@@ -305,6 +316,9 @@ function formatWarning(w) {
     if (w.kind === "long-title") {
         return `warning: $.commits[${w.commit}]: title is ${w.length} characters; keep it to 50`;
     }
+    if (w.kind === "section-order") {
+        return `warning: $.commits[${w.commit}]: section ${w.section} comes after ${w.after}; sections read story, steps, details, wiring`;
+    }
     if (w.kind === "question-addressed") {
         return `warning: question ${w.comment} is marked addressed; explain it with "answered" and "at" unless answering it changed the plan`;
     }
@@ -1053,6 +1067,13 @@ function waitOf(args) {
 /** One call fits inside a harness's tool timeout, so the agent's loop is one command per turn. */
 const ENTRY_WAIT_SECONDS = 90;
 const MAX_ENTRY_WAIT_SECONDS = 300;
+/** The step that names the oldest accepted offer the agent has not answered, or null. */
+async function offerStep(port, summary) {
+    const [first] = await fetchWaitingOffers(port, summary);
+    if (first === undefined)
+        return null;
+    return `${STILL_WORKING}; offer ${first.offer} waits for your diagram: follow-me reply ${first.comment} --diagram <file> [--map <file>], then run follow-me again`;
+}
 /**
  * Listens to the hosted review for up to --wait seconds and prints what the reviewer did. It
  * returns at once with news, and with the report when the reviewer submitted or ended the review.
@@ -1112,11 +1133,13 @@ async function listen(session, open, args) {
                 next("done; the user can port it with follow-me report --json");
                 return 0;
             }
-            next(`${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
+            next((await offerStep(port, summary)) ??
+                `${STILL_WORKING}; answer with follow-me reply <id> --body "<markdown>" [--diagram file], then run follow-me again`);
             return 0;
         }
         if (left <= 0) {
-            next(`${STILL_WORKING}; run follow-me again to keep listening`);
+            next((await offerStep(port, summary)) ??
+                `${STILL_WORKING}; run follow-me again to keep listening`);
             return 0;
         }
     }
@@ -1315,7 +1338,7 @@ async function report(cwd, args, walkOnly = false) {
     process.stdout.write(text);
     return 0;
 }
-const COVERAGE_USAGE = "usage: follow-me coverage <lcov> [--test <id> [--at <path:line>]]";
+const COVERAGE_USAGE = "usage: follow-me coverage <lcov> [--test <id> [--at <path:line>]] [--reset]\n       follow-me coverage --reset";
 /**
  * Records the lcov of a test run the agent made at the tip in the session's coverage.json and
  * prints how much of the branch's changed code it ran. follow-me never runs the tests itself.
@@ -1324,6 +1347,13 @@ async function coverage(cwd, args) {
     const [file, extra] = args.positionals;
     const id = args.values.get("test");
     const atArg = args.values.get("at");
+    const reset = args.flags.has("reset");
+    if (file === undefined && reset && id === undefined && atArg === undefined) {
+        const session = await openFresh(cwd, args);
+        session.clearCoverage();
+        say("coverage cleared; the next run starts fresh");
+        return 0;
+    }
     if (file === undefined || extra !== undefined)
         throw new UsageError(COVERAGE_USAGE);
     if (atArg !== undefined && id === undefined) {
@@ -1354,10 +1384,15 @@ async function coverage(cwd, args) {
         const at = atArg === undefined ? undefined : parseLocArg(atArg, place);
         if (typeof at === "string")
             throw new UsageError(at);
-        test = { id, ...(at === undefined ? {} : { at }) };
+        const preview = at === undefined ? undefined : await testPreview(session, at);
+        test = {
+            id,
+            ...(at === undefined ? {} : { at }),
+            ...(preview === undefined ? {} : { preview }),
+        };
     }
     const takenAt = new Date().toISOString();
-    const recorded = recordRun(session.coverage(), run, {
+    const recorded = recordRun(reset ? null : session.coverage(), run, {
         tip,
         takenAt,
         ...(test === undefined ? {} : { test }),
@@ -1370,6 +1405,19 @@ async function coverage(cwd, args) {
     say(`coverage for ${plural(recorded.files.size, "file")} at ${short(tip)}; ${covered} of ${executable} changed lines covered`);
     return 0;
 }
+/**
+ * Up to PREVIEW_LINES tip lines from where a test starts, when the branch leaves its file alone:
+ * the page shows the branch's own files from the plan, and the others need this to peek.
+ */
+async function testPreview(session, at) {
+    const changed = new Set([...session.diff.units.values()].map((u) => u.path));
+    if (changed.has(at.path))
+        return undefined;
+    const bytes = (await blobsAt(session.root, session.anchor.tip, [at.path])).get(at.path) ?? "";
+    return splitLines(bytes)
+        .slice(at.start - 1, at.start - 1 + PREVIEW_LINES)
+        .map((line) => Buffer.from(line.replace(/\r?\n$/, ""), "latin1").toString("utf8"));
+}
 /** The old name of report. */
 async function feedback(cwd, args) {
     console.error("follow-me: feedback is now report; printing the same");
@@ -1380,11 +1428,13 @@ function isCommentEvent(event) {
 }
 /**
  * Events the reviewer caused; the agent's own replies, explanations, version swaps and coverage
- * are not news.
+ * are not news, and neither is a dismissed offer, which asks nothing of the agent.
  */
 function isNews(event) {
     if (event.type === "version" || event.type === "coverage")
         return false;
+    if (event.type === "offer-dismissed")
+        return false;
     if (event.type === "comment" || event.type === "comment-updated") {
         return event.comment.author !== "agent";
     }
@@ -1464,12 +1514,18 @@ async function watch(cwd, args) {
 /** Posts the agent's answer under a comment on the hosted page. */
 async function reply(cwd, args) {
     const [commentId, extra] = args.positionals;
-    const body = args.values.get("body");
+    const diagram = diagramOf(args);
+    // A diagram can be the whole answer, as when it answers an accepted offer.
+    const body = args.values.get("body") ?? (diagram === undefined ? undefined : "");
     if (commentId === undefined || extra !== undefined || body === undefined) {
-        throw new UsageError("usage: follow-me reply <commentId> --body <text> [--diagram <file>]");
+        throw new UsageError(REPLY_USAGE);
+    }
+    const mapFile = args.values.get("map");
+    if (mapFile !== undefined && diagram === undefined) {
+        throw new UsageError(`--map needs --diagram, the state diagram it ties to code\n${REPLY_USAGE}`);
     }
-    const diagram = diagramOf(args);
     const session = await openSession(cwd, sessionOpts(args));
+    const map = mapFile === undefined ? undefined : await readMap(session, mapFile, diagram);
     const open = await openOnServer(session, null);
     if (open === null)
         return notOpen(session);
@@ -1477,11 +1533,59 @@ async function reply(cwd, args) {
         author: "agent",
         body,
         ...(diagram === undefined ? {} : { diagram }),
+        ...(map === undefined ? {} : { map }),
     });
     say(`replied ${id} to ${commentId}`);
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
+const REPLY_USAGE = `usage: follow-me reply <commentId> --body <text> [--diagram <file> [--map <file>]]
+       follow-me reply <commentId> --diagram <file> [--map <file>] [--body <text>]`;
+/** A map path as git names it: the JSON's UTF-8 text as the bytes git prints, read as latin1. */
+function repoPathOf(typed) {
+    const path = Buffer.from(typed, "utf8").toString("latin1");
+    if (!isRepoPath(path))
+        throw new UsageError(`${typed} is not a repo path`);
+    return path;
+}
+/**
+ * --map's JSON, checked against the tip: every place is a file there and within its lines. Every
+ * bad entry is named at once, so one fix round is enough.
+ */
+async function readMap(session, file, diagram) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        throw new UsageError(`cannot read ${file} as JSON: ${error instanceof Error ? error.message : error}`);
+    }
+    const typed = parseStateMap(raw, diagram);
+    if (typeof typed === "string")
+        throw new UsageError(`${file}: ${typed}`);
+    const at = (loc) => ({ ...loc, path: repoPathOf(loc.path) });
+    const map = {
+        states: Object.fromEntries(Object.entries(typed.states).map(([name, locs]) => [name, locs.map(at)])),
+        ...(typed.transitions === undefined
+            ? {}
+            : { transitions: typed.transitions.map((t) => ({ ...t, at: t.at.map(at) })) }),
+    };
+    const { root, anchor } = session;
+    const named = [
+        ...Object.values(map.states).flat(),
+        ...(map.transitions ?? []).flatMap((t) => t.at),
+    ].map((loc) => loc.path);
+    const tip = await pathsAt(root, anchor.tip);
+    const present = [...new Set(named)].filter((p) => tip.has(p));
+    const lines = new Map([...(await blobsAt(root, anchor.tip, present))].map(([p, bytes]) => [
+        p,
+        splitLines(bytes).length,
+    ]));
+    const problems = mapOffTip(map, lines, (p) => Buffer.from(p, "latin1").toString("utf8"));
+    if (problems.length > 0)
+        throw new UsageError(`${file}:\n  ${problems.join("\n  ")}`);
+    return map;
+}
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
 function diagramOf(args) {
     const file = args.values.get("diagram");
@@ -1950,7 +2054,7 @@ export async function main(argv, cwd) {
                 return await watch(cwd, parseArgs(rest, spec));
             }
             case "reply":
-                return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "branch"] }));
+                return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "map", "branch"] }));
             case "explain": {
                 const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
                 return await explain(cwd, parseArgs(rest, spec));
@@ -1958,7 +2062,7 @@ export async function main(argv, cwd) {
             case "show":
                 return await showRef(cwd, parseArgs(rest, { values: ["branch"] }));
             case "coverage":
-                return await coverage(cwd, parseArgs(rest, { values: ["test", "at", "branch"] }));
+                return await coverage(cwd, parseArgs(rest, { values: ["test", "at", "branch"], flags: ["reset"] }));
             case "report":
                 return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {

package/dist/src/comments.js

@@ -1,5 +1,6 @@
+import { parseLoc } from "./coverage.js";
 import { isRepoPath, isSha, isUnitId } from "./diff.js";
-import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, parsePlacedConcern, } from "./plan.js";
+import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isOfferId, isPlanVersion, isSeverity, parsePlacedConcern, } from "./plan.js";
 /**
  * The wire formats of review state, parsed once at the boundary: comments, replies, concern
  * decisions, the review file, its autosaved draft and the events a hosted session logs. Every
@@ -48,10 +49,110 @@ function parseAnchor(v) {
     }
     return { kind: "hunk", unit: v.unit, commit, changes, offsets };
 }
+function parseLocs(v, at, needed) {
+    const what = `${at}: expected a list of { path, start, end }${needed ? " with at least one place" : ""}`;
+    if (!isArray(v) || (needed && v.length === 0))
+        return what;
+    const out = [];
+    for (const [i, raw] of v.entries()) {
+        const loc = parseLoc(raw);
+        if (loc === null)
+            return `${at}[${i}]: expected { path, start, end } with 1 <= start <= end`;
+        out.push(loc);
+    }
+    return out;
+}
+const TRANSITION_ENDS = ["from", "to"];
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Boundary parse of a reply's state map. Every state has at least one place, every transition
+ * names states of the map, and with a stateDiagram every state name appears in it. The reason
+ * names the bad entry, as map.states.<name>[i] or map.transitions[i].<field>.
+ */
+export function parseStateMap(v, diagram) {
+    if (!isFields(v))
+        return "map: expected { states, transitions }";
+    if (!isFields(v.states) || Object.keys(v.states).length === 0) {
+        return "map.states: expected an object of state name to places";
+    }
+    const states = [];
+    for (const [name, raw] of Object.entries(v.states)) {
+        if (name.trim() === "")
+            return "map.states: a state has an empty name";
+        const locs = parseLocs(raw, `map.states.${name}`, true);
+        if (typeof locs === "string")
+            return locs;
+        states.push([name, locs]);
+    }
+    const named = new Set(states.map(([name]) => name));
+    const transitions = [];
+    const rawTransitions = v.transitions ?? [];
+    if (!isArray(rawTransitions))
+        return "map.transitions: expected a list";
+    for (const [i, raw] of rawTransitions.entries()) {
+        const at = `map.transitions[${i}]`;
+        if (!isFields(raw))
+            return `${at}: expected { from, to, event, at }`;
+        for (const end of TRANSITION_ENDS) {
+            const state = raw[end];
+            if (typeof state !== "string" || !named.has(state)) {
+                return `${at}.${end}: ${JSON.stringify(state)} is not a state in map.states`;
+            }
+        }
+        const { from, to, event } = raw;
+        if (typeof from !== "string" || typeof to !== "string")
+            return `${at}: expected from and to`;
+        if (event !== undefined && typeof event !== "string")
+            return `${at}.event: expected a string`;
+        const locs = parseLocs(raw.at, `${at}.at`, false);
+        if (typeof locs === "string")
+            return locs;
+        transitions.push({ from, to, ...(event === undefined ? {} : { event }), at: locs });
+    }
+    const first = (diagram ?? "")
+        .split("\n")
+        .find((line) => line.trim() !== "")
+        ?.trim() ?? "";
+    if (first.startsWith("stateDiagram")) {
+        for (const name of named) {
+            if (!new RegExp(`(^|[^\\w])${escapeRegExp(name)}([^\\w]|$)`, "m").test(diagram ?? "")) {
+                return `map.states.${name}: not a state of the stateDiagram`;
+            }
+        }
+    }
+    return {
+        states: Object.fromEntries(states),
+        ...(transitions.length === 0 ? {} : { transitions }),
+    };
+}
+/**
+ * Where a map points past the tip: a path the tip has no file at, or lines beyond its end. lines
+ * holds the line count of every tip file the map names that exists; show prints a path.
+ */
+export function mapOffTip(map, lines, show = (path) => path) {
+    const check = (loc, at) => {
+        const count = lines.get(loc.path);
+        if (count === undefined)
+            return [`${at}: ${show(loc.path)} is not a file at the tip`];
+        if (loc.end > count) {
+            return [
+                `${at}: lines ${loc.start}-${loc.end} are past the end of ${show(loc.path)}, which has ${count} lines at the tip`,
+            ];
+        }
+        return [];
+    };
+    return [
+        ...Object.entries(map.states).flatMap(([name, locs]) => locs.flatMap((loc, i) => check(loc, `map.states.${name}[${i}]`))),
+        ...(map.transitions ?? []).flatMap((t, i) => t.at.flatMap((loc, j) => check(loc, `map.transitions[${i}].at[${j}]`))),
+    ];
+}
 /** A stored reply. Replies a client posts go through parseNewReply, which mints id and time. */
 export function parseReply(v) {
-    if (!isFields(v))
+    if (!isFields(v)) {
         return "not an object";
+    }
     if (!isReplyId(v.id))
         return "id is not a reply id";
     if (v.author !== "agent" && v.author !== "reviewer")
@@ -61,30 +162,50 @@ export function parseReply(v) {
     }
     if (v.diagram !== undefined && typeof v.diagram !== "string")
         return "diagram is not a string";
+    const map = v.map === undefined ? undefined : parseStateMap(v.map, v.diagram);
+    if (typeof map === "string")
+        return map;
     return {
         id: v.id,
         author: v.author,
         body: v.body,
         ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
+        ...(map === undefined ? {} : { map }),
         createdAt: v.createdAt,
     };
 }
-/** The body of POST .../replies: who speaks, what, and an optional Mermaid diagram. */
+/**
+ * The body of POST .../replies: who speaks, what, and an optional Mermaid diagram. The body may be
+ * empty only when the diagram is the answer.
+ */
 export function parseNewReply(v) {
     if (!isFields(v))
         return "the reply is not an object";
     if (v.author !== "agent" && v.author !== "reviewer")
         return 'author is not "agent" or "reviewer"';
-    if (typeof v.body !== "string" || v.body.trim() === "")
-        return "body is not a non-empty string";
-    if (v.diagram === undefined)
+    if (typeof v.body !== "string")
+        return "body is not a string";
+    if (v.diagram === undefined) {
+        if (v.map !== undefined)
+            return "map needs the diagram it ties to code";
+        if (v.body.trim() === "")
+            return "body is empty; a reply needs words or a diagram";
         return { author: v.author, body: v.body };
+    }
     if (typeof v.diagram !== "string")
         return "diagram is not a string";
     const problem = diagramProblem(v.diagram);
     if (problem !== null)
         return `diagram: ${problem}`;
-    return { author: v.author, body: v.body, diagram: v.diagram };
+    const map = v.map === undefined ? undefined : parseStateMap(v.map, v.diagram);
+    if (typeof map === "string")
+        return map;
+    return {
+        author: v.author,
+        body: v.body,
+        diagram: v.diagram,
+        ...(map === undefined ? {} : { map }),
+    };
 }
 function isString(v) {
     return typeof v === "string";
@@ -133,6 +254,14 @@ export function parseComment(v) {
     const severity = v.severity;
     if (severity !== undefined && !isSeverity(severity))
         return "severity is unknown";
+    const offer = v.offer;
+    if (offer !== undefined) {
+        if (!isOfferId(offer))
+            return "offer is not an offer id";
+        if (v.kind !== "question" || v.author !== undefined) {
+            return "offer is only for a reviewer's question";
+        }
+    }
     const replies = parseList(v.replies, parseReply, "replies");
     if (typeof replies === "string")
         return replies;
@@ -152,6 +281,7 @@ export function parseComment(v) {
         ...(replies.length === 0 ? {} : { replies }),
         ...(v.author === "agent" ? { author: "agent" } : {}),
         ...(v.diagram === undefined ? {} : { diagram: v.diagram }),
+        ...(offer === undefined ? {} : { offer }),
     };
 }
 function withDecision(concern, v) {
@@ -363,6 +493,9 @@ export function parseReview(v) {
     const concernsCarried = parseList(v.carriedConcerns, parseCarriedConcern, "carriedConcerns");
     if (typeof concernsCarried === "string")
         return concernsCarried;
+    const dismissed = parseIds(v.dismissedOffers, isOfferId, "dismissedOffers", "offer");
+    if (typeof dismissed === "string")
+        return dismissed;
     return {
         schema: v.schema,
         mode,
@@ -376,6 +509,7 @@ export function parseReview(v) {
         ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
         ...(carried === null ? {} : { carried }),
         ...(concernsCarried.length === 0 ? {} : { carriedConcerns: concernsCarried }),
+        ...(dismissed.length === 0 ? {} : { dismissedOffers: dismissed }),
     };
 }
 function lenient(items, parse) {
@@ -403,6 +537,7 @@ export function parseDraft(v) {
         earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
         carried: v.carried === undefined ? null : lenient(v.carried, parseCarriedRef),
         carriedConcerns: lenient(v.carriedConcerns, parseCarriedConcern),
+        dismissedOffers: lenientIds(v.dismissedOffers, isOfferId),
     };
 }
 export function parseEvent(v) {
@@ -444,6 +579,10 @@ export function parseEvent(v) {
             }
             return { seq, type: v.type, commentId: id, resolved: v.resolved };
         }
+        case "offer-dismissed":
+            return isOfferId(v.offer)
+                ? { seq, type: v.type, offer: v.offer }
+                : "offer is not an offer id";
         case "version": {
             if (!isPlanVersion(v.version) || typeof v.hash !== "string")
                 return "malformed version event";

package/dist/src/coverage.js

@@ -188,6 +188,8 @@ function mergeMax(a, b) {
     }
     return out;
 }
+/** How many tip lines a test outside the branch's changes carries for the page's peek. */
+export const PREVIEW_LINES = 8;
 /**
  * The coverage after this run. A plain run replaces everything, its TN blocks becoming its tests.
  * A named test's run adds to what is already there for the same tip, and starts over otherwise.
@@ -202,6 +204,7 @@ export function recordRun(prior, run, at) {
     const tests = new Map(base?.tests ?? []);
     const entry = {
         ...(test.at === undefined ? {} : { at: test.at }),
+        ...(test.preview === undefined ? {} : { preview: test.preview }),
         lines: hitLines(run.files),
     };
     tests.set(test.id, entry);
@@ -281,6 +284,7 @@ export function serializeCoverage(c) {
         id,
         {
             ...(t.at === undefined ? {} : { at: t.at }),
+            ...(t.preview === undefined ? {} : { preview: [...t.preview] }),
             lines: Object.fromEntries([...t.lines].map(([p, ls]) => [p, [...ls]])),
         },
     ]));
@@ -296,7 +300,8 @@ function isLine(v) {
 function entries(v) {
     return isFields(v) ? Object.entries(v) : null;
 }
-function parseLoc(v) {
+/** A { path, start, end } with 1 <= start <= end, or null. */
+export function parseLoc(v) {
     if (!isFields(v))
         return null;
     const { path, start, end } = v;
@@ -350,6 +355,11 @@ function parseTest(v) {
     const at = v.at === undefined ? undefined : parseLoc(v.at);
     if (at === null)
         return "at is not a { path, start, end }";
+    const preview = v.preview;
+    if (preview !== undefined &&
+        !(Array.isArray(preview) && preview.every((l) => typeof l === "string"))) {
+        return "preview is not a list of lines";
+    }
     const lineEntries = entries(v.lines);
     if (lineEntries === null)
         return "lines is not an object";
@@ -360,7 +370,11 @@ function parseTest(v) {
         }
         lines.set(path, list);
     }
-    return { ...(at === undefined ? {} : { at }), lines };
+    return {
+        ...(at === undefined ? {} : { at }),
+        ...(preview === undefined ? {} : { preview: preview.filter((l) => typeof l === "string") }),
+        lines,
+    };
 }
 /** The one place coverage.json becomes a Coverage. */
 export function parseCoverage(v) {

package/dist/src/host.js

@@ -320,6 +320,29 @@ export async function fetchComments(port, summary) {
     }
     return out;
 }
+/**
+ * Offers accepted during the hosted review, on this version or a carried one, whose comment has no
+ * reply from the agent yet, oldest first.
+ */
+export async function fetchWaitingOffers(port, summary) {
+    const state = await call(port, "GET", `${summary.url}api/state`);
+    if (!isFields(state))
+        throw new RegistrationError("the server sent no state");
+    const comments = Array.isArray(state["comments"]) ? state["comments"] : [];
+    const carried = Array.isArray(state["carried"]) ? state["carried"] : [];
+    const said = [
+        ...comments.map((raw) => parseComment(raw)),
+        ...carried.map((raw) => {
+            const c = parseCarried(raw);
+            return typeof c === "string" ? c : c.comment;
+        }),
+    ];
+    return said
+        .flatMap((c) => (typeof c === "string" ? [] : [c]))
+        .filter((c) => !(c.replies ?? []).some((r) => r.author === "agent"))
+        .sort((a, b) => a.createdAt.localeCompare(b.createdAt))
+        .flatMap((c) => (c.offer === undefined ? [] : [{ offer: c.offer, comment: c.id }]));
+}
 /** One long poll of the session's event log: what happened after `since`, or nothing at timeout. */
 export async function pollEvents(port, summary, since, timeoutMs) {
     const path = `${summary.url}api/events?since=${since}&timeout=${timeoutMs}`;