@h-rig/cli 0.0.6-alpha.7 → 0.0.6-alpha.71

package/dist/src/commands/run.js

@@ -1,17 +1,22 @@
 // @bun
 // packages/cli/src/commands/run.ts
-import { existsSync as existsSync3, readFileSync as readFileSync3 } from "fs";
-import { resolve as resolve3 } 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 { CliError as RuntimeCliError } 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";
+
+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;
@@ -32,7 +37,7 @@ function takeOption(args, option) {
     if (current === option) {
       const next = args[index + 1];
       if (!next || next.startsWith("-")) {
-        throw new CliError(`Missing value for ${option}`);
+        throw new CliError(`Missing value for ${option}`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} <value>\`.` });
       }
       value = next;
       index += 1;
@@ -54,23 +59,19 @@ Usage: ${usage}`);
 // packages/cli/src/commands/run.ts
 import {
   listAuthorityRuns,
-  readAuthorityRun,
-  readJsonlFile,
-  resolveAuthorityRunDir
+  readAuthorityRun as readAuthorityRun2
 } from "@rig/runtime/control-plane/authority-files";
 import {
   cleanupRunState,
   deleteRunState,
   listOpenEpics,
   resolveDefaultEpic,
-  runResume,
-  runRestart,
   runStatus,
   runStop,
   startRun,
   defaultStartRunOptions
 } from "@rig/runtime/control-plane/native/run-ops";
-import { loadRuntimeContextFromEnv as loadRuntimeContextFromEnv2 } from "@rig/runtime/control-plane/runtime/context";
+import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 
 // packages/cli/src/commands/_parsers.ts
 function parsePositiveInt(value, option, fallback) {
@@ -79,13 +80,12 @@ function parsePositiveInt(value, option, fallback) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
 
 // packages/cli/src/commands/_server-client.ts
-import { spawnSync } from "child_process";
 import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { resolve as resolve2 } from "path";
 import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
@@ -112,9 +112,14 @@ function readJsonFile(path) {
   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);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
+function writeJsonFile(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
 function normalizeConnection(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return null;
@@ -155,25 +160,47 @@ function readRepoConnection(projectRoot) {
   return {
     selected,
     project: typeof record.project === "string" ? record.project : undefined,
-    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
   };
 }
+function writeRepoConnection(projectRoot, state) {
+  writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
+}
 function resolveSelectedConnection(projectRoot, options = {}) {
   const repo = readRepoConnection(projectRoot);
   if (!repo)
     return null;
   if (repo.selected === "local")
-    return { alias: "local", connection: { kind: "local", mode: "auto" } };
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
   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);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
   }
-  return { alias: repo.selected, connection };
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+function isRemoteConnectionSelected(projectRoot) {
+  return resolveSelectedConnection(projectRoot)?.connection.kind === "remote";
 }
 
 // packages/cli/src/commands/_server-client.ts
-var cachedGitHubBearerToken;
+var scopedGitHubBearerTokens = new Map;
+var serverPhaseListener = null;
+function setServerPhaseListener(listener) {
+  const previous = serverPhaseListener;
+  serverPhaseListener = listener;
+  return previous;
+}
+function reportServerPhase(label) {
+  serverPhaseListener?.(label);
+}
 function cleanToken(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : null;
@@ -190,49 +217,80 @@ function readPrivateRemoteSessionToken(projectRoot) {
   }
 }
 function readGitHubBearerTokenForRemote(projectRoot) {
-  if (cachedGitHubBearerToken !== undefined)
-    return cachedGitHubBearerToken;
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
   const privateSession = readPrivateRemoteSessionToken(projectRoot);
-  if (privateSession) {
-    cachedGitHubBearerToken = privateSession;
-    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;
+  if (privateSession)
+    return privateSession;
+  return cleanToken(process.env.RIG_SERVER_AUTH_TOKEN) ?? cleanToken(process.env.RIG_REMOTE_AUTH_TOKEN);
+}
+function readStoredGitHubAuthToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.token === "string" ? parsed.token : undefined);
+  } catch {
+    return null;
+  }
+}
+function readLocalConnectionFallbackToken(projectRoot) {
+  return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
 }
 async function ensureServerForCli(projectRoot) {
   try {
     const selected = resolveSelectedConnection(projectRoot);
     if (selected?.connection.kind === "remote") {
+      reportServerPhase(`Connecting to ${selected.alias}\u2026`);
+      const authToken = readGitHubBearerTokenForRemote(projectRoot);
+      const serverProjectRoot = selected.serverProjectRoot ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
       return {
         baseUrl: selected.connection.baseUrl,
-        authToken: readGitHubBearerTokenForRemote(projectRoot),
-        connectionKind: "remote"
+        authToken,
+        connectionKind: "remote",
+        serverProjectRoot
       };
     }
+    reportServerPhase("Starting local Rig server\u2026");
     const connection = await ensureLocalRigServerConnection(projectRoot);
     return {
       baseUrl: connection.baseUrl,
-      authToken: connection.authToken,
-      connectionKind: "local"
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
 }
+async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
+  const repo = readRepoConnection(projectRoot);
+  const slug = repo?.project?.trim();
+  if (!slug)
+    return null;
+  try {
+    const response = await fetch(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`, {
+      headers: mergeHeaders(undefined, authToken)
+    });
+    if (!response.ok)
+      return null;
+    const payload = await response.json();
+    const project = payload.project && typeof payload.project === "object" && !Array.isArray(payload.project) ? payload.project : null;
+    const checkouts = Array.isArray(project?.checkouts) ? project.checkouts : [];
+    const latestCheckout = [...checkouts].reverse().find((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.path === "string"));
+    const path = typeof latestCheckout?.path === "string" && latestCheckout.path.trim() ? latestCheckout.path.trim() : null;
+    if (path)
+      writeRepoServerProjectRoot(projectRoot, path);
+    return path;
+  } catch {
+    return null;
+  }
+}
 function mergeHeaders(headers, authToken) {
   const merged = new Headers(headers);
   if (authToken) {
@@ -255,12 +313,65 @@ function diagnosticMessage(payload) {
   });
   return messages.length > 0 ? messages.join("; ") : null;
 }
