cli.ts

import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { spawn } from "node:child_process";
import { fileURLToPath } from "node:url";
import YAML from "yaml";
import { runBoundedCommand, sshTransportArgs } from "./lib/process.js";
import {
  decideAutoscale,
  decideWebhookAutoscale,
  type AutoscaleDecision
} from "./lib/autoscale.js";
import {
  createAutoscaleWebhookServer,
  type AutoscaleWebhookDecision
} from "./lib/autoscale-webhook.js";
import { collectConfigWarnings, loadConfig, type ResolvedConfig } from "./lib/config.js";
import { renderCompose } from "./lib/compose.js";
import {
  auditLogFileFromEnv,
  auditMaxSizeBytesFromEnv,
  readJsonFromStdin,
  writeAuditRecord
} from "./lib/audit.js";
import {
  drainRunnerPool,
  type DrainProgress,
  type DrainReport
} from "./lib/drain.js";
import {
  pruneStaleRunners,
  type PruneStaleRunnersReport
} from "./lib/prune.js";
import { loadDeploymentEnv } from "./lib/env.js";
import { loadLinuxDockerConfig } from "./lib/linux-docker-config.js";
import {
  buildLinuxDockerInstallPlan,
  summarizeLinuxDockerInstallPlan
} from "./lib/linux-docker-install.js";
import { renderLinuxDockerCompose } from "./lib/linux-docker-compose.js";
import {
  buildLinuxDockerStatusReport,
  formatLinuxDockerStatusText,
  saveLinuxDockerResult
} from "./lib/linux-docker-status.js";
import { loadWindowsDockerConfig } from "./lib/windows-config.js";
import {
  buildWindowsDockerInstallPlan,
  summarizeWindowsDockerInstallPlan
} from "./lib/windows-install.js";
import { renderWindowsDockerCompose } from "./lib/windows-compose.js";
import {
  loadLumeConfig,
  lumeRunnerGroupExpectations,
  renderLumeShellExports
} from "./lib/lume-config.js";
import {
  buildLumeProjectResult,
  defaultLumeProjectLogFile,
  defaultLumeProjectPidFile,
  defaultLumeProjectResultPath,
  formatLumeProjectResultText,
  saveLumeProjectResult,
  type LumeProjectResult
} from "./lib/lume-project.js";
import { renderDoctorReport, runDoctor, type DoctorMode } from "./lib/doctor.js";
import {
  collectGitHubActualRunnerState,
  collectGitHubActualPoolState,
  compareDesiredActualRunners,
  compareDesiredActualPools,
  desiredPoolsFromConfig,
  type ConfigDiffReport,
  type DesiredRunnerState,
  type DriftReport
} from "./lib/drift.js";
import {
  buildRegistrationTokenRequest,
  fetchOrganizationRunnerGroups,
  fetchOrganizationRunners,
  fetchLatestRunnerRelease,
  fetchRunnerToken,
  getQueuedJobCount,
  resolveGitHubAccessToken,
  verifyContainerImageTag,
  verifyRunnerGroups
} from "./lib/github.js";
import {
  buildRunnerDownloadUrl,
  runnerReleaseAgeDays,
  summarizeRunnerVersion
} from "./lib/runner-version.js";
import {
  inspectRunnerGroupAccess,
  reconcileRunnerGroupAccess,
  type RunnerGroupAccessExpectation
} from "./lib/runner-group-access.js";
import {
  decideLinuxReconcile,
  emptyLinuxReconcileState,
  parseLinuxReconcileState,
  type LinuxReconcilePlane,
  type LinuxReconcileState
} from "./lib/reconcile.js";
import {
  buildSynologyInstallPlan,
  summarizeSynologyInstallPlan
} from "./lib/synology-install.js";
import {
  buildSynologyStatusReport,
  formatSynologyStatusText,
  saveSynologyResult
} from "./lib/synology-status.js";
import { log, type LogFields, type LogLevel } from "./lib/logger.js";
import { terminateTrackedProcess } from "./lib/process-lifecycle.js";

export async function main(
  commandLineArgs = process.argv.slice(2)
): Promise<void> {
  const [command, ...args] = commandLineArgs;

  switch (command) {
    case "validate-config":
      await validateConfig(args);
      break;
    case "doctor":
      await doctorCommand(args);
      break;
    case "synology-status":
      await synologyStatusCommand(args);
      break;
    case "linux-docker-status":
      await linuxDockerStatusCommand(args);
      break;
    case "drift-detect":
      await driftDetectCommand(args);
      break;
    case "config-diff":
      await configDiffCommand(args);
      break;
    case "audit-log":
      await auditLogCommand(args);
      break;
    case "scale":
      await scaleCommand(args);
      break;
    case "autoscale-webhook":
      await autoscaleWebhookCommand(args);
      break;
    case "drain-pool":
      await drainPoolCommand(args);
      break;
    case "reconcile-linux-pool":
      await reconcileLinuxPoolCommand(args);
      break;
    case "prune-stale-runners":
      await pruneStaleRunnersCommand(args);
      break;
    case "rotate-token":
      await rotateTokenCommand(args);
      break;
    case "validate-linux-docker-config":
      await validateLinuxDockerConfig(args);
      break;
    case "validate-linux-docker-github":
      await validateLinuxDockerGitHub(args);
      break;
    case "validate-windows-config":
      await validateWindowsDockerConfig(args);
      break;
    case "validate-windows-github":
      await validateWindowsDockerGitHub(args);
      break;
    case "validate-github":
      await validateGitHub(args);
      break;
    case "reconcile-github-access":
      await reconcileGitHubAccess(args);
      break;
    case "validate-image":
      await validateImage(args);
      break;
    case "render-linux-docker-compose":
      await renderLinuxDockerComposeCommand(args);
      break;
    case "render-linux-docker-project-manifest":
      await renderLinuxDockerProjectManifest(args);
      break;
    case "render-windows-compose":
      await renderWindowsDockerComposeCommand(args);
      break;
    case "render-windows-project-manifest":
      await renderWindowsDockerProjectManifest(args);
      break;
    case "render-compose":
      await renderComposeCommand(args);
      break;
    case "render-synology-project-manifest":
      await renderSynologyProjectManifest(args);
      break;
    case "install-linux-docker-project":
      await installLinuxDockerProject(args);
      break;
    case "install-synology-project":
      await installSynologyProject(args);
      break;
    case "teardown-linux-docker-project":
      await teardownLinuxDockerProject(args);
      break;
    case "install-windows-project":
      await installWindowsDockerProject(args);
      break;
    case "teardown-windows-project":
      await teardownWindowsDockerProject(args);
      break;
    case "teardown-synology-project":
      await teardownSynologyProject(args);
      break;
    case "check-runner-version":
      await checkRunnerVersion(args);
      break;
    case "runner-release-manifest":
      await runnerReleaseManifest(args);
      break;
    case "validate-lume-config":
      await validateLumeConfig(args);
      break;
    case "validate-lume-github":
      await validateLumeGitHub(args);
      break;
    case "render-lume-runner-manifest":
      await renderLumeRunnerManifest(args);
      break;
    case "lume-queued-jobs":
      await lumeQueuedJobs(args);
      break;
    case "install-lume-project":
      await installLumeProject(args);
      break;
    case "teardown-lume-project":
      await teardownLumeProject(args);
      break;
    default:
      printUsage();
      process.exitCode = 1;
  }
}

async function validateConfig(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);

  process.stdout.write(
    JSON.stringify(
      {
        version: config.version,
        image: config.image,
        pools: config.pools.map((pool) => ({
          key: pool.key,
          runnerGroup: pool.runnerGroup,
          visibility: pool.visibility,
          labels: pool.labels,
          size: pool.size,
          scaling: pool.scaling,
          architecture: pool.architecture,
          runnerRoot: pool.runnerRoot
        }))
      },
      null,
      2
    )
  );
}

async function doctorCommand(args: string[]): Promise<void> {
  const mode = getDoctorMode(args);
  const format = getOption(args, "--format", "text");
  if (format !== "text" && format !== "json") {
    throw new Error(`unknown doctor format: ${format}`);
  }
  const report = await runDoctor({
    mode,
    envPath: getOption(args, "--env", ".env"),
    configPath: getOption(args, "--config", "config/pools.yaml"),
    linuxConfigPath: getOption(
      args,
      "--linux-config",
      getOption(args, "--linux-docker-config", "config/linux-docker-runners.yaml")
    ),
    windowsConfigPath: getOption(args, "--windows-config", "config/windows-runners.yaml"),
    lumeConfigPath: getOption(args, "--lume-config", "config/lume-runners.yaml")
  });

  if (format === "json") {
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
    if (!report.ok) {
      process.exitCode = 1;
    }
    return;
  }

  process.stdout.write(renderDoctorReport(report));
  if (!report.ok) {
    process.exitCode = 1;
  }
}

async function synologyStatusCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const format = getOption(args, "--format", "text");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const compose = renderCompose(config, env);
  const report = buildSynologyStatusReport({
    config,
    env,
    composeContent: compose,
    savedResultPath: getOption(args, "--result")
  });

  if (format === "json") {
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
  } else if (format === "text") {
    process.stdout.write(formatSynologyStatusText(report));
  } else {
    throw new Error(`unknown synology-status format: ${format}`);
  }

  if (!report.ok) {
    process.exitCode = 1;
  }
}

async function linuxDockerStatusCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const format = getOption(args, "--format", "text");
  const config = loadLinuxDockerConfig(configPath!, env);
  const compose = renderLinuxDockerCompose(config, env);
  const report = buildLinuxDockerStatusReport({
    config,
    env,
    composeContent: compose,
    savedResultPath: getOption(args, "--result")
  });

  if (format === "json") {
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
  } else if (format === "text") {
    process.stdout.write(formatLinuxDockerStatusText(report));
  } else {
    throw new Error(`unknown linux-docker-status format: ${format}`);
  }

  if (!report.ok) {
    process.exitCode = 1;
  }
}

async function driftDetectCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const threshold = parseNonNegativeInteger(
    getOption(args, "--threshold", env.raw.DRIFT_THRESHOLD ?? "0")!,
    "--threshold"
  );
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const desiredPools = desiredPoolsFromConfig(config.pools);
  const token = await resolveGitHubAccessToken(env);
  const actualPools = await collectGitHubActualPoolState(
    env.githubApiUrl,
    token,
    desiredPools
  );
  const report = compareDesiredActualPools(
    desiredPools,
    actualPools,
    threshold
  );

  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
  if (report.drifted) {
    writeDriftNotification(
      report,
      env.raw.DRIFT_NOTIFY_CHANNEL,
      env.raw.GITHUB_STEP_SUMMARY
    );
    process.exitCode = 1;
  }
}

async function configDiffCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const format = getOption(args, "--format", "text")!;
  if (format !== "text" && format !== "json") {
    throw new Error(`unknown config-diff format: ${format}`);
  }

  const plane = getOption(args, "--plane") as DrainPlane | undefined;
  if (
    plane &&
    !["synology", "linux-docker", "windows-docker", "lume"].includes(plane)
  ) {
    throw new Error(`unknown config-diff plane: ${plane}`);
  }

  const desiredRunners = collectConfigDiffDesiredRunners(args, env, plane);
  const token = await resolveGitHubAccessToken(env);
  const actualRunners = await collectGitHubActualRunnerState(
    env.githubApiUrl,
    token,
    desiredRunners
  );
  const report = compareDesiredActualRunners(desiredRunners, actualRunners);

  process.stdout.write(
    format === "json"
      ? `${JSON.stringify(report, null, 2)}\n`
      : renderConfigDiffReport(report)
  );

  if (!report.inSync) {
    process.exitCode = 1;
  }
}

