import { createHash, randomBytes as createRandomBytes, randomUUID } from "node:crypto";
import { constants as fileSystemConstants } from "node:fs";
import * as defaultFileSystem from "node:fs/promises";
import { createConnection, createServer } from "node:net";
import { homedir } from "node:os";
import { basename, dirname, isAbsolute, join, resolve } from "node:path";

import {
  createCodexComposeFile,
  createCodexChatComposeFile,
  createCodexChatConfig,
  createCodexChatDockerfile,
  createCodexChatRequirements,
  createCodexConfig,
  createCodexDockerfile,
  createCodexRequirements,
  createGrokBuildComposeFile,
  createGrokBuildDockerfile,
  GROK_BUILD_CLI_VERSION,
  createLocalDeploymentPlan,
  createLocalDockerignore,
  validateInstallId,
  validateLocalPort,
  validateLocalTarget,
} from "../domain/local-endpoints.js";
import {
  safeSiwcCatalogFailure, safeSiwcRuntimeFailure,
  validateSiwcAuthBinding, validateSiwcRegistrationId,
} from "../domain/safety.js";
import {
  runLocalProcess,
  lockDownLocalPath,
  validateLocalDockerHost,
} from "../infrastructure/local-process.js";
import { getLocalProcessIdentity } from "../infrastructure/process-identity.js";
import { runCodexSiwcCommand } from "./codex-login.js";
import { collectSiwcRuntimeAssets } from "./siwc-runtime-assets.js";
import {
  finishAuthHandoff, prepareAuthHandoff, readAuthHandoff, readPendingAuthHandoff, readRegistration, listRegistrations,
  validateSiwcHostId,
} from "./siwc-session.mjs";
import {
  fingerprintLocalSiwcFiles, fingerprintLocalSiwcResources, localSiwcFinalizationFailure,
  localSiwcStagingPath, readLocalSiwcStaging, readLocalSiwcResumeAuthBinding,
  assertNoLocalSiwcOneOffContainers,
} from "./local-integration-lifecycle-lock.js";

const MANAGED_MARKER = ".managed-by-relmio.json";
const ROOT_MARKER = ".managed-by-relmio-root.json";
const MARKER_SCHEMA_VERSION = 2;
const CODEX_SIWC_MARKER_SCHEMA_VERSION = 3;
const ROOT_MARKER_SCHEMA_VERSION = 1;
const COMPOSE_FILENAME = "docker-compose.yml";
const INCOMPLETE_LOCK_STALE_MS = 30_000;
const PROJECTS = Object.freeze({
  "codex-chatgpt": Object.freeze({
    projectPrefix: "relmio-codex-chatgpt",
    serviceName: "codex",
    containerPort: 4_500,
    volumeNames: Object.freeze(["codex-state", "siwc-store", "codex-workspace"]),
  }),
  "codex-chat": Object.freeze({
    projectPrefix: "relmio-codex-chat",
    serviceName: "codex-chat",
    containerPort: 14_501,
    volumeNames: Object.freeze(["codex-state", "siwc-store", "codex-workspace"]),
  }),
  "xai-grok-build": Object.freeze({
    projectPrefix: "relmio-xai-grok-build",
    serviceName: "grok-build",
    containerPort: 14_502,
    volumeNames: Object.freeze(["grok-home"]),
  }),
});
const SIWC_ASSET_PATHS = new Set([
  "gateway/openai-oauth-sidecar.mjs", "gateway/codex-chat.js",
  "gateway/codex-app-server.mjs", "services/siwc-session.mjs",
  "services/siwc-handoff.mjs", "infrastructure/local-process.js",
  "services/local-integration-lifecycle-lock.js", "services/codex-images.mjs", "services/model-discovery.mjs",
  "infrastructure/process-identity.js",
]);
const DOCKER_SELECTION_VARIABLES = Object.freeze([
  "DOCKER_HOST",
  "DOCKER_CONTEXT",
  "DOCKER_CONFIG",
  "DOCKER_TLS_VERIFY",
  "DOCKER_CERT_PATH",
  "BUILDKIT_HOST",
]);

function isMissing(error) {
  return error?.code === "ENOENT";
}

function errorWithCode(message, code) {
  const error = new Error(message);
  error.code = code;
  return error;
}

function assertSupportedPlatform(platform) {
  if (typeof platform !== "string" || platform.length === 0) {
    throw new TypeError("The local platform is invalid.");
  }
}

function validateAbsolutePath(value) {
  if (
    typeof value !== "string" ||
    value.trim() === "" ||
    value.includes("\0") ||
    !isAbsolute(value)
  ) {
    throw new TypeError("Relmio local storage path is invalid.");
  }
  return resolve(value);
}

function validateManagedBase(value) {
  const resolved = validateAbsolutePath(value);
  if (basename(resolved) !== ".relmio") {
    throw new TypeError("Relmio local storage path is invalid.");
  }
  return resolved;
}

function validateInstallDirectory(value, target) {
  const resolved = validateAbsolutePath(value);
  if (
    basename(resolved) !== target ||
    basename(dirname(resolved)) !== "local" ||
    basename(resolve(resolved, "..", "..")) !== ".relmio"
  ) {
    throw new TypeError("The local endpoint install directory is invalid.");
  }
  return resolved;
}

export async function resolveLocalInstallRoot({
  target,
  env = process.env,
  homeDirectory = homedir(),
  fileSystem = defaultFileSystem,
  platform = process.platform,
} = {}) {
  assertSupportedPlatform(platform);
  const safeTarget = validateLocalTarget(target);
  const configuredHome =
    typeof env.RELMIO_HOME === "string" && env.RELMIO_HOME.trim() !== ""
      ? env.RELMIO_HOME
      : resolve(homeDirectory, ".relmio");
  const requestedHome = validateManagedBase(configuredHome);
  const requestedParent = dirname(requestedHome);
  let canonicalParent;
  try {
    canonicalParent = await fileSystem.realpath(requestedParent);
  } catch {
    throw new Error("The parent of the Relmio local storage directory is invalid.");
  }
  if (canonicalParent !== resolve(requestedParent)) {
    throw new Error(
      "Relmio refuses a local storage path with a symbolic-link ancestor.",
    );
  }
  const relmioHome = join(canonicalParent, ".relmio");
  return join(relmioHome, "local", safeTarget);
}

async function lstatIfExists(fileSystem, path) {
  try {
    return await fileSystem.lstat(path);
  } catch (error) {
    if (isMissing(error)) {
      return null;
    }
    throw new Error("Relmio could not inspect its local managed directory.");
  }
}

function assertDirectoryMetadata(metadata) {
  if (metadata.isSymbolicLink()) {
    throw new Error("Relmio refuses to use a symbolic link in its managed path.");
  }
  if (!metadata.isDirectory()) {
    throw new Error("Relmio local managed path is not a directory.");
  }
}

async function assertRegularManagedMarker(fileSystem, path, errorMessage) {
  const metadata = await lstatIfExists(fileSystem, path);
  if (!metadata || metadata.isSymbolicLink() || !metadata.isFile()) {
    throw new Error(errorMessage);
  }
}

async function inspectManagedRoot({ fileSystem, relmioHome, installRoot, target, staging }) {
  const localRoot = join(relmioHome, "local");
  const homeMetadata = await lstatIfExists(fileSystem, relmioHome);
  if (!homeMetadata) {
    return {
      baseExists: false,
      deploymentMode: "installed",
      marker: null,
      previousPort: null,
    };
  }
  assertDirectoryMetadata(homeMetadata);

  let rootMarkerContents;
  const rootMarkerPath = join(relmioHome, ROOT_MARKER);
  await assertRegularManagedMarker(
    fileSystem,
    rootMarkerPath,
    "The Relmio local storage directory already exists without a valid managed-root marker. Nothing was changed.",
  );
  try {
    rootMarkerContents = await fileSystem.readFile(rootMarkerPath, "utf8");
  } catch {
    throw new Error(
      "The Relmio local storage directory already exists without a valid managed-root marker. Nothing was changed.",
    );
  }
  try {
    const rootMarker = JSON.parse(rootMarkerContents);
    if (
      rootMarker?.schemaVersion !== ROOT_MARKER_SCHEMA_VERSION ||
      rootMarker?.kind !== "relmio-local-root"
    ) {
      throw new TypeError();
    }
  } catch {
    throw new Error(
      "The Relmio local storage managed-root marker is invalid. Nothing was changed.",
    );
  }

  for (const path of [localRoot, installRoot]) {
    const metadata = await lstatIfExists(fileSystem, path);
    if (metadata) {
      assertDirectoryMetadata(metadata);
    }
  }

  const installMetadata = await lstatIfExists(fileSystem, installRoot);
  if (!installMetadata) {
    return {
      baseExists: true,
      deploymentMode: "installed",
      marker: null,
      previousPort: null,
    };
  }

  if (staging && !(await lstatIfExists(fileSystem, join(installRoot, MANAGED_MARKER)))) {
    return { baseExists: true, deploymentMode: "installed", marker: null, previousPort: null };
  }
  let markerContents;
  const markerPath = join(installRoot, MANAGED_MARKER);
  await assertRegularManagedMarker(
    fileSystem,
    markerPath,
    "The local endpoint directory already exists without a Relmio managed marker. Nothing was overwritten.",
  );
  try {
    markerContents = await fileSystem.readFile(markerPath, "utf8");
  } catch (error) {
    if (isMissing(error)) {
      throw new Error(
        "The local endpoint directory already exists without a Relmio managed marker. Nothing was overwritten.",
      );
    }
    throw new Error("Relmio could not read its local managed marker.");
  }

  try {
    const marker = JSON.parse(markerContents);
    const installId = validateInstallId(marker?.installId);
    const dockerHost = validateLocalDockerHost(marker?.dockerHost);
    const projectName = `${PROJECTS[target].projectPrefix}-${installId}`;
    const tokenSha256 = marker?.tokenSha256;
    if (
      !(
        marker?.schemaVersion === MARKER_SCHEMA_VERSION ||
        (target !== "xai-grok-build" && marker?.schemaVersion === CODEX_SIWC_MARKER_SCHEMA_VERSION)
      ) ||
      marker?.target !== target ||
      !Number.isInteger(marker?.port) ||
      marker?.projectName !== projectName ||
      (tokenSha256 !== undefined &&
        (typeof tokenSha256 !== "string" || !/^[a-f0-9]{64}$/u.test(tokenSha256)))
    ) {
      throw new TypeError();
    }
    const siwc = marker.schemaVersion === CODEX_SIWC_MARKER_SCHEMA_VERSION
      ? validateSiwcAuthBinding(marker.authBinding)
      : null;
    if (siwc && (
      marker.registrationId !== siwc.registrationId ||
      marker.clientId !== siwc.clientId ||
      typeof marker.ownerHostId !== "string" ||
      marker.ownerHostId === siwc.ownerHostId
    )) throw new TypeError();
    if (siwc && marker.legacyInstallId !== undefined) {
      validateInstallId(marker.legacyInstallId);
      if (marker.legacyInstallId === installId) throw new TypeError();
    }
    if (siwc && marker.previousWasSiwc !== undefined &&
        (marker.previousWasSiwc !== true || !marker.legacyInstallId)) {
      throw new TypeError();
    }
    return {
      baseExists: true,
      deploymentMode: "updated",
      marker: {
        schemaVersion: marker.schemaVersion,
        target,
        port: marker.port,
        dockerHost,
        installId,
        projectName,
        ...(siwc ? {
          authBinding: siwc,
          registrationId: siwc.registrationId,
          clientId: siwc.clientId,
          ownerHostId: validateSiwcHostId(marker.ownerHostId),
          ...(marker.legacyInstallId ? { legacyInstallId: marker.legacyInstallId } : {}),
          ...(marker.previousWasSiwc ? { previousWasSiwc: true } : {}),
        } : {}),
        ...(target === "xai-grok-build" && typeof tokenSha256 === "string"
          ? { tokenSha256 }
          : {}),
      },
      previousPort: marker.port,
    };
  } catch {
    throw new Error("The local endpoint managed marker is invalid. Nothing was overwritten.");
  }
}

async function initializeManagedBase({
  fileSystem,
  relmioHome,
  baseExists,
  platform,
  lockDownPath,
}) {
  if (baseExists) {
    await fileSystem.chmod(relmioHome, 0o700);
    if (platform === "win32") await lockDownPath(relmioHome, { platform });
    return;
  }
  let createdIdentity = null;
  try {
    await fileSystem.mkdir(relmioHome, { mode: 0o700 });
    createdIdentity = await captureFreshDirectoryIdentity(fileSystem, relmioHome);
    await fileSystem.chmod(relmioHome, 0o700);
    if (platform === "win32") await lockDownPath(relmioHome, { platform });
    await writeManagedFile(
      fileSystem,
      join(relmioHome, ROOT_MARKER),
      `${JSON.stringify({
        schemaVersion: ROOT_MARKER_SCHEMA_VERSION,
        kind: "relmio-local-root",
      })}\n`,
      0o600,
    );
  } catch (error) {
    await removeFreshEmptyManagedRoot({
      fileSystem,
      relmioHome,
      createdIdentity,
    });
    throw error;
  }
}

function isDirectoryIdentity(metadata, identity) {
  return (
    metadata !== null &&
    !metadata.isSymbolicLink() &&
    metadata.isDirectory() &&
    identity !== null &&
    metadata.dev === identity.dev &&
    metadata.ino === identity.ino
  );
}

async function captureFreshDirectoryIdentity(fileSystem, path) {
  const metadata = await lstatIfExists(fileSystem, path);
  if (!metadata || metadata.isSymbolicLink() || !metadata.isDirectory()) {
    throw new Error("Relmio could not verify its newly created local storage directory.");
  }
  return { dev: metadata.dev, ino: metadata.ino };
}

async function removeFreshEmptyManagedRoot({
  fileSystem,
  relmioHome,
  createdIdentity,
}) {
  if (!createdIdentity) return;
  try {
    let metadata = await lstatIfExists(fileSystem, relmioHome);
    if (!isDirectoryIdentity(metadata, createdIdentity)) return;
    if ((await fileSystem.readdir(relmioHome)).length !== 0) return;
    metadata = await lstatIfExists(fileSystem, relmioHome);
    if (!isDirectoryIdentity(metadata, createdIdentity)) return;
    await fileSystem.rmdir(relmioHome);
  } catch {
    // Only an exact, still-empty root may be removed during recovery.
  }
}

async function ensurePrivateDirectory(fileSystem, path, platform, lockDownPath) {
  const existing = await lstatIfExists(fileSystem, path);
  if (existing) {
    assertDirectoryMetadata(existing);
  } else {
    await fileSystem.mkdir(path, { mode: 0o700 });
  }
  await fileSystem.chmod(path, 0o700);
  if (platform === "win32") await lockDownPath(path, { platform });
}

async function writeManagedFile(fileSystem, path, contents, mode) {
  const existing = await lstatIfExists(fileSystem, path);
  if (existing && (existing.isSymbolicLink() || !existing.isFile())) {
    throw new Error("Relmio refuses to replace a non-file in its managed directory.");
  }

  const temporaryPath = `${path}.tmp-${randomUUID()}`;
  let committed = false;
  try {
    await fileSystem.writeFile(temporaryPath, contents, { flag: "wx", mode });
    await fileSystem.chmod(temporaryPath, mode);
    await fileSystem.rename(temporaryPath, path);
    committed = true;
    await fileSystem.chmod(path, mode);
  } catch {
    try {
      await fileSystem.unlink(temporaryPath);
    } catch {
      // The temporary file may not have been created.
    }
    const error = new Error("Relmio could not write its local managed files.");
    error.committed = committed;
    throw error;
  }
}

function createClientCredential(randomBytes) {
  const capabilityBytes = randomBytes(32);
  if (!Buffer.isBuffer(capabilityBytes) || capabilityBytes.length !== 32) {
    throw new Error("Relmio could not generate a strong local capability.");
  }
  const clientCredential = capabilityBytes.toString("base64url");
  const tokenSha256 = createHash("sha256")
    .update(clientCredential)
    .digest("hex");
  return { clientCredential, tokenSha256 };
}

function validateClientCredentialVerifier(value) {
  if (typeof value !== "string" || !/^[a-f0-9]{64}$/u.test(value)) {
    throw new TypeError("The staged local client credential is invalid.");
  }
  return value;
}

function defaultIsProcessAlive(processId) {
  try {
    process.kill(processId, 0);
    return true;
  } catch (error) {
    return error?.code !== "ESRCH";
  }
}

function parseLockOwner(value) {
  try {
    const owner = JSON.parse(value);
    if (
      Number.isSafeInteger(owner?.processId) &&
      owner.processId > 0 &&
      typeof owner?.ownerToken === "string" &&
      owner.ownerToken.length > 0 &&
      owner.ownerToken.length <= 128 &&
      (owner.processStartIdentity === undefined || (
        typeof owner.processStartIdentity === "string" &&
        owner.processStartIdentity.length > 0 &&
        Buffer.byteLength(owner.processStartIdentity) <= 512 &&
        !/[\0\r\n]/u.test(owner.processStartIdentity)
      ))
    ) {
      return owner;
    }
  } catch {
    // An incomplete owner record is recoverable only after its metadata is stale.
  }
  return null;
}

