@h-rig/cli 0.0.6-alpha.88 → 0.0.6-alpha.89

package/dist/src/app-opentui/adapters/server.js

@@ -46,7 +46,8 @@ __export(exports__connection_state, {
   resolveGlobalConnectionsPath: () => resolveGlobalConnectionsPath,
   readRepoConnection: () => readRepoConnection,
   readGlobalConnections: () => readGlobalConnections,
-  isRemoteConnectionSelected: () => isRemoteConnectionSelected
+  isRemoteConnectionSelected: () => isRemoteConnectionSelected,
+  clearRepoServerProjectRoot: () => clearRepoServerProjectRoot
 });
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
 import { homedir } from "os";
@@ -130,12 +131,28 @@ function readRepoConnection(projectRoot) {
     selected,
     project: typeof record.project === "string" ? record.project : undefined,
     linkedAt: typeof record.linkedAt === "string" ? record.linkedAt : undefined,
-    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined
+    serverProjectRoot: typeof record.serverProjectRoot === "string" && record.serverProjectRoot.trim() ? record.serverProjectRoot.trim() : undefined,
+    serverProjectRootAlias: typeof record.serverProjectRootAlias === "string" && record.serverProjectRootAlias.trim() ? record.serverProjectRootAlias.trim() : undefined,
+    serverProjectRootBaseUrl: typeof record.serverProjectRootBaseUrl === "string" && record.serverProjectRootBaseUrl.trim() ? record.serverProjectRootBaseUrl.trim().replace(/\/+$/, "") : undefined
   };
 }
 function writeRepoConnection(projectRoot, state) {
   writeJsonFile(resolveRepoConnectionPath(projectRoot), state);
 }
