@h-rig/cli 0.0.6-alpha.9 → 0.0.6-alpha.90

package/dist/src/commands/server.js

@@ -1,12 +1,19 @@
 // @bun
 // packages/cli/src/runner.ts
 import { EventBus } from "@rig/runtime/control-plane/runtime/events";
-import { CliError } from "@rig/runtime/control-plane/errors";
+import { CliError as RuntimeCliError } from "@rig/runtime/control-plane/errors";
 import { evaluate, loadPolicy, resolveAction } from "@rig/runtime/control-plane/runtime/guard";
-import { PluginManager } from "@rig/runtime/control-plane/runtime/plugins";
-import { loadRuntimeContextFromEnv } from "@rig/runtime/control-plane/runtime/context";
 import { buildBinary } from "@rig/runtime/control-plane/runtime/isolation";
-import { CliError as CliError2 } from "@rig/runtime/control-plane/errors";
+
+class CliError extends RuntimeCliError {
+  hint;
+  constructor(message, exitCode = 1, options = {}) {
+    super(message, exitCode);
+    if (options.hint?.trim()) {
+      this.hint = options.hint.trim();
+    }
+  }
+}
 function takeOption(args, option) {
   const rest = [];
   let value;
@@ -15,7 +22,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;
@@ -34,12 +41,14 @@ Usage: ${usage}`);
   }
 }
 
+// packages/cli/src/commands/server.ts
+import { resolveRigServerCommand } from "@rig/runtime/local-server";
+
 // packages/cli/src/commands/_authority-runs.ts
 import {
   readAuthorityRun,
   readJsonlFile,
-  resolveAuthorityRunDir,
-  writeJsonFile
+  writeAuthorityRunRecord
 } from "@rig/runtime/control-plane/authority-files";
 
 // packages/cli/src/commands/_paths.ts
@@ -60,11 +69,133 @@ function normalizeRuntimeAdapter(value) {
   return "claude-code";
 }
 
-// packages/cli/src/commands/_server-client.ts
-import { spawnSync } from "child_process";
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve2 } from "path";
-import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+// packages/cli/src/app/drone-ui.ts
+import { ProcessTerminal, TUI, Text, Input, SelectList, matchesKey } from "@earendil-works/pi-tui";
+
+// packages/cli/src/app/theme.ts
+var RIG_PALETTE = {
+  ink: "#f2f3f6",
+  ink2: "#aeb0ba",
+  ink3: "#6c6e79",
+  ink4: "#44464f",
+  accent: "#ccff4d",
+  accentDim: "#a9d63f",
+  cyan: "#56d8ff",
+  red: "#ff5d5d",
+  yellow: "#ffd24d"
+};
+function hexToRgb(hex) {
+  const value = hex.replace("#", "");
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16)
+  ];
+}
+function fg(hex) {
+  const [r, g, b] = hexToRgb(hex);
+  return (text) => `\x1B[38;2;${r};${g};${b}m${text}\x1B[39m`;
+}
+var ink = fg(RIG_PALETTE.ink);
+var ink2 = fg(RIG_PALETTE.ink2);
+var ink3 = fg(RIG_PALETTE.ink3);
+var ink4 = fg(RIG_PALETTE.ink4);
+var accent = fg(RIG_PALETTE.accent);
+var accentDim = fg(RIG_PALETTE.accentDim);
+var cyan = fg(RIG_PALETTE.cyan);
+var red = fg(RIG_PALETTE.red);
+var yellow = fg(RIG_PALETTE.yellow);
+function bold(text) {
+  return `\x1B[1m${text}\x1B[22m`;
+}
+var DRONE_ART = [
+  "  .-=-.                   .-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'._               _.'-=-'   ",
+  "        '._           _.'         ",
+  "           '=$$$$$$$=.'           ",
+  "          =$$$$$$$$$$$=           ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "        $$$@@        @@$$$        ",
+  "        $$@    ?     @$$$         ",
+  "        $$$@   '-'   @$$$         ",
+  "        $$$@@        @@$$$        ",
+  "         $$$@@@@@@@@@@$$$         ",
+  "          =$$$$$$$$$$$=           ",
+  "           '=$$$$$$$=.'           ",
+  "        _.'           '._         ",
+  "  .-=-.'                 '.-=-.   ",
+  " ( !!! )                 ( !!! )  ",
+  "  '-=-'                   '-=-'   "
+];
+var EYE_FRAMES = ["@", "o", "."];
+var DRONE_WIDTH = DRONE_ART[0].length;
+var DRONE_HEIGHT = DRONE_ART.length;
+var MICRO_BLADES = ["---", "\\\\\\", "|||", "///"];
+function microDroneFrame(tick) {
+  const blade = MICRO_BLADES[tick % MICRO_BLADES.length];
+  const eye = EYE_FRAMES[Math.floor(tick / 2) % EYE_FRAMES.length];
+  return `(${blade})${eye}(${blade})`;
+}
+var MICRO_DRONE_FRAMES = Array.from({ length: 12 }, (_, index) => microDroneFrame(index));
+
+// packages/cli/src/app/drone-ui.ts
+var isTty = () => Boolean(process.stdout.isTTY);
+function droneCancel(text) {
+  console.log(` ${red("\u2716")} ${ink3(text)}`);
+}
+var SELECT_THEME = {
+  selectedPrefix: (text) => accent(text),
+  selectedText: (text) => bold(ink(text)),
+  description: (text) => ink3(text),
+  scrollInfo: (text) => ink4(text),
+  noMatch: (text) => ink3(text)
+};
+async function runMiniTui(build) {
+  const terminal = new ProcessTerminal;
+  const tui = new TUI(terminal);
+  let settled = false;
+  return await new Promise((resolve) => {
+    const finish = (result) => {
+      if (settled)
+        return;
+      settled = true;
+      tui.stop();
+      resolve(result);
+    };
+    build(tui, finish);
+    tui.start();
+  });
+}
+async function droneSelect(input) {
+  if (!isTty() || input.options.length === 0) {
+    return input.initialValue ?? input.options[0]?.value ?? null;
+  }
+  return runMiniTui((tui, finish) => {
+    tui.addChild(new Text(` ${accent("\u258D")}${bold(ink(input.message))}`));
+    const items = input.options.map((option) => ({
+      value: option.value,
+      label: option.label,
+      ...option.hint ? { description: option.hint } : {}
+    }));
+    const list = new SelectList(items, Math.min(items.length, 12), SELECT_THEME);
+    const initialIndex = input.initialValue ? items.findIndex((item) => item.value === input.initialValue) : -1;
+    if (initialIndex > 0)
+      list.setSelectedIndex(initialIndex);
+    list.onSelect = (item) => finish(item.value);
+    list.onCancel = () => finish(null);
+    tui.addChild(list);
+    tui.addChild(new Text(ink4(" \u2191\u2193 navigate \xB7 enter select \xB7 esc cancel")));
+    tui.setFocus(list);
+    tui.addInputListener((data) => {
+      if (matchesKey(data, "ctrl+c") || matchesKey(data, "escape")) {
+        finish(null);
+        return { consume: true };
+      }
+      return;
+    });
+  });
+}
 
 // packages/cli/src/commands/_connection-state.ts
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
@@ -88,9 +219,14 @@ function readJsonFile(path) {
   try {
     return JSON.parse(readFileSync(path, "utf8"));
   } catch (error) {
-    throw new CliError2(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1);
+    throw new CliError(`Invalid Rig connection state at ${path}: ${error instanceof Error ? error.message : String(error)}`, 1, { hint: "Fix or delete that file, then re-select a server with `rig server use <alias|local>`." });
   }
 }
+function writeJsonFile(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}
+`, "utf8");
+}
 function normalizeConnection(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     return null;
@@ -120,6 +256,18 @@ function readGlobalConnections(options = {}) {
   }
   return { connections };
 }
+function writeGlobalConnections(state, options = {}) {
+  writeJsonFile(resolveGlobalConnectionsPath(options.env ?? process.env), state);
+}
+function upsertGlobalConnection(alias, connection, options = {}) {
+  const cleanAlias = alias.trim();
+  if (!cleanAlias)
+    throw new CliError("Connection alias is required.", 1, { hint: "Save a server with `rig server add <alias> <url>`." });
+  const state = readGlobalConnections(options);
+  state.connections[cleanAlias] = connection;
+  writeGlobalConnections(state, options);
+  return state;
+}
 function readRepoConnection(projectRoot) {
   const payload = readJsonFile(resolveRepoConnectionPath(projectRoot));
   if (!payload || typeof payload !== "object" || Array.isArray(payload))
@@ -131,25 +279,218 @@ function readRepoConnection(projectRoot) {
   return {
     selected,
     project: typeof record.project === "string" ? record.project : undefined,
-    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined
+    linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
   };
 }
+function writeRepoConnection(projectRoot, state) {
+  writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
+}
 function resolveSelectedConnection(projectRoot, options = {}) {
   const repo = readRepoConnection(projectRoot);
   if (!repo)
     return null;
   if (repo.selected === "local")
-    return { alias: "local", connection: { kind: "local", mode: "auto" } };
+    return { alias: "local", connection: { kind: "local", mode: "auto" }, serverProjectRoot: repo.serverProjectRoot };
   const global = readGlobalConnections(options);
   const connection = global.connections[repo.selected];
   if (!connection) {
-    throw new CliError2(`Selected Rig connection "${repo.selected}" was not found. Run \`rig connect list\` or \`rig connect use local\`.`, 1);
+    throw new CliError(`Selected Rig server "${repo.selected}" was not found. Run \`rig server list\` or \`rig server use local\`.`, 1);
+  }
+  return { alias: repo.selected, connection, serverProjectRoot: repo.serverProjectRoot };
+}
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+}
+
+// packages/cli/src/commands/_cli-format.ts
+import pc from "picocolors";
+var themeDim = (value) => ink3(value);
+var themeFaint = (value) => ink4(value);
+function truncate(value, width) {
+  if (value.length <= width)
+    return value;
+  if (width <= 1)
+    return "\u2026";
+  return `${value.slice(0, width - 1)}\u2026`;
+}
+function pad(value, width) {
+  return value.length >= width ? value : `${value}${" ".repeat(width - value.length)}`;
+}
+function statusColor(status) {
+  const normalized = status.toLowerCase();
+  if (["completed", "merged", "closed", "done", "accepted", "pass", "selected", "approved", "running"].includes(normalized))
+    return accent;
+  if (["failed", "needs_attention", "needs-attention", "blocked", "error", "rejected"].includes(normalized))
+    return red;
+  if (["reviewing", "validating", "in_progress", "in-progress", "remote", "preparing", "closing-out"].includes(normalized))
+    return cyan;
+  if (["ready", "open", "queued", "created", "local", "pending"].includes(normalized))
+    return yellow;
+  return themeDim;
+}
+function formatStatusPill(status) {
+  const label = status || "unknown";
+  return statusColor(label)(`\u25CF ${label}`);
+}
+function formatSection(title, subtitle) {
+  return `${pc.bold(accent("\u25C6"))} ${pc.bold(title)}${subtitle ? themeDim(` \u2014 ${subtitle}`) : ""}`;
+}
+function formatSuccessCard(title, rows = []) {
+  const body = rows.filter(([, value]) => value !== undefined && value !== null && String(value).length > 0).map(([key, value]) => `${themeFaint("\u2502")} ${themeDim(key.padEnd(12))} ${value}`);
+  return [formatSection(title), ...body].join(`
+`);
+}
+function formatNextSteps(steps) {
+  if (steps.length === 0)
+    return [];
+  return [pc.bold("Next"), ...steps.map((step) => `${accent("\u203A")} ${step}`)];
+}
+function formatConnectionList(connections) {
+  const rows = [["local", { kind: "local", mode: "auto" }], ...Object.entries(connections)];
+  const aliasWidth = Math.min(24, Math.max(5, ...rows.map(([alias]) => alias.length)));
+  const lines = rows.map(([alias, connection]) => [
+    pc.bold(pad(truncate(alias, aliasWidth), aliasWidth)),
+    formatStatusPill(connection.kind),
+    connection.kind === "remote" ? connection.baseUrl ?? "" : connection.mode ?? "local"
+  ].join("  "));
+  return [formatSection("Rig servers", `${rows.length} available`), `${pc.bold(pad("ALIAS", aliasWidth))}  ${pc.bold("KIND")}  ${pc.bold("TARGET")}`, ...lines, "", ...formatNextSteps(["Select one: `rig server use <alias|local>`"])].join(`
+`);
+}
+function formatConnectionStatus(selected, connections) {
+  const connection = selected === "local" ? { kind: "local", mode: "auto" } : connections[selected];
+  const target = !connection ? "not configured" : connection.kind === "remote" ? connection.baseUrl : "local";
+  return [
+    formatSection("Rig server", "selected for this repo"),
+    `${themeFaint("\u2502")} ${themeDim("selected ")} ${pc.bold(selected)}`,
+    `${themeFaint("\u2502")} ${themeDim("kind     ")} ${formatStatusPill(connection?.kind ?? "unknown")}`,
+    `${themeFaint("\u2502")} ${themeDim("target   ")} ${target ?? "not configured"}`,
+    "",
+    ...formatNextSteps(["Change: `rig server use <alias|local>`", "List saved servers: `rig server list`"])
+  ].join(`
+`);
+}
+
+// packages/cli/src/commands/connect.ts
+function usageName(options) {
+  return `rig ${options.group}`;
+}
+function parseConnection(alias, value, options) {
+  if (alias === "local" && !value)
+    return { kind: "local", mode: "auto" };
+  if (!value)
+    throw new CliError(`Missing remote server URL. Usage: ${usageName(options)} add <alias> <url>`, 1);
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new CliError(`Invalid Rig server URL: ${value}`, 1, { hint: "Pass a full http(s) URL, e.g. `rig server add prod https://rig.example.com`." });
+  }
+  if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
+    throw new CliError("Rig remote server URL must be http(s).", 1, { hint: "Use an http:// or https:// URL, e.g. `rig server add prod https://rig.example.com`." });
+  }
+  return { kind: "remote", baseUrl: parsed.toString().replace(/\/+$/, "") };
+}
+function printJsonOrText(context, payload, text) {
+  if (context.outputMode === "json") {
+    console.log(JSON.stringify(payload, null, 2));
+  } else {
+    console.log(text);
+  }
+}
+async function promptForConnectionAlias(context) {
+  const state = readGlobalConnections();
+  const repo = readRepoConnection(context.projectRoot);
+  const options = [
+    { value: "local", label: "local", hint: "Use/start a local Rig server" },
+    ...Object.entries(state.connections).map(([alias, connection]) => ({
+      value: alias,
+      label: alias,
+      hint: connection.kind === "remote" ? connection.baseUrl : "local"
+    }))
+  ].filter((option, index, all) => all.findIndex((candidate) => candidate.value === option.value) === index);
+  const answer = await droneSelect({
+    message: "Select Rig server for this repo",
+    initialValue: repo?.selected ?? "local",
+    options
+  });
+  if (answer === null) {
+    droneCancel("No server selected.");
+    throw new CliError("No server selected.", 3);
+  }
+  return String(answer);
+}
+async function executeConnectionCommand(context, args, options) {
+  const [command, ...rest] = args;
+  switch (command ?? "status") {
+    case "list": {
+      requireNoExtraArgs(rest, `${usageName(options)} list`);
+      const state = readGlobalConnections();
+      printJsonOrText(context, state, formatConnectionList(state.connections));
+      return { ok: true, group: options.group, command: "list", details: state };
+    }
+    case "add": {
+      const [alias, url, ...extra] = rest;
+      if (!alias)
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} add <alias> <url>`, 1);
+      requireNoExtraArgs(extra, `${usageName(options)} add <alias> <url>`);
+      const connection = parseConnection(alias, url, options);
+      const state = upsertGlobalConnection(alias, connection);
+      printJsonOrText(context, { alias, connection }, formatSuccessCard("Rig server saved", [
+        ["alias", alias],
+        ["target", connection.kind === "remote" ? connection.baseUrl : "local"],
+        ["next", `${usageName(options)} use ${alias}`]
+      ]));
+      return { ok: true, group: options.group, command: "add", details: { alias, connection, count: Object.keys(state.connections).length } };
+    }
+    case "use": {
+      let [alias, ...extra] = rest;
+      requireNoExtraArgs(extra, `${usageName(options)} use <alias|local>`);
+      if (!alias && options.interactiveUse && context.outputMode === "text" && process.stdin.isTTY) {
+        alias = await promptForConnectionAlias(context);
+      }
+      if (!alias)
+        throw new CliError(`Missing alias. Usage: ${usageName(options)} use <alias|local>`, 1);
+      if (alias !== "local") {
+        const state = readGlobalConnections();
+        if (!state.connections[alias])
+          throw new CliError(`Unknown Rig server: ${alias}`, 1, { hint: "Run `rig server list` to see saved aliases, or save one with `rig server add <alias> <url>`." });
+      }
+      const repoState = { selected: alias, linkedAt: new Date().toISOString() };
+      writeRepoConnection(context.projectRoot, repoState);
+      printJsonOrText(context, repoState, formatSuccessCard("Rig server selected", [
+        ["selected", alias],
+        ["scope", "this repo"],
+        ["next", "rig task list"]
+      ]));
+      return { ok: true, group: options.group, command: "use", details: repoState };
+    }
+    case "status": {
+      requireNoExtraArgs(rest, `${usageName(options)} status`);
+      const repo = readRepoConnection(context.projectRoot);
+      const global = readGlobalConnections();
+      const details = { selected: repo?.selected ?? "local", repo, connections: global.connections };
+      printJsonOrText(context, details, formatConnectionStatus(details.selected, global.connections));
+      return { ok: true, group: options.group, command: "status", details };
+    }
+    default:
+      throw new CliError(`Unknown ${options.group} command: ${String(command)}
+Usage: ${usageName(options)} <list|add|use|status>`, 1);
   }
-  return { alias: repo.selected, connection };
 }
 
 // packages/cli/src/commands/_server-client.ts
-var cachedGitHubBearerToken;
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
+import { resolve as resolve2 } from "path";
+import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
+var scopedGitHubBearerTokens = new Map;
+var serverPhaseListener = null;
+function reportServerPhase(label) {
+  serverPhaseListener?.(label);
+}
 function cleanToken(value) {
   const trimmed = value?.trim();
   return trimmed ? trimmed : null;
@@ -166,49 +507,80 @@ function readPrivateRemoteSessionToken(projectRoot) {
   }
 }
 function readGitHubBearerTokenForRemote(projectRoot) {
-  if (cachedGitHubBearerToken !== undefined)
-    return cachedGitHubBearerToken;
+  const scopedKey = resolve2(projectRoot);
+  if (scopedGitHubBearerTokens.has(scopedKey))
+    return scopedGitHubBearerTokens.get(scopedKey) ?? null;
   const privateSession = readPrivateRemoteSessionToken(projectRoot);
-  if (privateSession) {
-    cachedGitHubBearerToken = privateSession;
-    return cachedGitHubBearerToken;
-  }
-  const envToken = cleanToken(process.env.RIG_GITHUB_TOKEN) ?? cleanToken(process.env.GITHUB_TOKEN) ?? cleanToken(process.env.GH_TOKEN);
-  if (envToken) {
-    cachedGitHubBearerToken = envToken;
-    return cachedGitHubBearerToken;
+  if (privateSession)
+    return privateSession;
+  return cleanToken(process.env.RIG_SERVER_AUTH_TOKEN) ?? cleanToken(process.env.RIG_REMOTE_AUTH_TOKEN);
+}
+function readStoredGitHubAuthToken(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "github-auth.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    return cleanToken(typeof parsed.token === "string" ? parsed.token : undefined);
+  } catch {
+    return null;
   }
-  const result = spawnSync("gh", ["auth", "token"], {
-    encoding: "utf8",
-    timeout: 5000,
-    stdio: ["ignore", "pipe", "ignore"]
-  });
-  cachedGitHubBearerToken = result.status === 0 ? cleanToken(result.stdout) : null;
-  return cachedGitHubBearerToken;
+}
+function readLocalConnectionFallbackToken(projectRoot) {
+  return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
 }
 async function ensureServerForCli(projectRoot) {
   try {
     const selected = resolveSelectedConnection(projectRoot);
     if (selected?.connection.kind === "remote") {
+      reportServerPhase(`Connecting to ${selected.alias}\u2026`);
+      const authToken = readGitHubBearerTokenForRemote(projectRoot);
+      const serverProjectRoot = selected.serverProjectRoot ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
       return {
         baseUrl: selected.connection.baseUrl,
-        authToken: readGitHubBearerTokenForRemote(projectRoot),
-        connectionKind: "remote"
+        authToken,
+        connectionKind: "remote",
+        serverProjectRoot
       };
     }
+    reportServerPhase("Starting local Rig server\u2026");
     const connection = await ensureLocalRigServerConnection(projectRoot);
     return {
       baseUrl: connection.baseUrl,
-      authToken: connection.authToken,
-      connectionKind: "local"
+      authToken: connection.authToken ?? readLocalConnectionFallbackToken(projectRoot),
+      connectionKind: "local",
+      serverProjectRoot: resolve2(projectRoot)
     };
   } catch (error) {
     if (error instanceof Error) {
-      throw new CliError2(error.message, 1);
+      throw new CliError(error.message, 1);
     }
     throw error;
   }
 }
+async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
+  const repo = readRepoConnection(projectRoot);
+  const slug = repo?.project?.trim();
+  if (!slug)
+    return null;
+  try {
+    const response = await fetch(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`, {
+      headers: mergeHeaders(undefined, authToken)
+    });
+    if (!response.ok)
+      return null;
+    const payload = await response.json();
+    const project = payload.project && typeof payload.project === "object" && !Array.isArray(payload.project) ? payload.project : null;
+    const checkouts = Array.isArray(project?.checkouts) ? project.checkouts : [];
+    const latestCheckout = [...checkouts].reverse().find((entry) => Boolean(entry && typeof entry === "object" && !Array.isArray(entry) && typeof entry.path === "string"));
+    const path = typeof latestCheckout?.path === "string" && latestCheckout.path.trim() ? latestCheckout.path.trim() : null;
+    if (path)
+      writeRepoServerProjectRoot(projectRoot, path);
+    return path;
+  } catch {
+    return null;
+  }
+}
 function mergeHeaders(headers, authToken) {
   const merged = new Headers(headers);
   if (authToken) {
@@ -231,12 +603,65 @@ function diagnosticMessage(payload) {
   });
   return messages.length > 0 ? messages.join("; ") : null;
 }