async function readLockOwnerState(fileSystem, ownerPath, directoryPath) {
  const directoryMetadata = await fileSystem.lstat(directoryPath);
  const directoryFingerprint = Object.freeze({
    dev: directoryMetadata.dev,
    ino: directoryMetadata.ino,
    birthtimeMs: directoryMetadata.birthtimeMs,
  });
  let serialized;
  let ownerMetadata;
  try {
    ownerMetadata = await fileSystem.lstat(ownerPath);
    serialized = await fileSystem.readFile(ownerPath, "utf8");
  } catch (error) {
    if (!isMissing(error)) {
      throw error;
    }
  }
  let ownerFingerprint = null;
  if (serialized !== undefined) {
    const ownerAfterRead = await fileSystem.lstat(ownerPath);
    ownerFingerprint = Object.freeze({
      raw: serialized,
      size: ownerMetadata.size,
      dev: ownerMetadata.dev,
      ino: ownerMetadata.ino,
      mtimeMs: ownerMetadata.mtimeMs,
      ctimeMs: ownerMetadata.ctimeMs,
    });
    const afterFingerprint = {
      raw: serialized,
      size: ownerAfterRead.size,
      dev: ownerAfterRead.dev,
      ino: ownerAfterRead.ino,
      mtimeMs: ownerAfterRead.mtimeMs,
      ctimeMs: ownerAfterRead.ctimeMs,
    };
    if (!lockOwnerFingerprintMatches(ownerFingerprint, afterFingerprint)) {
      throw new Error("The local project lock changed during inspection.");
    }
  }
  return {
    owner: serialized === undefined ? null : parseLockOwner(serialized),
    serialized,
    modifiedAtMs: serialized === undefined ? directoryMetadata.mtimeMs : ownerMetadata.mtimeMs,
    directoryFingerprint,
    ownerFingerprint,
  };
}

function lockDirectoryFingerprintMatches(left, right) {
  return left?.dev === right?.dev && left?.ino === right?.ino &&
    left?.birthtimeMs === right?.birthtimeMs;
}

function lockOwnerFingerprintMatches(left, right) {
  if (left === null || right === null) return left === right;
  return left?.raw === right?.raw && left?.size === right?.size &&
    left?.dev === right?.dev && left?.ino === right?.ino &&
    left?.mtimeMs === right?.mtimeMs && left?.ctimeMs === right?.ctimeMs;
}

function isIncompleteLockStale(state) {
  return (
    state.owner === null &&
    Number.isFinite(state.modifiedAtMs) &&
    Date.now() - state.modifiedAtMs >= INCOMPLETE_LOCK_STALE_MS
  );
}

function lockOwnerStateMatches(left, right) {
  if (!lockDirectoryFingerprintMatches(
    left.directoryFingerprint,
    right.directoryFingerprint,
  )) return false;
  if (!lockOwnerFingerprintMatches(left.ownerFingerprint, right.ownerFingerprint)) {
    return false;
  }
  if (left.owner && right.owner) {
    return (
      left.owner.processId === right.owner.processId &&
      left.owner.ownerToken === right.owner.ownerToken &&
      left.owner.processStartIdentity === right.owner.processStartIdentity
    );
  }
  return left.owner === null && right.owner === null && left.serialized === right.serialized;
}

async function assertPublishedLockOwner(
  fileSystem,
  ownerPath,
  directoryPath,
  { processId, ownerToken, processStartIdentity },
) {
  const state = await readLockOwnerState(fileSystem, ownerPath, directoryPath);
  if (
    state.owner?.processId !== processId ||
    state.owner?.ownerToken !== ownerToken ||
    state.owner?.processStartIdentity !== processStartIdentity
  ) {
    throw new Error("The local lock owner changed during publication.");
  }
  return state;
}

async function exactLockEntriesMatch(fileSystem, path, state, nestedState = null) {
  const entries = (await fileSystem.readdir(path)).sort();
  const expected = [
    ...(nestedState ? [".reclaim"] : []),
    ...(state.serialized === undefined ? [] : ["owner.json"]),
  ].sort();
  if (
    entries.length !== expected.length ||
    entries.some((entry, index) => entry !== expected[index])
  ) return false;
  const current = await readLockOwnerState(
    fileSystem,
    join(path, "owner.json"),
    path,
  );
  if (!lockOwnerStateMatches(current, state)) return false;
  if (nestedState) {
    const nestedPath = join(path, ".reclaim");
    const nested = await readLockOwnerState(
      fileSystem,
      join(nestedPath, "owner.json"),
      nestedPath,
    );
    if (!lockOwnerStateMatches(nested, nestedState)) return false;
  }
  return true;
}

async function removeExactDetachedLock(fileSystem, path, state, nestedState = null) {
  if (!await exactLockEntriesMatch(fileSystem, path, state, nestedState)) {
    throw new Error("The detached local project lock changed.");
  }
  if (nestedState) {
    const nestedPath = join(path, ".reclaim");
    if (nestedState.serialized !== undefined) {
      await fileSystem.unlink(join(nestedPath, "owner.json"));
    }
    await fileSystem.rmdir(nestedPath);
  }
  if (state.serialized !== undefined) {
    await fileSystem.unlink(join(path, "owner.json"));
  }
  await fileSystem.rmdir(path);
}

async function removeDetachedStaleLock(fileSystem, path, state, nestedState = null) {
  try {
    await removeExactDetachedLock(fileSystem, path, state, nestedState);
  } catch {
    // A uniquely renamed stale artifact is outside the canonical lock path and
    // must not strand the newly published owner when best-effort cleanup fails.
  }
}

async function acquireLocalProjectLock(
  { installRoot, target, lockName = target },
  {
    fileSystem = defaultFileSystem,
    processId = process.pid,
    isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity,
    platform = process.platform,
  } = {},
) {
  const safeTarget = validateLocalTarget(target);
  if (
    typeof lockName !== "string" ||
    lockName !== safeTarget
  ) {
    throw new TypeError("The local project lock name is invalid.");
  }
  const safeInstallRoot = validateInstallDirectory(installRoot, safeTarget);
  const lockPath = join(
    dirname(resolve(safeInstallRoot, "..", "..")),
    `.relmio-local-${lockName}.lock`,
  );
  const ownerPath = join(lockPath, "owner.json");
  const ownerToken = randomUUID();
  const useProcessIdentity = typeof getProcessIdentity === "function" || (
    getProcessIdentity === undefined &&
    processId === process.pid &&
    isProcessAlive === defaultIsProcessAlive
  );
  const identityReader = typeof getProcessIdentity === "function"
    ? getProcessIdentity
    : getLocalProcessIdentity;
  let processStartIdentity;
  if (useProcessIdentity) {
    let identity;
    try { identity = await identityReader(processId, { platform }); } catch {
      throw new Error("Relmio could not verify its local project lock identity.");
    }
    if (
      identity?.state !== "active" ||
      typeof identity.startIdentity !== "string" ||
      identity.startIdentity.length === 0
    ) {
      throw new Error("Relmio could not verify its local project lock identity.");
    }
    processStartIdentity = identity.startIdentity;
  }
  const ownerPublication = Object.freeze({
    processId,
    ownerToken,
    ...(processStartIdentity === undefined ? {} : { processStartIdentity }),
  });
  let ownedLockState;

  async function lockOwnerIsActive(owner) {
    if (owner.ownerToken === ownerToken || owner.processId === processId) return true;
    if (owner.processStartIdentity !== undefined && useProcessIdentity) {
      let identity;
      try { identity = await identityReader(owner.processId, { platform }); } catch {
        return true;
      }
      if (identity?.state === "dead") return false;
      if (identity?.state !== "active" || typeof identity.startIdentity !== "string") {
        return true;
      }
      return identity.startIdentity === owner.processStartIdentity;
    }
    return isProcessAlive(owner.processId);
  }

  async function createLock() {
    await fileSystem.mkdir(lockPath, { mode: 0o700 });
    try {
      await fileSystem.writeFile(
        ownerPath,
        `${JSON.stringify(ownerPublication)}\n`,
        { flag: "wx", mode: 0o600 },
      );
      return await assertPublishedLockOwner(
        fileSystem,
        ownerPath,
        lockPath,
        ownerPublication,
      );
    } catch {
      // Leave an incomplete directory for stale recovery. Removing the shared
      // path here could delete a successor lock after this creator was paused.
      throw new Error("Relmio could not create its local project lock.");
    }
  }

  try {
    ownedLockState = await createLock();
  } catch (error) {
    if (error?.code !== "EEXIST") {
      throw error;
    }

    let ownerState;
    try {
      ownerState = await readLockOwnerState(fileSystem, ownerPath, lockPath);
    } catch {
      throw new Error("Another Relmio process is changing this local endpoint.");
    }
    const owner = ownerState.owner;
    if (
      (owner === null && !isIncompleteLockStale(ownerState)) ||
      (owner !== null && await lockOwnerIsActive(owner))
    ) {
      throw new Error("Another Relmio process is changing this local endpoint.");
    }

    const reclaimPath = join(lockPath, ".reclaim");
    const reclaimOwnerPath = join(reclaimPath, "owner.json");
    let reclaimClaimed = false;
    let ownedReclaimState;
    async function createReclaimClaim() {
      await fileSystem.mkdir(reclaimPath, { mode: 0o700 });
      try {
        await fileSystem.writeFile(
          reclaimOwnerPath,
          `${JSON.stringify(ownerPublication)}\n`,
          { flag: "wx", mode: 0o600 },
        );
        return await assertPublishedLockOwner(
          fileSystem,
          reclaimOwnerPath,
          reclaimPath,
          ownerPublication,
        );
      } catch {
        // The same identity rule applies to reclaim publication: never remove
        // a shared path after an owner write that may have lost a race.
        throw new Error("Relmio could not create its reclaim lock.");
      }
    }
    try {
      try {
        ownedReclaimState = await createReclaimClaim();
      } catch (error) {
        if (error?.code !== "EEXIST") {
          throw error;
        }
        const reclaimState = await readLockOwnerState(
          fileSystem,
          reclaimOwnerPath,
          reclaimPath,
        );
        const reclaimOwner = reclaimState.owner;
        if (
          (reclaimOwner === null && !isIncompleteLockStale(reclaimState)) ||
          (reclaimOwner !== null && await lockOwnerIsActive(reclaimOwner))
        ) {
          throw new Error("Another process owns the reclaim lock.");
        }
        const staleReclaimPath = `${reclaimPath}.stale-${randomUUID()}`;
        await fileSystem.rename(reclaimPath, staleReclaimPath);
        const detachedReclaimState = await readLockOwnerState(
          fileSystem,
          join(staleReclaimPath, "owner.json"),
          staleReclaimPath,
        );
        if (!lockOwnerStateMatches(detachedReclaimState, reclaimState)) {
          try { await fileSystem.rename(staleReclaimPath, reclaimPath); } catch {
            // Preserve both paths when the exact stale claim cannot be restored.
          }
          throw new Error("The reclaim lock owner changed.");
        }
        ownedReclaimState = await createReclaimClaim();
        await removeDetachedStaleLock(
          fileSystem,
          staleReclaimPath,
          detachedReclaimState,
        );
      }
      reclaimClaimed = true;
      const reclaimOwner = JSON.parse(
        await fileSystem.readFile(reclaimOwnerPath, "utf8"),
      );
      if (reclaimOwner?.ownerToken !== ownerToken) {
        throw new Error("The reclaim lock owner changed.");
      }
      const currentOwnerState = await readLockOwnerState(
        fileSystem,
        ownerPath,
        lockPath,
      );
      if (!lockOwnerStateMatches(currentOwnerState, ownerState)) {
        throw new Error("The local project lock owner changed.");
      }
      const stalePath = `${lockPath}.stale-${randomUUID()}`;
      await fileSystem.rename(lockPath, stalePath);
      const detachedOwnerState = await readLockOwnerState(
        fileSystem,
        join(stalePath, "owner.json"),
        stalePath,
      );
      const detachedReclaimState = await readLockOwnerState(
        fileSystem,
        join(stalePath, ".reclaim", "owner.json"),
        join(stalePath, ".reclaim"),
      );
      if (
        !lockOwnerStateMatches(detachedOwnerState, ownerState) ||
        !lockOwnerStateMatches(detachedReclaimState, ownedReclaimState)
      ) {
        try { await fileSystem.rename(stalePath, lockPath); } catch {
          // A changed or replaced path must be preserved for manual inspection.
        }
        throw new Error("The local project lock owner changed.");
      }
      reclaimClaimed = false;
      ownedLockState = await createLock();
      await removeDetachedStaleLock(
        fileSystem,
        stalePath,
        detachedOwnerState,
        detachedReclaimState,
      );
    } catch {
      if (reclaimClaimed) {
        try {
          const reclaimState = await readLockOwnerState(
            fileSystem,
            reclaimOwnerPath,
            reclaimPath,
          );
          if (
            ownedReclaimState &&
            lockOwnerStateMatches(reclaimState, ownedReclaimState)
          ) {
            await removeExactDetachedLock(
              fileSystem,
              reclaimPath,
              reclaimState,
            );
          }
        } catch {
          // A changed or contended lock remains owned by the other process.
        }
      }
      throw new Error("Another Relmio process is changing this local endpoint.");
    }
  }

  return async () => {
    let detachedPath;
    try {
      const current = await readLockOwnerState(fileSystem, ownerPath, lockPath);
      if (!ownedLockState || !lockOwnerStateMatches(current, ownedLockState)) {
        throw new Error("The local project lock owner changed.");
      }
      if ((await fileSystem.readdir(lockPath)).includes(".reclaim")) {
        throw new Error("The local project lock is contended.");
      }
      detachedPath = `${lockPath}.released-${randomUUID()}`;
      await fileSystem.rename(lockPath, detachedPath);
      const detached = await readLockOwnerState(
        fileSystem,
        join(detachedPath, "owner.json"),
        detachedPath,
      );
      if (!lockOwnerStateMatches(detached, ownedLockState)) {
        throw new Error("The local project lock changed during release.");
      }
      await removeExactDetachedLock(fileSystem, detachedPath, detached);
      detachedPath = undefined;
    } catch (error) {
      if (detachedPath) {
        try {
          await fileSystem.lstat(join(detachedPath, "owner.json"));
        } catch (ownerError) {
          if (isMissing(ownerError) && ownedLockState?.serialized !== undefined) {
            try {
              await fileSystem.writeFile(
                join(detachedPath, "owner.json"),
                ownedLockState.serialized,
                { flag: "wx", mode: 0o600 },
              );
              await fileSystem.chmod(join(detachedPath, "owner.json"), 0o600);
            } catch {
              // Preserve the detached directory if its exact owner cannot be restored.
            }
          }
        }
        try {
          await fileSystem.lstat(lockPath);
        } catch (error) {
          if (isMissing(error)) {
            try { await fileSystem.rename(detachedPath, lockPath); } catch {
              // Preserve a changed detached lock instead of deleting it.
            }
          }
        }
      }
      throw new Error("Relmio could not safely release its local project lock.", {
        cause: error,
      });
    }
  };
}

async function settleLocalProjectOperation({ completionLabel, operation, releaseLock }) {
  let result;
  let operationError;
  try { result = await operation(); } catch (error) { operationError = error; }

  let releaseError;
  try { await releaseLock(); } catch (error) { releaseError = error; }

  if (operationError) {
    if (releaseError && operationError.cause === undefined) {
      try {
        Object.defineProperty(operationError, "cause", {
          configurable: true,
          value: releaseError,
        });
      } catch { /* Preserve the authoritative operation error unchanged. */ }
    }
    throw operationError;
  }
  if (releaseError) {
    if (result?.credentialShownOnce === true && result.account?.ownership === "owned") {
      return localSiwcFinalizationFailure(result);
    }
    throw new Error(
      `${completionLabel} completed, but Relmio could not release its operation lock. ` +
      "Restart Relmio before another action, then verify the managed endpoint.",
      { cause: releaseError },
    );
  }
  return result;
}

export async function acquireLocalEndpointChangeLock(
  { target },
  {
    fileSystem = defaultFileSystem,
    env = process.env,
    homeDirectory = homedir(),
    platform = process.platform,
    processId = process.pid,
    isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity,
  } = {},
) {
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const safeTarget = validateLocalTarget(target);
  const installRoot = await resolveLocalInstallRoot({
    target: safeTarget,
    env,
    homeDirectory,
    fileSystem,
    platform,
  });
  return acquireLocalProjectLock(
    { installRoot, target: safeTarget },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform },
  );
}

function replaceClientCredentialVerifier({ target, composeFile, tokenSha256 }) {
  if (typeof composeFile !== "string" || composeFile.length > 512 * 1024) {
    throw new Error("The managed local endpoint configuration is invalid.");
  }

  const pattern = /^([ \t]*RELMIO_GATEWAY_TOKEN_SHA256:[ \t]*)[a-f0-9]{64}([ \t]*)$/gmu;
  const matches = [...composeFile.matchAll(pattern)];
  if (matches.length !== 1) {
    throw new Error("The managed local endpoint configuration is invalid.");
  }
  return composeFile.replace(pattern, `$1${tokenSha256}$2`);
}

export function isLoopbackPortAvailable(port) {
  return new Promise((resolvePromise, rejectPromise) => {
    const server = createServer();
    server.unref();
    server.once("error", (error) => {
      if (error?.code === "EADDRINUSE" || error?.code === "EACCES") {
        resolvePromise(false);
      } else {
        rejectPromise(new Error("Relmio could not check the local endpoint port."));
      }
    });
    server.listen(port, "127.0.0.1", () => {
      server.close((error) => {
        if (error) {
          rejectPromise(new Error("Relmio could not finish checking the local port."));
        } else {
          resolvePromise(true);
        }
      });
    });
  });
}

function validateVersion(value, label) {
  const normalized = typeof value === "string" ? value.trim() : "";
  if (!/^[A-Za-z0-9.+-]{1,64}$/u.test(normalized)) {
    throw new Error(`${label} returned an invalid version.`);
  }
  return normalized;
}

