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

package/dist/src/commands/task.js

@@ -7,10 +7,19 @@ import { cancel as cancel2, confirm, isCancel as isCancel2 } from "@clack/prompt
 
 // 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;
@@ -31,7 +40,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;
@@ -124,7 +133,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) {
@@ -188,7 +197,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 };
 }
@@ -264,7 +273,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;
   }
@@ -324,15 +333,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 {
@@ -344,7 +402,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;
 }
@@ -353,7 +413,7 @@ async function listWorkspaceTasksViaServer(context, filters = {}) {
   appendTaskFilterParams(url, filters);
   const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
   if (!Array.isArray(payload)) {
-    throw new CliError2("Rig server returned an invalid task list payload.", 1);
+    throw new CliError("Rig server returned an invalid task list payload.", 1, { hint: "Check the selected server with `rig server status`; mixed CLI/server versions can mismatch \u2014 try `rig doctor`." });
   }
   return payload.flatMap((entry) => entry && typeof entry === "object" && !Array.isArray(entry) ? [entry] : []);
 }
@@ -369,7 +429,7 @@ async function selectNextWorkspaceTaskViaServer(context, filters = {}) {
   appendTaskFilterParams(url, filters);
   const payload = await requestServerJson(context, `${url.pathname}${url.search}`);
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new CliError2("Rig server returned an invalid next-task payload.", 1);
+    throw new CliError("Rig server returned an invalid next-task payload.", 1, { hint: "Check the selected server with `rig server status`; try `rig task list` to see the raw task set." });
   }
   const record = payload;
   const rawTask = record.task;
@@ -415,26 +475,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",
@@ -443,44 +483,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();
-}
 async function submitTaskRunViaServer(context, input) {
   const isTaskRun = Boolean(input.taskId);
   const endpoint = isTaskRun ? "/api/runs/task" : "/api/runs/adhoc";
@@ -504,11 +506,11 @@ async function submitTaskRunViaServer(context, input) {
     })
   });
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
-    throw new CliError2("Rig server returned an invalid run submission payload.", 1);
+    throw new CliError("Rig server returned an invalid run submission payload.", 1, { hint: "Check `rig server status` and retry; `rig run list` shows whether the run was created anyway." });
   }
   const runId = payload.runId;
   if (typeof runId !== "string" || runId.trim().length === 0) {
-    throw new CliError2("Rig server returned no runId for the submitted run.", 1);
+    throw new CliError("Rig server returned no runId for the submitted run.", 1, { hint: "Check `rig run list` \u2014 the run may still have been created; otherwise retry the submission." });
   }
   return { runId };
 }
@@ -678,9 +680,9 @@ async function runFastTaskRunPreflight(context, options = {}) {
   if (failures.length > 0) {
     const summary = failures.map((check) => `${check.label}${check.detail ? `: ${check.detail}` : ""}`).join("; ");
     if (failures.some((check) => check.id === "duplicate-active-run") && taskId) {
-      throw new CliError2(`Task ${taskId} already has an active Rig run. ${summary}`, 1);
+      throw new CliError(`Task ${taskId} already has an active Rig run. ${summary}`, 1, { hint: `Attach to it with \`rig run attach <run-id> --follow\`, or stop it first with \`rig run stop <run-id>\`.` });
     }
-    throw new CliError2(`Task run preflight failed: ${summary}`, 1);
+    throw new CliError(`Task run preflight failed: ${summary}`, 1, { hint: "Run `rig doctor` to diagnose, then retry `rig task run`." });
   }
   return { ok: true, checks };
 }
@@ -697,7 +699,7 @@ async function runProjectMainSyncPreflight(context, options) {
     runBootstrap: async () => {
       const bootstrap = await context.runCommand(["bun", "run", "bootstrap"]);
       if (bootstrap.exitCode !== 0) {
-        throw new CliError2(bootstrap.stderr || bootstrap.stdout || "bun run bootstrap failed during project pre-run sync", bootstrap.exitCode || 1);
+        throw new CliError(bootstrap.stderr || bootstrap.stdout || "bun run bootstrap failed during project pre-run sync", bootstrap.exitCode || 1);
       }
     }
   });
