@shiyuphan/follow-me 0.1.1 → 0.2.0

package/dist/src/cli.js

@@ -1,50 +1,96 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join, relative } from "node:path";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
 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 { BranchRefusedError, branchHead, GitError, signing, treeOf, writeBranch, } from "./git.js";
+import { fetchReport, findServer, followEvents, idleMs, listSessions, openBrowser, pollEvents, portFallbackMessage, postReply, probeHealth, registerWith, sessionUrl, spawnDetached, startOrAttach, stateDir, stillHosted, stopServer, swapVersion, } from "./host.js";
 import { runInstall, runUninstall } from "./install.js";
+import { naiveDraft } from "./naive.js";
 import { serializePlanFile, validatePlan } from "./plan.js";
-import { renderFeedback, renderPrompt } from "./prompt.js";
+import { renderEvents, renderPrompt, renderReport } 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 USAGE = `usage: follow-me <command> [options]
 
+Split your own branch:
+  split [--base <ref>] [--branch <name>] [--model <id>] [--no-open]
+                                            extract, draft (with an Anthropic key), apply and
+                                            open the review in one go
   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 [--walk] [--model <id>] [--branch <name>]
+                                            the same draft as prompt, written by the
+                                            Anthropic API
+  plan --naive [--branch <name>]            no API, 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 [--port <n>] [--detach] [--no-open] [--wait [--timeout <seconds>]]
+                                            open the plan review, commit by commit; --wait
+                                            returns only once the review ends
+  feedback [--walk] [--branch <name>]       print the latest plan review as markdown, or with
+                                            --walk the latest code review
   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
+
+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
+  report                                    print the consolidated report of the open review, or
+                                            of the last one that ended: issues by file and line
+                                            in both voices, then questions with answers
+  apply, while the page is open, swaps it to the new plan version in place, same URL.
+
+Review someone else's branch:
   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
+
+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
+  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
 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 +119,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 +182,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 +232,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 +249,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 +307,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 +370,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}`);
@@ -289,9 +488,29 @@ async function draftWithApi(session, cwd, mode, args) {
     say(`wrote ${relative(cwd, session.draftPath)} but it still has issues, repair it and run \`follow-me check${branchFlag(args)}\``);
     return null;
 }