function rejectDockerEnvironmentOverrides(env) {
  for (const name of DOCKER_SELECTION_VARIABLES) {
    if (typeof env[name] === "string" && env[name] !== "") {
      throw new Error(
        "Relmio local endpoints require the selected Docker context without Docker environment overrides.",
      );
    }
  }
}

async function resolveLocalDockerHost({
  runProcess,
  cwd,
  env,
  platform,
}) {
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const context = await runProcess({
    file: "docker",
    args: [
      "context",
      "inspect",
      "--format",
      "{{json .Endpoints.docker.Host}}",
    ],
    cwd,
  });
  if (context.code !== 0) {
    throw new Error("The selected Docker context could not be inspected.");
  }
  let candidate;
  try {
    candidate = JSON.parse(context.stdout.trim());
  } catch {
    throw new Error("The selected Docker context is not a local Docker daemon.");
  }
  let dockerHost;
  try {
    dockerHost = validateLocalDockerHost(candidate, { platform });
  } catch {
    throw new Error("The selected Docker context is not a local Docker daemon.");
  }
  if (platform === "win32" && dockerHost.startsWith("npipe:")) {
    const selectedContext = await runProcess({ file: "docker", args: ["context", "show"], cwd });
    if (selectedContext.code !== 0 || selectedContext.stdout.trim() !== "desktop-linux") {
      throw new Error("Docker Desktop's local Linux engine must be selected.");
    }
  }
  return dockerHost;
}

export async function getLocalDockerStatus({
  runProcess = runLocalProcess,
  cwd = process.cwd(),
  env = process.env,
  platform = process.platform,
} = {}) {
  // Owner decision: local Claude is macOS/Linux only; the wizard greys out its card from this flag.
  const claudeAvailability = platform === "win32" ? { claudeUnsupportedPlatform: true } : {};
  try {
    const dockerHost = await resolveLocalDockerHost({
      runProcess,
      cwd,
      env,
      platform,
    });
    // Both version checks only read from the same validated host, so they run together.
    const [docker, compose] = await Promise.all([
      runProcess({
        file: "docker",
        args: ["version", "--format", "{{.Server.Version}}"],
        cwd,
        dockerHost,
      }),
      runProcess({
        file: "docker",
        args: ["compose", "version", "--short"],
        cwd,
        dockerHost,
      }),
    ]);
    if (docker.code !== 0 || compose.code !== 0) {
      throw new Error();
    }
    return {
      dockerAvailable: true,
      dockerVersion: validateVersion(docker.stdout, "Docker"),
      composeVersion: validateVersion(compose.stdout, "Docker Compose"),
      dockerHost,
      ...claudeAvailability,
    };
  } catch {
    return {
      dockerAvailable: false,
      ...claudeAvailability,
    };
  }
}


function createServiceRecreateSpec({
  target,
  installRoot,
  dockerHost,
  projectName,
}) {
  const project = PROJECTS[target];
  return {
    label: "Local client credential rotation",
    file: "docker",
    args: createComposeArgs(target, projectName, [
      "up",
      "-d",
      "--wait",
      "--wait-timeout",
      "90",
      "--force-recreate",
      "--no-deps",
      project.serviceName,
    ]),
    cwd: installRoot,
    dockerHost,
  };
}

function createProjectName(target, installId) {
  return `${PROJECTS[target].projectPrefix}-${validateInstallId(installId)}`;
}

function createComposeArgs(target, projectName, suffix) {
  if (projectName !== createProjectName(target, projectName.slice(-32))) {
    throw new TypeError("The local Docker project identity is invalid.");
  }
  return [
    "compose",
    "--project-name",
    projectName,
    "--file",
    COMPOSE_FILENAME,
    ...suffix,
  ];
}

function createDeploymentSpecs({
  target,
  installRoot,
  dockerHost,
  projectName,
}) {
  const project = PROJECTS[target];
  const specs = [
    {
      label: "Local Compose validation",
      file: "docker",
      args: createComposeArgs(target, projectName, ["config", "--quiet"]),
      cwd: installRoot,
      dockerHost,
    },
    {
      label: "Local image build",
      file: "docker",
      args: createComposeArgs(target, projectName, ["build", project.serviceName]),
      cwd: installRoot,
      dockerHost,
    },
  ];
  specs.push({
    label: "Local endpoint start",
    file: "docker",
    args: createComposeArgs(target, projectName, [
      "up",
      "-d",
      "--wait",
      "--wait-timeout",
      "90",
      "--no-deps",
      project.serviceName,
    ]),
    cwd: installRoot,
    dockerHost,
  });
  return specs;
}

function createVerificationSpecs({ target, installRoot, dockerHost, projectName }) {
  const project = PROJECTS[target];
  return {
    running: {
      label: "Local endpoint status check",
      file: "docker",
      args: createComposeArgs(target, projectName, ["ps", "--status", "running", "--services"]),
      cwd: installRoot,
      dockerHost,
    },
    publication: {
      label: "Local endpoint publication check",
      file: "docker",
      args: createComposeArgs(target, projectName, ["ps", "--format", "json", project.serviceName]),
      cwd: installRoot,
      dockerHost,
    },
  };
}

function createCleanupSpec({ target, installRoot, dockerHost, projectName }) {
  const project = PROJECTS[target];
  return {
    label: "Unsafe local endpoint cleanup",
    file: "docker",
    args: createComposeArgs(target, projectName, [
      "rm",
      "--force",
      "--stop",
      project.serviceName,
    ]),
    cwd: installRoot,
    dockerHost,
  };
}

function createCleanupVerificationSpec({ target, installRoot, dockerHost, projectName }) {
  const project = PROJECTS[target];
  return {
    label: "Local endpoint cleanup verification",
    file: "docker",
    args: createComposeArgs(target, projectName, [
      "ps",
      "--all",
      "--services",
      project.serviceName,
    ]),
    cwd: installRoot,
    dockerHost,
  };
}

function createOwnershipPreflightSpecs({
  target,
  installRoot,
  dockerHost,
  projectName,
}) {
  const format = "{{json .}}";
  const projectFilter = `label=com.docker.compose.project=${projectName}`;
  return [
    {
      resource: "container",
      label: "Local container ownership check",
      file: "docker",
      args: ["ps", "--all", "--filter", projectFilter, "--format", format],
      cwd: installRoot,
      dockerHost,
    },
    {
      resource: "network",
      label: "Local network ownership check",
      file: "docker",
      args: ["network", "ls", "--filter", projectFilter, "--format", format],
      cwd: installRoot,
      dockerHost,
    },
    {
      resource: "volume",
      label: "Local volume ownership check",
      file: "docker",
      args: ["volume", "ls", "--filter", projectFilter, "--format", format],
      cwd: installRoot,
      dockerHost,
    },
  ];
}

function parseDockerLabels(value) {
  if (typeof value !== "string" || value.length > 16 * 1024) {
    throw new Error("The local Docker ownership metadata is invalid.");
  }
  const labels = new Map();
  for (const entry of value.split(",")) {
    const separator = entry.indexOf("=");
    const name = separator > 0 ? entry.slice(0, separator) : "";
    if (name === "" || labels.has(name)) {
      throw new Error("The local Docker ownership metadata is invalid.");
    }
    labels.set(name, entry.slice(separator + 1));
  }
  return labels;
}

function expectedLocalEndpointResourceIdentities(target, projectName) {
  const project = PROJECTS[target];
  return {
    container: new Map([
      [`${projectName}-${project.serviceName}-1`, project.serviceName],
    ]),
    network: new Map([[`${projectName}_default`, "default"]]),
    volume: new Map(
      project.volumeNames.map((name) => [`${projectName}_${name}`, name]),
    ),
  };
}

function validateOwnershipOutput(
  output,
  { target, installId, projectName, resource, strictResourceIdentities = false },
) {
  const rows = output.trim() === "" ? [] : output.trim().split("\n");
  const expectedIdentities = (
    strictResourceIdentities === true ||
    strictResourceIdentities?.[resource] === true
  )
    ? expectedLocalEndpointResourceIdentities(target, projectName)[resource]
    : null;
  const seenNames = new Set();
  for (const row of rows) {
    let parsed;
    try {
      parsed = JSON.parse(row);
    } catch {
      throw new Error("The local Docker ownership metadata is invalid.");
    }
    const labels = parseDockerLabels(parsed?.Labels);
    for (const [name, expected] of Object.entries({
      "com.docker.compose.project": projectName,
      "io.relmio.managed": "true",
      "io.relmio.target": target,
      "io.relmio.install": installId,
    })) {
      if (labels.get(name) !== expected) {
        throw new Error(
          "A Docker resource already uses this Relmio project identity without matching ownership. Nothing was changed.",
        );
      }
    }
    if (
      resource === "container" &&
      labels.get("com.docker.compose.service") !== PROJECTS[target].serviceName
    ) {
      throw new Error(
        "A Docker resource already uses this Relmio project identity without matching ownership. Nothing was changed.",
      );
    }
    if (expectedIdentities) {
      const name = resource === "container" ? parsed?.Names : parsed?.Name;
      const logicalLabel = resource === "container"
        ? "com.docker.compose.service"
        : `com.docker.compose.${resource}`;
      if (
        typeof name !== "string" ||
        !expectedIdentities.has(name) ||
        seenNames.has(name) ||
        labels.get(logicalLabel) !== expectedIdentities.get(name)
      ) {
        throw new Error(
          `The local ${resource} identity does not match the generated Compose plan.`,
        );
      }
      seenNames.add(name);
    }
  }
  return rows.length;
}

async function attestDockerOwnership({
  target,
  installRoot,
  dockerHost,
  installId,
  projectName,
  runProcess,
  strictResourceIdentities = false,
}) {
  const specs = createOwnershipPreflightSpecs({
    target,
    installRoot,
    dockerHost,
    projectName,
  });
  // The three lists only read from the same validated host, so they run together. They are
  // checked in the fixed order, so the first failure reported is the one a sequential run gave.
  const results = await Promise.allSettled(
    specs.map((spec) => runOrThrow(runProcess, spec)),
  );
  const counts = {};
  for (const [index, spec] of specs.entries()) {
    if (results[index].status === "rejected") throw results[index].reason;
    counts[spec.resource] = validateOwnershipOutput(results[index].value.stdout, {
      target,
      installId,
      projectName,
      resource: spec.resource,
      strictResourceIdentities,
    });
  }
  return counts;
}

async function runOrThrow(runProcess, spec) {
  const result = await runProcess({
    file: spec.file,
    args: spec.args,
    cwd: spec.cwd,
    ...(spec.dockerHost ? { dockerHost: spec.dockerHost } : {}),
    ...(spec.input !== undefined ? { input: spec.input } : {}),
  });
  if (result.code !== 0) {
    throw new Error(`${spec.label} failed.`);
  }
  return result;
}

function validatePublishedEndpoint(output, { target, port }) {
  let services;
  try {
    const parsed = JSON.parse(output);
    services = Array.isArray(parsed) ? parsed : [parsed];
  } catch {
    throw new Error("The local endpoint publication metadata is invalid.");
  }
  if (services.length !== 1 || !Array.isArray(services[0]?.Publishers)) {
    throw new Error("The local endpoint publication check failed closed.");
  }
  const publishers = services[0].Publishers;
  const expected = PROJECTS[target];
  if (
    publishers.length !== 1 ||
    publishers[0]?.URL !== "127.0.0.1" ||
    publishers[0]?.PublishedPort !== port ||
    publishers[0]?.TargetPort !== expected.containerPort ||
    publishers[0]?.Protocol !== "tcp"
  ) {
    throw new Error(
      "The local endpoint publication is not the exact planned loopback binding.",
    );
  }
}

function parseComposeStatusRecords(output) {
  if (typeof output !== "string" || Buffer.byteLength(output) > 1024 * 1024) {
    throw new Error("The local endpoint status metadata is invalid.");
  }
  if (output.trim() === "") return [];
  try {
    const parsed = JSON.parse(output);
    return Array.isArray(parsed) ? parsed : [parsed];
  } catch {
    try {
      return output.trim().split("\n").map((line) => JSON.parse(line));
    } catch {
      throw new Error("The local endpoint status metadata is invalid.");
    }
  }
}

function localEndpointSnapshot(plan, marker, account = null) {
  const siwc = marker?.schemaVersion === CODEX_SIWC_MARKER_SCHEMA_VERSION;
  return {
    target: plan.target,
    endpoint: plan.endpoint,
    auth: {
      configured: siwc ? account?.ownership === "owned" &&
        account?.session === "connected" && account?.planEnabled === true : true,
      disclosure: "rotate-only",
      ...(siwc && account ? { account } : {}),
    },
    ...(siwc ? { registrationId: marker.registrationId } : {}),
    migrationRequired: false,
    canRotateCredential: true,
  };
}

async function readLegacyMigrationState(fileSystem, installRoot, installId) {
  const legacyRoot = join(installRoot, "legacy");
  const parent = await lstatIfExists(fileSystem, legacyRoot);
  if (!parent) return null;
  assertDirectoryMetadata(parent);
  const archive = join(legacyRoot, validateInstallId(installId));
  const metadata = await lstatIfExists(fileSystem, archive);
  if (!metadata) return null;
  assertDirectoryMetadata(metadata);
  const journalPath = join(archive, "migration.json");
  const journal = await lstatIfExists(fileSystem, journalPath);
  if (!journal) return "incomplete";
  if (!journal.isFile() || journal.isSymbolicLink() || journal.size > 4096) {
    throw new Error("The legacy migration journal is unsafe.");
  }
  let record;
  try { record = JSON.parse(await fileSystem.readFile(journalPath, "utf8")); }
  catch { throw new Error("The legacy migration journal is invalid."); }
  if (record?.schemaVersion !== 1 ||
      record?.reviewedLegacy?.installId !== installId ||
      !["prepared", "stopped", "transferred"].includes(record?.state)) {
    throw new Error("The legacy migration journal needs manual inspection.");
  }
  return record.state;
}

async function assertInstalledCodexCompose({ fileSystem, installRoot, marker }) {
  if (marker.schemaVersion !== CODEX_SIWC_MARKER_SCHEMA_VERSION) {
    throw new Error("The native Codex login installation requires fresh SIWC sign-in and reviewed migration.");
  }
  const composePath = join(installRoot, COMPOSE_FILENAME);
  await assertRegularManagedMarker(
    fileSystem, composePath, "The installed Codex Compose file is unsafe.",
  );
  const contents = await fileSystem.readFile(composePath, "utf8");
  if (contents.length > 512 * 1024) {
    throw new Error("The installed Codex Compose file is invalid.");
  }
  const values = [...contents.matchAll(/^[ \t]*RELMIO_GATEWAY_TOKEN_SHA256:[ \t]*([a-f0-9]{64})[ \t]*$/gmu)];
  if (values.length !== 1) throw new Error("The installed Codex capability verifier is invalid.");
  const options = {
    port: marker.port, tokenSha256: values[0][1],
    installId: marker.installId, registrationId: marker.registrationId,
  };
  const expected = marker.target === "codex-chat"
    ? createCodexChatComposeFile(options)
    : createCodexComposeFile(options);
  if (contents !== expected) throw new Error("The installed Codex Compose file changed.");
}

async function verifyWindowsManagedLocalEndpointPathSecurity({
  fileSystem,
  installRoot,
  platform,
  lockDownPath,
}) {
  if (platform !== "win32") return;
  const relmioHome = resolve(installRoot, "..", "..");
  for (const path of [relmioHome, join(relmioHome, "local"), installRoot]) {
    assertDirectoryMetadata(await lstatIfExists(fileSystem, path));
    await lockDownPath(path, { platform, verifyOnly: true });
  }
  for (const path of [
    join(relmioHome, ROOT_MARKER),
    join(installRoot, MANAGED_MARKER),
    join(installRoot, COMPOSE_FILENAME),
  ]) {
    await assertRegularManagedMarker(
      fileSystem,
      path,
      "Relmio refuses an unsafe local endpoint managed file.",
    );
    await lockDownPath(path, {
      platform,
      kind: "file",
      verifyOnly: true,
      verifyEffectiveOwnerOnly: true,
    });
  }
}