+function rootAllowedForSelection(repo, connection) {
+  const root = repo.serverProjectRoot?.trim();
+  if (!root)
+    return;
+  if (connection.kind === "remote") {
+    if (repo.serverProjectRootAlias !== repo.selected)
+      return;
+    if (repo.serverProjectRootBaseUrl !== connection.baseUrl)
+      return;
+  } else if (repo.serverProjectRootAlias && repo.serverProjectRootAlias !== repo.selected) {
+    return;
+  }
+  return root;
+}
 function resolveSelectedConnection(projectRoot, options = {}) {
   const repo = readRepoConnection(projectRoot);
   if (!repo)
@@ -147,13 +164,41 @@ function resolveSelectedConnection(projectRoot, options = {}) {
   if (!connection) {
     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 };
+  return { alias: repo.selected, connection, serverProjectRoot: rootAllowedForSelection(repo, connection) };
 }
-function writeRepoServerProjectRoot(projectRoot, serverProjectRoot) {
+function writeRepoServerProjectRoot(projectRoot, serverProjectRoot, metadata = {}) {
   const repo = readRepoConnection(projectRoot);
   if (!repo)
     return;
-  writeRepoConnection(projectRoot, { ...repo, serverProjectRoot });
+  let inferred = metadata;
+  if (!inferred.alias || !inferred.baseUrl) {
+    try {
+      const selected = resolveSelectedConnection(projectRoot);
+      if (selected?.connection.kind === "remote") {
+        inferred = {
+          alias: inferred.alias ?? selected.alias,
+          baseUrl: inferred.baseUrl ?? selected.connection.baseUrl
+        };
+      }
+    } catch {}
+  }
+  writeRepoConnection(projectRoot, {
+    ...repo,
+    ...metadata.project ? { project: metadata.project } : {},
+    serverProjectRoot,
+    ...inferred.alias ? { serverProjectRootAlias: inferred.alias } : {},
+    ...inferred.baseUrl ? { serverProjectRootBaseUrl: inferred.baseUrl.replace(/\/+$/, "") } : {}
+  });
+}
+function clearRepoServerProjectRoot(projectRoot) {
+  const repo = readRepoConnection(projectRoot);
+  if (!repo)
+    return;
+  writeRepoConnection(projectRoot, {
+    selected: repo.selected,
+    ...repo.project ? { project: repo.project } : {},
+    ...repo.linkedAt ? { linkedAt: repo.linkedAt } : {}
+  });
 }
 function isRemoteConnectionSelected(projectRoot) {
   return resolveSelectedConnection(projectRoot)?.connection.kind === "remote";
@@ -180,12 +225,16 @@ __export(exports__server_client, {
   respondRunPiExtensionUiViaServer: () => respondRunPiExtensionUiViaServer,
   resolveServerConnectionLabel: () => resolveServerConnectionLabel,
   requestServerJson: () => requestServerJson,
+  repairRemoteProjectRootLink: () => repairRemoteProjectRootLink,
   registerProjectViaServer: () => registerProjectViaServer,
   prepareRemoteCheckoutViaServer: () => prepareRemoteCheckoutViaServer,
   postGitHubTokenViaServer: () => postGitHubTokenViaServer,
+  normalizeRepoSlug: () => normalizeRepoSlug,
   listWorkspaceTasksViaServer: () => listWorkspaceTasksViaServer,
   listRunsViaServer: () => listRunsViaServer,
   listGitHubProjectsViaServer: () => listGitHubProjectsViaServer,
+  isRemoteProjectRootLinkError: () => isRemoteProjectRootLinkError,
+  inspectRemoteProjectLink: () => inspectRemoteProjectLink,
   getWorkspaceTaskViaServer: () => getWorkspaceTaskViaServer,
   getRunTimelineViaServer: () => getRunTimelineViaServer,
   getRunPiStatusViaServer: () => getRunPiStatusViaServer,
@@ -197,13 +246,15 @@ __export(exports__server_client, {
   getRunDetailsViaServer: () => getRunDetailsViaServer,
   getGitHubProjectStatusFieldViaServer: () => getGitHubProjectStatusFieldViaServer,
   getGitHubAuthStatusViaServer: () => getGitHubAuthStatusViaServer,
+  formatRemoteProjectLinkHint: () => formatRemoteProjectLinkHint,
   ensureTaskLabelsViaServer: () => ensureTaskLabelsViaServer,
   ensureServerForCli: () => ensureServerForCli,
+  ensureRemoteProjectRootLink: () => ensureRemoteProjectRootLink,
   buildRunPiEventsWebSocketUrl: () => buildRunPiEventsWebSocketUrl,
   abortRunPiViaServer: () => abortRunPiViaServer
 });
-import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
-import { resolve as resolve2 } from "path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { dirname as dirname2, isAbsolute, resolve as resolve2 } from "path";
 import { ensureLocalRigServerConnection } from "@rig/runtime/local-server";
 function setServerPhaseListener(listener) {
   const previous = serverPhaseListener;
@@ -249,11 +300,10 @@ function readStoredGitHubAuthToken(projectRoot) {
   const parsed = readRemoteAuthState(projectRoot);
   return parsed ? cleanToken(typeof parsed.token === "string" ? parsed.token : undefined) : null;
 }
-function inferRemoteServerProjectRootFromAuthState(projectRoot) {
-  const repo = readRepoConnection(projectRoot);
-  const slug = repo?.project?.trim();
-  if (!slug || !/^[^/]+\/[^/]+$/.test(slug))
+function inferRemoteServerProjectRootCandidateFromAuthState(projectRoot, repoSlug) {
+  if (!/^[^/]+\/[^/]+$/.test(repoSlug))
     return null;
+  const repo = readRepoConnection(projectRoot);
   const auth = readRemoteAuthState(projectRoot);
   const authUpdatedAt = typeof auth?.updatedAt === "string" ? Date.parse(auth.updatedAt) : Number.NaN;
   const repoLinkedAt = typeof repo?.linkedAt === "string" ? Date.parse(repo.linkedAt) : Number.NaN;
@@ -262,25 +312,426 @@ function inferRemoteServerProjectRootFromAuthState(projectRoot) {
   const checkoutBaseDir = typeof auth?.checkoutBaseDir === "string" && auth.checkoutBaseDir.trim() ? auth.checkoutBaseDir.trim() : null;
   if (!checkoutBaseDir)
     return null;
-  const inferred = `${checkoutBaseDir.replace(/\/+$/, "")}/${slug}`;
-  writeRepoServerProjectRoot(projectRoot, inferred);
-  return inferred;
+  return `${checkoutBaseDir.replace(/\/+$/, "")}/${repoSlug}`;
 }
 function readLocalConnectionFallbackToken(projectRoot) {
   return readGitHubBearerTokenForRemote(projectRoot) ?? cleanToken(process.env.RIG_GITHUB_TOKEN) ?? readStoredGitHubAuthToken(projectRoot);
 }
+function normalizeRepoSlug(value) {
+  const slug = value?.trim();
+  return slug && /^[^/\s]+\/[^/\s]+$/.test(slug) ? slug : null;
+}
+function readProjectLinkSlug(projectRoot) {
+  const path = resolve2(projectRoot, ".rig", "state", "project-link.json");
+  if (!existsSync2(path))
+    return null;
+  try {
+    const parsed = JSON.parse(readFileSync2(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+      return null;
+    return normalizeRepoSlug(typeof parsed.repoSlug === "string" ? String(parsed.repoSlug) : null);
+  } catch {
+    return null;
+  }
+}
+function writeProjectLinkConnection(projectRoot, repoSlug, alias) {
+  const path = resolve2(projectRoot, ".rig", "state", "project-link.json");
+  mkdirSync2(dirname2(path), { recursive: true });
+  writeFileSync2(path, `${JSON.stringify({ repoSlug, connection: alias, linkedAt: new Date().toISOString() }, null, 2)}
+`, "utf8");
+}
+function remoteLinkRepairCommand(repoSlug) {
+  return repoSlug ? `rig server repair-link --repo ${repoSlug}` : "rig server repair-link --repo owner/repo";
+}
+function isRemoteProjectRootLinkError(error) {
+  const text = error instanceof Error ? error.message : String(error ?? "");
+  return /no server-host project root link|remote project(?:-root)? link|x-rig-project-root|serverProjectRoot/i.test(text);
+}
+function formatRemoteProjectLinkHint(resolution) {
+  const repair = remoteLinkRepairCommand(resolution.repoSlug);
+  if (resolution.status === "auth_required") {
+    return `Authenticate the selected remote${resolution.alias ? ` (${resolution.alias})` : ""}, then run \`${repair}\`. Use \`rig github auth import-gh\` or \`rig init --repair --server remote --github-auth device${resolution.repoSlug ? ` --repo ${resolution.repoSlug}` : ""}\`.`;
+  }
+  if (resolution.status === "missing_project") {
+    return `Record the repo slug, then run \`${repair}\` (or \`rig init --repo owner/repo --server remote --github-auth device\`).`;
+  }
+  if (resolution.status === "not_remote")
+    return "Select a remote server with `rig server use <alias>` before repairing a remote project link.";
+  return `Run \`${repair}\` to backfill or prepare a server-host checkout for the selected remote${resolution.alias ? ` (${resolution.alias})` : ""}.`;
+}
+function remoteProjectLinkFailure(input) {
+  const partial = {
+    status: input.status,
+    alias: input.alias,
+    baseUrl: input.baseUrl,
+    repoSlug: input.repoSlug
+  };
+  return {
+    ok: false,
+    ...input,
+    hint: formatRemoteProjectLinkHint(partial),
+    next: remoteLinkRepairCommand(input.repoSlug)
+  };
+}
+function remoteProjectLinkSuccess(input) {
+  return {
+    ok: true,
+    status: input.status,
+    alias: input.alias,
+    baseUrl: input.baseUrl,
+    repoSlug: input.repoSlug,
+    serverProjectRoot: input.serverProjectRoot,
+    source: input.source,
+    prepared: input.prepared ?? input.status === "prepared",
+    validated: input.validated ?? false,
+    message: input.message ?? `Remote project link ready for ${input.repoSlug}.`,
+    hint: "Remote-scoped task/run/status requests will send x-rig-project-root for this server-host checkout.",
+    next: "rig task list"
+  };
+}
+function localCheckoutPathCandidate(projectRoot, candidate) {
+  try {
+    const local = resolve2(projectRoot);
+    const resolved = resolve2(candidate);
+    return resolved === local || resolved.startsWith(`${local}/`);
+  } catch {
+    return false;
+  }
+}
+async function requestRemoteProjectLinkJson(baseUrl, pathname, authToken, init = {}) {
+  const requestUrl = new URL(`${baseUrl}${pathname}`);
+  if (authToken && queryAuthFallbackEnabled())
+    requestUrl.searchParams.set("rt", authToken);
+  const response = await fetch(requestUrl, {
+    ...init,
+    headers: mergeHeaders(init.headers, authToken)
+  });
+  const text = await response.text();
+  const payload = text.trim().length > 0 ? (() => {
+    try {
+      return JSON.parse(text);
+    } catch {
+      return null;
+    }
+  })() : null;
+  return { ok: response.ok, status: response.status, payload, text };
+}
+function payloadError(payload, fallback) {
+  if (payload && typeof payload === "object" && !Array.isArray(payload)) {
+    const record = payload;
+    const value = record.error ?? record.message ?? record.reason;
+    if (typeof value === "string" && value.trim())
+      return value.trim();
+  }
+  return fallback;
+}
+function checkoutPathsFromProjectPayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return [];
+  const project = payload.project;
+  if (!project || typeof project !== "object" || Array.isArray(project))
+    return [];
+  const checkouts = project.checkouts;
+  if (!Array.isArray(checkouts))
+    return [];
+  return [...checkouts].reverse().flatMap((entry) => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+      return [];
+    const path = entry.path;
+    return typeof path === "string" && path.trim() ? [path.trim()] : [];
+  });
+}
+function checkoutPathFromPreparePayload(payload) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload))
+    return null;
+  const checkout = payload.checkout;
+  if (!checkout || typeof checkout !== "object" || Array.isArray(checkout))
+    return null;
+  const path = checkout.path;
+  return typeof path === "string" && path.trim() ? path.trim() : null;
+}
+async function validateAndPersistRemoteRoot(input) {
+  const candidate = input.candidate.trim();
+  if (!candidate || !isAbsolute(candidate)) {
+    return remoteProjectLinkFailure({
+      status: "invalid_root",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      message: `Remote project root candidate is not an absolute server-host path: ${candidate || "(empty)"}.`
+    });
+  }
+  if (localCheckoutPathCandidate(input.projectRoot, candidate)) {
+    return remoteProjectLinkFailure({
+      status: "invalid_root",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      message: `Refusing to use local checkout path ${candidate} as a remote server project root.`
+    });
+  }
+  let response;
+  try {
+    response = await requestRemoteProjectLinkJson(input.baseUrl, "/api/server/project-root", input.authToken, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ projectRoot: candidate })
+    });
+  } catch (error) {
+    return remoteProjectLinkFailure({
+      status: "error",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      message: `Could not validate remote project root ${candidate}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+  if (response.status === 401 || response.status === 403) {
+    return remoteProjectLinkFailure({
+      status: "auth_required",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      statusCode: response.status,
+      message: `Remote server ${input.alias} requires authentication before validating project root ${candidate}.`
+    });
+  }
+  if (!response.ok) {
+    return remoteProjectLinkFailure({
+      status: "invalid_root",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      statusCode: response.status,
+      message: `Remote server rejected project root ${candidate} (${response.status}): ${payloadError(response.payload, response.text || "project-root validation failed")}`
+    });
+  }
+  const record = response.payload && typeof response.payload === "object" && !Array.isArray(response.payload) ? response.payload : {};
+  if (record.ok !== true) {
+    return remoteProjectLinkFailure({
+      status: "invalid_root",
+      alias: input.alias,
+      baseUrl: input.baseUrl,
+      repoSlug: input.repoSlug,
+      message: `Remote server did not accept project root ${candidate}: ${payloadError(response.payload, "project-root validation failed")}`
+    });
+  }
+  const accepted = typeof record.projectRoot === "string" && record.projectRoot.trim() ? record.projectRoot.trim() : typeof record.requestedProjectRoot === "string" && record.requestedProjectRoot.trim() ? record.requestedProjectRoot.trim() : candidate;
+  writeRepoServerProjectRoot(input.projectRoot, accepted, { alias: input.alias, baseUrl: input.baseUrl, project: input.repoSlug });
+  writeProjectLinkConnection(input.projectRoot, input.repoSlug, input.alias);
+  const status = input.status ?? (input.prepared ? "prepared" : "backfilled");
+  return remoteProjectLinkSuccess({
+    status,
+    alias: input.alias,
+    baseUrl: input.baseUrl,
+    repoSlug: input.repoSlug,
+    serverProjectRoot: accepted,
+    source: input.source,
+    prepared: input.prepared,
+    validated: true,
+    message: status === "ready" ? `Remote project link already points to ${accepted} and was validated on ${input.alias}.` : input.prepared ? `Prepared and linked remote checkout ${accepted} for ${input.repoSlug}.` : `Backfilled remote checkout ${accepted} for ${input.repoSlug}.`
+  });
+}
+async function ensureRemoteProjectRootLink(projectRoot, options = {}) {
+  let selected;
+  try {
+    selected = resolveSelectedConnection(projectRoot);
+  } catch (error) {
+    return remoteProjectLinkFailure({ status: "error", message: error instanceof Error ? error.message : String(error) });
+  }
+  if (!selected || selected.connection.kind !== "remote") {
+    return remoteProjectLinkFailure({ status: "not_remote", message: "No remote Rig server is selected for this repo." });
+  }
+  const repo = readRepoConnection(projectRoot);
+  const explicitRepoRequested = options.repoSlug !== undefined;
+  const explicitRepoSlug = explicitRepoRequested ? normalizeRepoSlug(options.repoSlug) : null;
+  const repoProjectSlug = normalizeRepoSlug(repo?.project);
+  const repoSlug = explicitRepoSlug ?? repoProjectSlug ?? readProjectLinkSlug(projectRoot);
+  const alias = selected.alias;
+  const baseUrl = selected.connection.baseUrl;
+  const authToken = options.authToken === undefined ? readGitHubBearerTokenForRemote(projectRoot) : options.authToken;
+  const mode = options.mode ?? "backfill-only";
+  if (explicitRepoRequested && !explicitRepoSlug) {
+    return remoteProjectLinkFailure({
+      status: "missing_project",
+      alias,
+      baseUrl,
+      message: `Invalid --repo value ${JSON.stringify(options.repoSlug)}. Expected owner/repo.`
+    });
+  }
+  if (!repoSlug) {
+    return remoteProjectLinkFailure({
+      status: "missing_project",
+      alias,
+      baseUrl,
+      message: `Remote server ${alias} is selected, but this checkout has no GitHub repo slug recorded.`
+    });
+  }
+  const skippedCandidates = [];
+  const storedRoot = selected.serverProjectRoot?.trim() || null;
+  const storedRootMatchesResolvedRepo = repoProjectSlug === repoSlug;
+  if (storedRoot && storedRootMatchesResolvedRepo) {
+    if (localCheckoutPathCandidate(projectRoot, storedRoot)) {
+      clearRepoServerProjectRoot(projectRoot);
+      skippedCandidates.push(storedRoot);
+    } else {
+      const storedResult = await validateAndPersistRemoteRoot({
+        projectRoot,
+        alias,
+        baseUrl,
+        authToken,
+        repoSlug,
+        candidate: storedRoot,
+        source: "stored",
+        status: "ready"
+      });
+      if (storedResult.ok || storedResult.status === "auth_required" || storedResult.status === "error")
+        return storedResult;
+      clearRepoServerProjectRoot(projectRoot);
+      skippedCandidates.push(storedRoot);
+    }
+  } else if (storedRoot) {
+    skippedCandidates.push(storedRoot);
+  }
+  const authCandidate = inferRemoteServerProjectRootCandidateFromAuthState(projectRoot, repoSlug);
+  if (authCandidate) {
+    const authResult = await validateAndPersistRemoteRoot({ projectRoot, alias, baseUrl, authToken, repoSlug, candidate: authCandidate, source: "auth-state" });
+    if (authResult.ok || authResult.status === "auth_required")
+      return authResult;
+  }
+  let registryResponse;
+  try {
+    registryResponse = await requestRemoteProjectLinkJson(baseUrl, `/api/projects/${encodeURIComponent(repoSlug)}`, authToken);
+  } catch (error) {
+    return remoteProjectLinkFailure({
+      status: "error",
+      alias,
+      baseUrl,
+      repoSlug,
+      message: `Could not read remote project registry for ${repoSlug} on ${alias}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+  if (registryResponse.status === 401 || registryResponse.status === 403) {
+    return remoteProjectLinkFailure({
+      status: "auth_required",
+      alias,
+      baseUrl,
+      repoSlug,
+      statusCode: registryResponse.status,
+      message: `Remote server ${alias} requires authentication before reading the ${repoSlug} project registry.`
+    });
+  }
+  if (registryResponse.ok) {
+    const candidates = checkoutPathsFromProjectPayload(registryResponse.payload);
+    for (const candidate of candidates) {
+      const result = await validateAndPersistRemoteRoot({ projectRoot, alias, baseUrl, authToken, repoSlug, candidate, source: "registry" });
+      if (result.ok || result.status === "auth_required")
+        return result;
+      skippedCandidates.push(candidate);
+    }
+    if (mode === "backfill-only") {
+      return remoteProjectLinkFailure({
+        status: candidates.length > 0 ? "invalid_root" : "no_server_checkout",
+        alias,
+        baseUrl,
+        repoSlug,
+        message: candidates.length > 0 ? `Remote registry has checkout candidates for ${repoSlug}, but none validated for ${alias}.` : `Remote registry has ${repoSlug}, but no server checkout path is linked yet.`,
+        skippedCandidates
+      });
+    }
+  } else if (registryResponse.status === 404) {
+    if (mode === "backfill-only") {
+      return remoteProjectLinkFailure({
+        status: "project_not_registered",
+        alias,
+        baseUrl,
+        repoSlug,
+        statusCode: registryResponse.status,
+        message: `Remote server ${alias} has no registered project record for ${repoSlug}.`
+      });
+    }
+  } else {
+    return remoteProjectLinkFailure({
+      status: "error",
+      alias,
+      baseUrl,
+      repoSlug,
+      statusCode: registryResponse.status,
+      message: `Could not backfill ${repoSlug} from remote registry (${registryResponse.status}): ${payloadError(registryResponse.payload, registryResponse.text || "registry lookup failed")}`,
+      skippedCandidates
+    });
+  }
+  let prepareResponse;
+  try {
+    prepareResponse = await requestRemoteProjectLinkJson(baseUrl, `/api/projects/${encodeURIComponent(repoSlug)}/prepare-checkout`, authToken, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ checkout: { kind: "managed-clone" }, repoUrl: `https://github.com/${repoSlug}.git` })
+    });
+  } catch (error) {
+    return remoteProjectLinkFailure({
+      status: "error",
+      alias,
+      baseUrl,
+      repoSlug,
+      message: `Could not prepare remote checkout for ${repoSlug} on ${alias}: ${error instanceof Error ? error.message : String(error)}`
+    });
+  }
+  if (prepareResponse.status === 401 || prepareResponse.status === 403) {
+    return remoteProjectLinkFailure({
+      status: "auth_required",
+      alias,
+      baseUrl,
+      repoSlug,
+      statusCode: prepareResponse.status,
+      message: `Remote server ${alias} requires authentication before preparing ${repoSlug}.`
+    });
+  }
+  if (!prepareResponse.ok) {
+    return remoteProjectLinkFailure({
+      status: "error",
+      alias,
+      baseUrl,
+      repoSlug,
+      statusCode: prepareResponse.status,
+      message: `Remote checkout prepare failed for ${repoSlug} (${prepareResponse.status}): ${payloadError(prepareResponse.payload, prepareResponse.text || "prepare-checkout failed")}`,
+      skippedCandidates
+    });
+  }
+  const preparedPath = checkoutPathFromPreparePayload(prepareResponse.payload);
+  if (!preparedPath) {
+    return remoteProjectLinkFailure({
+      status: "invalid_root",
+      alias,
+      baseUrl,
+      repoSlug,
+      message: `Remote checkout prepare for ${repoSlug} did not return a checkout.path.`,
+      skippedCandidates
+    });
+  }
+  return validateAndPersistRemoteRoot({ projectRoot, alias, baseUrl, authToken, repoSlug, candidate: preparedPath, source: "prepare", prepared: true });
+}
+async function inspectRemoteProjectLink(projectRoot) {
+  return ensureRemoteProjectRootLink(projectRoot, { mode: "backfill-only" });
+}
+async function repairRemoteProjectRootLink(context, options = {}) {
+  const resolution = await ensureRemoteProjectRootLink(context.projectRoot, { mode: options.mode ?? "prepare-if-missing", repoSlug: options.repoSlug });
+  if (!resolution.ok)
+    throw new CliError(resolution.message, 1, { hint: resolution.hint });
+  return resolution;
+}
 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 ?? inferRemoteServerProjectRootFromAuthState(projectRoot) ?? await backfillRemoteServerProjectRoot(projectRoot, selected.connection.baseUrl, authToken);
+      const link = await ensureRemoteProjectRootLink(projectRoot, { mode: "backfill-only", authToken });
       return {
         baseUrl: selected.connection.baseUrl,
         authToken,
         connectionKind: "remote",
-        serverProjectRoot
+        serverProjectRoot: link.ok ? link.serverProjectRoot ?? null : null
       };
     }
     reportServerPhase("Starting local Rig server\u2026");
@@ -298,32 +749,6 @@ async function ensureServerForCli(projectRoot) {
     throw error;
   }
 }
