@shiyuphan/follow-me 0.1.1 → 0.3.0

package/dist/src/cli.js

@@ -1,50 +1,124 @@
-import { readFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, relative } from "node:path";
-import { PlanRequestError, requestPlan } from "./anthropic.js";
-import { DiffParseError, formatUnitRef } from "./diff.js";
-import { BranchRefusedError, GitError, treeOf, writeBranch } from "./git.js";
-import { findServer, idleMs, listSessions, openBrowser, portFallbackMessage, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stopServer, } from "./host.js";
-import { runInstall, runUninstall } from "./install.js";
+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 { fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postComment, postReply, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
+import { runInstall, runUninstall, syncSkills } from "./install.js";
+import { naiveDraft } from "./naive.js";
 import { serializePlanFile, validatePlan } from "./plan.js";
-import { renderFeedback, renderPrompt } from "./prompt.js";
+import { renderEvents, renderPrompt, renderReport, reportItems, } from "./prompt.js";
 import { RegistrationError, sessionIdOf } from "./server.js";
-import { BranchMovedError, cleanSessions, extractSession, openSession, SessionFileError, SessionLockedError, } from "./session.js";
+import { BranchMovedError, cleanSessions, extractSession, MissingDraftError, NotARepositoryError, openSession, SessionFileError, SessionLockedError, } from "./session.js";
+import { checkSyntax } from "./syntax.js";
 class UsageError extends Error {
     name = "UsageError";
 }
-const USAGE = `usage: follow-me <command>
+const SHORT_USAGE = `usage: follow-me [--wait <seconds>] [--branch <name>]
 
+Run follow-me with no command. Each call does the next thing that is missing and returns: it
+writes the prompt for you to answer, reports what is wrong with your draft, opens the review for
+the user, then listens to them for up to --wait seconds (default 60, 0 for none) and prints what
+they flagged or asked. Do what its "next:" line says. Run it again to keep listening.
+
+Other commands:
+  reply <commentId> --body <text> [--diagram <file>]
+                                            answer under a comment on the page; the diagram is
+                                            Mermaid source
+  explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]
+                                            start a thread on the page without being asked
+  report [--json] [--markdown]              print the report of the latest review; --json lists
+                                            the items to post to a merge request
+
+help --all lists every command.`;
+const USAGE = `usage: follow-me <command> [options]
+
+follow-me with no command is the entry point; see \`follow-me help\`. The commands below are what it
+runs, for when you want one step by hand.
+
+Split your own branch:
+  split [--base <ref>] [--branch <name>] [--no-open]
+                                            extract, apply your agent's draft and open the
+                                            review in one go; without a valid draft it writes
+                                            the prompt for your agent and stops
   extract [--base <ref>] [--branch <name>]  anchor a session and list the units
-  check [path] [--branch <name>]            validate draft.json or the given plan file
-  apply [--name <branch>] [--force]         write the draft as commits on <branch>-split or
-                                            --name; never on <branch> or a checked-out branch
+  prompt [--walk] [--branch <name>]         print the planner prompt; your coding agent
+                                            writes draft.json from it
+  plan --naive [--branch <name>]            no agent: one "wip: <path>" commit per touched
+                                            file, in diff order
+  check [path] [--branch <name>] [--syntax "<cmd {file}>"]
+                                            validate draft.json or the given plan file, and
+                                            check that every file each commit writes parses;
+                                            --syntax runs <cmd> on every text file instead of
+                                            the checker for its extension
+  apply [--name <branch>] [--force] [--sign|--no-sign] [--syntax "<cmd {file}>"]
+        [--allow-syntax-errors]             write the draft as commits on <branch>-split or
+                                            --name; never on <branch> or a checked-out branch;
+                                            refuses a commit with a file that does not parse
+                                            unless --allow-syntax-errors
+  review [--base <ref>] [--branch <name>] [--port <n>] [--detach] [--no-open]
+         [--wait [--timeout <seconds>]]     open the review, commit by commit; --wait returns
+                                            only once the review ends. After apply it reviews
+                                            your split; otherwise it plans for a reader and
+                                            reviews the code, applying nothing
   status                                    show the session's plans, reviews, lock and the
                                             branch apply writes
-  prompt [--walk] [--branch <name>]         print the planner prompt for a coding agent
-  plan [--walk] [--model <id>] [--branch <name>]
-                                            ask the Anthropic API to write draft.json
-  review [--port <n>] [--detach] [--no-open] review the latest plan commit by commit
-  walk [--base <ref>] [--branch <name>] [--model <id>] [--port <n>] [--detach] [--no-open]
-                                            watch a branch being written, narrated, and
-                                            review its code; nothing is applied
+
+Interactive loop (while the review page is open):
+  watch [--since <seq>] [--timeout <seconds>] [--json] [--follow]
+                                            wait for the reviewer to comment, ask or decide and
+                                            print it; exits 0 with news, 2 on timeout, and
+                                            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>]
+                                            answer under a comment on the page; the diagram is
+                                            Mermaid source
+  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
+  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
+                                            line in both voices, then questions with answers;
+                                            --json lists the items to post to a merge request
+                                            (path, lines, severity, body, thread, excluded)
+  apply, while the page is open, swaps it to the new plan version in place, same URL.
+
+Old names, still working:
+  walk                                      is review; prints one line saying so
+  feedback [--walk]                         is report; prints one line saying so
+
+Review server:
   server status                             show the review server and the sessions it hosts
   server stop                               stop the review server; drafts are kept
-  feedback [--branch <name>]                print the latest review as markdown
-  clean [--all] [--dry-run]                 remove sessions of deleted branches, finished
-                                            review drafts and leftovers of dead processes;
-                                            --all removes .follow-me/ entirely
-  install [--harness <ids>|--all] [--user] [--dry-run]
+
+Setup:
+  install [--harness <ids>|--all] [--project] [--dry-run]
                                             copy the skill into coding agents' skill dirs
   install --list                            show each harness, its skill dirs and docs
-  uninstall [--harness <ids>|--all] [--user] [--dry-run]
+  uninstall [--harness <ids>|--all] [--project] [--dry-run]
                                             remove the skill files install writes
+  upgrade [--harness <ids>|--all] [--project] [--dry-run]
+                                            update the package with npm, then refresh the
+                                            installed skill copies
+  clean [--all] [--dry-run]                 remove sessions of deleted branches, finished
+                                            review drafts and leftovers of dead processes;
+                                            --all removes .follow-me/ entirely
+  --version                                 print the version
+  help                                      print this
 
---walk writes the prompt for a reviewer: a story with narration instead of a split.
-review and walk share one server per user: a running one hosts the session and the command
+--walk writes the prompt for a reviewer: a story with notes instead of a split.
+review shares one server per user: a running one hosts the session and the command
 prints its URL; otherwise the command serves until its review ends, or with --detach starts the
 server in the background. --port taken by another program falls back to a free port.
---force lets apply move a branch follow-me did not create; it never allows <branch> itself.`;
+--force lets apply move a branch follow-me did not create; it never allows <branch> itself.
+apply signs the commits when your git config signs commits (commit.gpgsign, gpg.format);
+--sign signs them anyway and --no-sign never signs.`;
 function parseArgs(argv, spec) {
     const positionals = [];
     const values = new Map();
@@ -73,6 +147,34 @@ function parseArgs(argv, spec) {
 function say(line = "") {
     process.stdout.write(`${line}\n`);
 }
+/** The step that follows; every command that moves the flow forward ends with one. */
+function next(step) {
+    say(`next: ${step}`);
+}
+/**
+ * The version in the package.json above this module, which sits one directory up from src/ and
+ * two up from dist/src/.
+ */
+function version() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 3; depth++) {
+        dir = dirname(dir);
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+        }
+        catch {
+            continue;
+        }
+        if (typeof raw !== "object" || raw === null)
+            continue;
+        const name = "name" in raw ? raw.name : undefined;
+        const value = "version" in raw ? raw.version : undefined;
+        if (name === "@shiyuphan/follow-me" && typeof value === "string")
+            return value;
+    }
+    throw new Error("cannot find the package.json of follow-me");
+}
 /** Paths are latin1 so bytes round-trip; show them as the UTF-8 the user typed. */
 function show(path) {
     return Buffer.from(path, "latin1").toString("utf8");
@@ -108,13 +210,22 @@ function describeFile(diff, units) {
         status = text.base === null ? "A" : text.tip === null ? "D" : "M";
     return { status, what: parts.join(", ") };
 }
-function summarize(session, cwd) {
-    const { anchor, diff } = session;
+function unitsByPath(diff) {
     const byPath = new Map();
     for (const unit of diff.units.values()) {
         byPath.set(unit.path, [...(byPath.get(unit.path) ?? []), unit]);
     }
-    say(`${anchor.branch} ${short(anchor.tip)} onto ${anchor.baseRef} ${short(anchor.base)}: ${plural(byPath.size, "file")}, ${plural(diff.units.size, "unit")}`);
+    return byPath;
+}
+function headline(session) {
+    const { anchor, diff } = session;
+    const files = unitsByPath(diff).size;
+    return `${anchor.branch} ${short(anchor.tip)} onto ${anchor.baseRef} ${short(anchor.base)}: ${plural(files, "file")}, ${plural(diff.units.size, "unit")}`;
+}
+function summarize(session, cwd) {
+    const { diff } = session;
+    const byPath = unitsByPath(diff);
+    say(headline(session));
     const width = Math.max(0, ...[...byPath.keys()].map((p) => show(p).length));
     for (const [path, units] of byPath) {
         const { status, what } = describeFile(diff, units);
@@ -149,6 +260,12 @@ function formatIssue(issue) {
             return `$.commits[${issue.commit}]: ${show(issue.file)} is a file while ${show(issue.under)} exists`;
         case "unknown-response":
             return `response to unknown comment ${issue.comment}`;
+        case "bad-answer":
+            return `response to ${issue.comment}: ${issue.reason}`;
+        case "bad-concern":
+            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 "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}`;
@@ -160,8 +277,22 @@ function formatIssue(issue) {
     }
 }
 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 === "question-addressed") {
+        return `warning: question ${w.comment} is marked addressed; explain it with "answered" and "at" unless answering it changed the plan`;
+    }
     return `warning: comment ${w.comment} from review v${w.review} has no response`;
 }
