@h-rig/cli 0.0.6-alpha.64 → 0.0.6-alpha.65

package/dist/src/commands/run.js

@@ -4,10 +4,19 @@ 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 { 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;
@@ -28,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;
@@ -73,7 +82,7 @@ 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;
 }
@@ -105,7 +114,7 @@ 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) {
@@ -169,7 +178,7 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server 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, serverProjectRoot: repo.serverProjectRoot };
 }
@@ -242,7 +251,7 @@ async function ensureServerForCli(projectRoot) {
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
@@ -292,15 +301,64 @@ 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 headers = mergeHeaders(init.headers, server.authToken);
   if (server.serverProjectRoot)
     headers.set("x-rig-project-root", server.serverProjectRoot);
-  const response = await fetch(`${server.baseUrl}${pathname}`, {
-    ...init,
-    headers
-  });
+  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 {
@@ -312,7 +370,9 @@ 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;
 }
@@ -362,26 +422,6 @@ async function steerRunViaServer(context, runId, message) {
   });
   return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { ok: true };
 }
-async function getRunPiSessionViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi`);
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
-}
-async function getRunPiMessagesViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/messages`);
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { messages: [] };
-}
-async function getRunPiStatusViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/status`);
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
-}
-async function getRunPiCommandsViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/commands`);
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { commands: [] };
-}
-async function getRunPiCapabilitiesViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/capabilities`);
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { capabilities: null };
-}
 async function sendRunPiPromptViaServer(context, runId, text, streamingBehavior) {
   const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/prompt`, {
     method: "POST",
@@ -390,44 +430,6 @@ async function sendRunPiPromptViaServer(context, runId, text, streamingBehavior)
   });
   return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { accepted: true };
 }
