@h-rig/cli 0.0.6-alpha.0

package/dist/src/commands/run.js

@@ -0,0 +1,753 @@
+// @bun
+// packages/cli/src/commands/run.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { createInterface as createInterface2 } from "readline/promises";
+
+// packages/cli/src/runner.ts
+import { EventBus } from "@rig/runtime/control-plane/runtime/events";
+import { CliError } from "@rig/runtime/control-plane/errors";
+import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
+import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
+import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
+import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
+import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+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}`);
+      }
+      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/src/commands/run.ts
+import {
+  listAuthorityRuns,
+  readAuthorityRun,
+  readJsonlFile,
+  resolveAuthorityRunDir
+} from "@rig/runtime/control-plane/authority-files";
+import {
+  cleanupRunState,
+  deleteRunState,
+  listOpenEpics,
+  resolveDefaultEpic,
+  runResume,
+  runStatus,
+  runStop,
+  startRun,
+  defaultStartRunOptions
+} from "@rig/runtime/control-plane/native/run-ops";
+import { loadRuntimeContextFromEnv as loadRuntimeContextFromEnv2 } from "@rig/runtime/control-plane/runtime/context";
+
+// packages/cli/src/commands/_parsers.ts
+function parsePositiveInt(value, option, fallback) {
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new CliError2(`Invalid ${option} value: ${value}`);
+  }
+  return parsed;
+}
+
+// packages/cli/src/commands/_server-client.ts
+import { spawnSync } from "child_process";
+import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+
+// packages/cli/src/commands/_connection-state.ts
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, resolve } from "path";
+function resolveGlobalConnectionsPath(env = process.env) {
+  const explicit = env.RIG_CONNECTIONS_FILE?.trim();
+  if (explicit)
+    return resolve(explicit);
+  const stateDir = env.RIG_GLOBAL_STATE_DIR?.trim();
+  if (stateDir)
+    return resolve(stateDir, "connections.json");
+  return resolve(homedir(), ".rig", "connections.json");
+}
+function resolveRepoConnectionPath(projectRoot) {
+  return resolve(projectRoot, ".rig", "state", "connection.json");
+}
+function readJsonFile(path) {
+  if (!existsSync(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+  }
+}
+function normalizeConnection(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return null;
+  const record = value;
+  if (record.kind === "local")
+    return { kind: "local", mode: "auto" };
+  if (record.kind === "remote" && typeof record.baseUrl === "string" && record.baseUrl.trim()) {
+    const baseUrl = record.baseUrl.trim().replace(/\/+$/, "");
+    return { kind: "remote", baseUrl };
+  }
+  return null;
+}
+function readGlobalConnections(options = {}) {
+  const path = resolveGlobalConnectionsPath(options.env ?? process.env);
+  const payload = readJsonFile(path);
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return { connections: {} };
+  }
+  const rawConnections = payload.connections;
+  const connections = {};
+  if (rawConnections && typeof rawConnections === "object" && !Array.isArray(rawConnections)) {
+    for (const [alias, raw] of Object.entries(rawConnections)) {
+      const connection = normalizeConnection(raw);
+      if (connection)
+        connections[alias] = connection;
+    }
+  }
+  return { connections };
+}
+function readRepoConnection(projectRoot) {
+  const payload = readJsonFile(resolveRepoConnectionPath(projectRoot));
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const selected = typeof record.selected === "string" ? record.selected.trim() : "";
+  if (!selected)
+    return null;
+  return {
+    selected,
+    project: typeof record.project === "string" ? record.project : undefined,
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined
+  };
+}
+function resolveSelectedConnection(projectRoot, options = {}) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return null;
+  if (repo.selected === "local")
+    return { alias: "local", connection: { kind: "local", mode: "auto" } };
+  const global = readGlobalConnections(options);
+  const connection = global.connections[repo.selected];
+  if (!connection) {
+    throw new CliError2(`Selected Rig connection "${repo.selected}" was not found. Run \`rig connect list\` or \`rig connect use local\`.`, 1);
+  }
+  return { alias: repo.selected, connection };
+}
+
+// packages/cli/src/commands/_server-client.ts
+var cachedGitHubBearerToken;
+function cleanToken(value) {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : null;
+}
+function readGitHubBearerTokenForRemote() {
+  if (cachedGitHubBearerToken !== undefined)
+    return cachedGitHubBearerToken;
+  const envToken = cleanToken(process.env.RIG_GITHUB_TOKEN) ?? cleanToken(process.env.GITHUB_TOKEN) ?? cleanToken(process.env.GH_TOKEN);
+  if (envToken) {
+    cachedGitHubBearerToken = envToken;
+    return cachedGitHubBearerToken;
+  }
+  const result = spawnSync("gh", ["auth", "token"], {
+    encoding: "utf8",
+    timeout: 5000,
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  cachedGitHubBearerToken = result.status === 0 ? cleanToken(result.stdout) : null;
+  return cachedGitHubBearerToken;
+}
+async function ensureServerForCli(projectRoot) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected?.connection.kind === "remote") {
+      return {
+        baseUrl: selected.connection.baseUrl,
+        authToken: readGitHubBearerTokenForRemote(),
+        connectionKind: "remote"
+      };
+    }
+    const connection = await ensureLocalRigServerConnection(projectRoot);
+    return {
+      baseUrl: connection.baseUrl,
+      authToken: connection.authToken,
+      connectionKind: "local"
+    };
+  } catch (error) {
+    if (error instanceof Error) {
+      throw new CliError2(error.message, 1);
+    }
+    throw error;
+  }
+}
+function mergeHeaders(headers, authToken) {
+  const merged = new Headers(headers);
+  if (authToken) {
+    merged.set("authorization", `Bearer ${authToken}`);
+  }
+  return merged;
+}
+function diagnosticMessage(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const record = payload;
+  const diagnostics = Array.isArray(record.diagnostics) ? record.diagnostics : [];
+  const messages = diagnostics.flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const diagnostic = entry;
+    const kind = typeof diagnostic.kind === "string" ? diagnostic.kind : "task-source";
+    const message = typeof diagnostic.message === "string" ? diagnostic.message : null;
+    return message ? [`${kind}: ${message}`] : [];
+  });
+  return messages.length > 0 ? messages.join("; ") : null;
+}
+async function requestServerJson(context, pathname, init = {}) {
+  const server = await ensureServerForCli(context.projectRoot);
+  const response = await fetch(`${server.baseUrl}${pathname}`, {
+    ...init,
+    headers: mergeHeaders(init.headers, server.authToken)
+  });
+  const text = await response.text();
+  const payload = text.trim().length > 0 ? (() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })() : null;
+  if (!response.ok) {
+    const diagnostics = diagnosticMessage(payload);
+    const detail = diagnostics ?? (text || response.statusText);
+    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+  }
+  return payload;
+}
+async function getRunDetailsViaServer(context, runId) {
+  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}`);
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+}
+async function getRunLogsViaServer(context, runId, options = {}) {
+  const url = new URL(`http://rig.local/api/runs/${encodeURIComponent(runId)}/logs`);
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  if (options.cursor)
+    url.searchParams.set("cursor", options.cursor);
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { entries: [] };
+}
+async function stopRunViaServer(context, runId) {
+  const payload = await requestServerJson(context, "/api/runs/stop", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ runId })
+  });
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true, runId };
+}
+async function steerRunViaServer(context, runId, message) {
+  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/steer`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ message })
+  });
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
+}
+
+// packages/cli/src/commands/_operator-view.ts
+import { createInterface } from "readline";
+var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
+var CANONICAL_STAGES = [
+  "Connect",
+  "GitHub/task sync",
+  "Prepare workspace",
+  "Launch Pi",
+  "Plan",
+  "Implement",
+  "Validate",
+  "Commit",
+  "Open PR",
+  "Review/CI",
+  "Merge",
+  "Complete"
+];
+function renderOperatorSnapshot(snapshot) {
+  const run = snapshot.run.run && typeof snapshot.run.run === "object" ? snapshot.run.run : snapshot.run;
+  const runId = String(run.runId ?? run.id ?? "run");
+  const status = String(run.status ?? "unknown");
+  const logs = snapshot.logs ?? [];
+  const stageLines = CANONICAL_STAGES.flatMap((stage) => {
+    const match = logs.find((log) => String(log.title ?? "").toLowerCase() === stage.toLowerCase() || String(log.stage ?? "").toLowerCase() === stage.toLowerCase());
+    return match ? [`${stage}: ${String(match.status ?? status)}`] : [];
+  });
+  return [`Rig run ${runId}: ${status}`, ...stageLines].join(`
+`);
+}
+function runStatusFromPayload(payload) {
+  const run = payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
+  return String(run.status ?? "unknown").toLowerCase();
+}
+async function applyOperatorCommand(context, input, deps = {}) {
+  const line = input.line.trim();
+  if (!line)
+    return { action: "ignored" };
+  if (line === "/detach" || line === "/quit" || line === "/q") {
+    return { action: "detach", message: "Detached from run." };
+  }
+  if (line === "/stop") {
+    await (deps.stop ?? stopRunViaServer)(context, input.runId);
+    return { action: "stopped", message: "Stop requested." };
+  }
+  const userMessage = line.startsWith("/user ") ? line.slice("/user ".length).trim() : line;
+  if (!userMessage)
+    return { action: "ignored" };
+  await (deps.steer ?? steerRunViaServer)(context, input.runId, userMessage);
+  return { action: "continue", message: "Steering message queued." };
+}
+async function readOperatorSnapshot(context, runId) {
+  const run = await getRunDetailsViaServer(context, runId);
+  const logsPage = await getRunLogsViaServer(context, runId, { limit: 100 });
+  const entries = Array.isArray(logsPage.entries) ? logsPage.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  return { run, logs: entries, rendered: renderOperatorSnapshot({ run, logs: entries }) };
+}
+async function attachRunOperatorView(context, input) {
+  let steered = false;
+  if (input.message?.trim()) {
+    await steerRunViaServer(context, input.runId, input.message.trim());
+    steered = true;
+  }
+  let snapshot = await readOperatorSnapshot(context, input.runId);
+  if (context.outputMode === "text") {
+    console.log(snapshot.rendered);
+    if (steered)
+      console.log("Steering message queued.");
+  }
+  let detached = false;
+  let rl = null;
+  if (input.follow && !input.once && context.outputMode === "text") {
+    if (input.interactive !== false && process.stdin.isTTY) {
+      console.log("Controls: /user <message>, /stop, /detach");
+      rl = createInterface({ input: process.stdin, output: process.stdout, terminal: false });
+      rl.on("line", (line) => {
+        applyOperatorCommand(context, { runId: input.runId, line }).then((result) => {
+          if (result.message)
+            console.log(result.message);
+          if (result.action === "detach" || result.action === "stopped") {
+            detached = true;
+            rl?.close();
+          }
+        }).catch((error) => console.log(`Operator command failed: ${error instanceof Error ? error.message : String(error)}`));
+      });
+    }
+    let lastRendered = snapshot.rendered;
+    const pollMs = Math.max(250, Math.trunc(input.pollMs ?? 2000));
+    while (!detached && !TERMINAL_RUN_STATUSES.has(runStatusFromPayload(snapshot.run))) {
+      await Bun.sleep(pollMs);
+      snapshot = await readOperatorSnapshot(context, input.runId);
+      if (snapshot.rendered !== lastRendered) {
+        console.log(snapshot.rendered);
+        lastRendered = snapshot.rendered;
+      }
+    }
+    rl?.close();
+  }
+  return { ...snapshot, steered, detached };
+}
+
+// packages/cli/src/commands/run.ts
+function shouldPromptForEpicSelection(context, command, promptEpic, noEpicPrompt) {
+  if (noEpicPrompt) {
+    return false;
+  }
+  if (promptEpic) {
+    return true;
+  }
+  if (command !== "start-serial") {
+    return false;
+  }
+  return context.outputMode === "text" && process.stdin.isTTY && process.stdout.isTTY;
+}
+async function promptForEpicSelection(projectRoot, command) {
+  const epics = listOpenEpics(projectRoot);
+  const defaultEpic = await resolveDefaultEpic(projectRoot);
+  const options = epics.map((epic) => epic.id);
+  if (defaultEpic && !options.includes(defaultEpic)) {
+    options.unshift(defaultEpic);
+  }
+  if (options.length === 0) {
+    throw new CliError2("No open epic found. Pass --epic <id>.");
+  }
+  console.log(`Select epic for run ${command}:`);
+  options.forEach((id, index) => {
+    const metadata = epics.find((epic) => epic.id === id);
+    const details = [
+      metadata?.priority !== undefined ? `priority:${metadata.priority}` : "",
+      metadata?.createdAt ? `created:${metadata.createdAt.slice(0, 10)}` : "",
+      id === defaultEpic ? "default" : ""
+    ].filter(Boolean).join(" ");
+    const suffix = details ? ` (${details})` : "";
+    console.log(`  ${index + 1}. ${id}${suffix}`);
+  });
+  const fallback = defaultEpic || options[0];
+  const rl = createInterface2({ input: process.stdin, output: process.stdout });
+  try {
+    while (true) {
+      const answer = (await rl.question(`Epic [1-${options.length}] or id (Enter for ${fallback}, q to cancel): `)).trim();
+      if (!answer) {
+        return fallback ?? options[0];
+      }
+      if (answer === "q" || answer === "quit") {
+        throw new CliError2("Run cancelled by user.");
+      }
+      if (/^\d+$/.test(answer)) {
+        const index = Number.parseInt(answer, 10) - 1;
+        if (index >= 0 && index < options.length) {
+          return options[index];
+        }
+      }
+      if (options.includes(answer)) {
+        return answer;
+      }
+      console.log("Invalid selection. Choose a listed number, exact epic id, or q to cancel.");
+    }
+  } finally {
+    rl.close();
+  }
+}
+async function executeRun(context, args) {
+  const [command = "status", ...rest] = args;
+  const runtimeContext = loadRuntimeContextFromEnv2() ?? undefined;
+  switch (command) {
+    case "list": {
+      requireNoExtraArgs(rest, "bun run rig run list");
+      const runs = listAuthorityRuns(context.projectRoot);
+      if (context.outputMode === "text") {
+        if (runs.length === 0) {
+          console.log("No runs recorded in .rig/runs.");
+        } else {
+          for (const run of runs) {
+            console.log(`- ${run.runId} \xB7 ${run.status} \xB7 ${run.title}`);
+          }
+        }
+      }
+      return { ok: true, group: "run", command, details: { runs } };
+    }
+    case "delete": {
+      let pending = rest;
+      const run = takeOption(pending, "--run");
+      pending = run.rest;
+      const purgeArtifacts = takeFlag(pending, "--purge-artifacts");
+      pending = purgeArtifacts.rest;
+      requireNoExtraArgs(pending, "bun run rig run delete --run <id> [--purge-artifacts]");
+      if (!run.value) {
+        throw new CliError2("run delete requires --run <id>.");
+      }
+      const result = await deleteRunState(context.projectRoot, {
+        runId: run.value,
+        purgeRuntime: true,
+        purgeTaskArtifacts: purgeArtifacts.value
+      });
+      if (context.outputMode === "text") {
+        console.log(`Deleted run ${result.runId}`);
+        if (result.runtimeIds.length > 0) {
+          console.log(`Cleaned runtimes: ${result.runtimeIds.join(", ")}`);
+        }
+        if (result.taskArtifactsDeleted) {
+          console.log(`Cleared task artifacts for ${result.taskId}`);
+        }
+      }
+      return { ok: true, group: "run", command, details: result };
+    }
+    case "cleanup": {
+      let pending = rest;
+      const all = takeFlag(pending, "--all");
+      pending = all.rest;
+      const keepArtifacts = takeFlag(pending, "--keep-artifacts");
+      pending = keepArtifacts.rest;
+      const keepRuntimes = takeFlag(pending, "--keep-runtimes");
+      pending = keepRuntimes.rest;
+      const keepQueue = takeFlag(pending, "--keep-queue");
+      pending = keepQueue.rest;
+      requireNoExtraArgs(pending, "bun run rig run cleanup --all [--keep-artifacts] [--keep-runtimes] [--keep-queue]");
+      if (!all.value) {
+        throw new CliError2("run cleanup currently requires --all.");
+      }
+      const result = await cleanupRunState(context.projectRoot, {
+        includeArtifacts: !keepArtifacts.value,
+        includeRuntimes: !keepRuntimes.value,
+        includeQueue: !keepQueue.value
+      });
+      if (context.outputMode === "text") {
+        console.log(`Deleted runs: ${result.runIds.length}`);
+        console.log(`Cleaned runtimes: ${result.runtimeIds.length}`);
+        console.log(`Artifacts cleared: ${result.artifactsCleared ? "yes" : "no"}`);
+        console.log(`Queue cleared: ${result.queueCleared ? "yes" : "no"}`);
+      }
+      return { ok: true, group: "run", command, details: result };
+    }
+    case "show": {
+      let pending = rest;
+      const run = takeOption(pending, "--run");
+      pending = run.rest;
+      requireNoExtraArgs(pending, "bun run rig run show --run <id>");
+      if (!run.value) {
+        throw new CliError2("run show requires --run <id>.");
+      }
+      const record = readAuthorityRun(context.projectRoot, run.value);
+      if (!record) {
+        throw new CliError2(`Run not found: ${run.value}`, 2);
+      }
+      if (context.outputMode === "text") {
+        console.log(JSON.stringify(record, null, 2));
+      }
+      return { ok: true, group: "run", command, details: record };
+    }
+    case "timeline": {
+      let pending = rest;
+      const run = takeOption(pending, "--run");
+      pending = run.rest;
+      const follow = takeFlag(pending, "--follow");
+      pending = follow.rest;
+      requireNoExtraArgs(pending, "bun run rig run timeline --run <id> [--follow]");
+      if (!run.value) {
+        throw new CliError2("run timeline requires --run <id>.");
+      }
+      const timelinePath = resolve2(resolveAuthorityRunDir(context.projectRoot, run.value), "timeline.jsonl");
+      const printEvents = () => {
+        const events2 = readJsonlFile(timelinePath);
+        if (context.outputMode === "text") {
+          for (const event of events2) {
+            console.log(JSON.stringify(event));
+          }
+        }
+        return events2;
+      };
+      const events = printEvents();
+      if (follow.value && context.outputMode === "text") {
+        let lastLength = existsSync2(timelinePath) ? readFileSync2(timelinePath, "utf8").length : 0;
+        while (true) {
+          await Bun.sleep(1000);
+          if (!existsSync2(timelinePath))
+            continue;
+          const next = readFileSync2(timelinePath, "utf8");
+          if (next.length <= lastLength)
+            continue;
+          const delta = next.slice(lastLength);
+          lastLength = next.length;
+          for (const line of delta.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean)) {
+            console.log(line);
+          }
+        }
+      }
+      return { ok: true, group: "run", command, details: { runId: run.value, events } };
+    }
+    case "attach": {
+      let pending = rest;
+      const runOption = takeOption(pending, "--run");
+      pending = runOption.rest;
+      const messageOption = takeOption(pending, "--message");
+      pending = messageOption.rest;
+      const once = takeFlag(pending, "--once");
+      pending = once.rest;
+      const follow = takeFlag(pending, "--follow");
+      pending = follow.rest;
+      const pollMs = takeOption(pending, "--poll-ms");
+      pending = pollMs.rest;
+      const positionalRunId = pending.length > 0 ? pending[0] : undefined;
+      const extra = positionalRunId ? pending.slice(1) : pending;
+      requireNoExtraArgs(extra, "bun run rig run attach <run-id>|--run <run-id> [--message <text>] [--once|--follow] [--poll-ms <ms>]");
+      const runId = runOption.value ?? positionalRunId;
+      if (!runId) {
+        throw new CliError2("run attach requires a run id.", 2);
+      }
+      const attached = await attachRunOperatorView(context, {
+        runId,
+        message: messageOption.value ?? null,
+        once: once.value,
+        follow: follow.value,
+        pollMs: parsePositiveInt(pollMs.value, "--poll-ms", 2000)
+      });
+      return { ok: true, group: "run", command, details: attached };
+    }
+    case "status": {
+      requireNoExtraArgs(rest, "bun run rig run status");
+      if (context.dryRun) {
+        if (context.outputMode === "text") {
+          console.log("[dry-run] rig run status");
+        }
+        return { ok: true, group: "run", command };
+      }
+      const summary = runStatus(context.projectRoot, runtimeContext);
+      if (context.outputMode === "text") {
+        console.log(`Active runs: ${summary.activeRuns.length}`);
+        for (const run of summary.activeRuns) {
+          console.log(`- ${run.runId} \xB7 ${run.status} \xB7 ${run.taskId ?? run.title}`);
+        }
+        if (summary.recentRuns.length > 0) {
+          console.log("");
+          console.log("Recent runs:");
+          for (const run of summary.recentRuns) {
+            console.log(`- ${run.runId} \xB7 ${run.status} \xB7 ${run.taskId ?? run.title}`);
+          }
+        }
+      }
+      return { ok: true, group: "run", command, details: summary };
+    }
+    case "start":
+    case "start-serial":
+    case "start-parallel": {
+      let pending = rest;
+      const epicResult = takeOption(pending, "--epic");
+      pending = epicResult.rest;
+      const promptEpicResult = takeFlag(pending, "--prompt-epic");
+      pending = promptEpicResult.rest;
+      const noEpicPromptResult = takeFlag(pending, "--no-epic-prompt");
+      pending = noEpicPromptResult.rest;
+      const wsPortResult = takeOption(pending, "--ws-port");
+      pending = wsPortResult.rest;
+      const serverHostResult = takeOption(pending, "--server-host");
+      pending = serverHostResult.rest;
+      const serverPortResult = takeOption(pending, "--server-port");
+      pending = serverPortResult.rest;
+      const pollResult = takeOption(pending, "--poll-ms");
+      pending = pollResult.rest;
+      const noServerResult = takeFlag(pending, "--no-server");
+      pending = noServerResult.rest;
+      requireNoExtraArgs(pending, "bun run rig run start [--epic <id>] [--prompt-epic|--no-epic-prompt] [--ws-port <n>] [--server-host <host>] [--server-port <n>] [--poll-ms <n>] [--no-server]");
+      if (promptEpicResult.value && noEpicPromptResult.value) {
+        throw new CliError2("Cannot use --prompt-epic and --no-epic-prompt together.");
+      }
+      if (promptEpicResult.value && (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY)) {
+        throw new CliError2("--prompt-epic requires an interactive terminal (TTY) in text mode.");
+      }
+      let resolvedEpicId = epicResult.value || undefined;
+      if (!resolvedEpicId && shouldPromptForEpicSelection(context, command, promptEpicResult.value, noEpicPromptResult.value)) {
+        resolvedEpicId = await promptForEpicSelection(context.projectRoot, command);
+      }
+      const defaults = defaultStartRunOptions(command === "start-parallel" ? "parallel" : "serial");
+      const result = await startRun(context.projectRoot, {
+        mode: command === "start-parallel" ? "parallel" : "serial",
+        workers: defaults.workers,
+        epicId: resolvedEpicId,
+        wsPort: parsePositiveInt(wsPortResult.value, "--ws-port", defaults.wsPort),
+        startEventServer: noServerResult.value ? false : defaults.startEventServer,
+        serverHost: serverHostResult.value || defaults.serverHost,
+        serverPort: parsePositiveInt(serverPortResult.value, "--server-port", defaults.serverPort),
+        serverPollMs: parsePositiveInt(pollResult.value, "--poll-ms", defaults.serverPollMs),
+        dryRun: context.dryRun,
+        runtimeContext
+      });
+      if (context.outputMode === "text") {
+        console.log(`Epic: ${result.epicId}`);
+        console.log(`Server: ${result.baseUrl}`);
+        if (result.eventServerUrl) {
+          console.log(`Events: ${result.eventServerUrl}`);
+        }
+        console.log(`Runs: ${result.runIds.join(", ")}`);
+      }
+      if (result.exitCode !== 0) {
+        throw new CliError2(`run ${command} failed with exit code ${result.exitCode}.`, result.exitCode);
+      }
+      return {
+        ok: true,
+        group: "run",
+        command,
+        details: {
+          epicId: result.epicId,
+          baseUrl: result.baseUrl,
+          runIds: result.runIds,
+          eventServerUrl: result.eventServerUrl || null
+        }
+      };
+    }
+    case "resume": {
+      requireNoExtraArgs(rest, "bun run rig run resume");
+      if (context.dryRun) {
+        if (context.outputMode === "text") {
+          console.log("[dry-run] rig run resume");
+        }
+        return { ok: true, group: "run", command };
+      }
+      const resumed = await runResume(context.projectRoot, runtimeContext);
+      if (context.outputMode === "text") {
+        console.log(`Resumed run: ${resumed.runId}`);
+      }
+      return { ok: true, group: "run", command, details: resumed };
+    }
+    case "stop": {
+      const runOption = takeOption(rest, "--run");
+      const positionalRunId = runOption.rest.length > 0 ? runOption.rest[0] : undefined;
+      const extra = positionalRunId ? runOption.rest.slice(1) : runOption.rest;
+      requireNoExtraArgs(extra, "bun run rig run stop [<run-id>|--run <id>]");
+      const runId = runOption.value ?? positionalRunId;
+      if (context.dryRun) {
+        return {
+          ok: true,
+          group: "run",
+          command,
+          details: runId ? { runId, accepted: true } : { stopped: 0, remaining: [] }
+        };
+      }
+      if (runId) {
+        const stopped = await stopRunViaServer(context, runId);
+        if (context.outputMode === "text")
+          console.log(`Stop requested: ${runId}`);
+        return { ok: true, group: "run", command, details: stopped };
+      }
+      const result = await runStop(context.projectRoot);
+      if (result.remaining.length > 0) {
+        throw new CliError2(`Failed to stop run(s): ${result.remaining.join(", ")}`, 1);
+      }
+      if (context.outputMode === "text") {
+        console.log(`Stopped process count: ${result.stopped}`);
+      }
+      return {
+        ok: true,
+        group: "run",
+        command,
+        details: {
+          stopped: result.stopped,
+          remaining: result.remaining
+        }
+      };
+    }
+    default:
+      throw new CliError2(`Unknown run command: ${command}`);
+  }
+}
+export {
+  executeRun
+};