async function pruneStaleRunnersCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const format = getOption(args, "--format", "text")!;
  if (format !== "text" && format !== "json") {
    throw new Error(`unknown prune-stale-runners format: ${format}`);
  }

  const plane = getOption(args, "--plane") as DrainPlane | undefined;
  if (
    plane &&
    !["synology", "linux-docker", "windows-docker", "lume"].includes(plane)
  ) {
    throw new Error(`unknown prune-stale-runners plane: ${plane}`);
  }

  const report = await pruneStaleRunners({
    apiUrl: env.githubApiUrl,
    token: await resolveGitHubAccessToken(env),
    pools: collectDrainPoolDefinitions(args, env, plane),
    apply: args.includes("--apply")
  });

  process.stdout.write(
    format === "json"
      ? `${JSON.stringify(report, null, 2)}\n`
      : renderPruneStaleRunnersReport(report)
  );
}

async function rotateTokenCommand(args: string[]): Promise<void> {
  if (args.includes("--apply") && args.includes("--dry-run")) {
    throw new Error("pass either --apply or --dry-run, not both");
  }

  const apply = args.includes("--apply");
  const dryRun = !apply;
  const envPath = getOption(args, "--env", ".env")!;
  const env = loadDeploymentEnv({
    envPath,
    requirePat: apply
  });
  const newTokenEnv = resolveNewTokenEnvName(args);
  const newToken =
    process.env[newTokenEnv]?.trim() || env.raw[newTokenEnv]?.trim();
  if (!newToken) {
    throw new Error(
      `${newTokenEnv} is required; export the replacement PAT and pass --new-token-env if you use a different variable`
    );
  }
  if (env.githubPat && newToken === env.githubPat) {
    throw new Error(`${newTokenEnv} must differ from GITHUB_PAT`);
  }

  const plane = getRotationPlane(args);
  const poolFilter = getOption(args, "--pool");
  const definitions = collectTokenRotationDefinitions(args, env, plane).filter(
    (definition) => !poolFilter || definition.key === poolFilter
  );
  if (definitions.length === 0) {
    throw new Error(poolFilter ? `unknown pool: ${poolFilter}` : "no runner pools found");
  }

  const actionFields = {
    command: "rotate-token",
    action: "rotate-token",
    plane: plane ?? "all",
    pool: poolFilter ?? "all",
    dryRun
  };
  const report = await withControllerAction(actionFields, async () => {
    const runnerGroups = await verifyRunnerGroups(
      env.githubApiUrl,
      newToken,
      definitions.map((definition) => ({
        poolKey: definition.key,
        organization: definition.organization,
        runnerGroup: definition.runnerGroup
      }))
    );
    const validatedOrganizations = await validateRegistrationTokenScopes(
      env.githubApiUrl,
      newToken,
      definitions
    );
    const plan = buildTokenRotationPlan(dryRun, newTokenEnv, definitions, {
      runnerGroups,
      validatedOrganizations
    });

    if (dryRun) {
      return {
        ...plan,
        drains: []
      };
    }

    const timeoutSeconds = parseDurationSeconds(
      getOption(args, "--drain-timeout", getOption(args, "--timeout", "300"))!,
      "--drain-timeout"
    );
    const intervalSeconds = parseDurationSeconds(
      getOption(args, "--drain-interval", getOption(args, "--interval", "5"))!,
      "--drain-interval"
    );
    const drains: DrainReport[] = [];

    for (const definition of definitions.filter(
      (entry) => entry.plane !== "lume"
    )) {
      const drainReport = await drainRunnerPool({
        apiUrl: env.githubApiUrl,
        token: env.githubPat!,
        organization: definition.organization,
        runnerGroup: definition.runnerGroup,
        poolKey: definition.key,
        runnerNames: definition.runnerNames,
        timeoutSeconds,
        intervalSeconds,
        onProgress: (progress) => writeDrainProgress(definition.plane, progress)
      });
      drains.push(drainReport);
      if (drainReport.status === "timeout") {
        throw new Error(
          `timed out waiting for ${drainReport.busy.join(", ")} to become idle before rotating ${definition.key}`
        );
      }
    }

    await withPatOverride(newToken, async () => {
      if (definitions.some((definition) => definition.plane === "synology")) {
        const rotatedEnv = loadDeploymentEnv({ envPath, requirePat: true });
        const configPath = getOption(args, "--config", "config/pools.yaml")!;
        const config = loadConfig(configPath, rotatedEnv);
        emitWarnings(config);
        const compose = renderCompose(config, rotatedEnv);
        const installPlan = buildSynologyInstallPlan(config, rotatedEnv, compose, {
          action: "up"
        });
        assertGeneratedPatRotation("Synology", installPlan.envFileContent, newToken);
        runSynologyInstallPlan(installPlan, getOption(args, "--python", "python3")!);
      }

      if (definitions.some((definition) => definition.plane === "linux-docker")) {
        const rotatedEnv = loadDeploymentEnv({ envPath, requirePat: true });
        const configPath = getOption(
          args,
          "--linux-config",
          "config/linux-docker-runners.yaml"
        )!;
        const config = loadLinuxDockerConfig(configPath, rotatedEnv);
        const compose = renderLinuxDockerCompose(config, rotatedEnv);
        const installPlan = buildLinuxDockerInstallPlan(config, rotatedEnv, compose, {
          action: "up"
        });
        assertGeneratedPatRotation("Linux Docker", installPlan.envFileContent, newToken);
        runLinuxDockerInstall(installPlan);
      }
    });

    writeTokenRotationAudit(definitions);
    return {
      ...plan,
      drains
    };
  }, (report) => ({
    pools: report.pools.length,
    runners: report.pools.reduce((count, pool) => count + pool.runnerNames.length, 0),
    validatedOrganizations: report.validation.registrationTokenOrganizations.length,
    drains: report.drains.length
  }));

  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
}

async function auditLogCommand(args: string[]): Promise<void> {
  const filePath = getOption(args, "--file", auditLogFileFromEnv());
  const maxSizeOption = getOption(args, "--max-size-bytes");
  const maxSizeBytes = maxSizeOption
    ? parsePositiveInteger(maxSizeOption, "--max-size-bytes")
    : auditMaxSizeBytesFromEnv();
  const record = writeAuditRecord(await readJsonFromStdin(), {
    filePath,
    maxSizeBytes
  });

  process.stdout.write(`${JSON.stringify(record)}\n`);
}

async function scaleCommand(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/pools.yaml")!;
  const poolFilter = getOption(args, "--pool");
  const config = loadConfig(configPath, env);
  emitWarnings(config);
  const cooldownElapsedSeconds = getConfigAgeSeconds(configPath);
  const pools = poolFilter
    ? config.pools.filter((pool) => pool.key === poolFilter)
    : config.pools;

  if (poolFilter && pools.length === 0) {
    throw new Error(`unknown pool: ${poolFilter}`);
  }

  const actionFields = {
    command: "scale",
    action: "autoscale",
    plane: "synology",
    pool: poolFilter ?? "all",
    dryRun
  };
  const report = await withControllerAction(actionFields, async () => {
    const decisions: AutoscaleDecision[] = [];
    const token = await resolveGitHubAccessToken(env);
    for (const pool of pools) {
      const queuedJobs = await getQueuedJobCount(env.githubApiUrl, token, {
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        repositories:
          pool.repositoryAccess === "selected" ? pool.allowedRepositories : [],
        labels: pool.labels
      });
      decisions.push(
        decideAutoscale({
          poolKey: pool.key,
          currentSize: pool.size,
          queuedJobs,
          scaling: pool.scaling,
          cooldownElapsedSeconds
        })
      );
    }

    const report = {
      dryRun,
      cooldownElapsedSeconds,
      pools: decisions,
      drains: [] as DrainReport[]
    };

    if (dryRun || decisions.every((decision) => decision.action === "none")) {
      return report;
    }

    const drainTimeoutSeconds = parseDurationSeconds(
      getOption(args, "--drain-timeout", "300")!,
      "--drain-timeout"
    );
    const drainIntervalSeconds = parseDurationSeconds(
      getOption(args, "--drain-interval", "5")!,
      "--drain-interval"
    );

    for (const decision of decisions.filter(
      (entry) => entry.action === "scale-down"
    )) {
      const pool = config.pools.find((entry) => entry.key === decision.poolKey)!;
      const drainReport = await drainRunnerPool({
        apiUrl: env.githubApiUrl,
        token,
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        poolKey: pool.key,
        runnerNames: buildIndexedRunnerNames(
          pool.key,
          decision.targetSize + 1,
          pool.size
        ),
        timeoutSeconds: drainTimeoutSeconds,
        intervalSeconds: drainIntervalSeconds,
        onProgress: (progress) => writeDrainProgress("synology", progress)
      });
      report.drains.push(drainReport);
      if (drainReport.status === "timeout") {
        throw new Error(
          `timed out waiting for ${drainReport.busy.join(", ")} to become idle before scaling ${pool.key} down`
        );
      }
    }

    const scaledConfig = applyAutoscaleDecisions(config, decisions);
    const compose = renderCompose(scaledConfig, env);
    const plan = buildSynologyInstallPlan(scaledConfig, env, compose, {
      action: "up"
    });
    runSynologyInstallPlan(plan, getOption(args, "--python", "python3")!);
    writeScaledPoolSizes(configPath, decisions);
    return report;
  }, (report) => ({
    decisionCount: report.pools.length,
    scaleUp: report.pools.filter((decision) => decision.action === "scale-up").length,
    scaleDown: report.pools.filter((decision) => decision.action === "scale-down").length,
    drains: report.drains.length
  }));

  if (dryRun || report.pools.every((decision) => decision.action === "none")) {
    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
    return;
  }
  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
}

async function autoscaleWebhookCommand(args: string[]): Promise<void> {
  const listen = getOption(args, "--listen", ":8080")!;
  const envPath = getOption(args, "--env", ".env")!;
  const configPath = getOption(args, "--config", "config/pools.yaml")!;
  const env = loadDeploymentEnv({ envPath, requirePat: false, requireGitHubAuth: true });
  const secretEnv = getOption(args, "--secret-env", "AUTOSCALE_WEBHOOK_SECRET")!;
  const secret = env.raw[secretEnv]?.trim();
  if (!secret) {
    throw new Error(`${secretEnv} is required`);
  }
  const config = loadConfig(configPath, env);
  const routes = config.pools.map((pool) => ({
    poolKey: pool.key,
    labels: ["self-hosted", ...pool.labels]
  }));
  const statePath = getOption(args, "--state", env.raw.AUTOSCALE_WEBHOOK_STATE_FILE);
  if (!statePath) {
    throw new Error("AUTOSCALE_WEBHOOK_STATE_FILE or --state is required for durable delivery deduplication");
  }
  const { host, port } = parseListenAddress(listen);
  let actuationQueue = Promise.resolve();
  const server = createAutoscaleWebhookServer({
    secret,
    routes,
    statePath,
    onDecision: async (decision) => {
      const actuation = actuationQueue.then(() =>
        actuateAutoscaleWebhookDecision({
          decision,
          args,
          envPath,
          configPath
        })
      );
      actuationQueue = actuation.catch(() => undefined);
      await actuation;
    }
  });
  await new Promise<void>((resolve) => {
    server.listen(port, host, resolve);
  });
  process.stdout.write(`autoscale webhook listening on ${host}:${port}\n`);
}

