tumwater 0.2.0 → 0.4.0

package/dist/src/operator/operator-commands.js

@@ -1,15 +1,18 @@
-// vocabulary: plain
-import { knownRoleIds, loadConfig } from "../config/config.js";
+import { knownRoleIds, knownRoleIdsCached, loadConfig } from "../config/config.js";
 import { fail, say, sayJson } from "../cli/cli-output.js";
-import { failOverDurationCap, flagValue, parseDurationFlag, parseRoleFlag } from "../cli/cli-args.js";
-import { errorMessage } from "../text/text.js";
+import { failOverDurationCap, flagValue, parseCountFlag, parseDurationFlag, parseRoleFlag } from "../cli/cli-args.js";
+import { errorMessage, splitCommaList } from "../text/text.js";
 import { PAUSE_FOR_OVERFLOW_HINT, REASON_VALUE_ERROR, ROLE_VALUE_ERROR } from "../cli/cli-flag-specs.js";
 import { artifactPhrase, hasRetirableLeftovers, previewRetire, retireRole } from "./retire.js";
-import { revertMergedCommit } from "./revert.js";
+import { previewRevert, revertFollowUp, revertMergedCommit, runRevertSha } from "./revert.js";
+import { runNotFoundMessage } from "../run/run-detail.js";
+import { readRunDetail } from "../run/run-detail-data.js";
+import { readRunRows } from "../history/history-data.js";
+import { canonicalRoleId } from "../roles/legacy-role-ids.js";
 import { agree, plural, teamResumePhrase, pauseReasonSuffix } from "../text/phrases.js";
 import { errCode } from "../errno.js";
 import { shortSha } from "../text/format.js";
-import { INSTANCE_ROLES } from "../roles/loop-ids.js";
+import { INSTANCE_ROLES } from "../roles/runner-ids.js";
 import { allRoleIds, unknownRoleMessage } from "../roles/roles.js";
 import { normalizePauseReason, pauseTeam, pauseRole, pausedRoles, resumeTeam, resumeRole, } from "../team/team-state.js";
 import { readOrchestratorInfo } from "../team/orchestrator-info.js";
@@ -21,15 +24,15 @@ import { markerApplyNote, NO_HARNESS_ERROR, PAUSE_FOR_MAX_MS, cancelScheduledSto
  * live beside their shared `--role` resolution. The marker-writing cores and shared
  * confirmations they print live in src/operator/operator-intent.ts (shared with the
  * dashboard and TUI); the team-side consumer half is src/operator/operator-requests.ts;
- * the `prompt` command, which drives the durable per-loop queues rather than the marker
+ * the `prompt` command, which drives the durable per-role queues rather than the marker
  * protocol, lives beside them in src/inbox/prompt-commands.ts, and the `config` command,
  * which reads and writes tumwater.json directly rather than touching team state, in
  * src/cli/config-commands.ts. Every command here is deliberately usable without a live
  * harness except `abort` and `stop`, which have nothing to reach when no team is up. */
 /** The `--role <id>` value when given, resolved WITHOUT tumwater.json when it names a
  * built-in catalog role: the team itself tolerates a broken config (the live reload keeps
- * the last-known-good one), so an operator marker aimed at a built-in loop must not depend
- * on the file parsing — the same resilience `logs --role` already has. A custom-loop id or
+ * the last-known-good one), so an operator marker aimed at a built-in role must not depend
+ * on the file parsing — the same resilience `logs --transcript` already has. A custom-role id or
  * an unknown id falls through to the config-backed check, which fails with the honest error
  * (the config problem, or "unknown role" naming every valid id). Returns null when no
  * --role is given. */
@@ -46,17 +49,41 @@ function namedRole(root, args) {
         fail(errorMessage(err)); // same message main().catch would print, but via the standard fail()
     }
 }