export async function getManagedLocalEndpointStatus(
  { target },
  {
    fileSystem = defaultFileSystem,
    runProcess = runLocalProcess,
    platform = process.platform,
    env = process.env,
    homeDirectory = homedir(),
    lockDownPath = lockDownLocalPath,
  } = {},
) {
  const safeTarget = validateLocalTarget(target);
  const absent = { target: safeTarget, managed: false, state: "absent" };
  const unavailable = { target: safeTarget, managed: false, state: "unavailable" };
  try {
    assertSupportedPlatform(platform);
    const installRoot = await resolveLocalInstallRoot({
      target: safeTarget,
      env,
      homeDirectory,
      fileSystem,
      platform,
    });
    const relmioHome = resolve(installRoot, "..", "..");
    if (safeTarget !== "xai-grok-build") {
      const staged = await readLocalSiwcStaging({ fileSystem, installRoot, platform, lockDownPath });
      if (staged && staged.checkpoint.stage !== "completed") {
        await fingerprintLocalSiwcFiles({ fileSystem, installRoot, platform, lockDownPath });
        const { installId, registrationId, stage } = staged.checkpoint;
        return { target: safeTarget, managed: true, state: "staged",
          staging: { installId, registrationId, stage } };
      }
    }
    if (await lstatIfExists(fileSystem, installRoot)) {
      await verifyWindowsManagedLocalEndpointPathSecurity({
        fileSystem,
        installRoot,
        platform,
        lockDownPath,
      });
    }
    const managed = await inspectManagedRoot({
      fileSystem,
      relmioHome,
      installRoot,
      target: safeTarget,
    });
    if (!managed.marker) return absent;
    const selectedDockerHost = await resolveLocalDockerHost({
      runProcess,
      cwd: installRoot,
      env,
      platform,
    });
    if (selectedDockerHost !== managed.marker.dockerHost) return unavailable;
    if (safeTarget !== "xai-grok-build" &&
        managed.marker.schemaVersion !== CODEX_SIWC_MARKER_SCHEMA_VERSION) {
      const port = validateLocalPort(managed.marker.port);
      const migrationState = await readLegacyMigrationState(
        fileSystem, installRoot, managed.marker.installId,
      );
      if (migrationState === "transferred") {
        throw new Error("The legacy migration metadata is inconsistent.");
      }
      return {
        target: safeTarget, managed: true,
        state: migrationState ? "partial" : "legacy",
        snapshot: {
          target: safeTarget,
          endpoint: safeTarget === "codex-chatgpt"
            ? `ws://127.0.0.1:${port}` : `http://127.0.0.1:${port}`,
          auth: { configured: false, disclosure: "rotate-only" },
          canRotateCredential: false, migrationRequired: true,
          ...(migrationState ? {
            migrationState, legacyResourcesPreserved: true,
          } : {}),
        },
      };
    }
    if (safeTarget !== "xai-grok-build") {
      if (managed.marker.legacyInstallId) {
        const migrationState = await readLegacyMigrationState(
          fileSystem, installRoot, managed.marker.legacyInstallId,
        );
        if (migrationState !== "transferred") {
          const port = validateLocalPort(managed.marker.port);
          return {
            target: safeTarget, managed: true, state: "partial",
            snapshot: {
              target: safeTarget,
              endpoint: safeTarget === "codex-chatgpt"
                ? `ws://127.0.0.1:${port}` : `http://127.0.0.1:${port}`,
              auth: { configured: false, disclosure: "rotate-only" },
              canRotateCredential: false,
              migrationRequired: !managed.marker.previousWasSiwc,
              replacementRequired: !!managed.marker.previousWasSiwc,
              migrationState: migrationState ?? "incomplete",
              legacyResourcesPreserved: true,
            },
          };
        }
      }
      await assertInstalledCodexCompose({
        fileSystem, installRoot, marker: managed.marker,
      });
      if (platform === "win32") {
        for (const relative of [
          "Dockerfile", ".dockerignore", "config.toml", "requirements.toml",
          "package.json", "package-lock.json", "services/siwc-session.mjs",
          "services/siwc-handoff.mjs", "infrastructure/local-process.js",
          "services/local-integration-lifecycle-lock.js", "services/codex-images.mjs", "services/model-discovery.mjs",
          "infrastructure/process-identity.js",
          safeTarget === "codex-chat" ? "gateway/codex-chat.js" : "gateway/codex-app-server.mjs",
        ]) {
          const path = join(installRoot, relative);
          // Installs made before the image add-on or model discovery lack these files; verify them whenever present.
          if (["services/codex-images.mjs", "services/model-discovery.mjs"].includes(relative) &&
              !await lstatIfExists(fileSystem, path)) continue;
          await assertRegularManagedMarker(fileSystem, path, "The installed Codex SIWC asset is unsafe.");
          await lockDownPath(path, {
            platform, kind: "file", verifyOnly: true, verifyEffectiveOwnerOnly: true,
          });
        }
      }
    }
    const plan = createLocalDeploymentPlan({
      target: safeTarget,
      port: managed.marker.port,
      authBinding: managed.marker.authBinding,
    });
    const counts = await attestDockerOwnership({
      target: safeTarget,
      installRoot,
      dockerHost: managed.marker.dockerHost,
      installId: managed.marker.installId,
      projectName: managed.marker.projectName,
      runProcess,
      strictResourceIdentities: true,
    });
    const expectedCounts = {
      container: 1,
      network: 1,
      volume: PROJECTS[safeTarget].volumeNames.length,
    };
    if (Object.keys(expectedCounts).some((key) => counts[key] > expectedCounts[key])) {
      return unavailable;
    }
    const result = await runOrThrow(runProcess, {
      label: "Local endpoint inventory check",
      file: "docker",
      args: createComposeArgs(safeTarget, managed.marker.projectName, [
        "ps",
        "--all",
        "--format",
        "json",
        PROJECTS[safeTarget].serviceName,
      ]),
      cwd: installRoot,
      dockerHost: managed.marker.dockerHost,
    });
    const records = parseComposeStatusRecords(result.stdout);
    let account = null;
    if (safeTarget !== "xai-grok-build" &&
        records.length === 1 && records[0]?.State === "running") {
      try {
        account = (await runCodexSiwcCommand({
          target: safeTarget, installRoot,
          dockerHost: managed.marker.dockerHost,
          projectName: managed.marker.projectName,
          command: "account-live", runProcess,
        })).account;
        if (account?.registrationId !== managed.marker.registrationId ||
            account?.ownerHostId !== managed.marker.ownerHostId ||
            account?.ownerRuntimeId !== managed.marker.installId ||
            account?.ownership !== "owned") {
          throw new Error("The installed Codex SIWC account could not be attested.");
        }
      } catch {
        return {
          target: safeTarget, managed: true, state: "partial",
          snapshot: localEndpointSnapshot(plan, managed.marker),
        };
      }
    }
    const snapshot = localEndpointSnapshot(plan, managed.marker, account);
    if (records.length === 0) {
      return { target: safeTarget, managed: true, state: "partial" };
    }
    if (records.length !== 1) {
      return unavailable;
    }
    const record = records[0];
    const expectedName = `${managed.marker.projectName}-${PROJECTS[safeTarget].serviceName}-1`;
    if (
      record.Name !== expectedName ||
      record.Service !== PROJECTS[safeTarget].serviceName ||
      typeof record.State !== "string"
    ) {
      return unavailable;
    }
    validatePublishedEndpoint(JSON.stringify(record), {
      target: safeTarget,
      port: plan.port,
    });
    if (Object.keys(expectedCounts).some((key) => counts[key] !== expectedCounts[key])) {
      return { target: safeTarget, managed: true, state: "partial" };
    }
    if (record.State === "running") {
      return record.Health === "healthy"
        ? { target: safeTarget, managed: true, state: "healthy", snapshot }
        : { target: safeTarget, managed: true, state: "partial" };
    }
    if (
      ["created", "exited"].includes(record.State) &&
      !["starting", "unhealthy"].includes(record.Health)
    ) {
      return { target: safeTarget, managed: true, state: "stopped", snapshot };
    }
    return { target: safeTarget, managed: true, state: "partial" };
  } catch {
    return unavailable;
  }
}

async function verifyHttpEndpoint({ plan, clientCredential, fetchImpl }) {
  const healthPath = plan.target === "codex-chatgpt" ? "/readyz" : "/health";
  let health;
  try {
    health = await fetchImpl(`http://127.0.0.1:${plan.port}${healthPath}`, {
      method: "GET",
      signal: AbortSignal.timeout(10_000),
    });
  } catch {
    throw new Error("The local endpoint did not answer its readiness check.");
  }
  if (!health.ok) throw new Error("The local endpoint did not pass its readiness check.");
  if (["codex-chat", "xai-grok-build"].includes(plan.target) && clientCredential !== undefined) {
    let verification;
    try {
      verification = await fetchImpl(`http://127.0.0.1:${plan.port}/auth/verify`, {
        method: "GET", headers: { Authorization: `Bearer ${clientCredential}` }, signal: AbortSignal.timeout(10_000),
      });
    } catch {
      throw new Error("The local agent client credential could not be verified.");
    }
    if (!verification.ok) throw new Error("The local agent client credential could not be verified.");
  }
  return [];
}

async function verifyCodexChatCatalog({ port, clientCredential, fetchImpl }) {
  const response = await fetchImpl(`http://127.0.0.1:${port}/models`, {
    method: "GET",
    headers: { Authorization: `Bearer ${clientCredential}` },
    signal: AbortSignal.timeout(10_000),
  });
  if (!response.ok) throw Object.assign(new Error("The selected account catalog is unavailable."), {
    status: response.status,
  });
  const payload = await response.json();
  if (!Array.isArray(payload?.models) ||
      !payload.models.every(model => typeof model?.slug === "string" &&
        /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u.test(model.slug))) {
    throw new Error("The selected account model catalog is invalid.");
  }
  return payload.models.map(model => model.slug);
}

async function verifyGrokBuildCli({ installRoot, dockerHost, projectName, runProcess }) {
  const result = await runOrThrow(runProcess, {
    label: "Grok Build CLI version verification",
    file: "docker",
    args: createComposeArgs("xai-grok-build", projectName, [
      "run", "--rm", "--no-deps", "--pull", "never", "--entrypoint", "grok", "grok-build", "--version",
    ]),
    cwd: installRoot,
    dockerHost,
  });
  if (!new RegExp(`^grok ${GROK_BUILD_CLI_VERSION.replaceAll(".", "\\.")} \\([0-9a-f]{7,64}\\)\\r?\\n?$`, "u").test(result.stdout)) {
    throw new Error("The managed Grok Build CLI version could not be verified.");
  }
}

export function verifyCodexWebSocketCapability(
  { port, clientCredential },
  {
    connectSocket = createConnection,
    randomBytes = createRandomBytes,
    timeoutMs = 10_000,
  } = {},
) {
  const safePort = validateLocalPort(port);
  if (
    typeof clientCredential !== "string" ||
    !/^[A-Za-z0-9_-]{43}$/u.test(clientCredential)
  ) {
    throw new TypeError("The staged local client credential is invalid.");
  }
  const keyBytes = randomBytes(16);
  if (!Buffer.isBuffer(keyBytes) || keyBytes.length !== 16) {
    throw new Error("Relmio could not verify the Codex client capability.");
  }
  const websocketKey = keyBytes.toString("base64");
  const expectedAccept = createHash("sha1")
    .update(`${websocketKey}258EAFA5-E914-47DA-95CA-C5AB0DC85B11`)
    .digest("base64");

  return new Promise((resolvePromise, rejectPromise) => {
    let settled = false;
    let response = "";
    const socket = connectSocket(
      { host: "127.0.0.1", port: safePort },
      () => {
        socket.write(
          [
            "GET / HTTP/1.1",
            `Host: 127.0.0.1:${safePort}`,
            "Upgrade: websocket",
            "Connection: Upgrade",
            `Sec-WebSocket-Key: ${websocketKey}`,
            "Sec-WebSocket-Version: 13",
            `Authorization: Bearer ${clientCredential}`,
            "",
            "",
          ].join("\r\n"),
        );
      },
    );

    const finish = (error) => {
      if (settled) {
        return;
      }
      settled = true;
      socket.destroy();
      if (error) {
        rejectPromise(
          new Error("The Codex client credential could not be verified."),
        );
      } else {
        resolvePromise();
      }
    };

    socket.setTimeout(timeoutMs, () => finish(new Error("timeout")));
    socket.on("error", finish);
    socket.on("close", () => finish(new Error("closed")));
    socket.on("data", (chunk) => {
      response += chunk.toString("latin1");
      if (response.length > 16 * 1024) {
        finish(new Error("oversized"));
        return;
      }
      const headerEnd = response.indexOf("\r\n\r\n");
      if (headerEnd === -1) {
        return;
      }
      const lines = response.slice(0, headerEnd).split("\r\n");
      if (!/^HTTP\/1\.1 101(?: |$)/u.test(lines.shift() ?? "")) {
        finish(new Error("unauthorized"));
        return;
      }
      const headers = new Map();
      for (const line of lines) {
        const separator = line.indexOf(":");
        if (separator <= 0) {
          finish(new Error("malformed"));
          return;
        }
        const rawName = line.slice(0, separator);
        if (!/^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/u.test(rawName)) {
          finish(new Error("malformed"));
          return;
        }
        const name = rawName.toLowerCase();
        const value = line.slice(separator + 1).trim();
        if (headers.has(name)) {
          finish(new Error("duplicate"));
          return;
        }
        headers.set(name, value);
      }
      if (
        headers.get("upgrade")?.toLowerCase() !== "websocket" ||
        !headers
          .get("connection")
          ?.split(",")
          .some((value) => value.trim().toLowerCase() === "upgrade") ||
        headers.get("sec-websocket-accept") !== expectedAccept
      ) {
        finish(new Error("invalid upgrade"));
        return;
      }
      finish();
    });
  });
}


async function defaultReadGrokBuildSource() {
  return defaultFileSystem.readFile(
    new URL("../supergrok/runtime.js", import.meta.url),
    "utf8",
  );
}

async function defaultReadGrokBuildChatSource() {
  return defaultFileSystem.readFile(
    new URL("../supergrok/chat.js", import.meta.url),
    "utf8",
  );
}

async function defaultReadGrokBuildSessionSource() {
  return defaultFileSystem.readFile(
    new URL("../supergrok/session.js", import.meta.url),
    "utf8",
  );
}

async function attestManagedGrokBuildFiles({
  fileSystem,
  installRoot,
  marker,
  readGrokBuildSource,
  readGrokBuildChatSource,
  readGrokBuildSessionSource,
}) {
  const expected = {
    Dockerfile: createGrokBuildDockerfile(),
    ".dockerignore": createLocalDockerignore("xai-grok-build"),
    [COMPOSE_FILENAME]: createGrokBuildComposeFile({
      port: marker.port,
      tokenSha256: marker.tokenSha256,
      installId: marker.installId,
    }),
    "gateway.js": validateGrokBuildPackagedSource(await readGrokBuildSource()),
    "chat.js": validateGrokBuildPackagedSource(await readGrokBuildChatSource()),
    "session.js": validateGrokBuildPackagedSource(await readGrokBuildSessionSource()),
  };
  for (const [name, contents] of Object.entries(expected)) {
    const path = join(installRoot, name);
    const metadata = await lstatIfExists(fileSystem, path);
    if (!metadata?.isFile?.() || metadata.isSymbolicLink()) {
      throw new Error("The managed Grok Build files could not be attested.");
    }
    const actual = await fileSystem.readFile(path, "utf8");
    if (actual !== contents) {
      throw new Error("The managed Grok Build files changed. Nothing was launched.");
    }
  }
}

function validateGrokBuildPackagedSource(source) {
  if (
    typeof source !== "string" ||
    source.length === 0 ||
    source.length > 512 * 1024
  ) {
    throw new Error("The packaged Grok Build runtime is invalid.");
  }
  return source;
}

async function attestManagedLocalEndpoint(
  {
    target,
    installDirectory,
    missingMessage,
    notRunningMessage,
    allowStopped = false,
    requireExactGatewayIdentity = false,
  },
  {
    fileSystem = defaultFileSystem,
    runProcess = runLocalProcess,
    platform = process.platform,
    lockDownPath = lockDownLocalPath,
    readGrokBuildSource = defaultReadGrokBuildSource,
    readGrokBuildChatSource = defaultReadGrokBuildChatSource,
    readGrokBuildSessionSource = defaultReadGrokBuildSessionSource,
  } = {},
) {
  assertSupportedPlatform(platform);
  const safeTarget = validateLocalTarget(target);
  const safeDirectory = validateInstallDirectory(
    installDirectory,
    safeTarget,
  );
  const relmioHome = resolve(safeDirectory, "..", "..");
  await verifyWindowsManagedLocalEndpointPathSecurity({
    fileSystem,
    installRoot: safeDirectory,
    platform,
    lockDownPath,
  });
  const managed = await inspectManagedRoot({
    fileSystem,
    relmioHome,
    installRoot: safeDirectory,
    target: safeTarget,
  });
  if (managed.deploymentMode !== "updated" || !managed.marker) {
    throw new Error(missingMessage);
  }
  if (safeTarget === "xai-grok-build") {
    if (typeof managed.marker.tokenSha256 !== "string") {
      throw new Error(
        "The managed Grok Build verifier is missing. This legacy installation requires a separately reviewed migration; its saved session has not been changed.",
      );
    }
    await attestManagedGrokBuildFiles({
      fileSystem,
      installRoot: safeDirectory,
      marker: managed.marker,
      readGrokBuildSource,
      readGrokBuildChatSource,
      readGrokBuildSessionSource,
    });
  } else {
    await assertInstalledCodexCompose({
      fileSystem, installRoot: safeDirectory, marker: managed.marker,
    });
  }
  const ownership = await attestDockerOwnership({
    target: safeTarget,
    installRoot: safeDirectory,
    dockerHost: managed.marker.dockerHost,
    installId: managed.marker.installId,
    projectName: managed.marker.projectName,
    runProcess,
    strictResourceIdentities: requireExactGatewayIdentity ? { container: true } : false,
  });
  if (requireExactGatewayIdentity && ownership.container !== 1) {
    throw new Error("The managed local gateway identity is not exact.");
  }
  const verification = createVerificationSpecs({
    target: safeTarget,
    installRoot: safeDirectory,
    dockerHost: managed.marker.dockerHost,
    projectName: managed.marker.projectName,
  });
  const running = await runOrThrow(runProcess, verification.running);
  const runningServices = running.stdout.trim() === ""
    ? []
    : running.stdout.trim().split(/\s+/u);
  const gatewayIsRunning =
    runningServices.length === 1 &&
    runningServices[0] === PROJECTS[safeTarget].serviceName;
  if (!gatewayIsRunning) {
    if (allowStopped === true && runningServices.length === 0) {
      return {
        target: safeTarget,
        installDirectory: safeDirectory,
        port: managed.marker.port,
        dockerHost: managed.marker.dockerHost,
        installId: managed.marker.installId,
        projectName: managed.marker.projectName,
        ...(safeTarget === "xai-grok-build" ? {} : { authBinding: managed.marker.authBinding }),
        running: false,
      };
    }
    throw new Error(
      notRunningMessage ?? "The managed local endpoint is not running.",
    );
  }
  const publication = await runOrThrow(runProcess, verification.publication);
  validatePublishedEndpoint(publication.stdout, {
    target: safeTarget,
    port: managed.marker.port,
  });
  return {
    target: safeTarget,
    installDirectory: safeDirectory,
    port: managed.marker.port,
    dockerHost: managed.marker.dockerHost,
    installId: managed.marker.installId,
    projectName: managed.marker.projectName,
    ...(safeTarget === "xai-grok-build" ? {} : { authBinding: managed.marker.authBinding }),
    running: true,
  };
}


