@tonyclaw/agent-inspector 3.1.32 → 4.0.2

package/src/cli/instanceRegistry.ts

@@ -1,731 +0,0 @@
-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);
-}
-
-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.`,
-  );
-}