-async function sendRunPiShellViaServer(context, runId, text) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/shell`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ text })
-  });
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { accepted: true };
-}
-async function runRunPiCommandViaServer(context, runId, text) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/commands/run`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ text })
-  });
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { type: "done" };
-}
-async function respondRunPiExtensionUiViaServer(context, runId, requestId, valueOrCancel) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/extension-ui/respond`, {
-    method: "POST",
-    headers: { "content-type": "application/json" },
-    body: JSON.stringify({ requestId, ...valueOrCancel })
-  });
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { accepted: true };
-}
-async function abortRunPiViaServer(context, runId) {
-  const payload = await requestServerJson(context, `/api/runs/${encodeURIComponent(runId)}/pi/abort`, { method: "POST" });
-  return payload && typeof payload === "object" && !Array.isArray(payload) ? payload : { aborted: true };
-}
-async function buildRunPiEventsWebSocketUrl(context, runId) {
-  const server = await ensureServerForCli(context.projectRoot);
-  const url = new URL(`${server.baseUrl.replace(/\/+$/, "")}/api/runs/${encodeURIComponent(runId)}/pi/events`);
-  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
-  if (server.authToken)
-    url.searchParams.set("token", server.authToken);
-  if (server.serverProjectRoot)
-    url.searchParams.set("rigProjectRoot", server.serverProjectRoot);
-  return url.toString();
-}
 
 // packages/cli/src/commands/_run-replay.ts
 import { existsSync as existsSync3, readdirSync } from "fs";
@@ -435,7 +437,7 @@ import { join, resolve as resolve3 } from "path";
 import {
   readAuthorityRun,
   readJsonlFile,
-  runLifecycleLogPath
+  runJournalPath
 } from "@rig/runtime/control-plane/authority-files";
 function asRecord(value) {
   return value && typeof value === "object" && !Array.isArray(value) ? value : null;
@@ -533,7 +535,7 @@ function resolveRunSessionFile(record) {
   }
 }
 function buildRunReplay(projectRoot, runId, options = {}) {
-  const logPath = runLifecycleLogPath(projectRoot, runId);
+  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) => ({
@@ -763,684 +765,8 @@ function createOperatorSurface(options = {}) {
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join as join2 } from "path";
-import {
-  createAgentSessionFromServices,
-  createAgentSessionServices,
-  main as runPiMain
-} from "@earendil-works/pi-coding-agent";
-
-// packages/cli/src/commands/_pi-remote-session.ts
-import { AgentSession as PiAgentSession, expandPromptTemplate } from "@earendil-works/pi-coding-agent";
-var TERMINAL_RUN_STATUSES = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
-function defaultTransport() {
-  return {
-    getSession: getRunPiSessionViaServer,
-    getMessages: getRunPiMessagesViaServer,
-    getStatus: getRunPiStatusViaServer,
-    getCommands: getRunPiCommandsViaServer,
-    getCapabilities: getRunPiCapabilitiesViaServer,
-    sendPrompt: sendRunPiPromptViaServer,
-    sendShell: sendRunPiShellViaServer,
-    runCommand: runRunPiCommandViaServer,
-    abort: abortRunPiViaServer,
-    buildEventsWebSocketUrl: buildRunPiEventsWebSocketUrl
-  };
-}
-function recordOf(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function emptyRemoteStatus() {
-  return {
-    isStreaming: false,
-    isCompacting: false,
-    isBashRunning: false,
-    pendingMessageCount: 0,
-    steeringMessages: [],
-    followUpMessages: [],
-    model: null,
-    thinkingLevel: null,
-    sessionName: null,
-    cwd: null,
-    stats: null,
-    contextUsage: null
-  };
-}
-function resolveAttachReadyTimeoutMs() {
-  const raw = Number.parseInt(process.env.RIG_PI_ATTACH_TIMEOUT_MS ?? "", 10);
-  return Number.isFinite(raw) && raw > 0 ? raw : 10 * 60000;
-}
-
-class RigRemoteSessionController {
-  context;
-  runId;
-  status = emptyRemoteStatus();
-  transport;
-  hooks = {};
-  session = null;
-  socket = null;
-  closed = false;
-  pendingShells = [];
-  pendingCompactions = [];
-  constructor(input) {
-    this.context = input.context;
-    this.runId = input.runId;
-    this.transport = input.transport ?? defaultTransport();
-  }
-  ingestEnvelope(envelopeValue) {
-    this.applyEnvelope(envelopeValue);
-  }
-  bindSession(session) {
-    this.session = session;
-  }
-  setUiHooks(hooks) {
-    this.hooks = hooks;
-  }
-  async connect() {
-    const ready = await this.waitForReady();
-    if (!ready || this.closed)
-      return;
-    let catchupDone = false;
-    const buffered = [];
-    const wsUrl = await this.transport.buildEventsWebSocketUrl(this.context, this.runId);
-    const socket = new WebSocket(wsUrl);
-    this.socket = socket;
-    socket.onopen = () => {
-      this.hooks.onConnectionChange?.(true);
-      this.hooks.onStatusText?.("worker session live");
-    };
-    socket.onmessage = (message) => {
-      try {
-        const payload = typeof message.data === "string" ? JSON.parse(message.data) : JSON.parse(Buffer.from(message.data).toString("utf8"));
-        if (!catchupDone)
-          buffered.push(payload);
-        else
-          this.applyEnvelope(payload);
-      } catch (error) {
-        this.hooks.onError?.(`Unparseable worker Pi event: ${error instanceof Error ? error.message : String(error)}`);
-      }
-    };
-    socket.onerror = () => socket.close();
-    socket.onclose = () => {
-      this.hooks.onConnectionChange?.(false);
-      if (!this.closed)
-        this.hooks.onStatusText?.("worker Pi WebSocket disconnected");
-    };
-    try {
-      const [messagesPayload, statusPayload, commandsPayload, capabilitiesPayload] = await Promise.all([
-        this.transport.getMessages(this.context, this.runId),
-        this.transport.getStatus(this.context, this.runId),
-        this.transport.getCommands(this.context, this.runId),
-        this.transport.getCapabilities(this.context, this.runId).catch(() => ({ capabilities: null }))
-      ]);
-      const messages = Array.isArray(messagesPayload.messages) ? messagesPayload.messages : [];
-      this.applyStatusPayload(statusPayload);
-      this.session?.replaceRemoteMessages(messages);
-      const commands = Array.isArray(commandsPayload.commands) ? commandsPayload.commands : [];
-      const capabilities = capabilitiesPayload.capabilities && typeof capabilitiesPayload.capabilities === "object" && !Array.isArray(capabilitiesPayload.capabilities) ? capabilitiesPayload.capabilities : null;
-      this.hooks.onCatchUp?.(messages, commands, capabilities);
-      catchupDone = true;
-      for (const payload of buffered.splice(0))
-        this.applyEnvelope(payload);
-    } catch (error) {
-      catchupDone = true;
-      this.hooks.onError?.(`Worker Pi catch-up failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  close() {
-    this.closed = true;
-    this.socket?.close();
-    for (const shell of this.pendingShells.splice(0))
-      shell.reject(new Error("Remote session closed."));
-    for (const compaction of this.pendingCompactions.splice(0))
-      compaction.reject(new Error("Remote session closed."));
-  }
-  async sendPrompt(text2, streamingBehavior) {
-    await this.transport.sendPrompt(this.context, this.runId, text2, streamingBehavior);
-  }
-  async sendCommand(text2) {
-    const result = await this.transport.runCommand(this.context, this.runId, text2);
-    return typeof result.message === "string" ? result.message : "worker command accepted";
-  }
-  async sendShell(text2) {
-    await this.transport.sendShell(this.context, this.runId, text2);
-  }
-  async abort() {
-    await this.transport.abort(this.context, this.runId);
-  }
-  registerPendingShell(shell) {
-    this.pendingShells.push(shell);
-  }
-  failPendingShell(shell, error) {
-    const index = this.pendingShells.indexOf(shell);
-    if (index !== -1)
-      this.pendingShells.splice(index, 1);
-    shell.reject(error);
-  }
-  registerPendingCompaction(pending) {
-    this.pendingCompactions.push(pending);
-  }
-  async waitForReady() {
-    const startedAt = Date.now();
-    const deadline = startedAt + resolveAttachReadyTimeoutMs();
-    let consecutiveFailures = 0;
-    while (!this.closed) {
-      let requestFailed = false;
-      const session = await this.transport.getSession(this.context, this.runId).catch((error) => {
-        requestFailed = true;
-        return { ready: false, status: error instanceof Error ? error.message : String(error), retryAfterMs: 1000 };
-      });
-      if (session.ready !== false)
-        return true;
-      consecutiveFailures = requestFailed ? consecutiveFailures + 1 : 0;
-      const status = String(session.status ?? "starting");
-      if (TERMINAL_RUN_STATUSES.has(status.toLowerCase())) {
-        this.hooks.onError?.(`Run ended before the worker Pi daemon became ready: ${status}. Inspect with \`rig run show ${this.runId}\`.`);
-        return false;
-      }
-      this.hooks.onStatusText?.(consecutiveFailures >= 5 ? "Rig server unreachable \xB7 retrying \xB7 /detach to exit" : `waiting for worker Pi daemon \xB7 ${status} \xB7 /detach to exit`);
-      if (Date.now() >= deadline) {
-        this.hooks.onError?.(`Worker Pi daemon did not become ready (last status: ${status}). Set RIG_PI_ATTACH_TIMEOUT_MS to wait longer.`);
-        return false;
-      }
-      await Bun.sleep(typeof session.retryAfterMs === "number" ? session.retryAfterMs : 750);
-    }
-    return false;
-  }
-  applyEnvelope(envelopeValue) {
-    const envelope = recordOf(envelopeValue);
-    if (!envelope)
-      return;
-    const type = String(envelope.type ?? "");
-    if (type === "status.update") {
-      this.applyStatusPayload(envelope);
-      return;
-    }
-    if (type === "activity.update") {
-      const activity = recordOf(envelope.activity);
-      this.hooks.onActivity?.(String(activity?.label ?? ""), activity?.detail ? String(activity.detail) : undefined);
-      return;
-    }
-    if (type === "extension_ui_request") {
-      const request = recordOf(envelope.request);
-      if (request)
-        this.hooks.onExtensionUiRequest?.(request);
-      return;
-    }
-    if (type === "pi.ui_event") {
-      this.applyShellUiEvent(envelope.event);
-      return;
-    }
-    if (type === "pi.event") {
-      this.session?.handleRemoteSessionEvent(envelope.event);
-      this.settlePendingCompaction(envelope.event);
-      return;
-    }
-    if (type === "error") {
-      this.hooks.onError?.(String(envelope.message ?? envelope.detail ?? "unknown worker error"));
-    }
-  }
-  applyStatusPayload(payload) {
-    const status = recordOf(payload.status) ?? payload;
-    const next = this.status;
-    next.isStreaming = status.isStreaming === true;
-    next.isCompacting = status.isCompacting === true;
-    next.isBashRunning = status.isBashRunning === true;
-    next.pendingMessageCount = typeof status.pendingMessageCount === "number" ? status.pendingMessageCount : 0;
-    next.steeringMessages = Array.isArray(status.steeringMessages) ? status.steeringMessages.map(String) : [];
-    next.followUpMessages = Array.isArray(status.followUpMessages) ? status.followUpMessages.map(String) : [];
-    next.model = recordOf(status.model) ?? next.model;
-    next.thinkingLevel = typeof status.thinkingLevel === "string" ? status.thinkingLevel : next.thinkingLevel;
-    next.sessionName = typeof status.sessionName === "string" ? status.sessionName : next.sessionName;
-    next.cwd = typeof status.cwd === "string" ? status.cwd : next.cwd;
-    next.stats = recordOf(status.stats) ?? next.stats;
-    next.contextUsage = recordOf(status.contextUsage) ?? next.contextUsage;
-  }
-  applyShellUiEvent(value) {
-    const event = recordOf(value);
-    if (!event)
-      return;
-    const type = String(event.type ?? "");
-    const pending = this.pendingShells[0];
-    if (type === "shell.chunk" && pending) {
-      pending.sawChunk = true;
-      pending.onData(Buffer.from(String(event.chunk ?? "")));
-      return;
-    }
-    if (type === "shell.end" && pending) {
-      const output = String(event.output ?? "");
-      if (output && !pending.sawChunk)
-        pending.onData(Buffer.from(output));
-      const index = this.pendingShells.indexOf(pending);
-      if (index !== -1)
-        this.pendingShells.splice(index, 1);
-      pending.resolve({ exitCode: typeof event.exitCode === "number" ? event.exitCode : event.isError === true ? 1 : 0 });
-    }
-  }
-  settlePendingCompaction(eventValue) {
-    const event = recordOf(eventValue);
-    if (!event)
-      return;
-    const type = String(event.type ?? "");
-    if (type !== "compaction_end" || this.pendingCompactions.length === 0)
-      return;
-    const pending = this.pendingCompactions.shift();
-    const result = recordOf(event.result);
-    if (result)
-      pending.resolve(result);
-    else if (event.aborted === true)
-      pending.reject(new Error("Compaction aborted on the worker."));
-    else
-      pending.resolve({});
-  }
-}
-
-class RigRemoteAgentSession extends PiAgentSession {
-  remote;
-  constructor(config, remote) {
-    super(config);
-    this.remote = remote;
-    remote.bindSession(this);
-  }
-  handleRemoteSessionEvent(eventValue) {
-    const event = recordOf(eventValue);
-    if (!event)
-      return;
-    const type = String(event.type ?? "");
-    if ((type === "message_end" || type === "turn_end") && recordOf(event.message)) {
-      this.agent.state.messages = [...this.agent.state.messages, event.message];
-    }
-    this._emit(eventValue);
-  }
-  replaceRemoteMessages(messages) {
-    this.agent.state.messages = messages;
-  }
-  async expandLocalInput(text2) {
-    let current = text2;
-    const runner = this.extensionRunner;
-    if (runner.hasHandlers("input")) {
-      const result = await runner.emitInput(current, undefined, "interactive");
-      if (result.action === "handled")
-        return null;
-      if (result.action === "transform")
-        current = result.text;
-    }
-    current = this._expandSkillCommand(current);
-    current = expandPromptTemplate(current, [...this.promptTemplates]);
-    return current;
-  }
-  async prompt(text2, options) {
-    const trimmed = text2.trim();
-    if (!trimmed)
-      return;
-    if (trimmed.startsWith("/")) {
-      if (await this._tryExecuteExtensionCommand(trimmed))
-        return;
-      const expanded2 = await this.expandLocalInput(trimmed);
-      if (expanded2 === null)
-        return;
-      if (expanded2 !== trimmed) {
-        const behavior2 = options?.streamingBehavior ?? (this.isStreaming || this.isCompacting ? "steer" : undefined);
-        options?.preflightResult?.(true);
-        await this.remote.sendPrompt(expanded2, behavior2);
-        return;
-      }
-      await this.remote.sendCommand(trimmed);
-      return;
-    }
-    if (trimmed.startsWith("!")) {
-      await this.remote.sendShell(trimmed);
-      return;
-    }
-    const expanded = await this.expandLocalInput(trimmed);
-    if (expanded === null)
-      return;
-    const behavior = options?.streamingBehavior ?? (this.isStreaming || this.isCompacting ? "steer" : undefined);
-    options?.preflightResult?.(true);
-    await this.remote.sendPrompt(expanded, behavior);
-  }
-  async steer(text2) {
-    const trimmed = text2.trim();
-    if (trimmed.startsWith("/") && await this._tryExecuteExtensionCommand(trimmed))
-      return;
-    const expanded = await this.expandLocalInput(trimmed);
-    if (expanded === null)
-      return;
-    await this.remote.sendPrompt(expanded, "steer");
-  }
-  async followUp(text2) {
-    const trimmed = text2.trim();
-    if (trimmed.startsWith("/") && await this._tryExecuteExtensionCommand(trimmed))
-      return;
-    const expanded = await this.expandLocalInput(trimmed);
-    if (expanded === null)
-      return;
-    await this.remote.sendPrompt(expanded, "followUp");
-  }
-  async abort() {
-    await this.remote.abort();
-  }
-  async compact(customInstructions) {
-    const pending = new Promise((resolve4, reject) => {
-      this.remote.registerPendingCompaction({ resolve: resolve4, reject });
-    });
-    await this.remote.sendCommand(`/compact${customInstructions ? ` ${customInstructions}` : ""}`);
-    return pending;
-  }
-  clearQueue() {
-    const cleared = {
-      steering: [...this.remote.status.steeringMessages],
-      followUp: [...this.remote.status.followUpMessages]
-    };
-    this.remote.status.steeringMessages = [];
-    this.remote.status.followUpMessages = [];
-    this.remote.status.pendingMessageCount = 0;
-    this.remote.sendCommand("/queue-clear").catch(() => {});
-    return cleared;
-  }
-  get isStreaming() {
-    return this.remote.status.isStreaming;
-  }
-  get isCompacting() {
-    return this.remote.status.isCompacting;
-  }
-  get isBashRunning() {
-    return this.remote.status.isBashRunning;
-  }
-  get pendingMessageCount() {
-    return this.remote.status.pendingMessageCount;
-  }
-  getSteeringMessages() {
-    return this.remote.status.steeringMessages;
-  }
-  getFollowUpMessages() {
-    return this.remote.status.followUpMessages;
-  }
-  get model() {
-    return this.remote.status.model ?? super.model;
-  }
-  async setModel(model) {
-    await this.remote.sendCommand(`/model ${model.provider}/${model.id}`);
-    this.remote.status.model = model;
-  }
-  get thinkingLevel() {
-    return this.remote.status.thinkingLevel ?? super.thinkingLevel;
-  }
-  setThinkingLevel(level) {
-    this.remote.status.thinkingLevel = level;
-    this.remote.sendCommand(`/thinking ${level}`).catch(() => {});
-  }
-  get sessionName() {
-    return this.remote.status.sessionName ?? super.sessionName;
-  }
-  setSessionName(name) {
-    this.remote.status.sessionName = name;
-    this.remote.sendCommand(`/name ${name}`).catch(() => {});
-  }
-  getSessionStats() {
-    return this.remote.status.stats ?? super.getSessionStats();
-  }
-  getContextUsage() {
-    return this.remote.status.contextUsage ?? super.getContextUsage();
-  }
-  dispose() {
-    this.remote.close();
-    super.dispose();
-  }
-}
-function createRemoteBashOperations(controller, excludeFromContext) {
-  return {
-    exec(command, _cwd, execOptions) {
-      return new Promise((resolve4, reject) => {
-        const pending = { onData: execOptions.onData, resolve: resolve4, reject, sawChunk: false };
-        const cleanup = () => {
-          execOptions.signal?.removeEventListener("abort", onAbort);
-          if (timer)
-            clearTimeout(timer);
-        };
-        const onAbort = () => {
-          cleanup();
-          controller.failPendingShell(pending, new Error("Remote worker shell command aborted locally."));
-        };
-        const timeoutMs = typeof execOptions.timeout === "number" && execOptions.timeout > 0 ? execOptions.timeout : 0;
-        const timer = timeoutMs > 0 ? setTimeout(() => {
-          cleanup();
-          controller.failPendingShell(pending, new Error(`Remote worker shell command timed out after ${timeoutMs}ms.`));
-        }, timeoutMs) : null;
-        const wrappedResolve = pending.resolve;
-        const wrappedReject = pending.reject;
-        pending.resolve = (result) => {
-          cleanup();
-          wrappedResolve(result);
-        };
-        pending.reject = (error) => {
-          cleanup();
-          wrappedReject(error);
-        };
-        execOptions.signal?.addEventListener("abort", onAbort, { once: true });
-        controller.registerPendingShell(pending);
-        controller.sendShell(`${excludeFromContext ? "!!" : "!"}${command}`).catch((error) => {
-          cleanup();
-          controller.failPendingShell(pending, error instanceof Error ? error : new Error(String(error)));
-        });
-      });
-    }
-  };
-}
-
-// packages/cli/src/commands/_spinner.ts
-var SPINNER_FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
-
-// packages/cli/src/commands/_pi-worker-bridge-extension.ts
-function recordOf2(value) {
-  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
-}
-function asText(value) {
-  if (typeof value === "string")
-    return value;
-  if (value === null || value === undefined)
-    return "";
-  if (typeof value === "number" || typeof value === "boolean")
-    return String(value);
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return String(value);
-  }
-}
-function names(value, key = "name") {
-  if (!Array.isArray(value))
-    return [];
-  return value.flatMap((entry) => {
-    if (typeof entry === "string")
-      return [entry];
-    const record = recordOf2(entry);
-    const name = record?.[key];
-    return typeof name === "string" ? [name] : [];
-  });
-}
-function renderWorkerCapabilities(capabilities) {
-  const lines = ["Worker session capabilities (in effect for this run)"];
-  const tools = Array.isArray(capabilities.tools) ? capabilities.tools : [];
-  const activeTools = tools.flatMap((tool) => {
-    const record = recordOf2(tool);
-    return record && record.active === true && typeof record.name === "string" ? [record.name] : [];
-  });
-  const inactiveCount = tools.length - activeTools.length;
-  lines.push(`  tools       ${activeTools.join(", ") || "(none)"}${inactiveCount > 0 ? `  (+${inactiveCount} inactive)` : ""}`);
-  const extensions = Array.isArray(capabilities.extensions) ? capabilities.extensions : [];
-  const extensionLabels = extensions.flatMap((entry) => {
-    const record = recordOf2(entry);
-    if (!record)
-      return [];
-    const path = typeof record.path === "string" ? record.path : "";
-    const short = path.split("/").filter(Boolean).slice(-2).join("/") || path || "extension";
-    return [short];
-  });
-  lines.push(`  extensions  ${extensionLabels.join(", ") || "(none)"}`);
-  const hookEvents = names(capabilities.hookEvents);
-  const hookList = Array.isArray(capabilities.hookEvents) ? capabilities.hookEvents.map(asText).filter(Boolean) : hookEvents;
-  lines.push(`  hooks       ${hookList.join(", ") || "(none)"}`);
-  lines.push(`  skills      ${names(capabilities.skills).join(", ") || "(none)"}`);
-  lines.push(`  prompts     ${names(capabilities.prompts).join(", ") || "(none)"}`);
-  const model = typeof capabilities.model === "string" ? capabilities.model : "(unknown)";
-  const thinking = typeof capabilities.thinkingLevel === "string" ? capabilities.thinkingLevel : "";
-  const cwd = typeof capabilities.cwd === "string" ? capabilities.cwd : "";
-  lines.push(`  model       ${model}${thinking ? ` \xB7 ${thinking}` : ""}`);
-  if (cwd)
-    lines.push(`  cwd         ${cwd}`);
-  lines.push("  (worker commands are in your palette as [worker \u2026] \xB7 /worker shows this again)");
-  return lines;
-}
-async function answerExtensionUiRequest(options, ctx, request) {
-  const requestId = String(request.requestId ?? request.id ?? `ui-${Date.now()}`);
-  const method = String(request.method ?? request.type ?? "input");
-  const prompt = asText(request.prompt ?? request.message ?? request.title ?? method);
-  const rawOptions = Array.isArray(request.options) ? request.options : Array.isArray(request.items) ? request.items : [];
-  const choices = rawOptions.map((option) => {
-    const record = recordOf2(option);
-    return record ? asText(record.label ?? record.value ?? record.name ?? option) : asText(option);
-  }).filter(Boolean);
-  try {
-    if (method === "confirm") {
-      const confirmed = await ctx.ui.confirm("Worker request", prompt);
-      await respondRunPiExtensionUiViaServer(options.context, options.runId, requestId, { value: confirmed, confirmed });
-      return;
-    }
-    if (choices.length > 0) {
-      const selected = await ctx.ui.select(prompt, choices);
-      await respondRunPiExtensionUiViaServer(options.context, options.runId, requestId, selected === undefined ? { cancelled: true } : { value: selected });
-      return;
-    }
-    const value = await ctx.ui.input("Worker request", prompt);
-    await respondRunPiExtensionUiViaServer(options.context, options.runId, requestId, value === undefined ? { cancelled: true } : { value });
-  } catch (error) {
-    ctx.ui.notify(`Failed to answer worker UI request: ${error instanceof Error ? error.message : String(error)}`, "error");
-  }
-}
-var LOCALLY_OWNED_COMMANDS = new Set(["detach", "quit", "q", "stop", "worker", "settings", "model", "thinking", "compact", "session", "name", "reload"]);
-function registerDaemonCommands(pi, options, ctx, commands, registered) {
-  for (const command of commands) {
-    const record = recordOf2(command);
-    const name = typeof record?.name === "string" ? record.name : "";
-    const source = typeof record?.source === "string" ? record.source : "worker";
-    if (!name || source === "builtin" || registered.has(name) || LOCALLY_OWNED_COMMANDS.has(name))
-      continue;
-    registered.add(name);
-    const description = typeof record?.description === "string" ? record.description : undefined;
-    try {
-      pi.registerCommand(name, {
-        description: `[worker ${source}] ${description ?? ""}`.trim(),
-        handler: async (args) => {
-          try {
-            const message = await options.controller.sendCommand(`/${name}${args ? ` ${args}` : ""}`);
-            ctx.ui.notify(message, "info");
-          } catch (error) {
-            ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-          }
-        }
-      });
-    } catch {}
-  }
-}
-function createRigWorkerPiBridgeExtension(options) {
-  return (pi) => {
-    const registeredDaemonCommands = new Set;
-    let capabilityLines = null;
-    let statusText = "connecting to worker session";
-    let busy = true;
-    let connected = false;
-    let frame = 0;
-    let spinnerTimer = null;
-    const renderStatus = (ctx) => {
-      const prefix = busy ? `${SPINNER_FRAMES[frame]} ` : connected ? "\u25CF " : "\u25CB ";
-      ctx.ui.setStatus("rig-worker-pi", `${prefix}${statusText}`);
-    };
-    const setStatus = (ctx, text2, isBusy) => {
-      statusText = text2;
-      busy = isBusy;
-      renderStatus(ctx);
-    };
-    pi.registerCommand("detach", {
-      description: "Detach from this run; the worker keeps going",
-      handler: async (_args, ctx) => {
-        ctx.ui.notify("Detached locally; the worker Pi daemon continues.", "info");
-        ctx.shutdown();
-      }
-    });
-    pi.registerCommand("stop", {
-      description: "Stop the worker Pi run and detach",
-      handler: async (_args, ctx) => {
-        await options.controller.abort();
-        ctx.ui.notify("Stop requested for the worker Pi daemon.", "info");
-        ctx.shutdown();
-      }
-    });
-    pi.registerCommand("worker", {
-      description: "Show the worker session's real capabilities (tools, extensions, hooks, skills)",
-      handler: async (_args, ctx) => {
-        if (capabilityLines)
-          ctx.ui.setWidget("rig-worker-capabilities", capabilityLines, { placement: "aboveEditor" });
-        else
-          ctx.ui.notify("Worker capabilities are not available yet (still connecting).", "info");
-      }
-    });
-    pi.on("user_bash", (event) => ({
-      operations: createRemoteBashOperations(options.controller, event.excludeFromContext === true)
-    }));
-    pi.on("session_start", async (_event, ctx) => {
-      ctx.ui.setTitle("Rig \xB7 enriched bundled Pi");
-      setStatus(ctx, "waiting for worker Pi daemon", true);
-      spinnerTimer = setInterval(() => {
-        frame = (frame + 1) % SPINNER_FRAMES.length;
-        if (busy)
-          renderStatus(ctx);
-      }, 150);
-      ctx.ui.notify(`Enriched bundled Pi \u2014 native UI + Rig layers, worker brain. Attached to run ${options.runId}. /worker shows live capabilities \xB7 /detach exits \xB7 /stop cancels.`, "info");
-      if (options.initialMessageSent)
-        ctx.ui.notify("Initial message sent to the worker Pi daemon.", "info");
-      const nativeUi = ctx.ui;
-      options.controller.setUiHooks({
-        onStatusText: (text2) => setStatus(ctx, text2, !connected),
-        onActivity: (label, detail) => {
-          const active = label !== "idle" && !/complete|ready/i.test(label);
-          setStatus(ctx, [label, detail].filter(Boolean).join(" \u2014 "), active);
-          if (/agent running|tool:/.test(label))
-            ctx.ui.setWidget("rig-worker-capabilities", undefined);
-        },
-        onConnectionChange: (nextConnected) => {
-          connected = nextConnected;
-          setStatus(ctx, nextConnected ? "worker session live" : "worker session disconnected", false);
-        },
-        onError: (message) => ctx.ui.notify(message, "error"),
-        onExtensionUiRequest: (request) => {
-          answerExtensionUiRequest(options, ctx, request);
-        },
-        onCatchUp: (messages, commands, capabilities) => {
-          if (nativeUi.appendSessionMessages)
-            nativeUi.appendSessionMessages(messages);
-          const cwd = options.controller.status.cwd;
-          if (nativeUi.setDisplayCwd && cwd)
-            nativeUi.setDisplayCwd(cwd);
-          registerDaemonCommands(pi, options, ctx, commands, registeredDaemonCommands);
-          if (capabilities) {
-            capabilityLines = renderWorkerCapabilities(capabilities);
-            ctx.ui.setWidget("rig-worker-capabilities", capabilityLines, { placement: "aboveEditor" });
-          }
-        }
-      });
-      options.controller.connect().catch((error) => {
-        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
-      });
-    });
-    pi.on("session_shutdown", () => {
-      if (spinnerTimer)
-        clearInterval(spinnerTimer);
-      options.controller.close();
-    });
-  };
-}
-
-// packages/cli/src/commands/_pi-frontend.ts
+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)) {
@@ -1456,51 +782,38 @@ function setTemporaryEnv(updates) {
     }
   };
 }
