import * as plugins from '../ts/plugins.js';
import type {
  IAGLHomeOptions,
  IAGLHomePaths,
} from '../ts/classes.aglhome.js';
import { resolveAGLHomePaths } from '../ts/classes.aglhome.js';
import {
  readDatabaseConfig,
  type IControllerDataDirectoryOptions,
} from '../ts/classes.config.js';
import {
  listControllerDataWriterProcessesForCliPaths,
  readControllerProcessIdentity,
} from '../ts/classes.processinspection.js';
import { embeddedDatabaseSocketPath, isSocketListening } from '../ts/functions.embeddeddb.js';
import type { IControllerDatabaseConfig } from '../ts/interfaces.config.js';
import {
  ControllerDataRootMigrationRunner,
  type IControllerDataRootMigrationResult,
  type IControllerDataWriterProcessRecord,
} from './v2_controllerdataroot.js';
import { flexProviderCredentialStoreId } from './v16_flexprovidercredentials.js';

const migrationVersion = 23 as const;
const journalFileName = 'agl-home-v23.json';
const maximumJournalBytes = 256 * 1024;
const maximumLockBytes = 4 * 1024;
const maximumJournalTemporaryFiles = 16;
const maximumLockTemporaryFiles = 16;
const maximumRootEntries = 2_048;
const maximumCredentialStores = 512;
const maximumLegacyUploadRoots = 256;
const maximumLegacyUploadNodes = 8_192;
const maximumLegacyUploadDepth = 32;
const controllerLogPattern = /^controller-(?:[1-9][0-9]{0,4})\.log(?:\.old)?$/;
const upgradeLogPattern = /^upgrade-[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{6}\.[0-9]{3}Z-[A-Za-z0-9_-]{10}\.log$/;
const credentialHashPattern = /^[a-f0-9]{64}$/;
const journalTemporaryPattern = /^agl-home-v23\.json\.[1-9][0-9]*-[a-f0-9]{16}\.tmp$/;
const lockTemporaryPattern = /\.tmp-([0-9]+)-([1-9][0-9]*)-([a-f0-9]{64})$/;
const legacyUploadRootPattern = /^harness-controller-uploads-[A-Za-z0-9]{6}$/;
const legacyUploadTombstonePattern = /^harness-controller-uploads-[A-Za-z0-9]{6}\.agl-v23-([a-f0-9]{64})\.removing$/;
const legacyUploadCleanupOperation = 'legacy-upload-roots';
const fixedOperationNames = new Set([
  'browser-runtime-active',
  'database-relocation-receipt',
  'git-reversion',
  'legacy-browser-runtime-config',
  'legacy-browser-runtime-state',
  'legacy-database-backup-v1',
  legacyUploadCleanupOperation,
  'legacy-v1-source-journal',
  'legacy-v1-target-journal',
  'legacy-v2-data-root-journal',
  'legacy-v2-database-relocation-receipt',
  'legacy-v2-target-marker',
  'unused-local-database',
]);

const isKnownOperationName = (valueArg: string): boolean => {
  if (fixedOperationNames.has(valueArg)) return true;
  if (/^credential:[a-f0-9]{64}$/.test(valueArg)) return true;
  const logMatch = /^log:(data|config|state):(.+)$/.exec(valueArg);
  return Boolean(logMatch && (
    controllerLogPattern.test(logMatch[2]) || upgradeLogPattern.test(logMatch[2])
  ));
};

export const legacyEmbeddedDatabaseSocketPath = (dataDirectoryArg: string): string => {
  const directoryHash = plugins.crypto
    .createHash('sha256')
    .update(dataDirectoryArg)
    .digest('hex')
    .slice(0, 16);
  return plugins.path.join(plugins.os.tmpdir(), `harness-controller-${directoryHash}.sock`);
};

export interface IAGLLegacyPaths {
  development: boolean;
  legacySourceEnabled: boolean;
  activeDataRoot: string;
  legacyConfigRoot?: string;
  legacyStateRoot?: string;
  v2JournalPath?: string;
  v2LockPath?: string;
}

const modulePackageRoot = plugins.path.resolve(
  plugins.path.dirname(plugins.url.fileURLToPath(import.meta.url)),
  '..',
);

const isDevelopmentCheckout = (packageRootArg: string): boolean => {
  try {
    const stats = plugins.fs.lstatSync(plugins.path.join(packageRootArg, '.git'));
    return stats.isDirectory() || stats.isFile();
  } catch {
    return false;
  }
};

export const resolveAGLLegacyPaths = (
  optionsArg: IAGLHomeOptions = {},
): IAGLLegacyPaths => {
  const environment = optionsArg.environment ?? process.env;
  const packageRoot = plugins.path.normalize(optionsArg.packageRoot ?? modulePackageRoot);
  if (isDevelopmentCheckout(packageRoot)) {
    const defaultRoot = plugins.path.join(packageRoot, '.nogit', 'agl');
    const configuredRoot = environment.AGL_HOME?.trim();
    const legacySourceEnabled = !configuredRoot
      || plugins.path.normalize(configuredRoot) === defaultRoot;
    return {
      development: true,
      legacySourceEnabled,
      activeDataRoot: plugins.path.join(packageRoot, '.nogit'),
    };
  }
  const homeDirectory = plugins.path.normalize(optionsArg.homeDirectory ?? plugins.os.homedir());
  const configuredConfigHome = environment.XDG_CONFIG_HOME?.trim();
  const configHome = configuredConfigHome && plugins.path.isAbsolute(configuredConfigHome)
    ? plugins.path.normalize(configuredConfigHome)
    : plugins.path.join(homeDirectory, '.config');
  const configuredStateHome = environment.XDG_STATE_HOME?.trim();
  const stateHome = configuredStateHome && plugins.path.isAbsolute(configuredStateHome)
    ? plugins.path.normalize(configuredStateHome)
    : plugins.path.join(homeDirectory, '.local', 'state');
  return {
    development: false,
    legacySourceEnabled: true,
    activeDataRoot: plugins.path.join(configHome, 'hcon'),
    legacyConfigRoot: plugins.path.join(configHome, 'harness-controller'),
    legacyStateRoot: plugins.path.join(stateHome, 'harness-controller'),
    v2JournalPath: plugins.path.join(configHome, '.hcon-controller-data-root-migration.json'),
    v2LockPath: plugins.path.join(configHome, '.hcon-controller-data-root-migration.lock'),
  };
};

export const readLegacyV2DatabaseConfig = (
  optionsArg: IAGLHomeOptions = {},
): IControllerDatabaseConfig => {
  const canonical = readDatabaseConfig(optionsArg);
  const environment = optionsArg.environment ?? process.env;
  if (canonical.mongoDbUrl !== undefined || environment.HARNESS_CONTROLLER_DB_DIR?.trim()) {
    return canonical;
  }
  const legacy = resolveAGLLegacyPaths(optionsArg);
  return {
    mongoDbName: canonical.mongoDbName,
    embeddedDataDirectory: plugins.path.join(legacy.activeDataRoot, 'smartdb'),
    ...(legacy.legacyStateRoot
      ? { legacyEmbeddedDataDirectory: plugins.path.join(legacy.legacyStateRoot, 'smartdb') }
      : {}),
  };
};

interface IFilesystemIdentity {
  device: string;
  inode: string;
}

interface ISourceIdentity extends IFilesystemIdentity {
  path: string;
}

interface ICredentialRelocationBinding {
  controllerHash: string;
  sourceDirectory: string;
}

interface ILegacyUploadRootBinding extends IFilesystemIdentity {
  path: string;
}

interface IAGLHomeMigrationJournal {
  version: typeof migrationVersion;
  phase: 'target-staged' | 'target-committed';
  mode: 'development' | 'installed';
  root: string;
  rootDevice: string;
  rootInode: string;
  nonce: string;
  sources: ISourceIdentity[];
  credentialRelocations: ICredentialRelocationBinding[];
  legacyUploadRoots: ILegacyUploadRootBinding[];
  completedOperations: string[];
}

interface ILockOwner {
  version: 1;
  pid: number;
  uid: number;
  fingerprint: string;
  nonce: string;
}

export interface IAGLHomeMigrationOptions {
  paths: IAGLHomePaths;
  legacyPaths: IAGLLegacyPaths;
  databaseConfig: IControllerDatabaseConfig;
  invokerPid: number;
  listDataWriterProcesses: () => Promise<readonly IControllerDataWriterProcessRecord[]>;
  isSocketListening?: (socketPathArg: string) => Promise<boolean>;
  relocateStoppedDatabaseRoot?: (
    inputArg: Readonly<plugins.smartdb.ILocalSmartDbStoppedStorageRootRelocationInput>,
    signalArg?: AbortSignal,
  ) => Promise<plugins.smartdb.ILocalSmartDbStoppedStorageRootRelocationReceipt>;
  relocateCredentialStore?: (
    inputArg: {
      controllerHash: string;
      sourceDirectory: string;
      destinationDirectory: string;
    },
    signalArg?: AbortSignal,
  ) => Promise<void>;
  legacyUploadTempDirectory?: string;
  signal?: AbortSignal;
}

export interface IAGLHomeMigrationPreflightOptions {
  allowDataWriters?: boolean;
}

export interface IAGLHomeMigrationResult {
  directoryPath: string;
  databaseConfig: IControllerDatabaseConfig;
}

const currentUid = (): number => {
  if (typeof process.getuid !== 'function') {
    throw new Error('AGL home migration requires a POSIX user identity.');
  }
  return process.getuid();
};

const isMissingError = (errorArg: unknown): boolean => (
  (errorArg as NodeJS.ErrnoException).code === 'ENOENT'
);

const identityFromStats = (statsArg: plugins.fs.BigIntStats): IFilesystemIdentity => ({
  device: statsArg.dev.toString(10),
  inode: statsArg.ino.toString(10),
});

const identitiesEqual = (
  leftArg: IFilesystemIdentity,
  rightArg: IFilesystemIdentity,
): boolean => leftArg.device === rightArg.device && leftArg.inode === rightArg.inode;

const lstatIfPresent = async (pathArg: string): Promise<plugins.fs.BigIntStats | undefined> => {
  try {
    return await plugins.fs.promises.lstat(pathArg, { bigint: true });
  } catch (errorArg) {
    if (isMissingError(errorArg)) return undefined;
    throw errorArg;
  }
};

const assertOwnedNode = (
  pathArg: string,
  statsArg: plugins.fs.BigIntStats,
  kindArg: 'file' | 'directory',
  privateRootArg = false,
): void => {
  if (
    statsArg.isSymbolicLink()
    || (kindArg === 'file' ? !statsArg.isFile() : !statsArg.isDirectory())
    || statsArg.uid !== BigInt(currentUid())
    || (kindArg === 'file' && statsArg.nlink !== 1n)
    || (privateRootArg && Number(statsArg.mode & 0o077n) !== 0)
  ) throw new Error(`AGL migration path is unsafe: ${pathArg}`);
};

const assertSafeAncestor = (pathArg: string, statsArg: plugins.fs.BigIntStats): void => {
  const mode = Number(statsArg.mode & 0o7777n);
  if (
    statsArg.isSymbolicLink()
    || !statsArg.isDirectory()
    || ((mode & 0o022) !== 0 && (mode & 0o1000) === 0)
  ) throw new Error(`AGL home ancestor is unsafe: ${pathArg}`);
};

const readBoundedDirectory = async (pathArg: string): Promise<string[]> => {
  const names = await plugins.fs.promises.readdir(pathArg);
  if (names.length > maximumRootEntries) {
    throw new Error(`AGL migration directory has too many entries: ${pathArg}`);
  }
  return names.sort();
};

const syncDirectory = async (pathArg: string): Promise<void> => {
  const handle = await plugins.fs.promises.open(
    pathArg,
    plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_DIRECTORY,
  );
  try {
    await handle.sync();
  } finally {
    await handle.close();
  }
};

const assertSafeSourceTree = async (
  rootArg: string,
  destinationDeviceArg?: string,
): Promise<void> => {
  const pending = [rootArg];
  let inspected = 0;
  while (pending.length > 0) {
    const path = pending.pop()!;
    const stats = await plugins.fs.promises.lstat(path, { bigint: true });
    if (
      stats.isSymbolicLink()
      || (!stats.isDirectory() && !stats.isFile())
      || stats.uid !== BigInt(currentUid())
      || (stats.isFile() && stats.nlink !== 1n)
      || (destinationDeviceArg !== undefined
        && stats.dev.toString(10) !== destinationDeviceArg)
    ) {
      throw new Error(`AGL migration source tree is unsafe: ${path}`);
    }
    inspected += 1;
    if (inspected > 200_000) throw new Error('AGL migration source tree exceeds its node limit.');
    if (!stats.isDirectory()) continue;
    for (const name of await readBoundedDirectory(path)) {
      pending.push(plugins.path.join(path, name));
    }
  }
};

const assertSafeLegacyUploadTree = async (
  rootArg: string,
  destinationDeviceArg: string,
): Promise<void> => {
  const pending = [{ path: rootArg, depth: 0 }];
  let inspected = 0;
  while (pending.length > 0) {
    const current = pending.pop()!;
    const stats = await plugins.fs.promises.lstat(current.path, { bigint: true });
    if (
      stats.isSymbolicLink()
      || (!stats.isDirectory() && !stats.isFile())
      || stats.uid !== BigInt(currentUid())
      || stats.dev.toString(10) !== destinationDeviceArg
      || (stats.isFile() && stats.nlink !== 1n)
    ) throw new Error(`Legacy controller upload tree is unsafe: ${current.path}`);
    inspected += 1;
    if (inspected > maximumLegacyUploadNodes) {
      throw new Error(`Legacy controller upload tree exceeds its node limit: ${rootArg}`);
    }
    if (!stats.isDirectory()) continue;
    const names = await readBoundedDirectory(current.path);
    if (names.length > 0 && current.depth >= maximumLegacyUploadDepth) {
      throw new Error(`Legacy controller upload tree exceeds its depth limit: ${rootArg}`);
    }
    for (const name of names) {
      pending.push({ path: plugins.path.join(current.path, name), depth: current.depth + 1 });
    }
  }
};

const nearestExistingDirectory = async (pathArg: string): Promise<{
  path: string;
  identity: IFilesystemIdentity;
}> => {
  let candidate = pathArg;
  while (true) {
    const stats = await lstatIfPresent(candidate);
    if (stats) {
      assertSafeAncestor(candidate, stats);
      const canonical = await plugins.fs.promises.realpath(candidate);
      if (canonical !== candidate) {
        throw new Error(`AGL home ancestor is not canonical: ${candidate}`);
      }
      return { path: candidate, identity: identityFromStats(stats) };
    }
    const parent = plugins.path.dirname(candidate);
    if (parent === candidate) throw new Error('AGL home has no existing directory ancestor.');
    candidate = parent;
  }
};

const parseJournal = (valueArg: unknown): IAGLHomeMigrationJournal => {
  if (!valueArg || typeof valueArg !== 'object' || Array.isArray(valueArg)) {
    throw new Error('AGL home migration journal is malformed.');
  }
  const value = valueArg as Record<string, unknown>;
  const keys = Object.keys(value).sort();
  const expected = [
    'completedOperations',
    'credentialRelocations',
    'legacyUploadRoots',
    'mode',
    'nonce',
    'phase',
    'root',
    'rootDevice',
    'rootInode',
    'sources',
    'version',
  ].sort();
  if (keys.length !== expected.length || keys.some((key, index) => key !== expected[index])) {
    throw new Error('AGL home migration journal has unexpected fields.');
  }
  if (
    value.version !== migrationVersion
    || (value.phase !== 'target-staged' && value.phase !== 'target-committed')
    || (value.mode !== 'development' && value.mode !== 'installed')
    || typeof value.root !== 'string'
    || !plugins.path.isAbsolute(value.root)
    || plugins.path.normalize(value.root) !== value.root
    || typeof value.rootDevice !== 'string'
    || !/^[0-9]+$/.test(value.rootDevice)
    || typeof value.rootInode !== 'string'
    || !/^[0-9]+$/.test(value.rootInode)
    || typeof value.nonce !== 'string'
    || !/^[a-f0-9]{64}$/.test(value.nonce)
    || !Array.isArray(value.completedOperations)
    || value.completedOperations.length > 4_096
    || !value.completedOperations.every((entry) => (
      typeof entry === 'string' && entry.length <= 512 && isKnownOperationName(entry)
    ))
    || new Set(value.completedOperations).size !== value.completedOperations.length
    || (value.completedOperations as string[]).some((entry, index, entries) => (
      index > 0 && entries[index - 1] > entry
    ))
    || !Array.isArray(value.sources)
    || value.sources.length > 8
    || !Array.isArray(value.credentialRelocations)
    || value.credentialRelocations.length > maximumCredentialStores
    || !Array.isArray(value.legacyUploadRoots)
    || value.legacyUploadRoots.length > maximumLegacyUploadRoots
  ) throw new Error('AGL home migration journal is invalid.');
  const sources = value.sources.map((entryArg): ISourceIdentity => {
    if (!entryArg || typeof entryArg !== 'object' || Array.isArray(entryArg)) {
      throw new Error('AGL home migration source binding is malformed.');
    }
    const entry = entryArg as Record<string, unknown>;
    if (
      Object.keys(entry).sort().join('\0') !== ['device', 'inode', 'path'].sort().join('\0')
      || typeof entry.path !== 'string'
      || !plugins.path.isAbsolute(entry.path)
      || plugins.path.normalize(entry.path) !== entry.path
      || typeof entry.device !== 'string'
      || !/^[0-9]+$/.test(entry.device)
      || typeof entry.inode !== 'string'
      || !/^[0-9]+$/.test(entry.inode)
    ) throw new Error('AGL home migration source binding is invalid.');
    return { path: entry.path, device: entry.device, inode: entry.inode };
  });
  const credentialRelocations = value.credentialRelocations.map(
    (entryArg, index, entries): ICredentialRelocationBinding => {
      if (!entryArg || typeof entryArg !== 'object' || Array.isArray(entryArg)) {
        throw new Error('AGL credential relocation binding is malformed.');
      }
      const entry = entryArg as Record<string, unknown>;
      if (
        Object.keys(entry).sort().join('\0')
          !== ['controllerHash', 'sourceDirectory'].sort().join('\0')
        || typeof entry.controllerHash !== 'string'
        || !credentialHashPattern.test(entry.controllerHash)
        || typeof entry.sourceDirectory !== 'string'
        || !plugins.path.isAbsolute(entry.sourceDirectory)
        || plugins.path.normalize(entry.sourceDirectory) !== entry.sourceDirectory
        || (index > 0
          && ((entries[index - 1] as Record<string, unknown>).controllerHash as string)
            >= entry.controllerHash)
      ) throw new Error('AGL credential relocation binding is invalid.');
      return {
        controllerHash: entry.controllerHash,
        sourceDirectory: entry.sourceDirectory,
      };
    },
  );
  const legacyUploadRoots = value.legacyUploadRoots.map(
    (entryArg, index, entries): ILegacyUploadRootBinding => {
      if (!entryArg || typeof entryArg !== 'object' || Array.isArray(entryArg)) {
        throw new Error('Legacy controller upload root binding is malformed.');
      }
      const entry = entryArg as Record<string, unknown>;
      if (
        Object.keys(entry).sort().join('\0') !== ['device', 'inode', 'path'].sort().join('\0')
        || typeof entry.path !== 'string'
        || !plugins.path.isAbsolute(entry.path)
        || plugins.path.normalize(entry.path) !== entry.path
        || !legacyUploadRootPattern.test(plugins.path.basename(entry.path))
        || typeof entry.device !== 'string'
        || !/^[0-9]+$/.test(entry.device)
        || typeof entry.inode !== 'string'
        || !/^[0-9]+$/.test(entry.inode)
        || (index > 0
          && ((entries[index - 1] as Record<string, unknown>).path as string) >= entry.path)
      ) throw new Error('Legacy controller upload root binding is invalid.');
      return {
        path: entry.path,
        device: entry.device,
        inode: entry.inode,
      };
    },
  );
  return {
    version: migrationVersion,
    phase: value.phase,
    mode: value.mode,
    root: value.root,
    rootDevice: value.rootDevice,
    rootInode: value.rootInode,
    nonce: value.nonce,
    sources,
    credentialRelocations,
    legacyUploadRoots,
    completedOperations: [...value.completedOperations],
  };
};

const readPrivateJournal = async (
  pathArg: string,
): Promise<IAGLHomeMigrationJournal | undefined> => {
  let handle: plugins.fs.promises.FileHandle;
  try {
    handle = await plugins.fs.promises.open(
      pathArg,
      plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
    );
  } catch (errorArg) {
    if (isMissingError(errorArg)) return undefined;
    throw errorArg;
  }
  try {
    const stats = await handle.stat({ bigint: true });
    if (
      !stats.isFile()
      || stats.uid !== BigInt(currentUid())
      || stats.nlink !== 1n
      || Number(stats.mode & 0o777n) !== 0o600
      || stats.size < 2n
      || stats.size > BigInt(maximumJournalBytes)
    ) throw new Error('AGL home migration journal is not a private bounded file.');
    return parseJournal(JSON.parse(await handle.readFile('utf8')) as unknown);
  } finally {
    await handle.close();
  }
};

const readPrivateLock = async (
  pathArg: string,
  allowHardlinkArg = false,
): Promise<{ identity: IFilesystemIdentity; owner: ILockOwner } | undefined> => {
  let handle: plugins.fs.promises.FileHandle;
  try {
    handle = await plugins.fs.promises.open(
      pathArg,
      plugins.fs.constants.O_RDONLY | plugins.fs.constants.O_NOFOLLOW,
    );
  } catch (errorArg) {
    if (isMissingError(errorArg)) return undefined;
    throw errorArg;
  }
  try {
    const stats = await handle.stat({ bigint: true });
    if (
      !stats.isFile()
      || stats.uid !== BigInt(currentUid())
      || (stats.nlink !== 1n && !(allowHardlinkArg && stats.nlink === 2n))
      || Number(stats.mode & 0o777n) !== 0o600
      || stats.size < 2n
      || stats.size > BigInt(maximumLockBytes)
    ) throw new Error('AGL home migration lock is not a private bounded file.');
    const raw = JSON.parse(await handle.readFile('utf8')) as Record<string, unknown>;
    if (
      Object.keys(raw).sort().join('\0')
        !== ['fingerprint', 'nonce', 'pid', 'uid', 'version'].sort().join('\0')
      || raw.version !== 1
      || raw.uid !== currentUid()
      || !Number.isSafeInteger(raw.pid)
      || (raw.pid as number) < 2
      || typeof raw.fingerprint !== 'string'
      || raw.fingerprint.length < 1
      || raw.fingerprint.length > 512
      || typeof raw.nonce !== 'string'
      || !/^[a-f0-9]{64}$/.test(raw.nonce)
    ) throw new Error('AGL home migration lock is malformed.');
    return {
      identity: identityFromStats(stats),
      owner: raw as unknown as ILockOwner,
    };
  } finally {
    await handle.close();
  }
};

const closeKernelStore = async (
  kernelStoreArg: plugins.smartsecret.SmartSecretKernelStore,
): Promise<void> => {
  const errors: unknown[] = [];
  for (let attempt = 0; attempt < 2; attempt += 1) {
    try {
      await kernelStoreArg.close();
      return;
    } catch (errorArg) {
      errors.push(errorArg);
    }
  }
  throw new AggregateError(errors, 'AGL credential kernel-store closure could not be confirmed.');
};

const retainedCredentialKernelStores = new Set<plugins.smartsecret.SmartSecretKernelStore>();

const drainRetainedCredentialKernelStores = async (): Promise<void> => {
  for (const kernelStore of retainedCredentialKernelStores) {
    await closeKernelStore(kernelStore);
    retainedCredentialKernelStores.delete(kernelStore);
  }
};

const relocateCredentialStore = async (
  inputArg: {
    controllerHash: string;
    sourceDirectory: string;
    destinationDirectory: string;
  },
  signalArg?: AbortSignal,
): Promise<void> => {
  signalArg?.throwIfAborted();
  await drainRetainedCredentialKernelStores();
  let kernelStore: plugins.smartsecret.SmartSecretKernelStore | undefined;
  let sealedStore: plugins.smartsecret.SmartSecretSealedFileStore | undefined;
  let operationError: unknown;
  try {
    kernelStore = await plugins.smartsecret.SmartSecretKernelStore.create({
      service: `modelprofile.flexharness.${inputArg.controllerHash.slice(0, 32)}`,
    });
    retainedCredentialKernelStores.add(kernelStore);
    sealedStore = await plugins.smartsecret.SmartSecretSealedFileStore.relocate({
      kernelStore,
      storeId: flexProviderCredentialStoreId,
      sourceDirectoryPath: inputArg.sourceDirectory,
      destinationDirectoryPath: inputArg.destinationDirectory,
    });
    await sealedStore.close();
    sealedStore = undefined;
  } catch (errorArg) {
    operationError = errorArg;
  }
  if (sealedStore) {
    try {
      await sealedStore.close();
    } catch (errorArg) {
      operationError = operationError
        ? new AggregateError([operationError, errorArg], 'AGL credential relocation cleanup failed.')
        : errorArg;
    }
  }
  if (kernelStore) {
    try {
      await closeKernelStore(kernelStore);
      retainedCredentialKernelStores.delete(kernelStore);
    } catch (errorArg) {
      operationError = operationError
        ? new AggregateError([operationError, errorArg], 'AGL credential relocation cleanup failed.')
        : errorArg;
    }
  }
  if (operationError) throw operationError;
};

export class AGLHomeMigrationRunner {
  private readonly journalPath: string;
  private readonly lockPath: string;
  private readonly socketCheck: (socketPathArg: string) => Promise<boolean>;
  private readonly relocateDatabase: NonNullable<
    IAGLHomeMigrationOptions['relocateStoppedDatabaseRoot']
  >;
  private readonly relocateCredentials: NonNullable<
    IAGLHomeMigrationOptions['relocateCredentialStore']
  >;
  private readonly legacyUploadTempDirectory: string;

  constructor(private readonly options: IAGLHomeMigrationOptions) {
    this.journalPath = plugins.path.join(options.paths.migration, journalFileName);
    this.lockPath = plugins.path.join(
      plugins.path.dirname(options.paths.root),
      `.${plugins.path.basename(options.paths.root)}-home-migration.lock`,
    );
    this.socketCheck = options.isSocketListening ?? isSocketListening;
    this.relocateDatabase = options.relocateStoppedDatabaseRoot
      ?? (async (inputArg, signalArg) => plugins.smartdb.LocalSmartDb.relocateStoppedStorageRoot(
        { ...inputArg },
        signalArg ? { signal: signalArg } : undefined,
      ));
    this.relocateCredentials = options.relocateCredentialStore ?? relocateCredentialStore;
    const configuredLegacyUploadTempDirectory = plugins.path.normalize(
      options.legacyUploadTempDirectory ?? plugins.os.tmpdir(),
    );
    if (
      !plugins.path.isAbsolute(configuredLegacyUploadTempDirectory)
      || plugins.path.parse(configuredLegacyUploadTempDirectory).root
        === configuredLegacyUploadTempDirectory
      || configuredLegacyUploadTempDirectory.includes('\0')
      || Buffer.byteLength(configuredLegacyUploadTempDirectory, 'utf8') > 4096
    ) throw new Error('The legacy controller upload temp directory is invalid.');
    this.legacyUploadTempDirectory = plugins.fs.realpathSync(configuredLegacyUploadTempDirectory);
  }

  public async isCommitted(): Promise<boolean> {
    const journal = await readPrivateJournal(this.journalPath);
    if (!journal) return false;
    this.assertJournalBinding(journal);
    await this.assertJournalRootIdentity(journal);
    return journal.phase === 'target-committed';
  }

  public async hasStarted(): Promise<boolean> {
    const journal = await readPrivateJournal(this.journalPath);
    if (!journal) return false;
    this.assertJournalBinding(journal);
    await this.assertJournalRootIdentity(journal);
    return true;
  }

  /** Performs no writes and is safe to invoke before logs or admission state exist. */
  public async preflight(optionsArg: IAGLHomeMigrationPreflightOptions = {}): Promise<void> {
    this.options.signal?.throwIfAborted();
    if (this.options.invokerPid !== process.pid) {
      throw new Error('AGL home migration invoker PID is not the current process.');
    }
    if (plugins.path.dirname(this.options.paths.root) === this.options.paths.root) {
      throw new Error('AGL_HOME cannot be a filesystem root.');
    }
    const destinationParent = await lstatIfPresent(plugins.path.dirname(this.options.paths.root));
    if (!destinationParent) {
      throw new Error('The direct parent of AGL_HOME must already exist.');
    }
    assertSafeAncestor(plugins.path.dirname(this.options.paths.root), destinationParent);
    const destinationAncestor = await nearestExistingDirectory(this.options.paths.root);
    const rootStats = await lstatIfPresent(this.options.paths.root);
    if (rootStats) assertOwnedNode(this.options.paths.root, rootStats, 'directory', true);
    const journal = await readPrivateJournal(this.journalPath);
    if (journal) {
      this.assertJournalBinding(journal);
      await this.assertJournalRootIdentity(journal, rootStats);
      for (const source of journal.sources) {
        const stats = await lstatIfPresent(source.path);
        if (stats && !identitiesEqual(identityFromStats(stats), source)) {
          throw new Error(`AGL migration source identity changed: ${source.path}`);
        }
      }
      if (journal.completedOperations.includes(legacyUploadCleanupOperation)) {
        await this.assertNoLegacyUploadRoots(journal);
      }
    }
    if (rootStats && journal?.phase !== 'target-committed') {
      await assertSafeSourceTree(this.options.paths.root, destinationAncestor.identity.device);
    }
    await this.inspectTargetInventory(journal !== undefined);
    const sourceNodes = await this.inspectSourceInventories();
    if (journal?.phase === 'target-committed' && sourceNodes.length > 0) {
      throw new Error('Legacy AGL state appeared after the target became authoritative.');
    }
    for (const source of sourceNodes) {
      if (await plugins.fs.promises.realpath(source.path) !== source.path) {
        throw new Error(`AGL migration source path is not canonical: ${source.path}`);
      }
      if (source.identity.device !== destinationAncestor.identity.device) {
        throw new Error(
          `AGL home migration cannot cross filesystems: ${source.path} -> ${this.options.paths.root}`,
        );
      }
      await assertSafeSourceTree(source.path, destinationAncestor.identity.device);
    }
    await this.assertGitStateRelocatable();
    if (!optionsArg.allowDataWriters) await this.assertNoConflictingWriters();
    if (this.usesDefaultEmbeddedDatabase()) {
      const directories = [this.options.paths.database];
      if (this.options.legacyPaths.legacySourceEnabled) {
        directories.unshift(plugins.path.join(this.options.legacyPaths.activeDataRoot, 'smartdb'));
      }
      if (this.options.legacyPaths.legacyStateRoot) {
        directories.unshift(plugins.path.join(this.options.legacyPaths.legacyStateRoot, 'smartdb'));
      }
      for (const directory of directories) {
        if (
          journal?.phase === 'target-committed'
          && directory === this.options.paths.database
        ) continue;
        const socketPath = directory === this.options.paths.database
          ? embeddedDatabaseSocketPath(directory, this.options.paths.sockets)
          : legacyEmbeddedDatabaseSocketPath(directory);
        if (await this.socketCheck(socketPath)) {
          throw new Error(`AGL database migration is blocked by an active socket: ${directory}`);
        }
      }
    }
  }

  public async run(): Promise<IAGLHomeMigrationResult> {
    await this.preflight();
    const lock = await this.acquireLock();
    let operationError: unknown;
    let result: IAGLHomeMigrationResult | undefined;
    try {
      await this.cleanupJournalTemporaryFiles();
      await this.preflight();
      result = await this.runLocked();
    } catch (errorArg) {
      operationError = errorArg;
    }
    try {
      await this.releaseLock(lock);
    } catch (errorArg) {
      operationError = operationError
        ? new AggregateError([operationError, errorArg], 'AGL home migration and lock cleanup failed.')
        : errorArg;
    }
    if (operationError) throw operationError;
    return result!;
  }

  private usesDefaultEmbeddedDatabase(): boolean {
    return this.options.databaseConfig.mongoDbUrl === undefined
      && this.options.databaseConfig.embeddedDataDirectory === this.options.paths.database;
  }

  private isConfiguredDatabaseSource(pathArg: string): boolean {
    return this.options.databaseConfig.mongoDbUrl === undefined
      && this.options.databaseConfig.embeddedDataDirectory !== undefined
      && plugins.path.normalize(this.options.databaseConfig.embeddedDataDirectory)
        !== plugins.path.normalize(this.options.paths.database)
      && plugins.path.normalize(this.options.databaseConfig.embeddedDataDirectory)
        === plugins.path.normalize(pathArg);
  }

  private assertJournalBinding(journalArg: IAGLHomeMigrationJournal): void {
    if (
      journalArg.root !== this.options.paths.root
      || journalArg.mode !== (this.options.legacyPaths.development ? 'development' : 'installed')
    ) throw new Error('AGL home migration journal belongs to another home or runtime mode.');
    const sourceRoots = new Set([
      ...(this.options.legacyPaths.legacySourceEnabled
        ? [plugins.path.join(this.options.legacyPaths.activeDataRoot, 'flex-provider-credentials')]
        : []),
      ...(this.options.legacyPaths.legacyConfigRoot
        ? [plugins.path.join(this.options.legacyPaths.legacyConfigRoot, 'flex-provider-credentials')]
        : []),
    ]);
    for (const binding of journalArg.credentialRelocations) {
      if (!sourceRoots.has(plugins.path.dirname(binding.sourceDirectory))) {
        throw new Error('AGL credential relocation binding belongs to another source root.');
      }
      if (plugins.path.basename(binding.sourceDirectory) !== binding.controllerHash) {
        throw new Error('AGL credential relocation binding does not match its controller hash.');
      }
    }
    for (const binding of journalArg.legacyUploadRoots) {
      if (
        plugins.path.dirname(binding.path) !== this.legacyUploadTempDirectory
        || !legacyUploadRootPattern.test(plugins.path.basename(binding.path))
      ) throw new Error('Legacy controller upload root binding belongs to another temp directory.');
    }
    const boundHashes = new Set(
      journalArg.credentialRelocations.map((binding) => binding.controllerHash),
    );
    for (const operation of journalArg.completedOperations) {
      if (operation.startsWith('credential:') && !boundHashes.has(operation.slice('credential:'.length))) {
        throw new Error('Completed AGL credential relocation has no source binding.');
      }
    }
  }

  private async assertJournalRootIdentity(
    journalArg: IAGLHomeMigrationJournal,
    statsArg?: plugins.fs.BigIntStats,
  ): Promise<void> {
    const stats = statsArg ?? await lstatIfPresent(this.options.paths.root);
    if (
      !stats
      || !stats.isDirectory()
      || !identitiesEqual(identityFromStats(stats), {
        device: journalArg.rootDevice,
        inode: journalArg.rootInode,
      })
    ) throw new Error('AGL home root identity changed after migration staging.');
  }

  private async inspectTargetInventory(hasJournalArg: boolean): Promise<void> {
    const root = await lstatIfPresent(this.options.paths.root);
    if (!root) return;
    const allowed = new Set([
      'database',
      'credentials',
      'git-reversion',
      'logs',
      'upgrade',
      'cache',
      'runtime',
      'migration',
      'identity',
    ]);
    for (const name of await readBoundedDirectory(this.options.paths.root)) {
      if (!allowed.has(name)) throw new Error(`Unexpected entry in AGL_HOME: ${name}`);
      const path = plugins.path.join(this.options.paths.root, name);
      const stats = await plugins.fs.promises.lstat(path, { bigint: true });
      assertOwnedNode(path, stats, 'directory', true);
      if (!hasJournalArg && name !== 'upgrade' && name !== 'migration') {
        throw new Error(`Unjournaled AGL_HOME state is ambiguous: ${path}`);
      }
    }
    const migrationStats = await lstatIfPresent(this.options.paths.migration);
    if (migrationStats) {
      const migrationNames = await readBoundedDirectory(this.options.paths.migration);
      const allowedNames = hasJournalArg
        ? new Set([
            journalFileName,
            'active-database-relocation-receipt.json',
            'legacy-unused-local-database',
            'legacy-database-backup-v1',
            'legacy-v2-target-marker.json',
            'legacy-v1-target-journal.json',
            'legacy-v1-source-journal.json',
            'legacy-v2-database-relocation-receipt.json',
            'legacy-browser-runtime-config',
            'legacy-browser-runtime-state',
            'legacy-v2-data-root-journal.json',
          ])
        : new Set<string>();
      const journalTemporaryNames = migrationNames.filter((name) => journalTemporaryPattern.test(name));
      if (journalTemporaryNames.length > maximumJournalTemporaryFiles) {
        throw new Error('AGL migration directory contains too many journal artifacts.');
      }
      if (
        (hasJournalArg && !migrationNames.includes(journalFileName))
        || migrationNames.some((name) => (
          !allowedNames.has(name) && !journalTemporaryPattern.test(name)
        ))
      ) throw new Error('AGL migration directory inventory is invalid.');
      for (const name of journalTemporaryNames) {
        const path = plugins.path.join(this.options.paths.migration, name);
        const stats = await plugins.fs.promises.lstat(path, { bigint: true });
        if (
          !stats.isFile()
          || stats.isSymbolicLink()
          || stats.uid !== BigInt(currentUid())
          || stats.nlink !== 1n
          || Number(stats.mode & 0o777n) !== 0o600
          || stats.size > BigInt(maximumJournalBytes)
        ) throw new Error(`AGL journal artifact is unsafe: ${path}`);
      }
    }
  }

  private async inspectSourceInventories(): Promise<Array<{
    path: string;
    identity: IFilesystemIdentity;
  }>> {
    const nodes: Array<{ path: string; identity: IFilesystemIdentity }> = [];
    const inspectRoot = async (
      rootArg: string | undefined,
      allowedArg: ReadonlySet<string>,
      dedicatedArg: boolean,
    ): Promise<void> => {
      if (!rootArg) return;
      const root = await lstatIfPresent(rootArg);
      if (!root) return;
      assertOwnedNode(rootArg, root, 'directory', dedicatedArg);
      const names = await readBoundedDirectory(rootArg);
      for (const name of names) {
        if (!allowedArg.has(name)) {
          if (dedicatedArg) throw new Error(`Unknown AGL legacy entry: ${plugins.path.join(rootArg, name)}`);
          continue;
        }
        const path = plugins.path.join(rootArg, name);
        if (this.isConfiguredDatabaseSource(path)) continue;
        const stats = await plugins.fs.promises.lstat(path, { bigint: true });
        if (stats.isSymbolicLink() || stats.uid !== BigInt(currentUid())) {
          throw new Error(`AGL legacy entry is unsafe: ${path}`);
        }
        nodes.push({ path, identity: identityFromStats(stats) });
      }
    };
    const dataAllowed = new Set([
      '.hcon-controller-data-root-marker.json',
      '.smartdb-location-migration.json',
      'smartdb',
      'flex-provider-credentials',
      'git-reversion',
      'browser-runtime',
    ]);
    if (this.options.legacyPaths.development) {
      for (const name of await this.listLegacyLogNames(this.options.legacyPaths.activeDataRoot)) {
        dataAllowed.add(name);
      }
    }
    if (this.options.legacyPaths.legacySourceEnabled) {
      await inspectRoot(
        this.options.legacyPaths.activeDataRoot,
        dataAllowed,
        !this.options.legacyPaths.development,
      );
    }
    const configAllowed = new Set([
      '.smartdb-location-migration.json',
      'smartdb',
      'flex-provider-credentials',
      'browser-runtime',
    ]);
    for (const name of await this.listLegacyLogNames(this.options.legacyPaths.legacyConfigRoot)) {
      configAllowed.add(name);
    }
    await inspectRoot(this.options.legacyPaths.legacyConfigRoot, configAllowed, true);
    const stateAllowed = new Set(['smartdb', 'browser-runtime']);
    for (const name of await this.listLegacyLogNames(this.options.legacyPaths.legacyStateRoot)) {
      stateAllowed.add(name);
    }
    await inspectRoot(this.options.legacyPaths.legacyStateRoot, stateAllowed, true);
    for (const path of [this.options.legacyPaths.v2JournalPath]) {
      if (!path) continue;
      const stats = await lstatIfPresent(path);
      if (!stats) continue;
      assertOwnedNode(path, stats, 'file', true);
      nodes.push({ path, identity: identityFromStats(stats) });
    }
    if (this.options.legacyPaths.v2LockPath) {
      const lock = await lstatIfPresent(this.options.legacyPaths.v2LockPath);
      if (lock) throw new Error('The legacy controller data-root migration lock is still present.');
      const parent = plugins.path.dirname(this.options.legacyPaths.v2LockPath);
      const base = plugins.path.basename(this.options.legacyPaths.v2LockPath);
      for (const name of await readBoundedDirectory(parent)) {
        if (name.startsWith(`${base}.`)) {
          throw new Error(`A legacy controller data-root migration lock artifact remains: ${name}`);
        }
      }
    }
    return nodes;
  }

  private async listLegacyLogNames(rootArg: string | undefined): Promise<string[]> {
    if (!rootArg || !await lstatIfPresent(rootArg)) return [];
    return (await readBoundedDirectory(rootArg)).filter((name) => (
      controllerLogPattern.test(name) || upgradeLogPattern.test(name)
    ));
  }

  private async assertNoConflictingWriters(): Promise<void> {
    const invoker = await readControllerProcessIdentity(this.options.invokerPid);
    if (!invoker) throw new Error('AGL home migration invoker identity cannot be verified.');
    const records = await this.options.listDataWriterProcesses();
    if (!Array.isArray(records) || records.length > 1_024) {
      throw new Error('AGL data-writer process inventory is invalid.');
    }
    for (const record of records) {
      if (
        record.identity.pid === invoker.pid
        && record.identity.fingerprint === invoker.fingerprint
      ) continue;
      throw new Error(`AGL home migration is blocked by ${record.kind} writer PID ${record.identity.pid}.`);
    }
  }

  private async assertGitStateRelocatable(): Promise<void> {
    if (!this.options.legacyPaths.legacySourceEnabled) return;
    const root = plugins.path.join(this.options.legacyPaths.activeDataRoot, 'git-reversion');
    if (!await lstatIfPresent(root)) return;
    await assertSafeSourceTree(root);
    for (const owner of await readBoundedDirectory(root)) {
      if (!credentialHashPattern.test(owner)) {
        throw new Error(`Unexpected AGL Git reversion owner directory: ${owner}`);
      }
      const ownerRoot = plugins.path.join(root, owner);
      const ownerStats = await plugins.fs.promises.lstat(ownerRoot, { bigint: true });
      assertOwnedNode(ownerRoot, ownerStats, 'directory');
      for (const name of ['worktrees', 'worktree-records']) {
        const directory = plugins.path.join(ownerRoot, name);
        const stats = await lstatIfPresent(directory);
        if (stats && (await readBoundedDirectory(directory)).length > 0) {
          throw new Error(`AGL home migration is blocked by active Git worktree state: ${directory}`);
        }
      }
    }
  }

  private async runLocked(): Promise<IAGLHomeMigrationResult> {
    let journal = await readPrivateJournal(this.journalPath);
    if (journal?.phase === 'target-committed') {
      this.assertJournalBinding(journal);
      await this.assertJournalRootIdentity(journal);
      return {
        directoryPath: this.options.paths.root,
        databaseConfig: { ...this.options.databaseConfig },
      };
    }
    await plugins.fs.promises.mkdir(this.options.paths.root, { recursive: true, mode: 0o700 });
    await plugins.fs.promises.chmod(this.options.paths.root, 0o700);
    await plugins.fs.promises.mkdir(this.options.paths.migration, { recursive: true, mode: 0o700 });
    await plugins.fs.promises.chmod(this.options.paths.migration, 0o700);
    if (!journal) {
      const rootIdentity = identityFromStats(await plugins.fs.promises.lstat(
        this.options.paths.root,
        { bigint: true },
      ));
      const sources: ISourceIdentity[] = [];
      for (const path of [
        this.options.legacyPaths.legacySourceEnabled
          ? this.options.legacyPaths.activeDataRoot
          : undefined,
        this.options.legacyPaths.legacyConfigRoot,
        this.options.legacyPaths.legacyStateRoot,
      ]) {
        if (!path) continue;
        const stats = await lstatIfPresent(path);
        if (stats) sources.push({ path, ...identityFromStats(stats) });
      }
      journal = {
        version: migrationVersion,
        phase: 'target-staged',
        mode: this.options.legacyPaths.development ? 'development' : 'installed',
        root: this.options.paths.root,
        rootDevice: rootIdentity.device,
        rootInode: rootIdentity.inode,
        nonce: plugins.crypto.randomBytes(32).toString('hex'),
        sources,
        credentialRelocations: [],
        legacyUploadRoots: [],
        completedOperations: [],
      };
      await this.writeJournal(journal);
    }
    this.assertJournalBinding(journal);
    await this.migrateDatabase(journal);
    await this.migrateCredentials(journal);
    if (this.options.legacyPaths.legacySourceEnabled) {
      await this.moveDirect(
        plugins.path.join(this.options.legacyPaths.activeDataRoot, 'git-reversion'),
        this.options.paths.gitReversion,
        'git-reversion',
        'directory',
        journal,
      );
      await this.moveDirect(
        plugins.path.join(this.options.legacyPaths.activeDataRoot, 'browser-runtime'),
        this.options.paths.browserRuntime,
        'browser-runtime-active',
        'directory',
        journal,
      );
    }
    for (const [root, category] of [
      [
        this.options.legacyPaths.legacySourceEnabled
          ? this.options.legacyPaths.activeDataRoot
          : undefined,
        'data',
      ],
      [this.options.legacyPaths.legacyConfigRoot, 'config'],
      [this.options.legacyPaths.legacyStateRoot, 'state'],
    ] as const) {
      await this.migrateLogs(root, category, journal);
    }
    await this.moveLegacyMetadata(journal);
    await this.cleanupLegacyUploadRoots(journal);
    await this.cleanupLegacyRoots();
    if ((await this.inspectSourceInventories()).length > 0) {
      throw new Error('AGL legacy source inventory is not empty after migration.');
    }
    for (const directory of [
      this.options.paths.database,
      this.options.paths.credentials,
      this.options.paths.gitReversion,
      this.options.paths.logs,
      this.options.paths.legacyLogs,
      this.options.paths.upgrade,
      this.options.paths.cache,
      this.options.paths.runtime,
      this.options.paths.mcpRuntime,
      this.options.paths.browserRuntime,
      this.options.paths.uploads,
      this.options.paths.sockets,
      this.options.paths.openCodeRuntime,
      this.options.paths.migration,
    ]) {
      await plugins.fs.promises.mkdir(directory, { recursive: true, mode: 0o700 });
      await plugins.fs.promises.chmod(directory, 0o700);
    }
    await this.inspectTargetInventory(true);
    await assertSafeSourceTree(this.options.paths.root, journal.rootDevice);
    journal = { ...journal, phase: 'target-committed' };
    await this.writeJournal(journal);
    return {
      directoryPath: this.options.paths.root,
      databaseConfig: { ...this.options.databaseConfig },
    };
  }

  private async migrateDatabase(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    const source = plugins.path.join(this.options.legacyPaths.activeDataRoot, 'smartdb');
    const sourceStats = this.options.legacyPaths.legacySourceEnabled
      ? await lstatIfPresent(source)
      : undefined;
    const destinationStats = await lstatIfPresent(this.options.paths.database);
    if (this.usesDefaultEmbeddedDatabase()) {
      if (sourceStats?.isDirectory()) {
        const receipt = await this.relocateDatabase({
          sourceFolderPath: source,
          destinationFolderPath: this.options.paths.database,
          relocationId: `agl-home-v23:${journalArg.nonce}:database`,
        }, this.options.signal);
        if (
          receipt.sourceFolderPath !== source
          || receipt.destinationFolderPath !== this.options.paths.database
          || receipt.sourceReceiptRetained !== true
          || receipt.storageRootDevice !== sourceStats.dev.toString(10)
          || receipt.storageRootInode !== sourceStats.ino.toString(10)
          || !/^[a-f0-9]{64}$/.test(receipt.providerRootId)
          || !/^[a-f0-9]{64}$/.test(receipt.receiptSha256)
        ) throw new Error('AGL SmartDB relocation receipt does not match its operation.');
        const relocated = await plugins.fs.promises.lstat(
          this.options.paths.database,
          { bigint: true },
        );
        if (
          !relocated.isDirectory()
          || relocated.dev.toString(10) !== receipt.storageRootDevice
          || relocated.ino.toString(10) !== receipt.storageRootInode
        ) throw new Error('AGL SmartDB destination identity does not match its receipt.');
        const retainedReceiptStats = await plugins.fs.promises.lstat(source, { bigint: true });
        if (
          !retainedReceiptStats.isFile()
          || retainedReceiptStats.uid !== BigInt(currentUid())
          || Number(retainedReceiptStats.mode & 0o777n) !== 0o600
          || retainedReceiptStats.size < 2n
          || retainedReceiptStats.size > 16_384n
        ) throw new Error('AGL SmartDB retained receipt is unsafe.');
        const retainedReceipt = JSON.parse(
          await plugins.fs.promises.readFile(source, 'utf8'),
        ) as Record<string, unknown>;
        for (const key of [
          'format',
          'version',
          'relocationId',
          'sourceFolderPath',
          'destinationFolderPath',
          'providerRootId',
          'storageRootDevice',
          'storageRootInode',
          'receiptSha256',
          'sourceReceiptRetained',
        ] as const) {
          if (retainedReceipt[key] !== receipt[key]) {
            throw new Error('AGL SmartDB retained receipt does not match its API receipt.');
          }
        }
      } else if (sourceStats && !sourceStats.isFile()) {
        throw new Error(`Legacy AGL database path is unsafe: ${source}`);
      } else if (!sourceStats && destinationStats && !destinationStats.isDirectory()) {
        throw new Error('AGL database destination is not a directory.');
      } else if (sourceStats?.isFile() && !destinationStats) {
        throw new Error('AGL database relocation receipt exists without its destination.');
      }
      await this.moveDirect(
        source,
        plugins.path.join(this.options.paths.migration, 'active-database-relocation-receipt.json'),
        'database-relocation-receipt',
        'file',
        journalArg,
      );
    } else if (!this.isConfiguredDatabaseSource(source) && (sourceStats || destinationStats)) {
      await this.moveDirect(
        source,
        plugins.path.join(this.options.paths.migration, 'legacy-unused-local-database'),
        'unused-local-database',
        sourceStats?.isFile() ? 'file' : 'directory',
        journalArg,
      );
    }
    if (this.options.legacyPaths.legacyStateRoot) {
      const historicalDatabase = plugins.path.join(
        this.options.legacyPaths.legacyStateRoot,
        'smartdb',
      );
      if (this.isConfiguredDatabaseSource(historicalDatabase)) return;
      await this.moveDirect(
        historicalDatabase,
        plugins.path.join(this.options.paths.migration, 'legacy-database-backup-v1'),
        'legacy-database-backup-v1',
        'directory',
        journalArg,
      );
    }
  }

  private async migrateCredentials(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    const destinationRoot = plugins.path.join(
      this.options.paths.credentials,
      'flex-provider-credentials',
    );
    const sourceRoots = [
      ...(this.options.legacyPaths.legacySourceEnabled
        ? [plugins.path.join(this.options.legacyPaths.activeDataRoot, 'flex-provider-credentials')]
        : []),
      ...(this.options.legacyPaths.legacyConfigRoot
        ? [plugins.path.join(this.options.legacyPaths.legacyConfigRoot, 'flex-provider-credentials')]
        : []),
    ];
    const sourceByHash = new Map<string, string>();
    for (const root of sourceRoots) {
      const stats = await lstatIfPresent(root);
      if (!stats) continue;
      assertOwnedNode(root, stats, 'directory', true);
      const hashes = await readBoundedDirectory(root);
      if (hashes.length > maximumCredentialStores) {
        throw new Error('Legacy AGL credential root has too many stores.');
      }
      for (const hash of hashes) {
        if (!credentialHashPattern.test(hash) || sourceByHash.has(hash)) {
          throw new Error(`Legacy AGL credential store is ambiguous: ${hash}`);
        }
        sourceByHash.set(hash, plugins.path.join(root, hash));
      }
    }
    const destinationHashes: string[] = [];
    const destinationRootStats = await lstatIfPresent(destinationRoot);
    if (destinationRootStats) {
      assertOwnedNode(destinationRoot, destinationRootStats, 'directory', true);
      for (const hash of await readBoundedDirectory(destinationRoot)) {
        if (!credentialHashPattern.test(hash)) {
          throw new Error(`AGL credential destination contains an unexpected entry: ${hash}`);
        }
        destinationHashes.push(hash);
      }
    }
    const bindingByHash = new Map(
      journalArg.credentialRelocations.map((binding) => [binding.controllerHash, binding]),
    );
    const hashes = [...new Set([
      ...sourceByHash.keys(),
      ...destinationHashes,
      ...bindingByHash.keys(),
    ])].sort();
    if (hashes.length > maximumCredentialStores) {
      throw new Error('AGL credential migration contains too many stores.');
    }
    if (hashes.length > 0 && !destinationRootStats) {
      await plugins.fs.promises.mkdir(destinationRoot, { recursive: true, mode: 0o700 });
      await plugins.fs.promises.chmod(this.options.paths.credentials, 0o700);
      await plugins.fs.promises.chmod(destinationRoot, 0o700);
    }
    for (const hash of hashes) {
      let binding = bindingByHash.get(hash);
      const observedSource = sourceByHash.get(hash);
      if (binding && observedSource && binding.sourceDirectory !== observedSource) {
        throw new Error(`AGL credential source changed after relocation intent: ${hash}`);
      }
      if (!binding) {
        if (!observedSource) {
          throw new Error(`AGL credential destination has no relocation intent: ${hash}`);
        }
        binding = { controllerHash: hash, sourceDirectory: observedSource };
        journalArg.credentialRelocations.push(binding);
        journalArg.credentialRelocations.sort((left, right) => (
          left.controllerHash.localeCompare(right.controllerHash)
        ));
        bindingByHash.set(hash, binding);
        await this.writeJournal(journalArg);
      }
      const source = binding.sourceDirectory;
      const destination = plugins.path.join(destinationRoot, hash);
      const sourceStats = await lstatIfPresent(source);
      const destinationStats = await lstatIfPresent(destination);
      if (sourceStats && destinationStats) {
        throw new Error(`AGL credential store exists at both source and destination: ${hash}`);
      }
      if (sourceStats) assertOwnedNode(source, sourceStats, 'directory', true);
      if (destinationStats) assertOwnedNode(destination, destinationStats, 'directory', true);
      const operation = `credential:${hash}`;
      if (journalArg.completedOperations.includes(operation)) {
        if (sourceStats || !destinationStats) {
          throw new Error(`Completed AGL credential relocation has an invalid location: ${hash}`);
        }
        continue;
      }
      if (!sourceStats && !destinationStats) {
        throw new Error(`AGL credential relocation has no source or destination: ${hash}`);
      }
      await this.relocateCredentials({
        controllerHash: hash,
        sourceDirectory: source,
        destinationDirectory: destination,
      }, this.options.signal);
      if (await lstatIfPresent(source)) {
        throw new Error(`AGL credential source remains after relocation: ${hash}`);
      }
      const migrated = await lstatIfPresent(destination);
      if (!migrated) throw new Error(`AGL credential relocation was not confirmed: ${hash}`);
      assertOwnedNode(destination, migrated, 'directory', true);
      await this.markOperation(journalArg, operation);
    }
  }

  private async migrateLogs(
    rootArg: string | undefined,
    categoryArg: string,
    journalArg: IAGLHomeMigrationJournal,
  ): Promise<void> {
    if (!rootArg || !await lstatIfPresent(rootArg)) return;
    for (const name of await this.listLegacyLogNames(rootArg)) {
      await this.moveDirect(
        plugins.path.join(rootArg, name),
        plugins.path.join(this.options.paths.legacyLogs, categoryArg, name),
        `log:${categoryArg}:${name}`,
        'file',
        journalArg,
      );
    }
  }

  private async moveLegacyMetadata(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    const legacyConfigDatabase = this.options.legacyPaths.legacyConfigRoot
      ? plugins.path.join(this.options.legacyPaths.legacyConfigRoot, 'smartdb')
      : undefined;
    const moves: Array<[string | undefined, string, string, 'file' | 'directory']> = [
      [
        this.options.legacyPaths.legacySourceEnabled
          ? plugins.path.join(
              this.options.legacyPaths.activeDataRoot,
              '.hcon-controller-data-root-marker.json',
            )
          : undefined,
        'legacy-v2-target-marker.json',
        'legacy-v2-target-marker',
        'file',
      ],
      [
        this.options.legacyPaths.legacySourceEnabled
          ? plugins.path.join(
              this.options.legacyPaths.activeDataRoot,
              '.smartdb-location-migration.json',
            )
          : undefined,
        'legacy-v1-target-journal.json',
        'legacy-v1-target-journal',
        'file',
      ],
      [
        this.options.legacyPaths.legacyConfigRoot
          ? plugins.path.join(this.options.legacyPaths.legacyConfigRoot, '.smartdb-location-migration.json')
          : undefined,
        'legacy-v1-source-journal.json',
        'legacy-v1-source-journal',
        'file',
      ],
      [
        legacyConfigDatabase && !this.isConfiguredDatabaseSource(legacyConfigDatabase)
          ? legacyConfigDatabase
          : undefined,
        'legacy-v2-database-relocation-receipt.json',
        'legacy-v2-database-relocation-receipt',
        'file',
      ],
      [
        this.options.legacyPaths.legacyConfigRoot
          ? plugins.path.join(this.options.legacyPaths.legacyConfigRoot, 'browser-runtime')
          : undefined,
        'legacy-browser-runtime-config',
        'legacy-browser-runtime-config',
        'directory',
      ],
      [
        this.options.legacyPaths.legacyStateRoot
          ? plugins.path.join(this.options.legacyPaths.legacyStateRoot, 'browser-runtime')
          : undefined,
        'legacy-browser-runtime-state',
        'legacy-browser-runtime-state',
        'directory',
      ],
      [
        this.options.legacyPaths.v2JournalPath,
        'legacy-v2-data-root-journal.json',
        'legacy-v2-data-root-journal',
        'file',
      ],
    ];
    for (const [source, destinationName, operation, kind] of moves) {
      if (!source) continue;
      await this.moveDirect(
        source,
        plugins.path.join(this.options.paths.migration, destinationName),
        operation,
        kind,
        journalArg,
      );
    }
  }

  private legacyUploadTombstonePath(
    bindingArg: ILegacyUploadRootBinding,
    journalArg: IAGLHomeMigrationJournal,
  ): string {
    return `${bindingArg.path}.agl-v23-${journalArg.nonce}.removing`;
  }

  private async scanLegacyUploadRoots(journalArg: IAGLHomeMigrationJournal): Promise<{
    sources: string[];
    tombstones: Map<string, string>;
  }> {
    const parentStats = await plugins.fs.promises.lstat(this.legacyUploadTempDirectory);
    if (!parentStats.isDirectory() || parentStats.isSymbolicLink()) {
      throw new Error('The legacy controller upload temp directory is unsafe.');
    }
    const sources: string[] = [];
    const tombstones = new Map<string, string>();
    let ownedMatches = 0;
    const directory = await plugins.fs.promises.opendir(this.legacyUploadTempDirectory);
    for await (const entry of directory) {
      const tombstoneMatch = legacyUploadTombstonePattern.exec(entry.name);
      if (!legacyUploadRootPattern.test(entry.name) && !tombstoneMatch) continue;
      const path = plugins.path.join(this.legacyUploadTempDirectory, entry.name);
      const stats = await plugins.fs.promises.lstat(path, { bigint: true });
      if (stats.uid !== BigInt(currentUid())) continue;
      ownedMatches += 1;
      if (ownedMatches > maximumLegacyUploadRoots * 2) {
        throw new Error('The legacy controller upload temp directory has too many owned roots.');
      }
      assertOwnedNode(path, stats, 'directory', true);
      if (tombstoneMatch) {
        if (tombstoneMatch[1] !== journalArg.nonce) {
          throw new Error(`Unexpected legacy controller upload tombstone: ${path}`);
        }
        const sourceName = entry.name.slice(0, entry.name.indexOf('.agl-v23-'));
        const sourcePath = plugins.path.join(this.legacyUploadTempDirectory, sourceName);
        if (tombstones.has(sourcePath)) {
          throw new Error(`Duplicate legacy controller upload tombstone: ${path}`);
        }
        tombstones.set(sourcePath, path);
      } else {
        sources.push(path);
      }
    }
    sources.sort();
    return { sources, tombstones };
  }

  private async assertNoLegacyUploadRoots(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    const inventory = await this.scanLegacyUploadRoots(journalArg);
    if (inventory.sources.length > 0 || inventory.tombstones.size > 0) {
      throw new Error('Legacy controller upload state appeared after cleanup completed.');
    }
  }

  private async processLegacyUploadRootBinding(
    bindingArg: ILegacyUploadRootBinding,
    journalArg: IAGLHomeMigrationJournal,
  ): Promise<void> {
    const tombstonePath = this.legacyUploadTombstonePath(bindingArg, journalArg);
    const [sourceStats, tombstoneStats] = await Promise.all([
      lstatIfPresent(bindingArg.path),
      lstatIfPresent(tombstonePath),
    ]);
    if (sourceStats && tombstoneStats) {
      throw new Error(`Legacy controller upload source and tombstone both exist: ${bindingArg.path}`);
    }
    const expectedIdentity = { device: bindingArg.device, inode: bindingArg.inode };
    if (sourceStats) {
      if (!identitiesEqual(identityFromStats(sourceStats), expectedIdentity)) {
        throw new Error(`Legacy controller upload root reappeared with a new identity: ${bindingArg.path}`);
      }
      assertOwnedNode(bindingArg.path, sourceStats, 'directory', true);
      await assertSafeLegacyUploadTree(bindingArg.path, bindingArg.device);
      await this.preflight();
      await plugins.fs.promises.rename(bindingArg.path, tombstonePath);
      await syncDirectory(this.legacyUploadTempDirectory);
    } else if (tombstoneStats) {
      if (!identitiesEqual(identityFromStats(tombstoneStats), expectedIdentity)) {
        throw new Error(`Legacy controller upload tombstone identity changed: ${tombstonePath}`);
      }
      await syncDirectory(this.legacyUploadTempDirectory);
    } else {
      await syncDirectory(this.legacyUploadTempDirectory);
      return;
    }
    const movedStats = await plugins.fs.promises.lstat(tombstonePath, { bigint: true });
    if (!identitiesEqual(identityFromStats(movedStats), expectedIdentity)) {
      throw new Error(`Legacy controller upload tombstone changed before cleanup: ${tombstonePath}`);
    }
    assertOwnedNode(tombstonePath, movedStats, 'directory', true);
    await assertSafeLegacyUploadTree(tombstonePath, bindingArg.device);
    await this.preflight();
    await plugins.fs.promises.rm(tombstonePath, { recursive: true });
    await syncDirectory(this.legacyUploadTempDirectory);
  }

  private async cleanupLegacyUploadRoots(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    if (journalArg.completedOperations.includes(legacyUploadCleanupOperation)) {
      await this.assertNoLegacyUploadRoots(journalArg);
      return;
    }
    for (let attempt = 0; attempt < 4; attempt++) {
      // Old upload roots have no owner marker. Repeat the complete writer and
      // socket preflight immediately before binding and deleting them.
      await this.preflight();
      const inventory = await this.scanLegacyUploadRoots(journalArg);
      const bindingByPath = new Map(
        journalArg.legacyUploadRoots.map((bindingArg) => [bindingArg.path, bindingArg]),
      );
      for (const sourcePath of inventory.sources) {
        const sourceStats = await plugins.fs.promises.lstat(sourcePath, { bigint: true });
        const existing = bindingByPath.get(sourcePath);
        if (existing) {
          if (!identitiesEqual(identityFromStats(sourceStats), existing)) {
            throw new Error(`Legacy controller upload root reappeared with a new identity: ${sourcePath}`);
          }
          continue;
        }
        if (journalArg.legacyUploadRoots.length >= maximumLegacyUploadRoots) {
          throw new Error('The legacy controller upload root count exceeds its migration limit.');
        }
        assertOwnedNode(sourcePath, sourceStats, 'directory', true);
        await assertSafeLegacyUploadTree(sourcePath, sourceStats.dev.toString(10));
        const binding = { path: sourcePath, ...identityFromStats(sourceStats) };
        journalArg.legacyUploadRoots.push(binding);
        bindingByPath.set(sourcePath, binding);
      }
      for (const sourcePath of inventory.tombstones.keys()) {
        if (!bindingByPath.has(sourcePath)) {
          throw new Error(`Unbound legacy controller upload tombstone: ${sourcePath}`);
        }
      }
      journalArg.legacyUploadRoots.sort((leftArg, rightArg) => (
        leftArg.path < rightArg.path ? -1 : leftArg.path > rightArg.path ? 1 : 0
      ));
      await this.writeJournal(journalArg);
      for (const binding of journalArg.legacyUploadRoots) {
        await this.processLegacyUploadRootBinding(binding, journalArg);
      }
      const remaining = await this.scanLegacyUploadRoots(journalArg);
      if (remaining.sources.length === 0 && remaining.tombstones.size === 0) {
        await this.markOperation(journalArg, legacyUploadCleanupOperation);
        return;
      }
      for (const sourcePath of remaining.sources) {
        const existing = bindingByPath.get(sourcePath);
        if (!existing) continue;
        const stats = await plugins.fs.promises.lstat(sourcePath, { bigint: true });
        if (!identitiesEqual(identityFromStats(stats), existing)) {
          throw new Error(`Legacy controller upload root reappeared with a new identity: ${sourcePath}`);
        }
      }
    }
    throw new Error('Legacy controller upload roots changed repeatedly during migration.');
  }

  private async moveDirect(
    sourceArg: string,
    destinationArg: string,
    operationArg: string,
    kindArg: 'file' | 'directory',
    journalArg: IAGLHomeMigrationJournal,
  ): Promise<void> {
    const source = await lstatIfPresent(sourceArg);
    const destination = await lstatIfPresent(destinationArg);
    if (journalArg.completedOperations.includes(operationArg)) {
      if (source) {
        throw new Error(`Completed AGL migration source reappeared: ${sourceArg}`);
      }
      if (destination) {
        assertOwnedNode(destinationArg, destination, kindArg, kindArg === 'directory');
      }
      return;
    }
    if (source && destination) {
      throw new Error(`AGL migration source and destination both exist: ${sourceArg}`);
    }
    if (!source && !destination) return;
    if (source) {
      assertOwnedNode(sourceArg, source, kindArg, kindArg === 'directory');
      if (kindArg === 'directory') await assertSafeSourceTree(sourceArg);
      const parent = plugins.path.dirname(destinationArg);
      await plugins.fs.promises.mkdir(parent, { recursive: true, mode: 0o700 });
      await plugins.fs.promises.chmod(parent, 0o700);
      await plugins.fs.promises.rename(sourceArg, destinationArg);
      await syncDirectory(plugins.path.dirname(sourceArg));
      await syncDirectory(parent);
    } else {
      assertOwnedNode(destinationArg, destination!, kindArg, kindArg === 'directory');
    }
    await this.markOperation(journalArg, operationArg);
  }

  private async markOperation(
    journalArg: IAGLHomeMigrationJournal,
    operationArg: string,
  ): Promise<void> {
    if (!isKnownOperationName(operationArg)) {
      throw new Error(`Unknown AGL migration operation: ${operationArg}`);
    }
    if (journalArg.completedOperations.includes(operationArg)) return;
    journalArg.completedOperations.push(operationArg);
    journalArg.completedOperations.sort();
    await this.writeJournal(journalArg);
  }

  private async cleanupLegacyRoots(): Promise<void> {
    const credentialRoots = [
      ...(this.options.legacyPaths.legacySourceEnabled
        ? [plugins.path.join(this.options.legacyPaths.activeDataRoot, 'flex-provider-credentials')]
        : []),
      ...(this.options.legacyPaths.legacyConfigRoot
        ? [plugins.path.join(this.options.legacyPaths.legacyConfigRoot, 'flex-provider-credentials')]
        : []),
    ];
    for (const root of credentialRoots) await this.removeEmptyDirectory(root);
    if (!this.options.legacyPaths.development && this.options.legacyPaths.legacySourceEnabled) {
      await this.removeEmptyDirectory(this.options.legacyPaths.activeDataRoot);
    }
    if (this.options.legacyPaths.legacyConfigRoot) {
      await this.removeEmptyDirectory(this.options.legacyPaths.legacyConfigRoot);
    }
    if (this.options.legacyPaths.legacyStateRoot) {
      await this.removeEmptyDirectory(this.options.legacyPaths.legacyStateRoot);
    }
  }

  private async removeEmptyDirectory(pathArg: string): Promise<void> {
    const stats = await lstatIfPresent(pathArg);
    if (!stats) return;
    assertOwnedNode(pathArg, stats, 'directory');
    if ((await readBoundedDirectory(pathArg)).length !== 0) return;
    await plugins.fs.promises.rmdir(pathArg);
    await syncDirectory(plugins.path.dirname(pathArg));
  }

  private async writeJournal(journalArg: IAGLHomeMigrationJournal): Promise<void> {
    const serialized = `${JSON.stringify(journalArg)}\n`;
    if (Buffer.byteLength(serialized, 'utf8') > maximumJournalBytes) {
      throw new Error('AGL home migration journal exceeds its size limit.');
    }
    const temporary = `${this.journalPath}.${process.pid}-${plugins.crypto.randomBytes(8).toString('hex')}.tmp`;
    let handle: plugins.fs.promises.FileHandle | undefined;
    let temporaryIdentity: IFilesystemIdentity | undefined;
    try {
      handle = await plugins.fs.promises.open(
        temporary,
        plugins.fs.constants.O_WRONLY
        | plugins.fs.constants.O_CREAT
        | plugins.fs.constants.O_EXCL
        | plugins.fs.constants.O_NOFOLLOW,
        0o600,
      );
      temporaryIdentity = identityFromStats(await handle.stat({ bigint: true }));
      await handle.chmod(0o600);
      await handle.writeFile(serialized, 'utf8');
      await handle.sync();
      await handle.close();
      handle = undefined;
      await plugins.fs.promises.rename(temporary, this.journalPath);
      temporaryIdentity = undefined;
      await syncDirectory(this.options.paths.migration);
      const persisted = await readPrivateJournal(this.journalPath);
      if (!persisted || JSON.stringify(persisted) !== JSON.stringify(journalArg)) {
        throw new Error('AGL home migration journal was not persisted exactly.');
      }
    } catch (errorArg) {
      const cleanupErrors: unknown[] = [];
      if (handle) {
        try {
          await handle.close();
        } catch (cleanupErrorArg) {
          cleanupErrors.push(cleanupErrorArg);
        }
      }
      if (temporaryIdentity) {
        try {
          const stats = await lstatIfPresent(temporary);
          if (!stats || !identitiesEqual(identityFromStats(stats), temporaryIdentity)) {
            throw new Error('AGL journal temporary identity changed before cleanup.');
          }
          await plugins.fs.promises.unlink(temporary);
          await syncDirectory(this.options.paths.migration);
        } catch (cleanupErrorArg) {
          cleanupErrors.push(cleanupErrorArg);
        }
      }
      if (cleanupErrors.length > 0) {
        throw new AggregateError(
          [errorArg, ...cleanupErrors],
          'AGL journal write failed and cleanup was incomplete.',
          { cause: errorArg },
        );
      }
      throw errorArg;
    }
  }

  private async cleanupJournalTemporaryFiles(): Promise<void> {
    const migrationStats = await lstatIfPresent(this.options.paths.migration);
    if (!migrationStats) return;
    const names = (await readBoundedDirectory(this.options.paths.migration))
      .filter((name) => journalTemporaryPattern.test(name));
    if (names.length > maximumJournalTemporaryFiles) {
      throw new Error('AGL migration directory contains too many journal artifacts.');
    }
    for (const name of names) {
      const path = plugins.path.join(this.options.paths.migration, name);
      const stats = await plugins.fs.promises.lstat(path, { bigint: true });
      if (
        !stats.isFile()
        || stats.isSymbolicLink()
        || stats.uid !== BigInt(currentUid())
        || stats.nlink !== 1n
        || Number(stats.mode & 0o777n) !== 0o600
        || stats.size > BigInt(maximumJournalBytes)
      ) throw new Error(`AGL journal artifact is unsafe: ${path}`);
      const identity = identityFromStats(stats);
      const stable = await lstatIfPresent(path);
      if (!stable || !identitiesEqual(identityFromStats(stable), identity)) {
        throw new Error(`AGL journal artifact changed before cleanup: ${path}`);
      }
      await plugins.fs.promises.unlink(path);
    }
    if (names.length > 0) await syncDirectory(this.options.paths.migration);
  }

  private async unlinkExactFile(
    pathArg: string,
    identityArg: IFilesystemIdentity,
  ): Promise<void> {
    const current = await lstatIfPresent(pathArg);
    if (!current) return;
    if (!identitiesEqual(identityFromStats(current), identityArg)) {
      throw new Error(`AGL migration file identity changed before removal: ${pathArg}`);
    }
    await plugins.fs.promises.unlink(pathArg);
  }

  private async cleanupStaleLockTemporaries(): Promise<void> {
    const parent = plugins.path.dirname(this.lockPath);
    const base = plugins.path.basename(this.lockPath);
    const entries = await plugins.fs.promises.readdir(parent, { withFileTypes: true });
    const temporaryNames = entries
      .map((entry) => entry.name)
      .filter((name) => name.startsWith(`${base}.tmp-`));
    if (temporaryNames.length > maximumLockTemporaryFiles) {
      throw new Error('Too many AGL migration lock temporary artifacts exist.');
    }
    for (const name of temporaryNames) {
      const match = lockTemporaryPattern.exec(name.slice(base.length));
      if (!match) throw new Error(`Unknown AGL migration lock artifact: ${name}`);
      const uid = Number(match[1]);
      const pid = Number(match[2]);
      if (!Number.isSafeInteger(uid) || uid !== currentUid() || !Number.isSafeInteger(pid)) {
        throw new Error(`AGL migration lock temporary artifact binding is invalid: ${name}`);
      }
      const path = plugins.path.join(parent, name);
      const stats = await plugins.fs.promises.lstat(path, { bigint: true });
      if (
        !stats.isFile()
        || stats.isSymbolicLink()
        || stats.uid !== BigInt(currentUid())
        || (stats.nlink !== 1n && stats.nlink !== 2n)
        || Number(stats.mode & 0o777n) !== 0o600
        || stats.size > BigInt(maximumLockBytes)
      ) throw new Error(`AGL migration lock temporary artifact is unsafe: ${path}`);
      const identity = identityFromStats(stats);
      let owner: ILockOwner | undefined;
      try {
        owner = (await readPrivateLock(path, true))?.owner;
      } catch (errorArg) {
        const live = await readControllerProcessIdentity(pid);
        if (live) continue;
      }
      if (owner) {
        if (owner.uid !== uid || owner.pid !== pid || owner.nonce !== match[3]) {
          throw new Error(`AGL migration lock temporary artifact owner binding is invalid: ${path}`);
        }
        const live = await readControllerProcessIdentity(owner.pid);
        if (live && live.fingerprint === owner.fingerprint) continue;
      } else if (await readControllerProcessIdentity(pid)) continue;
      await this.unlinkExactFile(path, identity);
    }
    if (temporaryNames.length > 0) await syncDirectory(parent);
  }

  private async acquireLock(): Promise<{ identity: IFilesystemIdentity; owner: ILockOwner }> {
    const identity = await readControllerProcessIdentity(process.pid);
    if (!identity) throw new Error('AGL home migration process identity cannot be verified.');
    await this.cleanupStaleLockTemporaries();
    const owner: ILockOwner = {
      version: 1,
      pid: process.pid,
      uid: currentUid(),
      fingerprint: identity.fingerprint,
      nonce: plugins.crypto.randomBytes(32).toString('hex'),
    };
    const temporaryPath = `${this.lockPath}.tmp-${owner.uid}-${owner.pid}-${owner.nonce}`;
    for (let attempt = 0; attempt < 2; attempt += 1) {
      let handle: plugins.fs.promises.FileHandle | undefined;
      let temporaryIdentity: IFilesystemIdentity | undefined;
      let publishedIdentity: IFilesystemIdentity | undefined;
      try {
        handle = await plugins.fs.promises.open(
          temporaryPath,
          plugins.fs.constants.O_WRONLY
          | plugins.fs.constants.O_CREAT
          | plugins.fs.constants.O_EXCL
          | plugins.fs.constants.O_NOFOLLOW,
          0o600,
        );
      } catch (errorArg) {
        if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
      }
      if (handle) {
        try {
          temporaryIdentity = identityFromStats(await handle.stat({ bigint: true }));
          await handle.chmod(0o600);
          await handle.writeFile(`${JSON.stringify(owner)}\n`, 'utf8');
          await handle.sync();
          await handle.close();
          handle = undefined;
          const temporary = await readPrivateLock(temporaryPath);
          if (!temporary || !temporaryIdentity || !identitiesEqual(temporary.identity, temporaryIdentity)) {
            throw new Error('AGL migration lock temporary owner could not be confirmed.');
          }
          try {
            await plugins.fs.promises.link(temporaryPath, this.lockPath);
            publishedIdentity = temporaryIdentity;
          } catch (errorArg) {
            if ((errorArg as NodeJS.ErrnoException).code !== 'EEXIST') throw errorArg;
          }
          if (publishedIdentity) {
            const publishedStats = await lstatIfPresent(this.lockPath);
            if (!publishedStats || !identitiesEqual(identityFromStats(publishedStats), publishedIdentity)) {
              throw new Error('AGL migration lock publication identity could not be confirmed.');
            }
            await this.unlinkExactFile(temporaryPath, temporaryIdentity);
            await syncDirectory(plugins.path.dirname(this.lockPath));
            const published = await readPrivateLock(this.lockPath);
            if (
              !published
              || !identitiesEqual(published.identity, publishedIdentity)
              || JSON.stringify(published.owner) !== JSON.stringify(owner)
            ) throw new Error('AGL migration lock publication owner could not be confirmed.');
            return { identity: published.identity, owner };
          }
          await this.unlinkExactFile(temporaryPath, temporaryIdentity);
          await syncDirectory(plugins.path.dirname(this.lockPath));
        } catch (errorArg) {
          const cleanupErrors: unknown[] = [];
          if (handle) {
            const failedHandle = handle;
            handle = undefined;
            try {
              await failedHandle.close();
            } catch (cleanupErrorArg) {
              cleanupErrors.push(cleanupErrorArg);
            }
          }
          if (publishedIdentity) {
            try {
              await this.unlinkExactFile(this.lockPath, publishedIdentity);
              await syncDirectory(plugins.path.dirname(this.lockPath));
            } catch (cleanupErrorArg) {
              cleanupErrors.push(cleanupErrorArg);
            }
          }
          if (temporaryIdentity) {
            try {
              await this.unlinkExactFile(temporaryPath, temporaryIdentity);
              await syncDirectory(plugins.path.dirname(this.lockPath));
            } catch (cleanupErrorArg) {
              cleanupErrors.push(cleanupErrorArg);
            }
          }
          if (cleanupErrors.length > 0) {
            throw new AggregateError(
              [errorArg, ...cleanupErrors],
              'AGL migration lock acquisition failed and cleanup was incomplete.',
              { cause: errorArg },
            );
          }
          throw errorArg;
        } finally {
          if (handle) await handle.close();
        }
      }
      const existing = await readPrivateLock(this.lockPath);
      if (!existing) continue;
      const live = await readControllerProcessIdentity(existing.owner.pid);
      if (live && live.fingerprint === existing.owner.fingerprint) {
        throw new Error(`AGL home migration lock is owned by live PID ${existing.owner.pid}.`);
      }
      const stable = await readPrivateLock(this.lockPath);
      if (!stable || !identitiesEqual(stable.identity, existing.identity)) {
        throw new Error('AGL home migration lock changed during stale-owner inspection.');
      }
      await this.unlinkExactFile(this.lockPath, existing.identity);
      await syncDirectory(plugins.path.dirname(this.lockPath));
    }
    throw new Error('AGL home migration lock could not be acquired.');
  }

  private async releaseLock(lockArg: {
    identity: IFilesystemIdentity;
    owner: ILockOwner;
  }): Promise<void> {
    const current = await readPrivateLock(this.lockPath);
    if (!current || !identitiesEqual(current.identity, lockArg.identity)) {
      throw new Error('AGL home migration lock identity changed before release.');
    }
    if (JSON.stringify(current.owner) !== JSON.stringify(lockArg.owner)) {
      throw new Error('AGL home migration lock owner changed before release.');
    }
    await this.unlinkExactFile(this.lockPath, lockArg.identity);
    await syncDirectory(plugins.path.dirname(this.lockPath));
  }
}

export interface IAGLHomeDataRootMigrationOptions extends IControllerDataDirectoryOptions {
  listDataWriterProcesses?: () => Promise<readonly IControllerDataWriterProcessRecord[]>;
  legacyUploadTempDirectory?: string;
  signal?: AbortSignal;
}

const resolveDataWriterProcessLister = (
  optionsArg: IAGLHomeDataRootMigrationOptions,
): (() => Promise<readonly IControllerDataWriterProcessRecord[]>) => (
  optionsArg.listDataWriterProcesses ?? (async () => {
    const cliPath = await plugins.fs.promises.realpath(
      plugins.url.fileURLToPath(new URL('../cli.js', import.meta.url)),
    );
    return await listControllerDataWriterProcessesForCliPaths([cliPath], {
      includeInstalledPackagePaths: true,
    });
  })
);

const createAGLHomeMigrationRunner = (
  optionsArg: IAGLHomeDataRootMigrationOptions,
  listDataWriterProcessesArg: () => Promise<readonly IControllerDataWriterProcessRecord[]>,
): AGLHomeMigrationRunner => new AGLHomeMigrationRunner({
  paths: resolveAGLHomePaths(optionsArg),
  legacyPaths: resolveAGLLegacyPaths(optionsArg),
  databaseConfig: readDatabaseConfig(optionsArg),
  invokerPid: process.pid,
  listDataWriterProcesses: listDataWriterProcessesArg,
  ...(optionsArg.legacyUploadTempDirectory
    ? { legacyUploadTempDirectory: optionsArg.legacyUploadTempDirectory }
    : {}),
  ...(optionsArg.signal ? { signal: optionsArg.signal } : {}),
});

const createLegacyDataRootMigrationRunner = (
  optionsArg: IAGLHomeDataRootMigrationOptions,
  listDataWriterProcessesArg: () => Promise<readonly IControllerDataWriterProcessRecord[]>,
): ControllerDataRootMigrationRunner => {
  const legacyPaths = resolveAGLLegacyPaths(optionsArg);
  const environment = optionsArg.environment ?? process.env;
  if (legacyPaths.development || !legacyPaths.legacyConfigRoot) {
    throw new Error('Legacy installed data-root migration is unavailable in development mode.');
  }
  return new ControllerDataRootMigrationRunner({
    oldRoot: legacyPaths.legacyConfigRoot,
    newRoot: legacyPaths.activeDataRoot,
    databaseConfig: readLegacyV2DatabaseConfig(optionsArg),
    oldEmbeddedSocketPath: legacyEmbeddedDatabaseSocketPath(
      plugins.path.join(legacyPaths.legacyConfigRoot, 'smartdb'),
    ),
    newEmbeddedSocketPath: legacyEmbeddedDatabaseSocketPath(
      plugins.path.join(legacyPaths.activeDataRoot, 'smartdb'),
    ),
    invokerPid: process.pid,
    listDataWriterProcesses: listDataWriterProcessesArg,
    preserveEmbeddedDataDirectory: Boolean(environment.HARNESS_CONTROLLER_DB_DIR?.trim()),
    ...(optionsArg.signal ? { signal: optionsArg.signal } : {}),
  });
};

export const preflightAGLHomeDataRootMigration = async (
  optionsArg: IAGLHomeDataRootMigrationOptions = {},
): Promise<void> => {
  const listDataWriterProcesses = resolveDataWriterProcessLister(optionsArg);
  const homeMigration = createAGLHomeMigrationRunner(optionsArg, listDataWriterProcesses);
  await homeMigration.preflight({ allowDataWriters: true });
  const legacyPaths = resolveAGLLegacyPaths(optionsArg);
  if (!await homeMigration.hasStarted() && !legacyPaths.development) {
    await createLegacyDataRootMigrationRunner(optionsArg, listDataWriterProcesses).preflight();
  }
};

export const ensureAGLHomeDataRoot = async (
  optionsArg: IAGLHomeDataRootMigrationOptions = {},
): Promise<IControllerDataRootMigrationResult> => {
  const paths = resolveAGLHomePaths(optionsArg);
  const legacyPaths = resolveAGLLegacyPaths(optionsArg);
  const databaseConfig = readDatabaseConfig(optionsArg);
  const listDataWriterProcesses = resolveDataWriterProcessLister(optionsArg);
  const homeMigration = createAGLHomeMigrationRunner(optionsArg, listDataWriterProcesses);
  if (await homeMigration.isCommitted()) {
    await homeMigration.preflight({ allowDataWriters: true });
    return { directoryPath: paths.root, databaseConfig };
  }
  if (await homeMigration.hasStarted()) return await homeMigration.run();
  if (!legacyPaths.development) {
    await createLegacyDataRootMigrationRunner(optionsArg, listDataWriterProcesses).run();
  }
  const result = await homeMigration.run();
  return { directoryPath: paths.root, databaseConfig: result.databaseConfig ?? databaseConfig };
};