async function actuateAutoscaleWebhookDecision(input: {
  decision: AutoscaleWebhookDecision;
  args: string[];
  envPath: string;
  configPath: string;
}): Promise<void> {
  const event = input.decision.event;
  if (!event || input.decision.signal === "none") return;

  const env = loadDeploymentEnv({
    envPath: input.envPath,
    requirePat: false,
    requireGitHubAuth: true
  });
  const config = loadConfig(input.configPath, env);
  const pool = config.pools.find((entry) => entry.key === event.poolKey);
  if (!pool) {
    throw new Error(`webhook selected unknown pool ${event.poolKey}`);
  }
  if (!pool.scaling) {
    log.info("ignored autoscale webhook for pool without scaling config", {
      pool: pool.key,
      jobId: event.jobId,
      signal: input.decision.signal
    });
    return;
  }

  const token = await resolveGitHubAccessToken(env);
  const queuedJobs = input.decision.signal === "scale-up"
    ? pool.scaling.queueThreshold
    : await getQueuedJobCount(env.githubApiUrl, token, {
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        repositories:
          pool.repositoryAccess === "selected" ? pool.allowedRepositories : [],
        labels: pool.labels
      });
  const autoscaleDecision = decideWebhookAutoscale({
    signal: input.decision.signal,
    poolKey: pool.key,
    currentSize: pool.size,
    scaling: pool.scaling,
    cooldownElapsedSeconds: getConfigAgeSeconds(input.configPath),
    queuedJobs
  });
  if (autoscaleDecision.action === "none") {
    log.info("autoscale webhook converged without capacity change", {
      pool: pool.key,
      jobId: event.jobId,
      reason: autoscaleDecision.reason
    });
    return;
  }

  await withControllerAction({
    command: "autoscale-webhook",
    action: autoscaleDecision.action,
    plane: "synology",
    pool: pool.key,
    dryRun: false
  }, async () => {
    if (autoscaleDecision.action === "scale-down") {
      const drainReport = await drainRunnerPool({
        apiUrl: env.githubApiUrl,
        token,
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        poolKey: pool.key,
        runnerNames: buildIndexedRunnerNames(
          pool.key,
          autoscaleDecision.targetSize + 1,
          pool.size
        ),
        timeoutSeconds: parseDurationSeconds(
          getOption(input.args, "--drain-timeout", "300")!,
          "--drain-timeout"
        ),
        intervalSeconds: parseDurationSeconds(
          getOption(input.args, "--drain-interval", "5")!,
          "--drain-interval"
        ),
        onProgress: (progress) => writeDrainProgress("synology", progress)
      });
      if (drainReport.status === "timeout") {
        throw new Error(
          `timed out draining ${pool.key} after workflow_job ${event.jobId}`
        );
      }
    }

    const scaledConfig = applyAutoscaleDecisions(config, [autoscaleDecision]);
    const compose = renderCompose(scaledConfig, env);
    const plan = buildSynologyInstallPlan(scaledConfig, env, compose, {
      action: "up"
    });
    runSynologyInstallPlan(plan, getOption(input.args, "--python", "python3")!);
    writeScaledPoolSizes(input.configPath, [autoscaleDecision]);
  }, () => ({
    jobId: event.jobId,
    deliveryAction: event.action,
    targetSize: autoscaleDecision.targetSize,
    queuedJobs
  }));
}

async function drainPoolCommand(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const poolKey = getOption(args, "--pool");
  if (!poolKey) {
    throw new Error("--pool is required");
  }

  const format = getOption(args, "--format", "text");
  if (format !== "text" && format !== "json") {
    throw new Error(`unknown drain format: ${format}`);
  }

  const definition = resolveDrainPoolDefinition(args, env, poolKey);
  const report = await withControllerAction(
    {
      command: "drain-pool",
      action: "drain",
      plane: definition.plane,
      pool: definition.key
    },
    async () =>
      drainRunnerPool({
        apiUrl: env.githubApiUrl,
        token: await resolveGitHubAccessToken(env),
        organization: definition.organization,
        runnerGroup: definition.runnerGroup,
        poolKey: definition.key,
        runnerNames: definition.runnerNames,
        timeoutSeconds: parseDurationSeconds(getOption(args, "--timeout", "300")!, "--timeout"),
        intervalSeconds: parseDurationSeconds(getOption(args, "--interval", "5")!, "--interval"),
        onProgress: (progress) => writeDrainProgress(definition.plane, progress)
      }),
    (report) => ({
      drainStatus: report.status,
      total: report.total,
      cordoned: report.cordoned.length,
      busy: report.busy.length,
      missing: report.missing.length
    })
  );

  if (format === "json") {
    process.stdout.write(`${JSON.stringify({ ...report, plane: definition.plane }, null, 2)}\n`);
  } else {
    process.stdout.write(renderDrainReport(definition.plane, report));
  }

  if (report.status === "timeout") {
    process.exitCode = 1;
  }
}

async function reconcileLinuxPoolCommand(args: string[]): Promise<void> {
  const requestedPlane = getOption(args, "--plane", "both");
  const planes: LinuxReconcilePlane[] =
    requestedPlane === "both"
      ? ["synology", "linux-docker"]
      : requestedPlane === "synology" || requestedPlane === "linux-docker"
        ? [requestedPlane]
        : (() => {
            throw new Error(`unknown reconcile plane: ${requestedPlane}`);
          })();
  const format = getOption(args, "--format", "text");
  if (format !== "text" && format !== "json") {
    throw new Error(`unknown reconcile format: ${format}`);
  }

  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const statePath = path.resolve(
    getOption(
      args,
      "--state",
      process.env.RUNNER_RECONCILE_STATE_FILE ??
        path.join(os.homedir(), ".local", "state", "github-runner-fleet", "reconcile.json")
    )!
  );
  const lockPath = path.resolve(
    getOption(args, "--lock", `${statePath}.lock`)!
  );
  const dryRun = args.includes("--dry-run");
  const force = args.includes("--force");

  const results = await withReconcileLock(lockPath, async () => {
    const state = readLinuxReconcileState(statePath);
    const token = await resolveGitHubAccessToken(env);
    const nextState: LinuxReconcileState = {
      version: 1,
      planes: { ...state.planes }
    };
    const reports: Array<Record<string, unknown>> = [];

    for (const plane of planes) {
      const configPath =
        plane === "synology"
          ? getOption(args, "--config", "config/pools.yaml")!
          : getOption(args, "--linux-config", "config/linux-docker-runners.yaml")!;
      const imageRef = readLinuxPlaneImageRef(plane, configPath, env);
      const verified = await verifyContainerImageTag(
        env.githubApiUrl,
        token,
        imageRef
      );
      const decision = decideLinuxReconcile({
        current: state.planes[plane],
        desiredImageRef: imageRef,
        verifiedVersionId: verified.versionId,
        force
      });
      const report: Record<string, unknown> = {
        plane,
        imageRef,
        versionId: verified.versionId,
        decision: decision.action,
        reason: decision.reason,
        dryRun
      };

      if (decision.action === "apply" && !dryRun) {
        await withControllerAction(
          {
            command: "reconcile-linux-pool",
            action: "reconcile",
            plane,
            pool: "all"
          },
          async () => {
            const definitions = collectDrainPoolDefinitions(
              [...args, "--plane", plane],
              env,
              plane
            );
            const timeoutSeconds = parseDurationSeconds(
              getOption(args, "--timeout", "15m")!,
              "--timeout"
            );
            const intervalSeconds = parseDurationSeconds(
              getOption(args, "--interval", "5")!,
              "--interval"
            );
            for (const definition of definitions) {
              const drain = await drainRunnerPool({
                apiUrl: env.githubApiUrl,
                token,
                organization: definition.organization,
                runnerGroup: definition.runnerGroup,
                poolKey: definition.key,
                runnerNames: definition.runnerNames,
                timeoutSeconds,
                intervalSeconds,
                onProgress: (progress) => writeDrainProgress(plane, progress)
              });
              if (drain.status === "timeout") {
                throw new Error(
                  `timed out draining ${plane}/${definition.key}: ${drain.busy.join(", ") || "busy runners remain"}`
                );
              }
            }

            runLinuxReconcileInstall(plane, args, env);
          },
          () => ({ imageRef, versionId: verified.versionId })
        );

        nextState.planes[plane] = {
          imageRef,
          versionId: verified.versionId,
          reconciledAt: new Date().toISOString()
        };
        writeLinuxReconcileState(statePath, nextState);
        report.status = "applied";
      } else {
        report.status = decision.action === "skip" ? "current" : "would-apply";
      }

      reports.push(report);
    }

    return reports;
  });

  if (format === "json") {
    process.stdout.write(`${JSON.stringify({ statePath, results }, null, 2)}\n`);
    return;
  }

  process.stdout.write(
    `${results
      .map(
        (result) =>
          `reconcile ${String(result.plane)} image=${String(result.imageRef)} status=${String(result.status)} reason=${String(result.reason)}`
      )
      .join("\n")}\n`
  );
}

function readLinuxPlaneImageRef(
  plane: LinuxReconcilePlane,
  configPath: string,
  env: ReturnType<typeof loadDeploymentEnv>
): string {
  if (plane === "synology") {
    const config = loadConfig(configPath, env);
    return `${config.image.repository}:${config.image.tag}`;
  }
  const config = loadLinuxDockerConfig(configPath, env);
  return `${config.image.repository}:${config.image.tag}`;
}

function runLinuxReconcileInstall(
  plane: LinuxReconcilePlane,
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>
): void {
  const installEnv = {
    ...env,
    synologyInstallPullImages: true,
    synologyInstallForceRecreate: true,
    synologyInstallRemoveOrphans: true,
    linuxDockerInstallPullImages: true,
    linuxDockerInstallForceRecreate: true,
    linuxDockerInstallRemoveOrphans: true
  };

  if (plane === "synology") {
    const config = loadConfig(
      getOption(args, "--config", "config/pools.yaml")!,
      installEnv
    );
    emitWarnings(config);
    const plan = buildSynologyInstallPlan(
      config,
      installEnv,
      renderCompose(config, installEnv),
      { action: "up" }
    );
    runSynologyInstallPlan(plan, getOption(args, "--python", "python3")!);
    return;
  }

  const config = loadLinuxDockerConfig(
    getOption(args, "--linux-config", "config/linux-docker-runners.yaml")!,
    installEnv
  );
  const plan = buildLinuxDockerInstallPlan(
    config,
    installEnv,
    renderLinuxDockerCompose(config, installEnv),
    { action: "up" }
  );
  runLinuxDockerInstall(plan);
}

function readLinuxReconcileState(statePath: string): LinuxReconcileState {
  if (!fs.existsSync(statePath)) {
    return emptyLinuxReconcileState();
  }
  return parseLinuxReconcileState(
    JSON.parse(fs.readFileSync(statePath, "utf8")) as unknown
  );
}

function writeLinuxReconcileState(
  statePath: string,
  state: LinuxReconcileState
): void {
  fs.mkdirSync(path.dirname(statePath), { recursive: true });
  const tempPath = `${statePath}.${process.pid}.tmp`;
  fs.writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, "utf8");
  fs.renameSync(tempPath, statePath);
}

async function withReconcileLock<T>(
  lockPath: string,
  callback: () => T | Promise<T>
): Promise<Awaited<T>> {
  fs.mkdirSync(path.dirname(lockPath), { recursive: true });
  if (fs.existsSync(lockPath)) {
    const ownerPath = path.join(lockPath, "owner");
    const owner = fs.existsSync(ownerPath)
      ? Number.parseInt(fs.readFileSync(ownerPath, "utf8").trim(), 10)
      : undefined;
    if (owner && isProcessRunning(owner)) {
      throw new Error(`reconcile already running under pid ${owner}`);
    }
    fs.rmSync(lockPath, { recursive: true, force: true });
  }

  fs.mkdirSync(lockPath, { recursive: false });
  fs.writeFileSync(path.join(lockPath, "owner"), `${process.pid}\n`, "utf8");
  try {
    return await callback();
  } finally {
    fs.rmSync(lockPath, { recursive: true, force: true });
  }
}