+/** Writes the one-commit-per-file draft with no API call and no agent. */
+function naive(session, cwd, args) {
+    if (args.flags.has("walk") || args.values.has("model")) {
+        throw new UsageError("--naive writes no story, so --walk and --model do 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;
+    const mode = modeOf(args);
+    if (args.flags.has("naive"))
+        return naive(session, cwd, args);
+    if ((await draftWithApi(session, cwd, mode, args)) === null)
+        return 1;
+    next(mode === "walk" ? `follow-me walk${branchFlag(args)}` : "follow-me apply");
+    return 0;
 }
 /** The latest frozen plan, or the draft frozen now when it validates. */
 function latestPlan(session) {
@@ -327,15 +546,10 @@ 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(mode, sessionUrl(open.port, open.summary), args);
+        return { kind: "elsewhere", ...open };
     }
     return locked(session, mode === "walk" ? "walk" : "review", async (held) => {
         const prepared = await prepare();
@@ -364,7 +578,7 @@ async function hostReview(session, mode, args, prepare, report) {
         if (started.kind === "attached") {
             const summary = await registerWith(started.port, registration);
             announce(mode, sessionUrl(started.port, summary), args);
-            return { kind: "elsewhere" };
+            return { kind: "elsewhere", port: started.port, summary };
         }
         const { host } = started;
         const { summary, done } = await host.register(registration);
@@ -387,25 +601,171 @@ 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))
+function alreadyReviewed(session, mode, version, args) {
+    if (!reviewsOf(session, mode).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`);
+    const branch = branchFlag(args);
+    console.error(mode === "walk"
+        ? `follow-me: plan v${version} already has a code review; read it with \`follow-me feedback --walk${branch}\``
+        : `follow-me: plan v${version} already has a review; read it with \`follow-me feedback${branch}\`, then run \`follow-me split${branch}\` for the next plan`);
     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;
+}
+/** The reviews in this mode's slot, oldest first. */
+function reviewsOf(session, mode) {
+    return mode === "walk" ? session.walkReviews() : session.reviews();
+}
+function savedReview(session, mode, version) {
+    const stored = reviewsOf(session, mode).find((r) => r.version === version);
+    return stored?.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.mode, hosted.summary.version);
+}
+function reportSplit(review) {
+    say(`review v${review.planVersion} saved with ${plural(review.comments.length, "comment")}`);
+    next("follow-me feedback");
+}
+function prepareSplit(session, args) {
+    return async () => {
         const latest = latestPlan(session);
-        if (latest === null || alreadyReviewed(session, latest.version, args))
+        if (latest === null || alreadyReviewed(session, "split", 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) {
+async function review(cwd, args) {
+    const session = await openSession(cwd);
+    const timeout = timeoutOf(args);
+    if (timeout !== undefined && !args.flags.has("wait")) {
+        throw new UsageError("--timeout only applies with --wait");
+    }
+    const hosted = await hostReview(session, "split", args, prepareSplit(session, args), reportSplit);
+    if (hosted.kind !== "elsewhere")
+        return exitCode(hosted);
+    if (!args.flags.has("wait")) {
+        next("end the review on the page, then follow-me feedback");
+        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" });
+    reportSplit(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}, and neither ANTHROPIC_API_KEY nor ANTHROPIC_AUTH_TOKEN is set to ask the API for one.`);
+    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, draft through the API when it can, apply, and open the
+ * review on the user's server. It stops with a handoff whenever an agent has to write the 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("split", sessionUrl(open.port, open.summary), args);
+        next("end the review on the page, then follow-me feedback");
+        return 0;
+    }
+    const need = draftNeed(session, cwd, args);
+    if (need === "invalid")
+        return 1;
+    if (need !== null) {
+        if (!hasApiCredentials()) {
+            handOff(session, cwd, args, need);
+            return 1;
+        }
+        say(`${need}; asking the Anthropic API for one`);
+        const drafted = await draftWithApi(session, cwd, "split", args);
+        if (drafted === null)
+            return 1;
+        listPlan(drafted);
+    }
+    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), reportSplit);
+    if (hosted.kind !== "elsewhere")
+        return exitCode(hosted);
+    next("end the review on the page, then follow-me feedback");
+    return 0;
+}
+/** 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);
@@ -445,13 +805,16 @@ function hasApiCredentials() {
     return Boolean(process.env["ANTHROPIC_API_KEY"] || process.env["ANTHROPIC_AUTH_TOKEN"]);
 }
 async function walk(cwd, args) {
-    const session = await openForWalk(cwd, args);
+    const session = await openFresh(cwd, args);
     const report = (review) => {
-        const saved = join(session.dir, "reviews", `v${review.planVersion}.json`);
+        const saved = join(session.reviewsDir("walk"), `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`);
+        next(`follow-me feedback --walk${branchFlag(args)}, which prints it as a code review for the author`);
     };
     const hosted = await hostReview(session, "walk", args, () => walkPlan(session, cwd, args), report);
+    if (hosted.kind === "elsewhere") {
+        next(`end the code review on the page, then follow-me feedback --walk${branchFlag(args)}`);
+    }
     return exitCode(hosted);
 }
 async function walkPlan(session, cwd, args) {
@@ -469,21 +832,169 @@ async function walkPlan(session, cwd, args) {
             return null;
         latest = { version: session.freeze(drafted), plan: drafted };
     }
-    return alreadyReviewed(session, latest.version, args) ? null : latest;
+    return alreadyReviewed(session, "walk", latest.version, args) ? null : latest;
+}
+/** The consolidated report of a saved review, or null after saying why it cannot be rendered. */
+function renderStored(session, stored) {
+    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);
+    return renderReport(stored.review, verdict.plan.commits, session.diff.units, {
+        branch: session.anchor.branch,
+        responses,
+    });
 }
 async function feedback(cwd, args) {
     const session = await openSession(cwd, sessionOpts(args));
-    const stored = session.reviews().at(-1);
+    const walk = args.flags.has("walk");
+    const walks = session.walkReviews();
+    const stored = walk ? walks.at(-1) : session.reviews().findLast((r) => r.review.mode === "split");
     if (stored === undefined) {
-        console.error("follow-me: no review yet, run `follow-me review` first");
+        const branch = branchFlag(args);
+        console.error(walk
+            ? `follow-me: no code review yet, run \`follow-me walk${branch}\` first`
+            : walks.length > 0
+                ? `follow-me: no plan review yet; \`follow-me feedback --walk${branch}\` prints the code review`
+                : "follow-me: no review yet, 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);
+    if (text === null)
+        return 1;
+    process.stdout.write(text);
+    say();
+    next(stored.review.mode === "walk"
+        ? "hand this to the branch's author"
+        : `hand this to your agent, then follow-me check${branchFlag(args)}`);
+    return 0;
+}
+/** The consolidated report of the hosted review as it stands, else of the last one that ended. */
+async function report(cwd, args) {
+    const session = await openSession(cwd, sessionOpts(args));
+    const open = await openOnServer(session, null);
+    if (open !== null) {
+        process.stdout.write(await fetchReport(open.port, open.summary));
+        return 0;
+    }
+    const ended = [...session.reviews(), ...session.walkReviews()].sort((a, b) => a.review.endedAt.localeCompare(b.review.endedAt));
+    const stored = ended.at(-1);
+    if (stored === undefined) {
+        console.error("follow-me: no review is open and none has ended; run `follow-me review` first");
+        return 1;
+    }
+    const text = renderStored(session, stored);
+    if (text === null)
+        return 1;
+    process.stdout.write(text);
+    return 0;
+}
+/** Events the reviewer caused; the agent's own replies and version swaps are not news to it. */
+function isNews(event) {
+    if (event.type === "version")
+        return false;
+    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`);
+    }
+    if (args.flags.has("follow")) {
+        let ended = false;
+        await followEvents(open.port, open.summary, since, (event) => {
+            if (event.type === "ended")
+                ended = true;
+            if (!isNews(event))
+                return;
+            if (args.flags.has("json"))
+                say(JSON.stringify(event));
+            else
+                process.stdout.write(renderEvents([event]));
+        });
+        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 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));
+            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 diagramFile = args.values.get("diagram");
+    let diagram;
+    if (diagramFile !== undefined) {
+        try {
+            diagram = readFileSync(diagramFile, "utf8");
+        }
+        catch (error) {
+            throw new UsageError(`cannot read ${diagramFile}: ${error instanceof Error ? error.message : error}`);
+        }
+    }
+    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;
 }
 function describeLock(lock) {
@@ -549,7 +1060,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 +1091,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,10 +1106,13 @@ 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\` has the Anthropic API write it`;
+}
 export async function main(argv, cwd) {
     const [command, ...rest] = argv;
     try {
@@ -600,12 +1120,17 @@ export async function main(argv, cwd) {
             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${branch} with an Anthropic key`);
                 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,9 +1141,18 @@ 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: ["model", "branch"], flags: ["walk", "naive"] }));
+            case "split": {
+                const spec = {
+                    values: ["base", "branch", "model", "syntax"],
+                    flags: ["no-open", "allow-syntax-errors"],
+                };
+                return await split(cwd, parseArgs(rest, spec));
+            }
+            case "review": {
+                const spec = { values: ["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"] };
                 return await walk(cwd, parseArgs(rest, spec));
@@ -626,7 +1160,15 @@ export async function main(argv, cwd) {
             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"] }));
+            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 "report":
+                return await report(cwd, parseArgs(rest, { values: ["branch"] }));
             case "clean": {
                 const args = parseArgs(rest, { flags: ["all", "dry-run"] });
                 const opts = { all: args.flags.has("all"), dryRun: args.flags.has("dry-run") };
@@ -637,19 +1179,24 @@ 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 "help":
+            case "-h":
             case "--help":
                 say(USAGE);
                 return command === undefined ? 1 : 0;
+            case "-v":
+            case "--version":
+                say(`follow-me ${version()}`);
+                return 0;
             default:
                 throw new UsageError(`unknown command "${command}"\n${USAGE}`);
         }
@@ -664,8 +1211,12 @@ export async function main(argv, cwd) {
             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)) {