@shiyuphan/follow-me 0.4.1 → 0.5.1

package/dist/src/cli.js

@@ -5,13 +5,13 @@ import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { DiffParseError, formatUnitRef, isUnitId } from "./diff.js";
 import { BranchRefusedError, branchHead, GitError, isOwnWork, signing, treeOf, writeBranch, } from "./git.js";
-import { fetchCarried, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, readServerRecord, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
-import { runInstall, runUninstall, syncSkills } from "./install.js";
+import { fetchCarried, fetchComments, fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, 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 { isFields, serializePlanFile, validatePlan } from "./plan.js";
-import { renderEvents, renderPrompt, renderReport, reportItems, } from "./prompt.js";
+import { isCommentId, isConcernId, isFields, serializePlanFile, validatePlan, } from "./plan.js";
+import { renderEvents, renderPrompt, renderReport, renderShownComment, renderShownConcern, renderShownUnit, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
-import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sinceLastPlan, } from "./session.js";
+import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, sessionComments, sinceLastPlan, } from "./session.js";
 import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
@@ -30,6 +30,9 @@ Other commands:
                                             Mermaid source
   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]>   print a unit, a comment's thread, a concern, or the
+                                            lines around path:line in commit n, instead of
+                                            reading files
   report [--json] [--markdown]              print the report of the latest review; --json lists
                                             the items to post to a merge request
 
@@ -82,6 +85,11 @@ Interactive loop (while the review page is open):
                                             --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]> [--branch <name>]
+                                            print a unit with the commits that take it, a
+                                            comment with its rows and thread, a concern with its
+                                            lines, or the lines around path:line at the tip, in
+                                            commit n of the plan, or in the base
   report [--json] [--markdown] [--branch <name>]
                                             print the report of the open review, or of the last
                                             one that ended. Markdown lists issues by file and
@@ -425,7 +433,7 @@ async function applyHosted(session, args, open) {
         say(`follow-me review: ${sessionUrl(open.port, swapped)}`);
         say(`the page now shows plan v${latest.version}; the comments on v${open.summary.version} are saved`);
     }
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
 function signMode(args) {
@@ -489,6 +497,7 @@ function promptInput(session, mode, args, changes) {
         diff: session.diff,
         draftPath: session.draftPath,
         checkCommand: `follow-me check${branchFlag(args)}`,
+        ...skillFile(),
         ...(changes === undefined ? {} : { changes }),
     };
     if (mode === "walk")
@@ -502,6 +511,17 @@ function promptInput(session, mode, args, changes) {
         previousCommits: previous === undefined ? [] : projectedCommits(session, previous.version),
     };
 }
