tumwater 0.1.2 → 0.2.0

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

@@ -1,29 +1,33 @@
+// vocabulary: plain
 import { knownRoleIds, 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 { PAUSE_FOR_OVERFLOW_HINT, REASON_VALUE_ERROR } from "../cli/cli-flag-specs.js";
-import { artifactPhrase, retireRole } from "./retire.js";
-import { agree, fleetResumePhrase, pauseReasonSuffix } from "../text/phrases.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 { agree, plural, teamResumePhrase, pauseReasonSuffix } from "../text/phrases.js";
 import { errCode } from "../errno.js";
-import { allRoleIds } from "../roles/roles.js";
-import { normalizePauseReason, pauseFleet, pauseRole, pausedRoles, resumeFleet, resumeRole, } from "../fleet/fleet-state.js";
-import { readOrchestratorInfo } from "../fleet/orchestrator-info.js";
+import { shortSha } from "../text/format.js";
+import { INSTANCE_ROLES } from "../roles/loop-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";
 import { pidAlive } from "../process/process.js";
-import { inspectReclaimCandidates } from "../fleet/reclaim.js";
-import { markerApplyNote, NO_HARNESS_ERROR, PAUSE_FOR_MAX_MS, cancelWakes, listWakes, renderWakeList, requestAbort, requestResetCounters, requestWake, rolePauseMessage, roleResumeMessage, runManualReclaim, timedPauseBits, } from "./operator-intent.js";
+import { inspectReclaimCandidates } from "../team/reclaim.js";
+import { markerApplyNote, NO_HARNESS_ERROR, PAUSE_FOR_MAX_MS, cancelScheduledStopMessage, cancelWakes, listWakes, renderWakeList, requestAbort, requestResetCounters, requestRestart, requestScheduledStop, requestWake, rolePauseMessage, roleResumeMessage, runManualReclaim, timedPauseBits, } from "./operator-intent.js";
 /** The CLI layer of the operator commands: the `reset-counters`, `wake`, `reclaim`, `abort`,
  * `pause`, `resume`, `stop`, and `retire` commands, split out of cli.ts so the command bodies
  * 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 fleet-side consumer half is src/operator/operator-requests.ts;
+ * 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
  * protocol, lives beside them in src/inbox/prompt-commands.ts, and the `config` command,
- * which reads and writes tumwater.json directly rather than touching fleet state, in
+ * 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 fleet is up. */
+ * 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 fleet itself tolerates a broken config (the live reload keeps
+ * 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
  * an unknown id falls through to the config-backed check, which fails with the honest error
@@ -42,6 +46,15 @@ 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 `--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
  * reset-counters/resume/wake, which default to every role), so the guard lives here once and
@@ -65,12 +78,14 @@ function targetRoles(root, args) {
 export async function cmdResetCounters(root, args) {
     say(requestResetCounters(root, targetRoles(root, args)));
 }
-/** `tumwater wake [--role <id>] [--in <duration> | --cancel | --list [--json]]`: tell the fleet "whatever the loops were
- * failing on is fixed — try again", so the named roles tick within one poll instead of
+/** `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
+ * 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 role's share) are dropped instead; no wake is
+ * written. With `--list`, every pending scheduled wake (or the named role's)
  * 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
@@ -109,7 +124,7 @@ export async function cmdWake(root, args) {
 /** `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 fleet the
+ * 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. */
 export async function cmdReclaim(root, args) {
@@ -124,7 +139,7 @@ export async function cmdReclaim(root, args) {
         for (const c of candidates) {
             const notes = [
                 `idle ${c.idleHours.toFixed(1)}h`,
-                `${c.paths} ignored path${c.paths === 1 ? "" : "s"}`,
+                plural(c.paths, "ignored path"),
                 ...(c.resumePending ? ["resume pending"] : []),
                 ...(c.reclaimable ? [] : ["not idle-reclaimable"]),
             ];
@@ -136,9 +151,9 @@ export async function cmdReclaim(root, args) {
 }
 /** `tumwater abort --role <id>`: kill one loop's in-flight tick right now. The CLI cannot
  * reach into the orchestrator process, so the request rides on disk like reset-counters':
- * a per-role marker file a running fleet consumes within one poll cycle (the runner's
+ * 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 fleet there is nothing to consume the marker. The loop stays enabled: it backs
+ * with no team there is nothing to consume the marker. The loop stays enabled: it backs
  * off normally and later ticks proceed as usual. */
 export async function cmdAbort(root, args) {
     // As in cmdLogs: the config exists only to validate the id against built-ins plus
@@ -149,17 +164,28 @@ export async function cmdAbort(root, args) {
         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,
+ * handleRestart in src/gui/gui-operator-commands.ts). Both call the same marker-writing
+ * core requestRestart, so the confirmation (or refusal) is byte-for-byte the GUI's. Takes
+ * no flags. */
+export async function cmdRestart(root, _args) {
+    const result = requestRestart(root);
+    if (!result.ok)
+        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
  * 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
- * it — so pausing before startup starts an already-paused fleet. Unlike abort, no live
+ * it — so pausing before startup starts an already-paused team. Unlike abort, no live
  * harness is required; when none runs, say where the pause takes effect instead of failing.
  * Idempotent: a second pause reports the existing marker as-is. */
 export async function cmdPause(root, args = [], now = Date.now()) {
-    // `--for <duration>` (the timed pause): the ms-epoch deadline pauseFleet/pauseRole write
+    // `--for <duration>` (the timed pause): the ms-epoch deadline pauseTeam/pauseRole write
     // into the marker and every consumer honors — the command's own gate (runMarkerCommand's
     // rejectUnknownArgs) has already restricted the flag to this command and validated its
     // value — shape and the 90-day cap both, via durationFlagSpec("pause --for")'s validate —
@@ -169,7 +195,7 @@ export async function cmdPause(root, args = [], now = Date.now()) {
     // `--reason <text>` (the operator pause's why): the gate in cli.ts has already restricted
     // the flag to this command, and its trailing-no-value slip to the spec's wording, so here
     // a valueless or empty reason fails with that same line beside the writer it feeds. The
-    // reason folds to one line (normalizePauseReason, the same home pauseFleet writes through)
+    // reason folds to one line (normalizePauseReason, the same home pauseTeam writes through)
     // so the confirmation line, the marker, and every single-line surface carry the same text
     // — a raw newline in the flag's value would otherwise break the header's one-line badge.
     const reasonRaw = flagValue(args, "--reason");
@@ -186,15 +212,15 @@ 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 = namedRole(root, args);
+    const role = pauseTargetRole(root, args);
     if (role) {
         // 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
         // when no marker carries it. Before any marker is written, beside the other fail-fasts.
         if (reason !== undefined)
-            fail("pause --reason states why the whole fleet is paused — a per-role pause carries no reason (drop --role, or run bare `tumwater pause --reason <text>`)");
-        // Per-role branch: pauseRole in src/fleet/fleet-state.ts is the single writer of the role
+            fail("pause --reason states why the whole team is paused — a per-role pause carries no reason (drop --role, or run bare `tumwater pause --reason <text>`)");
+        // Per-role branch: pauseRole in src/team/team-state.ts is the single writer of the role
         // marker (the TUI's Ctrl+P and the dashboard's /api/pause-role toggle call it too), so
         // 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,
@@ -202,20 +228,20 @@ export async function cmdPause(root, args = [], now = Date.now()) {
         say(rolePauseMessage(root, role, pauseRole(root, role, untilMs), timed, now));
         return;
     }
-    // pauseFleet in src/fleet/fleet-state.ts is the single writer of the pause marker — the GUI's
+    // pauseTeam in src/team/team-state.ts is the single writer of the pause marker — the GUI's
     // /api/pause toggle calls it too, so the CLI and the dashboard cannot drift on format
     // or idempotence; a false return means the marker was already there (a `--for` never
     // no-ops: it overwrites the standing deadline instead).
     // The reason rides the fresh pause write (or a `--for` overwrite): the same last-write-wins
     // rule as the deadline, so an "already paused" no-op keeps the standing note as-is.
-    if (!pauseFleet(root, untilMs, reason)) {
+    if (!pauseTeam(root, untilMs, reason)) {
         say("already paused");
         return;
     }
     const { when, tail } = markerApplyNote(root);
     const { forPhrase, note } = timedPauseBits(timed, now);
     const why = pauseReasonSuffix(reason);
-    say(`fleet paused${forPhrase}${why} — role loops stop starting new ticks${when} (in-flight ticks finish; the director keeps running your prompts)${note}${tail}`);
+    say(`team paused${forPhrase}${why} — roles start no new runs${when} (current runs finish; the director keeps running your messages)${note}${tail}`);
 }
 /** Deliver the stop signal to the recorded orchestrator pid: "signalled" when SIGTERM was
  * delivered, "gone" when the process died between the caller's liveness check and the
@@ -245,59 +271,119 @@ export function signalOrchestrator(pid) {
  * that `orchestratorAlive` already accepts everywhere (status, abort, pause) applies here
  * too: the info file is refreshed by the live orchestrator, so the window is small, and the
  * signal is the same one a human `kill <pid>` would send. */
-export async function cmdStop(root) {
+export async function cmdStop(root, args = []) {
+    const inRaw = flagValue(args, "--in");
+    if (args.includes("--cancel")) {
+        if (inRaw !== null)
+            fail("stop --cancel and --in cannot be combined");
+        say(cancelScheduledStopMessage(root));
+        return;
+    }
+    if (inRaw !== null) {
+        // The gate (STOP_IN_FLAG's validate) checked shape and cap; re-parse beside the writer.
+        const ms = parseDurationFlag("stop --in", inRaw);
+        failOverDurationCap("stop --in", ms, PAUSE_FOR_MAX_MS);
+        const result = requestScheduledStop(root, ms);
+        if (!result.ok)
+            fail(result.error);
+        say(result.message);
+        return;
+    }
     // Deliberately the same liveness gate and wording `requestAbort` uses: an unreadable info
     // file (torn write) and a dead recorded pid both mean nothing is running to stop.
     const info = readOrchestratorInfo(root);
     if (!info || !pidAlive(info.pid)) {
         fail(NO_HARNESS_ERROR);
     }
-    // A pid that dies between the liveness check and the signal (ESRCH) means the fleet is
+    // A pid that dies between the liveness check and the signal (ESRCH) means the team is
     // already stopped — say so and exit clean rather than surfacing Node's raw kill error;
     // anything else (EPERM on a recycled pid, …) comes back as signalOrchestrator's message.
     if (signalOrchestrator(info.pid) === "signalled")
-        say("stop requested — the fleet drains its in-flight ticks and exits (the same path as Ctrl+C)");
+        say("stop requested — the team finishes current work, then stops (the same path as Ctrl+C)");
     else
-        say("the orchestrator exited before the stop signal landed — nothing is running");
+        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 fleet pause by removing its marker. Idempotent
+ * 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 = namedRole(root, args);
+    const role = pauseTargetRole(root, args);
     if (role) {
-        // resumeRole (src/fleet/fleet-state.ts) is the single remover of the per-role marker; a false
+        // 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)));
         return;
     }
-    // resumeFleet (src/fleet/fleet-state.ts) is the single remover, shared with the GUI toggle;
+    // resumeTeam (src/team/team-state.ts) is the single remover, shared with the GUI toggle;
     // a false return means there was no marker to lift.
-    if (!resumeFleet(root)) {
+    if (!resumeTeam(root)) {
         say("not paused");
         return;
     }
     const { when, tail } = markerApplyNote(root);
-    // The per-role pause outlives a fleet resume (the markers are independent), so the resumed
-    // fleet's confirmation must name the roles still individually paused instead of claiming
+    // 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.
     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)`
         : "";
-    say(`${fleetResumePhrase()}${when}${roleNote}${tail}`);
+    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). */
+async function retireTargetRole(root, args) {
+    const role = flagValue(args, "--role");
+    if (role === null)
+        return requiredNamedRole(root, args, "retire");
+    if (!role)
+        fail(ROLE_VALUE_ERROR);
+    if (allRoleIds().includes(role))
+        return role;
+    let ids;
+    try {
+        ids = knownRoleIds(loadConfig(root));
+    }
+    catch (err) {
+        fail(errorMessage(err));
+    }
+    if (ids.includes(role) || (await hasRetirableLeftovers(root, role)))
+        return role;
+    fail(unknownRoleMessage(role, ids));
 }
 /** `tumwater retire --role <id> [--force] [--json]`: remove a disabled loop's leftover worktree,
- * branch, landing 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. */
+ * 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) {
-    // As in cmdAbort: 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, "retire");
-    const result = await retireRole(root, role, { force: args.includes("--force") });
+    // The config exists only to validate the id against built-ins plus user-defined loops, 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");
+    if (args.includes("--dry-run")) {
+        const preview = await previewRetire(root, role);
+        if (args.includes("--json")) {
+            sayJson({
+                role,
+                dryRun: true,
+                wouldRemove: preview.wouldRemove,
+                skipped: preview.skipped,
+                objections: preview.objections,
+            });
+            return;
+        }
+        for (const name of preview.wouldRemove)
+            say(`would remove ${artifactPhrase(name, role)}`);
+        for (const name of preview.skipped)
+            say(`nothing to remove: ${artifactPhrase(name, role)}`);
+        for (const reason of preview.objections)
+            say(force ? `--force overrides: ${reason}` : `would refuse: ${reason}`);
+        say("dry run — nothing removed");
+        return;
+    }
+    const result = await retireRole(root, role, { force });
     if (args.includes("--json")) {
         sayJson({ role, removed: result.removed, skipped: result.skipped });
         return;
@@ -309,3 +395,24 @@ 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. */
+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)");
+    // 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]);
+    if (!result.ok)
+        fail(result.error);
+    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");
+}