+var serverReachabilityCache = new Map;
+async function probeServerReachability(baseUrl, authToken) {
+  try {
+    const response = await fetch(`${baseUrl.replace(/\/+$/, "")}/api/server/status`, {
+      headers: mergeHeaders(undefined, authToken),
+      signal: AbortSignal.timeout(1500)
+    });
+    return response.ok;
+  } catch {
+    return false;
+  }
+}
+function cachedServerReachability(projectRoot, baseUrl, authToken) {
+  const key = resolve2(projectRoot);
+  const cached = serverReachabilityCache.get(key);
+  if (cached)
+    return cached;
+  const probe = probeServerReachability(baseUrl, authToken);
+  serverReachabilityCache.set(key, probe);
+  return probe;
+}
+function describeSelectedServer(projectRoot, server) {
+  try {
+    const selected = resolveSelectedConnection(projectRoot);
+    if (selected) {
+      return {
+        alias: selected.alias,
+        target: selected.connection.kind === "remote" ? selected.connection.baseUrl : server.baseUrl
+      };
+    }
+  } catch {}
+  return { alias: server.connectionKind === "remote" ? "remote" : "local", target: server.baseUrl };
+}
+async function buildServerFailureContext(projectRoot, server) {
+  const { alias, target } = describeSelectedServer(projectRoot, server);
+  const reachable = await cachedServerReachability(projectRoot, server.baseUrl, server.authToken);
+  const reachability = reachable ? "server is reachable" : "server is unreachable";
+  return {
+    contextLine: `Currently connected to: ${alias} at ${target} (${reachability}).`,
+    hint: "Check the selected server with `rig server status`, or switch with `rig server use <alias|local>`."
+  };
+}
 async function requestServerJson(context, pathname, init = {}) {
   const server = await ensureServerForCli(context.projectRoot);
-  const response = await fetch(`${server.baseUrl}${pathname}`, {
-    ...init,
-    headers: mergeHeaders(init.headers, server.authToken)
-  });
+  const headers = mergeHeaders(init.headers, server.authToken);
+  if (server.serverProjectRoot)
+    headers.set("x-rig-project-root", server.serverProjectRoot);
+  reportServerPhase(`${(init.method ?? "GET").toUpperCase()} ${pathname.split("?")[0]}\u2026`);
+  let response;
+  try {
+    response = await fetch(`${server.baseUrl}${pathname}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    const failure = await buildServerFailureContext(context.projectRoot, server);
+    throw new CliError(`Rig server request failed: ${error instanceof Error ? error.message : String(error)}
+${failure.contextLine}`, 1, { hint: failure.hint });
+  }
   const text = await response.text();
   const payload = text.trim().length > 0 ? (() => {
     try {
@@ -247,11 +672,26 @@ async function requestServerJson(context, pathname, init = {}) {
   })() : null;
   if (!response.ok) {
     const diagnostics = diagnosticMessage(payload);
-    const detail = diagnostics ?? (text || response.statusText);
-    throw new CliError2(`Rig server request failed (${response.status}): ${detail}`, 1);
+    const rawDetail = diagnostics ?? (text || response.statusText);
+    const detail = diagnostics ? rawDetail : rawDetail.split(`
+`).map((line) => line.trim()).find((line) => line.length > 0)?.slice(0, 200) ?? response.statusText;
+    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;
 }
+var RESUMABLE_RUN_STATUSES = new Set([
+  "created",
+  "preparing",
+  "running",
+  "validating",
+  "reviewing",
+  "stopped",
+  "failed",
+  "needs-attention",
+  "needs_attention"
+]);
 async function submitTaskRunViaServer(context, input) {
   const isTaskRun = Boolean(input.taskId);
   const endpoint = isTaskRun ? "/api/runs/task" : "/api/runs/adhoc";
@@ -275,18 +715,21 @@ 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 };
 }
 
 // packages/cli/src/commands/server.ts
 async function executeServer(context, args, options) {
-  const [command = "start", ...rest] = args;
+  const [command = "status", ...rest] = args;
+  if (["status", "list", "add", "use"].includes(command)) {
+    return executeConnectionCommand(context, [command, ...rest], { group: "server", interactiveUse: true });
+  }
   switch (command) {
     case "start": {
       let pending = rest;
@@ -298,8 +741,9 @@ async function executeServer(context, args, options) {
       pending = pollResult.rest;
       const authTokenResult = takeOption(pending, "--auth-token");
       pending = authTokenResult.rest;
-      requireNoExtraArgs(pending, "bun run rig server start [--host <host>] [--port <n>] [--poll-ms <n>] [--auth-token <token>]");
-      const commandParts = ["rig-server", "start"];
+      requireNoExtraArgs(pending, "rig server start [--host <host>] [--port <n>] [--poll-ms <n>] [--auth-token <token>]");
+      const serverCommand = resolveRigServerCommand(context.projectRoot);
+      const commandParts = [serverCommand.command, ...serverCommand.commandArgs, "start"];
       if (hostResult.value) {
         commandParts.push("--host", hostResult.value);
       }
@@ -316,13 +760,14 @@ async function executeServer(context, args, options) {
       return { ok: true, group: "server", command };
     }
     case "events":
-      throw new CliError2("server events is not supported by the CLI wrapper. Use `rig inspector stream` for bounded event streaming, or start the server with `rig server start`.", 2);
+      throw new CliError("server events is not supported by the CLI wrapper. Use `rig inspector stream` for bounded event streaming, or start the server with `rig server start`.", 2);
     case "notify-test": {
       let pending = rest;
       const eventResult = takeOption(pending, "--event");
       pending = eventResult.rest;
-      requireNoExtraArgs(pending, "bun run rig server notify-test [--event <type>]");
-      const commandParts = ["rig-server", "notify-test"];
+      requireNoExtraArgs(pending, "rig server notify-test [--event <type>]");
+      const serverCommand = resolveRigServerCommand(context.projectRoot);
+      const commandParts = [serverCommand.command, ...serverCommand.commandArgs, "notify-test"];
       if (eventResult.value) {
         commandParts.push("--event", eventResult.value);
       }
@@ -349,9 +794,9 @@ async function executeServer(context, args, options) {
       pending = dirtyBaselineResult.rest;
       const prResult = takeOption(pending, "--pr");
       pending = prResult.rest;
-      requireNoExtraArgs(pending, "bun run rig --run-id <run-id> server task-run [--task <id>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--dirty-baseline head|dirty-snapshot] [--pr auto|ask|off]");
+      requireNoExtraArgs(pending, "rig --run-id <run-id> server task-run [--task <id>] [--title <text>] [--runtime-adapter claude-code|codex|pi] [--model <model>] [--runtime-mode <mode>] [--interaction-mode <mode>] [--initial-prompt <text>] [--dirty-baseline head|dirty-snapshot] [--pr auto|ask|off]");
       if (!taskResult.value && !initialPromptResult.value && !titleResult.value) {
-        throw new CliError2("server task-run requires either --task <id> or --initial-prompt/--title for an ad hoc run.", 2);
+        throw new CliError("server task-run requires either --task <id> or --initial-prompt/--title for an ad hoc run.", 2);
       }
       const input = {
         runId: context.runId,
@@ -378,7 +823,7 @@ async function executeServer(context, args, options) {
       };
     }
     default:
-      throw new CliError2(`Unknown server command: ${command}`);
+      throw new CliError(`Unknown server command: ${command}`, 1, { hint: "Run `rig server --help` \u2014 primary commands are status|list|add|use|start." });
   }
 }
 export {