export async function attestLocalGrokBuildInstallation(
  { installDirectory },
  dependencies = {},
) {
  const attested = await attestManagedLocalEndpoint(
    {
      target: "xai-grok-build",
      installDirectory,
      missingMessage: "Install the local Grok Build endpoint before signing in.",
      notRunningMessage: "The managed local Grok Build endpoint is not running.",
    },
    dependencies,
  );
  return {
    installDirectory: attested.installDirectory,
    dockerHost: attested.dockerHost,
    projectName: attested.projectName,
  };
}

export async function prepareLocalClientCredentialRotation(
  { target },
  {
    fileSystem = defaultFileSystem,
    env = process.env,
    homeDirectory = homedir(),
    runProcess = runLocalProcess,
    randomBytes = createRandomBytes,
    platform = process.platform,
    lockDownPath = lockDownLocalPath,
  } = {},
) {
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const safeTarget = validateLocalTarget(target);
  const installDirectory = await resolveLocalInstallRoot({
    target: safeTarget,
    env,
    homeDirectory,
    fileSystem,
    platform,
  });
  const attested = await attestManagedLocalEndpoint(
    {
      target: safeTarget,
      installDirectory,
      missingMessage:
        "Install the local endpoint before rotating its client credential.",
    },
    { fileSystem, runProcess, platform, lockDownPath },
  );
  let selectedAccount = null;
  if (safeTarget !== "xai-grok-build") {
    selectedAccount = (await runCodexSiwcCommand({
      target: safeTarget, installRoot: installDirectory,
      dockerHost: attested.dockerHost, projectName: attested.projectName,
      command: "account-live", runProcess,
    })).account;
    if (selectedAccount?.registrationId !== attested.authBinding.registrationId ||
        selectedAccount?.ownerRuntimeId !== attested.installId ||
        selectedAccount?.ownership !== "owned") {
      throw new Error("The installed SIWC account could not be reviewed for local capability rotation.");
    }
  }
  const { clientCredential, tokenSha256 } = createClientCredential(randomBytes);
  const plan = createLocalDeploymentPlan({
    target: safeTarget,
    port: attested.port,
    authBinding: attested.authBinding,
  });
  return {
    target: plan.target,
    endpoint: plan.endpoint,
    protocol: plan.protocol,
    clientCredential,
    tokenSha256,
    ...(selectedAccount ? {
      registrationId: selectedAccount.registrationId,
      expectedGeneration: selectedAccount.generation,
    } : {}),
    credentialShownOnce: true,
    models: [],
    deploymentMode: "staged",
    experimental: plan.experimental,
    browserClients: plan.browserClients,
  };
}

export async function activateLocalClientCredentialRotation(
  { target, clientCredential, tokenSha256, registrationId, expectedGeneration },
  {
    fileSystem = defaultFileSystem,
    env = process.env,
    homeDirectory = homedir(),
    runProcess = runLocalProcess,
    fetchImpl = fetch,
    verifyCodexCapability = verifyCodexWebSocketCapability,
    platform = process.platform,
    lockDownPath = lockDownLocalPath,
    processId = process.pid,
    isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity,
    runSiwcCommand = runCodexSiwcCommand,
  } = {},
) {
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const safeTarget = validateLocalTarget(target);
  const safeVerifier = validateClientCredentialVerifier(tokenSha256);
  if (
    typeof clientCredential !== "string" ||
    createHash("sha256").update(clientCredential).digest("hex") !== safeVerifier
  ) {
    throw new TypeError("The staged local client credential is invalid.");
  }
  const installDirectory = await resolveLocalInstallRoot({
    target: safeTarget,
    env,
    homeDirectory,
    fileSystem,
    platform,
  });
  const releaseLock = await acquireLocalProjectLock(
    { installRoot: installDirectory, target: safeTarget },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform },
  );
  return settleLocalProjectOperation({
    completionLabel: "Local credential rotation",
    releaseLock,
    operation: async () => {
  const attested = await attestManagedLocalEndpoint(
    {
      target: safeTarget,
      installDirectory,
      missingMessage:
        "Install the local endpoint before rotating its client credential.",
    },
    { fileSystem, runProcess, platform, lockDownPath },
  );
  const composePath = join(installDirectory, COMPOSE_FILENAME);
  await assertRegularManagedMarker(
    fileSystem,
    composePath,
    "The managed local endpoint configuration is invalid.",
  );
  let previousCompose;
  try {
    previousCompose = await fileSystem.readFile(composePath, "utf8");
  } catch {
    throw new Error("The managed local endpoint configuration is invalid.");
  }

  const replacementCompose = replaceClientCredentialVerifier({
    target: safeTarget,
    composeFile: previousCompose,
    tokenSha256: safeVerifier,
  });
  const plan = createLocalDeploymentPlan({
    target: safeTarget,
    port: attested.port,
    authBinding: attested.authBinding,
  });
  const validateCompose = () =>
    runOrThrow(runProcess, {
      label: "Local Compose validation",
      file: "docker",
      args: createComposeArgs(safeTarget, attested.projectName, [
        "config",
        "--quiet",
      ]),
      cwd: installDirectory,
      dockerHost: attested.dockerHost,
    });
  if (safeTarget !== "xai-grok-build") {
    validateSiwcRegistrationId(registrationId);
    if (typeof expectedGeneration !== "string" ||
        !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(expectedGeneration) ||
        attested.authBinding.registrationId !== registrationId) {
      throw new Error("The selected Codex SIWC account changed before local credential rotation.");
    }
    const current = (await runSiwcCommand({
      target: safeTarget, installRoot: installDirectory,
      dockerHost: attested.dockerHost, projectName: attested.projectName,
      command: "account-live", runProcess,
    })).account;
    if (current?.registrationId !== registrationId ||
        current?.generation !== expectedGeneration ||
        current?.ownerRuntimeId !== attested.installId ||
        current?.ownership !== "owned") {
      throw new Error("The installed SIWC account changed. Review the rotation again.");
    }
    await runOrThrow(runProcess, {
      label: "Owned Codex endpoint drain", file: "docker",
      args: createComposeArgs(safeTarget, attested.projectName, [
        "stop", "--timeout", "30", PROJECTS[safeTarget].serviceName,
      ]),
      cwd: installDirectory, dockerHost: attested.dockerHost,
    });
    const stopped = await runOrThrow(runProcess, createVerificationSpecs({
      target: safeTarget, installRoot: installDirectory,
      dockerHost: attested.dockerHost, projectName: attested.projectName,
    }).running);
    if (stopped.stdout.trim() !== "") {
      throw new Error("The owned Codex endpoint did not drain; no verifier was replaced.");
    }
    const frozen = (await runSiwcCommand({
      target: safeTarget, installRoot: installDirectory,
      dockerHost: attested.dockerHost, projectName: attested.projectName,
      command: "account", runProcess,
    })).account;
    if (frozen?.registrationId !== registrationId ||
        frozen?.generation !== expectedGeneration ||
        frozen?.ownerRuntimeId !== attested.installId ||
        frozen?.ownership !== "owned") {
      throw new Error("The installed SIWC account changed while draining. The endpoint remains stopped.");
    }
  }
  let configurationWritten = false;

  try {
    await writeManagedFile(fileSystem, composePath, replacementCompose, 0o600);
    configurationWritten = true;
    await validateCompose();
    await runOrThrow(
      runProcess,
      createServiceRecreateSpec({
        target: safeTarget,
        installRoot: installDirectory,
        dockerHost: attested.dockerHost,
        projectName: attested.projectName,
      }),
    );
    await attestManagedLocalEndpoint(
      {
        target: safeTarget,
        installDirectory,
        missingMessage:
          "Install the local endpoint before rotating its client credential.",
      },
      { fileSystem, runProcess, platform, lockDownPath },
    );
    const models = await verifyHttpEndpoint({
      plan,
      clientCredential,
      fetchImpl,
    });
    if (safeTarget === "codex-chatgpt") {
      await verifyCodexCapability({
        port: plan.port,
        clientCredential,
      });
    }
    return {
      target: plan.target,
      endpoint: plan.endpoint,
      protocol: plan.protocol,
      models,
      deploymentMode: "updated",
      experimental: plan.experimental,
      browserClients: plan.browserClients,
    };
  } catch (error) {
    if (error?.committed === true) {
      configurationWritten = true;
    }
    if (!configurationWritten) {
      throw new Error("Relmio could not rotate the local client credential.");
    }

    try {
      await writeManagedFile(fileSystem, composePath, previousCompose, 0o600);
      await validateCompose();
      await runOrThrow(
        runProcess,
        createServiceRecreateSpec({
          target: safeTarget,
          installRoot: installDirectory,
          dockerHost: attested.dockerHost,
          projectName: attested.projectName,
        }),
      );
      await attestManagedLocalEndpoint(
        {
          target: safeTarget,
          installDirectory,
          missingMessage:
            "Install the local endpoint before rotating its client credential.",
        },
        { fileSystem, runProcess, platform, lockDownPath },
      );
      await verifyHttpEndpoint({ plan, fetchImpl });
    } catch {
      let stopped = false;
      try {
        await runOrThrow(
          runProcess,
          createCleanupSpec({
            target: safeTarget,
            installRoot: installDirectory,
            dockerHost: attested.dockerHost,
            projectName: attested.projectName,
          }),
        );
        const remaining = await runOrThrow(
          runProcess,
          createCleanupVerificationSpec({
            target: safeTarget,
            installRoot: installDirectory,
            dockerHost: attested.dockerHost,
            projectName: attested.projectName,
          }),
        );
        stopped = !remaining.stdout
          .split(/\s+/u)
          .includes(PROJECTS[safeTarget].serviceName);
      } catch {
        // The endpoint is left stopped only when Docker confirms the exact service is gone.
      }
      if (stopped) {
        throw new Error(
          "Local credential rotation failed safely. The local endpoint was stopped.",
        );
      }
      throw new Error(
        "Relmio could not confirm that the failed credential rotation was stopped. Inspect the Relmio Docker project before retrying.",
      );
    }

    throw new Error(
      "Local credential rotation failed safely. The previous verifier was restored and the managed endpoint was re-attested.",
    );
  }
    },
  });
}

async function validateReviewedCodexAccount(registration, binding) {
  const record = await readRegistration(registration);
  if (
    record?.registrationId !== binding.registrationId ||
    record?.clientId !== binding.clientId ||
    record?.generation !== binding.generation ||
    record?.owner?.hostId !== binding.ownerHostId ||
    record?.owner?.runtimeId !== binding.ownerRuntimeId ||
    record?.handoff?.state !== "owned" ||
    !record.planEnabled ||
    !record.session?.refreshToken ||
    !record.session?.scopes?.includes("chatgpt.tokens.use.direct")
  ) throw new Error("The selected SIWC account changed. Review and confirm it again.");
}

async function reviewCodexOwnedReplacement(
  { target, existingSiwc = false },
  {
    fileSystem = defaultFileSystem, env = process.env,
    homeDirectory = homedir(), runProcess = runLocalProcess,
    platform = process.platform, lockDownPath = lockDownLocalPath,
  } = {},
) {
  const safeTarget = validateLocalTarget(target);
  if (safeTarget === "xai-grok-build") {
    throw new TypeError("Only a managed legacy Codex endpoint can be migrated.");
  }
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const installRoot = await resolveLocalInstallRoot({
    target: safeTarget, env, homeDirectory, fileSystem, platform,
  });
  await verifyWindowsManagedLocalEndpointPathSecurity({
    fileSystem, installRoot, platform, lockDownPath,
  });
  const managed = await inspectManagedRoot({
    fileSystem, relmioHome: resolve(installRoot, "..", ".."),
    installRoot, target: safeTarget,
  });
  const marker = managed.marker;
  const expectedSchema = existingSiwc ? CODEX_SIWC_MARKER_SCHEMA_VERSION : MARKER_SCHEMA_VERSION;
  if (marker?.schemaVersion !== expectedSchema) {
    throw new Error("The selected Codex installation is not the reviewed owned runtime.");
  }
  const selectedDockerHost = await resolveLocalDockerHost({
    runProcess, cwd: installRoot, env, platform,
  });
  if (selectedDockerHost !== marker.dockerHost) {
    throw new Error("The selected Docker context changed.");
  }
  const ownership = await attestDockerOwnership({
    target: safeTarget, installRoot, dockerHost: marker.dockerHost,
    installId: marker.installId, projectName: marker.projectName, runProcess,
  });
  const logicalVolumes = existingSiwc
    ? ["codex-state", "siwc-store", "codex-workspace"]
    : ["codex-home", "codex-workspace"];
  const destinations = existingSiwc
    ? ["/home/node/.codex", "/home/node/.relmio-siwc", "/workspace"]
    : ["/home/node/.codex", "/workspace"];
  if (ownership.container !== 1 || ownership.network !== 1 ||
      ownership.volume !== logicalVolumes.length) {
    throw new Error("The exact owned Codex project is missing or has unexpected resources.");
  }
  const volumes = logicalVolumes.map(name => `${marker.projectName}_${name}`);
  const listed = await runOrThrow(runProcess, {
    label: "Legacy Codex volume identity check", file: "docker",
    args: ["volume", "ls", "--filter",
      `label=com.docker.compose.project=${marker.projectName}`,
      "--format", "{{json .}}"],
    cwd: installRoot, dockerHost: marker.dockerHost,
  });
  const volumeNames = listed.stdout.trim().split("\n").map(row => {
    try { return JSON.parse(row).Name; } catch { return null; }
  }).sort();
  if (JSON.stringify(volumeNames) !== JSON.stringify([...volumes].sort())) {
    throw new Error("The legacy credential and workspace volumes changed.");
  }
  const configResult = await runOrThrow(runProcess, {
    label: "Legacy Codex Compose validation", file: "docker",
    args: createComposeArgs(safeTarget, marker.projectName, ["config", "--format", "json"]),
    cwd: installRoot, dockerHost: marker.dockerHost,
  });
  let config;
  try { config = JSON.parse(configResult.stdout); } catch {
    throw new Error("The legacy Codex Compose metadata is invalid.");
  }
  const service = PROJECTS[safeTarget].serviceName;
  const current = config?.services?.[service];
  const port = validateLocalPort(marker.port);
  const mounted = Array.isArray(current?.volumes) ? current.volumes : [];
  if (Object.keys(config?.services ?? {}).length !== 1 ||
      Object.keys(config?.networks ?? {}).length !== 1 ||
      config?.networks?.default?.name !== `${marker.projectName}_default` ||
      (existingSiwc && (
        current?.environment?.RELMIO_REGISTRATION_ID !== marker.registrationId ||
        current?.environment?.RELMIO_RUNTIME_ID !== marker.installId ||
        current?.environment?.N8N_OPENAI_OAUTH_HOME !== "/home/node/.relmio-siwc"
      )) ||
      logicalVolumes.some((name, index) => config?.volumes?.[name]?.name !== volumes[index]) ||
      logicalVolumes.some((name, index) => !mounted.some(item =>
        item.source === name && item.target === destinations[index])) ||
      mounted.length !== logicalVolumes.length ||
      !Array.isArray(current?.ports) || current.ports.length !== 1 ||
      String(current.ports[0]?.published) !== String(port) ||
      current.ports[0]?.host_ip !== "127.0.0.1" ||
      current.ports[0]?.target !== PROJECTS[safeTarget].containerPort) {
    throw new Error("The legacy Codex Compose deployment differs from the owned installation.");
  }
  const containerResult = await runOrThrow(runProcess, {
    label: "Legacy Codex container identity check", file: "docker",
    args: createComposeArgs(safeTarget, marker.projectName, [
      "ps", "--all", "-q", service,
    ]),
    cwd: installRoot, dockerHost: marker.dockerHost,
  });
  const containerId = containerResult.stdout.trim();
  if (!/^[a-f0-9]{64}$/u.test(containerId)) {
    throw new Error("The legacy Codex container identity is invalid.");
  }
  const inspected = await runOrThrow(runProcess, {
    label: "Legacy Codex container inspection", file: "docker",
    args: ["container", "inspect", "--format", "{{json .}}", containerId],
    cwd: installRoot, dockerHost: marker.dockerHost,
  });
  let container;
  try { container = JSON.parse(inspected.stdout); } catch {
    throw new Error("The legacy Codex container metadata is invalid.");
  }
  const imageId = container?.Image;
  const networkResult = await runOrThrow(runProcess, {
    label: "Owned Codex network identity check", file: "docker",
    args: ["network", "inspect", "--format", "{{json .}}", `${marker.projectName}_default`],
    cwd: installRoot, dockerHost: marker.dockerHost,
  });
  let network;
  try { network = JSON.parse(networkResult.stdout); } catch {
    throw new Error("The owned Codex network identity is invalid.");
  }
  const networkId = network?.Id;
  const containerNetworkId =
    container?.NetworkSettings?.Networks?.[`${marker.projectName}_default`]?.NetworkID;
  const mounts = container?.Mounts;
  if (container?.Id !== containerId ||
      !/^sha256:[a-f0-9]{64}$/u.test(imageId) ||
      !/^[a-f0-9]{64}$/u.test(networkId) ||
      network?.Name !== `${marker.projectName}_default` ||
      (container?.State?.Running && containerNetworkId !== networkId) ||
      (container?.State?.Running === false && containerNetworkId !== undefined &&
        containerNetworkId !== networkId) ||
      container?.State?.Paused !== false ||
      typeof container?.State?.Running !== "boolean" ||
      container?.Config?.Labels?.["com.docker.compose.project"] !== marker.projectName ||
      container?.Config?.Labels?.["com.docker.compose.service"] !== service ||
      container?.Config?.Labels?.["io.relmio.managed"] !== "true" ||
      container?.Config?.Labels?.["io.relmio.target"] !== safeTarget ||
      container?.Config?.Labels?.["io.relmio.install"] !== marker.installId ||
      !Array.isArray(mounts) || mounts.length !== logicalVolumes.length ||
      logicalVolumes.some((name, index) => !mounts.some(item =>
        item.Type === "volume" && item.Name === volumes[index] &&
        item.Destination === destinations[index]))) {
    throw new Error("The old Codex container, image, network or volumes changed.");
  }
  return Object.freeze({
    target: safeTarget, installId: marker.installId,
    projectName: marker.projectName, dockerHost: marker.dockerHost,
    port, containerId, imageId, networkId,
    volumeNames: Object.freeze(volumes),
    ...(existingSiwc ? {
      registrationId: marker.registrationId,
      ownerHostId: marker.ownerHostId,
    } : {}),
    running: container.State.Running,
  });
}

