@h-rig/cli 0.0.6-alpha.1 → 0.0.6-alpha.100

package/dist/src/commands/remote.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 takeFlag(args, flag) {
   const rest = [];
   let value = false;
@@ -27,7 +34,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;
@@ -53,20 +60,846 @@ Usage: ${usage}`);
   return taskId;
 }
 
-// packages/cli/src/commands/remote.ts
-import {
-  doctorManagedRemoteEndpoints,
-  listManagedRemoteEndpoints,
-  matchesEventFilter,
-  migrateManagedRemoteEndpoints,
-  RemoteCliError,
-  RemoteWsClient,
-  removeManagedRemoteEndpoint,
-  resolveRemoteEndpoint,
-  summarizeMessage,
-  updateManagedRemoteEndpointInAuthority,
-  upsertManagedRemoteEndpoint
-} from "@rig/runtime/control-plane/remote";
+// packages/runtime/src/control-plane/remote.ts
+import { randomUUID } from "crypto";
+import { chmodSync, existsSync as existsSync2, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "fs";
+import { homedir, tmpdir } from "os";
+import { dirname as dirname2, join, resolve as resolve2 } from "path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+
+// packages/runtime/src/control-plane/server-paths.ts
+import { existsSync } from "fs";
+import { dirname, resolve, relative } from "path";
+import { assertPathInsideRoot, assertSafeRunId, safePathSegment } from "@rig/shared/safe-identifiers";
+function normalizeOptionalString(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function resolveAuthorityPaths(projectRoot) {
+  const normalizedRoot = resolve(projectRoot);
+  const stateRoot = resolveAuthorityStateRoot(normalizedRoot);
+  const stateDir = resolveAuthorityStateDir(normalizedRoot);
+  return {
+    projectRoot: normalizedRoot,
+    harnessRoot: resolve(normalizedRoot, "rig"),
+    runsDir: resolve(stateRoot, "runs"),
+    remoteDir: resolve(stateRoot, "remote"),
+    stateDir,
+    remoteEndpointsPath: resolve(stateRoot, "remote", "endpoints.toml"),
+    remoteSecretsPath: resolve(stateDir, "remote-secrets.toml")
+  };
+}
+function resolveAuthorityStateRoot(projectRoot) {
+  const normalizedRoot = resolve(projectRoot);
+  const taskWorkspace = normalizeOptionalString(process.env.RIG_TASK_WORKSPACE);
+  if (taskWorkspace) {
+    return resolve(taskWorkspace, ".rig");
+  }
+  const stateDir = normalizeOptionalString(process.env.RIG_STATE_DIR);
+  if (stateDir) {
+    return dirname(resolve(stateDir));
+  }
+  const logsDir = normalizeOptionalString(process.env.RIG_LOGS_DIR);
+  if (logsDir) {
+    return dirname(resolve(logsDir));
+  }
+  const sessionFile = normalizeOptionalString(process.env.RIG_SESSION_FILE);
+  if (sessionFile) {
+    return dirname(dirname(resolve(sessionFile)));
+  }
+  const projectStateRoot = resolve(normalizedRoot, ".rig");
+  if (existsSync(projectStateRoot)) {
+    return projectStateRoot;
+  }
+  return resolve(normalizedRoot, ".rig");
+}
+function resolveAuthorityStateDir(projectRoot) {
+  const explicit = normalizeOptionalString(process.env.RIG_STATE_DIR);
+  if (explicit) {
+    return resolve(explicit);
+  }
+  return resolve(resolveAuthorityStateRoot(projectRoot), "state");
+}
+
+// packages/runtime/src/control-plane/remote.ts
+var DEFAULT_REMOTE_PORT = 7890;
+var DEFAULT_RIG_BACKBONE_HOST = "where.rig-does.work";
+var DEFAULT_RIG_RELAY_URL = `wss://${DEFAULT_RIG_BACKBONE_HOST}`;
+var DEFAULT_RIG_REGISTRY_URL = `https://${DEFAULT_RIG_BACKBONE_HOST}/registry`;
+var DEFAULT_TIMEOUTS = {
+  connectMs: 5000,
+  authMs: 5000,
+  requestMs: 30000,
+  subscriptionMs: 1e4
+};
+var REMOTES_CONFIG_PATH = join(homedir(), ".config", "rig", "remotes.toml");
+
+class RemoteCliError extends Error {
+  code;
+  exitCode;
+  details;
+  constructor(code, message, exitCode = 1, details) {
+    super(message);
+    this.name = "RemoteCliError";
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+function loadRemotesConfig(configPath = REMOTES_CONFIG_PATH) {
+  if (!existsSync2(configPath)) {
+    return { version: 1, remotes: {} };
+  }
+  try {
+    const content = readFileSync(configPath, "utf-8");
+    if (!content.trim()) {
+      return { version: 1, remotes: {} };
+    }
+    const parsed = parseToml(content);
+    return {
+      version: parsed.version ?? 1,
+      remotes: parsed.remotes ?? {}
+    };
+  } catch (error) {
+    throw new RemoteCliError("RIG_REMOTE_CONFIG_PARSE_ERROR", `Failed to parse remotes config at ${configPath}: ${error instanceof Error ? error.message : String(error)}`, 2, { configPath });
+  }
+}
+function saveRemotesConfig(config, configPath = REMOTES_CONFIG_PATH) {
+  mkdirSync(dirname2(configPath), { recursive: true });
+  writeFileSync(configPath, `${stringifyToml(config).trimEnd()}
+`, "utf-8");
+  try {
+    chmodSync(configPath, 384);
+  } catch {}
+}
+function readTomlFile(path, fallback) {
+  if (!existsSync2(path))
+    return fallback;
+  const raw = readFileSync(path, "utf8");
+  if (!raw.trim())
+    return fallback;
+  return parseToml(raw);
+}
+function writeTomlFile(path, value) {
+  mkdirSync(dirname2(path), { recursive: true });
+  writeFileSync(path, `${stringifyToml(value).trimEnd()}
+`, "utf8");
+}
+function normalizeStringArray(value) {
+  if (!Array.isArray(value))
+    return [];
+  return value.map((entry) => normalizeString(entry)).filter((entry) => entry !== "");
+}
+function normalizePort(value) {
+  const port = typeof value === "number" ? value : Number(value);
+  return Number.isInteger(port) && port > 0 && port <= 65535 ? port : DEFAULT_REMOTE_PORT;
+}
+function loadRemoteEndpointsToml(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const parsed = readTomlFile(paths.remoteEndpointsPath, { version: 1, endpoints: {} });
+  return {
+    version: parsed.version ?? 1,
+    endpoints: parsed.endpoints ?? {}
+  };
+}
+function loadRemoteSecretsToml(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const parsed = readTomlFile(paths.remoteSecretsPath, { version: 1, secrets: {} });
+  return {
+    version: parsed.version ?? 1,
+    secrets: parsed.secrets ?? {}
+  };
+}
+function saveRemoteEndpointsToml(projectRoot, payload) {
+  writeTomlFile(resolveAuthorityPaths(projectRoot).remoteEndpointsPath, payload);
+}
+function saveRemoteSecretsToml(projectRoot, payload) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  writeTomlFile(paths.remoteSecretsPath, payload);
+  try {
+    chmodSync(paths.remoteSecretsPath, 384);
+  } catch {}
+}
+function listAuthorityRemoteEndpoints(projectRoot) {
+  const endpoints = loadRemoteEndpointsToml(projectRoot).endpoints ?? {};
+  const secrets = loadRemoteSecretsToml(projectRoot).secrets ?? {};
+  return Object.values(endpoints).map((entry) => {
+    const token = secrets[entry.secret_ref] ?? "";
+    return {
+      id: entry.id,
+      alias: entry.alias,
+      host: entry.host,
+      port: normalizePort(entry.port),
+      token,
+      autoConnect: Boolean(entry.auto_connect),
+      addedAt: entry.created_at,
+      updatedAt: entry.updated_at,
+      lastConnectedAt: normalizeString(entry.last_connected_at) || null,
+      labels: normalizeStringArray(entry.labels),
+      capabilities: normalizeStringArray(entry.capabilities),
+      transport: normalizeString(entry.transport) || "websocket",
+      secretRef: entry.secret_ref
+    };
+  }).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+function nextRemoteEndpointRecord(input) {
+  const timestamp = new Date().toISOString();
+  const secretRef = input.existing?.secret_ref ?? randomUUID();
+  return {
+    record: {
+      id: input.endpointId ?? input.existing?.id ?? randomUUID(),
+      alias: input.alias,
+      host: input.host,
+      port: normalizePort(input.port),
+      transport: normalizeString(input.transport) || normalizeString(input.existing?.transport) || "websocket",
+      auto_connect: input.autoConnect ?? input.existing?.auto_connect ?? false,
+      labels: input.labels ?? normalizeStringArray(input.existing?.labels),
+      capabilities: input.capabilities ?? normalizeStringArray(input.existing?.capabilities),
+      secret_ref: secretRef,
+      created_at: input.existing?.created_at ?? timestamp,
+      updated_at: timestamp,
+      last_connected_at: input.existing?.last_connected_at ?? null
+    },
+    secretRef
+  };
+}
+function upsertAuthorityRemoteEndpoint(projectRoot, input) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const existing = Object.values(endpointsToml.endpoints ?? {}).find((entry) => entry.alias === input.alias) ?? null;
+  const { record, secretRef } = nextRemoteEndpointRecord({
+    endpointId: input.endpointId,
+    existing,
+    alias: input.alias,
+    host: input.host,
+    port: input.port,
+    token: input.token,
+    autoConnect: input.autoConnect,
+    transport: input.transport,
+    labels: input.labels,
+    capabilities: input.capabilities
+  });
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [record.id]: record
+  };
+  secretsToml.secrets = {
+    ...secretsToml.secrets ?? {},
+    [secretRef]: input.token
+  };
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+  saveRemoteSecretsToml(projectRoot, secretsToml);
+  return listAuthorityRemoteEndpoints(projectRoot).find((entry) => entry.id === record.id);
+}
+function updateAuthorityRemoteEndpoint(projectRoot, input) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const current = Object.values(endpointsToml.endpoints ?? {}).find((entry) => input.endpointId && entry.id === input.endpointId || input.alias && entry.alias === input.alias);
+  if (!current)
+    return null;
+  const record = {
+    ...current,
+    alias: normalizeString(input.alias) || current.alias,
+    host: normalizeString(input.host) || current.host,
+    port: input.port !== undefined ? normalizePort(input.port) : current.port,
+    auto_connect: input.autoConnect ?? current.auto_connect,
+    transport: normalizeString(input.transport) || current.transport,
+    labels: input.labels ?? normalizeStringArray(current.labels),
+    capabilities: input.capabilities ?? normalizeStringArray(current.capabilities),
+    updated_at: new Date().toISOString()
+  };
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [record.id]: record
+  };
+  if (input.token !== undefined) {
+    secretsToml.secrets = {
+      ...secretsToml.secrets ?? {},
+      [record.secret_ref]: input.token
+    };
+  }
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+  saveRemoteSecretsToml(projectRoot, secretsToml);
+  return listAuthorityRemoteEndpoints(projectRoot).find((entry) => entry.id === record.id) ?? null;
+}
+function removeAuthorityRemoteEndpoint(projectRoot, endpointIdOrAlias) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const secretsToml = loadRemoteSecretsToml(projectRoot);
+  const entry = Object.values(endpointsToml.endpoints ?? {}).find((candidate) => candidate.id === endpointIdOrAlias || candidate.alias === endpointIdOrAlias);
+  if (!entry)
+    return false;
+  const nextEndpoints = { ...endpointsToml.endpoints ?? {} };
+  delete nextEndpoints[entry.id];
+  const nextSecrets = { ...secretsToml.secrets ?? {} };
+  delete nextSecrets[entry.secret_ref];
+  saveRemoteEndpointsToml(projectRoot, { version: endpointsToml.version ?? 1, endpoints: nextEndpoints });
+  saveRemoteSecretsToml(projectRoot, { version: secretsToml.version ?? 1, secrets: nextSecrets });
+  return true;
+}
+function markAuthorityRemoteEndpointConnected(projectRoot, endpointId, connectedAt = new Date().toISOString()) {
+  const endpointsToml = loadRemoteEndpointsToml(projectRoot);
+  const entry = endpointsToml.endpoints?.[endpointId];
+  if (!entry)
+    return;
+  endpointsToml.endpoints = {
+    ...endpointsToml.endpoints ?? {},
+    [endpointId]: {
+      ...entry,
+      last_connected_at: connectedAt,
+      updated_at: connectedAt
+    }
+  };
+  saveRemoteEndpointsToml(projectRoot, endpointsToml);
+}
+function importLegacyRemoteEndpoints(projectRoot, legacyPath = REMOTES_CONFIG_PATH) {
+  if (!existsSync2(legacyPath)) {
+    return { imported: 0, skipped: 0, sourcePath: legacyPath };
+  }
+  const parsed = readTomlFile(legacyPath, { version: 1, remotes: {} });
+  let imported = 0;
+  let skipped = 0;
+  for (const [alias, entry] of Object.entries(parsed.remotes ?? {})) {
+    const host = normalizeString(entry.host);
+    const token = normalizeString(entry.token);
+    if (!host || !token) {
+      skipped += 1;
+      continue;
+    }
+    upsertAuthorityRemoteEndpoint(projectRoot, {
+      alias,
+      host,
+      port: normalizePort(entry.port),
+      token
+    });
+    imported += 1;
+  }
+  return { imported, skipped, sourcePath: legacyPath };
+}
+function doctorAuthorityRemoteEndpoints(projectRoot) {
+  const paths = resolveAuthorityPaths(projectRoot);
+  const endpoints = loadRemoteEndpointsToml(projectRoot).endpoints ?? {};
+  const secrets = loadRemoteSecretsToml(projectRoot).secrets ?? {};
+  const missingSecrets = Object.values(endpoints).filter((entry) => !normalizeString(secrets[entry.secret_ref])).map((entry) => entry.alias);
+  const warnings = [];
+  if (!existsSync2(paths.remoteEndpointsPath)) {
+    warnings.push("Remote endpoint manifest is missing.");
+  }
+  if (!existsSync2(paths.remoteSecretsPath)) {
+    warnings.push("Remote secret store is missing.");
+  }
+  return {
+    manifestPath: paths.remoteEndpointsPath,
+    secretsPath: paths.remoteSecretsPath,
+    endpointCount: Object.keys(endpoints).length,
+    missingSecrets,
+    warnings
+  };
+}
+function listManagedRemoteEndpoints(configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    return listAuthorityRemoteEndpoints(projectRoot).map((entry) => ({
+      id: entry.id,
+      alias: entry.alias,
+      host: entry.host,
+      port: entry.port,
+      token: entry.token,
+      addedAt: entry.addedAt,
+      lastConnected: entry.lastConnectedAt
+    }));
+  }
+  const config = loadRemotesConfig(configPath);
+  return Object.entries(config.remotes ?? {}).map(([alias, entry]) => ({
+    id: alias,
+    alias,
+    host: normalizeString(entry.host) || "",
+    port: Number.isFinite(entry.port) ? Number(entry.port) : DEFAULT_REMOTE_PORT,
+    token: normalizeString(entry.token) || "",
+    addedAt: normalizeString(entry.addedAt) || null,
+    lastConnected: normalizeString(entry.lastConnected) || null
+  })).sort((left, right) => left.alias.localeCompare(right.alias));
+}
+function upsertManagedRemoteEndpoint(input, configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    const saved = upsertAuthorityRemoteEndpoint(projectRoot, {
+      ...input,
+      token: input.token ?? ""
+    });
+    return {
+      id: saved.id,
+      alias: saved.alias,
+      host: saved.host,
+      port: saved.port,
+      token: saved.token,
+      addedAt: saved.addedAt,
+      lastConnected: saved.lastConnectedAt
+    };
+  }
+  const config = loadRemotesConfig(configPath);
+  const existing = config.remotes?.[input.alias];
+  const nextEntry = {
+    host: input.host,
+    port: input.port,
+    token: input.token,
+    addedAt: normalizeString(existing?.addedAt) || new Date().toISOString(),
+    ...normalizeString(existing?.lastConnected) ? { lastConnected: normalizeString(existing?.lastConnected) } : {}
+  };
+  const nextConfig = {
+    version: config.version ?? 1,
+    remotes: {
+      ...config.remotes ?? {},
+      [input.alias]: nextEntry
+    }
+  };
+  saveRemotesConfig(nextConfig, configPath);
+  return {
+    id: input.alias,
+    alias: input.alias,
+    host: input.host,
+    port: input.port,
+    token: input.token ?? "",
+    addedAt: nextEntry.addedAt ?? null,
+    lastConnected: nextEntry.lastConnected ?? null
+  };
+}
+function removeManagedRemoteEndpoint(alias, configPath = REMOTES_CONFIG_PATH, projectRoot) {
+  if (projectRoot) {
+    return removeAuthorityRemoteEndpoint(projectRoot, alias);
+  }
+  const config = loadRemotesConfig(configPath);
+  if (!config.remotes?.[alias]) {
+    return false;
+  }
+  const nextRemotes = { ...config.remotes ?? {} };
+  delete nextRemotes[alias];
+  saveRemotesConfig({
+    version: config.version ?? 1,
+    remotes: nextRemotes
+  }, configPath);
+  return true;
+}
+function resolveRemoteEndpoint(options) {
+  const env = options.env ?? process.env;
+  const envHost = normalizeString(env.RIG_REMOTE_HOST);
+  const envToken = normalizeString(env.RIG_REMOTE_TOKEN);
+  const envPort = parsePort(normalizeString(env.RIG_REMOTE_PORT), "RIG_REMOTE_PORT");
+  const envAlias = normalizeString(env.RIG_REMOTE_ALIAS);
+  const explicitHost = normalizeString(options.host);
+  const explicitToken = normalizeString(options.token);
+  const explicitPort = parsePort(normalizeString(options.port), "--port");
+  const explicitProvided = Boolean(explicitHost || explicitToken || explicitPort !== null);
+  const requestedAlias = normalizeString(options.remoteAlias) || envAlias;
+  let endpoint = {
+    source: "env",
+    host: envHost || "",
+    port: envPort ?? DEFAULT_REMOTE_PORT,
+    token: envToken || "",
+    configPath: REMOTES_CONFIG_PATH
+  };
+  if (requestedAlias) {
+    if (options.projectRoot) {
+      const remote = listAuthorityRemoteEndpoints(options.projectRoot).find((entry) => entry.alias === requestedAlias);
+      if (!remote) {
+        const configPath = resolveAuthorityPaths(options.projectRoot).remoteEndpointsPath;
+        throw new RemoteCliError("RIG_REMOTE_ALIAS_NOT_FOUND", `Remote alias '${requestedAlias}' was not found in ${configPath}.`, 2, { alias: requestedAlias, configPath });
+      }
+      endpoint = {
+        source: "alias",
+        alias: requestedAlias,
+        host: remote.host,
+        port: remote.port,
+        token: remote.token,
+        configPath: resolveAuthorityPaths(options.projectRoot).remoteEndpointsPath
+      };
+    } else {
+      const config = loadRemotesConfig();
+      const remote = config.remotes?.[requestedAlias];
+      if (!remote) {
+        throw new RemoteCliError("RIG_REMOTE_ALIAS_NOT_FOUND", `Remote alias '${requestedAlias}' was not found in ${REMOTES_CONFIG_PATH}.`, 2, { alias: requestedAlias, configPath: REMOTES_CONFIG_PATH });
+      }
+      endpoint = {
+        source: "alias",
+        alias: requestedAlias,
+        host: normalizeString(remote.host) || "",
+        port: Number.isFinite(remote.port) ? Number(remote.port) : DEFAULT_REMOTE_PORT,
+        token: normalizeString(remote.token) || "",
+        configPath: REMOTES_CONFIG_PATH
+      };
+    }
+  }
+  if (explicitProvided) {
+    endpoint = {
+      ...endpoint,
+      source: "flags",
+      host: explicitHost || endpoint.host,
+      port: explicitPort ?? endpoint.port,
+      token: explicitToken || endpoint.token
+    };
+  }
+  if (!endpoint.host) {
+    throw new RemoteCliError("RIG_REMOTE_HOST_REQUIRED", "Remote host is required. Pass --host, --remote <alias>, or set RIG_REMOTE_HOST.", 2);
+  }
+  if (!Number.isFinite(endpoint.port) || endpoint.port <= 0 || endpoint.port > 65535) {
+    throw new RemoteCliError("RIG_REMOTE_INVALID_PORT", `Invalid remote port: ${endpoint.port}.`, 2);
+  }
+  return endpoint;
+}
+
+class RemoteWsClient {
+  endpoint;
+  ws = null;
+  connected = false;
+  pending = new Map;
+  onEvent;
+  requestTimeoutMs;
+  connectTimeoutMs;
+  authTimeoutMs;
+  subscriptionTimeoutMs;
+  connectionToken = null;
+  connectionTokenExpiresAt = null;
+  tokenRefreshTimer = null;
+  constructor(endpoint, options = {}) {
+    this.endpoint = endpoint;
+    this.onEvent = options.onEvent;
+    this.connectTimeoutMs = options.connectTimeoutMs ?? DEFAULT_TIMEOUTS.connectMs;
+    this.authTimeoutMs = options.authTimeoutMs ?? DEFAULT_TIMEOUTS.authMs;
+    this.requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUTS.requestMs;
+    this.subscriptionTimeoutMs = options.subscriptionTimeoutMs ?? DEFAULT_TIMEOUTS.subscriptionMs;
+  }
+  setEventHandler(handler) {
+    this.onEvent = handler;
+  }
+  async connect() {
+    if (this.connected) {
+      return;
+    }
+    const url = `ws://${this.endpoint.host}:${this.endpoint.port}`;
+    await new Promise((resolve3, reject) => {
+      let authResolved = false;
+      let connectTimer = setTimeout(() => {
+        connectTimer = null;
+        reject(new RemoteCliError("RIG_REMOTE_CONNECT_TIMEOUT", `Timed out connecting to ${url} after ${this.connectTimeoutMs}ms.`, 3, { host: this.endpoint.host, port: this.endpoint.port, timeoutMs: this.connectTimeoutMs }));
+      }, this.connectTimeoutMs);
+      const ws = new WebSocket(url);
+      this.ws = ws;
+      ws.onopen = () => {
+        const authMessage = {
+          type: "auth",
+          id: crypto.randomUUID(),
+          timestamp: new Date().toISOString(),
+          token: this.connectionToken || this.endpoint.token,
+          tokenType: this.connectionToken ? "connection" : "server"
+        };
+        let authTimer = setTimeout(() => {
+          authTimer = null;
+          reject(new RemoteCliError("RIG_REMOTE_AUTH_TIMEOUT", `Timed out waiting for auth response from ${url} after ${this.authTimeoutMs}ms.`, 3, { host: this.endpoint.host, port: this.endpoint.port, timeoutMs: this.authTimeoutMs }));
+        }, this.authTimeoutMs);
+        ws.send(JSON.stringify(authMessage));
+        const originalOnMessage = ws.onmessage;
+        ws.onmessage = (event) => {
+          const message = parseIncomingMessage(event.data);
+          if (!message) {
+            return;
+          }
+          if (message.type === "auth_response" && !authResolved) {
+            authResolved = true;
+            if (connectTimer) {
+              clearTimeout(connectTimer);
+              connectTimer = null;
+            }
+            if (authTimer) {
+              clearTimeout(authTimer);
+              authTimer = null;
+            }
+            const auth = message;
+            if (!auth.success) {
+              reject(new RemoteCliError("RIG_REMOTE_AUTH_FAILED", auth.error || "Remote authentication failed.", 3, { host: this.endpoint.host, port: this.endpoint.port }));
+              return;
+            }
+            if (auth.connectionToken && auth.connectionTokenExpiresAt) {
+              this.connectionToken = auth.connectionToken;
+              this.connectionTokenExpiresAt = auth.connectionTokenExpiresAt;
+              this.scheduleTokenRefresh();
+            }
+            if (this.endpoint.configPath.endsWith("endpoints.toml")) {
+              const projectRoot = dirname2(dirname2(dirname2(this.endpoint.configPath)));
+              try {
+                markAuthorityRemoteEndpointConnected(projectRoot, this.endpoint.alias ? listAuthorityRemoteEndpoints(projectRoot).find((entry) => entry.alias === this.endpoint.alias)?.id ?? "" : "");
+              } catch {}
+            }
+            this.connected = true;
+            ws.onmessage = (event2) => {
+              const next = parseIncomingMessage(event2.data);
+              if (!next) {
+                return;
+              }
+              this.routeMessage(next);
+            };
+            resolve3();
+            return;
+          }
+          if (typeof originalOnMessage === "function") {
+            originalOnMessage.call(ws, event);
+          }
+        };
+      };
+      ws.onerror = () => {
+        if (connectTimer) {
+          clearTimeout(connectTimer);
+          connectTimer = null;
+        }
+        if (!authResolved) {
+          reject(new RemoteCliError("RIG_REMOTE_CONNECT_FAILED", `Failed to connect to ${url}.`, 3, { host: this.endpoint.host, port: this.endpoint.port }));
+        }
+      };
+      ws.onclose = () => {
+        this.connected = false;
+        this.clearPending("Connection closed");
+      };
+    });
+  }
+  disconnect() {
+    this.connected = false;
+    this.clearTokenRefreshTimer();
+    this.clearPending("Connection closed");
+    if (this.ws) {
+      try {
+        this.ws.close();
+      } catch {}
+      this.ws = null;
+    }
+  }
+  async subscribe(eventTypes = []) {
+    const message = { type: "subscribe" };
+    if (eventTypes.length > 0) {
+      message.eventTypes = eventTypes;
+    }
+    const response = await this.request(message, this.subscriptionTimeoutMs);
+    return expectType(response, "operation_result");
+  }
+  async unsubscribe() {
+    return expectType(await this.request({ type: "unsubscribe" }), "operation_result");
+  }
+  async getState() {
+    return expectType(await this.request({ type: "get_state" }), "state_response");
+  }
+  async getTasks() {
+    return expectType(await this.request({ type: "get_tasks" }), "tasks_response");
+  }
+  async pause() {
+    return expectType(await this.request({ type: "pause" }), "operation_result");
+  }
+  async resume() {
+    return expectType(await this.request({ type: "resume" }), "operation_result");
+  }
+  async interrupt() {
+    return expectType(await this.request({ type: "interrupt" }), "operation_result");
+  }
+  async continueExecution() {
+    return expectType(await this.request({ type: "continue" }), "operation_result");
+  }
+  async refreshTasks() {
+    return expectType(await this.request({ type: "refresh_tasks" }), "operation_result");
+  }
+  async addIterations(count) {
+    return expectType(await this.request({ type: "add_iterations", count }), "operation_result");
+  }
+  async removeIterations(count) {
+    return expectType(await this.request({ type: "remove_iterations", count }), "operation_result");
+  }
+  async getPromptPreview(taskId) {
+    return expectType(await this.request({ type: "get_prompt_preview", taskId }), "prompt_preview_response");
+  }
+  async getIterationOutput(taskId) {
+    return expectType(await this.request({ type: "get_iteration_output", taskId }), "iteration_output_response");
+  }
+  async startOrchestration(options) {
+    return expectType(await this.request({
+      type: "orchestrate:start",
+      maxWorkers: options.maxWorkers,
+      maxIterations: options.maxIterations,
+      directMerge: options.directMerge
+    }), "orchestrate:start_response");
+  }
+  async pauseOrchestration(orchestrationId) {
+    return expectType(await this.request({ type: "orchestrate:pause", orchestrationId }), "operation_result");
+  }
+  async resumeOrchestration(orchestrationId) {
+    return expectType(await this.request({ type: "orchestrate:resume", orchestrationId }), "operation_result");
+  }
+  async stopOrchestration(orchestrationId) {
+    return expectType(await this.request({ type: "orchestrate:stop", orchestrationId }), "operation_result");
+  }
+  async getOrchestrationState(orchestrationId) {
+    return expectType(await this.request({ type: "orchestrate:get_state", orchestrationId }), "orchestrate:state_response");
+  }
+  async ping() {
+    return this.request({ type: "ping" });
+  }
+  async request(payload, timeoutMs = this.requestTimeoutMs) {
+    if (!this.connected || !this.ws) {
+      throw new RemoteCliError("RIG_REMOTE_NOT_CONNECTED", "Remote client is not connected.", 3);
+    }
+    const id = crypto.randomUUID();
+    const message = {
+      ...payload,
+      id,
+      timestamp: new Date().toISOString()
+    };
+    return await new Promise((resolve3, reject) => {
+      const timeout = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new RemoteCliError("RIG_REMOTE_REQUEST_TIMEOUT", `Timed out waiting for response to '${String(payload.type)}' after ${timeoutMs}ms.`, 3, { requestType: payload.type, requestId: id, timeoutMs }));
+      }, timeoutMs);
+      this.pending.set(id, { resolve: resolve3, reject, timeout });
+      this.ws?.send(JSON.stringify(message));
+    });
+  }
+  routeMessage(message) {
+    if (message.id && this.pending.has(message.id)) {
+      const pending = this.pending.get(message.id);
+      if (pending) {
+        clearTimeout(pending.timeout);
+        this.pending.delete(message.id);
+        pending.resolve(message);
+      }
+      return;
+    }
+    if (message.type === "token_refresh_response") {
+      const token = normalizeString(message.connectionToken);
+      const expiresAt = normalizeString(message.connectionTokenExpiresAt);
+      if (token && expiresAt) {
+        this.connectionToken = token;
+        this.connectionTokenExpiresAt = expiresAt;
+        this.scheduleTokenRefresh();
+      }
+    }
+    this.onEvent?.({ receivedAt: new Date().toISOString(), message });
+  }
+  scheduleTokenRefresh() {
+    this.clearTokenRefreshTimer();
+    if (!this.connectionToken || !this.connectionTokenExpiresAt || !this.ws || !this.connected) {
+      return;
+    }
+    const expiresAt = new Date(this.connectionTokenExpiresAt).getTime();
+    if (!Number.isFinite(expiresAt)) {
+      return;
+    }
+    const refreshAt = expiresAt - 60 * 60 * 1000;
+    const delay = Math.max(0, refreshAt - Date.now());
+    this.tokenRefreshTimer = setTimeout(() => {
+      if (!this.connected || !this.ws || !this.connectionToken) {
+        return;
+      }
+      const refreshMessage = {
+        type: "token_refresh",
+        id: crypto.randomUUID(),
+        timestamp: new Date().toISOString(),
+        connectionToken: this.connectionToken
+      };
+      this.ws.send(JSON.stringify(refreshMessage));
+    }, delay);
+  }
+  clearTokenRefreshTimer() {
+    if (this.tokenRefreshTimer) {
+      clearTimeout(this.tokenRefreshTimer);
+      this.tokenRefreshTimer = null;
+    }
+  }
+  clearPending(reason) {
+    for (const [requestId, pending] of this.pending.entries()) {
+      clearTimeout(pending.timeout);
+      pending.reject(new RemoteCliError("RIG_REMOTE_REQUEST_CANCELLED", `${reason} (request ${requestId}).`, 3, { requestId }));
+      this.pending.delete(requestId);
+    }
+  }
+}
+function matchesEventFilter(message, expectedType) {
+  if (!expectedType) {
+    return true;
+  }
+  if (message.type === expectedType) {
+    return true;
+  }
+  if (message.type === "engine_event") {
+    const eventType = normalizeString(message.event?.type);
+    return eventType === expectedType;
+  }
+  if (message.type === "parallel_event") {
+    const eventType = normalizeString(message.event?.type);
+    return eventType === expectedType;
+  }
+  return false;
+}
+function summarizeMessage(message) {
+  if (message.type === "pong") {
+    return "pong";
+  }
+  if (message.type === "engine_event") {
+    const eventType = normalizeString(message.event?.type);
+    return eventType ? `engine_event:${eventType}` : "engine_event";
+  }
+  if (message.type === "parallel_event") {
+    const eventType = normalizeString(message.event?.type);
+    const orchestrationId = normalizeString(message.orchestrationId);
+    return orchestrationId ? `parallel_event:${eventType || "unknown"}:${orchestrationId}` : `parallel_event:${eventType || "unknown"}`;
+  }
+  return message.type;
+}
+function migrateManagedRemoteEndpoints(projectRoot, legacyPath = REMOTES_CONFIG_PATH) {
+  return importLegacyRemoteEndpoints(projectRoot, legacyPath);
+}
+function doctorManagedRemoteEndpoints(projectRoot) {
+  return doctorAuthorityRemoteEndpoints(projectRoot);
+}
+function updateManagedRemoteEndpointInAuthority(projectRoot, input) {
+  const updated = updateAuthorityRemoteEndpoint(projectRoot, input);
+  if (!updated)
+    return null;
+  return {
+    id: updated.id,
+    alias: updated.alias,
+    host: updated.host,
+    port: updated.port,
+    token: updated.token,
+    addedAt: updated.addedAt,
+    lastConnected: updated.lastConnectedAt
+  };
+}
+function normalizeString(value) {
+  if (!value) {
+    return "";
+  }
+  return value.trim();
+}
+function parsePort(value, label) {
+  if (!value) {
+    return null;
+  }
+  const parsed = Number.parseInt(value, 10);
+  if (!Number.isFinite(parsed) || parsed <= 0 || parsed > 65535) {
+    throw new RemoteCliError("RIG_REMOTE_INVALID_PORT", `Invalid port for ${label}: ${value}.`, 2, { label, value });
+  }
+  return parsed;
+}
+function parseIncomingMessage(raw) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object" || typeof parsed.type !== "string") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function expectType(message, expectedType) {
+  if (message.type !== expectedType) {
+    throw new RemoteCliError("RIG_REMOTE_UNEXPECTED_RESPONSE", `Unexpected response type: ${message.type}. Expected ${expectedType}.`, 3, { expectedType, actualType: message.type, message });
+  }
+  return message;
+}
 
 // packages/cli/src/commands/_parsers.ts
 function parseOptionalPositiveInt(value, option) {
@@ -75,17 +908,17 @@ function parseOptionalPositiveInt(value, option) {
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
 function parseRequiredPositiveInt(value, option) {
   if (!value) {
-    throw new CliError2(`Missing value for ${option}.`);
+    throw new CliError(`Missing value for ${option}.`, 1, { hint: `Provide a value after ${option}, e.g. \`${option} 10\`.` });
   }
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed) || parsed <= 0) {
-    throw new CliError2(`Invalid ${option} value: ${value}`);
+    throw new CliError(`Invalid ${option} value: ${value}`, 1, { hint: `Pass a positive integer, e.g. \`${option} 10\`.` });
   }
   return parsed;
 }
