@shiyuphan/follow-me 0.7.1 → 0.9.0

package/README.md

@@ -75,16 +75,24 @@ The red blob in the party hat is your branch tip. Nothing follow-me does moves i
 ![Cmd-clicking format in pow opens a peek of its definition, which lives outside this branch](assets/screenshots/definition.png)
 *Cmd-click a name to jump to where it is defined, even in a later commit, and Alt+Left to come back. A definition the branch does not change opens as a peek.*
 
+When your agent's answer names code, like `src/lib.js:4-5`, each place becomes a numbered chip. Hover the answer to tint those lines, click a chip to jump there and Alt+Left to come back. An answer that names several places is a walkthrough: press Enter on it, then `.` and `,` to step.
+
+![An agent reply naming three places as numbered chips, one in a later commit, with those lines tinted and numbered in the code and the walkthrough bar at step 1 of 3](assets/screenshots/refs.png)
+*A walkthrough. Each place the agent names is tinted and numbered on the code, the current step strongest, and the bar at the bottom says where you are.*
+
 ![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 checkout state machine reply: each state marked by whether a test reached it, tested transitions green with a count of their tests, one untested transition red and dashed, the sequences no one test drives, and a table naming the tests of each state and move](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. A transition is green with the number of tests that take it, or red and dashed when none does. When the tests run one at a time, the table names them, and a list names the sequences each step of which has a test but no one test drives. Click a state or a transition 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.*
 
 ![The hand-off page: every kept item with its original-branch path and line, an include checkbox, and copy buttons](assets/screenshots/handoff.png)
 *Submit review. Each item carries the original branch's path and line, so your agent can post it to the merge request as is.*
 
-Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `g` shows or hides coverage and `x` jumps to the next uncovered line, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
+Keys: `[` shows or hides the index, `j` and `k` move between commits, Cmd-click (Ctrl-click) goes to a definition and Alt+Left comes back, arrows and Shift+arrows pick rows inside a hunk, `c` comments on the pick, `v` marks a commit viewed, `g` shows or hides coverage and `x` jumps to the next uncovered line, `.` and `,` step through the agent's walkthrough, `?` lists the rest. An unfinished review autosaves and comes back when the page is opened again.
 
 ### Reviewing someone else's branch
 

package/dist/src/cli.js

@@ -3,15 +3,17 @@ 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 { parseRefText, refsIn, repoPathOfTyped, resolveRefs } from "./refs.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
 import { BranchMovedError, cleanSessions, coverageAt, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
@@ -31,19 +33,21 @@ 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>
+  show <h_…|c_…|k_…|path:a[-b][@n|@base]|name>
                                             print a unit, a comment's thread, a concern, the
-                                            lines around path:line in commit n, or where a name
+                                            lines around path:a-b in commit n, or where a name
                                             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,18 +90,20 @@ 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. \`path:a-b[@n]\` in backticks in the body
+                                            points at code, and is refused if it does not exist
   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
                                             from 1; with no target it is about the whole plan.
                                             watch leaves these out like your replies
-  show <h_…|c_…|k_…|path:line[@n|@base]|name> [--branch <name>]
+  show <h_…|c_…|k_…|path:a[-b][@n|@base]|name> [--branch <name>]
                                             print a unit with the commits that take it, a
                                             comment with its rows and thread, a concern with its
-                                            lines, the lines around path:line at the tip, in
+                                            lines, the lines around path:a-b at the tip, in
                                             commit n of the plan, or in the base, or each place
                                             a name is defined at the tip with the commit it
                                             lands in
@@ -107,11 +113,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 +298,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 +318,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 +1069,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 +1135,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 +1340,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 +1349,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 +1386,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 +1407,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 +1430,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,24 +1516,107 @@ 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);
+    const refs = await bodyRefs(session, open.summary.version, body);
     const id = await postReply(open.port, open.summary, commentId, {
         author: "agent",
         body,
         ...(diagram === undefined ? {} : { diagram }),
+        ...(map === undefined ? {} : { map }),
+        ...(refs.length === 0 ? {} : { refs }),
     });
     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 refs --body writes, resolved against plan `version` and the tip. Every one that does not
+ * resolve is named at once, as --map's are.
+ */
+async function bodyRefs(session, version, body) {
+    const specs = refsIn(body);
+    if (specs.length === 0)
+        return [];
+    const { root, diff } = session;
+    const otherChanged = new Set([...diff.units.values()].flatMap((u) => (diff.textFiles.has(u.path) ? [] : [u.path])));
+    const asked = [...new Set(specs.map((s) => repoPathOfTyped(s.path)))].filter((p) => isRepoPath(p) && !diff.textFiles.has(p) && !otherChanged.has(p));
+    const tip = asked.length === 0 ? new Set() : await pathsAt(root, diff.tip);
+    const present = asked.filter((p) => tip.has(p));
+    const unchanged = new Map([...(await blobsAt(root, diff.tip, present))].map(([p, bytes]) => [p, splitLines(bytes)]));
+    const { refs, problems } = resolveRefs(specs, {
+        tip: diff.tip,
+        textFiles: diff.textFiles,
+        otherChanged,
+        unchanged,
+        commits: projectedCommits(session, version),
+        version,
+    });
+    if (problems.length > 0) {
+        throw new UsageError(`--body points at code that does not resolve:\n  ${problems.join("\n  ")}`);
+    }
+    return refs;
+}
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
 function diagramOf(args) {
     const file = args.values.get("diagram");
@@ -1589,17 +1724,19 @@ async function explain(cwd, args) {
     if (open === null)
         return notOpen(session);
     const target = explainTarget(session, open.summary.version, args);
+    const refs = await bodyRefs(session, open.summary.version, body);
     const id = await postComment(open.port, open.summary, {
         ...target,
         body,
         author: "agent",
         ...(diagram === undefined ? {} : { diagram }),
+        ...(refs.length === 0 ? {} : { refs }),
     });
     say(`explained ${id}`);
     next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
-const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]|name>";
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:a[-b][@<commit>|@base]|name>";
 /** Every comment the session has, with the plan version it was made on: live ones first. */
 async function knownComments(session) {
     const open = await openOnServer(session, null);
@@ -1613,14 +1750,16 @@ async function knownComments(session) {
 }
 const SHOW_MARGIN = 3;
 /**
- * The lines around path:line as commit `at` of the latest plan writes the file (1-based), the
- * base, or the tip when `at` is undefined. Read from the plan, so it works before any apply.
+ * The lines around path:a-b as commit `at` of the latest plan writes the file (1-based), the
+ * base, or the tip when `at` is null. Read from the plan, so it works before any apply.
  */
 function showLines(session, raw) {
-    const m = /^(.+):(\d+)(?:@(\d+|base))?$/.exec(raw);
-    const [, typed, lineRaw, at] = m ?? [];
-    if (typed === undefined || lineRaw === undefined)
+    const spec = parseRefText(raw);
+    if (spec === null)
         throw new UsageError(SHOW_USAGE);
+    const { path: typed, start, end, at } = spec;
+    if (end < start)
+        throw new UsageError(`${raw} ends before it starts`);
     const path = Buffer.from(typed, "utf8").toString("latin1");
     const file = [...session.diff.textFiles.values()].find((f) => f.path === path);
     if (file === undefined) {
@@ -1628,7 +1767,7 @@ function showLines(session, raw) {
     }
     let text;
     let label;
-    if (at === undefined) {
+    if (at === null) {
         text = file.tip?.bytes ?? null;
         label = "the tip";
     }
@@ -1639,7 +1778,7 @@ function showLines(session, raw) {
     else {
         const latest = session.plans().at(-1);
         const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
-        const n = Number(at);
+        const n = at;
         if (n < 1 || n > commits.length) {
             throw new UsageError(`@${at} is not one of the ${commits.length} commits of the plan`);
         }
@@ -1658,18 +1797,18 @@ function showLines(session, raw) {
     const lines = Buffer.from(text, "latin1").toString("utf8").split("\n");
     if (lines.at(-1) === "")
         lines.pop();
-    const line = Number(lineRaw);
-    if (line < 1 || line > lines.length) {
+    if (start < 1 || end > lines.length) {
         return `${typed} has ${plural(lines.length, "line")} in ${label}\n`;
     }
-    const from = Math.max(1, line - SHOW_MARGIN);
-    const to = Math.min(lines.length, line + SHOW_MARGIN);
+    const from = Math.max(1, start - SHOW_MARGIN);
+    const to = Math.min(lines.length, end + SHOW_MARGIN);
     const width = String(to).length;
     const rows = lines.slice(from - 1, to).map((l, i) => {
         const n = from + i;
-        return `${n === line ? ">" : " "} ${String(n).padStart(width)}  ${l}`;
+        return `${n >= start && n <= end ? ">" : " "} ${String(n).padStart(width)}  ${l}`;
     });
-    return `${typed}:${line} in ${label}\n${rows.join("\n")}\n`;
+    const span = end > start ? `${start}-${end}` : `${start}`;
+    return `${typed}:${span} in ${label}\n${rows.join("\n")}\n`;
 }
 /** Expands a ref the agent was given to the lines and thread it names, so no file read is needed. */
 async function showRef(cwd, args) {
@@ -1950,7 +2089,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 +2097,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": {