export function reviewLocalCodexLegacyMigration({ target }, deps = {}) {
  return reviewCodexOwnedReplacement({ target }, deps);
}

export function reviewLocalCodexSiwcReplacement({ target }, deps = {}) {
  return reviewCodexOwnedReplacement({ target, existingSiwc: true }, deps);
}

async function attestRetiredCodex({ runProcess, installRoot, binding }) {
  validateInstallId(binding?.installId);
  if (!/^[a-f0-9]{64}$/u.test(binding.containerId)) throw new Error("The retained Codex identity is invalid.");
  const container = JSON.parse((await runOrThrow(runProcess, {
    label: "Retired Codex writer check", file: "docker",
    args: ["container", "inspect", "--format", "{{json .}}", binding.containerId],
    cwd: installRoot, dockerHost: binding.dockerHost,
  })).stdout);
  if (container?.Id !== binding.containerId || container.Image !== binding.imageId ||
      container.State?.Running !== false || container.State?.Paused !== false ||
      container.Config?.Labels?.["io.relmio.install"] !== binding.installId ||
      container.Config?.Labels?.["com.docker.compose.project"] !== binding.projectName ||
      !Array.isArray(container.Mounts) ||
      JSON.stringify(container.Mounts.map(item => item.Name).sort()) !== JSON.stringify([...binding.volumeNames].sort())) {
    throw new Error("The retained old Codex writer or volumes changed.");
  }
}

export async function reviewLocalSiwcResume(
  { target, registration },
  { fileSystem = defaultFileSystem, env = process.env, homeDirectory = homedir(),
    runProcess = runLocalProcess, platform = process.platform, lockDownPath = lockDownLocalPath,
    runSiwcCommand = runCodexSiwcCommand } = {},
) {
  const safeTarget = validateLocalTarget(target);
  rejectDockerEnvironmentOverrides(env);
  const installRoot = await resolveLocalInstallRoot({ target: safeTarget, env, homeDirectory, fileSystem, platform });
  const staged = await readLocalSiwcStaging({ fileSystem, installRoot, platform, lockDownPath });
  if (!staged || staged.checkpoint.stage === "completed") throw new Error("There is no interrupted SIWC installation to resume.");
  const { checkpoint, checkpointSha256 } = staged;
  let plan = createLocalDeploymentPlan(checkpoint.plan);
  if (checkpoint.projectName !== createProjectName(safeTarget, checkpoint.installId) ||
      plan.target !== safeTarget ||
      await resolveLocalDockerHost({ runProcess, cwd: homeDirectory, env, platform }) !== checkpoint.dockerHost) {
    throw new Error("The staged SIWC destination changed.");
  }
  await attestDockerOwnership({ target: safeTarget, installRoot: homeDirectory,
    dockerHost: checkpoint.dockerHost, installId: checkpoint.installId,
    projectName: checkpoint.projectName, runProcess, strictResourceIdentities: true });
  if (checkpoint.reviewedLegacy && checkpoint.oldStopped) {
    await attestRetiredCodex({ runProcess, installRoot, binding: checkpoint.reviewedLegacy });
  }
  const filesSha256 = await fingerprintLocalSiwcFiles({ fileSystem, installRoot, platform, lockDownPath });
  const resourcesSha256 = await fingerprintLocalSiwcResources({ runProcess, installRoot, checkpoint });
  if (checkpoint.ownerHostId) {
    const { marker } = await inspectManagedRoot({ fileSystem, installRoot,
      relmioHome: resolve(installRoot, "..", ".."), target: safeTarget });
    if (marker?.installId !== checkpoint.installId || marker?.ownerHostId !== checkpoint.ownerHostId) {
      throw new Error("The staged SIWC owner marker changed.");
    }
    await assertInstalledCodexCompose({ fileSystem, installRoot, marker });
  }
  const authBinding = await readLocalSiwcResumeAuthBinding({ checkpoint, registration, readRegistration, readPendingAuthHandoff,
    readReceipt: pending => runSiwcCommand({ target: safeTarget, installRoot,
      dockerHost: checkpoint.dockerHost, projectName: checkpoint.projectName,
      registrationId: checkpoint.registrationId, command: "receipt", runProcess,
      input: Buffer.from(JSON.stringify({ handoffId: pending.handoffId, binding: pending.binding, identity: pending.identity })) }) });
  plan = createLocalDeploymentPlan({ ...checkpoint.plan, authBinding });
  return { target: safeTarget, installId: checkpoint.installId,
    registrationId: plan.authBinding.registrationId, stage: checkpoint.stage, plan, checkpointSha256,
    ...(checkpoint.migration ? { migration: checkpoint.migration } : {}),
    filesSha256, resourcesSha256 };
}

export async function reconcileLocalSiwcHandoff(
  { target, registration, confirmed },
  { fileSystem = defaultFileSystem, env = process.env, homeDirectory = homedir(),
    runProcess = runLocalProcess, platform = process.platform, lockDownPath = lockDownLocalPath,
    processId = process.pid, isProcessAlive = defaultIsProcessAlive, getProcessIdentity,
    runSiwcCommand = runCodexSiwcCommand } = {},
) {
  const safeTarget = validateLocalTarget(target);
  if (safeTarget === "xai-grok-build" || confirmed !== true) throw new Error("Confirm reconciliation of the selected SIWC handoff.");
  validateSiwcRegistrationId(registration?.registrationId);
  rejectDockerEnvironmentOverrides(env);
  const installRoot = await resolveLocalInstallRoot({ target: safeTarget, env, homeDirectory, fileSystem, platform });
  const releaseLock = await acquireLocalProjectLock({ installRoot, target: safeTarget },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform });
  return settleLocalProjectOperation({ completionLabel: "SIWC handoff reconciliation", releaseLock,
    operation: async () => {
      await fingerprintLocalSiwcFiles({ fileSystem, installRoot, platform, lockDownPath });
      const { marker } = await inspectManagedRoot({ fileSystem, installRoot,
        relmioHome: resolve(installRoot, "..", ".."), target: safeTarget });
      if (marker?.registrationId !== registration.registrationId) throw new Error("The selected SIWC destination changed.");
      await assertInstalledCodexCompose({ fileSystem, installRoot, marker });
      if (await resolveLocalDockerHost({ runProcess, cwd: installRoot, env, platform }) !== marker.dockerHost) {
        throw new Error("The selected Docker context changed.");
      }
      await attestDockerOwnership({ target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        installId: marker.installId, projectName: marker.projectName, runProcess, strictResourceIdentities: true });
      const source = await readRegistration(registration);
      const pending = await readPendingAuthHandoff(registration);
      const request = pending ?? (source?.handoff?.state === "transferred" ? {
        handoffId: source.handoff.handoffId, binding: source.handoff.receipt.binding,
        target: source.handoff.receipt.binding.target,
        identity: { issuer: source.identity.issuer, clientId: source.clientId, subject: source.identity.subject },
      } : null);
      if (!request || request.target.hostId !== marker.ownerHostId || request.target.runtimeId !== marker.installId) {
        throw new Error("The frozen handoff does not match this destination.");
      }
      let receipt;
      try {
        ({ receipt } = await runSiwcCommand({ target: safeTarget, installRoot,
          dockerHost: marker.dockerHost, projectName: marker.projectName, registrationId: marker.registrationId,
          command: "receipt", input: Buffer.from(JSON.stringify({
            handoffId: request.handoffId, binding: request.binding, identity: request.identity,
          })), runProcess }));
      } catch {
        throw Object.assign(new Error("The SIWC receipt outcome is unresolved. The source remains frozen."), { remoteOutcomeUnknown: true });
      }
      if (receipt === null) {
        await assertNoLocalSiwcOneOffContainers({ runProcess, installRoot,
          dockerHost: marker.dockerHost, projectName: marker.projectName });
        const staged = await readLocalSiwcStaging({ fileSystem, installRoot, platform, lockDownPath });
        if (!staged || staged.checkpoint.registrationId !== registration.registrationId) {
          throw new Error("The original SIWC checkpoint changed.");
        }
        staged.checkpoint.notAccepted = true;
        const path = localSiwcStagingPath(installRoot);
        await writeManagedFile(fileSystem, path, `${JSON.stringify(staged.checkpoint)}\n`, 0o600);
        if (platform === "win32") await lockDownPath(path, { platform, kind: "file" });
        return { outcome: "not-accepted",
          account: (await listRegistrations({ storageRoot: registration.storageRoot })).find(
            account => account.registrationId === registration.registrationId) };
      }
      if (receipt?.handoffId !== request.handoffId ||
          JSON.stringify(receipt.binding) !== JSON.stringify(request.binding)) throw new Error("The SIWC receipt binding changed.");
      const account = await finishAuthHandoff(registration, { handoffId: request.handoffId, receipt: receipt.receipt });
      return { outcome: "finished", account };
    } });
}

