@tonyclaw/agent-inspector 3.0.44 → 3.0.45

package/src/cli/instanceRegistry.ts

@@ -0,0 +1,740 @@
+import { randomUUID } from "node:crypto";
+import {
+  closeSync,
+  type Dirent,
+  existsSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { createServer } from "node:net";
+import { homedir } from "node:os";
+import { join, posix, win32 } from "node:path";
+import { z } from "zod";
+import {
+  ensurePrivateDirectorySync,
+  PRIVATE_FILE_MODE,
+  securePrivateFileSync,
+} from "../proxy/privateDataPath";
+import {
+  InstanceRecordSchema,
+  instanceRegistryError,
+  instanceRegistrySuccess,
+  type InstanceRecord,
+  type InstanceRegistryResult,
+  validateInstanceName,
+} from "./instanceModel";
+
+export {
+  createInstanceRecord,
+  INSTANCE_OUTPUT_SCHEMA_VERSION,
+  INSTANCE_RECORD_SCHEMA_VERSION,
+  InstanceLaunchSchema,
+  InstanceRecordSchema,
+  instanceRegistryError,
+  instanceRegistrySuccess,
+  MAX_INSTANCE_NAME_LENGTH,
+  normalizeInstanceBasePath,
+  rotateInstanceLaunch,
+  toInstanceRecordOutput,
+  validateInstanceName,
+} from "./instanceModel";
+export type {
+  CreateInstanceRecordInput,
+  InstanceIdentityFactory,
+  InstanceLaunch,
+  InstanceRecord,
+  InstanceRecordOutput,
+  InstanceRegistryError,
+  InstanceRegistryErrorCode,
+  InstanceRegistryResult,
+} from "./instanceModel";
+
+export const AGENT_INSPECTOR_INSTANCES_DIR_ENV = "AGENT_INSPECTOR_INSTANCES_DIR";
+export const DEFAULT_NAMED_INSTANCE_PUBLIC_PORT = 9530;
+export const NAMED_INSTANCE_PORT_STEP = 3;
+export const NAMED_INSTANCE_UPSTREAM_OFFSET = 2;
+export const DEFAULT_INSTANCE_LOCK_TIMEOUT_MS = 10_000;
+export const DEFAULT_INSTANCE_LOCK_STALE_MS = 30_000;
+
+const INSTANCE_RECORD_FILE_NAME = "instance.json";
+const ROOT_LOCK_DIRECTORY_NAME = ".allocation.lock";
+const INSTANCE_LOCK_DIRECTORY_NAME = ".mutation.lock";
+const LOCK_OWNER_FILE_NAME = "owner.json";
+const DEFAULT_LOCK_RETRY_MS = 50;
+
+type InstanceRootEnv = Readonly<Record<string, string | undefined>>;
+
+export type InstancePaths = {
+  root: string;
+  instanceDir: string;
+  dataDir: string;
+  recordPath: string;
+  lockPath: string;
+};
+
+export function getInstancesRoot(
+  env: InstanceRootEnv = process.env,
+  platform: typeof process.platform = process.platform,
+): string {
+  const pathApi = platform === "win32" ? win32 : posix;
+  const explicitRoot = env[AGENT_INSPECTOR_INSTANCES_DIR_ENV];
+  if (explicitRoot !== undefined && explicitRoot.trim().length > 0) {
+    return pathApi.isAbsolute(explicitRoot) ? explicitRoot : pathApi.resolve(explicitRoot);
+  }
+
+  if (platform === "win32") {
+    const localAppData = env["LOCALAPPDATA"];
+    if (localAppData !== undefined && localAppData.trim().length > 0) {
+      return win32.join(localAppData, "agent-inspector", "instances");
+    }
+    const userProfile = env["USERPROFILE"];
+    const fallback =
+      userProfile !== undefined && userProfile.trim().length > 0 ? userProfile : homedir();
+    return win32.join(fallback, ".agent-inspector", "instances");
+  }
+
+  const home = env["HOME"];
+  const base = home !== undefined && home.trim().length > 0 ? home : homedir();
+  return posix.join(base, ".agent-inspector", "instances");
+}
+
+export function getInstancePaths(
+  root: string,
+  rawName: string,
+): InstanceRegistryResult<InstancePaths> {
+  const name = validateInstanceName(rawName);
+  if (name.kind === "error") return name;
+  const instanceDir = join(root, name.value);
+  return instanceRegistrySuccess({
+    root,
+    instanceDir,
+    dataDir: join(instanceDir, "data"),
+    recordPath: join(instanceDir, INSTANCE_RECORD_FILE_NAME),
+    lockPath: join(instanceDir, INSTANCE_LOCK_DIRECTORY_NAME),
+  });
+}
+
+export function ensureInstancesRoot(root = getInstancesRoot()): InstanceRegistryResult<string> {
+  return ensurePrivateDirectorySync(root)
+    ? instanceRegistrySuccess(root)
+    : instanceRegistryError(
+        "registry_io",
+        `Cannot create or secure the private instance registry at ${root}.`,
+      );
+}
+
+function nodeErrorCode(error: unknown): string | null {
+  if (typeof error !== "object" || error === null) return null;
+  const descriptor = Object.getOwnPropertyDescriptor(error, "code");
+  return typeof descriptor?.value === "string" ? descriptor.value : null;
+}
+
+function readRecordFile(recordPath: string): InstanceRegistryResult<InstanceRecord> {
+  let parsedJson: unknown;
+  try {
+    parsedJson = JSON.parse(readFileSync(recordPath, "utf8"));
+  } catch {
+    return instanceRegistryError(
+      "record_invalid",
+      `Instance record ${recordPath} is unreadable or is not valid JSON.`,
+    );
+  }
+
+  const parsed = InstanceRecordSchema.safeParse(parsedJson);
+  return parsed.success
+    ? instanceRegistrySuccess(parsed.data)
+    : instanceRegistryError(
+        "record_invalid",
+        `Instance record ${recordPath} does not match schema version 1: ${parsed.error.issues[0]?.message ?? "invalid record"}.`,
+      );
+}
+
+export function readInstanceRecord(
+  root: string,
+  rawName: string,
+): InstanceRegistryResult<InstanceRecord | null> {
+  const paths = getInstancePaths(root, rawName);
+  if (paths.kind === "error") return paths;
+  if (!existsSync(paths.value.recordPath)) return instanceRegistrySuccess(null);
+  return readRecordFile(paths.value.recordPath);
+}
+
+export function listInstanceRecords(
+  root: string,
+): InstanceRegistryResult<readonly InstanceRecord[]> {
+  if (!existsSync(root)) return instanceRegistrySuccess([]);
+
+  let entries: Dirent<string>[];
+  try {
+    entries = readdirSync(root, { withFileTypes: true });
+  } catch {
+    return instanceRegistryError("registry_io", `Cannot read the instance registry at ${root}.`);
+  }
+
+  const records: InstanceRecord[] = [];
+  const names = new Set<string>();
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const recordPath = join(root, entry.name, INSTANCE_RECORD_FILE_NAME);
+    if (!existsSync(recordPath)) continue;
+    const record = readRecordFile(recordPath);
+    if (record.kind === "error") return record;
+    const expectedName = validateInstanceName(entry.name);
+    if (
+      expectedName.kind === "error" ||
+      record.value.name !== expectedName.value ||
+      names.has(record.value.name)
+    ) {
+      return instanceRegistryError(
+        "record_invalid",
+        `Instance directory ${entry.name} does not uniquely match its saved normalized name.`,
+      );
+    }
+    names.add(record.value.name);
+    records.push(record.value);
+  }
+  records.sort((left, right) => left.name.localeCompare(right.name));
+  return instanceRegistrySuccess(records);
+}
+
+function cleanupFile(path: string): void {
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // Best effort: a failed atomic write must not hide the original error.
+  }
+}
+
+export function writeInstanceRecord(
+  root: string,
+  record: InstanceRecord,
+): InstanceRegistryResult<InstanceRecord> {
+  const validated = InstanceRecordSchema.safeParse(record);
+  if (!validated.success) {
+    return instanceRegistryError(
+      "record_invalid",
+      `Cannot save instance record: ${validated.error.issues[0]?.message ?? "invalid record"}.`,
+    );
+  }
+  const paths = getInstancePaths(root, validated.data.name);
+  if (paths.kind === "error") return paths;
+  const rootResult = ensureInstancesRoot(root);
+  if (rootResult.kind === "error") return rootResult;
+  if (!ensurePrivateDirectorySync(paths.value.instanceDir)) {
+    return instanceRegistryError(
+      "registry_io",
+      `Cannot create or secure the private directory for instance ${validated.data.name}.`,
+    );
+  }
+  if (!ensurePrivateDirectorySync(validated.data.dataDir)) {
+    return instanceRegistryError(
+      "registry_io",
+      `Cannot create or secure the data directory for instance ${validated.data.name}.`,
+    );
+  }
+
+  const temporaryPath = join(
+    paths.value.instanceDir,
+    `.${INSTANCE_RECORD_FILE_NAME}.${String(process.pid)}.${randomUUID()}.tmp`,
+  );
+  let descriptor: number | null = null;
+  try {
+    descriptor = openSync(temporaryPath, "wx", PRIVATE_FILE_MODE);
+    writeFileSync(descriptor, `${JSON.stringify(validated.data, null, 2)}\n`, "utf8");
+    closeSync(descriptor);
+    descriptor = null;
+    if (!securePrivateFileSync(temporaryPath)) {
+      cleanupFile(temporaryPath);
+      return instanceRegistryError(
+        "registry_io",
+        `Cannot secure the saved record for instance ${validated.data.name}.`,
+      );
+    }
+    renameSync(temporaryPath, paths.value.recordPath);
+    return instanceRegistrySuccess(validated.data);
+  } catch {
+    if (descriptor !== null) {
+      try {
+        closeSync(descriptor);
+      } catch {
+        // The original write error remains the actionable failure.
+      }
+    }
+    cleanupFile(temporaryPath);
+    return instanceRegistryError(
+      "registry_io",
+      `Cannot atomically save the record for instance ${validated.data.name}.`,
+    );
+  }
+}
+
+const InstanceLockOwnerSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    pid: z.number().int().positive(),
+    token: z.string().min(8),
+    createdAt: z.string().datetime(),
+  })
+  .strict();
+
+type InstanceLockOwner = z.infer<typeof InstanceLockOwnerSchema>;
+
+export type InstanceLockHandle = {
+  path: string;
+  release: () => InstanceRegistryResult<void>;
+};
+
+export type InstanceLockOptions = {
+  timeoutMs?: number;
+  retryDelayMs?: number;
+  staleAfterMs?: number;
+  pid?: number;
+  now?: () => number;
+  sleep?: (milliseconds: number) => Promise<void>;
+  isProcessAlive?: (pid: number) => boolean;
+  createToken?: () => string;
+};
+
+function defaultSleep(milliseconds: number): Promise<void> {
+  return new Promise((resolveSleep) => {
+    setTimeout(resolveSleep, milliseconds);
+  });
+}
+
+function defaultIsProcessAlive(pid: number): boolean {
+  if (pid === process.pid) return true;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return nodeErrorCode(error) !== "ESRCH";
+  }
+}
+
+function readLockOwner(lockPath: string): InstanceLockOwner | null {
+  try {
+    const raw: unknown = JSON.parse(readFileSync(join(lockPath, LOCK_OWNER_FILE_NAME), "utf8"));
+    const parsed = InstanceLockOwnerSchema.safeParse(raw);
+    return parsed.success ? parsed.data : null;
+  } catch {
+    return null;
+  }
+}
+
+function lockCreatedAt(lockPath: string, owner: InstanceLockOwner | null): number | null {
+  if (owner !== null) return Date.parse(owner.createdAt);
+  try {
+    return statSync(lockPath).mtimeMs;
+  } catch {
+    return null;
+  }
+}
+
+function recoverStaleLock(
+  lockPath: string,
+  staleAfterMs: number,
+  now: number,
+  isProcessAlive: (pid: number) => boolean,
+): boolean {
+  const owner = readLockOwner(lockPath);
+  const createdAt = lockCreatedAt(lockPath, owner);
+  if (createdAt === null || now - createdAt < staleAfterMs) return false;
+  if (owner !== null && isProcessAlive(owner.pid)) return false;
+
+  const recoveredPath = `${lockPath}.stale-${randomUUID()}`;
+  try {
+    renameSync(lockPath, recoveredPath);
+    rmSync(recoveredPath, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function releaseDirectoryLock(lockPath: string, token: string): InstanceRegistryResult<void> {
+  if (!existsSync(lockPath)) return instanceRegistrySuccess(undefined);
+  const owner = readLockOwner(lockPath);
+  if (owner === null || owner.token !== token) {
+    return instanceRegistryError(
+      "lock_not_owned",
+      `Lifecycle lock ${lockPath} is no longer owned by this command.`,
+    );
+  }
+  try {
+    rmSync(lockPath, { recursive: true, force: true });
+    return instanceRegistrySuccess(undefined);
+  } catch {
+    return instanceRegistryError("registry_io", `Cannot release lifecycle lock ${lockPath}.`);
+  }
+}
+
+async function acquireDirectoryLock(
+  lockPath: string,
+  options: InstanceLockOptions,
+): Promise<InstanceRegistryResult<InstanceLockHandle>> {
+  const timeoutMs = options.timeoutMs ?? DEFAULT_INSTANCE_LOCK_TIMEOUT_MS;
+  const retryDelayMs = options.retryDelayMs ?? DEFAULT_LOCK_RETRY_MS;
+  const staleAfterMs = options.staleAfterMs ?? DEFAULT_INSTANCE_LOCK_STALE_MS;
+  const pid = options.pid ?? process.pid;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? defaultSleep;
+  const isProcessAlive = options.isProcessAlive ?? defaultIsProcessAlive;
+  const createToken = options.createToken ?? randomUUID;
+  const startedAt = now();
+
+  while (now() - startedAt <= timeoutMs) {
+    const token = createToken();
+    try {
+      mkdirSync(lockPath, { mode: 0o700 });
+    } catch (error) {
+      if (nodeErrorCode(error) !== "EEXIST") {
+        return instanceRegistryError("registry_io", `Cannot acquire lifecycle lock ${lockPath}.`);
+      }
+
+      if (recoverStaleLock(lockPath, staleAfterMs, now(), isProcessAlive)) continue;
+      if (now() - startedAt >= timeoutMs) break;
+      await sleep(retryDelayMs);
+      continue;
+    }
+
+    try {
+      if (!ensurePrivateDirectorySync(lockPath)) {
+        rmSync(lockPath, { recursive: true, force: true });
+        return instanceRegistryError("registry_io", `Cannot secure lifecycle lock ${lockPath}.`);
+      }
+      const owner: InstanceLockOwner = {
+        schemaVersion: 1,
+        pid,
+        token,
+        createdAt: new Date(now()).toISOString(),
+      };
+      const ownerPath = join(lockPath, LOCK_OWNER_FILE_NAME);
+      writeFileSync(ownerPath, `${JSON.stringify(owner)}\n`, {
+        encoding: "utf8",
+        flag: "wx",
+        mode: PRIVATE_FILE_MODE,
+      });
+      if (!securePrivateFileSync(ownerPath)) {
+        rmSync(lockPath, { recursive: true, force: true });
+        return instanceRegistryError("registry_io", `Cannot secure lifecycle lock ${lockPath}.`);
+      }
+      return instanceRegistrySuccess({
+        path: lockPath,
+        release: () => releaseDirectoryLock(lockPath, token),
+      });
+    } catch {
+      try {
+        rmSync(lockPath, { recursive: true, force: true });
+      } catch {
+        // The registry error remains actionable even if cleanup is deferred.
+      }
+      return instanceRegistryError("registry_io", `Cannot acquire lifecycle lock ${lockPath}.`);
+    }
+  }
+
+  return instanceRegistryError(
+    "lock_timeout",
+    `Timed out waiting for lifecycle lock ${lockPath}; retry after the other command finishes.`,
+  );
+}
+
+export async function acquireRegistryLock(
+  root: string,
+  options: InstanceLockOptions = {},
+): Promise<InstanceRegistryResult<InstanceLockHandle>> {
+  const ensured = ensureInstancesRoot(root);
+  return ensured.kind === "error"
+    ? ensured
+    : acquireDirectoryLock(join(root, ROOT_LOCK_DIRECTORY_NAME), options);
+}
+
+export async function acquireInstanceLock(
+  root: string,
+  rawName: string,
+  options: InstanceLockOptions = {},
+): Promise<InstanceRegistryResult<InstanceLockHandle>> {
+  const paths = getInstancePaths(root, rawName);
+  if (paths.kind === "error") return paths;
+  const ensured = ensureInstancesRoot(root);
+  if (ensured.kind === "error") return ensured;
+  if (!ensurePrivateDirectorySync(paths.value.instanceDir)) {
+    return instanceRegistryError(
+      "registry_io",
+      `Cannot create or secure the private directory for instance ${rawName}.`,
+    );
+  }
+  return acquireDirectoryLock(paths.value.lockPath, options);
+}
+
+type LockedOperation<T> = () => InstanceRegistryResult<T> | Promise<InstanceRegistryResult<T>>;
+
+async function runWithLock<T>(
+  acquired: Promise<InstanceRegistryResult<InstanceLockHandle>>,
+  operation: LockedOperation<T>,
+): Promise<InstanceRegistryResult<T>> {
+  const lock = await acquired;
+  if (lock.kind === "error") return lock;
+
+  let result: InstanceRegistryResult<T>;
+  try {
+    result = await operation();
+  } catch {
+    result = instanceRegistryError("registry_io", "The lifecycle registry operation failed.");
+  }
+  const released = lock.value.release();
+  return released.kind === "error" && result.kind === "success" ? released : result;
+}
+
+export function withRegistryLock<T>(
+  root: string,
+  operation: LockedOperation<T>,
+  options: InstanceLockOptions = {},
+): Promise<InstanceRegistryResult<T>> {
+  return runWithLock(acquireRegistryLock(root, options), operation);
+}
+
+export function withInstanceLock<T>(
+  root: string,
+  rawName: string,
+  operation: LockedOperation<T>,
+  options: InstanceLockOptions = {},
+): Promise<InstanceRegistryResult<T>> {
+  return runWithLock(acquireInstanceLock(root, rawName, options), operation);
+}
+
+type PathApi = typeof win32;
+
+export type CanonicalDataDirectory = {
+  path: string;
+  comparisonKey: string;
+};
+
+export type CanonicalizeDataDirectoryOptions = {
+  platform?: typeof process.platform;
+  cwd?: string;
+  realpath?: (path: string) => string;
+};
+
+function pathApiForPlatform(platform: typeof process.platform): PathApi {
+  return platform === "win32" ? win32 : posix;
+}
+
+function resolveRealPathWithMissingTail(
+  absolutePath: string,
+  pathApi: PathApi,
+  realpath: (path: string) => string,
+): string {
+  let current = absolutePath;
+  const missingSegments: string[] = [];
+  while (true) {
+    try {
+      return pathApi.join(realpath(current), ...missingSegments.reverse());
+    } catch {
+      const parent = pathApi.dirname(current);
+      if (parent === current) return absolutePath;
+      missingSegments.push(pathApi.basename(current));
+      current = parent;
+    }
+  }
+}
+
+export function canonicalizeDataDirectory(
+  rawPath: string,
+  options: CanonicalizeDataDirectoryOptions = {},
+): InstanceRegistryResult<CanonicalDataDirectory> {
+  if (rawPath.trim().length === 0 || rawPath.includes("\u0000")) {
+    return instanceRegistryError("data_dir_invalid", "Instance data directory cannot be empty.");
+  }
+
+  const platform = options.platform ?? process.platform;
+  const pathApi = pathApiForPlatform(platform);
+  const cwd = options.cwd ?? process.cwd();
+  const absolutePath = pathApi.resolve(cwd, rawPath);
+  const resolvedPath = resolveRealPathWithMissingTail(
+    absolutePath,
+    pathApi,
+    options.realpath ?? realpathSync.native,
+  );
+  const normalizedPath = pathApi.normalize(resolvedPath);
+  const root = pathApi.parse(normalizedPath).root;
+  const withoutTrailingSeparator =
+    normalizedPath === root ? normalizedPath : normalizedPath.replace(/[\\/]+$/u, "");
+  return instanceRegistrySuccess({
+    path: withoutTrailingSeparator,
+    comparisonKey:
+      platform === "win32" ? withoutTrailingSeparator.toLowerCase() : withoutTrailingSeparator,
+  });
+}
+
+export function validateDataDirectoryAssignment(
+  rawPath: string,
+  records: readonly InstanceRecord[],
+  excludeName?: string,
+  options: CanonicalizeDataDirectoryOptions = {},
+): InstanceRegistryResult<CanonicalDataDirectory> {
+  const candidate = canonicalizeDataDirectory(rawPath, options);
+  if (candidate.kind === "error") return candidate;
+  const normalizedExcludedName = excludeName?.toLowerCase();
+
+  for (const record of records) {
+    if (record.name === normalizedExcludedName) continue;
+    const registered = canonicalizeDataDirectory(record.dataDir, options);
+    if (registered.kind === "error") {
+      return instanceRegistryError(
+        "data_dir_conflict",
+        `Cannot safely compare the data directory registered to instance ${record.name}.`,
+      );
+    }
+    if (registered.value.comparisonKey === candidate.value.comparisonKey) {
+      return instanceRegistryError(
+        "data_dir_conflict",
+        `Data directory ${candidate.value.path} is already assigned to instance ${record.name}; named instances cannot share data.`,
+      );
+    }
+  }
+  return candidate;
+}
+
+export type InstancePortPair = {
+  publicPort: number;
+  upstreamPort: number;
+};
+
+export type PortAvailabilityCheck = (port: number, host: string) => boolean | Promise<boolean>;
+
+export type PlanInstancePortsOptions = {
+  records: readonly InstanceRecord[];
+  requestedPublicPort?: number;
+  requestedUpstreamPort?: number;
+  excludeName?: string;
+  publicHost?: string;
+  isPortAvailable?: PortAvailabilityCheck;
+};
+
+function validPort(port: number): boolean {
+  return Number.isInteger(port) && port >= 1 && port <= 65_535;
+}
+
+function registeredPortOwner(
+  pair: InstancePortPair,
+  records: readonly InstanceRecord[],
+  excludeName: string | undefined,
+): string | null {
+  const excluded = excludeName?.toLowerCase();
+  for (const record of records) {
+    if (record.name === excluded) continue;
+    const occupied = new Set([record.publicPort, record.upstreamPort]);
+    if (occupied.has(pair.publicPort) || occupied.has(pair.upstreamPort)) return record.name;
+  }
+  return null;
+}
+
+export function isPortAvailableByBinding(port: number, host: string): Promise<boolean> {
+  return new Promise((resolveAvailability) => {
+    const server = createServer();
+    let settled = false;
+    const finish = (available: boolean): void => {
+      if (settled) return;
+      settled = true;
+      server.removeAllListeners();
+      resolveAvailability(available);
+    };
+    server.once("error", () => finish(false));
+    server.once("listening", () => {
+      server.close((error) => finish(error === undefined));
+    });
+    server.unref();
+    try {
+      server.listen({ port, host, exclusive: true });
+    } catch {
+      finish(false);
+    }
+  });
+}
+
+async function pairIsAvailable(
+  pair: InstancePortPair,
+  publicHost: string,
+  check: PortAvailabilityCheck,
+): Promise<{ available: boolean; conflictingPort: number | null }> {
+  if (!(await check(pair.publicPort, publicHost))) {
+    return { available: false, conflictingPort: pair.publicPort };
+  }
+  if (!(await check(pair.upstreamPort, "127.0.0.1"))) {
+    return { available: false, conflictingPort: pair.upstreamPort };
+  }
+  return { available: true, conflictingPort: null };
+}
+
+export async function planInstancePorts(
+  options: PlanInstancePortsOptions,
+): Promise<InstanceRegistryResult<InstancePortPair>> {
+  const check = options.isPortAvailable ?? isPortAvailableByBinding;
+  const publicHost = options.publicHost ?? "127.0.0.1";
+
+  if (options.requestedPublicPort === undefined && options.requestedUpstreamPort !== undefined) {
+    return instanceRegistryError(
+      "port_invalid",
+      "An explicit upstream port requires an explicit public port.",
+    );
+  }
+
+  if (options.requestedPublicPort !== undefined) {
+    const pair = {
+      publicPort: options.requestedPublicPort,
+      upstreamPort:
+        options.requestedUpstreamPort ??
+        options.requestedPublicPort + NAMED_INSTANCE_UPSTREAM_OFFSET,
+    };
+    if (
+      !validPort(pair.publicPort) ||
+      !validPort(pair.upstreamPort) ||
+      pair.publicPort === pair.upstreamPort
+    ) {
+      return instanceRegistryError(
+        "port_invalid",
+        "Public and upstream ports must be different integers from 1 to 65535.",
+      );
+    }
+    const owner = registeredPortOwner(pair, options.records, options.excludeName);
+    if (owner !== null) {
+      return instanceRegistryError(
+        "port_conflict",
+        `Requested port pair ${String(pair.publicPort)}/${String(pair.upstreamPort)} overlaps instance ${owner}.`,
+      );
+    }
+    const availability = await pairIsAvailable(pair, publicHost, check);
+    return availability.available
+      ? instanceRegistrySuccess(pair)
+      : instanceRegistryError(
+          "port_conflict",
+          `Port ${String(availability.conflictingPort)} already has a listener; no process was terminated.`,
+        );
+  }
+
+  for (
+    let publicPort = DEFAULT_NAMED_INSTANCE_PUBLIC_PORT;
+    publicPort + NAMED_INSTANCE_UPSTREAM_OFFSET <= 65_535;
+    publicPort += NAMED_INSTANCE_PORT_STEP
+  ) {
+    const pair = {
+      publicPort,
+      upstreamPort: publicPort + NAMED_INSTANCE_UPSTREAM_OFFSET,
+    };
+    if (registeredPortOwner(pair, options.records, options.excludeName) !== null) continue;
+    const availability = await pairIsAvailable(pair, publicHost, check);
+    if (availability.available) return instanceRegistrySuccess(pair);
+  }
+
+  return instanceRegistryError(
+    "port_exhausted",
+    `No available named-instance port pair was found from ${String(DEFAULT_NAMED_INSTANCE_PUBLIC_PORT)} through 65535.`,
+  );
+}