+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 restoreEnv = setTemporaryEnv({
-    PI_CODING_AGENT_SESSION_DIR: tempSessionDir,
-    PI_SKIP_VERSION_CHECK: "1",
-    PI_HIDDEN_COMMANDS: "import,fork,clone,tree,new,resume,trust"
-  });
-  const controller = new RigRemoteSessionController({ context, runId: input.runId });
-  const createRemoteRuntime = async ({ cwd, agentDir, sessionManager, sessionStartEvent }) => {
-    const services = await createAgentSessionServices({
-      cwd,
-      agentDir,
-      resourceLoaderOptions: {
-        extensionFactories: [
-          createRigWorkerPiBridgeExtension({
-            context,
-            controller,
-            runId: input.runId,
-            initialMessageSent: input.steered === true
-          })
-        ],
-        noExtensions: true,
-        noSkills: true,
-        noPromptTemplates: true,
-        noContextFiles: true
-      }
-    });
-    const created = await createAgentSessionFromServices({
-      services,
-      sessionManager,
-      sessionStartEvent,
-      noTools: "all",
-      sessionFactory: (config) => new RigRemoteAgentSession(config, controller)
-    });
-    return { ...created, services, diagnostics: services.diagnostics };
+  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([], {
-      createRuntimeOverride: () => createRemoteRuntime
+      extensionFactories: [piRigExtensionFactory]
     });
     detached = true;
   } finally {
     restoreEnv();
-    controller.close();
     rmSync(tempSessionDir, { recursive: true, force: true });
   }
   let run = { runId: input.runId, status: "unknown" };