export async function installLocalEndpoint(
  request,
  {
    fileSystem = defaultFileSystem,
    env = process.env,
    homeDirectory = homedir(),
    runProcess = runLocalProcess,
    randomBytes = createRandomBytes,
    isPortAvailable = isLoopbackPortAvailable,
    collectAssets = collectSiwcRuntimeAssets,
    runSiwcCommand = runCodexSiwcCommand,
    readGrokBuildSource = defaultReadGrokBuildSource,
    readGrokBuildChatSource = defaultReadGrokBuildChatSource,
    readGrokBuildSessionSource = defaultReadGrokBuildSessionSource,
    fetchImpl = fetch,
    verifyCodexCapability = verifyCodexWebSocketCapability,
    platform = process.platform,
    lockDownPath = lockDownLocalPath,
    processId = process.pid,
    isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity,
  } = {},
) {
  const isSiwc = request?.plan?.target !== "xai-grok-build";
  const migrating = request?.migrationConsent !== undefined ||
    request?.legacyBinding !== undefined || request?.resume?.migration === "legacy";
  const replacing = request?.replacementConsent !== undefined ||
    request?.existingBinding !== undefined || request?.resume?.migration === "replacement";
  if (
    !request ||
    typeof request !== "object" ||
    Array.isArray(request) ||
    Object.keys(request).length !== (isSiwc ? ((migrating || replacing) && !request.resume ? 5 : 3) : 2) + (request.resume === undefined ? 0 : 1) ||
    !Object.hasOwn(request, "plan") ||
    !Object.hasOwn(request, "confirmed") ||
    (isSiwc && !Object.hasOwn(request, "registration")) ||
    (!request.resume && migrating && (!isSiwc || replacing || request.migrationConsent !== true ||
      !Object.hasOwn(request, "legacyBinding"))) ||
    (!request.resume && replacing && (!isSiwc || request.replacementConsent !== true ||
      !Object.hasOwn(request, "existingBinding")))
  ) {
    throw new TypeError("The local endpoint install request is invalid.");
  }
  const { plan, confirmed, registration, legacyBinding, existingBinding, resume } = request;
  if (confirmed !== true) {
    throw new Error("Confirm the reviewed local endpoint plan before installing.");
  }
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);

  const normalizedPlan = createLocalDeploymentPlan({
    target: plan?.target,
    port: plan?.port,
    authBinding: plan?.authBinding,
  });
  const binding = isSiwc ? validateSiwcAuthBinding(normalizedPlan.authBinding) : null;
  if (isSiwc) {
    if (registration?.registrationId !== binding.registrationId || !registration.storageRoot) {
      throw new Error("The selected SIWC account does not match the reviewed endpoint.");
    }
    if (!resume) await validateReviewedCodexAccount(registration, binding);
  }
  const installRoot = await resolveLocalInstallRoot({
    target: normalizedPlan.target,
    env,
    homeDirectory,
    fileSystem,
    platform,
  });
  const releaseLock = await acquireLocalProjectLock(
    { installRoot, target: normalizedPlan.target },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform },
  );
  let preservedResult;
  return settleLocalProjectOperation({
    completionLabel: "Local endpoint installation",
    releaseLock,
    operation: async () => {
  try {
  const relmioHome = resolve(installRoot, "..", "..");
  const staged = isSiwc ? await readLocalSiwcStaging({ fileSystem, installRoot, platform, lockDownPath }) : null;
  if (staged && staged.checkpoint.stage !== "completed" && !resume) {
    throw new Error("Review the interrupted SIWC installation before resuming.");
  }
  if (resume) {
    const reviewed = await reviewLocalSiwcResume({ target: normalizedPlan.target, registration },
      { fileSystem, env, homeDirectory, runProcess, platform, lockDownPath });
    if (JSON.stringify(reviewed) !== JSON.stringify(resume) ||
        JSON.stringify(reviewed.plan) !== JSON.stringify(normalizedPlan)) {
      throw new Error("The reviewed SIWC resume binding changed.");
    }
    const source = await readRegistration(registration);
    if (source?.handoff?.state === "handoff-pending") throw new Error("Reconcile the frozen handoff before resuming.");
    if (source?.handoff?.state !== "transferred") await validateReviewedCodexAccount(registration, binding);
    else if (source.handoff.receipt.binding.target.runtimeId !== staged.checkpoint.installId ||
             source.handoff.receipt.binding.target.hostId !== staged.checkpoint.ownerHostId) {
      throw new Error("The completed handoff belongs to another destination.");
    }
  }
  const managed = await inspectManagedRoot({
    fileSystem,
    relmioHome,
    installRoot,
    target: normalizedPlan.target,
    staging: staged?.checkpoint,
  });
  let reviewedLegacy = resume ? staged.checkpoint.reviewedLegacy ?? null : null;
  const retiring = migrating || replacing;
  if (retiring && !(resume && staged.checkpoint.oldStopped)) {
    const expectedSchema = replacing
      ? CODEX_SIWC_MARKER_SCHEMA_VERSION : MARKER_SCHEMA_VERSION;
    if (managed.marker?.schemaVersion !== expectedSchema) {
      throw new Error("The reviewed Codex installation is no longer available.");
    }
    const inspect = replacing
      ? reviewLocalCodexSiwcReplacement : reviewLocalCodexLegacyMigration;
    reviewedLegacy = await inspect(
      { target: normalizedPlan.target },
      { fileSystem, env, homeDirectory, runProcess, platform, lockDownPath },
    );
    const expected = resume ? staged.checkpoint.reviewedLegacy : replacing ? existingBinding : legacyBinding;
    for (const field of [
      "target", "installId", "projectName", "dockerHost", "port",
      "containerId", "imageId", "networkId", "running",
      ...(replacing ? ["registrationId", "ownerHostId"] : []),
    ]) {
      if (expected?.[field] !== reviewedLegacy[field]) {
        throw new Error("The reviewed old Codex installation changed. Review replacement again.");
      }
    }
    if (JSON.stringify(expected?.volumeNames) !==
        JSON.stringify(reviewedLegacy.volumeNames) ||
        (replacing && reviewedLegacy.registrationId === binding.registrationId)) {
      throw new Error("The reviewed old account or protected volumes changed.");
    }
  } else if (isSiwc && managed.marker && !resume) {
    throw new Error("The existing Codex installation needs a separately reviewed replacement or legacy migration.");
  }
  if (
    normalizedPlan.target === "xai-grok-build" && managed.marker &&
    typeof managed.marker.tokenSha256 !== "string"
  ) {
    throw new Error(
      "This legacy Grok installation requires a separately reviewed migration to a fresh OAuth session. Its files, containers, and saved session have not been changed.",
    );
  }
  const dockerHost = managed.marker?.dockerHost ??
    (await resolveLocalDockerHost({
      runProcess,
      cwd: dirname(relmioHome),
      env,
      platform,
    }));
  const installIdBytes = isSiwc || !managed.marker ? randomBytes(32) : null;
  if (
    installIdBytes !== null &&
    (!Buffer.isBuffer(installIdBytes) || installIdBytes.length !== 32)
  ) {
    throw new Error("Relmio could not generate a strong installation identity.");
  }
  const installId = resume ? staged.checkpoint.installId : isSiwc
    ? installIdBytes.subarray(0, 16).toString("hex")
    : managed.marker?.installId ?? installIdBytes.subarray(0, 16).toString("hex");
  validateInstallId(installId);
  if (retiring && installId === reviewedLegacy.installId) {
    throw new Error("The fresh SIWC installation identity collided with the old Codex project.");
  }
  const projectName = createProjectName(normalizedPlan.target, installId);
  await attestDockerOwnership({
    target: normalizedPlan.target,
    installRoot: managed.marker ? installRoot : dirname(relmioHome),
    dockerHost, installId, projectName, runProcess,
  });
  if (managed.previousPort !== normalizedPlan.port &&
      !(await isPortAvailable(normalizedPlan.port))) {
    throw new Error("The selected local endpoint port is already in use.");
  }
  const capabilityBytes = randomBytes(32);
  if (!Buffer.isBuffer(capabilityBytes) || capabilityBytes.length !== 32) {
    throw new Error("Relmio could not generate a strong local capability.");
  }
  const clientCredential = capabilityBytes.toString("base64url");
  const tokenSha256 = createHash("sha256").update(clientCredential).digest("hex");
  if (resume && (await readRegistration(registration))?.handoff?.state === "transferred") {
    const account = (await runSiwcCommand({ target: normalizedPlan.target, installRoot, dockerHost,
      projectName, command: "account", runProcess })).account;
    if (account?.registrationId !== binding.registrationId || account?.ownerHostId !== staged.checkpoint.ownerHostId ||
        account?.ownerRuntimeId !== installId || account?.ownership !== "owned") {
      throw new Error("The resumed destination account changed.");
    }
    preservedResult = { target: normalizedPlan.target, endpoint: normalizedPlan.endpoint,
      protocol: normalizedPlan.protocol, clientCredential, credentialShownOnce: true,
      models: [], account, runtimeState: "unknown", readiness: "unverified",
      experimental: normalizedPlan.experimental, browserClients: normalizedPlan.browserClients };
  }
  const checkpoint = resume ? staged.checkpoint : {
    schemaVersion: 1, target: normalizedPlan.target, installId, projectName, dockerHost,
    registrationId: binding?.registrationId, plan: normalizedPlan, stage: "staged",
    ...(retiring ? { reviewedLegacy, migration: replacing ? "replacement" : "legacy",
      ...(replacing ? { previousGeneration: existingBinding.expectedGeneration } : {}) } : {}),
  };
  if (resume) {
    if (checkpoint.registrationId !== binding.registrationId) {
      await assertNoLocalSiwcOneOffContainers({ runProcess, installRoot, dockerHost, projectName });
    }
    checkpoint.registrationId = binding.registrationId;
    checkpoint.plan = normalizedPlan;
    checkpoint.notAccepted = false;
  }
  const saveStage = async stage => {
    if (!isSiwc) return;
    checkpoint.stage = stage;
    const path = localSiwcStagingPath(installRoot);
    await writeManagedFile(fileSystem, path, `${JSON.stringify(checkpoint)}\n`, 0o600);
    if (platform === "win32") await lockDownPath(path, { platform, kind: "file" });
  };
  if (isSiwc) await saveStage(checkpoint.stage);
  let legacyArchive = retiring ? join(installRoot, "legacy", reviewedLegacy.installId) : null;
  if (retiring && !(resume && checkpoint.oldStopped)) {
    await validateReviewedCodexAccount(registration, binding);
    const inspect = replacing
      ? reviewLocalCodexSiwcReplacement : reviewLocalCodexLegacyMigration;
    const freshPrevious = await inspect(
      { target: normalizedPlan.target },
      { fileSystem, env, homeDirectory, runProcess, platform, lockDownPath },
    );
    for (const field of [
      "target", "installId", "projectName", "dockerHost", "port",
      "containerId", "imageId", "networkId", "running",
      ...(replacing ? ["registrationId", "ownerHostId"] : []),
    ]) {
      if (freshPrevious[field] !== reviewedLegacy[field]) {
        throw new Error("The old Codex service changed before replacement. Review again.");
      }
    }
    if (JSON.stringify(freshPrevious.volumeNames) !==
        JSON.stringify(reviewedLegacy.volumeNames)) {
      throw new Error("The old Codex volumes changed before replacement.");
    }
    if (replacing) {
      const old = (await runSiwcCommand({
        target: normalizedPlan.target, installRoot,
        dockerHost: reviewedLegacy.dockerHost,
        projectName: reviewedLegacy.projectName,
        command: "account", runProcess,
      })).account;
      if (old?.registrationId !== reviewedLegacy.registrationId ||
          old?.ownerHostId !== reviewedLegacy.ownerHostId ||
          old?.generation !== (resume ? checkpoint.previousGeneration : existingBinding.expectedGeneration) ||
          old?.session !== "signed-out" || old?.planEnabled !== false) {
        throw new Error("Sign out of the exact old SIWC account before reviewed replacement.");
      }
    }
    const legacyRoot = join(installRoot, "legacy");
    legacyArchive = join(legacyRoot, reviewedLegacy.installId);
    if (!resume && await lstatIfExists(fileSystem, legacyArchive)) {
      throw new Error("A prior Codex replacement is incomplete. Inspect the retained project before retrying.");
    }
    await ensurePrivateDirectory(fileSystem, legacyRoot, platform, lockDownPath);
    await ensurePrivateDirectory(fileSystem, legacyArchive, platform, lockDownPath);
    const retain = async (filename, bytes) => {
      const path = join(legacyArchive, filename);
      await writeManagedFile(fileSystem, path, bytes, 0o600);
      if (platform === "win32") await lockDownPath(path, { platform, kind: "file" });
    };
    for (const filename of [
      MANAGED_MARKER, COMPOSE_FILENAME, "Dockerfile", ".dockerignore",
      "config.toml", "requirements.toml",
      ...(migrating && normalizedPlan.target === "codex-chat" ? ["gateway.mjs"] : []),
      ...(replacing ? ["package.json", "package-lock.json"] : []),
    ]) {
      const oldPath = join(installRoot, filename);
      const metadata = await lstatIfExists(fileSystem, oldPath);
      if (!metadata?.isFile?.() || metadata.isSymbolicLink() ||
          metadata.size > 1024 * 1024 ||
          (platform !== "win32" && (metadata.mode & 0o077) !== 0)) {
        throw new Error("An old Codex managed file is missing or unsafe. The old service has not been resumed.");
      }
      if (platform === "win32") {
        await lockDownPath(oldPath, {
          platform, kind: "file", verifyOnly: true, verifyEffectiveOwnerOnly: true,
        });
      }
      await retain(filename, await fileSystem.readFile(oldPath));
    }
    const journal = async state => retain("migration.json", Buffer.from(
      `${JSON.stringify({
        schemaVersion: 1, state, reviewedLegacy,
        replacementInstallId: installId, previousWasSiwc: replacing,
      })}\n`,
    ));
    await journal("prepared");
    if (reviewedLegacy.running) {
      await runOrThrow(runProcess, {
        label: "Attested old Codex service drain", file: "docker",
        args: createComposeArgs(normalizedPlan.target, reviewedLegacy.projectName, [
          "stop", "--timeout", "30", PROJECTS[normalizedPlan.target].serviceName,
        ]),
        cwd: installRoot, dockerHost: reviewedLegacy.dockerHost,
      });
    }
    const stoppedPrevious = await inspect(
      { target: normalizedPlan.target },
      { fileSystem, env, homeDirectory, runProcess, platform, lockDownPath },
    );
    for (const field of [
      "target", "installId", "projectName", "dockerHost", "port",
      "containerId", "imageId", "networkId",
      ...(replacing ? ["registrationId", "ownerHostId"] : []),
    ]) {
      if (stoppedPrevious[field] !== reviewedLegacy[field]) {
        throw new Error("The old Codex service changed while stopping; it will not be resumed automatically.");
      }
    }
    if (stoppedPrevious.running ||
        JSON.stringify(stoppedPrevious.volumeNames) !==
          JSON.stringify(reviewedLegacy.volumeNames)) {
      throw new Error("The old refresh writer or protected volumes could not be proved stopped.");
    }
    if (replacing) {
      const old = (await runSiwcCommand({
        target: normalizedPlan.target, installRoot,
        dockerHost: reviewedLegacy.dockerHost,
        projectName: reviewedLegacy.projectName,
        command: "account", runProcess,
      })).account;
      if (old?.registrationId !== reviewedLegacy.registrationId ||
          old?.generation !== (resume ? checkpoint.previousGeneration : existingBinding.expectedGeneration) ||
          old?.session !== "signed-out" || old?.planEnabled !== false) {
        throw new Error("The old signed-out SIWC account changed. The retired service remains stopped.");
      }
    }
    await journal("stopped");
    checkpoint.oldStopped = true;
    await saveStage("staged");
  }
  await initializeManagedBase({
    fileSystem, relmioHome, baseExists: managed.baseExists, platform, lockDownPath,
  });
  await ensurePrivateDirectory(fileSystem, join(relmioHome, "local"), platform, lockDownPath);
  await ensurePrivateDirectory(fileSystem, installRoot, platform, lockDownPath);
  if (resume && (await readRegistration(registration))?.handoff?.state === "transferred") {
    await runOrThrow(runProcess, { label: "Resumed owned endpoint stop", file: "docker",
      args: createComposeArgs(normalizedPlan.target, projectName, ["stop", "--timeout", "30", PROJECTS[normalizedPlan.target].serviceName]),
      cwd: installRoot, dockerHost });
    const running = await runOrThrow(runProcess, createVerificationSpecs({
      target: normalizedPlan.target, installRoot, dockerHost, projectName }).running);
    if (running.stdout.trim() !== "") throw new Error("The resumed owner did not stop.");
  }

  let dockerfile;
  let composeFile;
  if (normalizedPlan.target === "xai-grok-build") {
    const [gatewaySource, chatSource, sessionSource] = await Promise.all([
      readGrokBuildSource(),
      readGrokBuildChatSource(),
      readGrokBuildSessionSource(),
    ]);
    validateGrokBuildPackagedSource(gatewaySource);
    validateGrokBuildPackagedSource(chatSource);
    validateGrokBuildPackagedSource(sessionSource);
    dockerfile = createGrokBuildDockerfile();
    composeFile = createGrokBuildComposeFile({
      port: normalizedPlan.port,
      tokenSha256,
      installId,
    });
    await writeManagedFile(fileSystem, join(installRoot, "gateway.js"), gatewaySource, 0o600);
    await writeManagedFile(fileSystem, join(installRoot, "chat.js"), chatSource, 0o600);
    await writeManagedFile(fileSystem, join(installRoot, "session.js"), sessionSource, 0o600);
  } else {
    const codexChat = normalizedPlan.target === "codex-chat";
    const options = {
      port: normalizedPlan.port, tokenSha256, installId,
      registrationId: binding.registrationId,
    };
    dockerfile = codexChat ? createCodexChatDockerfile() : createCodexDockerfile();
    composeFile = codexChat
      ? createCodexChatComposeFile(options)
      : createCodexComposeFile(options);
    const writeSiwcAsset = async (relative, contents) => {
      const path = join(installRoot, relative);
      await writeManagedFile(fileSystem, path, contents, 0o600);
      if (platform === "win32") await lockDownPath(path, { platform, kind: "file" });
    };
    for (const folder of ["services", "gateway", "infrastructure"]) {
      await ensurePrivateDirectory(fileSystem, join(installRoot, folder), platform, lockDownPath);
    }
    const assets = await collectAssets();
    await writeSiwcAsset("package.json", assets.packageJson);
    await writeSiwcAsset("package-lock.json", assets.packageLock);
    for (const asset of assets.files) {
      if (!SIWC_ASSET_PATHS.has(asset.path) || !Buffer.isBuffer(asset.contents)) {
        throw new Error("The packaged Codex SIWC assets are invalid.");
      }
      await writeSiwcAsset(asset.path, asset.contents);
    }
    await writeSiwcAsset("config.toml",
      codexChat ? createCodexChatConfig() : createCodexConfig());
    await writeSiwcAsset("requirements.toml",
      codexChat ? createCodexChatRequirements() : createCodexRequirements());
  }

  await writeManagedFile(
    fileSystem,
    join(installRoot, "Dockerfile"),
    dockerfile,
    0o600,
  );
  await writeManagedFile(
    fileSystem,
    join(installRoot, ".dockerignore"),
    createLocalDockerignore(normalizedPlan.target),
    0o600,
  );
  await writeManagedFile(
    fileSystem,
    join(installRoot, COMPOSE_FILENAME),
    composeFile,
    0o600,
  );
  if (isSiwc && platform === "win32") {
    for (const filename of ["Dockerfile", ".dockerignore", COMPOSE_FILENAME]) {
      await lockDownPath(join(installRoot, filename), { platform, kind: "file" });
    }
  }
  if (!isSiwc) {
    await writeManagedFile(
      fileSystem,
      join(installRoot, MANAGED_MARKER),
      `${JSON.stringify({
        schemaVersion: MARKER_SCHEMA_VERSION,
        target: normalizedPlan.target,
        port: normalizedPlan.port,
        dockerHost,
        installId,
        projectName,
        tokenSha256,
      })}\n`,
      0o600,
    );
  }

  let deploymentStarted = false;
  let models = [];
  let account;
  let catalogFailure;
  let destinationHostId;
  let handoffCommitted = resume && (await readRegistration(registration))?.handoff?.state === "transferred";
  let runtimeAttested = false;
  try {
    for (const spec of createDeploymentSpecs({
      target: normalizedPlan.target,
      installRoot,
      dockerHost,
      projectName,
    })) {
      if (isSiwc && spec.args.includes("up")) {
        const destination = await runSiwcCommand({
          target: normalizedPlan.target, installRoot, dockerHost,
          projectName, command: "host", runProcess,
        });
        validateSiwcHostId(destination?.hostId);
        if (destination.runtimeId !== installId ||
            destination.hostId === binding.ownerHostId) {
          throw new Error("The Codex SIWC destination host identity is invalid.");
        }
        destinationHostId = destination.hostId;
        const markerPath = join(installRoot, MANAGED_MARKER);
        await writeManagedFile(fileSystem, markerPath, `${JSON.stringify({
          schemaVersion: CODEX_SIWC_MARKER_SCHEMA_VERSION,
          target: normalizedPlan.target,
          port: normalizedPlan.port, dockerHost, installId, projectName,
          authBinding: binding, registrationId: binding.registrationId,
          clientId: binding.clientId, ownerHostId: destination.hostId,
          ...(retiring ? {
            legacyInstallId: reviewedLegacy.installId,
            ...(replacing ? { previousWasSiwc: true } : {}),
          } : {}),
        })}\n`, 0o600);
        if (platform === "win32") {
          await lockDownPath(markerPath, { platform, kind: "file" });
        }
        checkpoint.ownerHostId = destination.hostId;
        await saveStage("prepared");
        const identities = await attestDockerOwnership({
          target: normalizedPlan.target, installRoot, dockerHost,
          installId, projectName, runProcess,
          strictResourceIdentities: { network: true, volume: true },
        });
        if ((!handoffCommitted && identities.container !== 0) || identities.network !== 1 ||
            identities.volume !== PROJECTS[normalizedPlan.target].volumeNames.length) {
          throw new Error("The exact Codex SIWC destination resources are not ready.");
        }
        if (handoffCommitted) {
          account = (await runSiwcCommand({ target: normalizedPlan.target, installRoot, dockerHost,
            projectName, command: "account", runProcess })).account;
          if (account?.ownerHostId !== destination.hostId || account?.ownerRuntimeId !== installId ||
              account?.registrationId !== binding.registrationId || account?.ownership !== "owned") {
            throw new Error("The resumed SIWC destination account changed.");
          }
        } else {
        await validateReviewedCodexAccount(registration, binding);
        const { handoffId } = await prepareAuthHandoff(registration, {
          expectedGeneration: binding.generation,
          target: destination, backgroundConsent: false,
        });
        await saveStage("handoff-pending");
        const contents = await readAuthHandoff(registration, {
          handoffId, expectedGeneration: binding.generation,
        });
        let accepted;
        try {
          accepted = await runSiwcCommand({
            target: normalizedPlan.target, installRoot, dockerHost,
            projectName, registrationId: binding.registrationId, command: "accept", input: contents, runProcess,
          });
        } catch (error) {
          throw Object.assign(new Error("The Codex SIWC transfer outcome is unresolved. The source remains frozen; reconcile the destination before retrying."),
            { remoteOutcomeUnknown: true });
        }
        if (accepted?.handoffId !== handoffId ||
            accepted.account?.registrationId !== binding.registrationId ||
            accepted.account?.ownerHostId !== destination.hostId ||
            accepted.account?.ownerRuntimeId !== installId ||
            accepted.account?.ownership !== "owned") {
          throw new Error("The Codex SIWC receipt or destination account does not match. The source remains frozen.");
        }
        account = accepted.account;
        preservedResult = { target: normalizedPlan.target, endpoint: normalizedPlan.endpoint,
          protocol: normalizedPlan.protocol, clientCredential, credentialShownOnce: true,
          models: [], account, runtimeState: "stopped", readiness: "unverified",
          experimental: normalizedPlan.experimental, browserClients: normalizedPlan.browserClients };
        await finishAuthHandoff(registration, { handoffId, receipt: accepted.receipt });
        handoffCommitted = true;
        }
        await saveStage("transferred");
        deploymentStarted = true;
      } else if (spec.args.includes("up")) {
        deploymentStarted = true;
      }
      await runOrThrow(runProcess, spec);
    }
    const verification = createVerificationSpecs({
      target: normalizedPlan.target,
      installRoot,
      dockerHost,
      projectName,
    });
    const running = await runOrThrow(runProcess, verification.running);
    if (
      !running.stdout
        .split(/\s+/u)
        .includes(PROJECTS[normalizedPlan.target].serviceName)
    ) {
      throw new Error("The local endpoint did not reach the running state.");
    }
    const publication = await runOrThrow(runProcess, verification.publication);
    validatePublishedEndpoint(publication.stdout, {
      target: normalizedPlan.target,
      port: normalizedPlan.port,
    });
    runtimeAttested = true;
    if (preservedResult) preservedResult.runtimeState = "running";
    if (isSiwc) {
      try {
        await verifyHttpEndpoint({ plan: normalizedPlan, clientCredential, fetchImpl });
        if (normalizedPlan.target === "codex-chatgpt") {
          await verifyCodexCapability({
            port: normalizedPlan.port, clientCredential,
          });
          const catalog = (await runSiwcCommand({
            target: normalizedPlan.target, installRoot, dockerHost,
            projectName, command: "models", runProcess,
          })).models;
          if (!Array.isArray(catalog) ||
              !catalog.every(model => typeof model?.slug === "string" &&
                /^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/u.test(model.slug))) {
            throw new Error("The selected account model catalog is invalid.");
          }
          models = catalog.map(model => model.slug);
        } else {
          models = await verifyCodexChatCatalog({
            port: normalizedPlan.port, clientCredential, fetchImpl,
          });
        }
      } catch (error) {
        catalogFailure = safeSiwcCatalogFailure(error);
      }
      let current;
      try {
        current = (await runSiwcCommand({
          target: normalizedPlan.target, installRoot, dockerHost,
          projectName, command: "account-live", runProcess,
        })).account;
      } catch {
        catalogFailure ??= safeSiwcCatalogFailure({
          code: "owner_status_unavailable", recovery: "retry-later",
        });
      }
      if (current) {
        if (current.registrationId !== binding.registrationId ||
            current.ownerHostId !== destinationHostId ||
            current.ownerRuntimeId !== installId ||
            current.ownership !== "owned") {
          throw new Error("The installed Codex SIWC account changed.");
        }
        account = current;
      }
    } else {
      models = await verifyHttpEndpoint({
        plan: normalizedPlan, clientCredential, fetchImpl,
      });
    }
    if (normalizedPlan.target === "xai-grok-build") {
      await verifyGrokBuildCli({
        installRoot,
        dockerHost,
        projectName,
        runProcess,
      });
    }
  } catch (error) {
    if (isSiwc) {
      if (!handoffCommitted) throw error;
      let stopped = false;
      try {
        await runOrThrow(runProcess, {
          label: "Unverified owned Codex endpoint stop", file: "docker",
          args: createComposeArgs(normalizedPlan.target, projectName, [
            "stop", "--timeout", "30", PROJECTS[normalizedPlan.target].serviceName,
          ]),
          cwd: installRoot, dockerHost,
        });
        const running = await runOrThrow(runProcess, createVerificationSpecs({
          target: normalizedPlan.target, installRoot, dockerHost, projectName,
        }).running);
        stopped = running.stdout.trim() === "";
      } catch {
        // A disconnected Docker operation leaves the owned runtime outcome unknown.
      }
      const failureResult = {
        target: normalizedPlan.target, endpoint: normalizedPlan.endpoint,
        protocol: normalizedPlan.protocol, clientCredential, credentialShownOnce: true,
        models: [], deploymentMode: "partial", account,
        experimental: normalizedPlan.experimental, browserClients: normalizedPlan.browserClients,
        readiness: "unverified", runtimeState: stopped ? "stopped" : "unknown",
      };
      if (runtimeAttested) return localSiwcFinalizationFailure(failureResult, "resolve-handoff");
      return {
        target: normalizedPlan.target, endpoint: normalizedPlan.endpoint,
        protocol: normalizedPlan.protocol, clientCredential,
        credentialShownOnce: true, models: [],
        deploymentMode: "partial", account,
        experimental: normalizedPlan.experimental,
        browserClients: normalizedPlan.browserClients,
        readiness: "unverified",
        runtimeState: stopped ? "stopped" : "unknown",
        runtimeFailure: stopped ? safeSiwcRuntimeFailure() : {
          error: "The owned endpoint may be running with an unverified binding. Inspect and stop it before use.",
          status: 503, recovery: "resolve-handoff",
        },
        finalizationFailure: {
          error: "Ownership transferred, but runtime verification failed. Save the one-time key and resolve recovery before use.",
          recovery: "resolve-handoff",
        },
        ...(migrating ? { migrationPending: true, legacyRetained: true } : {}),
        ...(replacing ? { replacementPending: true, oldHistoryRetained: true } : {}),
      };
    }
    if (deploymentStarted) {
      let cleanupConfirmed = false;
      try {
        await runOrThrow(
          runProcess,
          createCleanupSpec({
            target: normalizedPlan.target,
            installRoot,
            dockerHost,
            projectName,
          }),
        );
        const remaining = await runOrThrow(
          runProcess,
          createCleanupVerificationSpec({
            target: normalizedPlan.target,
            installRoot,
            dockerHost,
            projectName,
          }),
        );
        cleanupConfirmed = !remaining.stdout
          .split(/\s+/u)
          .includes(PROJECTS[normalizedPlan.target].serviceName);
      } catch {
        // The caller receives a stronger fail-closed error below.
      }
      if (!cleanupConfirmed) {
        throw new Error(
          "Relmio could not confirm that the failed local endpoint was stopped. Inspect the Relmio Docker project before retrying.",
        );
      }
    }
    throw error;
  }
  try {
  if (retiring) {
    const journalPath = join(legacyArchive, "migration.json");
    await writeManagedFile(fileSystem, journalPath, Buffer.from(
      `${JSON.stringify({
        schemaVersion: 1, state: "transferred",
        reviewedLegacy, replacementInstallId: installId,
        previousWasSiwc: replacing,
      })}\n`,
    ), 0o600);
    if (platform === "win32") {
      await lockDownPath(journalPath, { platform, kind: "file" });
    }
  }
  await saveStage("completed");
  } catch {
    if (handoffCommitted) return localSiwcFinalizationFailure({
      target: normalizedPlan.target, endpoint: normalizedPlan.endpoint,
      protocol: normalizedPlan.protocol, clientCredential, credentialShownOnce: true,
      models, account, runtimeState: "running", readiness: "unverified",
      experimental: normalizedPlan.experimental, browserClients: normalizedPlan.browserClients,
      ...(migrating ? { migrationPending: true, legacyRetained: true } : {}),
      ...(replacing ? { replacementPending: true, oldHistoryRetained: true } : {}),
    });
    throw new Error("Local installation finalization failed.");
  }

  return {
    target: normalizedPlan.target,
    endpoint: normalizedPlan.endpoint,
    protocol: normalizedPlan.protocol,
    clientCredential,
    credentialShownOnce: true,
    models,
    deploymentMode: migrating ? "migrated" : replacing ? "replaced" : managed.deploymentMode,
    experimental: normalizedPlan.experimental,
    browserClients: normalizedPlan.browserClients,
    ...(isSiwc ? {
      account,
      runtimeState: "running",
      readiness: catalogFailure ? "unverified" : "verified",
      ...(catalogFailure ? { catalogFailure } : {}),
    } : {}),
    ...(migrating ? { migratedLegacy: true, legacyRetained: true } : {}),
    ...(replacing ? { replacedAccount: true, oldHistoryRetained: true } : {}),
  };
  } catch (error) {
    if (preservedResult) return localSiwcFinalizationFailure(preservedResult, "resolve-handoff");
    throw error;
  }
    },
  });
}