function writeDriftNotification(
  report: DriftReport,
  channel: string | undefined,
  stepSummaryPath: string | undefined
): void {
  const normalizedChannel = channel?.trim();
  if (!normalizedChannel) {
    return;
  }

  if (!stepSummaryPath) {
    process.stderr.write(
      "DRIFT_NOTIFY_CHANNEL is set, but GITHUB_STEP_SUMMARY is unavailable; no drift notification was written.\n"
    );
    return;
  }

  const driftedPools = report.pools.filter((pool) => pool.status !== "ok");
  const rows = driftedPools
    .map(
      (pool) =>
        `| ${pool.name} | ${pool.desired} | ${pool.actual} | ${pool.drift} | ${pool.status} |`
    )
    .join("\n");
  fs.appendFileSync(
    stepSummaryPath,
    [
      "## Runner Pool Drift Detected",
      "",
      "Notification channel configured.",
      "",
      "| Pool | Desired | Actual | Drift | Status |",
      "| --- | ---: | ---: | ---: | --- |",
      rows,
      ""
    ].join("\n"),
    "utf8"
  );
}

async function renderComposeCommand(args: string[]): Promise<void> {
  const output = getOption(args, "--output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const compose = renderCompose(config, env);

  if (output) {
    fs.writeFileSync(path.resolve(output), `${compose}\n`, "utf8");
    process.stdout.write(`${output}\n`);
    return;
  }

  process.stdout.write(`${compose}\n`);
}

async function validateGitHub(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);

  const pools = await inspectRunnerGroupAccess(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    runnerGroupAccessExpectations(config)
  );
  const ok = pools.every((pool) => pool.ok);

  process.stdout.write(
    `${JSON.stringify(
      {
        ok,
        pools
      },
      null,
      2
    )}\n`
  );
  if (!ok) {
    process.exitCode = 1;
  }
}

async function reconcileGitHubAccess(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const report = await reconcileRunnerGroupAccess(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    runnerGroupAccessExpectations(config),
    args.includes("--apply")
  );

  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
  if (!report.ok) {
    process.exitCode = 1;
  }
}

function runnerGroupAccessExpectations(
  config: ResolvedConfig
): RunnerGroupAccessExpectation[] {
  return config.pools.map((pool) => ({
    poolKey: pool.key,
    organization: pool.organization,
    runnerGroup: pool.runnerGroup,
    repositoryAccess: pool.repositoryAccess,
    allowedRepositories: pool.allowedRepositories,
    allowsPublicRepositories: pool.visibility === "public"
  }));
}

async function validateLinuxDockerConfig(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);

  process.stdout.write(
    `${JSON.stringify(
      {
        version: config.version,
        image: config.image,
        pools: config.pools.map((pool) => ({
          key: pool.key,
          runnerGroup: pool.runnerGroup,
          visibility: pool.visibility,
          labels: pool.labels,
          size: pool.size,
          architecture: pool.architecture,
          runnerRoot: pool.runnerRoot
        }))
      },
      null,
      2
    )}\n`
  );
}

async function validateLinuxDockerGitHub(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);
  const matches = await verifyRunnerGroups(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    config.pools.map((pool) => ({
      poolKey: pool.key,
      organization: pool.organization,
      runnerGroup: pool.runnerGroup
    }))
  );

  process.stdout.write(
    `${JSON.stringify(
      {
        ok: true,
        pools: matches
      },
      null,
      2
    )}\n`
  );
}

async function validateWindowsDockerConfig(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);

  process.stdout.write(
    `${JSON.stringify(
      {
        version: config.version,
        plane: config.plane,
        image: config.image,
        pools: config.pools.map((pool) => ({
          key: pool.key,
          runnerGroup: pool.runnerGroup,
          visibility: pool.visibility,
          labels: pool.labels,
          size: pool.size,
          host: pool.host,
          sshUser: pool.sshUser,
          runnerRoot: pool.runnerRoot,
          imageRef: pool.imageRef
        }))
      },
      null,
      2
    )}\n`
  );
}

async function validateWindowsDockerGitHub(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);
  const matches = await verifyRunnerGroups(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    config.pools.map((pool) => ({
      poolKey: pool.key,
      organization: pool.organization,
      runnerGroup: pool.runnerGroup
    }))
  );

  process.stdout.write(
    `${JSON.stringify(
      {
        ok: true,
        pools: matches
      },
      null,
      2
    )}\n`
  );
}

async function renderSynologyProjectManifest(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const compose = renderCompose(config, env);
  const plan = buildSynologyInstallPlan(config, env, compose, {
    allowIncomplete: true
  });

  process.stdout.write(
    `${JSON.stringify(summarizeSynologyInstallPlan(plan), null, 2)}\n`
  );
}

async function renderLinuxDockerComposeCommand(args: string[]): Promise<void> {
  const output = getOption(args, "--output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);
  const compose = renderLinuxDockerCompose(config, env);

  if (output) {
    fs.writeFileSync(path.resolve(output), `${compose}\n`, "utf8");
    process.stdout.write(`${output}\n`);
    return;
  }

  process.stdout.write(`${compose}\n`);
}

async function renderLinuxDockerProjectManifest(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);
  const compose = renderLinuxDockerCompose(config, env);
  const plan = buildLinuxDockerInstallPlan(config, env, compose, {
    allowIncomplete: true
  });

  process.stdout.write(
    `${JSON.stringify(summarizeLinuxDockerInstallPlan(plan), null, 2)}\n`
  );
}

async function renderWindowsDockerComposeCommand(args: string[]): Promise<void> {
  const output = getOption(args, "--output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);
  const compose = renderWindowsDockerCompose(config, env);

  if (output) {
    fs.writeFileSync(path.resolve(output), `${compose}\n`, "utf8");
    process.stdout.write(`${output}\n`);
    return;
  }

  process.stdout.write(`${compose}\n`);
}

async function renderWindowsDockerProjectManifest(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);
  const compose = renderWindowsDockerCompose(config, env);
  const plan = buildWindowsDockerInstallPlan(config, env, compose, {
    allowIncomplete: true
  });

  process.stdout.write(
    `${JSON.stringify(summarizeWindowsDockerInstallPlan(plan), null, 2)}\n`
  );
}

async function installSynologyProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const statusOutput = getOption(args, "--status-output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const compose = renderCompose(config, env);
  const plan = buildSynologyInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "up"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "install-synology-project",
      action: "install",
      plane: "synology",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeSynologyInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  const python = getOption(args, "--python", "python3")!;
  await withControllerAction({
    command: "install-synology-project",
    action: "install",
    plane: "synology",
    pool: "all",
    dryRun: false
  }, () => {
    const output = runSynologyInstallPlan(plan, python);
    if (statusOutput) {
      saveSynologyResult(statusOutput, "up", output);
    }
  });
}

async function installLinuxDockerProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const statusOutput = getOption(args, "--status-output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);
  const compose = renderLinuxDockerCompose(config, env);
  const plan = buildLinuxDockerInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "up"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "install-linux-docker-project",
      action: "install",
      plane: "linux-docker",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeLinuxDockerInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  await withControllerAction({
    command: "install-linux-docker-project",
    action: "install",
    plane: "linux-docker",
    pool: "all",
    dryRun: false
  }, () => {
    try {
      const composePsOutput = runLinuxDockerInstall(plan);
      if (statusOutput) {
        saveLinuxDockerResult(statusOutput, {
          ok: true,
          action: "up",
          remoteLogPath: buildLinuxDockerRemoteLogPath(plan),
          composePsOutput,
          connection: plan.connection,
          project: {
            name: plan.project.name,
            directory: plan.project.directory
          },
          options: { ...plan.options }
        });
      }
    } catch (error) {
      if (statusOutput) {
        saveLinuxDockerResult(statusOutput, {
          ok: false,
          action: "up",
          remoteLogPath: buildLinuxDockerRemoteLogPath(plan),
          error: formatError(error),
          connection: plan.connection,
          project: {
            name: plan.project.name,
            directory: plan.project.directory
          },
          options: { ...plan.options }
        });
      }
      throw error;
    }
  });
}

async function teardownSynologyProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const statusOutput = getOption(args, "--status-output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const compose = renderCompose(config, env);
  const plan = buildSynologyInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "down"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "teardown-synology-project",
      action: "teardown",
      plane: "synology",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeSynologyInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  await withControllerAction({
    command: "teardown-synology-project",
    action: "teardown",
    plane: "synology",
    pool: "all",
    dryRun: false
  }, async () => {
    await drainBeforeTeardown(args, env, [
      ...config.pools.map((pool) => ({
        plane: "synology" as const,
        key: pool.key,
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
      }))
    ]);

    const python = getOption(args, "--python", "python3")!;
    const output = runSynologyInstallPlan(plan, python);
    if (statusOutput) {
      saveSynologyResult(statusOutput, "down", output);
    }
  });
}

function runSynologyInstallPlan(
  plan: ReturnType<typeof buildSynologyInstallPlan>,
  python: string
): string {
  const scriptPath = path.resolve("scripts/install-synology-project.py");
  const result = runBoundedCommand(python, [scriptPath], "Synology installer failed", {
    timeoutMs: Number(process.env.LOCAL_INSTALL_TIMEOUT_SECONDS ?? "900") * 1000,
    input: JSON.stringify(plan)
  });
  process.stdout.write(result);
  return result;
}

async function teardownLinuxDockerProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const statusOutput = getOption(args, "--status-output");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/linux-docker-runners.yaml");
  const config = loadLinuxDockerConfig(configPath!, env);
  const compose = renderLinuxDockerCompose(config, env);
  const plan = buildLinuxDockerInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "down"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "teardown-linux-docker-project",
      action: "teardown",
      plane: "linux-docker",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeLinuxDockerInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  await withControllerAction({
    command: "teardown-linux-docker-project",
    action: "teardown",
    plane: "linux-docker",
    pool: "all",
    dryRun: false
  }, async () => {
    await drainBeforeTeardown(args, env, [
      ...config.pools.map((pool) => ({
        plane: "linux-docker" as const,
        key: pool.key,
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
      }))
    ]);

    try {
      const composePsOutput = runLinuxDockerInstall(plan);
      if (statusOutput) {
        saveLinuxDockerResult(statusOutput, {
          ok: true,
          action: "down",
          remoteLogPath: buildLinuxDockerRemoteLogPath(plan),
          composePsOutput,
          connection: plan.connection,
          project: {
            name: plan.project.name,
            directory: plan.project.directory
          },
          options: { ...plan.options }
        });
      }
    } catch (error) {
      if (statusOutput) {
        saveLinuxDockerResult(statusOutput, {
          ok: false,
          action: "down",
          remoteLogPath: buildLinuxDockerRemoteLogPath(plan),
          error: formatError(error),
          connection: plan.connection,
          project: {
            name: plan.project.name,
            directory: plan.project.directory
          },
          options: { ...plan.options }
        });
      }
      throw error;
    }
  });
}

async function installWindowsDockerProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);
  const compose = renderWindowsDockerCompose(config, env);
  const plan = buildWindowsDockerInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "up"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "install-windows-project",
      action: "install",
      plane: "windows-docker",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeWindowsDockerInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  await withControllerAction({
    command: "install-windows-project",
    action: "install",
    plane: "windows-docker",
    pool: "all",
    dryRun: false
  }, () => {
    runWindowsDockerInstall(plan);
  });
}