+var serverReachabilityCache = new Map;
+async function probeServerReachability(baseUrl, authToken) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/server/status`, {
+      headers: mergeHeaders(undefined, authToken),
+      signal: AbortSignal.timeout(1500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function cachedServerReachability(projectRoot, baseUrl, authToken) {
+  const key = resolve2(projectRoot);
+  const cached = serverReachabilityCache.get(key);
+  if (cached)
+    return cached;
+  const probe = probeServerReachability(baseUrl, authToken);
+  serverReachabilityCache.set(key, probe);
+  return probe;
+}
+function describeSelectedServer(projectRoot, server) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected) {
+      return {
+        alias: selected.alias,
+        target: selected.connection.kind === "remote" ? selected.connection.baseUrl : server.baseUrl
+      };
+    }
+  } catch {}
+  return { alias: server.connectionKind === "remote" ? "remote" : "local", target: server.baseUrl };
+}
+async function buildServerFailureContext(projectRoot, server) {
+  const { alias, target } = describeSelectedServer(projectRoot, server);
+  const reachable = await cachedServerReachability(projectRoot, server.baseUrl, server.authToken);
+  const reachability = reachable ? "server is reachable" : "server is unreachable";
+  return {
+    contextLine: `Currently connected to: ${alias} at ${target} (${reachability}).`,
+    hint: "Check the selected server with `rig server status`, or switch with `rig server use <alias|local>`."
+  };
+}
 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 headers = mergeHeaders(init.headers, server.authToken);
+  if (server.serverProjectRoot)
+    headers.set("x-rig-project-root", server.serverProjectRoot);
+  reportServerPhase(`${(init.method ?? "GET").toUpperCase()} ${pathname.split("?")[0]}\u2026`);
+  let response;
+  try {
+    response = await fetch(`${server.baseUrl}${pathname}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed: ${error instanceof Error ? error.message : String(error)}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
   const text = await response.text();
   const payload = text.trim().length > 0 ? (() => {
     try {
@@ -272,10 +383,20 @@ async function requestServerJson(context, pathname, init = {}) {
   if (!response.ok) {
     const diagnostics = diagnosticMessage(payload);
     const detail = diagnostics ?? (text || response.statusText);
-    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed (${response.status}): ${detail}
+${failure.contextLine}`, 1, { hint: failure.hint });
   }
   return payload;
 }
+async function listRunsViaServer(context, options = {}) {
+  const url = new URL("http://rig.local/api/runs");
+  if (options.limit !== undefined)
+    url.searchParams.set("limit", String(options.limit));
+  const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
+  const runs = Array.isArray(payload) ? payload : payload && typeof payload === "object" && !Array.isArray(payload) && Array.isArray(payload.runs) ? payload.runs : [];
+  return runs.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry)));
+}
 async function getRunDetailsViaServer(context, runId) {
   const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}`);
   return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
@@ -289,6 +410,47 @@ async function getRunLogsViaServer(context, runId, options = {}) {
   const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
   return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { entries: [] };
 }
+async function getRunTimelineViaServer(context, runId, options = {}) {
+  const url = new URL(`http://rig.local/api/runs/${encodeURIComponent(runId)}/timeline`);
+  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: [] };
+}
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
+async function resumeRunViaServer(context, runId, options) {
+  let targetRunId = runId?.trim() || null;
+  if (!targetRunId) {
+    const candidates = (await listRunsViaServer(context)).filter((run) => RESUMABLE_RUN_STATUSES.has(String(run.status ?? ""))).sort((left, right) => String(right.updatedAt ?? "").localeCompare(String(left.updatedAt ?? "")));
+    targetRunId = typeof candidates[0]?.runId === "string" ? candidates[0].runId : null;
+  }
+  if (!targetRunId) {
+    throw new CliError(options.restart ? "No run is available to restart." : "No resumable run is available.", 2, { hint: "List runs with `rig run list`, then pass an explicit id: `rig run resume <run-id>`." });
+  }
+  const payload = await requestServerJson(context, "/api/runs/resume", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ runId: targetRunId, createdAt: new Date().toISOString(), restart: options.restart })
+  });
+  const record = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  if (record.ok === false) {
+    const message = typeof record.error === "string" && record.error.trim() ? record.error : "run resume failed";
+    throw new CliError(`${options.restart ? "restart" : "resume"} failed for ${targetRunId}: ${message}`, 1);
+  }
+  return { ok: true, runId: targetRunId, ...record };
+}
 async function stopRunViaServer(context, runId) {
   const payload = await requestServerJson(context, "/api/runs/stop", {
     method: "POST",
@@ -305,10 +467,155 @@ async function steerRunViaServer(context, runId, message) {
   });
   return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
 }
+async function sendRunPiPromptViaServer(context, runId, text, streamingBehavior) {
+  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/prompt`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ text, streamingBehavior })
+  });
+  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { accepted: true };
+}
 
-// packages/cli/src/commands/_operator-view.ts
+// packages/cli/src/commands/_run-replay.ts
+import { existsSync as existsSync3, readdirSync } from "fs";
+import { join, resolve as resolve3 } from "path";
+import {
+  readAuthorityRun,
+  readJsonlFile,
+  runJournalPath
+} from "@rig/runtime/control-plane/authority-files";
+function asRecord(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function text(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function snippet(value, max = 120) {
+  const raw = text(value);
+  if (!raw)
+    return null;
+  const flat = raw.replace(/\s+/g, " ");
+  return flat.length > max ? `${flat.slice(0, max - 1)}\u2026` : flat;
+}
+function summarizeLifecycleEntry(entry) {
+  const type = text(entry.type) ?? "event";
+  switch (type) {
+    case "status": {
+      const anchor = text(entry.sessionId);
+      return [
+        `status \u2192 ${text(entry.status) ?? "(unknown)"}`,
+        snippet(entry.detail) ? `\u2014 ${snippet(entry.detail)}` : null,
+        anchor ? `[session ${anchor}]` : null
+      ].filter(Boolean).join(" ");
+    }
+    case "timeline-entry": {
+      const payload = asRecord(entry.payload) ?? {};
+      const kind = text(payload.type) ?? "entry";
+      const body = snippet(payload.title) ?? snippet(payload.text) ?? snippet(payload.detail);
+      const state = text(payload.state);
+      return [`timeline ${kind}`, body ? `\u2014 ${body}` : null, state ? `(${state})` : null].filter(Boolean).join(" ");
+    }
+    case "log-entry": {
+      const payload = asRecord(entry.payload) ?? {};
+      const title = snippet(payload.title) ?? "log";
+      const detail = snippet(payload.detail);
+      return [`log ${title}`, detail ? `\u2014 ${detail}` : null].filter(Boolean).join(" ");
+    }
+    case "record-patch": {
+      const patch = asRecord(entry.patch) ?? {};
+      const keys = Object.keys(patch);
+      const shown = keys.slice(0, 8).join(", ");
+      return `record-patch {${shown}${keys.length > 8 ? `, +${keys.length - 8} more` : ""}}`;
+    }
+    case "timeline":
+      return "timeline updated (signal)";
+    case "log":
+      return `log signal${snippet(entry.title) ? ` \u2014 ${snippet(entry.title)}` : ""}`;
+    case "completed":
+      return "run completed";
+    case "failed":
+      return `run failed${snippet(entry.error) ? ` \u2014 ${snippet(entry.error)}` : ""}`;
+    default:
+      return type;
+  }
+}
+function summarizeSessionEntry(entry) {
+  const type = text(entry.type) ?? "entry";
+  const message = asRecord(entry.message);
+  const role = text(message?.role);
+  const content = message?.content;
+  let body = null;
+  if (typeof content === "string") {
+    body = snippet(content);
+  } else if (Array.isArray(content)) {
+    body = snippet(content.map((part) => text(asRecord(part)?.text) ?? "").filter(Boolean).join(" "));
+  }
+  return [
+    `pi ${type}`,
+    role ? `(${role})` : null,
+    body ? `\u2014 ${body}` : null
+  ].filter(Boolean).join(" ");
+}
+function sessionEntryTimestamp(entry) {
+  return text(entry.timestamp) ?? text(entry.at) ?? text(entry.createdAt) ?? null;
+}
+function resolveRunSessionFile(record) {
+  const piSession = record?.piSession ?? null;
+  if (!piSession)
+    return null;
+  const recorded = text(piSession.sessionFile);
+  if (recorded && existsSync3(recorded)) {
+    return recorded;
+  }
+  const cwd = text(piSession.cwd);
+  const sessionId = text(piSession.sessionId);
+  if (!cwd || !sessionId)
+    return null;
+  const sessionDir = resolve3(cwd, ".rig", "session");
+  try {
+    const match = readdirSync(sessionDir).find((name) => name.endsWith(`_${sessionId}.jsonl`));
+    return match ? join(sessionDir, match) : null;
+  } catch {
+    return null;
+  }
+}
+function buildRunReplay(projectRoot, runId, options = {}) {
+  const logPath = runJournalPath(projectRoot, runId);
+  const record = readAuthorityRun(projectRoot, runId);
+  const lifecycleEntries = readJsonlFile(logPath).map((entry) => asRecord(entry)).filter((entry) => entry !== null);
+  const merged = lifecycleEntries.map((entry) => ({
+    at: text(entry.at),
+    source: "run",
+    summary: summarizeLifecycleEntry(entry)
+  }));
+  let sessionFile = null;
+  let sessionEntryCount = 0;
+  if (options.withSession) {
+    sessionFile = resolveRunSessionFile(record);
+    if (sessionFile) {
+      let lastSeenAt = null;
+      const sessionLines = readJsonlFile(sessionFile).map((entry) => asRecord(entry)).filter((entry) => entry !== null).map((entry) => {
+        lastSeenAt = sessionEntryTimestamp(entry) ?? lastSeenAt;
+        return { at: lastSeenAt, source: "session", summary: summarizeSessionEntry(entry) };
+      });
+      sessionEntryCount = sessionLines.length;
+      merged.push(...sessionLines);
+      merged.sort((left, right) => (left.at ?? "").localeCompare(right.at ?? ""));
+    }
+  }
+  const lines = merged.map((line) => `${line.at ?? "(no timestamp)      "}  ${line.source === "run" ? "run    " : "session"}  ${line.summary}`);
+  return {
+    runId,
+    logPath,
+    sessionFile,
+    entryCount: lifecycleEntries.length,
+    sessionEntryCount,
+    lines
+  };
+}
+
+// packages/cli/src/commands/_operator-surface.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",
@@ -323,18 +630,380 @@ var CANONICAL_STAGES = [
   "Merge",
   "Complete"
 ];
+function logDetail(log) {
+  return typeof log.detail === "string" ? log.detail.trim() : "";
+}
+function parseProviderProtocolLog(title, detail) {
+  if (title.trim().toLowerCase() !== "agent output")
+    return null;
+  if (!detail.startsWith("{") || !detail.endsWith("}"))
+    return null;
+  try {
+    const record = JSON.parse(detail);
+    if (!record || typeof record !== "object" || Array.isArray(record))
+      return null;
+    const type = record.type;
+    return typeof type === "string" && [
+      "assistant",
+      "message_start",
+      "message_update",
+      "message_end",
+      "stream_event",
+      "tool_result",
+      "tool_execution_start",
+      "tool_execution_update",
+      "tool_execution_end",
+      "turn_start",
+      "turn_end"
+    ].includes(type) ? record : null;
+  } catch {
+    return null;
+  }
+}
+function renderProviderProtocolLog(record) {
+  const type = typeof record.type === "string" ? record.type : "";
+  if (type === "tool_execution_start" || type === "tool_execution_update" || type === "tool_execution_end") {
+    const toolName = String(record.toolName ?? record.name ?? "tool");
+    const status = type === "tool_execution_start" ? "started" : type === "tool_execution_end" ? record.isError === true || record.result && typeof record.result === "object" && !Array.isArray(record.result) && record.result.isError === true ? "failed" : "completed" : "running";
+    return `[Pi tool] ${toolName} ${status}`;
+  }
+  return null;
+}
+function entryId(entry, fallback) {
+  return typeof entry.id === "string" && entry.id.trim() ? entry.id : fallback;
+}
 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 latestByStage = new Map;
+  for (const log of logs) {
+    const title = String(log.title ?? "").toLowerCase();
+    const stageName = String(log.stage ?? "").toLowerCase();
+    const stage = CANONICAL_STAGES.find((candidate) => candidate.toLowerCase() === title || candidate.toLowerCase() === stageName);
+    if (stage)
+      latestByStage.set(stage, log);
+  }
   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)}`] : [];
+    const match = latestByStage.get(stage);
+    return match ? [`${stage}: ${String(match.status ?? status)}${logDetail(match) ? ` \u2014 ${logDetail(match)}` : ""}`] : [];
   });
   return [`Rig run ${runId}: ${status}`, ...stageLines].join(`
 `);
 }