@@ -1514,12 +827,12 @@ async function attachRunBundledPiFrontend(context, input) {
     timelineCursor: null,
     steered: input.steered === true,
     detached,
-    rendered: "enriched bundled Pi frontend with remote worker session runtime"
+    rendered: "stock Pi operator console with the pi-rig extension"
   };
 }
 
 // packages/cli/src/commands/_operator-view.ts
-var TERMINAL_RUN_STATUSES2 = new Set(["completed", "failed", "stopped", "cancelled", "canceled", "closed", "merged", "needs_attention", "needs-attention"]);
+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();
@@ -1596,7 +909,7 @@ async function attachRunOperatorView(context, input) {
     }
     const pollMs = Math.max(250, Math.trunc(input.pollMs ?? 2000));
     let timelineCursor = snapshot.timelineCursor;
-    while (!detached && !TERMINAL_RUN_STATUSES2.has(runStatusFromPayload(snapshot.run))) {
+    while (!detached && !TERMINAL_RUN_STATUSES.has(runStatusFromPayload(snapshot.run))) {
       await Bun.sleep(pollMs);
       snapshot = await readOperatorSnapshot(context, input.runId, { timelineCursor });
       timelineCursor = snapshot.timelineCursor;
@@ -1803,6 +1116,44 @@ function formatRunSummaryLine(run) {
   return `${pc.dim("\u2502")} ${pc.bold(runId)} ${formatStatusPill(status)} ${descriptor}${runtime ? pc.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;
@@ -1854,7 +1205,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) => {
@@ -1876,7 +1227,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;
@@ -1902,6 +1253,7 @@ async function executeRun(context, args) {
       const { runs, source } = await listRunsForSelectedConnection(context, { limit: 100 });
       if (context.outputMode === "text") {
         printFormattedOutput(formatRunList(runs, { source }));
+        await printPendingInboxFooter(context);
       }
       return { ok: true, group: "run", command, details: { runs, source } };
     }
@@ -1913,7 +1265,7 @@ async function executeRun(context, args) {
       pending = purgeArtifacts.rest;
       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,
@@ -1943,7 +1295,7 @@ async function executeRun(context, args) {
       pending = keepQueue.rest;
       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,
@@ -1969,11 +1321,11 @@ async function executeRun(context, args) {
       requireNoExtraArgs(extra, "rig run show <id>|--run <id> [--raw]");
       const runId = run.value ?? positionalRunId;
       if (!runId) {
-        throw new CliError2("run show requires a run id.");
+        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 = readAuthorityRun2(context.projectRoot, runId) ?? normalizeRemoteRunDetails(await getRunDetailsViaServer(context, runId).catch(() => ({})));
       if (!record) {
-        throw new CliError2(`Run not found: ${runId}`, 2);
+        throw new CliError(`Run not found: ${runId}`, 2, { hint: "Run `rig run list` to see recorded runs." });
       }
       if (context.outputMode === "text") {
         printFormattedOutput(rawResult.value ? JSON.stringify(record, null, 2) : formatRunCard(record));
@@ -1988,7 +1340,7 @@ async function executeRun(context, args) {
       pending = follow.rest;
       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;
@@ -2020,11 +1372,11 @@ async function executeRun(context, args) {
       requireNoExtraArgs(extra, "rig run replay <id>|--run <id> [--with-session]");
       const runId = run.value ?? positionalRunId;
       if (!runId) {
-        throw new CliError2("run replay requires a run id.", 2);
+        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 CliError2(`No run.jsonl lifecycle log found for ${runId} (looked at ${replay.logPath}).`, 2);
+        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` : ""}):`);
@@ -2066,7 +1418,7 @@ async function executeRun(context, args) {
       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;
       if (messageOption.value?.trim()) {
@@ -2095,6 +1447,7 @@ async function executeRun(context, args) {
       const recentRuns = Array.isArray(summary.recentRuns) ? summary.recentRuns.filter((run) => Boolean(run && typeof run === "object" && !Array.isArray(run))) : [];
       if (context.outputMode === "text") {
         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 };
     }
@@ -2120,10 +1473,10 @@ async function executeRun(context, args) {
       pending = noServerResult.rest;
       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)) {
@@ -2151,7 +1504,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,
@@ -2203,10 +1556,10 @@ async function executeRun(context, args) {
       const runId = runOption.value ?? positionalRunId;
       const message = messageOption.value ?? shortMessageOption.value;
       if (!runId) {
-        throw new CliError2("run steer requires a run id (positional or --run <id>).", 2);
+        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 CliError2("run steer requires --message <text>.", 2);
+        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") {
@@ -2242,7 +1595,7 @@ async function executeRun(context, args) {
       }
       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}`);
@@ -2258,7 +1611,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 {