async function teardownWindowsDockerProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getOption(args, "--config", "config/windows-runners.yaml");
  const config = loadWindowsDockerConfig(configPath!, env);
  const compose = renderWindowsDockerCompose(config, env);
  const plan = buildWindowsDockerInstallPlan(config, env, compose, {
    allowIncomplete: dryRun,
    action: "down"
  });

  if (dryRun) {
    emitControllerAction("info", "controller action dry-run", {
      command: "teardown-windows-project",
      action: "teardown",
      plane: "windows-docker",
      pool: "all",
      dryRun: true,
      status: "dry-run"
    });
    process.stdout.write(
      `${JSON.stringify(summarizeWindowsDockerInstallPlan(plan), null, 2)}\n`
    );
    return;
  }

  await withControllerAction({
    command: "teardown-windows-project",
    action: "teardown",
    plane: "windows-docker",
    pool: "all",
    dryRun: false
  }, async () => {
    await drainBeforeTeardown(args, env, [
      ...config.pools.map((pool) => ({
        plane: "windows-docker" as const,
        key: pool.key,
        organization: pool.organization,
        runnerGroup: pool.runnerGroup,
        runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
      }))
    ]);

    runWindowsDockerInstall(plan);
  });
}

async function validateImage(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/pools.yaml");
  const config = loadConfig(configPath!, env);
  emitWarnings(config);
  const imageRef = `${config.image.repository}:${config.image.tag}`;

  const match = await verifyContainerImageTag(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    imageRef
  );

  process.stdout.write(
    `${JSON.stringify(
      {
        ok: true,
        image: match
      },
      null,
      2
    )}\n`
  );
}

async function checkRunnerVersion(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const currentVersion = getOption(args, "--current", env.runnerVersion) ?? env.runnerVersion;
  const release = await fetchLatestRunnerRelease(env.githubApiUrl, env.githubPat);
  const status = summarizeRunnerVersion(currentVersion, release.version);
  const failAfterDays = parseNonNegativeInteger(
    getOption(args, "--fail-after-days", "21")!,
    "--fail-after-days"
  );
  const ageDays = runnerReleaseAgeDays(release.publishedAt);
  const blocked =
    status.outdated && (ageDays === undefined || ageDays >= failAfterDays);

  process.stdout.write(
    `${JSON.stringify(
      {
        ...status,
        ageDays,
        failAfterDays,
        blocked,
        publishedAt: release.publishedAt,
        htmlUrl: release.htmlUrl
      },
      null,
      2
    )}\n`
  );
  if (blocked) {
    process.exitCode = 1;
  }
}

async function runnerReleaseManifest(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const currentVersion = getOption(args, "--current", env.runnerVersion) ?? env.runnerVersion;
  const release = await fetchLatestRunnerRelease(env.githubApiUrl, env.githubPat);
  const status = summarizeRunnerVersion(currentVersion, release.version);

  process.stdout.write(
    `${JSON.stringify(
      {
        ...status,
        assets: {
          amd64: buildRunnerDownloadUrl(release.version, "amd64"),
          arm64: buildRunnerDownloadUrl(release.version, "arm64")
        }
      },
      null,
      2
    )}\n`
  );
}

async function validateLumeConfig(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/lume-runners.yaml");
  const config = loadLumeConfig(configPath!, env);

  process.stdout.write(
    `${JSON.stringify(
      {
        version: config.version,
        host: config.host,
        pool: {
          key: config.pool.key,
          organization: config.pool.organization,
          runnerGroup: config.pool.runnerGroup,
          slotRunnerGroups: config.pool.slotRunnerGroups,
          labels: config.pool.labels,
          size: config.pool.size,
          vmBaseName: config.pool.vmBaseName,
          vmSlotPrefix: config.pool.vmSlotPrefix,
          runnerVersion: config.pool.runnerVersion
        },
        slots: config.slots.map((slot) => ({
          index: slot.index,
          slotKey: slot.slotKey,
          vmName: slot.vmName,
          runnerName: slot.runnerName
        }))
      },
      null,
      2
    )}\n`
  );
}

async function validateLumeGitHub(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/lume-runners.yaml");
  const config = loadLumeConfig(configPath!, env);
  const matches = await verifyRunnerGroups(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    lumeRunnerGroupExpectations(config)
  );

  process.stdout.write(
    `${JSON.stringify(
      {
        ok: true,
        pools: matches
      },
      null,
      2
    )}\n`
  );
}

async function renderLumeRunnerManifest(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false
  });
  const configPath = getOption(args, "--config", "config/lume-runners.yaml");
  const slot = getOption(args, "--slot");
  const format = getOption(args, "--format", "json");
  const config = loadLumeConfig(configPath!, env);

  if (format === "shell") {
    if (!slot) {
      throw new Error("--slot is required when --format shell is used");
    }

    process.stdout.write(renderLumeShellExports(config, Number(slot)));
    return;
  }

  if (slot) {
    const slotIndex = Number(slot);
    const manifest = config.slots.find((entry) => entry.index === slotIndex);
    if (!manifest) {
      throw new Error(`slot ${slotIndex} is outside configured pool size ${config.pool.size}`);
    }

    process.stdout.write(
      `${JSON.stringify(
        {
          host: config.host,
          pool: config.pool,
          slot: manifest
        },
        null,
        2
      )}\n`
    );
    return;
  }

  process.stdout.write(`${JSON.stringify(config, null, 2)}\n`);
}

/** Read-only queued-job count used by the Lume slot watchdog to confirm a zombie listener while work is waiting. */
async function lumeQueuedJobs(args: string[]): Promise<void> {
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: false,
    requireGitHubAuth: true
  });
  const configPath = getOption(args, "--config", "config/lume-runners.yaml");
  const config = loadLumeConfig(configPath!, env);
  const slot = getOption(args, "--slot");
  const format = getOption(args, "--format", "text");

  if (slot) {
    const slotIndex = Number(slot);
    if (!config.slots.some((entry) => entry.index === slotIndex)) {
      throw new Error(`slot ${slotIndex} is outside configured pool size ${config.pool.size}`);
    }
  }

  const runnerGroup =
    (slot ? config.pool.slotRunnerGroups?.[slot] : undefined) ??
    config.pool.runnerGroup;
  const queuedJobs = await getQueuedJobCount(
    env.githubApiUrl,
    await resolveGitHubAccessToken(env),
    {
      organization: config.pool.organization,
      runnerGroup,
      repositories: [],
      labels: config.pool.labels
    }
  );

  if (format === "json") {
    process.stdout.write(
      `${JSON.stringify(
        {
          poolKey: config.pool.key,
          runnerGroup,
          queuedJobs
        },
        null,
        2
      )}\n`
    );
    return;
  }

  process.stdout.write(`${queuedJobs}\n`);
}

async function installLumeProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const format = getLumeProjectFormat(args);
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getLumeConfigPath(args);
  const config = loadLumeConfig(configPath, env);
  const resultPath = getOption(
    args,
    "--status-output",
    defaultLumeProjectResultPath(config)
  )!;
  let status: LumeProjectResult["status"] = "dry-run";
  let supervisorPid: number | undefined;

  if (!dryRun) {
    await withControllerAction({
      command: "install-lume-project",
      action: "install",
      plane: "lume",
      pool: config.pool.key,
      dryRun: false
    }, () => {
      const existingPid = readPidFile(defaultLumeProjectPidFile(config));
      if (existingPid && isProcessRunning(existingPid)) {
        status = "already-running";
        supervisorPid = existingPid;
      } else {
        supervisorPid = startLumeSupervisor(configPath, getOption(args, "--env", ".env")!, config);
        status = "started";
      }
    }, () => ({ lifecycleStatus: status, supervisorPid }));
  } else {
    emitControllerAction("info", "controller action dry-run", {
      command: "install-lume-project",
      action: "install",
      plane: "lume",
      pool: config.pool.key,
      dryRun: true,
      status: "dry-run"
    });
  }

  const result = buildLumeProjectResult({
    action: "install",
    status,
    config,
    resultPath,
    supervisorPid
  });
  saveLumeProjectResult(result);
  writeLumeProjectResult(result, format);
}

async function teardownLumeProject(args: string[]): Promise<void> {
  const dryRun = args.includes("--dry-run");
  const format = getLumeProjectFormat(args);
  const env = loadDeploymentEnv({
    envPath: getOption(args, "--env", ".env"),
    requirePat: !dryRun
  });
  const configPath = getLumeConfigPath(args);
  const config = loadLumeConfig(configPath, env);
  const resultPath = getOption(
    args,
    "--status-output",
    defaultLumeProjectResultPath(config)
  )!;
  let drain: LumeProjectResult["drain"];

  if (!dryRun) {
    await withControllerAction({
      command: "teardown-lume-project",
      action: "teardown",
      plane: "lume",
      pool: config.pool.key,
      dryRun: false
    }, async () => {
      const drainReport = await drainRunnerPool({
        apiUrl: env.githubApiUrl,
        token: await resolveGitHubAccessToken(env),
        organization: config.pool.organization,
        runnerGroup: config.pool.runnerGroup,
        poolKey: config.pool.key,
        runnerNames: config.slots.map((slot) => slot.runnerName),
        timeoutSeconds: parseDurationSeconds(
          getOption(args, "--drain-timeout", getOption(args, "--timeout", "300"))!,
          "--drain-timeout"
        ),
        intervalSeconds: parseDurationSeconds(
          getOption(args, "--drain-interval", getOption(args, "--interval", "5"))!,
          "--drain-interval"
        ),
        onProgress: (progress) => writeDrainProgress("lume", progress)
      });

      if (drainReport.status === "timeout") {
        throw new Error(
          `timed out waiting for ${drainReport.busy.join(", ")} to become idle before tearing down ${config.pool.key}`
        );
      }

      drain = {
        status: drainReport.status,
        cordoned: drainReport.cordoned,
        busy: drainReport.busy,
        missing: drainReport.missing
      };
      await stopLumeSupervisor(config);
      for (const slot of config.slots) {
        await stopLumeWorker(slot.workerPidFile);
        runLumeSlotTeardown(configPath, getOption(args, "--env", ".env")!, slot.index);
        fs.rmSync(slot.hostDir, { recursive: true, force: true });
      }
    }, () => ({
      drainStatus: drain?.status,
      cordoned: drain?.cordoned.length ?? 0,
      busy: drain?.busy.length ?? 0,
      missing: drain?.missing.length ?? 0
    }));
  } else {
    emitControllerAction("info", "controller action dry-run", {
      command: "teardown-lume-project",
      action: "teardown",
      plane: "lume",
      pool: config.pool.key,
      dryRun: true,
      status: "dry-run"
    });
  }

  const result = buildLumeProjectResult({
    action: "teardown",
    status: dryRun ? "dry-run" : "stopped",
    config,
    resultPath,
    drain
  });
  saveLumeProjectResult(result);
  writeLumeProjectResult(result, format);
}

function getConfigAgeSeconds(configPath: string): number {
  const stats = fs.statSync(path.resolve(configPath));
  return Math.max(0, Math.floor((Date.now() - stats.mtimeMs) / 1000));
}

interface ControllerActionFields extends LogFields {
  command: string;
  action: string;
}

async function withControllerAction<T>(
  fields: ControllerActionFields,
  callback: () => T | Promise<T>,
  completedFields: (result: Awaited<T>) => LogFields = () => ({})
): Promise<Awaited<T>> {
  emitControllerAction("info", "controller action started", {
    ...fields,
    status: "started"
  });

  try {
    const result = await callback();
    emitControllerAction("info", "controller action completed", {
      ...fields,
      ...completedFields(result),
      status: "completed"
    });
    return result;
  } catch (error) {
    emitControllerAction("error", "controller action failed", {
      ...fields,
      status: "failed",
      error
    });
    throw error;
  }
}