+function createPiRunStreamRenderer(output = process.stdout) {
+  let lastSnapshot = "";
+  const assistantTextById = new Map;
+  const seenTimeline = new Set;
+  const seenLogs = new Set;
+  const writeLine = (line) => output.write(`${line}
+`);
+  return {
+    renderSnapshot(snapshot) {
+      const rendered = renderOperatorSnapshot(snapshot);
+      if (rendered && rendered !== lastSnapshot) {
+        writeLine(rendered);
+        lastSnapshot = rendered;
+      }
+    },
+    renderTimeline(entries) {
+      for (const [index, entry] of entries.entries()) {
+        const id = entryId(entry, `timeline:${index}:${String(entry.cursor ?? "")}`);
+        if (entry.type === "assistant_message" && typeof entry.text === "string") {
+          const text2 = entry.text;
+          const previousText = assistantTextById.get(id) ?? "";
+          if (!previousText && text2.trim()) {
+            writeLine("[Pi assistant]");
+          }
+          if (text2.startsWith(previousText)) {
+            const delta = text2.slice(previousText.length);
+            if (delta)
+              output.write(delta);
+          } else if (text2.trim() && text2 !== previousText) {
+            if (previousText)
+              writeLine(`
+[Pi assistant]`);
+            output.write(text2);
+          }
+          assistantTextById.set(id, text2);
+          continue;
+        }
+        if (seenTimeline.has(id))
+          continue;
+        seenTimeline.add(id);
+        if (entry.type === "tool_execution_start" || entry.type === "tool_execution_update" || entry.type === "tool_execution_end" || entry.type === "mcp_tool_call") {
+          writeLine(`[Pi tool] ${String(entry.toolName ?? entry.name ?? entry.title ?? entry.type)} ${String(entry.status ?? entry.state ?? "")}`.trim());
+          continue;
+        }
+        if (entry.type === "timeline_warning") {
+          writeLine(`[Rig timeline] ${String(entry.detail ?? entry.message ?? "timeline unavailable")}`);
+          continue;
+        }
+        if (entry.type === "action") {
+          const text2 = String(entry.detail ?? entry.message ?? entry.title ?? "").trim();
+          if (text2)
+            writeLine(`[Rig action] ${text2}`);
+          continue;
+        }
+        if (entry.type === "user_message") {
+          const text2 = String(entry.text ?? entry.message ?? entry.detail ?? "").trim();
+          if (text2)
+            writeLine(`[Operator] ${text2}`);
+          continue;
+        }
+        const fallback = String(entry.detail ?? entry.message ?? entry.text ?? entry.title ?? "").trim();
+        if (fallback)
+          writeLine(`[${String(entry.type ?? "timeline")}] ${fallback}`);
+      }
+    },
+    renderLogs(entries) {
+      for (const [index, entry] of entries.entries()) {
+        const id = entryId(entry, `log:${index}:${String(entry.createdAt ?? "")}:${String(entry.title ?? "")}`);
+        if (seenLogs.has(id))
+          continue;
+        seenLogs.add(id);
+        const title = String(entry.title ?? "");
+        if (CANONICAL_STAGES.some((stage) => stage.toLowerCase() === title.toLowerCase()))
+          continue;
+        const detail = logDetail(entry);
+        if (!detail)
+          continue;
+        const protocolRecord = parseProviderProtocolLog(title, detail);
+        if (protocolRecord) {
+          const protocolLine = renderProviderProtocolLog(protocolRecord);
+          if (protocolLine)
+            writeLine(protocolLine);
+          continue;
+        }
+        writeLine(`[${title || "Rig log"}] ${detail}`);
+      }
+    }
+  };
+}
+function createOperatorSurface(options = {}) {
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const errorOutput = options.errorOutput ?? process.stderr;
+  const renderer = createPiRunStreamRenderer(output);
+  const writeLine = (line) => output.write(`${line}
+`);
+  return {
+    mode: "pi-compatible-text",
+    ...renderer,
+    info: writeLine,
+    error: (message) => errorOutput.write(`${message}
+`),
+    attachCommandInput(handler) {
+      if (options.interactive === false || !input.isTTY)
+        return null;
+      const rl = createInterface({ input, output: process.stdout, terminal: false });
+      rl.on("line", (line) => {
+        Promise.resolve(handler(line)).catch((error) => writeLine(`Operator command failed: ${error instanceof Error ? error.message : String(error)}`));
+      });
+      return { close: () => rl.close() };
+    }
+  };
+}
+
+// packages/cli/src/commands/_pi-frontend.ts
+import { mkdtempSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join as join2 } from "path";
+import { main as runPiMain } from "@earendil-works/pi-coding-agent";
+import createPiRigExtension from "@rig/pi-rig";
+function setTemporaryEnv(updates) {
+  const previous = new Map;
+  for (const [key, value] of Object.entries(updates)) {
+    previous.set(key, process.env[key]);
+    process.env[key] = value;
+  }
+  return () => {
+    for (const [key, value] of previous) {
+      if (value === undefined)
+        delete process.env[key];
+      else
+        process.env[key] = value;
+    }
+  };
+}
+function buildOperatorPiEnv(input) {
+  return {
+    PI_CODING_AGENT_SESSION_DIR: input.sessionDir,
+    PI_SKIP_VERSION_CHECK: "1",
+    RIG_PI_OPERATOR_SESSION: "1",
+    RIG_RUN_ID: input.runId,
+    RIG_SERVER_URL: input.serverUrl,
+    ...input.authToken ? { RIG_AUTH_TOKEN: input.authToken } : {},
+    ...input.serverProjectRoot ? { RIG_PROJECT_ROOT: input.serverProjectRoot } : {}
+  };
+}
+async function attachRunBundledPiFrontend(context, input) {
+  const tempSessionDir = mkdtempSync(join2(tmpdir(), "rig-pi-frontend-sessions-"));
+  const server = await ensureServerForCli(context.projectRoot);
+  const restoreEnv = setTemporaryEnv(buildOperatorPiEnv({
+    runId: input.runId,
+    serverUrl: server.baseUrl,
+    authToken: server.authToken,
+    serverProjectRoot: server.serverProjectRoot,
+    sessionDir: tempSessionDir
+  }));
+  const piRigExtensionFactory = (pi) => {
+    createPiRigExtension(pi);
+  };
+  let detached = false;
+  try {
+    await runPiMain([
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-context-files"
+    ], {
+      extensionFactories: [piRigExtensionFactory]
+    });
+    detached = true;
+  } finally {
+    restoreEnv();
+    rmSync(tempSessionDir, { recursive: true, force: true });
+  }
+  let run = { runId: input.runId, status: "unknown" };
+  try {
+    run = await getRunDetailsViaServer(context, input.runId);
+  } catch {}
+  return {
+    run,
+    logs: [],
+    timeline: [],
+    timelineCursor: null,
+    steered: input.steered === true,
+    detached,
+    rendered: "stock Pi operator console with the pi-rig extension"
+  };
+}
+
+// packages/cli/src/commands/_async-ui.ts
+import pc from "picocolors";
+
+// packages/cli/src/commands/_spinner.ts
+var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function createTtySpinner(input) {
+  const output = input.output ?? process.stdout;
+  const isTty = output.isTTY === true;
+  const frames = input.frames && input.frames.length > 0 ? input.frames : SPINNER_FRAMES;
+  let label = input.label;
+  let frame = 0;
+  let paused = false;
+  let stopped = false;
+  let lastPrintedLabel = "";
+  const render = () => {
+    if (stopped || paused)
+      return;
+    if (!isTty) {
+      if (label !== lastPrintedLabel) {
+        output.write(`${label}
+`);
+        lastPrintedLabel = label;
+      }
+      return;
+    }
+    frame = (frame + 1) % frames.length;
+    const glyph = frames[frame] ?? frames[0] ?? "";
+    output.write(`\r\x1B[2K${input.styleFrame ? input.styleFrame(glyph) : glyph} ${label}`);
+  };
+  const clearLine = () => {
+    if (isTty)
+      output.write("\r\x1B[2K");
+  };
+  render();
+  const timer = isTty ? setInterval(render, input.intervalMs ?? 120) : null;
+  return {
+    setLabel(next) {
+      label = next;
+      render();
+    },
+    pause() {
+      paused = true;
+      clearLine();
+    },
+    resume() {
+      if (stopped)
+        return;
+      paused = false;
+      render();
+    },
+    stop(finalLine) {
+      if (stopped)
+        return;
+      stopped = true;
+      if (timer)
+        clearInterval(timer);
+      clearLine();
+      if (finalLine)
+        output.write(`${finalLine}
+`);
+    }
+  };
+}
+
+// packages/cli/src/commands/_async-ui.ts
+var CLACK_SPINNER_FRAMES = ["\u25D2", "\u25D0", "\u25D3", "\u25D1"];
+var DONE_SYMBOL = pc.green("\u25C7");
+var FAIL_SYMBOL = pc.red("\u25A0");
+var activeUpdate = null;
+async function withSpinner(label, work, options = {}) {
+  if (options.outputMode === "json") {
+    return work(() => {});
+  }
+  if (activeUpdate) {
+    const outer = activeUpdate;
+    outer(label);
+    return work(outer);
+  }
+  const output = options.output ?? process.stderr;
+  const isTty = output.isTTY === true;
+  let lastLabel = label;
+  if (!isTty) {
+    output.write(`${label}
+`);
+    const update2 = (next) => {
+      lastLabel = next;
+    };
+    activeUpdate = update2;
+    const previousListener2 = setServerPhaseListener(update2);
+    try {
+      return await work(update2);
+    } finally {
+      activeUpdate = null;
+      setServerPhaseListener(previousListener2);
+    }
+  }
+  const spinner = createTtySpinner({
+    label,
+    output,
+    frames: CLACK_SPINNER_FRAMES,
+    styleFrame: (frame) => pc.magenta(frame)
+  });
+  const update = (next) => {
+    lastLabel = next;
+    spinner.setLabel(next);
+  };
+  activeUpdate = update;
+  const previousListener = setServerPhaseListener(update);
+  try {
+    const result = await work(update);
+    spinner.stop(options.doneLabel ? `${DONE_SYMBOL} ${options.doneLabel}` : undefined);
+    return result;
+  } catch (error) {
+    spinner.stop(`${FAIL_SYMBOL} ${lastLabel}`);
+    throw error;
+  } finally {
+    activeUpdate = null;
+    setServerPhaseListener(previousListener);
+  }
+}
+
+// packages/cli/src/commands/_operator-view.ts
+var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
 function runStatusFromPayload(payload) {
   const run = payload.run && typeof payload.run === "object" && !Array.isArray(payload.run) ? payload.run : payload;
   return String(run.status ?? "unknown").toLowerCase();
@@ -356,56 +1025,307 @@ async function applyOperatorCommand(context, input, deps = {}) {
   await (deps.steer ?? steerRunViaServer)(context, input.runId, userMessage);
   return { action: "continue", message: "Steering message queued." };
 }
-async function readOperatorSnapshot(context, runId) {
+async function readOperatorSnapshot(context, runId, options = {}) {
   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 }) };