export async function inspectStoppedLocalSiwcInstallation(
  { target, registrationId, confirmed },
  {
    fileSystem = defaultFileSystem, env = process.env,
    homeDirectory = homedir(), runProcess = runLocalProcess,
    platform = process.platform, lockDownPath = lockDownLocalPath,
    processId = process.pid, isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity, runSiwcCommand = runCodexSiwcCommand,
  } = {},
) {
  const safeTarget = validateLocalTarget(target);
  if (safeTarget === "xai-grok-build" || confirmed !== true) {
    throw new Error("Confirm inspection of the stopped Codex SIWC account.");
  }
  validateSiwcRegistrationId(registrationId);
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const installRoot = await resolveLocalInstallRoot({
    target: safeTarget, env, homeDirectory, fileSystem, platform,
  });
  const releaseLock = await acquireLocalProjectLock(
    { installRoot, target: safeTarget },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform },
  );
  return settleLocalProjectOperation({
    completionLabel: "Stopped Codex SIWC account inspection",
    releaseLock,
    operation: async () => {
      await verifyWindowsManagedLocalEndpointPathSecurity({
        fileSystem, installRoot, platform, lockDownPath,
      });
      const managed = await inspectManagedRoot({
        fileSystem, relmioHome: resolve(installRoot, "..", ".."),
        installRoot, target: safeTarget,
      });
      const marker = managed.marker;
      if (marker?.schemaVersion !== CODEX_SIWC_MARKER_SCHEMA_VERSION ||
          marker.registrationId !== registrationId) {
        throw new Error("The selected registration is not installed in this Codex endpoint.");
      }
      await assertInstalledCodexCompose({ fileSystem, installRoot, marker });
      const selectedDockerHost = await resolveLocalDockerHost({
        runProcess, cwd: installRoot, env, platform,
      });
      if (selectedDockerHost !== marker.dockerHost) {
        throw new Error("The selected Docker context changed.");
      }
      const ownership = await attestDockerOwnership({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        installId: marker.installId, projectName: marker.projectName,
        runProcess, strictResourceIdentities: true,
      });
      if (ownership.container !== 1 || ownership.network !== 1 ||
          ownership.volume !== PROJECTS[safeTarget].volumeNames.length) {
        throw new Error("The exact owned Codex endpoint is missing.");
      }
      const running = await runOrThrow(runProcess, createVerificationSpecs({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        projectName: marker.projectName,
      }).running);
      if (running.stdout.trim() !== "") {
        throw new Error("The Codex endpoint is running; use read-only status instead.");
      }
      const account = (await runSiwcCommand({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        projectName: marker.projectName, command: "account", runProcess,
      })).account;
      if (account?.registrationId !== registrationId ||
          account?.ownerHostId !== marker.ownerHostId ||
          account?.ownerRuntimeId !== marker.installId ||
          account?.ownership !== "owned") {
        throw new Error("The stopped Codex SIWC account could not be attested.");
      }
      return { account };
    },
  });
}

export async function manageLocalSiwcInstallation(
  { target, registrationId, action, expectedGeneration, confirmed },
  {
    fileSystem = defaultFileSystem, env = process.env,
    homeDirectory = homedir(), runProcess = runLocalProcess,
    platform = process.platform, lockDownPath = lockDownLocalPath,
    processId = process.pid, isProcessAlive = defaultIsProcessAlive,
    getProcessIdentity, runSiwcCommand = runCodexSiwcCommand,
  } = {},
) {
  const safeTarget = validateLocalTarget(target);
  if (safeTarget === "xai-grok-build" ||
      confirmed !== true ||
      !["sign-out", "disable-plan", "enable-plan"].includes(action)) {
    throw new Error("Confirm the selected installed Codex SIWC account operation.");
  }
  validateSiwcRegistrationId(registrationId);
  if (typeof expectedGeneration !== "string" ||
      !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(expectedGeneration)) {
    throw new TypeError("The selected SIWC account generation is invalid.");
  }
  assertSupportedPlatform(platform);
  rejectDockerEnvironmentOverrides(env);
  const installRoot = await resolveLocalInstallRoot({
    target: safeTarget, env, homeDirectory, fileSystem, platform,
  });
  const releaseLock = await acquireLocalProjectLock(
    { installRoot, target: safeTarget },
    { fileSystem, processId, isProcessAlive, getProcessIdentity, platform },
  );
  return settleLocalProjectOperation({
    completionLabel: "Installed Codex SIWC account operation",
    releaseLock,
    operation: async () => {
      await verifyWindowsManagedLocalEndpointPathSecurity({
        fileSystem, installRoot, platform, lockDownPath,
      });
      const managed = await inspectManagedRoot({
        fileSystem, relmioHome: resolve(installRoot, "..", ".."),
        installRoot, target: safeTarget,
      });
      const marker = managed.marker;
      if (marker?.schemaVersion !== CODEX_SIWC_MARKER_SCHEMA_VERSION ||
          marker.registrationId !== registrationId) {
        throw new Error("The selected registration is not installed in this Codex endpoint.");
      }
      await assertInstalledCodexCompose({ fileSystem, installRoot, marker });
      const selectedDockerHost = await resolveLocalDockerHost({
        runProcess, cwd: installRoot, env, platform,
      });
      if (selectedDockerHost !== marker.dockerHost) {
        throw new Error("The selected Docker context changed.");
      }
      const ownership = await attestDockerOwnership({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        installId: marker.installId, projectName: marker.projectName,
        runProcess, strictResourceIdentities: true,
      });
      if (ownership.container !== 1 || ownership.network !== 1 ||
          ownership.volume !== PROJECTS[safeTarget].volumeNames.length) {
        throw new Error("The exact owned Codex endpoint is missing.");
      }
      const identitySpec = {
        label: "Owned Codex endpoint identity check", file: "docker",
        args: createComposeArgs(safeTarget, marker.projectName, [
          "ps", "--all", "-q", PROJECTS[safeTarget].serviceName,
        ]),
        cwd: installRoot, dockerHost: marker.dockerHost,
      };
      const containerId = (await runOrThrow(runProcess, identitySpec)).stdout.trim();
      if (!/^[a-f0-9]{64}$/u.test(containerId)) {
        throw new Error("The owned Codex endpoint identity is invalid.");
      }
      const before = (await runSiwcCommand({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        projectName: marker.projectName, command: "account", runProcess,
      })).account;
      if (before?.registrationId !== registrationId ||
          before?.ownerHostId !== marker.ownerHostId ||
          before?.ownerRuntimeId !== marker.installId ||
          before?.generation !== expectedGeneration ||
          before?.ownership !== "owned") {
        throw new Error("The installed SIWC account changed; review it again.");
      }
      if (action === "enable-plan" &&
          (before.planPermission !== "granted" || before.session !== "connected")) {
        throw new Error("This installed account needs a fresh authorized SIWC sign-in before plan use can resume.");
      }
      await runOrThrow(runProcess, {
        label: "Owned Codex endpoint stop", file: "docker",
        args: createComposeArgs(safeTarget, marker.projectName, [
          "stop", "--timeout", "30", PROJECTS[safeTarget].serviceName,
        ]),
        cwd: installRoot, dockerHost: marker.dockerHost,
      });
      const afterId = (await runOrThrow(runProcess, identitySpec)).stdout.trim();
      const running = await runOrThrow(runProcess, createVerificationSpecs({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        projectName: marker.projectName,
      }).running);
      if (afterId !== containerId || running.stdout.trim() !== "") {
        throw new Error("The owned Codex endpoint did not stop; account mutation was not attempted.");
      }
      const changed = await runSiwcCommand({
        target: safeTarget, installRoot, dockerHost: marker.dockerHost,
        projectName: marker.projectName, command: action,
        input: Buffer.from(JSON.stringify({ registrationId, expectedGeneration })),
        runProcess,
      });
      if (changed.account?.registrationId !== registrationId ||
          changed.account?.ownerHostId !== marker.ownerHostId ||
          changed.account?.ownerRuntimeId !== marker.installId ||
          changed.account?.ownership !== "owned") {
        throw new Error("The installed SIWC result could not be attested.");
      }
      if (action === "enable-plan") {
        if (changed.account.planEnabled !== true ||
            changed.account.planPermission !== "granted") {
          throw new Error("The installed SIWC grant could not be confirmed. The Codex endpoint remains stopped.");
        }
        try {
        await runOrThrow(runProcess, {
          label: "Owned Codex SIWC endpoint start", file: "docker",
          args: createComposeArgs(safeTarget, marker.projectName, [
            "up", "-d", "--wait", "--wait-timeout", "90",
            "--no-build", "--no-deps", PROJECTS[safeTarget].serviceName,
          ]),
          cwd: installRoot, dockerHost: marker.dockerHost,
        });
        const verification = createVerificationSpecs({
          target: safeTarget, installRoot, dockerHost: marker.dockerHost,
          projectName: marker.projectName,
        });
        const started = await runOrThrow(runProcess, verification.running);
        if (!started.stdout.split(/\s+/u).includes(PROJECTS[safeTarget].serviceName)) {
          throw new Error("The owned Codex endpoint did not reach the running state.");
        }
          const publication = await runOrThrow(runProcess, verification.publication);
          validatePublishedEndpoint(publication.stdout, {
            target: safeTarget, port: marker.port,
          });
        } catch {
          let stoppedAfterFailure = false;
          try {
            await runOrThrow(runProcess, {
              label: "Unverified enabled endpoint stop", file: "docker",
              args: createComposeArgs(safeTarget, marker.projectName, [
                "stop", "--timeout", "30", PROJECTS[safeTarget].serviceName,
              ]),
              cwd: installRoot, dockerHost: marker.dockerHost,
            });
            const afterId = (await runOrThrow(runProcess, identitySpec)).stdout.trim();
            const stopped = await runOrThrow(runProcess, createVerificationSpecs({
              target: safeTarget, installRoot, dockerHost: marker.dockerHost, projectName: marker.projectName }).running);
            stoppedAfterFailure = afterId === containerId && stopped.stdout.trim() === "";
          } catch { /* Preserve the unknown runtime outcome. */ }
          throw Object.assign(new Error(stoppedAfterFailure
            ? "The enabled endpoint failed verification and its stopped state was confirmed."
            : "The enabled endpoint outcome is unknown. Inspect and stop the owned service before use."),
          { runtimeStopped: stoppedAfterFailure, remoteOutcomeUnknown: !stoppedAfterFailure });
        }
      }
      return {
        account: changed.account, revocation: changed.revocation,
        runtimeStopped: action !== "enable-plan",
      };
    },
  });
}