function emitControllerAction(
  level: LogLevel,
  msg: string,
  fields: ControllerActionFields
): void {
  log[level](msg, {
    component: "controller",
    ...fields
  });
}

function applyAutoscaleDecisions(
  config: ResolvedConfig,
  decisions: AutoscaleDecision[]
): ResolvedConfig {
  const targetSizes = new Map(
    decisions
      .filter((decision) => decision.action !== "none")
      .map((decision) => [decision.poolKey, decision.targetSize])
  );

  return {
    ...config,
    pools: config.pools.map((pool) => ({
      ...pool,
      size: targetSizes.get(pool.key) ?? pool.size
    }))
  };
}

function writeScaledPoolSizes(
  configPath: string,
  decisions: AutoscaleDecision[]
): void {
  const targetSizes = new Map(
    decisions
      .filter((decision) => decision.action !== "none")
      .map((decision) => [decision.poolKey, decision.targetSize])
  );
  if (targetSizes.size === 0) {
    return;
  }

  const absolutePath = path.resolve(configPath);
  const document = YAML.parse(fs.readFileSync(absolutePath, "utf8")) as {
    pools?: Array<{ key?: string; size?: number }>;
  };
  if (!Array.isArray(document.pools)) {
    throw new Error(`config ${configPath} did not include pools`);
  }

  for (const pool of document.pools) {
    if (pool.key && targetSizes.has(pool.key)) {
      pool.size = targetSizes.get(pool.key);
    }
  }

  fs.writeFileSync(absolutePath, YAML.stringify(document), "utf8");
}

type DrainPlane = "synology" | "linux-docker" | "windows-docker" | "lume";
type TokenRotationPlane = Exclude<DrainPlane, "windows-docker">;

interface DrainPoolDefinition {
  plane: DrainPlane;
  key: string;
  organization: string;
  runnerGroup: string;
  runnerNames: string[];
}

interface TokenRotationPoolDefinition {
  plane: TokenRotationPlane;
  key: string;
  organization: string;
  runnerGroup: string;
  runnerNames: string[];
}

interface TokenRotationValidation {
  runnerGroups: Awaited<ReturnType<typeof verifyRunnerGroups>>;
  validatedOrganizations: string[];
}

function resolveNewTokenEnvName(args: string[]): string {
  return getOption(
    args,
    "--new-token-env",
    process.env.GITHUB_PAT_NEXT ? "GITHUB_PAT_NEXT" : "NEW_GITHUB_PAT"
  )!;
}

function getRotationPlane(args: string[]): TokenRotationPlane | undefined {
  const plane = getOption(args, "--plane") as TokenRotationPlane | undefined;
  if (plane && !["synology", "linux-docker", "lume"].includes(plane)) {
    throw new Error(`unknown rotate-token plane: ${plane}`);
  }
  return plane;
}

function collectTokenRotationDefinitions(
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>,
  requestedPlane?: TokenRotationPlane
): TokenRotationPoolDefinition[] {
  const definitions: TokenRotationPoolDefinition[] = [];

  if (shouldLoadDrainConfig(args, "--config", requestedPlane, "synology")) {
    const configPath = getOption(args, "--config", "config/pools.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadConfig(configPath, env);
      emitWarnings(config);
      definitions.push(
        ...config.pools.map((pool) => ({
          plane: "synology" as const,
          key: pool.key,
          organization: pool.organization,
          runnerGroup: pool.runnerGroup,
          runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
        }))
      );
    }
  }

  if (shouldLoadDrainConfig(args, "--linux-config", requestedPlane, "linux-docker")) {
    const configPath = getOption(
      args,
      "--linux-config",
      "config/linux-docker-runners.yaml"
    )!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLinuxDockerConfig(configPath, env);
      definitions.push(
        ...config.pools.map((pool) => ({
          plane: "linux-docker" as const,
          key: pool.key,
          organization: pool.organization,
          runnerGroup: pool.runnerGroup,
          runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
        }))
      );
    }
  }

  if (shouldLoadDrainConfig(args, "--lume-config", requestedPlane, "lume")) {
    const configPath = getOption(args, "--lume-config", "config/lume-runners.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLumeConfig(configPath, env);
      definitions.push({
        plane: "lume",
        key: config.pool.key,
        organization: config.pool.organization,
        runnerGroup: config.pool.runnerGroup,
        runnerNames: config.slots.map((slot) => slot.runnerName)
      });
    }
  }

  return definitions;
}

async function validateRegistrationTokenScopes(
  apiUrl: string,
  token: string,
  definitions: TokenRotationPoolDefinition[]
): Promise<string[]> {
  const organizations = [...new Set(definitions.map((entry) => entry.organization))].sort();
  for (const organization of organizations) {
    await fetchRunnerToken(
      buildRegistrationTokenRequest(apiUrl, organization, token),
      undefined,
      { plane: "rotate-token" }
    );
  }
  return organizations;
}

function buildTokenRotationPlan(
  dryRun: boolean,
  tokenEnv: string,
  definitions: TokenRotationPoolDefinition[],
  validation: TokenRotationValidation
) {
  return {
    dryRun,
    tokenEnv,
    validation: {
      runnerGroups: validation.runnerGroups,
      registrationTokenOrganizations: validation.validatedOrganizations
    },
    pools: definitions.map((definition) => ({
      plane: definition.plane,
      key: definition.key,
      organization: definition.organization,
      runnerGroup: definition.runnerGroup,
      runnerNames: definition.runnerNames,
      actions:
        definition.plane === "lume"
          ? [
              "validated replacement PAT can mint registration tokens",
              "no host restart required; Lume guests receive the configured PAT on each VM boot"
            ]
          : [
              "validated replacement PAT can mint registration tokens",
              "wait for configured runners to become idle and deregister each idle runner",
              "redeploy the plane with the replacement PAT in the generated env file",
              "verify the previous PAT is absent from regenerated project env files and replacement runners register"
            ]
    }))
  };
}

function assertGeneratedPatRotation(
  planeName: string,
  envFileContent: string,
  expectedToken: string
): void {
  const generatedPat = parseGeneratedDotEnvValue(envFileContent, "GITHUB_PAT");
  if (generatedPat !== expectedToken) {
    throw new Error(`${planeName} rotation did not generate env content with the replacement PAT`);
  }
}

function parseGeneratedDotEnvValue(content: string, key: string): string | undefined {
  const line = content
    .split("\n")
    .find((entry) => entry.startsWith(`${key}=`));
  if (!line) {
    return undefined;
  }

  const rawValue = line.slice(key.length + 1);
  if (!rawValue.startsWith('"') || !rawValue.endsWith('"')) {
    return rawValue;
  }

  const quotedValue = rawValue.slice(1, -1);
  let parsed = "";
  for (let index = 0; index < quotedValue.length; index += 1) {
    const character = quotedValue[index];
    if (character !== "\\" || index === quotedValue.length - 1) {
      parsed += character;
      continue;
    }

    const next = quotedValue[index + 1];
    index += 1;
    if (next === "n") {
      parsed += "\n";
    } else {
      parsed += next;
    }
  }

  return parsed;
}

async function withPatOverride<T>(
  githubPat: string,
  callback: () => T | Promise<T>
): Promise<T> {
  const previous = process.env.GITHUB_PAT;
  process.env.GITHUB_PAT = githubPat;
  try {
    return await callback();
  } finally {
    if (previous === undefined) {
      delete process.env.GITHUB_PAT;
    } else {
      process.env.GITHUB_PAT = previous;
    }
  }
}

function writeTokenRotationAudit(
  definitions: TokenRotationPoolDefinition[]
): void {
  for (const definition of definitions) {
    for (const runnerName of definition.runnerNames) {
      writeAuditRecord({
        event: "runner_token_rotated",
        runner_name: runnerName,
        pool: definition.key,
        plane: definition.plane,
        org: definition.organization
      });
    }
  }
}

async function drainBeforeTeardown(
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>,
  definitions: DrainPoolDefinition[]
): Promise<void> {
  if (!args.includes("--drain")) {
    return;
  }

  const timeoutSeconds = parseDurationSeconds(
    getOption(args, "--drain-timeout", getOption(args, "--timeout", "300"))!,
    "--drain-timeout"
  );
  const intervalSeconds = parseDurationSeconds(
    getOption(args, "--drain-interval", getOption(args, "--interval", "5"))!,
    "--drain-interval"
  );

  for (const definition of definitions) {
    const report = await drainRunnerPool({
      apiUrl: env.githubApiUrl,
      token: await resolveGitHubAccessToken(env),
      organization: definition.organization,
      runnerGroup: definition.runnerGroup,
      poolKey: definition.key,
      runnerNames: definition.runnerNames,
      timeoutSeconds,
      intervalSeconds,
      onProgress: (progress) => writeDrainProgress(definition.plane, progress)
    });

    if (report.status === "timeout") {
      throw new Error(
        `timed out waiting for ${report.busy.join(", ")} to become idle before tearing down ${definition.key}`
      );
    }
  }
}

function resolveDrainPoolDefinition(
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>,
  poolKey: string
): DrainPoolDefinition {
  const plane = getOption(args, "--plane") as DrainPlane | undefined;
  if (
    plane &&
    !["synology", "linux-docker", "windows-docker", "lume"].includes(plane)
  ) {
    throw new Error(`unknown drain plane: ${plane}`);
  }

  const matches = collectDrainPoolDefinitions(args, env, plane).filter(
    (definition) => definition.key === poolKey
  );
  if (matches.length === 0) {
    throw new Error(`unknown pool: ${poolKey}`);
  }
  if (matches.length > 1) {
    throw new Error(
      `pool ${poolKey} exists in multiple planes; pass --plane to choose one`
    );
  }

  return matches[0];
}

function collectDrainPoolDefinitions(
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>,
  requestedPlane?: DrainPlane
): DrainPoolDefinition[] {
  const definitions: DrainPoolDefinition[] = [];

  if (shouldLoadDrainConfig(args, "--config", requestedPlane, "synology")) {
    const configPath = getOption(args, "--config", "config/pools.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadConfig(configPath, env);
      definitions.push(
        ...config.pools.map((pool) => ({
          plane: "synology" as const,
          key: pool.key,
          organization: pool.organization,
          runnerGroup: pool.runnerGroup,
          runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
        }))
      );
    }
  }

  if (shouldLoadDrainConfig(args, "--linux-config", requestedPlane, "linux-docker")) {
    const configPath = getOption(
      args,
      "--linux-config",
      "config/linux-docker-runners.yaml"
    )!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLinuxDockerConfig(configPath, env);
      definitions.push(
        ...config.pools.map((pool) => ({
          plane: "linux-docker" as const,
          key: pool.key,
          organization: pool.organization,
          runnerGroup: pool.runnerGroup,
          runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
        }))
      );
    }
  }

  if (shouldLoadDrainConfig(args, "--windows-config", requestedPlane, "windows-docker")) {
    const configPath = getOption(
      args,
      "--windows-config",
      "config/windows-runners.yaml"
    )!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadWindowsDockerConfig(configPath, env);
      definitions.push(
        ...config.pools.map((pool) => ({
          plane: "windows-docker" as const,
          key: pool.key,
          organization: pool.organization,
          runnerGroup: pool.runnerGroup,
          runnerNames: buildIndexedRunnerNames(pool.key, 1, pool.size)
        }))
      );
    }
  }

  if (shouldLoadDrainConfig(args, "--lume-config", requestedPlane, "lume")) {
    const configPath = getOption(args, "--lume-config", "config/lume-runners.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLumeConfig(configPath, env);
      definitions.push({
        plane: "lume",
        key: config.pool.key,
        organization: config.pool.organization,
        runnerGroup: config.pool.runnerGroup,
        runnerNames: config.slots.map((slot) => slot.runnerName)
      });
    }
  }

  return definitions;
}