@@ -134,7 +967,7 @@ async function executeRemote(context, args) {
     const [subcommand = "list", ...subRest] = rest;
     switch (subcommand) {
       case "list": {
-        requireNoExtraArgs(subRest, "bun run rig remote endpoint list");
+        requireNoExtraArgs(subRest, "rig remote endpoint list");
         const endpoints = listManagedRemoteEndpoints(undefined, context.projectRoot);
         const redactedEndpoints = endpoints.map((endpoint2) => redactRemoteEndpoint(endpoint2));
         if (context.outputMode === "text") {
@@ -158,9 +991,9 @@ async function executeRemote(context, args) {
         pending2 = port.rest;
         const token = takeOption(pending2, "--token");
         pending2 = token.rest;
-        requireNoExtraArgs(pending2, "bun run rig remote endpoint add --alias <a> --host <h> --port <n> --token <t>");
+        requireNoExtraArgs(pending2, "rig remote endpoint add --alias <a> --host <h> --port <n> --token <t>");
         if (!alias.value || !host.value || !token.value || !port.value) {
-          throw new CliError2("remote endpoint add requires --alias, --host, --port, and --token.");
+          throw new CliError("remote endpoint add requires --alias, --host, --port, and --token.", 1, { hint: "Re-run as `rig remote endpoint add --alias <a> --host <h> --port <n> --token <t>`." });
         }
         const created = upsertManagedRemoteEndpoint({
           alias: alias.value,
@@ -185,9 +1018,9 @@ async function executeRemote(context, args) {
         pending2 = port.rest;
         const token = takeOption(pending2, "--token");
         pending2 = token.rest;
-        requireNoExtraArgs(pending2, "bun run rig remote endpoint update --id <id> [--alias <a>] [--host <h>] [--port <n>] [--token <t>]");
+        requireNoExtraArgs(pending2, "rig remote endpoint update --id <id> [--alias <a>] [--host <h>] [--port <n>] [--token <t>]");
         if (!endpointId.value && !alias.value) {
-          throw new CliError2("remote endpoint update requires --id <id> or --alias <a>.");
+          throw new CliError("remote endpoint update requires --id <id> or --alias <a>.", 1, { hint: "List endpoints with `rig remote endpoint list`, then pass --id or --alias." });
         }
         const updated = updateManagedRemoteEndpointInAuthority(context.projectRoot, {
           endpointId: endpointId.value || undefined,
@@ -197,7 +1030,7 @@ async function executeRemote(context, args) {
           token: token.value || undefined
         });
         if (!updated) {
-          throw new CliError2("Remote endpoint not found.", 2);
+          throw new CliError("Remote endpoint not found.", 2, { hint: "Run `rig remote endpoint list` to see configured endpoints." });
         }
         if (context.outputMode === "text") {
           console.log(`Updated remote endpoint ${updated.alias} -> ${updated.host}:${updated.port}`);
@@ -208,13 +1041,13 @@ async function executeRemote(context, args) {
         let pending2 = subRest;
         const alias = takeOption(pending2, "--alias");
         pending2 = alias.rest;
-        requireNoExtraArgs(pending2, "bun run rig remote endpoint remove --alias <a>");
+        requireNoExtraArgs(pending2, "rig remote endpoint remove --alias <a>");
         if (!alias.value) {
-          throw new CliError2("remote endpoint remove requires --alias.");
+          throw new CliError("remote endpoint remove requires --alias.", 1, { hint: "Run `rig remote endpoint list` to find the alias, then `rig remote endpoint remove --alias <a>`." });
         }
         const removed = removeManagedRemoteEndpoint(alias.value, undefined, context.projectRoot);
         if (!removed) {
-          throw new CliError2(`Remote endpoint alias not found: ${alias.value}`, 2);
+          throw new CliError(`Remote endpoint alias not found: ${alias.value}`, 2, { hint: "Run `rig remote endpoint list` to see configured endpoint aliases." });
         }
         if (context.outputMode === "text") {
           console.log(`Removed remote endpoint ${alias.value}`);
@@ -225,9 +1058,9 @@ async function executeRemote(context, args) {
         let pending2 = subRest;
         const alias = takeOption(pending2, "--alias");
         pending2 = alias.rest;
-        requireNoExtraArgs(pending2, "bun run rig remote endpoint test --alias <a>");
+        requireNoExtraArgs(pending2, "rig remote endpoint test --alias <a>");
         if (!alias.value) {
-          throw new CliError2("remote endpoint test requires --alias.");
+          throw new CliError("remote endpoint test requires --alias.", 1, { hint: "Run `rig remote endpoint list` to find the alias, then `rig remote endpoint test --alias <a>`." });
         }
         const endpoint2 = resolveRemoteEndpoint({ remoteAlias: alias.value, projectRoot: context.projectRoot });
         const client = new RemoteWsClient(endpoint2);
@@ -256,7 +1089,7 @@ async function executeRemote(context, args) {
         }
       }
       case "migrate": {
-        requireNoExtraArgs(subRest, "bun run rig remote endpoint migrate");
+        requireNoExtraArgs(subRest, "rig remote endpoint migrate");
         const result = migrateManagedRemoteEndpoints(context.projectRoot);
         if (context.outputMode === "text") {
           console.log(`Imported ${result.imported} endpoint(s) from ${result.sourcePath}${result.skipped > 0 ? `, skipped ${result.skipped}` : ""}.`);
@@ -264,7 +1097,7 @@ async function executeRemote(context, args) {
         return { ok: true, group: "remote", command: "endpoint migrate", details: result };
       }
       case "doctor": {
-        requireNoExtraArgs(subRest, "bun run rig remote endpoint doctor");
+        requireNoExtraArgs(subRest, "rig remote endpoint doctor");
         const result = doctorManagedRemoteEndpoints(context.projectRoot);
         if (context.outputMode === "text") {
           console.log(JSON.stringify(result, null, 2));
@@ -272,7 +1105,7 @@ async function executeRemote(context, args) {
         return { ok: true, group: "remote", command: "endpoint doctor", details: result };
       }
       default:
-        throw new CliError2(`Unknown remote endpoint command: ${subcommand}`);
+        throw new CliError(`Unknown remote endpoint command: ${subcommand}`, 1, { hint: "Run `rig remote --help` for endpoint commands (list|add|update|remove|test)." });
     }
   }
   let pending = rest;
@@ -317,17 +1150,17 @@ async function executeRemote(context, args) {
   try {
     switch (command) {
       case "test": {
-        requireNoExtraArgs(pending, "bun run rig remote test [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
+        requireNoExtraArgs(pending, "rig remote test [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
         const response = await withClient((client) => client.ping());
         return { ok: true, group: "remote", command, details: toDetails(response) };
       }
       case "status": {
-        requireNoExtraArgs(pending, "bun run rig remote status [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
+        requireNoExtraArgs(pending, "rig remote status [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
         const response = await withClient((client) => client.getState());
         return { ok: true, group: "remote", command, details: toDetails(response) };
       }
       case "tasks": {
-        requireNoExtraArgs(pending, "bun run rig remote tasks [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
+        requireNoExtraArgs(pending, "rig remote tasks [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
         const response = await withClient((client) => client.getTasks());
         return { ok: true, group: "remote", command, details: toDetails(response) };
       }
@@ -337,11 +1170,11 @@ async function executeRemote(context, args) {
         watchPending = secondsResult.rest;
         const eventResult = takeOption(watchPending, "--event");
         watchPending = eventResult.rest;
-        requireNoExtraArgs(watchPending, "bun run rig remote watch [--seconds <n>] [--event <type>] [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
+        requireNoExtraArgs(watchPending, "rig remote watch [--seconds <n>] [--event <type>] [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]");
         const seconds = parseOptionalPositiveInt(secondsResult.value, "--seconds");
         const eventFilter = eventResult.value || undefined;
         if (context.outputMode === "json" && !seconds) {
-          throw new CliError2("--json remote watch requires --seconds <n> to produce bounded output.", 2);
+          throw new CliError("--json remote watch requires --seconds <n> to produce bounded output.", 2, { hint: "Re-run as `rig remote watch --seconds 10 --json`." });
         }
         const captured = [];
         let dropped = 0;
@@ -406,7 +1239,7 @@ async function executeRemote(context, args) {
       case "stop":
       case "continue":
       case "refresh": {
-        requireNoExtraArgs(pending, `bun run rig remote ${command} [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
+        requireNoExtraArgs(pending, `rig remote ${command} [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
         const response = await withClient(async (client) => {
           switch (command) {
             case "pause":
@@ -429,7 +1262,7 @@ async function executeRemote(context, args) {
         let countPending = pending;
         const countResult = takeOption(countPending, "--count");
         countPending = countResult.rest;
-        requireNoExtraArgs(countPending, `bun run rig remote ${command} --count <n> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
+        requireNoExtraArgs(countPending, `rig remote ${command} --count <n> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
         const count = parseRequiredPositiveInt(countResult.value, "--count");
         const response = await withClient(async (client) => command === "add-iterations" ? await client.addIterations(count) : await client.removeIterations(count));
         assertRemoteOperationSuccess(command, response);
@@ -440,8 +1273,8 @@ async function executeRemote(context, args) {
         let taskPending = pending;
         const taskResult = takeOption(taskPending, "--task");
         taskPending = taskResult.rest;
-        requireNoExtraArgs(taskPending, `bun run rig remote ${command} --task <id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
-        const taskId = requireTask(taskResult.value, `bun run rig remote ${command} --task <id>`);
+        requireNoExtraArgs(taskPending, `rig remote ${command} --task <id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
+        const taskId = requireTask(taskResult.value, `rig remote ${command} --task <id>`);
         const response = await withClient(async (client) => command === "prompt-preview" ? await client.getPromptPreview(taskId) : await client.getIterationOutput(taskId));
         assertRemoteOperationSuccess(command, response);
         return { ok: true, group: "remote", command, details: toDetails(response) };
@@ -454,7 +1287,7 @@ async function executeRemote(context, args) {
         orchestrationPending = maxIterationsResult.rest;
         const directMergeResult = takeFlag(orchestrationPending, "--direct-merge");
         orchestrationPending = directMergeResult.rest;
-        requireNoExtraArgs(orchestrationPending, "bun run rig remote orchestrate-start [--max-workers <n>] [--max-iterations <n>] [--direct-merge]");
+        requireNoExtraArgs(orchestrationPending, "rig remote orchestrate-start [--max-workers <n>] [--max-iterations <n>] [--direct-merge]");
         const response = await withClient((client) => client.startOrchestration({
           maxWorkers: parseOptionalPositiveInt(maxWorkersResult.value, "--max-workers"),
           maxIterations: parseOptionalPositiveInt(maxIterationsResult.value, "--max-iterations"),
@@ -475,8 +1308,8 @@ async function executeRemote(context, args) {
         let orchestrationPending = pending;
         const idResult = takeOption(orchestrationPending, "--id");
         orchestrationPending = idResult.rest;
-        requireNoExtraArgs(orchestrationPending, `bun run rig remote ${command} --id <orch-id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
-        const orchestrationId = requireTask(idResult.value, `bun run rig remote ${command} --id <orch-id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
+        requireNoExtraArgs(orchestrationPending, `rig remote ${command} --id <orch-id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
+        const orchestrationId = requireTask(idResult.value, `rig remote ${command} --id <orch-id> [--remote <alias>] [--host <host>] [--port <n>] [--token <token>]`);
         const response = await withClient(async (client) => {
           switch (command) {
             case "orchestrate-pause":
@@ -493,11 +1326,11 @@ async function executeRemote(context, args) {
         return { ok: true, group: "remote", command, details: toDetails(response) };
       }
       default:
-        throw new CliError2(`Unknown remote command: ${command}`);
+        throw new CliError(`Unknown remote command: ${command}`, 1, { hint: "Run `rig remote --help` to list remote commands." });
     }
   } catch (error) {
     if (error instanceof RemoteCliError) {
-      throw new CliError2(`[${error.code}] ${error.message}`, error.exitCode);
+      throw new CliError(`[${error.code}] ${error.message}`, error.exitCode);
     }
     throw error;
   }