-/** namedRole for the commands that write or lift the per-role pause marker: `--role feature-1`
- * (`bugfix-1`) is the pause key of instance 1 of a multi-instance role (src/roles/loop-ids.ts's
- * instancePauseKey), returned verbatim; every other value resolves through namedRole. */
-function pauseTargetRole(root, args) {
-    const role = flagValue(args, "--role");
-    if (role && [...INSTANCE_ROLES].some((base) => role === `${base}-1`))
-        return role;
-    return namedRole(root, args);
+/** The trimmed, non-empty pieces of a comma-separated `--role` value; null when `--role` is
+ * absent, and a failure with ROLE_VALUE_ERROR when no piece remains (bare `--role`, `,`). */
+function rolePieces(args) {
+    const value = flagValue(args, "--role");
+    if (value === null)
+        return null;
+    const pieces = splitCommaList(value ?? "");
+    if (pieces.length === 0)
+        fail(ROLE_VALUE_ERROR);
+    return pieces;
+}
+/** namedRole over a comma list (`--role clean,dedupe`): every piece resolves through namedRole
+ * before the caller writes anything, so a bad id writes no marker. Deduplicated in first-seen
+ * order; null when `--role` is absent. */
+function namedRoleList(root, args) {
+    const pieces = rolePieces(args);
+    if (pieces === null)
+        return null;
+    return [...new Set(pieces.map((piece) => namedRole(root, ["--role", piece])))];
+}
+/** namedRole for the commands that write or lift the per-role pause marker, over a comma list
+ * (`--role clean,dedupe`, like `history --role`): `feature-1` (`bugfix-1`) is the pause key of
+ * instance 1 of a multi-instance role (src/roles/runner-ids.ts's instancePauseKey), kept
+ * verbatim; every other piece resolves through namedRole. Every piece resolves before the
+ * caller writes anything, so a bad id writes no marker. Deduplicated in first-seen order;
+ * null when `--role` is absent. */
+function pauseTargetRoles(root, args) {
+    const pieces = rolePieces(args);
+    if (pieces === null)
+        return null;
+    const roles = pieces.map((piece) => [...INSTANCE_ROLES].some((base) => piece === `${base}-1`) ? piece : namedRole(root, ["--role", piece]));
+    return [...new Set(roles)];
 }
 /** The `--role <id>` value a marker command requires: namedRole's resolution plus the
- * command-specific "requires --role" failure. abort and retire both need a target (unlike
+ * command-specific "requires --role" failure. retire needs a target (unlike
  * reset-counters/resume/wake, which default to every role), so the guard lives here once and
  * names the calling command in the error. */
 function requiredNamedRole(root, args, command) {
@@ -65,27 +92,26 @@ function requiredNamedRole(root, args, command) {
         fail(`${command} requires --role <id> (e.g. \`--role feature\`)`);
     return role;
 }
-/** The role(s) a marker command targets: the `--role <id>` value when given, otherwise every
- * role in the config. reset-counters and wake share the same all-roles default, so it lives
- * here once instead of drifting between their bodies. */
+/** The role(s) a marker command targets: the `--role <id>[,<id>...]` value when given,
+ * otherwise every role in the config. reset-counters and wake share the same all-roles
+ * default, so it lives here once instead of drifting between their bodies. */
 function targetRoles(root, args) {
-    const role = namedRole(root, args);
-    return role ? [role] : Object.keys(loadConfig(root).roles);
+    return namedRoleList(root, args) ?? Object.keys(loadConfig(root).roles);
 }
-/** `tumwater reset-counters [--role <id>]`: zero the per-loop counters shown in the
+/** `tumwater reset-counters [--role <id>[,<id>...]]`: zero the per-role counters shown in the
  * dashboards so a fresh observation window can begin. Scheduling fields and pi session
- * continuity are untouched: loops keep sleeping/waking exactly as before. */
+ * continuity are untouched: roles keep sleeping/waking exactly as before. */
 export async function cmdResetCounters(root, args) {
     say(requestResetCounters(root, targetRoles(root, args)));
 }
-/** `tumwater wake [--role <id>] [--in <duration> | --cancel | --list [--json]]`: tell the
- * team "whatever the loops were failing on is fixed — try again", so the named roles tick
+/** `tumwater wake [--role <id>[,<id>...]] [--in <duration> | --cancel | --list [--json]]`: tell the
+ * team "whatever the roles were failing on is fixed — try again", so the named roles run
  * within one poll instead of
  * sleeping until their backoff expires. With `--in`, the wake is scheduled: the marker is
  * written now but consumed no earlier than now + duration, the same shape `pause --for`'s
  * auto-resume takes — the wake applies at the deadline, not at submit. With `--cancel`, the
- * pending scheduled wakes (or the named role's share) are dropped instead; no wake is
- * written. With `--list`, every pending scheduled wake (or the named role's)
+ * pending scheduled wakes (or the named roles' share) are dropped instead; no wake is
+ * written. With `--list`, every pending scheduled wake (or the named roles')
  * is printed, earliest first — `--json` as an array of {roles, atMs}; read-only. */
 export async function cmdWake(root, args) {
     // `--in <duration>` (the scheduled wake): the command's own gate (runMarkerCommand's
@@ -99,9 +125,9 @@ export async function cmdWake(root, args) {
         if (inRaw !== null || args.includes("--cancel"))
             fail("wake --list cannot be combined with --in or --cancel");
         const now = Date.now();
-        const role = namedRole(root, args) ?? undefined;
-        const wakes = listWakes(root, role, now);
-        say(args.includes("--json") ? JSON.stringify(wakes) : renderWakeList(wakes, now, role));
+        const roles = namedRoleList(root, args) ?? undefined;
+        const wakes = listWakes(root, roles, now);
+        say(args.includes("--json") ? JSON.stringify(wakes) : renderWakeList(wakes, now, roles));
         return;
     }
     if (args.includes("--json"))
@@ -109,29 +135,36 @@ export async function cmdWake(root, args) {
     if (args.includes("--cancel")) {
         if (inRaw !== null)
             fail("wake --cancel and --in cannot be combined");
-        const role = namedRole(root, args);
-        say(cancelWakes(root, role ?? undefined));
+        say(cancelWakes(root, namedRoleList(root, args) ?? undefined));
         return;
     }
     const inMs = inRaw !== null ? parseDurationFlag("wake --in", inRaw) : undefined;
     if (inMs !== undefined)
         failOverDurationCap("wake --in", inMs, PAUSE_FOR_MAX_MS);
     // requestWake takes the duration, not a deadline: it reads the clock once for both the
-    // marker's deadline and its "wakes in" phrase, so no tick between two reads can reword
+    // marker's deadline and its "wakes in" phrase, so no clock advance between two reads can reword
     // "45m" as "2699999ms".
     say(requestWake(root, targetRoles(root, args), inMs));
 }
-/** `tumwater reclaim [--dry-run]`: run one manual reclaim pass over every harness worktree
- * (plans/disk-floor.md, part 3/4). `--dry-run` lists each candidate with its idle age and how
- * many ignored paths `git clean -ndX` would remove, and changes nothing — it neither cleans a
- * worktree nor writes the worktree-use registry. With a live team the
- * pass is requested through the marker the orchestrator consumes, so in-use worktrees are
- * respected; with none running it runs in-process, since nothing is in use. */
+/** `tumwater reclaim [--dry-run [--json]]`: run one manual reclaim pass over every harness
+ * worktree (plans/disk-floor.md, part 3/4). `--dry-run` lists each candidate with its idle
+ * age and how many ignored paths `git clean -ndX` would remove, and changes nothing — it
+ * neither cleans a worktree nor writes the worktree-use registry; `--json` prints those rows
+ * as data. With a live team the pass is requested through the marker the orchestrator
+ * consumes, so in-use worktrees are respected; with none running it runs in-process, since
+ * nothing is in use. */
 export async function cmdReclaim(root, args) {
     const dryRun = args.includes("--dry-run");
+    const json = args.includes("--json");
+    if (json && !dryRun)
+        fail("reclaim --json requires --dry-run");
     const idleHours = loadConfig(root).worktreeIdleReclaimHours;
     if (dryRun) {
         const candidates = await inspectReclaimCandidates(root, idleHours);
+        if (json) {
+            sayJson({ dryRun: true, idleReclaimHours: idleHours, candidates });
+            return;
+        }
         if (candidates.length === 0) {
             say("nothing to reclaim — no reclaimable worktrees");
             return;
@@ -149,20 +182,23 @@ export async function cmdReclaim(root, args) {
     }
     say(await runManualReclaim(root));
 }
-/** `tumwater abort --role <id>`: kill one loop's in-flight tick right now. The CLI cannot
+/** `tumwater abort --role <id>[,<id>...]`: kill the named roles' in-flight runs right now (a
+ * comma list writes one marker per role). The CLI cannot
  * reach into the orchestrator process, so the request rides on disk like reset-counters':
  * a per-role marker file a running team consumes within one poll cycle (the runner's
- * abortTick kills the pi child and resets the worktree to main). Requires a live harness —
- * with no team there is nothing to consume the marker. The loop stays enabled: it backs
- * off normally and later ticks proceed as usual. */
+ * abortRun kills the pi child and resets the worktree to main). Requires a live harness —
+ * with no team there is nothing to consume the marker. The role stays enabled: it backs
+ * off normally and later runs proceed as usual. */
 export async function cmdAbort(root, args) {
     // As in cmdLogs: the config exists only to validate the id against built-ins plus
-    // user-defined loops; a missing --role fails before it is ever needed.
-    const role = requiredNamedRole(root, args, "abort");
-    const result = requestAbort(root, role);
-    if (!result.ok)
-        fail(result.error);
-    say(result.message);
+    // user-defined roles; a missing --role fails before it is ever needed.
+    const roles = namedRoleList(root, args) ?? fail("abort requires --role <id> (e.g. `--role feature`)");
+    for (const role of roles) {
+        const result = requestAbort(root, role);
+        if (!result.ok)
+            fail(result.error);
+        say(result.message);
+    }
 }
 /** `tumwater restart`: apply a pending self-redeploy now, waiving the restart cooldown —
  * the terminal twin of the dashboard update alert's refresh button (POST /api/restart,
@@ -175,9 +211,10 @@ export async function cmdRestart(root, _args) {
         fail(result.error);
     say(result.message);
 }
-/** `tumwater pause [--role <id>] [--for <duration>]`: with a role, stop THAT loop from
- * starting new ticks — in-flight ones finish, every other role (the director included)
- * keeps running; without one, stop every role loop from starting NEW ticks while in-flight
+/** `tumwater pause [--role <id>[,<id>...]] [--for <duration>]`: with roles (a comma list pauses
+ * each), stop THAT role from
+ * starting new runs — in-flight ones finish, every other role (the director included)
+ * keeps running; without one, stop every role from starting NEW runs while in-flight
  * ones finish and the director keeps running (its prompts outrank operator gates, like
  * under the budget cap). The markers
  * are persistent state, not one-shot requests: presence means paused until `resume` removes
@@ -212,8 +249,8 @@ export async function cmdPause(root, args = [], now = Date.now()) {
     // discipline timedPauseBits's own `now` parameter follows.
     const timed = forMs === undefined ? undefined : { ms: forMs, untilMs: now + forMs };
     const untilMs = timed?.untilMs;
-    const role = pauseTargetRole(root, args);
-    if (role) {
+    const roles = pauseTargetRoles(root, args);
+    if (roles) {
         // The plan keeps per-role pauses anonymous (a per-role reason would need a per-role map
         // for no observed need), so a reason aimed at a role pause fails fast here — accepting
         // the flag and silently dropping the note would tell the operator the reason stands
@@ -225,7 +262,8 @@ export async function cmdPause(root, args = [], now = Date.now()) {
         // the CLI, TUI, and GUI cannot drift on format or idempotence; a false return means the
         // role was already in the set, which rolePauseMessage words — unless a `--for` stands,
         // which overwrites the deadline and reports the fresh confirmation.
-        say(rolePauseMessage(root, role, pauseRole(root, role, untilMs), timed, now));
+        for (const role of roles)
+            say(rolePauseMessage(root, role, pauseRole(root, role, untilMs), timed, now));
         return;
     }
     // pauseTeam in src/team/team-state.ts is the single writer of the pause marker — the GUI's
@@ -263,7 +301,7 @@ export function signalOrchestrator(pid) {
         throw err;
     }
 }
-/** `tumwater stop`: SIGTERM the running orchestrator, which drains its in-flight ticks and
+/** `tumwater stop`: SIGTERM the running orchestrator, which drains its in-flight runs and
  * exits — exactly the shutdown the supervised child's own SIGINT/SIGTERM handler performs, so
  * Ctrl+C and `stop` from another terminal are the same code path (the supervisor needs no
  * signal of its own: a clean child exit already ends its loop). Unlike the marker commands
@@ -303,17 +341,19 @@ export async function cmdStop(root, args = []) {
     else
         say("the orchestrator exited before the stop signal arrived — nothing is running");
 }
-/** `tumwater resume [--role <id>]`: with a role, lift that one role's pause (removed from the
- * per-role marker set); without one, lift a team pause by removing its marker. Idempotent
- * like pause: with no marker there is nothing to do. No live harness required — resuming
- * before startup just means the next `tumwater run` starts unpaused. */
+/** `tumwater resume [--role <id>[,<id>...]]`: with roles (a comma list lifts
+ * each), lift that role's pause (removed from the per-role marker set); without one,
+ * lift a team pause by removing its marker. Idempotent like pause: with no marker there
+ * is nothing to do. No live harness required — resuming before startup just means the
+ * next `tumwater run` starts unpaused. */
 export async function cmdResume(root, args = []) {
-    const role = pauseTargetRole(root, args);
-    if (role) {
+    const roles = pauseTargetRoles(root, args);
+    if (roles) {
         // resumeRole (src/team/team-state.ts) is the single remover of the per-role marker; a false
         // return means the role was never paused — the changed-state contract roleResumeMessage
         // words ("is already paused" vs "was not paused").
-        say(roleResumeMessage(root, role, resumeRole(root, role)));
+        for (const role of roles)
+            say(roleResumeMessage(root, role, resumeRole(root, role)));
         return;
     }
     // resumeTeam (src/team/team-state.ts) is the single remover, shared with the GUI toggle;
@@ -325,7 +365,7 @@ export async function cmdResume(root, args = []) {
     const { when, tail } = markerApplyNote(root);
     // The per-role pause outlives a team resume (the markers are independent), so the resumed
     // team's confirmation must name the roles still individually paused instead of claiming
-    // "role loops tick again" for loops the scheduler keeps gated.
+    // "roles run again" for roles the scheduler keeps gated.
     const still = pausedRoles(root);
     const roleNote = still.length > 0
         ? ` (${still.join(", ")} ${agree(still.length, "is", "are")} still individually paused — \`tumwater resume --role <id>\` lifts each)`
@@ -333,7 +373,7 @@ export async function cmdResume(root, args = []) {
     say(`${teamResumePhrase()}${when}${roleNote}${tail}`);
 }
 /** The role id retire targets: a built-in or configured id as for the other marker commands, or
- * else any well-formed id that still has a branch or merge ref (a loop no config names). */
+ * else any well-formed id that still has a branch or merge ref (a role no config names). */
 async function retireTargetRole(root, args) {
     const role = flagValue(args, "--role");
     if (role === null)
@@ -353,12 +393,12 @@ async function retireTargetRole(root, args) {
         return role;
     fail(unknownRoleMessage(role, ids));
 }
-/** `tumwater retire --role <id> [--force] [--json]`: remove a disabled loop's leftover worktree,
+/** `tumwater retire --role <id> [--force] [--json]`: remove a disabled role's leftover worktree,
  * branch, merge ref, and paused-state marker. The collection, safety rails, and removal live in
  * src/operator/retire.ts; this is the render layer — one line per removed artifact, the skip lines
  * that make a second run idempotent, or the `--json` payload. */
 export async function cmdRetire(root, args) {
-    // The config exists only to validate the id against built-ins plus user-defined loops, with
+    // The config exists only to validate the id against built-ins plus user-defined roles, with
     // the leftover-branch gate for ids no config names; a missing --role fails before it is needed.
     const role = await retireTargetRole(root, args);
     const force = args.includes("--force");
@@ -395,24 +435,95 @@ export async function cmdRetire(root, args) {
     if (result.removed.length === 0 && result.skipped.length === 0)
         say(`nothing to remove for role ${role}`);
 }
-/** `tumwater revert <sha>`: undo one merged change on main, committing the inverse as
- * `tumwater(operator): Revert <short sha>` under the primary-worktree lock. The lock, branch
- * guard, and fail-closed ref/conflict handling live in src/operator/revert.ts; this renderer
- * names the new main head and reminds the caller the reverted role may redo the work. */
+const REVERT_USAGE = "usage: tumwater revert <sha>|<role> <n>|<role> --last [--dry-run] [--json]";
+/** The sha the run `<role> <n>` (or the newest completed run of `<role>` under `last`) merged
+ * under, resolved the way `tumwater history <role> <n>` and the dashboard's revert resolve it
+ * (`runMergedSha`). Fails, exit 1, when the run is unknown or did not merge: revert is an
+ * action, so a miss is an error rather than history's exit-0 "not found". */
+function revertRunSha(root, positionals, last) {
+    const role = canonicalRoleId(positionals[0]);
+    const ids = knownRoleIdsCached(root);
+    if (!ids.includes(role))
+        fail(`${unknownRoleMessage(role, ids)} (${REVERT_USAGE})`);
+    const run = last
+        ? (readRunRows(root, 1, role)[0]?.run ?? null)
+        : parseCountFlag("revert <n>", positionals[1]);
+    if (run === null)
+        fail(`no completed run of ${role} in the event log`);
+    const detail = readRunDetail(root, role, run);
+    if (detail === null)
+        fail(runNotFoundMessage(role, run));
+    const found = runRevertSha(role, run, detail);
+    if (!found.ok)
+        fail(found.error);
+    const sha = found.sha;
+    return { sha, line: `run ${role} #${run} merged as ${shortSha(sha)}`, role, run };
+}
+/** `tumwater revert <sha>|<role> <n>|<role> --last`: undo one merged change on main,
+ * committing the inverse as `tumwater(operator): Revert <short sha>` under the primary-worktree
+ * lock. The lock, branch guard, and fail-closed ref/conflict handling live in
+ * src/operator/revert.ts; this renderer names the new main head and names the role
+ * that made the reverted commit, when one did, as the one that may redo the work.
+ * `--json` prints the preview or the revert as one JSON object instead (refusals still fail on
+ * stderr). */
 export async function cmdRevert(root, args) {
-    // No flags; exactly one positional names the commit to undo. A flag or extra positional
-    // fails before anything is looked up or written.
-    if (args.length !== 1)
-        fail("revert needs a commit (e.g. run tumwater revert 1a2b3c4)");
+    // `--dry-run` and `--last` are the only flags; the positionals select a sha (one), a run
+    // (`<role> <n>`) or the newest run of a role (`<role>` with --last). A flag or any other
+    // shape fails before anything is looked up or written.
+    const dryRun = args.includes("--dry-run");
+    const last = args.includes("--last");
+    const json = args.includes("--json");
+    const rest = args.filter((a) => a !== "--dry-run" && a !== "--last" && a !== "--json");
     // A flag-shaped token is a dropped flag, not a commit: refuse it before rev-parse turns a
     // lone `--json` into the misleading "no such commit". Mirrors `config set`'s
     // flag-looking-value gate and gui-command.ts's --token gate, and a real sha never starts
     // with `-`.
-    if (args[0].startsWith("-"))
-        fail(`revert takes no flags (got ${args[0]}); pass the commit to undo as the only argument`);
-    const result = await revertMergedCommit(root, args[0]);
+    const flagged = rest.find((a) => a.startsWith("-"));
+    if (flagged !== undefined)
+        fail(`revert takes only --dry-run, --last and --json (got ${flagged}); pass the commit or run to undo as the argument`);
+    if (last ? rest.length !== 1 : rest.length < 1 || rest.length > 2)
+        fail(`revert needs a commit or a run (${REVERT_USAGE})`);
+    const run = last || rest.length === 2 ? revertRunSha(root, rest, last) : null;
+    const sha = run?.sha ?? rest[0];
+    const runLine = run?.line ?? null;
+    const runRef = run === null ? null : { role: run.role, run: run.run };
+    if (dryRun) {
+        const p = await previewRevert(root, sha);
+        if (!p.ok)
+            fail(p.error);
+        if (json) {
+            sayJson({ dryRun: true, run: runRef, sha: p.sha, subject: p.subject, paths: p.paths, head: p.head, primary: p.primary, applies: p.applies, dirty: p.dirty });
+            if (!p.applies || p.dirty)
+                process.exitCode = 1;
+            return;
+        }
+        if (runLine !== null)
+            say(runLine);
+        say(`would revert ${shortSha(p.sha)} ${p.subject}`);
+        for (const path of p.paths)
+            say(`  ${path}`);
+        const on = `on ${p.primary} (HEAD ${shortSha(p.head)}); nothing was written`;
+        if (p.applies && !p.dirty)
+            say(`applies cleanly ${on}`);
+        if (!p.applies)
+            say(`would conflict ${on}`);
+        if (p.dirty)
+            say("the checkout has staged or unstaged changes, so tumwater revert would refuse until they are committed or stashed; nothing was written");
+        if (!p.applies || p.dirty)
+            process.exitCode = 1;
+        return;
+    }
+    const result = await revertMergedCommit(root, sha);
     if (!result.ok)
         fail(result.error);
+    if (json) {
+        sayJson({ dryRun: false, run: runRef, subject: result.subject, headSha: result.headSha, beforeSha: result.beforeSha, followUp: revertFollowUp(result.subject) });
+        return;
+    }
+    if (runLine !== null)
+        say(runLine);
     say(`main is now ${shortSha(result.headSha)}`);
-    say("the reverted role may redo the work, so cancel or edit its PLANS.md/BUGS.md entry if it should not");
+    const followUp = revertFollowUp(result.subject);
+    if (followUp !== null)
+        say(followUp);
 }