function shouldLoadDrainConfig(
  args: string[],
  optionName: string,
  requestedPlane: DrainPlane | undefined,
  plane: DrainPlane
): boolean {
  if (args.includes(optionName)) {
    return true;
  }
  return !requestedPlane || requestedPlane === plane;
}

function buildIndexedRunnerNames(
  poolKey: string,
  startIndex: number,
  endIndex: number
): string[] {
  if (endIndex < startIndex) {
    return [];
  }
  return Array.from(
    { length: endIndex - startIndex + 1 },
    (_value, offset) =>
      `${poolKey}-runner-${String(startIndex + offset).padStart(2, "0")}`
  );
}

function writeDrainProgress(plane: DrainPlane, progress: DrainProgress): void {
  emitControllerAction(
    progress.status === "timeout" ? "warn" : "info",
    `drain ${plane}/${progress.poolKey}: ${progress.status}`,
    {
      command: "drain-pool",
      action: "drain",
      plane,
      pool: progress.poolKey,
      drainStatus: progress.status,
      iteration: progress.iteration,
      total: progress.total,
      cordoned: progress.cordoned.length,
      busy: progress.busy.length,
      missing: progress.missing.length,
      cordonedRunners: progress.cordoned,
      busyRunners: progress.busy,
      missingRunners: progress.missing
    }
  );
}

function renderDrainReport(plane: DrainPlane, report: DrainReport): string {
  return [
    `drain ${plane}/${report.poolKey}: ${report.status}`,
    `cordoned: ${report.cordoned.length}/${report.total}`,
    `busy: ${report.busy.length ? report.busy.join(", ") : "none"}`,
    `already absent: ${report.missing.length ? report.missing.join(", ") : "none"}`,
    ""
  ].join("\n");
}

function renderPruneStaleRunnersReport(
  report: PruneStaleRunnersReport
): string {
  const lines = [
    `prune-stale-runners mode=${report.apply ? "apply" : "dry-run"}`,
    `groups scanned: ${report.groups.length}`,
    `stale runners: ${report.stale.length}`,
    `deleted: ${report.deleted.length}`
  ];

  for (const runner of report.stale) {
    lines.push(
      `- ${runner.organization}/${runner.runnerGroup} ${runner.name} (${runner.plane}/${runner.poolKey}) id=${runner.id}` +
        (report.apply ? ` deleted=${runner.deleted === true ? "yes" : "no"}` : "")
    );
  }

  if (!report.apply && report.stale.length > 0) {
    lines.push("rerun with --apply to deregister the stale offline runners");
  }

  return `${lines.join("\n")}\n`;
}

function renderConfigDiffReport(report: ConfigDiffReport): string {
  if (report.inSync) {
    return "config-diff: in sync\n";
  }

  const lines = [
    "config-diff: out of sync",
    `added: ${report.added.length}`,
    `removed: ${report.removed.length}`,
    `changed: ${report.changed.length}`
  ];

  for (const runner of report.added) {
    lines.push(
      `+ ${runner.organization}/${runner.name} ${runner.plane}/${runner.poolKey} group=${runner.runnerGroup} labels=${runner.labels.join(",")}`
    );
  }

  for (const runner of report.removed) {
    lines.push(
      `- ${runner.organization}/${runner.name} group=${runner.runnerGroup ?? "unknown"} status=${runner.status} labels=${runner.labels.join(",")}`
    );
  }

  for (const runner of report.changed) {
    const details = [
      runner.actualRunnerGroup !== runner.runnerGroup
        ? `group ${runner.actualRunnerGroup ?? "unknown"} -> ${runner.runnerGroup}`
        : undefined,
      runner.missingLabels.length > 0
        ? `missing labels ${runner.missingLabels.join(",")}`
        : undefined,
      runner.unexpectedLabels.length > 0
        ? `unexpected labels ${runner.unexpectedLabels.join(",")}`
        : undefined
    ].filter((entry): entry is string => entry !== undefined);
    lines.push(
      `~ ${runner.organization}/${runner.name} ${runner.plane}/${runner.poolKey}: ${details.join("; ")}`
    );
  }

  return `${lines.join("\n")}\n`;
}

function collectConfigDiffDesiredRunners(
  args: string[],
  env: ReturnType<typeof loadDeploymentEnv>,
  requestedPlane?: DrainPlane
): DesiredRunnerState[] {
  const runners: DesiredRunnerState[] = [];

  if (shouldLoadDrainConfig(args, "--config", requestedPlane, "synology")) {
    const configPath = getOption(args, "--config", "config/pools.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadConfig(configPath, env);
      emitWarnings(config);
      for (const pool of config.pools) {
        runners.push(
          ...buildIndexedRunnerNames(pool.key, 1, pool.size).map((name) => ({
            plane: "synology",
            poolKey: pool.key,
            organization: pool.organization,
            name,
            runnerGroup: pool.runnerGroup,
            labels: pool.labels
          }))
        );
      }
    }
  }

  if (shouldLoadDrainConfig(args, "--linux-config", requestedPlane, "linux-docker")) {
    const configPath = getOption(
      args,
      "--linux-config",
      "config/linux-docker-runners.yaml"
    )!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLinuxDockerConfig(configPath, env);
      for (const pool of config.pools) {
        runners.push(
          ...buildIndexedRunnerNames(pool.key, 1, pool.size).map((name) => ({
            plane: "linux-docker",
            poolKey: pool.key,
            organization: pool.organization,
            name,
            runnerGroup: pool.runnerGroup,
            labels: pool.labels
          }))
        );
      }
    }
  }

  if (shouldLoadDrainConfig(args, "--windows-config", requestedPlane, "windows-docker")) {
    const configPath = getOption(
      args,
      "--windows-config",
      "config/windows-runners.yaml"
    )!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadWindowsDockerConfig(configPath, env);
      for (const pool of config.pools) {
        runners.push(
          ...buildIndexedRunnerNames(pool.key, 1, pool.size).map((name) => ({
            plane: "windows-docker",
            poolKey: pool.key,
            organization: pool.organization,
            name,
            runnerGroup: pool.runnerGroup,
            labels: pool.labels
          }))
        );
      }
    }
  }

  if (shouldLoadDrainConfig(args, "--lume-config", requestedPlane, "lume")) {
    const configPath = getOption(args, "--lume-config", "config/lume-runners.yaml")!;
    if (fs.existsSync(path.resolve(configPath))) {
      const config = loadLumeConfig(configPath, env);
      runners.push(
        ...config.slots.map((slot) => ({
          plane: "lume",
          poolKey: config.pool.key,
          organization: config.pool.organization,
          name: slot.runnerName,
          runnerGroup: config.pool.runnerGroup,
          labels: config.pool.labels
        }))
      );
    }
  }

  return runners;
}

function getDoctorMode(args: string[]): DoctorMode {
  const optionFlags = new Set([
    "--env",
    "--config",
    "--linux-config",
    "--linux-docker-config",
    "--windows-config",
    "--lume-config",
    "--format"
  ]);

  for (let index = 0; index < args.length; index += 1) {
    const arg = args[index];
    if (optionFlags.has(arg)) {
      index += 1;
      continue;
    }

    if (arg.startsWith("--")) {
      continue;
    }

    if (
      arg === "full" ||
      arg === "synology" ||
      arg === "linux-docker" ||
      arg === "windows-docker" ||
      arg === "lume"
    ) {
      return arg;
    }

    throw new Error(`unknown doctor mode: ${arg}`);
  }

  return "full";
}

function getLumeConfigPath(args: string[]): string {
  return getOption(
    args,
    "--lume-config",
    getOption(args, "--config", "config/lume-runners.yaml")
  )!;
}

function getLumeProjectFormat(args: string[]): "json" | "text" {
  const format = getOption(args, "--format", "text")!;
  if (format !== "json" && format !== "text") {
    throw new Error(`unknown Lume project format: ${format}`);
  }
  return format;
}

function getOption(
  args: string[],
  flag: string,
  defaultValue?: string
): string | undefined {
  const index = args.indexOf(flag);
  if (index === -1) {
    return defaultValue;
  }

  const value = args[index + 1];
  if (!value || value.startsWith("--")) {
    throw new Error(`missing value for ${flag}`);
  }

  return value;
}

function parseListenAddress(value: string): { host: string; port: number } {
  const normalized = value.startsWith(":") ? `0.0.0.0${value}` : value;
  const [host, portValue] = normalized.split(":");
  const port = Number(portValue);
  if (!host || !Number.isInteger(port) || port <= 0 || port > 65535) {
    throw new Error(`invalid --listen address: ${value}`);
  }
  return { host, port };
}

function parseNonNegativeInteger(value: string, optionName: string): number {
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed < 0) {
    throw new Error(`${optionName} must be a non-negative integer`);
  }
  return parsed;
}

function parsePositiveInteger(value: string, optionName: string): number {
  const parsed = Number(value);
  if (!Number.isInteger(parsed) || parsed <= 0) {
    throw new Error(`${optionName} must be a positive integer`);
  }
  return parsed;
}

function parseDurationSeconds(value: string, optionName: string): number {
  const match = value.match(/^(\d+)([smh])?$/);
  if (!match) {
    throw new Error(`${optionName} must be a non-negative duration like 300, 15m, or 1h`);
  }

  const amount = parseNonNegativeInteger(match[1], optionName);
  const unit = match[2] ?? "s";
  if (unit === "h") {
    return amount * 60 * 60;
  }
  if (unit === "m") {
    return amount * 60;
  }
  return amount;
}

function runLinuxDockerInstall(
  plan: ReturnType<typeof buildLinuxDockerInstallPlan>
): string {
  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "linux-docker-install-"));
  const composePath = path.join(stagingDir, plan.project.composeFileName);
  const envPath = path.join(stagingDir, plan.project.envFileName);
  const scriptPath = path.join(stagingDir, plan.project.deploymentScriptName);
  const remote = `${plan.connection.username}@${plan.connection.host}`;
  let output = "";

  try {
    fs.writeFileSync(composePath, `${plan.composeContent}\n`, "utf8");
    fs.writeFileSync(envPath, plan.envFileContent, "utf8");
    fs.writeFileSync(scriptPath, plan.deploymentScript, "utf8");

    output += runCommand(
      "ssh",
      [
        ...sshTransportArgs(),
        "-p",
        plan.connection.port,
        remote,
        [
          "mkdir -p",
          shellQuote(plan.project.directory),
          shellQuote(path.posix.join(plan.project.directory, "logs")),
          ...plan.stateDirectories.map((entry) => shellQuote(entry))
        ].join(" ")
      ],
      "failed to prepare remote Linux Docker host"
    );

    output += runCommand(
      "scp",
      [
        ...sshTransportArgs(),
        "-P",
        plan.connection.port,
        composePath,
        envPath,
        scriptPath,
        `${remote}:${shellEscapeRemotePath(plan.project.directory)}/`
      ],
      "failed to upload Linux Docker project files"
    );

    output += runCommand(
      "ssh",
      [
        ...sshTransportArgs(),
        "-p",
        plan.connection.port,
        remote,
        [
          "chmod 700",
          shellQuote(path.posix.join(plan.project.directory, plan.project.deploymentScriptName)),
          "&& cd",
          shellQuote(plan.project.directory),
          "&& ./" + plan.project.deploymentScriptName
        ].join(" ")
      ],
      "failed to execute Linux Docker deployment"
    );
  } finally {
    fs.rmSync(stagingDir, { recursive: true, force: true });
  }

  return output.trim();
}