+function concernTally(commits) {
+    const all = commits.flatMap((c) => c.concerns ?? []);
+    const parts = ["blocker", "major", "minor"].flatMap((severity) => {
+        const n = all.filter((c) => c.severity === severity).length;
+        return n === 0 ? [] : [`${n} ${severity}`];
+    });
+    return parts.length === 0 ? null : `concerns: ${parts.join(", ")}`;
+}
 function readPlanArg(path) {
     try {
         return JSON.parse(readFileSync(path, "utf8"));
@@ -204,17 +335,53 @@ async function check(cwd, args) {
     const session = await openSession(cwd, sessionOpts(args));
     const path = args.positionals[0];
     const verdict = validate(session, path === undefined ? session.readDraft() : readPlanArg(path));
-    if (!verdict.ok)
+    if (!verdict.ok) {
+        const fix = path ?? relative(cwd, session.draftPath);
+        next(`fix ${fix}, then follow-me check${path === undefined ? "" : ` ${path}`}${branchFlag(args)}`);
         return 1;
-    const { plan } = verdict;
+    }
+    listPlan(verdict.plan);
+    for (const w of verdict.warnings)
+        say(formatWarning(w));
+    const syntax = await checkSyntax(verdict.plan, syntaxOverride(args));
+    for (const line of formatSyntax(syntax))
+        say(line);
+    if (syntax.issues.length > 0) {
+        next(`fix the commits above so every file parses, then follow-me check${branchFlag(args)}`);
+        return 1;
+    }
+    next("follow-me apply");
+    return 0;
+}
+function syntaxOverride(args) {
+    const override = args.values.get("syntax");
+    if (override === undefined)
+        return {};
+    if (!override.includes("{file}"))
+        throw new UsageError("--syntax needs {file} in the command");
+    return { override };
+}
+function formatSyntax(report, mark = "") {
+    const out = report.issues.map((i) => `${mark}$.commits[${i.commit}]: ${show(i.path)}: ${i.message}`);
+    for (const i of report.tip) {
+        out.push(`${mark}${show(i.path)}: ${i.message} (the tip itself does not parse here, so earlier commits are not checked for it)`);
+    }
+    const reasons = [...new Set(report.skipped.map((s) => s.reason))];
+    const skipped = reasons.length === 0
+        ? ""
+        : `, ${plural(report.skipped.length, "file")} skipped (${reasons.join(", ")})`;
+    out.push(`syntax: ${plural(report.checked, "write")} checked${skipped}`);
+    return out;
+}
+function listPlan(plan) {
     say(`ok: ${plural(plan.commits.length, "commit")}, plan ${short(plan.hash)}`);
     for (const c of plan.commits) {
         const subject = c.message.split("\n")[0] ?? "";
         say(`  ${c.index + 1}  ${subject}  (${plural(c.refs.length, "unit")}, ${plural(c.changes.length, "file")})`);
     }
-    for (const w of verdict.warnings)
-        say(formatWarning(w));
-    return 0;
+    const tally = concernTally(plan.commits);
+    if (tally !== null)
+        say(tally);
 }
 /** Runs one command under the session's lock, so two agents never apply or review it at once. */
 async function locked(session, command, run) {
@@ -231,25 +398,85 @@ function splitBranch(session) {
 }
 async function apply(cwd, args) {
     const session = await openSession(cwd);
-    return locked(session, "apply", () => applyLocked(session, args));
+    const open = await openOnServer(session, "split");
+    if (open !== null)
+        return applyHosted(session, args, open);
+    const code = await locked(session, "apply", () => applyLocked(session, args));
+    if (code === 0)
+        next("follow-me review");
+    return code;
+}
+/**
+ * Applies while the review server hosts the session. The server holds the session lock, so the
+ * write runs under it, and the page is then swapped to the new plan version in place.
+ */
+async function applyHosted(session, args, open) {
+    const code = await applyLocked(session, args);
+    const latest = session.plans().at(-1);
+    if (code !== 0 || latest === undefined)
+        return code;
+    if (latest.version === open.summary.version) {
+        say(`plan v${latest.version} is already open: ${sessionUrl(open.port, open.summary)}`);
+    }
+    else {
+        const swapped = await swapVersion(open.port, open.summary, latest.version, latest.hash);
+        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");
+    return 0;
+}
+function signMode(args) {
+    const on = args.flags.has("sign");
+    const off = args.flags.has("no-sign");
+    if (on && off)
+        throw new UsageError("--sign and --no-sign cannot be used together");
+    return on ? "on" : off ? "off" : "config";
+}
+function describeSigning(s) {
+    return s.on ? `on (${s.format})` : "off";
 }
 async function applyLocked(session, args) {
+    const mode = signMode(args);
     const verdict = validate(session, session.readDraft());
     if (!verdict.ok)
         return 1;
-    const version = session.freeze(verdict.plan);
+    const { plan } = verdict;
+    const syntax = await checkSyntax(plan, syntaxOverride(args));
+    const allowed = args.flags.has("allow-syntax-errors");
+    if (syntax.issues.length > 0) {
+        for (const line of formatSyntax(syntax, allowed ? "warning: " : ""))
+            say(line);
+        if (!allowed) {
+            say("refusing to apply: fix the commits above, or pass --allow-syntax-errors");
+            return 1;
+        }
+    }
+    const version = session.freeze(plan);
     const name = args.values.get("name") ?? splitBranch(session);
+    const signed = await signing(session.root, mode);
     const last = session.applied();
-    const result = await writeBranch(session.root, session.diff, verdict.plan, {
-        name,
-        source: session.anchor.branch,
-        expectedOld: last?.branch === name ? last.head : null,
-        force: args.flags.has("force"),
-    });
-    session.recordApplied(version, result);
+    // Signatures can differ per run, so the record, not SHA equality, decides that nothing changed.
+    const recorded = last !== null &&
+        last.branch === name &&
+        last.version === version &&
+        last.hash === plan.hash &&
+        last.signed === signed.on &&
+        (await branchHead(session.root, name)) === last.head;
+    const result = recorded
+        ? { kind: "unchanged", branch: name, head: last.head }
+        : await writeBranch(session.root, session.diff, plan, {
+            name,
+            source: session.anchor.branch,
+            expectedOld: last?.branch === name ? last.head : null,
+            force: args.flags.has("force"),
+            sign: signed.on,
+        });
+    session.recordApplied({ version, hash: plan.hash }, { ...result, signed: signed.on });
     for (const w of verdict.warnings)
         say(formatWarning(w));
-    say(`${result.kind} ${result.branch} at ${short(result.head)} from plan v${version} (${plural(result.commits.length, "commit")})`);
+    say(`${result.kind} ${result.branch} at ${short(result.head)} from plan v${version} (${plural(plan.commits.length, "commit")})`);
+    say(`signing: ${describeSigning(signed)}`);
     const tree = await treeOf(session.root, result.head);
     const same = tree === session.anchor.tipTree;
     say(`proof: ${result.branch}^{tree} ${tree} ${same ? "equals" : "DIFFERS FROM"} ${session.anchor.branch}^{tree} ${session.anchor.tipTree}`);
@@ -263,35 +490,43 @@ function promptInput(session, mode, args) {
     };
     if (mode === "walk")
         return { ...common, mode };
+    const previous = session.plans().at(-1);
     return {
         ...common,
         mode,
-        previousPlan: session.plans().at(-1)?.file ?? null,
+        previousPlan: previous?.file ?? null,
         review: session.lastReview(),
+        previousCommits: previous === undefined ? [] : projectedCommits(session, previous.version),
     };
 }
-/** Asks the API for draft.json, feeding issues back once. Returns the plan when it validates. */
-async function draftWithApi(session, cwd, mode, args) {
-    const model = args.values.get("model");
-    const opts = model === undefined ? {} : { model };
-    let prompt = renderPrompt(promptInput(session, mode, args));
-    for (let round = 1; round <= 2; round++) {
-        const draft = await requestPlan(prompt, opts);
-        session.writeDraft(draft);
-        const verdict = validate(session, draft);
-        if (verdict.ok) {
-            say(`wrote ${relative(cwd, session.draftPath)} (${plural(verdict.plan.commits.length, "commit")})`);
-            return verdict.plan;
-        }
-        const issues = verdict.issues.map((issue) => `- ${formatIssue(issue)}`).join("\n");
-        prompt = `${prompt}\n\n## Your previous draft had these issues, write a corrected plan\n\n${issues}\n`;
-    }
-    say(`wrote ${relative(cwd, session.draftPath)} but it still has issues, repair it and run \`follow-me check${branchFlag(args)}\``);
-    return null;
+/** 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);
+    if (plan === undefined)
+        return [];
+    const verdict = validatePlan(session.diff, serializePlanFile(plan.file));
+    return verdict.ok ? verdict.plan.commits : [];
+}
+/** Writes the one-commit-per-file draft with no agent. */
+function naive(session, cwd, args) {
+    if (args.flags.has("walk")) {
+        throw new UsageError("--naive writes no story, so --walk does not apply");
+    }
+    const draft = naiveDraft(session.diff);
+    session.writeDraft(draft);
+    const verdict = validate(session, draft);
+    if (!verdict.ok)
+        return 1;
+    say(`wrote ${relative(cwd, session.draftPath)} (${plural(verdict.plan.commits.length, "commit")})`);
+    next("follow-me apply");
+    return 0;
 }
 async function plan(cwd, args) {
-    const session = await openSession(cwd, sessionOpts(args));
-    return (await draftWithApi(session, cwd, modeOf(args), args)) === null ? 1 : 0;
+    if (!args.flags.has("naive")) {
+        console.error("follow-me plan: there is no built-in model planner; your coding agent writes the draft from `follow-me prompt`, or use --naive for one commit per file");
+        return 1;
+    }
+    return naive(await openSession(cwd, sessionOpts(args)), cwd, args);
 }
 /** The latest frozen plan, or the draft frozen now when it validates. */
 function latestPlan(session) {
@@ -305,8 +540,8 @@ function latestPlan(session) {
         return null;
     return { version: session.freeze(verdict.plan), plan: verdict.plan };
 }
-function announce(mode, url, args) {
-    say(`follow-me ${mode === "walk" ? "code review" : "review"}: ${url}`);
+function announce(url, args) {
+    say(`follow-me review: ${url}`);
     if (!args.flags.has("no-open"))
         openBrowser(url);
 }
@@ -327,17 +562,12 @@ async function runningServer(home, port) {
  */
 async function hostReview(session, mode, args, prepare, report) {
     const home = stateDir();
-    const lock = session.lockState();
-    const live = await findServer(home);
-    if (live !== null && lock.kind === "held" && lock.pid === live.pid) {
-        const id = sessionIdOf(session.dir);
-        const open = (await listSessions(live.port)).find((s) => s.id === id && s.mode === mode);
-        if (open !== undefined) {
-            announce(mode, sessionUrl(live.port, open), args);
-            return { kind: "elsewhere" };
-        }
+    const open = await openOnServer(session, mode);
+    if (open !== null) {
+        announce(sessionUrl(open.port, open.summary), args);
+        return { kind: "elsewhere", ...open };
     }
-    return locked(session, mode === "walk" ? "walk" : "review", async (held) => {
+    return locked(session, "review", async (held) => {
         const prepared = await prepare();
         if (prepared === null)
             return { kind: "refused" };
@@ -363,12 +593,12 @@ async function hostReview(session, mode, args, prepare, report) {
             started = await startOrAttach(home, port, say);
         if (started.kind === "attached") {
             const summary = await registerWith(started.port, registration);
-            announce(mode, sessionUrl(started.port, summary), args);
-            return { kind: "elsewhere" };
+            announce(sessionUrl(started.port, summary), args);
+            return { kind: "elsewhere", port: started.port, summary };
         }
         const { host } = started;
         const { summary, done } = await host.register(registration);
-        announce(mode, sessionUrl(host.port, summary), args);
+        announce(sessionUrl(host.port, summary), args);
         const review = await done;
         if (review === null)
             return { kind: "stopped" };
@@ -388,24 +618,391 @@ function exitCode(hosted) {
     return hosted.kind === "refused" || hosted.kind === "stopped" ? 1 : 0;
 }
 function alreadyReviewed(session, version, args) {
-    if (!session.reviews().some((r) => r.version === version))
+    if (!reviewsOf(session).some((r) => r.version === version))
         return false;
-    console.error(`follow-me: plan v${version} already has a review; read it with \`follow-me feedback${branchFlag(args)}\` or plan again first`);
+    console.error(`follow-me: plan v${version} already has a review; read it with \`follow-me report${branchFlag(args)}\``);
     return true;
 }
-async function review(cwd, args) {
-    const session = await openSession(cwd);
-    const prepare = async () => {
+/** This session's review, of this mode or any, on the user's server when that holds its lock. */
+async function openOnServer(session, mode) {
+    const lock = session.lockState();
+    const live = await findServer(stateDir());
+    if (live === null || lock.kind !== "held" || lock.pid !== live.pid)
+        return null;
+    const id = sessionIdOf(session.dir);
+    const summary = (await listSessions(live.port)).find((s) => s.id === id && (mode === null || s.mode === mode));
+    return summary === undefined ? null : { port: live.port, summary };
+}
+function timeoutOf(args) {
+    const raw = args.values.get("timeout");
+    if (raw === undefined)
+        return undefined;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds <= 0) {
+        throw new UsageError(`--timeout ${raw} is not a number of seconds`);
+    }
+    return seconds;
+}
+/** Every finished review, oldest first, including reviewer reviews older builds stored apart. */
+function reviewsOf(session) {
+    const seen = new Set();
+    return [...session.reviews(), ...session.walkReviews()]
+        .filter((r) => !seen.has(r.version) && seen.add(r.version))
+        .sort((a, b) => a.version - b.version);
+}
+function savedReview(session, version) {
+    return reviewsOf(session).find((r) => r.version === version)?.review ?? null;
+}
+/**
+ * Polls the server until it no longer hosts the session, then reads the review it saved. Null
+ * when the server stopped without one; "timeout" when the review is still open at the deadline.
+ */
+async function waitForEnd(session, hosted, timeout) {
+    const deadline = timeout === undefined ? Number.POSITIVE_INFINITY : Date.now() + timeout * 1000;
+    while (await stillHosted(hosted.port, hosted.summary)) {
+        if (Date.now() >= deadline)
+            return "timeout";
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return savedReview(session, hosted.summary.version);
+}
+function reportSaved(review) {
+    say(`review v${review.planVersion} saved with ${plural(review.comments.length, "comment")}`);
+    next("follow-me report");
+}
+function prepareSplit(session, args) {
+    return async () => {
         const latest = latestPlan(session);
         if (latest === null || alreadyReviewed(session, latest.version, args))
             return null;
         return latest;
     };
-    const report = (review) => say(`review v${review.planVersion} saved with ${plural(review.comments.length, "comment")}`);
-    return exitCode(await hostReview(session, "split", args, prepare, report));
 }
-/** Opens the reviewer's session, re-extracting instead of failing when the branch moved. */
-async function openForWalk(cwd, args) {
+/**
+ * Author mode when a split branch was applied for the latest plan: the plan is the author's own
+ * and the review is of it. Otherwise the reader is a reviewer meeting the branch, so the plan only
+ * orders the reading and nothing is applied. The wire keeps calling that mode "walk".
+ */
+function reviewMode(session) {
+    const applied = session.applied();
+    const latest = session.plans().at(-1);
+    return applied !== null && latest !== undefined && applied.version === latest.version
+        ? "split"
+        : "walk";
+}
+/** Hosts the review of the session: the plan for its author, or the code for a reviewer. */
+async function review(cwd, args) {
+    const session = await openFresh(cwd, args);
+    const timeout = timeoutOf(args);
+    if (timeout !== undefined && !args.flags.has("wait")) {
+        throw new UsageError("--timeout only applies with --wait");
+    }
+    const open = await openOnServer(session, null);
+    const mode = open?.summary.mode ?? reviewMode(session);
+    const prepare = mode === "split" ? prepareSplit(session, args) : () => walkPlan(session, args);
+    const hosted = await hostReview(session, mode, args, prepare, reportSaved);
+    if (hosted.kind !== "elsewhere")
+        return exitCode(hosted);
+    if (!args.flags.has("wait")) {
+        next("end the review on the page, then follow-me report");
+        return 0;
+    }
+    const ended = await waitForEnd(session, hosted, timeout);
+    if (ended === "timeout") {
+        console.error(`follow-me: the review is still open after ${timeout}s; run \`follow-me review --wait\` again to keep waiting`);
+        return 1;
+    }
+    if (ended === null)
+        return exitCode({ kind: "stopped" });
+    reportSaved(ended);
+    return 0;
+}
+/** Why split needs a new draft before it can go on, or null when draft.json is ready. */
+function draftNeed(session, cwd, args) {
+    let draft;
+    try {
+        draft = session.readDraft();
+    }
+    catch (error) {
+        if (error instanceof MissingDraftError)
+            return `no draft for ${session.anchor.branch} yet`;
+        throw error;
+    }
+    const verdict = validatePlan(session.diff, draft, { lastReview: session.lastReview() });
+    if (!verdict.ok) {
+        if (verdict.issues.some((issue) => issue.kind === "stale")) {
+            return `the draft for ${session.anchor.branch} was written for an older tip`;
+        }
+        for (const issue of verdict.issues)
+            say(formatIssue(issue));
+        next(`fix ${relative(cwd, session.draftPath)}, then follow-me split${branchFlag(args)}`);
+        return "invalid";
+    }
+    const { hash } = verdict.plan;
+    const reviewed = session
+        .plans()
+        .find((p) => p.hash === hash && session.reviews().some((r) => r.version === p.version));
+    if (reviewed !== undefined) {
+        return `plan v${reviewed.version} of ${session.anchor.branch} already has a review and needs a new draft that answers it`;
+    }
+    listPlan(verdict.plan);
+    return null;
+}
+/** Writes the prompt for an agent and prints what to tell it and what to run after. */
+function handOff(session, cwd, args, why) {
+    session.writePrompt(renderPrompt(promptInput(session, "split", args)));
+    const prompt = relative(cwd, session.promptPath);
+    say(`${why}.`);
+    say(`Have your coding agent follow ${prompt} and write ${relative(cwd, session.draftPath)}, then run:`);
+    say(`  follow-me check${branchFlag(args)}`);
+    say(`  follow-me split${branchFlag(args)}`);
+    next(`hand ${prompt} to your agent`);
+}
+/**
+ * The author's one command: extract, apply the agent's draft, and open the review on the user's
+ * server. It stops with a handoff whenever there is no valid draft.
+ */
+async function split(cwd, args) {
+    const session = await openFresh(cwd, args);
+    say(headline(session));
+    const open = await openOnServer(session, "split");
+    if (open !== null) {
+        announce(sessionUrl(open.port, open.summary), args);
+        next("end the review on the page, then follow-me report");
+        return 0;
+    }
+    const need = draftNeed(session, cwd, args);
+    if (need === "invalid")
+        return 1;
+    if (need !== null) {
+        handOff(session, cwd, args, need);
+        return 1;
+    }
+    const applied = await locked(session, "apply", () => applyLocked(session, args));
+    if (applied !== 0)
+        return applied;
+    const detached = { ...args, flags: new Set([...args.flags, "detach"]) };
+    const hosted = await hostReview(session, "split", detached, prepareSplit(session, args), reportSaved);
+    if (hosted.kind !== "elsewhere")
+        return exitCode(hosted);
+    next("end the review on the page, then follow-me report");
+    return 0;
+}
+/** The mode a bare `follow-me` works in: a split already applied, else whoever wrote the branch. */
+async function entryMode(session, args) {
+    if (args.flags.has("author") && args.flags.has("reviewer")) {
+        throw new UsageError("--author and --reviewer cannot be used together");
+    }
+    if (args.flags.has("reviewer"))
+        return "walk";
+    if (args.flags.has("author"))
+        return "split";
+    if (reviewMode(session) === "split")
+        return "split";
+    return (await isOwnWork(session.root, session.anchor.base, session.anchor.tip))
+        ? "split"
+        : "walk";
+}
+function draftState(session) {
+    let draft;
+    try {
+        draft = session.readDraft();
+    }
+    catch (error) {
+        if (error instanceof MissingDraftError)
+            return { kind: "missing" };
+        throw error;
+    }
+    const verdict = validatePlan(session.diff, draft, { lastReview: session.lastReview() });
+    if (verdict.ok)
+        return { kind: "valid", prepared: verdict.plan };
+    if (verdict.issues.some((issue) => issue.kind === "stale"))
+        return { kind: "stale" };
+    for (const issue of verdict.issues)
+        say(formatIssue(issue));
+    return { kind: "invalid" };
+}
+/** The newest review of a plan that still fits the branch, or null. */
+function reviewedPlan(session) {
+    const reviews = reviewsOf(session);
+    for (const stored of reviews.toReversed()) {
+        const plan = session.plans().find((p) => p.version === stored.version);
+        if (plan !== undefined && validatePlan(session.diff, serializePlanFile(plan.file)).ok) {
+            return stored;
+        }
+    }
+    return null;
+}
+/** Prints the finished review's report, which is what the agent works from from here on. */
+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")}`);
+    process.stdout.write(text);
+    say();
+    next("done; the user can port it with follow-me report --json");
+    return 0;
+}
+/** Writes the prompt for the agent and says where; used whenever there is no plan to review. */
+function promptHandoff(session, cwd, mode, args) {
+    session.writePrompt(renderPrompt(promptInput(session, mode, args)));
+    const prompt = relative(cwd, session.promptPath);
+    const draft = relative(cwd, session.draftPath);
+    say(`wrote ${prompt}`);
+    next(`write ${draft} from ${prompt}, then run follow-me again`);
+    return 0;
+}
+function cursorPath(session) {
+    return join(session.dir, "cursor.json");
+}
+/** Where the last `follow-me` stopped reading this hosted session's events; 0 for a new one. */
+function readCursor(session, summary) {
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(cursorPath(session), "utf8"));
+    }
+    catch {
+        return 0;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return 0;
+    const seen = "session" in raw ? raw.session : undefined;
+    const seq = "seq" in raw ? raw.seq : undefined;
+    const same = seen === `${summary.id}@${summary.openedAt}`;
+    return same && typeof seq === "number" && Number.isInteger(seq) && seq >= 0 ? seq : 0;
+}
+function writeCursor(session, summary, seq) {
+    const cursor = { session: `${summary.id}@${summary.openedAt}`, seq };
+    writeFileSync(cursorPath(session), `${JSON.stringify(cursor)}\n`);
+}
+function waitOf(args) {
+    const raw = args.values.get("wait");
+    if (raw === undefined)
+        return ENTRY_WAIT_SECONDS;
+    const seconds = Number(raw);
+    if (!Number.isFinite(seconds) || seconds < 0) {
+        throw new UsageError(`--wait ${raw} is not a number of seconds`);
+    }
+    return seconds;
+}
+const ENTRY_WAIT_SECONDS = 60;
+/**
+ * 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.
+ */
+async function listen(session, open, args) {
+    const { port, summary } = open;
+    const waitMs = waitOf(args) * 1000;
+    const deadline = Date.now() + waitMs;
+    let since = readCursor(session, summary);
+    let version = summary.version;
+    for (;;) {
+        const left = Math.max(0, deadline - Date.now());
+        let batch;
+        try {
+            batch = await pollEvents(port, summary, since, Math.min(left, POLL_MS));
+        }
+        catch (error) {
+            if (!(error instanceof RegistrationError))
+                throw error;
+            // The log restarted under us (a new server); read it from the start.
+            since = 0;
+            writeCursor(session, summary, 0);
+            continue;
+        }
+        since = batch.seq;
+        writeCursor(session, summary, since);
+        for (const event of batch.events)
+            if (event.type === "version")
+                version = event.version;
+        const news = batch.events.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")) {
+                say();
+                if (ended) {
+                    const stored = reviewsOf(session).find((r) => r.version === version);
+                    if (stored !== undefined)
+                        return finished(session, stored);
+                }
+                process.stdout.write(await fetchReport(port, summary));
+                say();
+                next("done; the user can port it with follow-me report --json");
+                return 0;
+            }
+            next('answer with follow-me reply <id> --body "<markdown>" [--diagram file], or run follow-me again to keep listening');
+            return 0;
+        }
+        if (left <= 0) {
+            say(`nothing new on the review page in ${Math.round(waitMs / 1000)}s`);
+            next("run follow-me again to keep listening");
+            return 0;
+        }
+    }
+}
+/**
+ * The agent's one command. Each call does the next thing that is missing and returns: it writes
+ * the prompt, reports a bad draft, applies and opens the review, then listens to the reviewer
+ * and hands back the report once the review is submitted.
+ */
+async function entry(cwd, args) {
+    syncSkills(homedir(), say);
+    const session = await openFresh(cwd, args);
+    const hosted = await openOnServer(session, null);
+    if (hosted !== null)
+        return listen(session, hosted, args);
+    const mode = await entryMode(session, args);
+    const state = draftState(session);
+    if (state.kind === "invalid") {
+        next("fix the draft, then run follow-me again");
+        return 1;
+    }
+    const done = reviewedPlan(session);
+    if (state.kind === "valid") {
+        const reviewed = reviewsOf(session).find((r) => session.plans().find((p) => p.version === r.version)?.hash === state.prepared.hash);
+        if (reviewed !== undefined)
+            return finished(session, reviewed);
+    }
+    else if (done !== null) {
+        return finished(session, done);
+    }
+    let prepared = null;
+    if (state.kind === "valid") {
+        const syntax = await checkSyntax(state.prepared, syntaxOverride(args));
+        if (syntax.issues.length > 0) {
+            for (const line of formatSyntax(syntax))
+                say(line);
+            next("fix the draft, then run follow-me again");
+            return 1;
+        }
+        if (mode === "split") {
+            const code = await locked(session, "apply", () => applyLocked(session, args));
+            if (code !== 0) {
+                next("fix the draft, then run follow-me again");
+                return code;
+            }
+            prepared = latestPlan(session);
+        }
+        else
+            prepared = { version: session.freeze(state.prepared), plan: state.prepared };
+    }
+    else if (mode === "walk") {
+        prepared = walkablePlan(session);
+    }
+    if (prepared === null)
+        return promptHandoff(session, cwd, mode, args);
+    const prep = prepared;
+    const detached = { ...args, flags: new Set([...args.flags, "detach"]) };
+    const result = await hostReview(session, mode, detached, async () => prep, reportSaved);
+    if (result.kind !== "elsewhere")
+        return exitCode(result);
+    return listen(session, result, args);
+}
+/** Opens the session, re-extracting instead of failing when the branch moved or --base changed. */
+async function openFresh(cwd, args) {
     const opts = sessionOpts(args);
     try {
         const session = await openSession(cwd, opts);
@@ -441,49 +1038,296 @@ function walkablePlan(session) {
     const verdict = validatePlan(session.diff, draft, { lastReview });
     return verdict.ok ? { version: session.freeze(verdict.plan), plan: verdict.plan } : null;
 }
-function hasApiCredentials() {
-    return Boolean(process.env["ANTHROPIC_API_KEY"] || process.env["ANTHROPIC_AUTH_TOKEN"]);
-}
+/** The old name of review; it prints one line saying so and goes on. */
 async function walk(cwd, args) {
-    const session = await openForWalk(cwd, args);
-    const report = (review) => {
-        const saved = join(session.dir, "reviews", `v${review.planVersion}.json`);
-        say(`code review saved to ${relative(cwd, saved)} with ${plural(review.comments.length, "comment")}`);
-        say(`\`follow-me feedback${branchFlag(args)}\` prints it as a code review for the author`);
-    };
-    const hosted = await hostReview(session, "walk", args, () => walkPlan(session, cwd, args), report);
-    return exitCode(hosted);
+    console.error("follow-me: walk is now review; running review");
+    return review(cwd, args);
 }
-async function walkPlan(session, cwd, args) {
-    let latest = walkablePlan(session);
+async function walkPlan(session, args) {
+    const latest = walkablePlan(session);
     if (latest === null) {
-        if (!hasApiCredentials()) {
-            say(`no plan for ${session.anchor.branch} yet, and neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set to ask the API for one.`);
-            say("Have a coding agent follow the prompt, then walk again:");
-            say(`  follow-me prompt --walk${branchFlag(args)}`);
-            say(`  follow-me walk${branchFlag(args)}`);
-            return null;
-        }
-        const drafted = await draftWithApi(session, cwd, "walk", args);
-        if (drafted === null)
-            return null;
-        latest = { version: session.freeze(drafted), plan: drafted };
+        say(`no plan for ${session.anchor.branch} yet.`);
+        say("Have a coding agent follow the prompt, then review again:");
+        say(`  follow-me prompt --walk${branchFlag(args)}`);
+        say(`  follow-me review${branchFlag(args)}`);
+        return null;
     }
     return alreadyReviewed(session, latest.version, args) ? null : latest;
 }
-async function feedback(cwd, args) {
+/** The consolidated report of a saved review, or null after saying why it cannot be rendered. */
+function renderStored(session, stored, format = "markdown") {
+    const plan = session.plans().find((p) => p.version === stored.version);
+    if (plan === undefined) {
+        console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
+        return null;
+    }
+    const verdict = validatePlan(session.diff, serializePlanFile(plan.file));
+    if (!verdict.ok) {
+        console.error(`follow-me: plan v${plan.version} no longer fits ${session.anchor.branch}`);
+        return null;
+    }
+    // Later plans answer this review's questions.
+    const responses = session
+        .plans()
+        .filter((p) => p.version > stored.version)
+        .flatMap((p) => p.file.responses);
+    const opts = { branch: session.anchor.branch, responses };
+    if (format === "json") {
+        const items = reportItems(stored.review, verdict.plan.commits, session.diff.units, opts);
+        return `${JSON.stringify(items, null, 2)}\n`;
+    }
+    return renderReport(stored.review, verdict.plan.commits, session.diff.units, opts);
+}
+/**
+ * The report of the hosted review as it stands, else of the latest one that ended. --json lists
+ * the items to carry to a merge request; --markdown, the default, reads as the agent's to-do.
+ * --walk keeps reading only reviewer-mode reviews, as `feedback --walk` did.
+ */
+async function report(cwd, args, walkOnly = false) {
+    if (args.flags.has("json") && args.flags.has("markdown")) {
+        throw new UsageError("--json and --markdown cannot be used together");
+    }
     const session = await openSession(cwd, sessionOpts(args));
-    const stored = session.reviews().at(-1);
+    const format = args.flags.has("json") ? "json" : "markdown";
+    const open = walkOnly ? null : await openOnServer(session, null);
+    if (open !== null) {
+        const text = await fetchReport(open.port, open.summary, format);
+        process.stdout.write(format === "json" ? `${JSON.stringify(JSON.parse(text), null, 2)}\n` : text);
+        return 0;
+    }
+    const ended = (walkOnly ? session.walkReviews() : reviewsOf(session)).sort((a, b) => a.review.endedAt.localeCompare(b.review.endedAt));
+    const stored = ended.at(-1);
     if (stored === undefined) {
-        console.error("follow-me: no review yet, run `follow-me review` first");
+        console.error("follow-me: no review is open and none has ended; run `follow-me review` first");
         return 1;
     }
-    const plan = session.plans().find((p) => p.version === stored.version);
-    if (plan === undefined) {
-        console.error(`follow-me: review v${stored.version} refers to a plan that is missing`);
+    const text = renderStored(session, stored, format);
+    if (text === null)
+        return 1;
+    process.stdout.write(text);
+    return 0;
+}
+/** The old name of report. */
+async function feedback(cwd, args) {
+    console.error("follow-me: feedback is now report; printing the same");
+    return report(cwd, args, args.flags.has("walk"));
+}
+/** Events the reviewer caused; the agent's own replies, explanations and version swaps are not news. */
+function isNews(event) {
+    if (event.type === "version")
+        return false;
+    if (event.type === "comment" || event.type === "comment-updated") {
+        return event.comment.author !== "agent";
+    }
+    return !(event.type === "reply" && event.reply.author === "agent");
+}
+const POLL_MS = 25_000;
+const DEFAULT_WATCH_SECONDS = 90;
+function notOpen(session) {
+    console.error(`follow-me: ${session.anchor.branch} is not open on the review server; run \`follow-me review\` first`);
+    return 1;
+}
+/**
+ * Waits for the reviewer to do something on the hosted page and prints it. Exits 0 with the first
+ * batch, or 2 with nothing at the timeout. The log is the server's, so nothing is read from files.
+ */
+async function watch(cwd, args) {
+    const session = await openSession(cwd, sessionOpts(args));
+    const open = await openOnServer(session, null);
+    if (open === null)
+        return notOpen(session);
+    const sinceRaw = args.values.get("since");
+    let since = sinceRaw === undefined ? 0 : Number(sinceRaw);
+    if (!Number.isInteger(since) || since < 0) {
+        throw new UsageError(`--since ${sinceRaw} is not an event number`);
+    }
+    // Comments are quoted as the plan they were made on wrote them; a swap changes which that is.
+    let version = open.summary.version;
+    const quoting = (events) => {
+        for (const event of events)
+            if (event.type === "version")
+                version = event.version;
+        return { commits: projectedCommits(session, version), units: session.diff.units };
+    };
+    if (args.flags.has("follow")) {
+        let ended = false;
+        await followEvents(open.port, open.summary, since, (event) => {
+            if (event.type === "ended")
+                ended = true;
+            const ctx = quoting([event]);
+            if (!isNews(event))
+                return;
+            if (args.flags.has("json"))
+                say(JSON.stringify(event));
+            else
+                process.stdout.write(renderEvents([event], ctx));
+        });
+        if (ended)
+            return 0;
+        console.error("follow-me: the event stream closed before the review ended");
         return 1;
     }
-    process.stdout.write(renderFeedback(stored.review, plan.file, session.diff.units));
+    const deadline = Date.now() + (timeoutOf(args) ?? DEFAULT_WATCH_SECONDS) * 1000;
+    for (;;) {
+        const left = deadline - Date.now();
+        if (left <= 0) {
+            console.error(`follow-me: nothing new on the review page since event ${since}`);
+            return 2;
+        }
+        const batch = await pollEvents(open.port, open.summary, since, Math.min(left, POLL_MS));
+        since = batch.seq;
+        const ctx = quoting(batch.events);
+        const news = batch.events.filter(isNews);
+        if (news.length === 0)
+            continue;
+        if (args.flags.has("json"))
+            for (const event of news)
+                say(JSON.stringify(event));
+        else {
+            process.stdout.write(renderEvents(news, ctx));
+            next(news.some((e) => e.type === "ended")
+                ? "follow-me report"
+                : `follow-me reply <comment> --body <text>, or write a new draft and apply; then follow-me watch --since ${since}`);
+        }
+        return 0;
+    }
+}
+/** 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");
+    if (commentId === undefined || extra !== undefined || body === undefined) {
+        throw new UsageError("usage: follow-me reply <commentId> --body <text> [--diagram <file>]");
+    }
+    const diagram = diagramOf(args);
+    const session = await openSession(cwd, sessionOpts(args));
+    const open = await openOnServer(session, null);
+    if (open === null)
+        return notOpen(session);
+    const id = await postReply(open.port, open.summary, commentId, {
+        author: "agent",
+        body,
+        ...(diagram === undefined ? {} : { diagram }),
+    });
+    say(`replied ${id} to ${commentId}`);
+    next("follow-me watch");
+    return 0;
+}
+/** The Mermaid source in --diagram's file, or undefined without the flag. */
+function diagramOf(args) {
+    const file = args.values.get("diagram");
+    if (file === undefined)
+        return undefined;
+    try {
+        return readFileSync(file, "utf8");
+    }
+    catch (error) {
+        throw new UsageError(`cannot read ${file}: ${error instanceof Error ? error.message : error}`);
+    }
+}
+/** "3" or "2-5" as the change indices they name. */
+function parseLineRange(raw) {
+    const m = /^(\d+)(?:-(\d+))?$/.exec(raw);
+    const from = Number(m?.[1]);
+    const to = Number(m?.[2] ?? m?.[1]);
+    if (m === null || to < from) {
+        throw new UsageError(`--lines ${raw} is not a change line or a range like 2-5`);
+    }
+    return Array.from({ length: to - from + 1 }, (_, i) => from + i);
+}
+/**
+ * Where an explanation points: --unit with --lines names change lines of a hunk, as the prompt
+ * numbers them, and the page marks their rows. --commit alone is the commit itself; nothing is
+ * the whole plan. Commits count from 1, as the prompt prints them.
+ */
+function explainTarget(session, version, args) {
+    const commitRaw = args.values.get("commit");
+    const unitRaw = args.values.get("unit");
+    const linesRaw = args.values.get("lines");
+    if (linesRaw !== undefined && unitRaw === undefined) {
+        throw new UsageError("--lines needs --unit");
+    }
+    if (commitRaw === undefined && unitRaw === undefined) {
+        return { anchor: { kind: "plan" }, context: { commitMessage: "", path: null } };
+    }
+    const commits = projectedCommits(session, version);
+    if (commits.length === 0) {
+        throw new UsageError(`plan v${version} no longer fits ${session.anchor.branch}`);
+    }
+    const unit = unitRaw === undefined || !isUnitId(unitRaw) ? undefined : session.diff.units.get(unitRaw);
+    if (unitRaw !== undefined && unit === undefined) {
+        throw new UsageError(`--unit ${unitRaw} is not a unit of this branch`);
+    }
+    let index = -1;
+    if (commitRaw !== undefined) {
+        index = Number(commitRaw) - 1;
+        if (!Number.isInteger(index) || index < 0 || index >= commits.length) {
+            throw new UsageError(`--commit ${commitRaw} is not one of the ${commits.length} commits`);
+        }
+    }
+    else {
+        index = commits.findIndex((c) => c.refs.some((r) => r.unit === unit?.id));
+    }
+    const commit = commits[index];
+    if (commit === undefined)
+        throw new UsageError(`no commit of plan v${version} takes ${unitRaw}`);
+    if (unit === undefined) {
+        return {
+            anchor: { kind: "message", commit: index },
+            context: { commitMessage: commit.message, path: null },
+        };
+    }
+    const ref = commit.refs.find((r) => r.unit === unit.id);
+    if (ref === undefined)
+        throw new UsageError(`commit ${index + 1} does not take ${unit.id}`);
+    const context = { commitMessage: commit.message, path: unit.path };
+    if (linesRaw === undefined) {
+        return { anchor: { kind: "hunk", unit: unit.id, commit: index, changes: null }, context };
+    }
+    if (unit.kind !== "hunk")
+        throw new UsageError(`--lines needs a text hunk, ${unit.id} is not one`);
+    const changes = parseLineRange(linesRaw);
+    const taken = ref.select.kind === "lines" ? ref.select.changes : null;
+    for (const n of changes) {
+        if (n >= unit.changeCount || (taken !== null && !taken.includes(n))) {
+            throw new UsageError(`commit ${index + 1} does not take change line ${n} of ${unit.id}`);
+        }
+    }
+    const rows = unit.body.flatMap((line, offset) => line.op !== " " && changes.includes(line.change) ? [{ line, offset }] : []);
+    return {
+        anchor: {
+            kind: "hunk",
+            unit: unit.id,
+            commit: index,
+            changes,
+            offsets: rows.map((r) => r.offset),
+        },
+        context: {
+            ...context,
+            lines: rows.map(({ line }) => `${line.op}${line.text.replace(/\r?\n$/, "")}`),
+        },
+    };
+}
+/** Starts a thread on the hosted page: the agent explains before anyone asks. */
+async function explain(cwd, args) {
+    const body = args.values.get("body");
+    if (body === undefined || args.positionals.length > 0) {
+        throw new UsageError("usage: follow-me explain [--commit <n>] [--unit <id>] [--lines <a-b>] --body <text> [--diagram <file>]");
+    }
+    const diagram = diagramOf(args);
+    const session = await openSession(cwd, sessionOpts(args));
+    const open = await openOnServer(session, null);
+    if (open === null)
+        return notOpen(session);
+    const target = explainTarget(session, open.summary.version, args);
+    const id = await postComment(open.port, open.summary, {
+        ...target,
+        body,
+        author: "agent",
+        ...(diagram === undefined ? {} : { diagram }),
+    });
+    say(`explained ${id}`);
+    next("follow-me watch");
     return 0;
 }
 function describeLock(lock) {
@@ -549,7 +1393,8 @@ async function status(cwd) {
     const session = await openSession(cwd);
     const { anchor, diff } = session;
     const plans = session.plans();
-    const reviews = session.reviews();
+    const reviews = session.reviews().filter((r) => r.review.mode === "split");
+    const walks = session.walkReviews();
     say(`${anchor.branch} ${short(anchor.tip)} onto ${anchor.baseRef} ${short(anchor.base)}`);
     say(`writes to: ${splitBranch(session)}`);
     const lock = session.lockState();
@@ -579,6 +1424,11 @@ async function status(cwd) {
         const open = lastReview.review.comments.filter((c) => !answered.has(c.id)).length;
         say(`reviews: ${reviews.map((r) => `v${r.version}`).join(", ")} (latest has ${plural(lastReview.review.comments.length, "comment")}, ${open} open)`);
     }
+    if (walks.length > 0) {
+        const latest = walks.at(-1)?.review.comments.length ?? 0;
+        say(`code reviews: ${walks.map((r) => `v${r.version}`).join(", ")} (latest has ${plural(latest, "comment")})`);
+    }
+    say(`signing: ${describeSigning(await signing(session.root, "config"))}`);
     const applied = session.applied();
     say(applied === null
         ? "applied: never"
@@ -589,23 +1439,67 @@ function skillTargets(args) {
     return {
         harness: args.values.get("harness"),
         all: args.flags.has("all"),
-        user: args.flags.has("user"),
+        project: args.flags.has("project"),
         dryRun: args.flags.has("dry-run"),
     };
 }
+function missingDraft(error, cwd) {
+    return `no draft at ${relative(cwd, error.path)} yet; your coding agent writes it from \`follow-me prompt\`, or \`follow-me plan --naive\` writes one commit per file`;
+}
+const PACKAGE_NAME = "@shiyuphan/follow-me";
+/**
+ * Updates the global package, then refreshes every installed skill copy, which otherwise
+ * stays at the old version. FOLLOW_ME_UPGRADE_COMMAND replaces the npm call in tests.
+ */
+function upgrade(targets, cwd) {
+    const override = process.env["FOLLOW_ME_UPGRADE_COMMAND"];
+    const command = override === undefined
+        ? ["npm", "install", "-g", `${PACKAGE_NAME}@latest`]
+        : ["sh", "-c", override];
+    const [file, ...args] = command;
+    if (file === undefined)
+        return 1;
+    say(`${targets.dryRun ? "would run" : "running"}: ${override ?? command.join(" ")}`);
+    if (!targets.dryRun) {
+        try {
+            execFileSync(file, args, { stdio: "inherit" });
+        }
+        catch (error) {
+            console.error(`follow-me: upgrade failed: ${error instanceof Error ? error.message : error}`);
+            return 1;
+        }
+    }
+    const code = runInstall({ ...targets, list: false }, homedir(), cwd, say);
+    if (code === 0)
+        say(`next: follow-me --version`);
+    return code;
+}
+const HELP_OR_VERSION = new Set(["--help", "--version"]);
 export async function main(argv, cwd) {
     const [command, ...rest] = argv;
     try {
+        if (command === undefined || (command.startsWith("--") && !HELP_OR_VERSION.has(command))) {
+            const spec = {
+                values: ["wait", "base", "branch", "port", "syntax", "name"],
+                flags: ["no-open", "author", "reviewer", "allow-syntax-errors", "force", "sign", "no-sign"],
+            };
+            return await entry(cwd, parseArgs(argv, spec));
+        }
         switch (command) {
             case "extract": {
                 const args = parseArgs(rest, { values: ["base", "branch"] });
                 summarize(await extractSession(cwd, sessionOpts(args)), cwd);
+                const branch = branchFlag(args);
+                next(`follow-me prompt${branch}, or follow-me plan --naive${branch}`);
                 return 0;
             }
             case "check":
-                return await check(cwd, parseArgs(rest, { values: ["branch"] }));
+                return await check(cwd, parseArgs(rest, { values: ["branch", "syntax"] }));
             case "apply":
-                return await apply(cwd, parseArgs(rest, { values: ["name"], flags: ["force"] }));
+                return await apply(cwd, parseArgs(rest, {
+                    values: ["name", "syntax"],
+                    flags: ["force", "sign", "no-sign", "allow-syntax-errors"],
+                }));
             case "status":
                 parseArgs(rest, {});
                 return await status(cwd);
@@ -616,17 +1510,41 @@ export async function main(argv, cwd) {
                 return 0;
             }
             case "plan":
-                return await plan(cwd, parseArgs(rest, { values: ["model", "branch"], flags: ["walk"] }));
-            case "review":
-                return await review(cwd, parseArgs(rest, { values: ["port"], flags: ["no-open", "detach"] }));
+                return await plan(cwd, parseArgs(rest, { values: ["branch"], flags: ["walk", "naive"] }));
+            case "split": {
+                const spec = {
+                    values: ["base", "branch", "syntax"],
+                    flags: ["no-open", "allow-syntax-errors"],
+                };
+                return await split(cwd, parseArgs(rest, spec));
+            }
+            case "review": {
+                const spec = {
+                    values: ["base", "branch", "port", "timeout"],
+                    flags: ["no-open", "detach", "wait"],
+                };
+                return await review(cwd, parseArgs(rest, spec));
+            }
             case "walk": {
-                const spec = { values: ["base", "branch", "model", "port"], flags: ["no-open", "detach"] };
+                const spec = { values: ["base", "branch", "port"], flags: ["no-open", "detach"] };
                 return await walk(cwd, parseArgs(rest, spec));
             }
             case "server":
                 return await serverCommand(rest);
             case "feedback":
-                return await feedback(cwd, parseArgs(rest, { values: ["branch"] }));
+                return await feedback(cwd, parseArgs(rest, { values: ["branch"], flags: ["walk", "json", "markdown"] }));
+            case "watch": {
+                const spec = { values: ["since", "timeout", "branch"], flags: ["json", "follow"] };
+                return await watch(cwd, parseArgs(rest, spec));
+            }
+            case "reply":
+                return await reply(cwd, parseArgs(rest, { values: ["body", "diagram", "branch"] }));
+            case "explain": {
+                const spec = { values: ["commit", "unit", "lines", "body", "diagram", "branch"] };
+                return await explain(cwd, parseArgs(rest, spec));
+            }
+            case "report":
+                return await report(cwd, parseArgs(rest, { values: ["branch"], flags: ["json", "markdown"] }));
             case "clean": {
                 const args = parseArgs(rest, { flags: ["all", "dry-run"] });
                 const opts = { all: args.flags.has("all"), dryRun: args.flags.has("dry-run") };
@@ -637,21 +1555,29 @@ export async function main(argv, cwd) {
             case "install": {
                 const args = parseArgs(rest, {
                     values: ["harness"],
-                    flags: ["all", "user", "dry-run", "list"],
+                    flags: ["all", "project", "dry-run", "list"],
                 });
                 return runInstall({ ...skillTargets(args), list: args.flags.has("list") }, homedir(), cwd, say);
             }
             case "uninstall": {
-                const args = parseArgs(rest, { values: ["harness"], flags: ["all", "user", "dry-run"] });
+                const args = parseArgs(rest, { values: ["harness"], flags: ["all", "project", "dry-run"] });
                 return runUninstall(skillTargets(args), homedir(), cwd, say);
             }
-            case undefined:
+            case "upgrade": {
+                const args = parseArgs(rest, { values: ["harness"], flags: ["all", "project", "dry-run"] });
+                return upgrade(skillTargets(args), cwd);
+            }
             case "help":
+            case "-h":
             case "--help":
-                say(USAGE);
-                return command === undefined ? 1 : 0;
+                say(parseArgs(rest, { flags: ["all"] }).flags.has("all") ? USAGE : SHORT_USAGE);
+                return 0;
+            case "-v":
+            case "--version":
+                say(`follow-me ${version()}`);
+                return 0;
             default:
-                throw new UsageError(`unknown command "${command}"\n${USAGE}`);
+                throw new UsageError(`unknown command "${command}"\n${SHORT_USAGE}`);
         }
     }
     catch (error) {
@@ -663,9 +1589,12 @@ export async function main(argv, cwd) {
             SessionLockedError,
             RegistrationError,
             GitError,
-            PlanRequestError,
+            NotARepositoryError,
         ];
-        if (error instanceof DiffParseError) {
+        if (error instanceof MissingDraftError) {
+            console.error(`follow-me: ${missingDraft(error, cwd)}`);
+        }
+        else if (error instanceof DiffParseError) {
             console.error(`follow-me: could not parse the diff, please report this: ${error.message}`);
         }
         else if (error instanceof Error && known.some((k) => error instanceof k)) {