@h-rig/cli-surface-plugin 0.0.6-alpha.146

package/dist/src/commands/run.js

@@ -0,0 +1,645 @@
+// @bun
+var __require = import.meta.require;
+
+// packages/cli-surface-plugin/src/commands/run.ts
+import { TERMINAL_RUN_STATUSES } from "@rig/contracts";
+import {
+  activeRunByTaskId,
+  assertNoActiveRunForTask,
+  deliverRemoteRunControl,
+  deliverRunControl,
+  getRun,
+  isReadyTask,
+  listRuns,
+  listTasks,
+  normalizeTaskId,
+  readSessionRunEntries,
+  readTaskTitle,
+  removeRegistryRoom,
+  resolveJoinTarget,
+  resolveStartTask,
+  selectNextReadyTask
+} from "@rig/client";
+
+// packages/cli-surface-plugin/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
+function takeFlag(args, flag) {
+  const rest = [];
+  let value = false;
+  for (const arg of args) {
+    if (arg === flag) {
+      value = true;
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { value, rest };
+}
+function takeOption(args, option) {
+  const rest = [];
+  let value;
+  for (let index = 0;index < args.length; index += 1) {
+    const current = args[index];
+    if (current === option) {
+      const next = args[index + 1];
+      if (!next || next.startsWith("-")) {
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
+      }
+      value = next;
+      index += 1;
+      continue;
+    }
+    if (current !== undefined) {
+      rest.push(current);
+    }
+  }
+  return { value, rest };
+}
+function requireNoExtraArgs(args, usage) {
+  if (args.length > 0) {
+    throw new CliError(`Unexpected arguments: ${args.join(" ")}
+Usage: ${usage}`);
+  }
+}
+
+// packages/cli-surface-plugin/src/kernel-dispatch.ts
+async function dispatchThroughKernel(input, options) {
+  const { getProcessKernel } = await import("@rig/kernel/boot-default");
+  const kernel = getProcessKernel();
+  if (!kernel) {
+    throw new Error("Kernel not booted: cannot dispatch a run through the transport capability.");
+  }
+  const runId = await kernel.transport.dispatch(input, options);
+  return { runId };
+}
+
+// packages/cli-surface-plugin/src/commands/_cli-format.ts
+import pc from "picocolors";
+import { runStatusColorRole, runStatusText, statusColorRole } from "@rig/client";
+var dim = pc.dim;
+var faintBar = pc.dim("\u2502");
+var accent = pc.cyan;
+function truncate(value, width) {
+  return value.length <= width ? value : `${value.slice(0, Math.max(0, width - 1))}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function colorForRole(role) {
+  switch (role) {
+    case "success":
+      return pc.green;
+    case "action-yellow":
+      return pc.yellow;
+    case "active-cyan":
+      return pc.cyan;
+    case "failure":
+      return pc.red;
+    case "muted":
+    case "neutral":
+      return pc.dim;
+  }
+}
+function compactDate(value) {
+  const parsed = Date.parse(value);
+  if (!Number.isFinite(parsed))
+    return value;
+  return new Date(parsed).toISOString().replace("T", " ").replace(/\.\d{3}Z$/, "Z");
+}
+function firstString(record, keys, fallback = "") {
+  for (const key of keys) {
+    const value = record[key];
+    if (typeof value === "string" && value.trim())
+      return value;
+  }
+  return fallback;
+}
+function runIdOf(run) {
+  return firstString(run, ["runId", "id"], "(unknown-run)");
+}
+function taskIdOf(run) {
+  return firstString(run, ["taskId", "task", "task_id"]);
+}
+function runTitleOf(run) {
+  return firstString(run, ["title", "summary", "name"], taskIdOf(run) || "(untitled)");
+}
+function runLikeStatusText(run) {
+  return runStatusText(run);
+}
+function runLikeStatusColor(run) {
+  return colorForRole(runStatusColorRole(run));
+}
+function printFormattedOutput(message) {
+  console.log(message);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(accent("\u25C6"))} ${pc.bold(title)}${subtitle ? dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${faintBar} ${dim(key.padEnd(12))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatLegacyAutomationSurface() {
+  return [];
+}
+function formatRunList(runs, options = {}) {
+  if (runs.length === 0) {
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? dim("No runs recorded on the selected server.") : dim("No runs recorded in local state."),
+      "",
+      ...formatLegacyAutomationSurface()
+    ].join(`
+`);
+  }
+  const body = runs.map((run) => {
+    const row = run;
+    const runId = runIdOf(row);
+    const status = runLikeStatusText(run);
+    const runtime = firstString(row, ["runtime", "runtimeAdapter"], "");
+    return [
+      pc.bold(runId),
+      runLikeStatusColor(run)(pad(truncate(status, 12), 12)),
+      `${runTitleOf(row)}${runtime ? dim(`  ${runtime}`) : ""}`
+    ].join("  ");
+  });
+  return [formatSection("Runs", options.source === "server" ? "selected server" : "local state"), ...body, "", ...formatLegacyAutomationSurface()].join(`
+`);
+}
+function formatSubmittedRun(input) {
+  return formatSuccessCard("Run submitted", [
+    ["run", input.runId],
+    ["task", input.taskId ?? undefined],
+    ["title", input.title ?? undefined],
+    ["queue", input.queuePosition ?? undefined]
+  ]);
+}
+function formatRunCard(run, options = {}) {
+  const record = run;
+  const lines = [formatSection(options.title ?? "Run")];
+  for (const [label, value] of [
+    ["run", runIdOf(record)],
+    ["task", taskIdOf(record)],
+    ["title", runTitleOf(record)],
+    ["status", runLikeStatusText(run)],
+    ["runtime", firstString(record, ["runtime", "runtimeAdapter"], "")],
+    ["created", firstString(record, ["createdAt"], "")],
+    ["updated", firstString(record, ["updatedAt"], "")]
+  ]) {
+    if (value)
+      lines.push(`${faintBar} ${dim(label.padEnd(12))} ${label === "status" ? runLikeStatusColor(run)(value) : label === "created" || label === "updated" ? compactDate(value) : value}`);
+  }
+  const errorSummary = firstString(record, ["errorSummary"]);
+  if (errorSummary)
+    lines.push(`${faintBar} Error: ${errorSummary}`);
+  return lines.join(`
+`);
+}
+function formatRunStatus(summary, options = {}) {
+  const activeRuns = summary.activeRuns ?? [];
+  const recentRuns = summary.recentRuns ?? [];
+  const lines = [formatSection("Run status", options.source === "server" ? "selected server" : "local state")];
+  lines.push(`Active runs (${activeRuns.length})`);
+  if (activeRuns.length === 0)
+    lines.push(dim("No active runs."));
+  else
+    for (const run of activeRuns)
+      lines.push(formatRunSummaryLine(run));
+  lines.push("", `Recent runs (${recentRuns.length})`);
+  if (recentRuns.length === 0)
+    lines.push(dim("No recent terminal runs."));
+  else
+    for (const run of recentRuns.slice(0, 10))
+      lines.push(formatRunSummaryLine(run));
+  lines.push("", ...formatLegacyAutomationSurface());
+  return lines.join(`
+`);
+}
+function formatRunSummaryLine(run) {
+  const record = run;
+  const runId = runIdOf(record);
+  const taskId = taskIdOf(record);
+  const title = runTitleOf(record);
+  const status = runLikeStatusText(run);
+  const runtime = firstString(record, ["runtime", "runtimeAdapter"], "");
+  const descriptor = [taskId, title].filter(Boolean).join(" \xB7 ");
+  return `${faintBar} ${pc.bold(runId)} ${runLikeStatusColor(run)(`\u25CF ${status}`)} ${descriptor}${runtime ? dim(`  ${runtime}`) : ""}`;
+}
+
+// packages/cli-surface-plugin/src/commands/run.ts
+var TERMINAL = new Set(TERMINAL_RUN_STATUSES);
+var RUN_COMMANDS = new Set([
+  "list",
+  "status",
+  "start",
+  "start-parallel",
+  "start-serial",
+  "show",
+  "timeline",
+  "replay",
+  "attach",
+  "steer",
+  "stop",
+  "pause",
+  "resume",
+  "restart",
+  "delete",
+  "cleanup"
+]);
+function normalizeRunArgs(args) {
+  if (args.length === 0)
+    return ["status"];
+  const first = args[0];
+  if (first && RUN_COMMANDS.has(first))
+    return args;
+  if (first?.startsWith("-") || first?.startsWith("#") || /[\d-]/.test(first ?? ""))
+    return ["start", ...args];
+  return args;
+}
+function parsePromptOverride(prompt, initialPrompt) {
+  const promptText = prompt?.trim();
+  const initialPromptText = initialPrompt?.trim();
+  if (promptText && initialPromptText) {
+    throw new CliError("Pass only one of --prompt or --initial-prompt.", 2, {
+      hint: "Use `--prompt <text>`; `--initial-prompt` is accepted as a compatibility alias."
+    });
+  }
+  return promptText || initialPromptText || null;
+}
+function parsePositiveLimit(value) {
+  if (value === undefined)
+    return;
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0 || String(parsed) !== value.trim()) {
+    throw new CliError("--limit must be a positive integer.", 1, { hint: "Re-run with a positive number, e.g. `rig run start-parallel --limit 4`." });
+  }
+  return parsed;
+}
+function printText(context, message) {
+  if (context.outputMode === "text")
+    printFormattedOutput(message);
+}
+function toRunLike(run) {
+  return {
+    runId: run.runId,
+    taskId: run.taskId,
+    title: run.title,
+    status: run.status,
+    source: run.source,
+    live: run.live,
+    stale: run.stale,
+    startedAt: run.startedAt,
+    updatedAt: run.updatedAt,
+    completedAt: run.completedAt,
+    joinLink: run.joinLink,
+    prUrl: run.prUrl,
+    pendingApprovals: run.pendingApprovals,
+    pendingInputs: run.pendingInputs,
+    steeringCount: run.steeringCount,
+    stallCount: run.stallCount
+  };
+}
+function positional(args) {
+  const idx = args.findIndex((arg) => !arg.startsWith("-"));
+  if (idx < 0)
+    return { runId: undefined, rest: args };
+  return { runId: args[idx], rest: [...args.slice(0, idx), ...args.slice(idx + 1)] };
+}
+function requireRunId(value, usage) {
+  if (!value || !value.trim()) {
+    throw new CliError(`${usage} requires a run id.`, 2, { hint: "Run `rig run list` to find run ids." });
+  }
+  return value.trim();
+}
+async function executeRun(context, args, deps = {}) {
+  const listRunRecords = deps.listRuns ?? ((root) => listRuns(root));
+  const getRunRecord = deps.getRun ?? ((root, id) => getRun(root, id));
+  const joinTarget = deps.resolveJoin ?? ((root, id) => resolveJoinTarget(root, id));
+  const dispatch = deps.dispatch ?? ((input) => dispatchThroughKernel(input));
+  const listTaskRecords = deps.listTasks ?? ((root) => listTasks(root));
+  const [command = "status", ...rest] = normalizeRunArgs(args);
+  const text = context.outputMode === "text";
+  switch (command) {
+    case "list": {
+      requireNoExtraArgs(rest, "rig run list");
+      const runs = await listRunRecords(context.projectRoot);
+      if (text)
+        printFormattedOutput(formatRunList(runs.map(toRunLike)));
+      return { ok: true, group: "run", command, details: { runs: runs.map(toRunLike), source: "local" } };
+    }
+    case "status": {
+      requireNoExtraArgs(rest, "rig run status");
+      const runs = await listRunRecords(context.projectRoot);
+      const activeRuns = runs.filter((run) => !TERMINAL.has(run.status)).map(toRunLike);
+      const recentRuns = runs.filter((run) => TERMINAL.has(run.status)).map(toRunLike);
+      if (text)
+        printFormattedOutput(formatRunStatus({ activeRuns, recentRuns, runs: [...activeRuns, ...recentRuns] }));
+      return { ok: true, group: "run", command, details: { activeRuns, recentRuns } };
+    }
+    case "start": {
+      let pending = rest;
+      const nextResult = takeFlag(pending, "--next");
+      pending = nextResult.rest;
+      const forceResult = takeFlag(pending, "--force");
+      pending = forceResult.rest;
+      const taskResult = takeOption(pending, "--task");
+      pending = taskResult.rest;
+      const titleResult = takeOption(pending, "--title");
+      pending = titleResult.rest;
+      const modelResult = takeOption(pending, "--model");
+      pending = modelResult.rest;
+      const promptResult = takeOption(pending, "--prompt");
+      pending = promptResult.rest;
+      const initialPromptResult = takeOption(pending, "--initial-prompt");
+      pending = initialPromptResult.rest;
+      const taskRef = pending[0]?.startsWith("-") ? undefined : pending[0];
+      requireNoExtraArgs(taskRef ? pending.slice(1) : pending, "rig run [start] [#<issue>|<task-id>|--next|--task <id>] [--title <t>] [--model <m>] [--prompt <p>|--initial-prompt <p>] [--force]");
+      const { taskId, task } = await resolveStartTask({ projectRoot: context.projectRoot, taskId: taskResult.value ?? taskRef, next: nextResult.value, listTasks: listTaskRecords });
+      const title = titleResult.value ?? readTaskTitle(task);
+      const model = modelResult.value?.trim() || null;
+      const prompt = parsePromptOverride(promptResult.value, initialPromptResult.value);
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { taskId, title: title ?? null, model, prompt, dryRun: true } };
+      if (!forceResult.value)
+        await assertNoActiveRunForTask(listRunRecords, context.projectRoot, taskId);
+      const submitted = await dispatch({ projectRoot: context.projectRoot, taskId, title, force: forceResult.value, model, prompt });
+      printText(context, `${formatSubmittedRun({ runId: submitted.runId, taskId, title })}
+
+Next: rig run attach ${submitted.runId}`);
+      return { ok: true, group: "run", command, details: { runId: submitted.runId, taskId, title: title ?? null, model, prompt, detached: true } };
+    }
+    case "start-parallel": {
+      const forceResult = takeFlag(rest, "--force");
+      const limitResult = takeOption(forceResult.rest, "--limit");
+      requireNoExtraArgs(limitResult.rest, "rig run start-parallel [--limit <n>] [--force]");
+      const limit = parsePositiveLimit(limitResult.value);
+      let readyTasks = (await listTaskRecords(context.projectRoot)).filter(isReadyTask);
+      let skipped = 0;
+      if (!forceResult.value) {
+        const active = await activeRunByTaskId(listRunRecords, context.projectRoot);
+        const before = readyTasks.length;
+        readyTasks = readyTasks.filter((task) => {
+          const id = normalizeTaskId(task.id);
+          return !(id !== undefined && active.has(id));
+        });
+        skipped = before - readyTasks.length;
+      }
+      const selectedTasks = limit === undefined ? readyTasks : readyTasks.slice(0, limit);
+      if (selectedTasks.length === 0) {
+        throw new CliError(skipped > 0 ? `No ready tasks without an active run (${skipped} already running; use --force to re-dispatch).` : "No ready tasks found.", 1, { hint: "Run `rig task list` to inspect available tasks." });
+      }
+      if (context.dryRun) {
+        return { ok: true, group: "run", command, details: { count: selectedTasks.length, taskIds: selectedTasks.map((task) => task.id), limit: limit ?? null, skipped, dryRun: true } };
+      }
+      const submittedRuns = [];
+      for (const task of selectedTasks) {
+        const taskId = normalizeTaskId(task.id);
+        if (!taskId)
+          continue;
+        const title = readTaskTitle(task);
+        const submitted = await dispatch({ projectRoot: context.projectRoot, taskId, title });
+        submittedRuns.push({ runId: submitted.runId, taskId, title: title ?? null });
+      }
+      if (submittedRuns.length === 0)
+        throw new CliError("No ready tasks with task ids found.", 1, { hint: "Run `rig task list` to inspect available tasks." });
+      printText(context, [
+        `Dispatched ${submittedRuns.length} ready task${submittedRuns.length === 1 ? "" : "s"} as detached runs:`,
+        ...submittedRuns.map((run) => `- ${run.taskId} -> ${run.runId}`),
+        ...skipped > 0 ? [`(skipped ${skipped} task${skipped === 1 ? "" : "s"} already running; --force to re-dispatch)`] : [],
+        "",
+        `Next: rig run attach <runId> (for example: rig run attach ${submittedRuns[0].runId})`
+      ].join(`
+`));
+      return { ok: true, group: "run", command, details: { count: submittedRuns.length, runs: submittedRuns, limit: limit ?? null, skipped, detached: true } };
+    }
+    case "start-serial": {
+      const force = takeFlag(rest, "--force");
+      requireNoExtraArgs(force.rest, "rig run start-serial [--force]");
+      const task = selectNextReadyTask(await listTaskRecords(context.projectRoot));
+      const taskId = normalizeTaskId(task?.id);
+      if (!task || !taskId)
+        throw new CliError("No ready task found.", 1, { hint: "Run `rig task list` to inspect available tasks." });
+      const title = readTaskTitle(task);
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { taskId, title: title ?? null, dryRun: true, serialStepOnly: true } };
+      if (!force.value)
+        await assertNoActiveRunForTask(listRunRecords, context.projectRoot, taskId);
+      const submitted = await dispatch({ projectRoot: context.projectRoot, taskId, title });
+      printText(context, `${formatSubmittedRun({ runId: submitted.runId, taskId, title })}
+
+Note: start-serial dispatches only the next ready task; run it again after that run finishes to continue the serial queue.
+
+Next: rig run attach ${submitted.runId}`);
+      return { ok: true, group: "run", command, details: { runId: submitted.runId, taskId, title: title ?? null, detached: true, serialStepOnly: true } };
+    }
+    case "show": {
+      const raw = takeFlag(rest, "--raw");
+      const run = takeOption(raw.rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, "rig run show <id>|--run <id> [--raw]");
+      const runId = requireRunId(run.value ?? pos, "rig run show");
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      if (text)
+        printFormattedOutput(raw.value ? JSON.stringify(record, null, 2) : formatRunCard(toRunLike(record)));
+      return { ok: true, group: "run", command, details: { run: toRunLike(record), projection: record.projection } };
+    }
+    case "timeline":
+    case "replay": {
+      const withSession = takeFlag(rest, "--with-session");
+      const run = takeOption(withSession.rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, `rig run ${command} <id>|--run <id>`);
+      const runId = requireRunId(run.value ?? pos, `rig run ${command}`);
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      const entries = readSessionRunEntries(record.sessionPath).filter((entry) => typeof entry.customType === "string" && entry.customType.startsWith("rig.run."));
+      if (text) {
+        printFormattedOutput(formatRunCard(toRunLike(record)));
+        if (entries.length === 0) {
+          printFormattedOutput("(no run journal entries recorded for this run yet)");
+        } else {
+          for (const entry of entries) {
+            const data = entry.data;
+            const at = data && typeof data === "object" && "at" in data && typeof data.at === "string" ? data.at : "";
+            const kind = String(entry.customType).replace("rig.run.", "");
+            printFormattedOutput(`${at ? `${at} ` : ""}${kind} ${JSON.stringify(data)}`.trim());
+          }
+        }
+      }
+      return { ok: true, group: "run", command, details: { runId: record.runId, entryCount: entries.length, entries } };
+    }
+    case "attach": {
+      const message = takeOption(rest, "--message");
+      const run = takeOption(message.rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, "rig run attach <id>|--run <id>");
+      const runId = requireRunId(run.value ?? pos, "rig run attach");
+      if (message.value?.trim()) {
+        throw new CliError("`rig run attach` does not deliver messages; steer the run instead.", 2, { hint: `rig run steer ${runId} --message <text>` });
+      }
+      const target = await joinTarget(context.projectRoot, runId);
+      if (!target)
+        throw new CliError(`Run ${runId} is not currently joinable.`, 2, { hint: "It may be finished or offline. Run `rig run show <id>` for its recorded state." });
+      if (target.stale)
+        throw new CliError(`Run ${runId} is stale (no recent heartbeat); it may have exited.`, 2, { hint: "Run `rig run show <id>` for its last recorded state." });
+      if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        if (text) {
+          printFormattedOutput(`Run ${runId} live collab link:`);
+          printFormattedOutput(target.joinLink);
+          printFormattedOutput("Attach interactively with: rig join <link>");
+        }
+        return { ok: true, group: "run", command, details: { runId, joinLink: target.joinLink, attached: false } };
+      }
+      if (text) {
+        printFormattedOutput(`Run ${runId} live collab link:`);
+        printFormattedOutput(target.joinLink);
+        printFormattedOutput("Attach interactively with: rig join <link>");
+      }
+      return { ok: true, group: "run", command, details: { runId, joinLink: target.joinLink, attached: false } };
+    }
+    case "steer": {
+      const message = takeOption(rest, "--message");
+      const short = takeOption(message.rest, "-m");
+      const run = takeOption(short.rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, "rig run steer <id>|--run <id> --message <text>");
+      const runId = requireRunId(run.value ?? pos, "rig run steer");
+      const messageText = (message.value ?? short.value)?.trim();
+      if (!messageText)
+        throw new CliError("rig run steer requires --message <text>.", 2);
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      await deliverRunControl(context.projectRoot, record, { kind: "steer", message: messageText }, { deliverRemote: deps.deliverRemote ?? deliverRemoteRunControl });
+      if (text)
+        printFormattedOutput(`Steered run ${record.runId}.`);
+      return { ok: true, group: "run", command, details: { runId: record.runId, steered: true } };
+    }
+    case "stop": {
+      const run = takeOption(rest, "--run");
+      const reasonOpt = takeOption(run.rest, "--reason");
+      const { runId: pos, rest: extra } = positional(reasonOpt.rest);
+      requireNoExtraArgs(extra, "rig run stop <id>|--run <id> [--reason <text>]");
+      const runId = requireRunId(run.value ?? pos, "rig run stop");
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      await deliverRunControl(context.projectRoot, record, { kind: "stop", reason: reasonOpt.value ?? "operator requested stop" }, { deliverRemote: deps.deliverRemote ?? deliverRemoteRunControl });
+      if (text)
+        printFormattedOutput(`Requested stop for run ${record.runId}.`);
+      return { ok: true, group: "run", command, details: { runId: record.runId, stopRequested: true } };
+    }
+    case "pause": {
+      const run = takeOption(rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, "rig run pause <id>|--run <id>");
+      const runId = requireRunId(run.value ?? pos, "rig run pause");
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      if (!record.live || record.stale)
+        throw new CliError(`Run ${runId} is not live; only a running run can be paused.`, 2, { hint: `Re-dispatch it instead: rig run restart ${runId}` });
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { runId: record.runId, dryRun: true } };
+      await deliverRunControl(context.projectRoot, record, { kind: "pause" }, { deliverRemote: deps.deliverRemote ?? deliverRemoteRunControl });
+      if (text)
+        printFormattedOutput(`Requested pause for run ${record.runId}. Resume it with \`rig run resume ${record.runId}\`.`);
+      return { ok: true, group: "run", command, details: { runId: record.runId, pauseRequested: true } };
+    }
+    case "resume": {
+      const run = takeOption(rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, "rig run resume <id>|--run <id>");
+      const runId = requireRunId(run.value ?? pos, "rig run resume");
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      if (record.live && !record.stale) {
+        if (context.dryRun)
+          return { ok: true, group: "run", command, details: { runId: record.runId, dryRun: true } };
+        await deliverRunControl(context.projectRoot, record, { kind: "resume" }, { deliverRemote: deps.deliverRemote ?? deliverRemoteRunControl });
+        if (text)
+          printFormattedOutput(`Requested resume for run ${record.runId}.`);
+        return { ok: true, group: "run", command, details: { runId: record.runId, resumeRequested: true } };
+      }
+      if (!record.taskId)
+        throw new CliError(`Run ${runId} is not live and has no task id to re-dispatch.`, 2);
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { taskId: record.taskId, dryRun: true } };
+      const redispatched = await dispatch({ projectRoot: context.projectRoot, taskId: record.taskId, title: record.title });
+      if (text)
+        printFormattedOutput(`Run ${runId} was not live \u2014 re-dispatched ${record.taskId} as run ${redispatched.runId}.`);
+      return { ok: true, group: "run", command, details: { previousRunId: runId, runId: redispatched.runId, taskId: record.taskId } };
+    }
+    case "restart": {
+      const run = takeOption(rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, `rig run ${command} <id>|--run <id>`);
+      const runId = requireRunId(run.value ?? pos, `rig run ${command}`);
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (!record)
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see runs." });
+      if (!record.taskId)
+        throw new CliError(`Run ${runId} has no task id; it cannot be re-dispatched.`, 2);
+      if (record.live && !record.stale)
+        throw new CliError(`Run ${runId} is still live.`, 2, { hint: `Stop it first (rig run stop ${runId}) or attach: rig run attach ${runId}` });
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { taskId: record.taskId, dryRun: true } };
+      const dispatched = await dispatch({ projectRoot: context.projectRoot, taskId: record.taskId, title: record.title });
+      if (text)
+        printFormattedOutput(`Re-dispatched ${record.taskId} as run ${dispatched.runId} (detached runs start fresh).`);
+      return { ok: true, group: "run", command, details: { previousRunId: runId, runId: dispatched.runId, taskId: record.taskId } };
+    }
+    case "delete":
+    case "cleanup": {
+      const run = takeOption(rest, "--run");
+      const { runId: pos, rest: extra } = positional(run.rest);
+      requireNoExtraArgs(extra, `rig run ${command} [<id>|--run <id>]`);
+      const runIdArg = run.value ?? pos;
+      if (!runIdArg) {
+        const staleRuns = (await listRunRecords(context.projectRoot)).filter((r) => r.stale);
+        if (context.dryRun)
+          return { ok: true, group: "run", command, details: { staleCount: staleRuns.length, dryRun: true } };
+        let removed2 = 0;
+        for (const r of staleRuns)
+          if (await removeRegistryRoom(context.projectRoot, r.runId))
+            removed2 += 1;
+        if (text)
+          printFormattedOutput(staleRuns.length ? `Pruned ${removed2}/${staleRuns.length} stale run(s) from the live registry. (On-disk session journals are retained.)` : "No stale runs to prune.");
+        return { ok: true, group: "run", command, details: { staleCount: staleRuns.length, removed: removed2 } };
+      }
+      const runId = requireRunId(runIdArg, `rig run ${command}`);
+      const record = await getRunRecord(context.projectRoot, runId);
+      if (record && record.live && !record.stale)
+        throw new CliError(`Run ${runId} is still live; stop it before deleting.`, 2, { hint: `Attach to stop: rig run attach ${runId}` });
+      if (context.dryRun)
+        return { ok: true, group: "run", command, details: { runId, dryRun: true } };
+      const removed = await removeRegistryRoom(context.projectRoot, record?.runId ?? runId);
+      if (text)
+        printFormattedOutput(removed ? `Removed run ${runId} from the live registry.` : `Run ${runId} had no live registry entry to remove; its on-disk session journal is retained.`);
+      return { ok: true, group: "run", command, details: { runId, registryRemoved: removed } };
+    }
+    default:
+      throw new CliError(`Unknown run command: ${command}`, 1, { hint: "Run `rig run --help` to list run commands." });
+  }
+}
+export {
+  executeRun
+};

package/dist/src/commands/server.d.ts

@@ -0,0 +1,3 @@
+import type { CommandOutcome } from "@rig/runtime";
+import { type RunnerContext } from "../runner";
+export declare function executeServer(context: RunnerContext, args: string[]): Promise<CommandOutcome>;