@@ -1027,684 +1029,8 @@ async function selectTaskWithTextPicker(tasks, io = {}) {
 import { mkdtempSync, rmSync } from "fs";
 import { tmpdir } from "os";
 import { join } 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 = (message2) => {
-      try {
-        const payload = typeof message2.data === "string" ? JSON.parse(message2.data) : JSON.parse(Buffer.from(message2.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(text, streamingBehavior) {
-    await this.transport.sendPrompt(this.context, this.runId, text, streamingBehavior);
-  }
-  async sendCommand(text) {
-    const result = await this.transport.runCommand(this.context, this.runId, text);
-    return typeof result.message === "string" ? result.message : "worker command accepted";
-  }
-  async sendShell(text) {
-    await this.transport.sendShell(this.context, this.runId, text);
-  }
-  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(text) {
-    let current = text;
-    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(text, options) {
-    const trimmed = text.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(text) {
-    const trimmed = text.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(text) {
-    const trimmed = text.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((resolve3, reject) => {
-      this.remote.registerPendingCompaction({ resolve: resolve3, 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((resolve3, reject) => {
-        const pending = { onData: execOptions.onData, resolve: resolve3, 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 message2 = await options.controller.sendCommand(`/${name}${args ? ` ${args}` : ""}`);
-            ctx.ui.notify(message2, "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, text, isBusy) => {
-      statusText = text;
-      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: (text) => setStatus(ctx, text, !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: (message2) => ctx.ui.notify(message2, "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)) {
@@ -1720,51 +1046,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(join(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" };
@@ -1778,12 +1091,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();
@@ -1860,7 +1173,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;
@@ -2042,55 +1355,91 @@ function formatSubmittedRun(input) {
 `);
 }
 
+// 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/_help-catalog.ts
 import { intro, log as log2, note as note2, outro } from "@clack/prompts";
 import pc2 from "picocolors";
 var TOP_LEVEL_SECTIONS = [
   {
     title: "Start here",
-    subtitle: "one-time setup for a repo",
+    subtitle: "one-time setup, pick a server",
     commands: [
       { command: "rig init", description: "Wizard: config, GitHub auth, task source, server, Pi wiring." },
-      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
-      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." }
+      { command: "rig server use <alias|local>", description: "Pick which Rig server owns this repo (`rig server list` to see them)." },
+      { command: "rig server status", description: "Show the selected server for this repo." }
     ]
   },
   {
     title: "Work",
-    subtitle: "find a task and put an agent on it",
+    subtitle: "find a task, put an agent on it, answer what it asks",
     commands: [
       { command: "rig task list", description: "What's on the board (from the selected source/server)." },
-      { command: "rig task next", description: "The next ready task, as a card." },
       { command: "rig task run --next", description: "Dispatch an agent; interactive mode opens the native Pi session." },
-      { command: "rig task run <id> --detach", description: "Fire-and-forget a specific task." }
+      { command: "rig run status", description: "Active and recent runs at a glance." },
+      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
+      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." }
     ]
   },
   {
-    title: "Watch & steer",
-    subtitle: "live runs are observable and steerable, attached or not",
+    title: "Watch",
+    subtitle: "fleet metrics and per-task forensics",
     commands: [
-      { command: "rig run status", description: "Active and recent runs at a glance." },
-      { command: "rig run attach <id> --follow", description: "Join the live Pi session (worker keeps running if you /detach)." },
-      { command: "rig run steer <id> -m <text>", description: "Drop a message into a live worker without attaching." },
-      { command: "rig run stop <id>", description: "Cancel a running worker." }
+      { command: "rig stats [--since 7d]", description: "Fleet metrics: completion/failure rates, median run time, steering, stalls." },
+      { command: "rig inspect logs --task <id>", description: "Latest run log for a task." },
+      { command: "rig inspect diff --task <id>", description: "Changed files for a task." }
     ]
   },
   {
-    title: "Unblock & gate",
-    subtitle: "answer what workers ask; control what merges",
+    title: "Unblock",
+    subtitle: "diagnose wiring, fix auth",
     commands: [
-      { command: "rig inbox approvals", description: "Approvals workers are waiting on (then `rig inbox approve \u2026`)." },
-      { command: "rig inbox inputs", description: "Questions workers asked (then `rig inbox respond \u2026`)." },
-      { command: "rig review show|set", description: "The completion review gate (Greptile is mandatory on merges)." }
+      { command: "rig doctor", description: "Check every part of the wiring \u2014 run this when anything feels off." },
+      { command: "rig github auth status", description: "GitHub auth state on the selected server." }
     ]
   },
   {
     title: "Extend",
-    subtitle: "more Pi, more plugins",
+    subtitle: "plugins contribute validators, hooks, task sources, commands",
     commands: [
-      { command: "rig pi search <term>", description: "Discover community Pi extensions on npm." },
-      { command: "rig pi add <pkg>", description: "Add a Pi extension to this project (workers pick it up too)." },
-      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." }
+      { command: "rig plugin list", description: "What the rig.config.ts plugins contribute." },
+      { command: "rig plugin run <command-id>", description: "Execute a plugin-contributed CLI command." }
     ]
   }
 ];
@@ -2114,22 +1463,20 @@ var PRIMARY_GROUPS = [
       "rig server use local",
       "rig server start --port 3773"
     ],
-    next: ["Use `rig task list` to see server-owned work.", "Use `rig run list` or `rig run attach <id> --follow` to monitor runs."],
-    advanced: ["Compatibility alias: `rig connect ...` remains callable."]
+    next: ["Use `rig task list` to see server-owned work.", "Use `rig run list` or `rig run attach <id> --follow` to monitor runs."]
   },
   {
     name: "task",
     summary: "Find work, start Pi-backed runs, and validate task results.",
     usage: ["rig task <list|next|show|run> [options]"],
     commands: [
-      { command: "list [--assignee <login|@me>] [--state open|closed]", description: "List tasks from the selected server/source.", primary: true },
+      { command: "list [--assignee <login|me|@me>] [--state open|closed]", description: "List tasks from the selected server/source.", primary: true },
       { command: "next [filters]", description: "Render the next matching task as a selected-task card.", primary: true },
       { command: "show <id>|--task <id> [--raw]", description: "Show a human task summary; --raw prints the full payload.", primary: true },
       { command: "run [#<issue>|<task-id>|--next|--task <id>]", description: "Submit a task run; interactive follows with bundled Pi.", primary: true },
       { command: "validate|verify [--task <id>]", description: "Run configured task checks/review gates." },
       { command: "details --task <id>", description: "Show full task info from the configured source." },
       { command: "reopen [--task <id> | --all] [--reason <text>]", description: "Reopen closed task(s) in the configured source." },
-      { command: "reset --task <id>", description: "Compatibility spelling of `reopen --task <id>`." },
       { command: "artifacts|artifact-dir|artifact-write", description: "Inspect or write task artifacts." },
       { command: "report-bug", description: "Create a structured bug report/task." }
     ],
@@ -2187,15 +1534,54 @@ var PRIMARY_GROUPS = [
     next: ["Rejoin the run after resolving a block: `rig run attach <run-id> --follow`."]
   },
   {
-    name: "review",
-    summary: "Inspect or change completion review gate policy.",
-    usage: ["rig review <show|set>"],
+    name: "stats",
+    summary: "Fleet metrics computed from on-disk run journals (no server required).",
+    usage: ["rig stats [show] [--since <7d|30d|ISO date>]"],
     commands: [
-      { command: "show", description: "Show current review gate settings.", primary: true },
-      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider.", primary: true }
+      { command: "show [--since <window>]", description: "Total runs, completion/failure/needs-attention rates, median run time, steering, stalls, approvals.", primary: true }
     ],
-    examples: ["rig review show", "rig review set required --provider greptile"],
-    next: ["Use `rig inbox approvals` for blocked run handoffs."]
+    examples: [
+      "rig stats",
+      "rig stats --since 7d",
+      "rig stats --since 2026-06-01 --json"
+    ],
+    next: ["Inspect outliers with `rig run list` and `rig run show <run-id>`.", "Use `--json` for the schema'd envelope (see docs/cli-json.md)."]
+  },
+  {
+    name: "inspect",
+    summary: "Inspect logs, artifacts, graphs, failures for a task.",
+    usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff> --task <id>"],
+    commands: [
+      { command: "logs --task <id>", description: "Latest run log for a task (local or selected server).", primary: true },
+      { command: "artifacts --task <id>", description: "List the task's completion artifacts.", primary: true },
+      { command: "failures --task <id>", description: "Recorded failures for a task.", primary: true },
+      { command: "diff --task <id>", description: "Changed files for a task.", primary: true },
+      { command: "graph", description: "Task dependency graph." },
+      { command: "audit", description: "Controlled-command audit trail." }
+    ],
+    examples: ["rig inspect logs --task <id>", "rig inspect diff --task <id>"],
+    next: ["Use `rig stats` for fleet-level metrics across runs."]
+  },
+  {
+    name: "repo",
+    summary: "Repository sync/baseline helpers for the Rig-managed checkout.",
+    usage: ["rig repo <sync|reset-baseline>"],
+    commands: [
+      { command: "sync", description: "Sync project repository state.", primary: true },
+      { command: "reset-baseline", description: "Reset the managed baseline for the repo." }
+    ],
+    examples: ["rig repo sync"]
+  },
+  {
+    name: "plugin",
+    summary: "Plugin listing, validation, and plugin-contributed commands.",
+    usage: ["rig plugin <list|validate|run> [options]"],
+    commands: [
+      { command: "list", description: "List plugins declared in rig.config.ts and their contributions.", primary: true },
+      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task.", primary: true },
+      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
+    ],
+    examples: ["rig plugin list", "rig plugin run <command-id>"]
   },
   {
     name: "init",
@@ -2203,12 +1589,14 @@ var PRIMARY_GROUPS = [
     usage: ["rig init [--yes] [--server local|remote] [--repo owner/repo] [--remote-url <url>]"],
     commands: [
       { command: "init", description: "Interactive setup wizard for a new or existing Rig repo.", primary: true },
+      { command: "init --demo", description: "Offline demo project: files task source + 3 sample tasks, zero GitHub.", primary: true },
       { command: "init --yes", description: "Non-interactive setup using detected/default settings.", primary: true },
       { command: "init --server remote --remote-url <url>", description: "Link this repo to a remote Rig server.", primary: true },
       { command: "init --repair", description: "Repair missing private state without replacing project config." }
     ],
     examples: [
       "rig init",
+      "rig init --demo",
       "rig init --yes --repo humanity-org/humanwork",
       "rig init --server remote --remote-url https://where.rig-does.work --repo owner/repo"
     ],
@@ -2239,23 +1627,19 @@ var PRIMARY_GROUPS = [
   }
 ];
 var ADVANCED_GROUPS = [
-  { name: "connect", summary: "Compatibility alias for `rig server` selection commands.", usage: ["rig connect <status|list|add|use>"], commands: [{ command: "status|list|add|use", description: "Use `rig server ...` for the primary UX." }] },
   { name: "setup", summary: "Bootstrap/check local setup.", usage: ["rig setup <bootstrap|check|preflight>"], commands: [{ command: "bootstrap|check|preflight", description: "Setup helpers." }] },
+  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
   {
-    name: "inspect",
-    summary: "Inspect logs, artifacts, graphs, failures for a task.",
-    usage: ["rig inspect <logs|artifacts|failures|graph|audit|diff> --task <id>"],
+    name: "review",
+    summary: "Inspect or change completion review gate policy.",
+    usage: ["rig review <show|set>"],
     commands: [
-      { command: "logs --task <id>", description: "Latest run log for a task (local or selected server)." },
-      { command: "artifacts --task <id>", description: "List the task's completion artifacts." },
-      { command: "failures --task <id>", description: "Recorded failures for a task." },
-      { command: "graph", description: "Task dependency graph." },
-      { command: "audit", description: "Controlled-command audit trail." },
-      { command: "diff --task <id>", description: "Changed files for a task." }
-    ]
+      { command: "show", description: "Show current review gate settings." },
+      { command: "set <off|advisory|required> [--provider greptile]", description: "Change review strictness/provider." }
+    ],
+    examples: ["rig review show", "rig review set required --provider greptile"],
+    next: ["Use `rig inbox approvals` for blocked run handoffs."]
   },
-  { name: "repo", summary: "Repository sync/baseline helpers.", usage: ["rig repo <sync|reset-baseline>"], commands: [{ command: "sync", description: "Sync project repository state." }] },
-  { name: "profile", summary: "Runtime profile/model defaults.", usage: ["rig profile <show|set>"], commands: [{ command: "show", description: "Show active profile." }] },
   {
     name: "browser",
     summary: "Browser/app diagnostics for browser-required tasks.",
@@ -2281,16 +1665,6 @@ var ADVANCED_GROUPS = [
     examples: ["rig pi search subagents", "rig pi add pi-subagents", "rig pi list"],
     next: ["Config-managed extensions: declare `runtime: { pi: { packages: [...] } }` in rig.config.ts \u2014 workers pick them up automatically."]
   },
-  {
-    name: "plugin",
-    summary: "Plugin listing, validation, and plugin-contributed commands.",
-    usage: ["rig plugin <list|validate|run> [options]"],
-    commands: [
-      { command: "list", description: "List plugins declared in rig.config.ts and their contributions." },
-      { command: "validate --task <id>", description: "Run plugin-contributed validators for a task." },
-      { command: "run <command-id> [args...]", description: "Execute a plugin-contributed CLI command (also callable as `rig <command-id>`)." }
-    ]
-  },
   { name: "queue", summary: "Run task queues locally.", usage: ["rig queue run [options]"], commands: [{ command: "run", description: "Process queue work." }] },
   { name: "agent", summary: "Runtime agent workspace helpers.", usage: ["rig agent <list|prepare|run|cleanup>"], commands: [{ command: "list", description: "List prepared agents." }] },
   { name: "inspector", summary: "Event stream and drift scanners.", usage: ["rig inspector <stream|scan-upstream-drift>"], commands: [{ command: "stream", description: "Stream events." }] },
@@ -2357,7 +1731,7 @@ function renderGroup(group) {
 function renderTopLevelHelp() {
   return [
     `${heading("rig")} ${pc2.dim("\u2014 server-owned task/run control plane for Pi-backed engineering work")}`,
-    pc2.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox/review gates."),
+    pc2.dim("Current path: select a server, choose a task, submit a run, attach with native Pi, clear inbox gates."),
     "",
     ...TOP_LEVEL_SECTIONS.flatMap((section) => [
       `${pc2.bold(pc2.magenta(`\u25C7 ${section.title}`))} \u2014 ${pc2.dim(section.subtitle)}`,
@@ -2409,7 +1783,7 @@ function printTopLevelHelp(state = {}) {
     commandLine("--dry-run", "Print the command plan without mutating state.")
   ].join(`
 `), "Global options");
-  outro("init \u2192 task run \u2192 watch/steer \u2192 inbox/review \u2192 merged.");
+  outro("init \u2192 task run \u2192 watch \u2192 inbox \u2192 merged.");
 }
 function printGroupHelpDocument(groupName) {
   const rendered = renderGroupHelp(groupName) ?? renderTopLevelHelp();
@@ -2450,7 +1824,7 @@ async function readStdin() {
   }
   return Buffer.concat(chunks).toString("utf-8");
 }
-function normalizeAssignedToAlias(value) {
+function normalizeAssigneeAlias(value) {
   if (!value)
     return;
   return value.trim().toLowerCase() === "me" ? "@me" : value;
@@ -2459,25 +1833,19 @@ function parseTaskFilters(args) {
   let pending = args;
   const assigneeResult = takeOption(pending, "--assignee");
   pending = assigneeResult.rest;
-  const assignedToResult = takeOption(pending, "--assigned-to");
-  pending = assignedToResult.rest;
   const stateResult = takeOption(pending, "--state");
   pending = stateResult.rest;
   const statusResult = takeOption(pending, "--status");
   pending = statusResult.rest;
   const limitResult = takeOption(pending, "--limit");
   pending = limitResult.rest;
-  const normalizedAssignedTo = normalizeAssignedToAlias(assignedToResult.value);
-  if (assigneeResult.value && normalizedAssignedTo && assigneeResult.value !== normalizedAssignedTo) {
-    throw new CliError2("--assignee and --assigned-to cannot specify different assignees.", 2);
-  }
-  const assignee = normalizedAssignedTo ?? assigneeResult.value;
+  const assignee = normalizeAssigneeAlias(assigneeResult.value);
   const limit = (() => {
     if (!limitResult.value)
       return;
     const parsed = Number.parseInt(limitResult.value, 10);
     if (!Number.isFinite(parsed) || parsed < 1) {
-      throw new CliError2("--limit must be a positive integer.", 2);
+      throw new CliError("--limit must be a positive integer.", 2, { hint: "Re-run with a positive number, e.g. `rig task list --limit 20`." });
     }
     return parsed;
   })();
@@ -2512,7 +1880,7 @@ function normalizePrMode(value) {
     return;
   if (value === "auto" || value === "ask" || value === "off")
     return value;
-  throw new CliError2("--pr must be auto, ask, or off.", 2);
+  throw new CliError("--pr must be auto, ask, or off.", 2, { hint: "Re-run with `--pr auto|ask|off`, or pass `--no-pr` to disable the PR." });
 }
 function detectLocalDirtyState(projectRoot) {
   const result = spawnSync("git", ["-C", projectRoot, "status", "--porcelain"], { encoding: "utf8", timeout: 5000 });
@@ -2535,7 +1903,7 @@ function selectedServerKind(projectRoot) {
 }
 async function resolveDirtyBaselineForTaskRun(context, explicit) {
   if (explicit && explicit !== "head" && explicit !== "dirty-snapshot") {
-    throw new CliError2("--dirty-baseline must be head or dirty-snapshot.", 2);
+    throw new CliError("--dirty-baseline must be head or dirty-snapshot.", 2, { hint: "Re-run with `--dirty-baseline head` or `--dirty-baseline dirty-snapshot`." });
   }
   if (selectedServerKind(context.projectRoot) !== "local") {
     return { mode: explicit === "dirty-snapshot" ? "dirty-snapshot" : "head", state: null };
@@ -2555,7 +1923,7 @@ async function resolveDirtyBaselineForTaskRun(context, explicit) {
     });
     if (isCancel2(answer)) {
       cancel2("Run cancelled.");
-      throw new CliError2("Run cancelled by user.", 1);
+      throw new CliError("Run cancelled by user.", 1);
     }
     return { mode: answer ? "dirty-snapshot" : "head", state };
   }
@@ -2610,11 +1978,12 @@ async function executeTask(context, args, options) {
       const rawResult = takeFlag(pending, "--raw");
       pending = rawResult.rest;
       const { filters, rest: remaining } = parseTaskFilters(pending);
-      requireNoExtraArgs(remaining, "rig task list [--raw] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
+      requireNoExtraArgs(remaining, "rig task list [--raw] [--assignee <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
       const tasks = await listWorkspaceTasksViaServer(context, filters);
       if (context.outputMode === "text") {
         const renderedTasks = rawResult.value ? tasks.map((task) => summarizeTask(task, { raw: true })) : tasks.map((task) => summarizeTask(task));
         printFormattedOutput(formatTaskList(renderedTasks, { raw: rawResult.value }));
+        await printPendingInboxFooter(context);
       }
       return {
         ok: true,
@@ -2633,10 +2002,10 @@ async function executeTask(context, args, options) {
       requireNoExtraArgs(remaining, "rig task show <id>|--task <id> [--raw]");
       const taskId3 = normalizeTaskRunTaskId(taskOption.value ?? positional);
       if (!taskId3)
-        throw new CliError2("task show requires a task id.", 2);
+        throw new CliError("task show requires a task id.", 2, { hint: "Run `rig task list` to find ids, then `rig task show <id>`." });
       const task = await getWorkspaceTaskViaServer(context, taskId3);
       if (!task)
-        throw new CliError2(`Task not found: ${taskId3}`, 3);
+        throw new CliError(`Task not found: ${taskId3}`, 3, { hint: "Run `rig task list` to see available tasks." });
       const summary = summarizeTask(task, { raw: true });
       if (context.outputMode === "text") {
         printFormattedOutput(rawResult.value ? JSON.stringify(summary, null, 2) : formatTaskDetails(summary));
@@ -2645,7 +2014,7 @@ async function executeTask(context, args, options) {
     }
     case "next": {
       const { filters, rest: remaining } = parseTaskFilters(rest);
-      requireNoExtraArgs(remaining, "rig task next [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
+      requireNoExtraArgs(remaining, "rig task next [--assignee <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>]");
       const selected = await selectNextWorkspaceTaskViaServer(context, filters);
       if (context.outputMode === "text") {
         if (selected.task) {
@@ -2700,7 +2069,7 @@ async function executeTask(context, args, options) {
     }
     case "artifact-write": {
       if (rest.length < 1) {
-        throw new CliError2(`Usage: rig task artifact-write <filename> [--file <path>]
+        throw new CliError(`Usage: rig task artifact-write <filename> [--file <path>]
 ` + `  Reads content from stdin (or --file), writes to the active task artifact dir.
 ` + "  Example: echo '...' | rig task artifact-write collection-audit.md");
       }
@@ -2713,7 +2082,7 @@ async function executeTask(context, args, options) {
         content = await readStdin();
       }
       if (!artifactFilename) {
-        throw new CliError2("Usage: rig task artifact-write <filename> [--file path]");
+        throw new CliError("Usage: rig task artifact-write <filename> [--file path]");
       }
       withMutedConsole(context.outputMode === "json", () => taskArtifactWrite(context.projectRoot, artifactFilename, content));
       return { ok: true, group: "task", command, details: { filename: artifactFilename } };
@@ -2722,11 +2091,11 @@ async function executeTask(context, args, options) {
       return options.executeTaskReportBug(context, rest);
     case "lookup": {
       if (rest.length !== 1) {
-        throw new CliError2("Usage: rig task lookup <task-id>");
+        throw new CliError("Usage: rig task lookup <task-id>");
       }
       const lookupId = rest[0];
       if (!lookupId) {
-        throw new CliError2("Usage: rig task lookup <task-id>");
+        throw new CliError("Usage: rig task lookup <task-id>");
       }
       const result = taskLookup(context.projectRoot, lookupId);
       if (context.outputMode === "text") {
@@ -2736,11 +2105,11 @@ async function executeTask(context, args, options) {
     }
     case "record": {
       if (rest.length < 2) {
-        throw new CliError2("Usage: rig task record <decision|failure> <text>");
+        throw new CliError("Usage: rig task record <decision|failure> <text>");
       }
       const type = rest[0];
       if (type !== "decision" && type !== "failure") {
-        throw new CliError2("Usage: rig task record <decision|failure> <text>");
+        throw new CliError("Usage: rig task record <decision|failure> <text>");
       }
       withMutedConsole(context.outputMode === "json", () => taskRecord(context.projectRoot, type, rest.slice(1).join(" ")));
       return { ok: true, group: "task", command, details: { type: rest[0] } };
@@ -2783,15 +2152,15 @@ async function executeTask(context, args, options) {
       if (positionalTaskId) {
         pending = pending.slice(1);
       }
-      requireNoExtraArgs(pending, "rig task run [#<issue>|<task-id>] [--next] [--task <id>] [--detach] [--assignee <login|@me>] [--assigned-to <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--pr auto|ask|off] [--no-pr] [--dirty-baseline head|dirty-snapshot] [--skip-project-sync]");
+      requireNoExtraArgs(pending, "rig task run [#<issue>|<task-id>] [--next] [--task <id>] [--detach] [--assignee <login|me|@me>] [--state open|closed] [--status <status>] [--limit <n>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--pr auto|ask|off] [--no-pr] [--dirty-baseline head|dirty-snapshot] [--skip-project-sync]");
       if (nextResult.value && (taskResult.value || positionalTaskId)) {
-        throw new CliError2("task run cannot combine --next with an explicit task id.", 2);
+        throw new CliError("task run cannot combine --next with an explicit task id.", 2, { hint: "Use either `rig task run --next` or `rig task run <id>`." });
       }
       if (taskResult.value && positionalTaskId) {
-        throw new CliError2("task run cannot combine positional task id with --task <id>.", 2);
+        throw new CliError("task run cannot combine positional task id with --task <id>.", 2, { hint: "Pass the id once, e.g. `rig task run <id>`." });
       }
       if (prResult.value && noPrResult.value) {
-        throw new CliError2("task run cannot combine --pr with --no-pr.", 2);
+        throw new CliError("task run cannot combine --pr with --no-pr.", 2, { hint: "Use `--pr auto|ask|off` or `--no-pr`, not both." });
       }
       let selectedTask = null;
       let selectedTaskId = normalizeTaskRunTaskId(taskResult.value) ?? positionalTaskId;
@@ -2800,18 +2169,18 @@ async function executeTask(context, args, options) {
         selectedTask = selected.task;
         selectedTaskId = selected.task ? readTaskId(selected.task) : null;
         if (!selectedTaskId) {
-          throw new CliError2("No matching task found for task run --next.", 3);
+          throw new CliError("No matching task found for task run --next.", 3, { hint: "Run `rig task list` to inspect available work, or relax the filters." });
         }
       }
       if (!selectedTaskId && !initialPromptResult.value && !titleResult.value) {
         if (context.outputMode !== "text" || !process.stdin.isTTY || !process.stdout.isTTY) {
-          throw new CliError2("task run requires an interactive terminal to pick a task; pass --next, --task <id>, or --initial-prompt/--title for an ad hoc run.", 2);
+          throw new CliError("task run requires an interactive terminal to pick a task; pass --next, --task <id>, or --initial-prompt/--title for an ad hoc run.", 2);
         }
         const tasks = await listWorkspaceTasksViaServer(context, filterResult.filters);
         selectedTask = await selectTaskWithTextPicker(tasks);
         selectedTaskId = selectedTask ? readTaskId(selectedTask) : null;
         if (!selectedTaskId) {
-          throw new CliError2("No task selected.", 3);
+          throw new CliError("No task selected.", 3, { hint: "Run `rig task run --next` for the next ready task, or `rig task run --task <id>`." });
         }
       }
       await runProjectMainSyncPreflight(context, { disabled: skipProjectSyncResult.value });
@@ -2885,7 +2254,7 @@ async function executeTask(context, args, options) {
       }
       const ok = await withMutedConsole(context.outputMode === "json", async () => taskValidate(context.projectRoot, task || undefined, await validatorRegistryForTaskCommands(context.projectRoot)));
       if (!ok) {
-        throw new CliError2(`Validation failed for ${task || "active task"}.`, 2);
+        throw new CliError(`Validation failed for ${task || "active task"}.`, 2, { hint: "Inspect failures with `rig inspect failures --task <id>`, fix, then re-run `rig task validate --task <id>`." });
       }
       return { ok: true, group: "task", command, details: { task: task || "active" } };
     }
@@ -2898,21 +2267,10 @@ async function executeTask(context, args, options) {
       }
       const ok = await withMutedConsole(context.outputMode === "json", () => taskVerify(context.projectRoot, task || undefined));
       if (!ok) {
-        throw new CliError2(`Verification rejected for ${task || "active task"}.`, 2);
+        throw new CliError(`Verification rejected for ${task || "active task"}.`, 2, { hint: "Check `rig inspect logs --task <id>`, address the rejection, then re-run `rig task verify --task <id>`." });
       }
       return { ok: true, group: "task", command, details: { task: task || "active" } };
     }
-    case "reset": {
-      const { value: task, rest: remaining } = takeOption(rest, "--task");
-      requireNoExtraArgs(remaining, "rig task reset --task <task-id>");
-      const requiredTask = requireTask(task, "rig task reset --task <task-id>");
-      const summary = withMutedConsole(context.outputMode === "json", () => taskReopen(context.projectRoot, {
-        all: false,
-        taskId: requiredTask,
-        dryRun: false
-      }));
-      return { ok: true, group: "task", command, details: summary };
-    }
     case "details": {
       const { value: task, rest: remaining } = takeOption(rest, "--task");
       requireNoExtraArgs(remaining, "rig task details --task <task-id>");
@@ -2926,7 +2284,7 @@ async function executeTask(context, args, options) {
       const { rest: remaining } = takeOption(allFlag.rest, "--reason");
       requireNoExtraArgs(remaining, "rig task reopen [--task <id> | --all] [--reason <text>]");
       if (!allFlag.value && !task) {
-        throw new CliError2("Usage: rig task reopen [--task <id> | --all] [--reason <text>]");
+        throw new CliError("Usage: rig task reopen [--task <id> | --all] [--reason <text>]");
       }
       const summary = withMutedConsole(context.outputMode === "json", () => taskReopen(context.projectRoot, {
         all: allFlag.value,
@@ -2936,7 +2294,10 @@ async function executeTask(context, args, options) {
       return { ok: true, group: "task", command, details: summary };
     }
     default:
-      throw new CliError2(`Unknown task command: ${command}`);
+      if (command === "reset") {
+        throw new CliError("Unknown task command: reset", 1, { hint: "Use `rig task reopen --task <id>`." });
+      }
+      throw new CliError(`Unknown task command: ${command}`, 1, { hint: "Run `rig task --help` to list available task commands." });
   }
 }
 export {