+/** The skill this package ships, which holds the rules prompt.md points at; none if it is missing. */
+function skillFile() {
+    try {
+        return { skillPath: join(findSkillDir(), "SKILL.md") };
+    }
+    catch (error) {
+        if (error instanceof InstallError)
+            return {};
+        throw error;
+    }
+}
 /** The commits of a frozen plan as projected now, or none when it no longer fits the branch. */
 function projectedCommits(session, version) {
     const plan = session.plans().find((p) => p.version === version);
@@ -889,7 +909,9 @@ function finished(session, stored) {
     const text = renderStored(session, stored);
     if (text === null)
         return 1;
-    say(`review v${stored.version} ended with ${plural(stored.review.comments.length, "comment")}`);
+    // A review that swapped versions holds what its earlier versions said too.
+    const said = stored.review.comments.length + (stored.review.carried?.length ?? 0);
+    say(`review v${stored.version} ended with ${plural(said, "comment")}`);
     process.stdout.write(text);
     say();
     next("done; the user can port it with follow-me report --json");
@@ -917,8 +939,7 @@ function evolveHandoff(session, cwd, mode, args, moved, hosted) {
         session.writeDraft(serializePlanFile(moved.draft));
     if (draftState(session).kind === "valid")
         return null;
-    const { since, vanished, added } = moved;
-    session.writePrompt(renderPrompt(promptInput(session, mode, args, { since, vanished, added })));
+    session.writePrompt(renderPrompt(promptInput(session, mode, args, moved)));
     say(`wrote ${relative(cwd, session.promptPath)}`);
     const step = `assign the new units in ${relative(cwd, session.draftPath)}, then run follow-me again`;
     next(hosted ? `${step}; ${STILL_WORKING}` : step);
@@ -1058,9 +1079,12 @@ async function listen(session, open, args) {
         const news = fresh.filter(isNews);
         if (news.length > 0) {
             const ctx = { commits: projectedCommits(session, version), units: session.diff.units };
-            process.stdout.write(renderEvents(news, ctx));
             const ended = news.some((e) => e.type === "ended");
-            if (ended || news.some((e) => e.type === "submitted")) {
+            const done = ended || news.some((e) => e.type === "submitted");
+            // The report that follows quotes every comment, so the digest only says what else happened.
+            const shown = done ? news.filter((e) => !isCommentEvent(e)) : news;
+            process.stdout.write(renderEvents(shown, ctx));
+            if (done) {
                 say();
                 if (ended) {
                     const stored = reviewsOf(session).find((r) => r.version === version);
@@ -1218,7 +1242,19 @@ function renderStored(session, stored, format = "markdown") {
         .plans()
         .filter((p) => p.version > stored.version)
         .flatMap((p) => p.file.responses);
-    const opts = { branch: session.anchor.branch, responses };
+    const { carried } = stored.review;
+    const said = reviewsOf(session)
+        .filter((r) => r.version <= stored.version)
+        .map((r) => r.review);
+    const earlier = carried === undefined
+        ? {}
+        : {
+            earlier: {
+                comments: sessionComments(carried, said),
+                concerns: stored.review.carriedConcerns ?? [],
+            },
+        };
+    const opts = { branch: session.anchor.branch, responses, ...earlier };
     if (format === "json") {
         const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
         return `${JSON.stringify(items, null, 2)}\n`;
@@ -1259,6 +1295,9 @@ async function feedback(cwd, args) {
     console.error("follow-me: feedback is now report; printing the same");
     return report(cwd, args, args.flags.has("walk"));
 }
+function isCommentEvent(event) {
+    return event.type === "comment" || event.type === "comment-updated";
+}
 /** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
 function isNews(event) {
     if (event.type === "version")
@@ -1357,7 +1396,7 @@ async function reply(cwd, args) {
         ...(diagram === undefined ? {} : { diagram }),
     });
     say(`replied ${id} to ${commentId}`);
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
     return 0;
 }
 /** The Mermaid source in --diagram's file, or undefined without the flag. */
@@ -1474,7 +1513,123 @@ async function explain(cwd, args) {
         ...(diagram === undefined ? {} : { diagram }),
     });
     say(`explained ${id}`);
-    next("follow-me watch");
+    next(`run follow-me again; ${STILL_WORKING}`);
+    return 0;
+}
+const SHOW_USAGE = "usage: follow-me show <h_…|c_…|k_…|path:line[@<commit>|@base]>";
+/** 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);
+    const live = open === null ? [] : await fetchComments(open.port, open.summary);
+    const saved = [
+        session.priorReview("split", null),
+        session.priorReview("walk", null),
+        ...reviewsOf(session).map((r) => r.review),
+    ].flatMap((r) => (r === null ? [] : [{ version: r.planVersion, comments: r.comments }]));
+    return [...live, ...saved];
+}
+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.
+ */
+function showLines(session, raw) {
+    const m = /^(.+):(\d+)(?:@(\d+|base))?$/.exec(raw);
+    const [, typed, lineRaw, at] = m ?? [];
+    if (typed === undefined || lineRaw === undefined)
+        throw new UsageError(SHOW_USAGE);
+    const path = Buffer.from(typed, "utf8").toString("latin1");
+    const file = [...session.diff.textFiles.values()].find((f) => f.path === path);
+    if (file === undefined) {
+        return `${typed} is not a text file this branch changes; it reads the same in every commit, so read it from the working tree\n`;
+    }
+    let text;
+    let label;
+    if (at === undefined) {
+        text = file.tip?.bytes ?? null;
+        label = "the tip";
+    }
+    else if (at === "base") {
+        text = file.base === null ? null : file.base.lines.join("");
+        label = "the base";
+    }
+    else {
+        const latest = session.plans().at(-1);
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        const n = Number(at);
+        if (n < 1 || n > commits.length) {
+            throw new UsageError(`@${at} is not one of the ${commits.length} commits of the plan`);
+        }
+        text = file.base === null ? null : file.base.lines.join("");
+        for (const commit of commits.slice(0, n)) {
+            for (const change of commit.changes) {
+                if (change.path !== path)
+                    continue;
+                text = change.op === "write" ? change.bytes : null;
+            }
+        }
+        label = `commit ${n}`;
+    }
+    if (text === null)
+        return `${typed} does not exist in ${label}\n`;
+    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) {
+        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 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 `${typed}:${line} 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) {
+    const [ref, extra] = args.positionals;
+    if (ref === undefined || extra !== undefined)
+        throw new UsageError(SHOW_USAGE);
+    const session = await openSession(cwd, sessionOpts(args));
+    const { units } = session.diff;
+    const latest = session.plans().at(-1);
+    if (isUnitId(ref)) {
+        const unit = units.get(ref);
+        if (unit === undefined) {
+            throw new UsageError(`${ref} is not a unit of the branch now; its hunk changed`);
+        }
+        const commits = latest === undefined ? [] : projectedCommits(session, latest.version);
+        process.stdout.write(renderShownUnit(unit, commits));
+        return 0;
+    }
+    if (/^c_[a-z2-7]{6}$/.test(ref) && isCommentId(ref)) {
+        for (const { version, comments } of await knownComments(session)) {
+            const comment = comments.find((c) => c.id === ref);
+            if (comment === undefined)
+                continue;
+            const ctx = { commits: projectedCommits(session, version), units };
+            process.stdout.write(renderShownComment(comment, ctx, version));
+            return 0;
+        }
+        throw new UsageError(`no comment ${ref} in this session`);
+    }
+    if (isConcernId(ref)) {
+        for (const plan of session.plans().toReversed()) {
+            const commits = projectedCommits(session, plan.version);
+            for (const commit of commits) {
+                const concern = commit.concerns?.find((k) => k.id === ref);
+                if (concern === undefined)
+                    continue;
+                process.stdout.write(renderShownConcern(concern, commit.index, { commits, units }));
+                return 0;
+            }
+        }
+        throw new UsageError(`no concern ${ref} in a plan that fits the branch`);
+    }
+    process.stdout.write(showLines(session, ref));
     return 0;
 }
 function describeLock(lock) {
@@ -1711,6 +1866,8 @@ export async function main(argv, cwd) {
                 const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
                 return await explain(cwd, parseArgs(rest, spec));
             }
+            case "show":
+                return await showRef(cwd, parseArgs(rest, { values: ["branch"] }));
             case "report":
                 return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {

package/dist/src/comments.js

@@ -1,5 +1,5 @@
 import { isRepoPath, isUnitId } from "./diff.js";
-import { diagramProblem, isArray, isCommentId, isConcernId, isFields, isPlanVersion, isSeverity, } from "./plan.js";
+import { diagramProblem, isArray, isCommentId, isConcernId, isFields, 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
@@ -253,13 +253,7 @@ function parseEarlierReplies(v) {
 function isLine(v) {
     return typeof v === "number" && Number.isInteger(v) && v >= 1;
 }
-export function parseCarried(v) {
-    if (!isFields(v)) {
-        return "not an object";
-    }
-    const comment = parseComment(v.comment);
-    if (typeof comment === "string")
-        return comment;
+function parsePlacement(v) {
     const { unit, offsets, changed, path, newLine } = v;
     if (unit !== null && !(typeof unit === "string" && isUnitId(unit)))
         return "unit is not a unit id";
@@ -273,7 +267,6 @@ export function parseCarried(v) {
     if (newLine !== null && !isLine(newLine))
         return "newLine is not null or a line";
     return {
-        comment,
         unit,
         offsets: offsets === null ? null : offsets.filter(isIndex),
         changed,
@@ -281,6 +274,56 @@ export function parseCarried(v) {
         newLine,
     };
 }
+export function parseCarried(v) {
+    if (!isFields(v))
+        return "not an object";
+    const comment = parseComment(v.comment);
+    if (typeof comment === "string")
+        return comment;
+    const placement = parsePlacement(v);
+    return typeof placement === "string" ? placement : { comment, ...placement };
+}
+function parseSince(v) {
+    if (v === null)
+        return null;
+    return isPlanVersion(v) ? v : "since is not null or a plan version";
+}
+function parseCarriedRef(v) {
+    if (!isFields(v))
+        return "not an object";
+    const comment = asCommentId(v.comment);
+    if (comment === null)
+        return "comment is not a comment id";
+    if (!isPlanVersion(v.version))
+        return "version is not a plan version";
+    const since = parseSince(v.since);
+    if (typeof since === "string")
+        return since;
+    const placement = parsePlacement(v);
+    if (typeof placement === "string")
+        return placement;
+    return { ...placement, comment, version: v.version, since };
+}
+function parseCarriedConcern(v) {
+    if (!isFields(v)) {
+        return "not an object";
+    }
+    const concern = parsePlacedConcern(v.concern);
+    if (typeof concern === "string")
+        return `concern: ${concern}`;
+    if (!isIndex(v.commit))
+        return "commit is not a commit index";
+    const decision = parseDecision(v.decision);
+    if (typeof decision === "string")
+        return `decision: ${decision}`;
+    const since = parseSince(v.since);
+    if (typeof since === "string")
+        return since;
+    const placement = parsePlacement(v);
+    if (typeof placement === "string")
+        return placement;
+    return { ...placement, concern, commit: v.commit, decision, since };
+}
 /** Boundary parse of reviews/vN.json. Files written before walk mode existed have no mode. */
 export function parseReview(v) {
     if (!isFields(v)) {
@@ -314,6 +357,12 @@ export function parseReview(v) {
     const earlier = parseList(v.earlierReplies, parseEarlierReplies, "earlierReplies");
     if (typeof earlier === "string")
         return earlier;
+    const carried = v.carried === undefined ? null : parseList(v.carried, parseCarriedRef, "carried");
+    if (typeof carried === "string")
+        return carried;
+    const concernsCarried = parseList(v.carriedConcerns, parseCarriedConcern, "carriedConcerns");
+    if (typeof concernsCarried === "string")
+        return concernsCarried;
     return {
         schema: v.schema,
         mode,
@@ -325,6 +374,8 @@ export function parseReview(v) {
         ...(resolved.length === 0 ? {} : { resolved }),
         ...(anyExcluded ? { excluded } : {}),
         ...(earlier.length === 0 ? {} : { earlierReplies: earlier }),
+        ...(carried === null ? {} : { carried }),
+        ...(concernsCarried.length === 0 ? {} : { carriedConcerns: concernsCarried }),
     };
 }
 function lenient(items, parse) {
@@ -350,6 +401,8 @@ export function parseDraft(v) {
         resolved: lenientIds(v.resolved, isCommentIdValue),
         excluded: typeof excluded === "string" ? { comments: [], concerns: [] } : excluded,
         earlierReplies: lenient(v.earlierReplies, parseEarlierReplies),
+        carried: v.carried === undefined ? null : lenient(v.carried, parseCarriedRef),
+        carriedConcerns: lenient(v.carriedConcerns, parseCarriedConcern),
     };
 }
 export function parseEvent(v) {

package/dist/src/evolve.js

@@ -78,46 +78,166 @@ function distance(hunk, units, line) {
     const [from, to] = span(hunk, units);
     return line < from ? from - line : line > to ? line - to : 0;
 }
-/**
- * Pure. Places each comment of the previous version on the new diff: on its own unit when that
- * hunk is unchanged, else on the hunk of the same path nearest its old tip line.
- */
-export function carryComments(comments, oldUnits, newUnits) {
-    return comments.map((comment) => carry(comment, oldUnits, newUnits));
+/** The body row whose tip line is `line`; a kept row before a removal at the same line. */
+function rowAt(hunk, units, line) {
+    if (line === null)
+        return 0;
+    const lines = tipLines(hunk, units);
+    const row = hunk.body.findIndex((r, i) => r.op !== "-" && lines[i] === line);
+    return row === -1 ? 0 : row;
 }
-function carry(comment, oldUnits, newUnits) {
+function pinnedComment(comment) {
     const { anchor } = comment;
-    const nowhere = { comment, unit: null, offsets: null, newLine: null };
-    if (anchor.kind !== "hunk")
-        return { ...nowhere, changed: false, path: comment.context.path };
-    const kept = newUnits.get(anchor.unit);
+    // A comment on a whole hunk has no line; inventing one moves its card off the hunk's end.
+    const whole = anchor.kind === "hunk" && anchor.changes === null && anchor.offsets === undefined;
+    return { whole, row: (hunk) => firstRow(comment, hunk) };
+}
+function pinnedConcern(concern) {
+    const { lines } = concern;
+    if (lines === undefined)
+        return { whole: true, row: () => 0 };
+    return {
+        whole: false,
+        row: (hunk) => {
+            const row = hunk.body.findIndex((r) => r.op !== " " && lines.includes(r.change));
+            return row === -1 ? 0 : row;
+        },
+    };
+}
+/** Where a comment points on the version it was made on. */
+function placedOwn(comment) {
+    const { anchor } = comment;
+    return {
+        unit: anchor.kind === "hunk" ? anchor.unit : null,
+        offsets: anchor.kind === "hunk" ? (anchor.offsets ?? null) : null,
+        changed: false,
+        path: comment.context.path,
+        newLine: null,
+    };
+}
+/**
+ * Pure. Moves a placement on the old diff to the new one: a unit the new diff still has keeps its
+ * place, else the hunk of the same path nearest its old tip line takes it, marked changed. A
+ * placement on no unit stays as it is.
+ */
+function move(at, pinned, oldUnits, newUnits) {
+    if (at.unit === null)
+        return at;
+    const kept = newUnits.get(at.unit);
+    const old = oldUnits.get(at.unit);
     if (kept !== undefined) {
-        const newLine = kept.kind === "hunk" ? (tipLines(kept, newUnits)[firstRow(comment, kept)] ?? null) : null;
-        return {
-            comment,
-            unit: kept.id,
-            offsets: anchor.offsets ?? null,
-            changed: false,
-            path: kept.path,
-            newLine,
-        };
+        let newLine = null;
+        if (kept.kind === "hunk" && !pinned.whole) {
+            if (!at.changed)
+                newLine = tipLines(kept, newUnits)[pinned.row(kept)] ?? null;
+            else if (at.newLine !== null && old?.kind === "hunk") {
+                newLine = at.newLine - tipStartOf(old, oldUnits) + tipStartOf(kept, newUnits);
+            }
+            else
+                newLine = at.newLine;
+        }
+        return { ...at, path: kept.path, newLine };
     }
-    const old = oldUnits.get(anchor.unit);
-    const path = old?.path ?? comment.context.path;
+    const path = old?.path ?? at.path;
     const onPath = [...newUnits.values()].filter((u) => u.path === path);
     const first = onPath[0];
+    const moved = { offsets: null, changed: true, path };
     if (first === undefined)
-        return { ...nowhere, changed: true, path };
-    const moved = { comment, offsets: null, changed: true, path };
+        return { ...moved, unit: null, newLine: null };
     const hunks = onPath.filter((u) => u.kind === "hunk");
     if (old?.kind !== "hunk" || hunks.length === 0)
         return { ...moved, unit: first.id, newLine: null };
-    const row = firstRow(comment, old);
+    const row = at.changed ? rowAt(old, oldUnits, at.newLine) : pinned.row(old);
     const oldLine = tipLines(old, oldUnits)[row] ?? tipStartOf(old, oldUnits);
     const nearest = hunks.reduce((a, b) => distance(b, newUnits, oldLine) < distance(a, newUnits, oldLine) ? b : a);
     return {
         ...moved,
         unit: nearest.id,
-        newLine: landing(nearest, newUnits, oldLine, old.body[row]?.text),
+        newLine: pinned.whole ? null : landing(nearest, newUnits, oldLine, old.body[row]?.text),
     };
 }
+/**
+ * Pure. Places each comment of the previous version on the new diff: on its own unit when that
+ * hunk is unchanged, else on the hunk of the same path nearest its old tip line.
+ */
+export function carryComments(comments, oldUnits, newUnits) {
+    return comments.map((comment) => ({
+        comment,
+        ...move(placedOwn(comment), pinnedComment(comment), oldUnits, newUnits),
+    }));
+}
+/** since stays once set; a first change records the version the code still matched. */
+function sinceOf(before, after, since, at) {
+    return since ?? (after.changed && !before.changed ? at : null);
+}
+/**
+ * Pure. What an open review carries from version `at` into the next: what it carried already,
+ * moved again, then the comments said on `at`. Nothing is dropped, so a comment of v1 is still
+ * there after the second swap.
+ */
+export function carrySession(carried, said, at, oldUnits, newUnits) {
+    const again = carried.map((c) => {
+        const moved = move(c, pinnedComment(c.comment), oldUnits, newUnits);
+        return { ...c, ...moved, since: sinceOf(c, moved, c.since, at) };
+    });
+    const fresh = said.map((comment) => {
+        const own = placedOwn(comment);
+        const moved = move(own, pinnedComment(comment), oldUnits, newUnits);
+        return { comment, version: at, ...moved, since: sinceOf(own, moved, null, at) };
+    });
+    return [...again, ...fresh];
+}
+/**
+ * Pure. Kept concerns of version `at` that the next plan no longer has, plus those carried before,
+ * placed on the new diff. A concern the next plan has again keeps its decision there instead, so
+ * it is left out here.
+ */
+export function carryConcerns(carried, kept, inNext, at, oldUnits, newUnits) {
+    const fresh = kept.map((k) => {
+        const unit = k.concern.unit ?? null;
+        const path = unit === null ? null : (oldUnits.get(unit)?.path ?? null);
+        return { ...k, unit, offsets: null, changed: false, path, newLine: null, since: null };
+    });
+    return [...carried, ...fresh]
+        .filter((c) => !inNext.has(c.concern.id))
+        .map((c) => {
+        const moved = move(c, pinnedConcern(c.concern), oldUnits, newUnits);
+        return { ...c, ...moved, since: sinceOf(c, moved, c.since, at) };
+    });
+}
+/**
+ * Pure. Where a carried hunk comment points on the diff it was carried to, as an anchor of that
+ * diff: its own rows when the hunk is unchanged, the row at its new line when it changed, the
+ * whole hunk when it has no line. Null when the code is gone or the comment is not on a hunk.
+ */
+export function anchorOn(carried, units, commit) {
+    const { anchor } = carried.comment;
+    if (anchor.kind !== "hunk" || carried.unit === null)
+        return null;
+    if (!carried.changed)
+        return { ...anchor, commit };
+    const hunk = units.get(carried.unit);
+    if (hunk?.kind !== "hunk" || carried.newLine === null) {
+        return { kind: "hunk", unit: carried.unit, commit, changes: null };
+    }
+    const row = rowAt(hunk, units, carried.newLine);
+    const at = hunk.body[row];
+    const changes = at === undefined || at.op === " " ? [] : [at.change];
+    return { kind: "hunk", unit: carried.unit, commit, changes, offsets: [row] };
+}
+/** Pure. A carried concern as a concern of the diff it was carried to; see anchorOn. */
+export function concernOn(carried, units) {
+    const { concern } = carried;
+    if (carried.unit === null)
+        return concern;
+    if (!carried.changed)
+        return { ...concern, unit: carried.unit };
+    const { lines: _old, ...rest } = concern;
+    const hunk = units.get(carried.unit);
+    if (hunk?.kind !== "hunk" || carried.newLine === null)
+        return { ...rest, unit: carried.unit };
+    const at = hunk.body[rowAt(hunk, units, carried.newLine)];
+    return at === undefined || at.op === " "
+        ? { ...rest, unit: carried.unit }
+        : { ...rest, unit: carried.unit, lines: [at.change] };
+}

package/dist/src/harness.js

@@ -68,7 +68,10 @@ export const HARNESSES = [
 export function findHarness(id) {
     return HARNESSES.find((h) => h.id === id);
 }
+/** The files of the skill folder, SKILL.md first. */
+export const SKILL_FILES = ["SKILL.md", "porting.md"];
 export function plannedInstall(harness, scope, home, repoRoot) {
     const root = scope === "user" ? join(home, harness.userDir) : join(repoRoot, harness.projectDir);
-    return [{ path: join(root, SKILL_NAME, "SKILL.md"), source: "SKILL.md" }];
+    // porting.md is read only when the user asks to post a review, so the skill stays short.
+    return SKILL_FILES.map((source) => ({ path: join(root, SKILL_NAME, source), source }));
 }

package/dist/src/host.js

@@ -3,11 +3,11 @@ import { randomUUID } from "node:crypto";
 import { closeSync, linkSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { parseCarried, parseEvent, parseEventBatch } from "./comments.js";
+import { parseCarried, parseComment, parseEvent, parseEventBatch, } from "./comments.js";
 import { carryComments } from "./evolve.js";
 import { isPlanVersion, serializePlanFile, validatePlan } from "./plan.js";
-import { HEALTH_APP, isSessionId, loadDraftComments, PortInUseError, RegistrationError, startServer, } from "./server.js";
-import { BranchMovedError, diffOfPlan, isAlive, openSessionAt, SessionFileError, SessionLockedError, } from "./session.js";
+import { HEALTH_APP, isSessionId, loadDraft, PortInUseError, RegistrationError, startServer, } from "./server.js";
+import { BranchMovedError, diffOfPlan, isAlive, openSessionAt, SessionFileError, SessionLockedError, sessionComments, } from "./session.js";
 const RECORD = "server.json";
 const DEFAULT_IDLE_MS = 30_000;
 const START_TIMEOUT_MS = 10_000;
@@ -127,7 +127,15 @@ async function loadHosted(registration, held) {
             throw new RegistrationError(`plan v${version} no longer fits ${branch}; check it again`);
         }
         const reviewsDir = session.reviewsDir();
-        const comments = await loadDraftComments(reviewsDir, version);
+        const draft = await loadDraft(reviewsDir, version);
+        const { comments } = draft;
+        // A restart in the middle of a review that swapped: the draft names what was said before.
+        const earlier = draft.carried === null
+            ? null
+            : {
+                comments: sessionComments(draft.carried, reviewed.filter((r) => r.version < version).map((r) => r.review)),
+                concerns: draft.carriedConcerns,
+            };
         const prior = session.priorReview(mode, version);
         const previous = prior === null || prior.comments.length === 0
             ? null
@@ -151,6 +159,7 @@ async function loadHosted(registration, held) {
             release,
             previous,
             carried,
+            earlier,
             state: {
                 mode,
                 anchor: session.anchor,
@@ -295,6 +304,22 @@ export async function fetchCarried(port, summary) {
         return [carried];
     });
 }
+/** The comments of the hosted review, and of the version before a swap, with their versions. */
+export async function fetchComments(port, summary) {
+    const state = await call(port, "GET", `${summary.url}api/state`);
+    const parse = (raw) => (Array.isArray(raw) ? raw : []).flatMap((item) => {
+        const comment = parseComment(item);
+        return typeof comment === "string" ? [] : [comment];
+    });
+    if (!isFields(state))
+        throw new RegistrationError("the server sent no state");
+    const previous = state["previous"];
+    const out = [{ version: summary.version, comments: parse(state["comments"]) }];
+    if (isFields(previous) && isPlanVersion(previous["version"])) {
+        out.push({ version: previous["version"], comments: parse(previous["comments"]) });
+    }
+    return out;
+}
 /** 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}`;