function runWindowsDockerInstall(
  plan: ReturnType<typeof buildWindowsDockerInstallPlan>
): void {
  const stagingDir = fs.mkdtempSync(path.join(os.tmpdir(), "windows-docker-install-"));
  const composePath = path.join(stagingDir, plan.project.composeFileName);
  const envPath = path.join(stagingDir, plan.project.envFileName);
  const scriptPath = path.join(stagingDir, plan.project.deploymentScriptName);
  const remote = `${plan.connection.username}@${plan.connection.host}`;
  const remoteProjectDir = windowsRemotePath(plan.project.directory);
  const remoteScriptPath = windowsRemotePath(
    path.win32.join(plan.project.directory, plan.project.deploymentScriptName)
  );

  try {
    fs.writeFileSync(composePath, `${plan.composeContent}\n`, "utf8");
    fs.writeFileSync(envPath, plan.envFileContent, "utf8");
    fs.writeFileSync(scriptPath, plan.deploymentScript, "utf8");

    runCommand(
      "ssh",
      [
        ...sshTransportArgs(),
        "-p",
        plan.connection.port,
        remote,
        "powershell",
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-Command",
        `New-Item -ItemType Directory -Force -Path ${powerShellQuote(plan.project.directory)} | Out-Null`
      ],
      "failed to prepare remote Windows Docker host"
    );

    runCommand(
      "scp",
      [
        ...sshTransportArgs(),
        "-P",
        plan.connection.port,
        composePath,
        envPath,
        scriptPath,
        `${remote}:${remoteProjectDir}/`
      ],
      "failed to upload Windows Docker project files"
    );

    runCommand(
      "ssh",
      [
        ...sshTransportArgs(),
        "-p",
        plan.connection.port,
        remote,
        "powershell",
        "-NoProfile",
        "-ExecutionPolicy",
        "Bypass",
        "-File",
        remoteScriptPath
      ],
      "failed to execute Windows Docker deployment"
    );
  } finally {
    fs.rmSync(stagingDir, { recursive: true, force: true });
  }
}

function startLumeSupervisor(
  configPath: string,
  envPath: string,
  config: ReturnType<typeof loadLumeConfig>
): number {
  const pidFile = defaultLumeProjectPidFile(config);
  const logFile = defaultLumeProjectLogFile(config);
  fs.mkdirSync(path.dirname(pidFile), { recursive: true });
  fs.mkdirSync(path.dirname(logFile), { recursive: true });

  const output = fs.openSync(logFile, "a");
  const child = spawn(
    "bash",
    [
      path.resolve("scripts/lume/reconcile-pool.sh"),
      "--config",
      path.resolve(configPath),
      "--env",
      path.resolve(envPath)
    ],
    {
      detached: true,
      env: process.env,
      stdio: ["ignore", output, output]
    }
  );
  if (!child.pid) {
    fs.closeSync(output);
    throw new Error("failed to start Lume project supervisor");
  }
  child.unref();
  fs.closeSync(output);
  fs.writeFileSync(pidFile, `${child.pid}\n`, "utf8");
  return child.pid;
}

async function stopLumeSupervisor(config: ReturnType<typeof loadLumeConfig>): Promise<void> {
  const pidFile = defaultLumeProjectPidFile(config);
  await terminateTrackedProcess({ pidFile, expectedCommand: "reconcile-pool.sh" });
}

async function stopLumeWorker(pidFile: string): Promise<void> {
  await terminateTrackedProcess({ pidFile, expectedCommand: "run-slot.sh" });
}

function runLumeSlotTeardown(
  configPath: string,
  envPath: string,
  slotIndex: number
): void {
  runCommand(
    "bash",
    [
      path.resolve("scripts/lume/destroy-slot.sh"),
      "--slot",
      String(slotIndex),
      "--config",
      path.resolve(configPath),
      "--env",
      path.resolve(envPath)
    ],
    `failed to tear down Lume slot ${slotIndex}`
  );
}

function readPidFile(pidFile: string): number | undefined {
  if (!fs.existsSync(pidFile)) {
    return undefined;
  }
  const parsed = Number.parseInt(fs.readFileSync(pidFile, "utf8").trim(), 10);
  return Number.isFinite(parsed) ? parsed : undefined;
}

function isProcessRunning(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch {
    return false;
  }
}

function writeLumeProjectResult(
  result: LumeProjectResult,
  format: "json" | "text"
): void {
  process.stdout.write(
    format === "json"
      ? `${JSON.stringify(result, null, 2)}\n`
      : formatLumeProjectResultText(result)
  );
}

function runCommand(
  command: string,
  args: string[],
  errorPrefix: string
): string {
  const output = runBoundedCommand(command, args, errorPrefix, {
    timeoutMs: Number(process.env.REMOTE_COMMAND_TIMEOUT_SECONDS ?? "300") * 1000
  });
  if (output) process.stdout.write(output);
  return output;
}

function shellQuote(value: string): string {
  return `'${value.replace(/'/g, `'\"'\"'`)}'`;
}

function shellEscapeRemotePath(value: string): string {
  return value.replace(/(["\\$`])/g, "\\$1");
}

function buildLinuxDockerRemoteLogPath(
  plan: ReturnType<typeof buildLinuxDockerInstallPlan>
): string {
  return path.posix.join(plan.project.directory, "logs", plan.project.logFileName);
}

function formatError(error: unknown): string {
  return error instanceof Error ? error.message : String(error);
}

function windowsRemotePath(value: string): string {
  return value.replace(/\\/g, "/");
}

function powerShellQuote(value: string): string {
  return `'${value.replace(/'/g, "''")}'`;
}

function printUsage(): void {
  process.stderr.write(`Usage:
  pnpm doctor [full|synology|linux-docker|windows-docker|lume] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--linux-docker-config config/linux-docker-runners.yaml] [--windows-config config/windows-runners.yaml] [--lume-config config/lume-runners.yaml] [--format text|json]
  pnpm synology-status [--config config/pools.yaml] [--env .env] [--result .tmp/synology-status.json] [--format text|json]
  pnpm linux-docker-status [--config config/linux-docker-runners.yaml] [--env .env] [--result .tmp/linux-docker-status.json] [--format text|json]
  pnpm audit-log [--file /var/log/runner-fleet/audit.jsonl] [--max-size-bytes 10485760] < event.json
  pnpm drift-detect [--config config/pools.yaml] [--env .env] [--threshold 0]
  pnpm config-diff [--plane synology|linux-docker|windows-docker|lume] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--windows-config config/windows-runners.yaml] [--lume-config config/lume-runners.yaml] [--format text|json]
  pnpm drain-pool -- --pool synology-private [--plane synology|linux-docker|windows-docker|lume] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--windows-config config/windows-runners.yaml] [--lume-config config/lume-runners.yaml] [--timeout 15m] [--interval 5] [--format text|json]
  pnpm reconcile-linux-pool -- [--plane synology|linux-docker|both] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--state path] [--lock path] [--timeout 15m] [--interval 5] [--format text|json] [--dry-run] [--force]
  pnpm prune-stale-runners [--plane synology|linux-docker|windows-docker|lume] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--windows-config config/windows-runners.yaml] [--lume-config config/lume-runners.yaml] [--format text|json] [--apply]
  pnpm rotate-token [--plane synology|linux-docker|lume] [--pool synology-private] [--env .env] [--config config/pools.yaml] [--linux-config config/linux-docker-runners.yaml] [--lume-config config/lume-runners.yaml] [--new-token-env NEW_GITHUB_PAT] [--dry-run|--apply] [--drain-timeout 15m] [--drain-interval 5]
  pnpm scale [--config config/pools.yaml] [--env .env] [--pool synology-private] [--dry-run] [--drain-timeout 300] [--drain-interval 5] [--python python3]
  pnpm autoscale-webhook -- [--config config/pools.yaml] [--env .env] [--listen :8080] [--secret-env AUTOSCALE_WEBHOOK_SECRET] [--state .tmp/autoscale-webhook.json]
  pnpm validate-config [--config config/pools.yaml] [--env .env]
  pnpm validate-linux-docker-config [--config config/linux-docker-runners.yaml] [--env .env]
  pnpm validate-linux-docker-github [--config config/linux-docker-runners.yaml] [--env .env]
  pnpm validate-windows-config [--config config/windows-runners.yaml] [--env .env]
  pnpm validate-windows-github [--config config/windows-runners.yaml] [--env .env]
  pnpm validate-github [--config config/pools.yaml] [--env .env]
  pnpm reconcile-github-access [--config config/pools.yaml] [--env .env] [--apply]
  pnpm validate-image [--config config/pools.yaml] [--env .env]
  pnpm render-linux-docker-compose [--config config/linux-docker-runners.yaml] [--env .env] [--output docker-compose.linux-docker.yml]
  pnpm render-linux-docker-project-manifest [--config config/linux-docker-runners.yaml] [--env .env]
  pnpm render-windows-compose [--config config/windows-runners.yaml] [--env .env] [--output docker-compose.windows.yml]
  pnpm render-windows-project-manifest [--config config/windows-runners.yaml] [--env .env]
  pnpm render-compose [--config config/pools.yaml] [--env .env] [--output docker-compose.generated.yml]
  pnpm install-linux-docker-project [--config config/linux-docker-runners.yaml] [--env .env] [--status-output .tmp/linux-docker-status.json] [--dry-run]
  pnpm teardown-linux-docker-project [--config config/linux-docker-runners.yaml] [--env .env] [--status-output .tmp/linux-docker-status.json] [--dry-run] [--drain] [--drain-timeout 15m]
  pnpm install-windows-project [--config config/windows-runners.yaml] [--env .env] [--dry-run]
  pnpm teardown-windows-project [--config config/windows-runners.yaml] [--env .env] [--dry-run] [--drain] [--drain-timeout 15m]
  pnpm render-synology-project-manifest [--config config/pools.yaml] [--env .env]
  pnpm install-synology-project [--config config/pools.yaml] [--env .env] [--status-output .tmp/synology-status.json] [--dry-run] [--python python3]
  pnpm teardown-synology-project [--config config/pools.yaml] [--env .env] [--status-output .tmp/synology-status.json] [--dry-run] [--drain] [--drain-timeout 15m] [--python python3]
  pnpm check-runner-version [--current 2.333.0] [--env .env]
  pnpm runner-release-manifest [--current 2.333.0] [--env .env]
  pnpm validate-lume-config [--config config/lume-runners.yaml] [--env .env]
  pnpm validate-lume-github [--config config/lume-runners.yaml] [--env .env]
  pnpm render-lume-runner-manifest [--config config/lume-runners.yaml] [--env .env] [--slot 1] [--format json|shell]
  pnpm lume-queued-jobs [--config config/lume-runners.yaml] [--env .env] [--slot 1] [--format text|json]
  pnpm install-lume-project [--lume-config config/lume-runners.yaml] [--env .env] [--format text|json] [--status-output path] [--dry-run]
  pnpm teardown-lume-project [--lume-config config/lume-runners.yaml] [--env .env] [--format text|json] [--status-output path] [--drain-timeout 15m] [--dry-run]
`);
}

function emitWarnings(config: ReturnType<typeof loadConfig>): void {
  for (const warning of collectConfigWarnings(config)) {
    process.stderr.write(`warning: ${warning}\n`);
  }
}

if (
  process.argv[1] &&
  path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)
) {
  main().catch((error: unknown) => {
    const message = error instanceof Error ? error.message : String(error);
    process.stderr.write(`${message}\n`);
    process.exitCode = 1;
  });
}