+  const timelinePage = await getRunTimelineViaServer(context, runId, { limit: 200, ...options.timelineCursor ? { cursor: options.timelineCursor } : {} }).catch((error) => ({
+    entries: [{
+      id: `timeline-unavailable:${runId}`,
+      type: "timeline_warning",
+      detail: `Selected Rig server did not provide run timeline events: ${error instanceof Error ? error.message : String(error)}`,
+      createdAt: new Date().toISOString()
+    }],
+    nextCursor: options.timelineCursor ?? null
+  }));
+  const logs = Array.isArray(logsPage.entries) ? logsPage.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))).toReversed() : [];
+  const timeline = Array.isArray(timelinePage.entries) ? timelinePage.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+  const timelineCursor = typeof timelinePage.nextCursor === "string" ? timelinePage.nextCursor : options.timelineCursor ?? null;
+  return { run, logs, timeline, timelineCursor, rendered: renderOperatorSnapshot({ run, logs, timeline }) };
 }
 async function attachRunOperatorView(context, input) {
   let steered = false;
-  if (input.message?.trim()) {
-    await steerRunViaServer(context, input.runId, input.message.trim());
+  const attachMessage = input.message?.trim();
+  if (attachMessage) {
+    await withSpinner("Queueing steering message\u2026", () => sendRunPiPromptViaServer(context, input.runId, attachMessage, "steer").catch(() => steerRunViaServer(context, input.runId, attachMessage)), { outputMode: context.outputMode });
     steered = true;
   }
-  let snapshot = await readOperatorSnapshot(context, input.runId);
+  if (input.follow && !input.once && input.interactive !== false && context.outputMode === "text" && Boolean(process.stdin.isTTY && process.stdout.isTTY)) {
+    return attachRunBundledPiFrontend(context, {
+      runId: input.runId,
+      steered
+    });
+  }
+  const surface = createOperatorSurface({ interactive: input.interactive !== false });
+  let snapshot = await withSpinner(`Connecting to run ${input.runId}\u2026`, () => readOperatorSnapshot(context, input.runId), { outputMode: context.outputMode });
   if (context.outputMode === "text") {
-    console.log(snapshot.rendered);
+    surface.renderSnapshot(snapshot);
+    surface.renderTimeline(snapshot.timeline);
+    surface.renderLogs(snapshot.logs);
     if (steered)
-      console.log("Steering message queued.");
+      surface.info("Message submitted to worker Pi.");
   }
   let detached = false;
-  let rl = null;
+  let commandInput = 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)}`));
+      surface.info("Controls: /user <message>, /stop, /detach");
+      commandInput = surface.attachCommandInput(async (line) => {
+        const result = await applyOperatorCommand(context, { runId: input.runId, line });
+        if (result.message)
+          surface.info(result.message);
+        if (result.action === "detach" || result.action === "stopped") {
+          detached = true;
+          commandInput?.close();
+        }
       });
     }
-    let lastRendered = snapshot.rendered;
     const pollMs = Math.max(250, Math.trunc(input.pollMs ?? 2000));
+    let timelineCursor = snapshot.timelineCursor;
     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;
-      }
+      snapshot = await readOperatorSnapshot(context, input.runId, { timelineCursor });
+      timelineCursor = snapshot.timelineCursor;
+      surface.renderSnapshot(snapshot);
+      surface.renderTimeline(snapshot.timeline);
+      surface.renderLogs(snapshot.logs);
     }
-    rl?.close();
+    commandInput?.close();
   }
   return { ...snapshot, steered, detached };
 }
 
+// packages/cli/src/commands/_cli-format.ts
+import { log, note } from "@clack/prompts";
+import pc2 from "picocolors";
+function stringField(record, key, fallback = "") {
+  const value = record[key];
+  return typeof value === "string" && value.trim() ? value.trim() : fallback;
+}
+function rawObject(record) {
+  const raw = record.raw;
+  return raw && typeof raw === "object" && !Array.isArray(raw) ? raw : {};
+}
+function truncate(value, width) {
+  if (value.length <= width)
+    return value;
+  if (width <= 1)
+    return "\u2026";
+  return `${value.slice(0, width - 1)}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function statusColor(status) {
+  const normalized = status.toLowerCase();
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected", "approved"].includes(normalized))
+    return pc2.green;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error", "rejected"].includes(normalized))
+    return pc2.red;
+  if (["running", "reviewing", "validating", "in_progress", "in-progress", "remote"].includes(normalized))
+    return pc2.cyan;
+  if (["ready", "open", "queued", "created", "preparing", "local", "pending"].includes(normalized))
+    return pc2.yellow;
+  return pc2.dim;
+}
+function compactDate(value) {
+  if (!value.trim())
+    return "";
+  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 = stringField(record, key);
+    if (value)
+      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 shouldUseClackOutput() {
+  return Boolean(process.stdout.isTTY) && process.env.RIG_CLI_PLAIN_HELP !== "1";
+}
+function printFormattedOutput(message, options = {}) {
+  if (!shouldUseClackOutput()) {
+    console.log(message);
+    return;
+  }
+  if (options.title)
+    note(message, options.title);
+  else
+    log.message(message);
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc2.bold(pc2.cyan("\u25C6"))} ${pc2.bold(title)}${subtitle ? pc2.dim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${pc2.dim("\u2502")} ${pc2.dim(key.padEnd(12))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc2.bold("Next"), ...steps.map((step) => `${pc2.dim("\u203A")} ${step}`)];
+}
+function formatRunList(runs, options = {}) {
+  if (runs.length === 0) {
+    return [
+      formatSection("Runs", "none recorded"),
+      options.source === "server" ? pc2.dim("No runs recorded on the selected Rig server.") : pc2.dim("No runs recorded in .rig/runs."),
+      "",
+      ...formatNextSteps(["Start one: `rig task run --next`", "Check server: `rig server status`"])
+    ].join(`
+`);
+  }
+  const rows = runs.map((run) => {
+    const runId = stringField(run, "runId", stringField(run, "id", "(unknown-run)"));
+    const status = stringField(run, "status", "unknown");
+    const taskId = stringField(run, "taskId", "");
+    const title = stringField(run, "title", taskId || "(untitled)");
+    const runtime = stringField(run, "runtimeAdapter", "");
+    return { runId, status, title, runtime };
+  });
+  const idWidth = Math.min(36, Math.max(6, ...rows.map((row) => row.runId.length)));
+  const statusWidth = Math.min(16, Math.max(6, ...rows.map((row) => row.status.length)));
+  const header = `${pc2.bold(pad("RUN", idWidth))}  ${pc2.bold(pad("STATUS", statusWidth))}  ${pc2.bold("TITLE")}`;
+  const body = rows.map((row) => [
+    pc2.bold(pad(truncate(row.runId, idWidth), idWidth)),
+    statusColor(row.status)(pad(truncate(row.status, statusWidth), statusWidth)),
+    `${row.title}${row.runtime ? pc2.dim(`  ${row.runtime}`) : ""}`
+  ].join("  "));
+  return [formatSection("Runs", options.source === "server" ? "selected server" : "local state"), header, ...body, "", ...formatNextSteps(["Follow live: `rig run attach <run-id> --follow`", "Details: `rig run show <run-id>`"])].join(`
+`);
+}
+function formatRunCard(run, options = {}) {
+  const raw = rawObject(run);
+  const merged = { ...raw, ...run };
+  const runId = runIdOf(merged);
+  const status = firstString(merged, ["status"], "unknown");
+  const taskId = taskIdOf(merged);
+  const title = runTitleOf(merged);
+  const runtime = firstString(merged, ["runtimeAdapter", "runtime", "adapter"]);
+  const mode = firstString(merged, ["runtimeMode", "mode"]);
+  const interaction = firstString(merged, ["interactionMode"]);
+  const created = compactDate(firstString(merged, ["createdAt"]));
+  const started = compactDate(firstString(merged, ["startedAt"]));
+  const updated = compactDate(firstString(merged, ["updatedAt"]));
+  const completed = compactDate(firstString(merged, ["completedAt", "finishedAt"]));
+  const worktree = firstString(merged, ["worktreePath", "cwd", "projectRoot"]);
+  const piSession = merged.piSession && typeof merged.piSession === "object" && !Array.isArray(merged.piSession) ? firstString(merged.piSession, ["sessionId", "id"]) : "";
+  const timeline = Array.isArray(merged.timeline) ? merged.timeline.length : null;
+  const approvals = Array.isArray(merged.approvals) ? merged.approvals.length : null;
+  const inputs = Array.isArray(merged.userInputs) ? merged.userInputs.length : null;
+  const rows = [
+    ["run", pc2.bold(runId)],
+    ["status", formatStatusPill(status)],
+    ["task", taskId],
+    ["title", title],
+    ["runtime", [runtime, mode, interaction].filter(Boolean).join(" \xB7 ")],
+    ["created", created],
+    ["started", started],
+    ["updated", updated],
+    ["completed", completed],
+    ["worktree", worktree],
+    ["pi", piSession],
+    ["timeline", timeline],
+    ["approvals", approvals],
+    ["inputs", inputs]
+  ];
+  return [
+    formatSuccessCard(options.title ?? "Run details", rows),
+    "",
+    ...formatNextSteps([`Follow live: \`rig run attach ${runId} --follow\``, `Raw payload: \`rig run show ${runId} --raw\``])
+  ].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("", pc2.bold(`Active runs (${activeRuns.length})`));
+  if (activeRuns.length === 0) {
+    lines.push(pc2.dim("No active runs."));
+  } else {
+    for (const run of activeRuns) {
+      lines.push(formatRunSummaryLine(run));
+    }
+  }
+  lines.push("", pc2.bold(`Recent runs (${recentRuns.length})`));
+  if (recentRuns.length === 0) {
+    lines.push(pc2.dim("No recent terminal runs."));
+  } else {
+    for (const run of recentRuns.slice(0, 10)) {
+      lines.push(formatRunSummaryLine(run));
+    }
+  }
+  lines.push("", ...formatNextSteps(["Start work: `rig task run --next`", "Attach: `rig run attach <run-id> --follow`", "Details: `rig run show <run-id>`"]));
+  return lines.join(`
+`);
+}
+function formatRunSummaryLine(run) {
+  const record = run;
+  const runId = runIdOf(record);
+  const status = firstString(record, ["status"], "unknown");
+  const taskId = taskIdOf(record);
+  const title = runTitleOf(record);
+  const runtime = firstString(record, ["runtimeAdapter", "runtime", "adapter"]);
+  const descriptor = [taskId, title].filter(Boolean).join(" \xB7 ");
+  return `${pc2.dim("\u2502")} ${pc2.bold(runId)} ${formatStatusPill(status)} ${descriptor}${runtime ? pc2.dim(`  ${runtime}`) : ""}`;
+}
+
+// packages/cli/src/commands/inbox.ts
+async function listInboxRecords(context, kind, filters) {
+  const params = new URLSearchParams;
+  if (filters.run)
+    params.set("runId", filters.run);
+  if (filters.task)
+    params.set("taskId", filters.task);
+  const query = params.size > 0 ? `?${params.toString()}` : "";
+  const payload = await requestServerJson(context, `/api/inbox/${kind}${query}`);
+  const records = Array.isArray(payload) ? payload : [];
+  return filters.pendingOnly ? records.filter((entry) => (entry.status ?? "pending") !== "resolved") : records;
+}
+async function readPendingInboxCounts(context) {
+  try {
+    const [approvals, inputs] = await Promise.all([
+      listInboxRecords(context, "approvals", { pendingOnly: true }),
+      listInboxRecords(context, "inputs", { pendingOnly: true })
+    ]);
+    return { approvals: approvals.length, inputs: inputs.length };
+  } catch {
+    return null;
+  }
+}
+async function printPendingInboxFooter(context) {
+  if (context.outputMode !== "text")
+    return;
+  const counts = await readPendingInboxCounts(context);
+  if (!counts || counts.approvals === 0 && counts.inputs === 0)
+    return;
+  const parts = [];
+  if (counts.approvals > 0)
+    parts.push(`${counts.approvals} approval${counts.approvals === 1 ? "" : "s"}`);
+  if (counts.inputs > 0)
+    parts.push(`${counts.inputs} input request${counts.inputs === 1 ? "" : "s"}`);
+  console.log(`
+\u26A0 ${parts.join(" and ")} pending \u2014 run \`rig inbox\` to review.`);
+}
+
 // packages/cli/src/commands/run.ts
 function normalizeRemoteRunDetails(payload) {
   const run = payload.run;
@@ -418,6 +1338,22 @@ function normalizeRemoteRunDetails(payload) {
     ...Array.isArray(payload.userInputs) ? { userInputs: payload.userInputs } : {}
   };
 }
+var REMOTE_TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged"]);
+async function listRunsForSelectedConnection(context, options = {}) {
+  if (isRemoteConnectionSelected(context.projectRoot)) {
+    return { runs: await listRunsViaServer(context, options), source: "server" };
+  }
+  return { runs: listAuthorityRuns(context.projectRoot), source: "local" };
+}
+function runStringField(run, key, fallback = "") {
+  const value = run[key];
+  return typeof value === "string" && value.trim() ? value : fallback;
+}
+function buildServerRunStatus(runs) {
+  const activeRuns = runs.filter((run) => !REMOTE_TERMINAL_RUN_STATUSES.has(runStringField(run, "status").toLowerCase()));
+  const recentRuns = runs.filter((run) => REMOTE_TERMINAL_RUN_STATUSES.has(runStringField(run, "status").toLowerCase()));
+  return { activeRuns, recentRuns, runs };
+}
 function shouldPromptForEpicSelection(context, command, promptEpic, noEpicPrompt) {
   if (noEpicPrompt) {
     return false;
@@ -438,7 +1374,7 @@ async function promptForEpicSelection(projectRoot, command) {
     options.unshift(defaultEpic);
   }
   if (options.length === 0) {
-    throw new CliError2("No open epic found. Pass --epic <id>.");
+    throw new CliError("No open epic found. Pass --epic <id>.", 1, { hint: "Re-run with `rig run start --epic <id>`." });
   }
   console.log(`Select epic for run ${command}:`);
   options.forEach((id, index) => {
@@ -460,7 +1396,7 @@ async function promptForEpicSelection(projectRoot, command) {
         return fallback ?? options[0];
       }
       if (answer === "q" || answer === "quit") {
-        throw new CliError2("Run cancelled by user.");
+        throw new CliError("Run cancelled by user.");
       }
       if (/^\d+$/.test(answer)) {
         const index = Number.parseInt(answer, 10) - 1;
@@ -479,21 +1415,16 @@ async function promptForEpicSelection(projectRoot, command) {
 }
 async function executeRun(context, args) {
   const [command = "status", ...rest] = args;
-  const runtimeContext = loadRuntimeContextFromEnv2() ?? undefined;
+  const runtimeContext = loadRuntimeContextFromEnv() ?? undefined;
   switch (command) {
     case "list": {
-      requireNoExtraArgs(rest, "bun run rig run list");
-      const runs = listAuthorityRuns(context.projectRoot);
+      requireNoExtraArgs(rest, "rig run list");
+      const { runs, source } = isRemoteConnectionSelected(context.projectRoot) ? await withSpinner("Reading runs from server\u2026", () => listRunsForSelectedConnection(context, { limit: 100 }), { outputMode: context.outputMode }) : await listRunsForSelectedConnection(context, { limit: 100 });
       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}`);
-          }
-        }
+        printFormattedOutput(formatRunList(runs, { source }));
+        await printPendingInboxFooter(context);
       }
-      return { ok: true, group: "run", command, details: { runs } };
+      return { ok: true, group: "run", command, details: { runs, source } };
     }
     case "delete": {
       let pending = rest;
@@ -501,9 +1432,9 @@ async function executeRun(context, args) {
       pending = run.rest;
       const purgeArtifacts = takeFlag(pending, "--purge-artifacts");
       pending = purgeArtifacts.rest;
-      requireNoExtraArgs(pending, "bun run rig run delete --run <id> [--purge-artifacts]");
+      requireNoExtraArgs(pending, "rig run delete --run <id> [--purge-artifacts]");
       if (!run.value) {
-        throw new CliError2("run delete requires --run <id>.");
+        throw new CliError("run delete requires --run <id>.", 1, { hint: "Run `rig run list` to find run ids, then `rig run delete --run <run-id>`." });
       }
       const result = await deleteRunState(context.projectRoot, {
         runId: run.value,
@@ -531,9 +1462,9 @@ async function executeRun(context, args) {
       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]");
+      requireNoExtraArgs(pending, "rig run cleanup --all [--keep-artifacts] [--keep-runtimes] [--keep-queue]");
       if (!all.value) {
-        throw new CliError2("run cleanup currently requires --all.");
+        throw new CliError("run cleanup currently requires --all.", 1, { hint: "Run `rig run cleanup --all` (add --keep-artifacts/--keep-runtimes/--keep-queue to retain state)." });
       }
       const result = await cleanupRunState(context.projectRoot, {
         includeArtifacts: !keepArtifacts.value,
@@ -550,20 +1481,25 @@ async function executeRun(context, args) {
     }
     case "show": {
       let pending = rest;
+      const rawResult = takeFlag(pending, "--raw");
+      pending = rawResult.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 positionalRunId = pending.length > 0 && pending[0] && !pending[0].startsWith("-") ? pending[0] : undefined;
+      const extra = positionalRunId ? pending.slice(1) : pending;
+      requireNoExtraArgs(extra, "rig run show <id>|--run <id> [--raw]");
+      const runId = run.value ?? positionalRunId;
+      if (!runId) {
+        throw new CliError("run show requires a run id.", 1, { hint: "Run `rig run list` to find run ids, then `rig run show <run-id>`." });
       }
-      const record = readAuthorityRun(context.projectRoot, run.value) ?? normalizeRemoteRunDetails(await getRunDetailsViaServer(context, run.value).catch(() => ({})));
+      const record = readAuthorityRun2(context.projectRoot, runId) ?? normalizeRemoteRunDetails(await withSpinner(`Reading run ${runId} from server\u2026`, () => getRunDetailsViaServer(context, runId).catch(() => ({})), { outputMode: context.outputMode }));
       if (!record) {
-        throw new CliError2(`Run not found: ${run.value}`, 2);
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see recorded runs." });
       }
       if (context.outputMode === "text") {
-        console.log(JSON.stringify(record, null, 2));
+        printFormattedOutput(rawResult.value ? JSON.stringify(record, null, 2) : formatRunCard(record));
       }
-      return { ok: true, group: "run", command, details: record };
+      return { ok: true, group: "run", command, details: { ...record, rawOutput: rawResult.value } };
     }
     case "timeline": {
       let pending = rest;
@@ -571,38 +1507,69 @@ async function executeRun(context, args) {
       pending = run.rest;
       const follow = takeFlag(pending, "--follow");
       pending = follow.rest;
-      requireNoExtraArgs(pending, "bun run rig run timeline --run <id> [--follow]");
+      requireNoExtraArgs(pending, "rig run timeline --run <id> [--follow]");
       if (!run.value) {
-        throw new CliError2("run timeline requires --run <id>.");
+        throw new CliError("run timeline requires --run <id>.", 1, { hint: "Run `rig run list` to find run ids, then `rig run timeline --run <run-id>`." });
+      }
+      const renderer = createPiRunStreamRenderer();
+      let cursor = null;
+      const timelineRunId = run.value;
+      const page = await withSpinner(`Reading timeline for ${timelineRunId}\u2026`, () => getRunTimelineViaServer(context, timelineRunId, { limit: 500 }), { outputMode: context.outputMode });
+      const events = Array.isArray(page.entries) ? page.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+      cursor = typeof page.nextCursor === "string" ? page.nextCursor : null;
+      if (context.outputMode === "text") {
+        renderer.renderTimeline(events);
       }
-      const timelinePath = resolve3(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 = existsSync3(timelinePath) ? readFileSync3(timelinePath, "utf8").length : 0;
         while (true) {
           await Bun.sleep(1000);
-          if (!existsSync3(timelinePath))
-            continue;
-          const next = readFileSync3(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);
-          }
+          const nextPage = await getRunTimelineViaServer(context, run.value, { limit: 500, ...cursor ? { cursor } : {} });
+          const nextEvents = Array.isArray(nextPage.entries) ? nextPage.entries.filter((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry))) : [];
+          cursor = typeof nextPage.nextCursor === "string" ? nextPage.nextCursor : cursor;
+          renderer.renderTimeline(nextEvents);
         }
       }
-      return { ok: true, group: "run", command, details: { runId: run.value, events } };
+      return { ok: true, group: "run", command, details: { runId: run.value, events, cursor } };
+    }
+    case "replay": {
+      let pending = rest;
+      const run = takeOption(pending, "--run");
+      pending = run.rest;
+      const withSession = takeFlag(pending, "--with-session");
+      pending = withSession.rest;
+      const positionalRunId = pending.length > 0 && pending[0] && !pending[0].startsWith("-") ? pending[0] : undefined;
+      const extra = positionalRunId ? pending.slice(1) : pending;
+      requireNoExtraArgs(extra, "rig run replay <id>|--run <id> [--with-session]");
+      const runId = run.value ?? positionalRunId;
+      if (!runId) {
+        throw new CliError("run replay requires a run id.", 2, { hint: "Run `rig run list` to find run ids, then `rig run replay <run-id>`." });
+      }
+      const replay = buildRunReplay(context.projectRoot, runId, { withSession: withSession.value });
+      if (replay.entryCount === 0 && replay.sessionEntryCount === 0) {
+        throw new CliError(`No run.jsonl lifecycle log found for ${runId} (looked at ${replay.logPath}).`, 2, { hint: "Run `rig run list` to confirm the run id; older runs may predate consolidated run.jsonl logging." });
+      }
+      if (context.outputMode === "text") {
+        console.log(`Replay of ${runId} (${replay.entryCount} lifecycle entries${withSession.value ? `, ${replay.sessionEntryCount} session entries` : ""}):`);
+        for (const line of replay.lines) {
+          console.log(line);
+        }
+        if (withSession.value && !replay.sessionFile) {
+          console.log("(no Pi session file resolvable from the run record; showing run.jsonl only)");
+        }
+      }
+      return {
+        ok: true,
+        group: "run",
+        command,
+        details: {
+          runId,
+          logPath: replay.logPath,
+          sessionFile: replay.sessionFile,
+          entryCount: replay.entryCount,
+          sessionEntryCount: replay.sessionEntryCount,
+          lines: replay.lines
+        }
+      };
     }
     case "attach": {
       let pending = rest;
@@ -618,41 +1585,40 @@ async function executeRun(context, args) {
       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>]");
+      requireNoExtraArgs(extra, "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);
+        throw new CliError("run attach requires a run id.", 2, { hint: "Run `rig run list` to find run ids, then `rig run attach <run-id> --follow`." });
+      }
+      let steered = false;
+      const steerMessage = messageOption.value?.trim();
+      if (steerMessage) {
+        await withSpinner("Queueing steering message\u2026", () => steerRunViaServer(context, runId, steerMessage), { outputMode: context.outputMode });
+        steered = true;
       }
       const attached = await attachRunOperatorView(context, {
         runId,
-        message: messageOption.value ?? null,
+        message: null,
         once: once.value,
         follow: follow.value,
         pollMs: parsePositiveInt(pollMs.value, "--poll-ms", 2000)
       });
-      return { ok: true, group: "run", command, details: attached };
+      return { ok: true, group: "run", command, details: { ...attached, steered: attached.steered || steered } };
     }
     case "status": {
-      requireNoExtraArgs(rest, "bun run rig run status");
+      requireNoExtraArgs(rest, "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);
+      const summary = isRemoteConnectionSelected(context.projectRoot) ? buildServerRunStatus(await withSpinner("Reading run status from server\u2026", () => listRunsViaServer(context, { limit: 100 }), { outputMode: context.outputMode })) : runStatus(context.projectRoot, runtimeContext);
+      const activeRuns = Array.isArray(summary.activeRuns) ? summary.activeRuns.filter((run) => Boolean(run && typeof run === "object" && !Array.isArray(run))) : [];
+      const recentRuns = Array.isArray(summary.recentRuns) ? summary.recentRuns.filter((run) => Boolean(run && typeof run === "object" && !Array.isArray(run))) : [];
       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}`);
-          }
-        }
+        printFormattedOutput(formatRunStatus({ activeRuns, recentRuns, runs: Array.isArray(summary.runs) ? summary.runs : [...activeRuns, ...recentRuns] }, { source: isRemoteConnectionSelected(context.projectRoot) ? "server" : "local" }));
+        await printPendingInboxFooter(context);
       }
       return { ok: true, group: "run", command, details: summary };
     }
@@ -676,12 +1642,12 @@ async function executeRun(context, args) {
       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]");
+      requireNoExtraArgs(pending, "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.");
+        throw new CliError("Cannot use --prompt-epic and --no-epic-prompt together.", 1, { hint: "Pass only one of --prompt-epic or --no-epic-prompt." });
       }
       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.");
+        throw new CliError("--prompt-epic requires an interactive terminal (TTY) in text mode.", 1, { hint: "Pass the epic explicitly instead: `rig run start --epic <id>`." });
       }
       let resolvedEpicId = epicResult.value || undefined;
       if (!resolvedEpicId && shouldPromptForEpicSelection(context, command, promptEpicResult.value, noEpicPromptResult.value)) {
@@ -709,7 +1675,7 @@ async function executeRun(context, args) {
         console.log(`Runs: ${result.runIds.join(", ")}`);
       }
       if (result.exitCode !== 0) {
-        throw new CliError2(`run ${command} failed with exit code ${result.exitCode}.`, result.exitCode);
+        throw new CliError(`run ${command} failed with exit code ${result.exitCode}.`, result.exitCode, { hint: "Inspect with `rig run status` and `rig inspect logs --task <id>`." });
       }
       return {
         ok: true,
@@ -724,38 +1690,76 @@ async function executeRun(context, args) {
       };
     }
     case "resume": {
-      requireNoExtraArgs(rest, "bun run rig run resume");
+      let pending = rest;
+      const runOpt = takeOption(pending, "--run");
+      pending = runOpt.rest;
+      const positional = pending[0] && !pending[0].startsWith("-") ? pending.shift() : undefined;
+      requireNoExtraArgs(pending, "rig run resume [<run-id>] [--run <id>]");
+      const targetRunId = runOpt.value ?? positional ?? null;
       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);
+      const resumed = await withSpinner(targetRunId ? `Resuming run ${targetRunId}\u2026` : "Resuming latest resumable run\u2026", () => resumeRunViaServer(context, targetRunId, { restart: false }), { outputMode: context.outputMode });
       if (context.outputMode === "text") {
         console.log(`Resumed run: ${resumed.runId}`);
       }
       return { ok: true, group: "run", command, details: resumed };
     }
     case "restart": {
-      requireNoExtraArgs(rest, "bun run rig run restart");
+      let pending = rest;
+      const runOpt = takeOption(pending, "--run");
+      pending = runOpt.rest;
+      const positional = pending[0] && !pending[0].startsWith("-") ? pending.shift() : undefined;
+      requireNoExtraArgs(pending, "rig run restart [<run-id>] [--run <id>]");
+      const targetRunId = runOpt.value ?? positional ?? null;
       if (context.dryRun) {
         if (context.outputMode === "text") {
           console.log("[dry-run] rig run restart");
         }
         return { ok: true, group: "run", command };
       }
-      const restarted = await runRestart(context.projectRoot, runtimeContext);
+      const restarted = await withSpinner(targetRunId ? `Restarting run ${targetRunId}\u2026` : "Restarting latest run\u2026", () => resumeRunViaServer(context, targetRunId, { restart: true }), { outputMode: context.outputMode });
       if (context.outputMode === "text") {
         console.log(`Restarted run: ${restarted.runId}`);
       }
       return { ok: true, group: "run", command, details: restarted };
     }
+    case "steer": {
+      const runOption = takeOption(rest, "--run");
+      const messageOption = takeOption(runOption.rest, "--message");
+      const shortMessageOption = takeOption(messageOption.rest, "-m");
+      const positionalRunId = shortMessageOption.rest.length > 0 ? shortMessageOption.rest[0] : undefined;
+      const extra = positionalRunId ? shortMessageOption.rest.slice(1) : shortMessageOption.rest;
+      requireNoExtraArgs(extra, "rig run steer [<run-id>|--run <id>] --message <text>");
+      const runId = runOption.value ?? positionalRunId;
+      const message = messageOption.value ?? shortMessageOption.value;
+      if (!runId) {
+        throw new CliError("run steer requires a run id (positional or --run <id>).", 2, { hint: "Run `rig run list` to find run ids, then `rig run steer <run-id> --message <text>`." });
+      }
+      if (!message?.trim()) {
+        throw new CliError("run steer requires --message <text>.", 2, { hint: 'Re-run as `rig run steer <run-id> --message "your steering note"`.' });
+      }
+      if (context.dryRun) {
+        if (context.outputMode === "text") {
+          console.log(`[dry-run] rig run steer ${runId} --message ${JSON.stringify(message)}`);
+        }
+        return { ok: true, group: "run", command, details: { runId, dryRun: true } };
+      }
+      const trimmedMessage = message.trim();
+      await withSpinner("Queueing steering message\u2026", () => steerRunViaServer(context, runId, trimmedMessage), { outputMode: context.outputMode });
+      if (context.outputMode === "text") {
+        console.log(`Steering message queued for ${runId}.`);
+      }
+      return { ok: true, group: "run", command, details: { runId, queued: true } };
+    }
     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>]");
+      requireNoExtraArgs(extra, "rig run stop [<run-id>|--run <id>]");
       const runId = runOption.value ?? positionalRunId;
       if (context.dryRun) {
         return {
@@ -766,14 +1770,14 @@ async function executeRun(context, args) {
         };
       }
       if (runId) {
-        const stopped = await stopRunViaServer(context, runId);
+        const stopped = await withSpinner(`Requesting stop for ${runId}\u2026`, () => stopRunViaServer(context, runId), { outputMode: context.outputMode });
         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);
+        throw new CliError(`Failed to stop run(s): ${result.remaining.join(", ")}`, 1, { hint: "Check `rig run status`, then retry `rig run stop <run-id>` for the remaining runs." });
       }
       if (context.outputMode === "text") {
         console.log(`Stopped process count: ${result.stopped}`);
@@ -789,7 +1793,7 @@ async function executeRun(context, args) {
       };
     }
     default:
-      throw new CliError2(`Unknown run command: ${command}`);
+      throw new CliError(`Unknown run command: ${command}`, 1, { hint: "Run `rig run --help` to list available run commands." });
   }
 }
 export {