-async function backfillRemoteServerProjectRoot(projectRoot, baseUrl, authToken) {
-  const repo = readRepoConnection(projectRoot);
-  const slug = repo?.project?.trim();
-  if (!slug)
-    return null;
-  try {
-    const url = new URL(`${baseUrl}/api/projects/${encodeURIComponent(slug)}`);
-    if (authToken && queryAuthFallbackEnabled())
-      url.searchParams.set("rt", authToken);
-    const response = await fetch(url, {
-      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 appendTaskFilterParams(url, filters) {
   if (filters.assignee)
     url.searchParams.set("assignee", filters.assignee);
@@ -424,13 +849,20 @@ function canUseRemoteWithoutProjectRoot(pathname) {
 async function requestServerJson(context, pathname, init = {}) {
   const server = await ensureServerForCli(context.projectRoot);
   const requestUrl = new URL(`${server.baseUrl}${pathname}`);
-  if (server.connectionKind === "remote" && !server.serverProjectRoot && !canUseRemoteWithoutProjectRoot(requestUrl.pathname) && (server.authToken || !isLoopbackRemoteBaseUrl(server.baseUrl))) {
-    const repo = readRepoConnection(context.projectRoot);
-    throw new CliError(`Remote server is selected for ${repo?.project ?? "this repo"}, but this checkout has no server-host project root link.`, 1, { hint: "Run `rig init --repair` or `rig init --yes --repo owner/repo --server remote` to repair the remote project link before task/run commands." });
+  let scopedServerProjectRoot = server.serverProjectRoot;
+  if (server.connectionKind === "remote" && !scopedServerProjectRoot && !canUseRemoteWithoutProjectRoot(requestUrl.pathname) && (server.authToken || !isLoopbackRemoteBaseUrl(server.baseUrl))) {
+    const link = await ensureRemoteProjectRootLink(context.projectRoot, { mode: "backfill-only", authToken: server.authToken });
+    if (link.ok && link.serverProjectRoot) {
+      scopedServerProjectRoot = link.serverProjectRoot;
+    } else {
+      const repo = readRepoConnection(context.projectRoot);
+      const target = link.alias && link.baseUrl ? `${link.alias} (${link.baseUrl})` : server.baseUrl;
+      throw new CliError(`Remote server ${target} is selected for ${link.repoSlug ?? repo?.project ?? "this repo"}, but this checkout has no server-host project root link. ${link.message}`, 1, { hint: link.hint });
+    }
   }
   const headers = mergeHeaders(init.headers, server.authToken);
-  if (server.serverProjectRoot)
-    headers.set("x-rig-project-root", server.serverProjectRoot);
+  if (scopedServerProjectRoot)
+    headers.set("x-rig-project-root", scopedServerProjectRoot);
   if (server.connectionKind === "remote" && server.authToken && queryAuthFallbackEnabled()) {
     requestUrl.searchParams.set("rt", server.authToken);
   }
@@ -795,6 +1227,9 @@ var init__server_client = __esm(() => {
   ]);
 });
 
+// packages/cli/src/app-opentui/adapters/server.ts
+import { spawnSync } from "child_process";
+
 // packages/cli/src/app-opentui/adapters/common.ts
 function projectRootOf(ctx) {
   const root = ctx.rig?.projectRoot ?? ctx.projectRoot ?? ctx.getState().projectRoot;
@@ -802,6 +1237,22 @@ function projectRootOf(ctx) {
     return root;
   throw new Error("App adapter requires a projectRoot.");
 }
+async function runtimeOf(ctx) {
+  if (ctx.rig && "runId" in ctx.rig && ctx.ensureRuntime === undefined) {
+    return ctx.rig;
+  }
+  if (ctx.ensureRuntime)
+    return ctx.ensureRuntime();
+  throw new Error("App adapter requires ensureRuntime() before this action can run.");
+}
+function normalizeAppError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  const rawHint = error instanceof Error ? error.hint : undefined;
+  return {
+    message,
+    ...typeof rawHint === "string" && rawHint.trim() ? { hint: rawHint.trim() } : {}
+  };
+}
 function emitStarted(ctx, label, optimistic) {
   ctx.emit({ type: "action.started", label, ...optimistic ? { optimistic } : {} });
 }
@@ -811,6 +1262,18 @@ function emitProgress(ctx, label, detail, data) {
 function emitCompleted(ctx, label, data) {
   ctx.emit({ type: "action.completed", label, ...data ? { data } : {} });
 }
+function emitFailed(ctx, label, error, data) {
+  if (data)
+    patchData(ctx, data);
+  const normalized = normalizeAppError(error);
+  ctx.emit({
+    type: "action.failed",
+    label,
+    message: normalized.message,
+    ...normalized.hint ? { hint: normalized.hint } : {},
+    cause: error
+  });
+}
 function patchData(ctx, data) {
   ctx.emit({ type: "data.patch", data });
 }
@@ -856,11 +1319,128 @@ function startLocalRequested(ctx) {
   const action = intent.action;
   return action?.payload?.startLocal === true;
 }
+async function serverAliases(projectRoot) {
+  const { readGlobalConnections: readGlobalConnections2, readRepoConnection: readRepoConnection2 } = await Promise.resolve().then(() => (init__connection_state(), exports__connection_state));
+  const selected = readRepoConnection2(projectRoot)?.selected ?? "local";
+  const global = readGlobalConnections2();
+  const aliases = [{ alias: "local", kind: "local", selected: selected === "local" }];
+  for (const [alias, connection] of Object.entries(global.connections)) {
+    aliases.push({
+      alias,
+      kind: connection.kind,
+      ...connection.kind === "remote" ? { baseUrl: connection.baseUrl } : {},
+      selected: alias === selected
+    });
+  }
+  return aliases;
+}
+function firstString(parts, offset = 0) {
+  return parts.slice(offset).find((part) => part.trim() && !part.startsWith("-"))?.trim();
+}
+function normalizeUrl(value) {
+  const trimmed = value?.trim().replace(/\/+$/, "");
+  if (!trimmed)
+    return;
+  return /^https?:\/\//i.test(trimmed) ? trimmed : undefined;
+}
+async function useLocalServerFromApp(ctx) {
+  const label = "Selecting local server";
+  emitStarted(ctx, label);
+  try {
+    const projectRoot = projectRootOf(ctx);
+    const { readRepoConnection: readRepoConnection2, writeRepoConnection: writeRepoConnection2 } = await Promise.resolve().then(() => (init__connection_state(), exports__connection_state));
+    const previous = readRepoConnection2(projectRoot);
+    writeRepoConnection2(projectRoot, {
+      selected: "local",
+      ...previous?.project ? { project: previous.project } : {},
+      linkedAt: new Date().toISOString()
+    });
+    emitCompleted(ctx, label, { selected: "local" });
+    return refreshServerStatus(ctx);
+  } catch (error) {
+    emitFailed(ctx, label, error);
+    throw error;
+  }
+}
+async function useRemoteServerFromApp(ctx, alias) {
+  const label = alias ? `Selecting remote ${alias}` : "Selecting remote server";
+  emitStarted(ctx, label);
+  try {
+    const cleanAlias = alias?.trim();
+    if (!cleanAlias)
+      throw new Error("Enter a saved remote alias, or add one with: add remote \u2192 <alias> <https-url>.");
+    const projectRoot = projectRootOf(ctx);
+    const { readGlobalConnections: readGlobalConnections2, readRepoConnection: readRepoConnection2, writeRepoConnection: writeRepoConnection2 } = await Promise.resolve().then(() => (init__connection_state(), exports__connection_state));
+    const connection = readGlobalConnections2().connections[cleanAlias];
+    if (!connection)
+      throw new Error(`Remote alias ${cleanAlias} is not saved yet. Use add remote first.`);
+    if (connection.kind !== "remote")
+      throw new Error(`${cleanAlias} is not a remote server alias.`);
+    const previous = readRepoConnection2(projectRoot);
+    writeRepoConnection2(projectRoot, {
+      selected: cleanAlias,
+      ...previous?.project ? { project: previous.project } : {},
+      linkedAt: new Date().toISOString()
+    });
+    emitCompleted(ctx, label, { selected: cleanAlias, baseUrl: connection.baseUrl });
+    return refreshServerStatus(ctx);
+  } catch (error) {
+    emitFailed(ctx, label, error);
+    throw error;
+  }
+}
+async function addRemoteServerFromApp(ctx, args) {
+  const label = "Adding remote server";
+  emitStarted(ctx, label);
+  try {
+    const alias = firstString(args, 2);
+    const url = normalizeUrl(firstString(args, alias ? args.indexOf(alias) + 1 : 3));
+    if (!alias || !url)
+      throw new Error("Add remote expects: <alias> <https-url>. Example: prod https://rig.example.com");
+    const projectRoot = projectRootOf(ctx);
+    const { readRepoConnection: readRepoConnection2, upsertGlobalConnection: upsertGlobalConnection2, writeRepoConnection: writeRepoConnection2 } = await Promise.resolve().then(() => (init__connection_state(), exports__connection_state));
+    upsertGlobalConnection2(alias, { kind: "remote", baseUrl: url });
+    const previous = readRepoConnection2(projectRoot);
+    writeRepoConnection2(projectRoot, {
+      selected: alias,
+      ...previous?.project ? { project: previous.project } : {},
+      linkedAt: new Date().toISOString()
+    });
+    emitCompleted(ctx, label, { alias, baseUrl: url });
+    return refreshServerStatus(ctx);
+  } catch (error) {
+    emitFailed(ctx, label, error);
+    throw error;
+  }
+}
+async function importGitHubAuthFromGhApp(ctx) {
+  const label = "Importing GitHub auth";
+  emitStarted(ctx, label);
+  try {
+    const projectRoot = projectRootOf(ctx);
+    const token = spawnSync("gh", ["auth", "token"], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], timeout: 1e4 }).stdout.trim();
+    if (!token)
+      throw new Error("Could not read GitHub token from gh. Sign in with gh auth login, then retry import auth.");
+    const runtime = await runtimeOf(ctx);
+    const { postGitHubTokenViaServer: postGitHubTokenViaServer2, setGitHubBearerTokenForCurrentProcess: setGitHubBearerTokenForCurrentProcess2 } = await Promise.resolve().then(() => (init__server_client(), exports__server_client));
+    const { readRepoConnection: readRepoConnection2 } = await Promise.resolve().then(() => (init__connection_state(), exports__connection_state));
+    const selectedRepo = readRepoConnection2(projectRoot)?.project;
+    const payload = await postGitHubTokenViaServer2(runtime, token, selectedRepo ? { selectedRepo } : {});
+    const apiSessionToken = payload && typeof payload === "object" && !Array.isArray(payload) ? payload.apiSessionToken : undefined;
+    setGitHubBearerTokenForCurrentProcess2(typeof apiSessionToken === "string" ? apiSessionToken : token, projectRoot);
+    emitCompleted(ctx, label, { selectedRepo: selectedRepo ?? null });
+    return refreshServerStatus(ctx);
+  } catch (error) {
+    emitFailed(ctx, label, error);
+    throw error;
+  }
+}
 async function startLocalServerFromApp(ctx) {
   const label = "Starting local server";
   emitStarted(ctx, label);
   patchData(ctx, {
     lastIntent: undefined,
+    remoteProjectLink: undefined,
     server: { label: "starting local server", reachable: false, error: "spawning local rig-server (detached)\u2026" }
   });
   try {
@@ -885,32 +1465,61 @@ async function startLocalServerFromApp(ctx) {
       reachable: false,
       error: error instanceof Error ? error.message : String(error)
     };
-    patchData(ctx, { server: state, lastRefreshError: state.error });
+    patchData(ctx, { server: state, remoteProjectLink: undefined, lastRefreshError: state.error });
     patchFooter(ctx, { server: "unavailable" });
-    emitCompleted(ctx, label, { server: state.label, reachable: false, error: state.error });
+    emitCompleted(ctx, label, { serverLabel: state.label, reachable: false, error: state.error });
     return state;
   }
 }
+async function repairRemoteProjectRootLinkFromApp(ctx) {
+  const label = "Repairing remote project link";
+  emitStarted(ctx, label);
+  try {
+    const projectRoot = projectRootOf(ctx);
+    const { ensureRemoteProjectRootLink: ensureRemoteProjectRootLink2 } = await Promise.resolve().then(() => (init__server_client(), exports__server_client));
+    emitProgress(ctx, label, "backfilling or preparing server-host checkout");
+    const result = await ensureRemoteProjectRootLink2(projectRoot, { mode: "prepare-if-missing" });
+    patchData(ctx, { remoteProjectLink: result, server: { label: result.alias ?? "remote", baseUrl: result.baseUrl, kind: "remote", reachable: result.status !== "not_remote", remoteProjectLink: result } });
+    patchFooter(ctx, { server: result.alias ?? "remote", message: `remote link ${result.status}` });
+    if (!result.ok) {
+      const error = new Error(result.message);
+      error.hint = result.hint;
+      patchData(ctx, { lastRefreshError: result.message });
+      throw error;
+    }
+    emitCompleted(ctx, label, { repoSlug: result.repoSlug, serverProjectRoot: result.serverProjectRoot, status: result.status });
+    return result;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const existing = ctx.getState().data?.remoteProjectLink;
+    const remoteProjectLink = existing && typeof existing === "object" && !Array.isArray(existing) ? existing : { ok: false, status: "error", message };
+    patchData(ctx, { lastRefreshError: message, remoteProjectLink });
+    emitCompleted(ctx, label, { ok: false, error: message, remoteProjectLink });
+    throw error;
+  }
+}
 async function refreshServerStatus(ctx) {
   if (startLocalRequested(ctx)) {
     return startLocalServerFromApp(ctx);
   }
   const label = "Checking server";
   emitStarted(ctx, label);
-  patchData(ctx, { server: { label: "checking selected server", reachable: false, error: "checking selected server\u2026" } });
+  patchData(ctx, { server: { label: "checking selected server", reachable: false, error: "checking selected server\u2026" }, remoteProjectLink: undefined });
   const started = Date.now();
   try {
-    const { ensureServerForCli: ensureServerForCli2, requestServerJson: requestServerJson2, resolveServerConnectionLabel: resolveServerConnectionLabel2 } = await Promise.resolve().then(() => (init__server_client(), exports__server_client));
+    const { ensureRemoteProjectRootLink: ensureRemoteProjectRootLink2, ensureServerForCli: ensureServerForCli2, requestServerJson: requestServerJson2, resolveServerConnectionLabel: resolveServerConnectionLabel2 } = await Promise.resolve().then(() => (init__server_client(), exports__server_client));
     const projectRoot = projectRootOf(ctx);
+    const aliases = await serverAliases(projectRoot);
     emitProgress(ctx, label, "resolving selected server");
     const [connectionLabel, server] = await Promise.all([
       resolveServerConnectionLabel2(projectRoot),
       withTimeout(ensureServerForCli2(projectRoot), 5000, "server connection")
     ]);
     emitProgress(ctx, label, "requesting server status", { baseUrl: server.baseUrl, kind: server.connectionKind });
-    const [status, auth] = await Promise.all([
+    const [status, auth, remoteProjectLink] = await Promise.all([
       withRetry("server status", () => withTimeout(requestServerJson2({ projectRoot }, "/api/server/status"), SERVER_PROBE_TIMEOUT_MS, "server status")).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) })),
-      withRetry("github auth status", () => withTimeout(requestServerJson2({ projectRoot }, "/api/github/auth/status"), SERVER_PROBE_TIMEOUT_MS, "github auth status")).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) }))
+      withRetry("github auth status", () => withTimeout(requestServerJson2({ projectRoot }, "/api/github/auth/status"), SERVER_PROBE_TIMEOUT_MS, "github auth status")).catch((error) => ({ ok: false, error: error instanceof Error ? error.message : String(error) })),
+      server.connectionKind === "remote" ? withTimeout(ensureRemoteProjectRootLink2(projectRoot, { mode: "backfill-only", authToken: server.authToken }), SERVER_PROBE_TIMEOUT_MS, "remote project link").catch((error) => ({ ok: false, status: "error", message: error instanceof Error ? error.message : String(error) })) : Promise.resolve(null)
     ]);
     const state = {
       label: connectionLabel,
@@ -919,26 +1528,34 @@ async function refreshServerStatus(ctx) {
       reachable: true,
       latencyMs: Date.now() - started,
       status: status && typeof status === "object" && !Array.isArray(status) ? status : {},
-      auth: auth && typeof auth === "object" && !Array.isArray(auth) ? auth : {}
+      auth: auth && typeof auth === "object" && !Array.isArray(auth) ? auth : {},
+      aliases,
+      ...remoteProjectLink && typeof remoteProjectLink === "object" && !Array.isArray(remoteProjectLink) ? { remoteProjectLink } : {}
     };
-    patchData(ctx, { server: state });
+    patchData(ctx, { server: state, remoteProjectLink: state.remoteProjectLink });
     patchFooter(ctx, { server: connectionLabel, latency: `${state.latencyMs}ms` });
-    emitCompleted(ctx, label, { server: connectionLabel, latencyMs: state.latencyMs });
+    emitCompleted(ctx, label, { serverLabel: connectionLabel, latencyMs: state.latencyMs });
     return state;
   } catch (error) {
     const state = {
       label: "server unavailable",
       reachable: false,
       latencyMs: Date.now() - started,
+      aliases: await serverAliases(projectRootOf(ctx)).catch(() => []),
       error: error instanceof Error ? error.message : String(error)
     };
-    patchData(ctx, { server: state });
+    patchData(ctx, { server: state, remoteProjectLink: undefined });
     patchFooter(ctx, { server: "unavailable" });
-    emitCompleted(ctx, label, { server: state.label, reachable: false, error: state.error });
+    emitCompleted(ctx, label, { serverLabel: state.label, reachable: false, error: state.error });
     return state;
   }
 }
 export {
+  useRemoteServerFromApp,
+  useLocalServerFromApp,
   startLocalServerFromApp,
-  refreshServerStatus
+  repairRemoteProjectRootLinkFromApp,
+  refreshServerStatus,
+  importGitHubAuthFromGhApp,
+  addRemoteServerFromApp
 };