AntigravityInstallation.ts

// @effect-diagnostics nodeBuiltinImport:off - Effect has no incremental digest or free-space query.
import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
import * as ModelManifest from "./ModelManifest.ts";
import { resolveProviderCompatibility } from "./providerCompatibility.ts";
import { cliArchiveTarCommand } from "@t3tools/shared/cliRelease";
import { compareSemverVersions } from "@t3tools/shared/semver";
import * as EffectNodeStream from "@effect/platform-node/NodeStream";
import { ProviderDriverKind, type ProviderInstallState } from "@t3tools/contracts";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { resolveNodeExecutable, nodeRuntimeUnavailableMessage } from "@t3tools/shared/nodeRuntime";
import { resolveCommandPath } from "@t3tools/shared/shell";
import * as Clock from "effect/Clock";
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as SecureRandom from "effect/crypto/SecureRandom";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Fiber from "effect/Fiber";
import * as FileSystem from "effect/FileSystem";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import * as Path from "effect/Path";
import * as Schema from "effect/Schema";
import * as Schedule from "effect/Schedule";
import * as Scope from "effect/Scope";
import * as Semaphore from "effect/Semaphore";
import * as Stream from "effect/Stream";
import * as SubscriptionRef from "effect/SubscriptionRef";
import { HttpClient, HttpClientError, HttpClientRequest, HttpClientResponse } from "effect/http";
import * as ChildProcess from "effect/process/ChildProcess";
import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
import * as NodeCrypto from "node:crypto";
import * as NodeFSP from "node:fs/promises";
import * as EffectAcpErrors from "effect-acp/errors";

import * as ServerConfig from "../config.ts";
import * as ServerSettings from "../serverSettings.ts";
import {
  ANTIGRAVITY_CLI_MANIFEST_BASE,
  antigravityCliTarget,
  parseAntigravityCliRelease,
  type AntigravityCliReleaseAsset,
} from "./antigravityCliRelease.ts";
import { openZipArchive } from "../zipArchive.ts";
import { makeAntigravityAcpRuntime } from "./acp/AntigravityAcpSupport.ts";
import {
  buildAntigravityAcpSpawnInput,
  prepareAntigravityProfile,
} from "./antigravityAuthSupport.ts";
import { type AntigravityReleaseAsset } from "./antigravityRelease.ts";

const DRIVER = ProviderDriverKind.make("antigravity");
const DOWNLOAD_TIMEOUT = "45 minutes";
const VALIDATION_TIMEOUT = "90 seconds";
const MAX_DOWNLOAD_BYTES = 512 * 1024 * 1024;
const MAX_EXECUTABLE_BYTES = 512 * 1024 * 1024;
const UPDATE_CHECK_INTERVAL = 60 * 60 * 1000;
const FREE_SPACE_MARGIN = 256 * 1024 * 1024;
const RECORD_MAX_BYTES = 8 * 1024;
const RELEASE_RECORD = ".install-complete.json";
const LARGE_PAGE_KERNEL_MESSAGE =
  "Google's linux-arm64 Antigravity runtime needs a kernel with 4 KiB memory pages, and this kernel uses larger pages (as on Asahi Linux or Raspberry Pi 5). Use a remote environment or a custom Antigravity executable.";

const ReleaseId = Schema.String.check(Schema.isPattern(/^[a-f0-9]{64}$/u));
const ActiveRelease = Schema.Struct({ releaseId: ReleaseId });
const InstalledRelease = Schema.Struct({
  releaseId: ReleaseId,
  version: Schema.String,
  executable: Schema.Struct({ name: Schema.String, bytes: Schema.Number }),
  harness: Schema.NullOr(Schema.Struct({ name: Schema.String, bytes: Schema.Number })),
});
type InstalledRelease = typeof InstalledRelease.Type;
const encodeActiveRelease = Schema.encodeEffect(Schema.fromJsonString(ActiveRelease));
const encodeInstalledRelease = Schema.encodeEffect(Schema.fromJsonString(InstalledRelease));

export class AntigravityInstallationError extends Schema.TaggedError<AntigravityInstallationError>()(
  "AntigravityInstallationError",
  {
    operation: Schema.String,
    detail: Schema.String,
    cause: Schema.optional(Schema.Defect()),
  },
) {
  override get message() {
    return this.detail;
  }
}
const isInstallationError = Schema.is(AntigravityInstallationError);
const isAcpProcessExitedError = Schema.is(EffectAcpErrors.AcpProcessExitedError);

export interface AntigravityExecutable {
  readonly executablePath: string;
  /** Null for the `agy` CLI, which embeds the harness and runs as `agy acp`. */
  readonly harnessPath: string | null;
  readonly source: "override" | "managed" | "path";
  readonly version: string | null;
  readonly managedVersionDirectory: string | null;
}

interface AntigravityInstallationService {
  readonly managedDirectory: string;
  readonly resolve: (
    binaryPath?: string,
    environment?: NodeJS.ProcessEnv,
  ) => Effect.Effect<AntigravityExecutable, AntigravityInstallationError>;
  /** Hold the lease until the spawned process has exited. */
  readonly acquire: (
    binaryPath?: string,
    environment?: NodeJS.ProcessEnv,
  ) => Effect.Effect<AntigravityExecutable, AntigravityInstallationError, Scope.Scope>;
  readonly start: Effect.Effect<ProviderInstallState, AntigravityInstallationError>;
  readonly cancel: (
    operationId: string,
  ) => Effect.Effect<ProviderInstallState, AntigravityInstallationError>;
  readonly state: Effect.Effect<ProviderInstallState>;
  readonly changes: Stream.Stream<ProviderInstallState>;
  readonly checkForUpdate: Effect.Effect<void>;
  readonly remove: (
    protectedBinaryPaths?: ReadonlyArray<string>,
  ) => Effect.Effect<void, AntigravityInstallationError>;
}

export class AntigravityInstallation extends Context.Service<
  AntigravityInstallation,
  AntigravityInstallationService
>()("t3/provider/AntigravityInstallation") {
  static readonly layer = Layer.effect(
    AntigravityInstallation,
    Effect.gen(function* () {
      const config = yield* ServerConfig.ServerConfig;
      const settings = yield* ServerSettings.ServerSettingsService;
      return yield* makeAntigravityInstallation({
        baseDir: config.baseDir,
        updateChecksEnabled: settings.getSettings.pipe(
          Effect.map((value) => value.enableProviderUpdateChecks),
          Effect.orElseSucceed(() => false),
        ),
      });
    }),
  );
}

export interface AntigravityInstallationOptions {
  readonly baseDir: string;
  readonly releaseAsset?: AntigravityReleaseAsset | AntigravityCliReleaseAsset | null;
  readonly updateChecksEnabled?: Effect.Effect<boolean>;
  readonly validate?: (
    executable: AntigravityExecutable,
    expectedVersion: string,
  ) => Effect.Effect<void, AntigravityInstallationError, Scope.Scope>;
}

const installationError = (operation: string, detail: string, cause?: unknown) =>
  new AntigravityInstallationError({
    operation,
    detail,
    ...(cause === undefined ? {} : { cause }),
  });

const wrapFailure = (operation: string, detail: string) => (cause: unknown) =>
  isInstallationError(cause) ? cause : installationError(operation, detail, cause);

function executableNames(platform: NodeJS.Platform) {
  return platform === "win32"
    ? { executable: "agy_acp_server.exe", harness: "localharness_external.exe" }
    : { executable: "agy_acp_server.par", harness: "localharness_external" };
}

/** Antigravity CLI 1.5.0+ serves ACP itself (`agy acp`), so it has no `localharness_external` sibling. */
function isAntigravityCli(...candidates: ReadonlyArray<string>) {
  return candidates.some((candidate) =>
    /^(?:agy|antigravity)(?:\.(?:exe|cmd|bat))?$/iu.test(candidate.split(/[\\/]/u).at(-1) ?? ""),
  );
}

function isRunning(state: ProviderInstallState) {
  return (
    state.phase === "downloading" || state.phase === "extracting" || state.phase === "verifying"
  );
}

export const makeAntigravityInstallation = Effect.fn("AntigravityInstallation.make")(function* (
  options: AntigravityInstallationOptions,
) {
  const manifestService = yield* ModelManifest.ModelManifest;
  const fs = yield* FileSystem.FileSystem;
  const path = yield* Path.Path;
  const random = yield* SecureRandom.SecureRandom;
  const http = yield* HttpClient.HttpClient;
  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
  const serviceScope = yield* Effect.scope;
  const platform = yield* HostProcess.Platform;
  const arch = yield* HostProcess.Architecture;
  const environment = yield* HostProcess.Environment;
  let releaseAsset = options.releaseAsset ?? null;
  const supported =
    options.releaseAsset === undefined
      ? antigravityCliTarget(platform, arch) !== null
      : options.releaseAsset !== null;
  const names = executableNames(platform);
  const managedDirectory = path.join(
    options.baseDir,
    "tools",
    "antigravity-acp",
    `${platform}-${arch}`,
  );
  const versionsDirectory = path.join(managedDirectory, "versions");
  const activePath = path.join(managedDirectory, "active.json");
  const gate = yield* Semaphore.make(1);
  const leases = new Map<string, number>();
  let running: { readonly operationId: string; readonly fiber: Fiber.Fiber<void> } | undefined;
  const state = yield* SubscriptionRef.make<ProviderInstallState>({
    driver: DRIVER,
    operationId: null,
    phase: "idle",
    downloadedBytes: 0,
    totalBytes:
      releaseAsset !== null && "archiveBytes" in releaseAsset ? releaseAsset.archiveBytes : null,
    version: releaseAsset?.version ?? null,
    installedVersion: null,
    canRemove: false,
    message: null,
  });

  const isWithdrawn = Effect.fn("AntigravityInstallation.isWithdrawn")(function* (version: string) {
    const manifest = yield* manifestService.current;
    const status = (
      resolveProviderCompatibility(manifest.compatibility, DRIVER, version) ??
      resolveProviderCompatibility(
        ModelManifest.BUNDLED_MODEL_MANIFEST.compatibility,
        DRIVER,
        version,
      )
    )?.status;
    return status === "broken" || status === "unsupported";
  });
  const ensureEligible = Effect.fn("AntigravityInstallation.ensureEligible")(function* (
    version: string,
  ) {
    if (yield* isWithdrawn(version))
      return yield* installationError(
        "verify",
        "This Antigravity release was withdrawn. Check for updates and try again.",
      );
  });

  const readRecord = Effect.fn("AntigravityInstallation.readRecord")(function* <A>(
    filePath: string,
    schema: Schema.Codec<A>,
  ) {
    const info = yield* fs.stat(filePath);
    if (info.type !== "File" || Number(info.size) > RECORD_MAX_BYTES) {
      return yield* installationError(
        "resolve",
        "The managed runtime record is invalid. Reinstall Antigravity.",
      );
    }
    const contents = yield* fs.readFileString(filePath);
    return yield* Schema.decodeEffect(Schema.fromJsonString(schema))(contents);
  });

  const executableFile = Effect.fn("AntigravityInstallation.executableFile")(function* (
    filePath: string,
    bytes?: number,
  ) {
    const info = yield* fs.stat(filePath).pipe(Effect.option);
    return (
      Option.isSome(info) &&
      info.value.type === "File" &&
      (bytes === undefined || Number(info.value.size) === bytes) &&
      (platform === "win32" || (info.value.mode & 0o111) !== 0)
    );
  });

  const completedRelease = Effect.fn("AntigravityInstallation.completedRelease")(function* (
    releaseId: string,
  ) {
    const directory = path.join(versionsDirectory, releaseId);
    const record = yield* readRecord(path.join(directory, RELEASE_RECORD), InstalledRelease);
    if (
      record.releaseId !== releaseId ||
      (record.harness === null
        ? record.executable.name !== (platform === "win32" ? "agy.exe" : "antigravity")
        : record.executable.name !== names.executable || record.harness.name !== names.harness) ||
      !Number.isSafeInteger(record.executable.bytes) ||
      record.executable.bytes <= 0 ||
      (record.harness !== null &&
        (!Number.isSafeInteger(record.harness.bytes) || record.harness.bytes <= 0)) ||
      !record.version.trim() ||
      !(yield* executableFile(
        path.join(directory, record.executable.name),
        record.executable.bytes,
      )) ||
      (record.harness !== null &&
        !(yield* executableFile(path.join(directory, record.harness.name), record.harness.bytes)))
    ) {
      return yield* installationError(
        "resolve",
        "The managed Antigravity runtime is incomplete. Reinstall it.",
      );
    }
    return {
      executablePath: path.join(directory, record.executable.name),
      harnessPath: record.harness === null ? null : path.join(directory, record.harness.name),
      source: "managed",
      version: record.version,
      managedVersionDirectory: directory,
    } satisfies AntigravityExecutable;
  });

  const fromExternal = Effect.fn("AntigravityInstallation.fromExternal")(function* (
    candidate: string,
    source: "override" | "path",
  ) {
    if (!(yield* executableFile(candidate))) return null;
    const executablePath = yield* fs.realPath(candidate);
    const realVersions = yield* fs.realPath(versionsDirectory).pipe(Effect.option);
    const directory = path.dirname(executablePath);
    if (
      Option.isSome(realVersions) &&
      path.dirname(directory) === realVersions.value &&
      /^[a-f0-9]{64}$/u.test(path.basename(directory))
    ) {
      const installed = yield* completedRelease(path.basename(directory));
      return { ...installed, source };
    }
    // Keep launcher symlinks intact: version-manager shims dispatch by their invoked name.
    if (isAntigravityCli(candidate, executablePath)) {
      return {
        executablePath: candidate,
        harnessPath: null,
        source,
        version: null,
        managedVersionDirectory: null,
      } satisfies AntigravityExecutable;
    }
    const harnessPath = path.join(directory, names.harness);
    if (!(yield* executableFile(harnessPath))) return null;
    return {
      executablePath,
      harnessPath,
      source,
      version: null,
      managedVersionDirectory: null,
    } satisfies AntigravityExecutable;
  });

  const commandPath = (command: string, env: NodeJS.ProcessEnv) =>
    resolveCommandPath(command, { env }).pipe(
      Effect.map((resolved) => (resolved === null ? null : path.resolve(resolved))),
      Effect.provideService(HostProcess.Platform, platform),
      Effect.provideService(FileSystem.FileSystem, fs),
      Effect.provideService(Path.Path, path),
    );

  // Resolve per PATH entry so an executable without its harness falls through to later entries.
  const commandCandidates = Effect.fn("AntigravityInstallation.commandCandidates")(function* (
    command: string,
    processEnvironment = environment,
  ) {
    if (command.includes("/") || command.includes("\\")) {
      const resolved = yield* commandPath(command, processEnvironment);
      return resolved === null ? [] : [resolved];
    }
    const pathValue =
      platform === "win32"
        ? Object.entries(processEnvironment).findLast(([key]) => key.toUpperCase() === "PATH")?.[1]
        : processEnvironment.PATH;
    const candidates: string[] = [];
    for (const directory of (pathValue ?? "").split(platform === "win32" ? ";" : ":")) {
      const entry = directory.trim().replace(/^"|"$/gu, "");
      if (entry.length === 0) continue;
      const resolved = yield* commandPath(command, { ...processEnvironment, PATH: entry });
      if (resolved !== null) candidates.push(resolved);
    }
    return candidates;
  });

  const resolve: AntigravityInstallationService["resolve"] = Effect.fn(
    "AntigravityInstallation.resolve",
  )(
    function* (binaryPath?: string, processEnvironment?: NodeJS.ProcessEnv) {
      const override = expandHomePath(binaryPath?.trim() ?? "", yield* HostProcess.HomeDirectory);
      if (override) {
        for (const candidate of yield* commandCandidates(override, processEnvironment)) {
          const selected = yield* fromExternal(candidate, "override");
          if (selected) return selected;
        }
        return yield* installationError(
          "resolve",
          "The custom Antigravity executable is missing or not executable, or it needs a localharness_external sibling. The agy CLI does not.",
        );
      }
      if (yield* fs.exists(activePath)) {
        const active = yield* readRecord(activePath, ActiveRelease);
        const installed = yield* completedRelease(active.releaseId);
        if (yield* isWithdrawn(installed.version))
          return yield* installationError(
            "resolve",
            `Antigravity ${installed.version} no longer works with this T3 Code release. Update it in Antigravity setup.`,
          );
        return installed;
      }
      for (const candidate of yield* commandCandidates(names.executable, processEnvironment)) {
        const selected = yield* fromExternal(candidate, "path");
        if (selected) return selected;
      }
      return yield* installationError(
        "resolve",
        supported
          ? "Antigravity ACP runtime is not installed. Install it in this environment's provider settings or set a custom ACP executable path. The Antigravity app, IDE, and CLI are separate installations."
          : `Google does not publish an Antigravity runtime for ${platform}-${arch}. Use a supported environment or a custom executable.`,
      );
    },
    Effect.mapError(
      wrapFailure(
        "resolve",
        "Could not read the Antigravity installation. Reinstall it or set a custom executable path.",
      ),
    ),
  );

  const acquire = (binaryPath?: string, processEnvironment?: NodeJS.ProcessEnv) =>
    Effect.acquireRelease(
      gate.withPermit(
        Effect.gen(function* () {
          const executable = yield* resolve(binaryPath, processEnvironment);
          const directory = executable.managedVersionDirectory;
          if (directory) leases.set(directory, (leases.get(directory) ?? 0) + 1);
          return executable;
        }),
      ),
      (executable) =>
        gate.withPermit(
          Effect.sync(() => {
            const directory = executable.managedVersionDirectory;
            if (!directory) return;
            const remaining = (leases.get(directory) ?? 1) - 1;
            if (remaining > 0) leases.set(directory, remaining);
            else leases.delete(directory);
          }),
        ),
    );

  const validate =
    options.validate ??
    Effect.fn("AntigravityInstallation.validate")(
      function* (executable: AntigravityExecutable, expectedVersion: string) {
        const validationScope = yield* Effect.scope;
        const profileDirectory = yield* Effect.acquireRelease(
          fs.makeTempDirectory({ prefix: "t3-antigravity-validate-" }),
          (directory) =>
            fs.remove(directory, { recursive: true, force: true }).pipe(
              // Windows may retain DLL handles briefly after taskkill returns.
              Effect.retry({
                times: platform === "win32" ? 10 : 0,
                schedule: Schedule.spaced("100 millis"),
                while: (error) =>
                  error.reason._tag === "PermissionDenied" ||
                  error.reason._tag === "Busy" ||
                  error.reason._tag === "Unknown",
              }),
              Effect.orDie,
            ),
        );
        const profile = yield* prepareAntigravityProfile({
          profileDirectory,
          platform,
          baseEnv: environment,
          // A shallow scoped profile cleans up unpacked files within Windows' path limit.
          tempDirectory: profileDirectory,
        });
        const runtime = yield* makeAntigravityAcpRuntime({
          runtimeVersion: expectedVersion,
          spawn: buildAntigravityAcpSpawnInput({
            installation: executable,
            profile,
            cwd: profileDirectory,
            baseEnv: environment,
          }),
          cwd: profileDirectory,
          childProcessSpawner:
            platform === "win32"
              ? ChildProcessSpawner.make(
                  Effect.fnUntraced(function* (command) {
                    const child = yield* spawner.spawn(command);
                    // Stop PyInstaller's tree before ACP closes pipes; after launcher exit, taskkill cannot reach children holding DLLs open.
                    yield* Scope.addFinalizer(
                      validationScope,
                      child.kill({ forceKillAfter: "1 second" }).pipe(Effect.orDie),
                    );
                    return child;
                  }),
                )
              : spawner,
        });
        const initialized = yield* runtime.initialize();
        if (
          (executable.harnessPath === null
            ? initialized.agentInfo?.name !== "Antigravity ACP Server"
            : initialized.agentInfo?.name !== "antigravity-acp") ||
          initialized.agentInfo?.version !== expectedVersion ||
          // Antigravity 1.1.1 may report protocol 2 with legacy ACP; choose wire format from the response shape.
          (initialized.protocolVersion !== 1 && initialized.protocolVersion !== 2) ||
          initialized.agentCapabilities?.loadSession !== true ||
          !initialized.agentCapabilities.sessionCapabilities?.resume ||
          !initialized.agentCapabilities.auth?.logout ||
          !initialized.authMethods?.some((method) => method.id === "oauth-personal")
        ) {
          return yield* installationError(
            "verify",
            "The downloaded runtime did not identify as the expected Google Antigravity release.",
          );
        }
      },
      Effect.provideService(FileSystem.FileSystem, fs),
      Effect.provideService(Path.Path, path),
      Effect.provideService(ChildProcessSpawner.ChildProcessSpawner, spawner),
      Effect.provideService(SecureRandom.SecureRandom, random),
      Effect.mapError((cause) => {
        if (isInstallationError(cause)) return cause;
        const stderr = isAcpProcessExitedError(cause) ? (cause.stderr ?? "") : "";
        const detail = /\b(?:AF_INET6|enforce_kernel_ipv6_support)\b/.test(stderr)
          ? "Antigravity requires IPv6 socket support. Enable IPv6 in this environment. On WSL, remove ipv6.disable=1 from .wslconfig and run wsl --shutdown."
          : /page-size\.cc|Compile-time page size does not match/.test(stderr)
            ? LARGE_PAGE_KERNEL_MESSAGE
            : "The downloaded Antigravity runtime could not start in this environment.";
        return installationError("verify", detail, cause);
      }),
    );

  const install = Effect.fn("AntigravityInstallation.install")(
    function* (asset: AntigravityReleaseAsset | AntigravityCliReleaseAsset) {
      yield* ensureEligible(asset.version);
      const cli = "sha512" in asset;
      // Existing installation records use 64-character IDs, including native SHA-512 prefixes.
      const releaseId = cli ? asset.sha512.slice(0, 64) : asset.sha256;
      const archiveBytes = cli ? null : asset.archiveBytes;
      yield* resolveNodeExecutable("Antigravity", environment).pipe(
        Effect.provideService(FileSystem.FileSystem, fs),
        Effect.provideService(Path.Path, path),
        Effect.provideService(HostProcess.Platform, platform),
        Effect.mapError((cause) =>
          installationError("verify", nodeRuntimeUnavailableMessage("Antigravity"), cause),
        ),
      );
      if (!cli && platform === "linux" && arch === "arm64") {
        const pageSize = yield* spawner
          .string(ChildProcess.make("getconf", ["PAGESIZE"], { stdin: "ignore", stderr: "ignore" }))
          .pipe(
            Effect.map((output) => Number(output.trim())),
            Effect.timeout("5 seconds"),
            Effect.orElseSucceed(() => Number.NaN),
          );
        if (pageSize > 4096) {
          return yield* installationError("download", LARGE_PAGE_KERNEL_MESSAGE);
        }
      }
      const report = (phase: ProviderInstallState["phase"], message: string | null) =>
        SubscriptionRef.update(state, (current) => ({ ...current, phase, message }));
      yield* fs.makeDirectory(versionsDirectory, { recursive: true });
      yield* SubscriptionRef.update(state, (current) => ({ ...current, canRemove: true }));
      const destination = path.join(versionsDirectory, releaseId);
      const activate = Effect.fn("AntigravityInstallation.activate")(
        function* () {
          yield* ensureEligible(asset.version);
          const pointerDirectory = yield* fs.makeTempDirectoryScoped({
            directory: managedDirectory,
            prefix: "active.json.",
          });
          const pointerPath = path.join(pointerDirectory, "contents.tmp");
          yield* fs.writeFileString(pointerPath, yield* encodeActiveRelease({ releaseId }), {
            flag: "wx",
            mode: 0o600,
          });
          yield* fs.rename(pointerPath, activePath);
          yield* SubscriptionRef.update(
            state,
            (current) =>
              ({
                ...current,
                phase: "succeeded",
                installedVersion: asset.version,
                message: null,
              }) satisfies ProviderInstallState,
          );
        },
        Effect.scoped,
        Effect.mapError(
          wrapFailure(
            "activate",
            "Could not activate Antigravity. The previous runtime is unchanged. Check for locked files and try again.",
          ),
        ),
        Effect.uninterruptible,
      );

      if (yield* fs.exists(destination)) {
        const existing = yield* completedRelease(releaseId);
        if (existing.version !== asset.version) {
          return yield* installationError(
            "verify",
            "The existing managed release has the wrong version. Remove it before reinstalling.",
          );
        }
        yield* report("verifying", "Checking the installed runtime.");
        yield* validate(existing, asset.version).pipe(
          Effect.scoped,
          Effect.timeout(VALIDATION_TIMEOUT),
        );
        yield* activate();
        return;
      }

      const available = yield* Effect.tryPromise({
        try: () => NodeFSP.statfs(versionsDirectory, { bigint: true }),
        catch: (cause) => installationError("download", "Could not check free disk space.", cause),
      }).pipe(Effect.option);
      const required = cli
        ? MAX_DOWNLOAD_BYTES + MAX_EXECUTABLE_BYTES + FREE_SPACE_MARGIN
        : asset.archiveBytes + asset.executable.bytes + asset.harness.bytes + FREE_SPACE_MARGIN;
      if (
        Option.isSome(available) &&
        available.value.bavail * available.value.bsize < BigInt(required)
      ) {
        return yield* installationError(
          "download",
          `Antigravity needs at least ${Math.ceil(required / 1024 / 1024)} MiB of free space to install.`,
        );
      }
      const staging = yield* fs.makeTempDirectoryScoped({
        directory: versionsDirectory,
        prefix: ".install-",
      });
      const archivePath = path.join(staging, "download.zip");
      const pairDirectory = path.join(staging, "runtime");
      yield* fs.makeDirectory(pairDirectory);
      const hash = NodeCrypto.createHash(cli ? "sha512" : "sha256");
      let downloadedBytes = 0;
      let lastProgressAt = yield* Clock.currentTimeMillis;
      yield* Effect.gen(function* () {
        const response = yield* http
          .execute(HttpClientRequest.get(asset.url))
          .pipe(Effect.flatMap(HttpClientResponse.filterStatusOk));
        // dl.google.com may gzip the zip: content-length is encoded, while byte/hash checks use decoded data.
        const contentLength = response.headers["content-length"];
        const contentEncoding = response.headers["content-encoding"]?.trim().toLowerCase();
        const identityBody = contentEncoding === undefined || contentEncoding === "identity";
        if (
          identityBody &&
          contentLength !== undefined &&
          archiveBytes !== null &&
          Number(contentLength) !== archiveBytes
        ) {
          return yield* installationError(
            "download",
            "The Antigravity download size did not match the pinned release.",
          );
        }
        yield* response.stream.pipe(
          Stream.tap((chunk) =>
            Effect.gen(function* () {
              downloadedBytes += chunk.byteLength;
              if (downloadedBytes > (archiveBytes ?? MAX_DOWNLOAD_BYTES)) {
                return yield* installationError(
                  "download",
                  "The Antigravity download exceeded its allowed size.",
                );
              }
              hash.update(chunk);
              const now = yield* Clock.currentTimeMillis;
              if (now - lastProgressAt >= 250 || downloadedBytes === archiveBytes) {
                lastProgressAt = now;
                yield* SubscriptionRef.update(state, (current) => ({
                  ...current,
                  downloadedBytes,
                }));
              }
            }),
          ),
          Stream.run(fs.sink(archivePath, { flag: "wx", mode: 0o600 })),
        );
      }).pipe(
        Effect.timeout(DOWNLOAD_TIMEOUT),
        Effect.mapError((cause) =>
          HttpClientError.isHttpClientError(cause) || Cause.isTimeoutError(cause)
            ? installationError(
                "download",
                "Could not download Antigravity from Google. Check the network connection and any proxy settings, then try again.",
                cause,
              )
            : cause,
        ),
      );
      if (
        (archiveBytes !== null && downloadedBytes !== archiveBytes) ||
        hash.digest("hex") !== (cli ? asset.sha512 : asset.sha256)
      ) {
        return yield* installationError(
          "download",
          "The Antigravity download failed its size or checksum check. Nothing was installed.",
        );
      }

      yield* report("extracting", "Extracting the verified runtime.");
      if (cli) {
        const executablePath = path.join(pairDirectory, asset.executable.name);
        if (asset.format === "executable") {
          yield* fs.copyFile(archivePath, executablePath);
        } else {
          const tar = cliArchiveTarCommand(platform, environment);
          const list = yield* spawner.string(ChildProcess.make(tar, ["-tzf", archivePath]));
          const types = yield* spawner.string(ChildProcess.make(tar, ["-tvzf", archivePath]));
          if (
            list.trim() !== asset.executable.name ||
            types.trim().split(/\r?\n/u).length !== 1 ||
            !types.startsWith("-")
          ) {
            return yield* installationError(
              "extract",
              "The Antigravity archive must contain one regular executable.",
            );
          }
          yield* Effect.gen(function* () {
            const child = yield* spawner.spawn(
              ChildProcess.make(tar, ["-xOzf", archivePath, asset.executable.name], {
                stdout: "pipe",
                stderr: "pipe",
              }),
            );
            let extractedBytes = 0;
            yield* child.stdout.pipe(
              Stream.tap((chunk) =>
                Effect.gen(function* () {
                  extractedBytes += chunk.byteLength;
                  if (extractedBytes > MAX_EXECUTABLE_BYTES)
                    return yield* installationError(
                      "extract",
                      "The Antigravity executable exceeded its size limit.",
                    );
                }),
              ),
              Stream.run(fs.sink(executablePath, { flag: "wx", mode: 0o700 })),
            );
            if ((yield* child.exitCode) !== 0 || extractedBytes === 0)
              return yield* installationError(
                "extract",
                "Could not extract the Antigravity executable.",
              );
          }).pipe(Effect.scoped);
        }
      } else
        yield* Effect.gen(function* () {
          const archive = yield* openZipArchive(archivePath, (detail, cause) =>
            installationError("extract", detail, cause),
          );
          if (archive.entryCount !== 2) {
            return yield* installationError(
              "extract",
              "The archive must contain exactly the Antigravity executable and its harness.",
            );
          }
          const seen = new Set<string>();
          for (;;) {
            const entry = yield* archive.next;
            if (!entry) break;
            const expected = [asset.executable, asset.harness].find(
              (file) => file.name === entry.fileName,
            );
            const unixType = (entry.externalFileAttributes >>> 16) & 0o170000;
            if (
              !expected ||
              seen.has(entry.fileName) ||
              entry.fileName.includes("/") ||
              entry.fileName.includes("\\") ||
              (unixType !== 0 && unixType !== 0o100000) ||
              (entry.externalFileAttributes & 0x10) !== 0 ||
              (entry.generalPurposeBitFlag & 1) !== 0 ||
              ![0, 8].includes(entry.compressionMethod) ||
              entry.uncompressedSize !== expected.bytes
            ) {
              return yield* installationError(
                "extract",
                "The archive contains an unexpected, unsafe, or incorrectly sized member.",
              );
            }
            seen.add(entry.fileName);
            yield* Effect.gen(function* () {
              const readable = yield* archive.streamEntry(entry);
              let extractedBytes = 0;
              yield* EffectNodeStream.fromReadable<Uint8Array, AntigravityInstallationError>({
                evaluate: () => readable,
                onError: wrapFailure("extract", "Could not extract the Antigravity runtime."),
              }).pipe(
                Stream.tap((chunk) =>
                  Effect.gen(function* () {
                    extractedBytes += chunk.byteLength;
                    if (extractedBytes > expected.bytes) {
                      return yield* installationError(
                        "extract",
                        "An archive member exceeded its pinned size.",
                      );
                    }
                  }),
                ),
                Stream.run(
                  fs.sink(path.join(pairDirectory, entry.fileName), { flag: "wx", mode: 0o700 }),
                ),
              );
              if (extractedBytes !== expected.bytes) {
                return yield* installationError("extract", "An archive member was truncated.");
              }
            }).pipe(Effect.scoped);
          }
          if (!seen.has(asset.executable.name) || !seen.has(asset.harness.name)) {
            return yield* installationError(
              "extract",
              "The archive is missing the Antigravity executable or its harness.",
            );
          }
        }).pipe(Effect.scoped);
      yield* fs.remove(archivePath);
      const executablePath = path.join(pairDirectory, asset.executable.name);
      const harnessPath = cli ? null : path.join(pairDirectory, asset.harness.name);
      if (platform !== "win32") {
        yield* fs.chmod(executablePath, 0o755);
        if (harnessPath !== null) yield* fs.chmod(harnessPath, 0o755);
      }
      if (!cli && platform === "darwin" && arch === "x64") {
        // Google signs the Intel build with the hardened runtime but no JIT entitlement, so
        // libffi's writable+executable trampolines spin forever. Re-sign ad hoc after the hash check.
        const exitCode = yield* spawner
          .spawn(
            ChildProcess.make(
              "/usr/bin/codesign",
              [
                "--force",
                "--sign",
                "-",
                executablePath,
                ...(harnessPath === null ? [] : [harnessPath]),
              ],
              { stdout: "ignore", stderr: "ignore" },
            ),
          )
          .pipe(
            Effect.flatMap((child) => child.exitCode),
            Effect.scoped,
          );
        if (exitCode !== 0) {
          return yield* installationError(
            "extract",
            "Could not prepare the Antigravity runtime for this Mac. Check that codesign is available.",
          );
        }
      }
      yield* report("verifying", "Checking the downloaded runtime.");
      yield* validate(
        {
          executablePath,
          harnessPath,
          source: "managed",
          version: asset.version,
          managedVersionDirectory: pairDirectory,
        },
        asset.version,
      ).pipe(Effect.scoped, Effect.timeout(VALIDATION_TIMEOUT));
      const record: InstalledRelease = {
        releaseId,
        version: asset.version,
        executable: {
          name: asset.executable.name,
          bytes: Number((yield* fs.stat(executablePath)).size),
        },
        harness:
          cli || harnessPath === null
            ? null
            : { name: asset.harness.name, bytes: Number((yield* fs.stat(harnessPath)).size) },
      };
      yield* fs.writeFileString(
        path.join(pairDirectory, RELEASE_RECORD),
        yield* encodeInstalledRelease(record),
        { flag: "wx", mode: 0o600 },
      );
      yield* fs.rename(pairDirectory, destination).pipe(
        Effect.catch((cause) =>
          completedRelease(releaseId).pipe(
            Effect.flatMap((existing) =>
              existing.version === asset.version
                ? validate(existing, asset.version).pipe(
                    Effect.scoped,
                    Effect.timeout(VALIDATION_TIMEOUT),
                  )
                : Effect.fail(
                    installationError(
                      "activate",
                      "Another installation published a different Antigravity release.",
                    ),
                  ),
            ),
            Effect.mapError(() =>
              installationError(
                "activate",
                "Could not publish the Antigravity runtime. The previous release is unchanged. Try again.",
                cause,
              ),
            ),
          ),
        ),
      );
      yield* activate();
    },
    Effect.scoped,
    Effect.mapError(
      wrapFailure(
        "install",
        "Could not install Antigravity. Check free disk space and directory access, then try again.",
      ),
    ),
  );

  let lastUpdateCheck: number | undefined;
  const refreshRelease = Effect.fn("AntigravityInstallation.refreshRelease")(function* (
    explicit = false,
  ) {
    if (options.releaseAsset !== undefined || !supported) return;
    if (!explicit && !(yield* options.updateChecksEnabled ?? Effect.succeed(true))) return;
    const now = yield* Clock.currentTimeMillis;
    if (!explicit && lastUpdateCheck !== undefined && now - lastUpdateCheck < UPDATE_CHECK_INTERVAL)
      return;
    lastUpdateCheck = now;
    const musl =
      platform === "linux" &&
      (yield* fs.exists(
        arch === "arm64" ? "/lib/libc.musl-aarch64.so.1" : "/lib/libc.musl-x86_64.so.1",
      ));
    const target = antigravityCliTarget(platform, arch, musl);
    const latest = yield* http.get(`${ANTIGRAVITY_CLI_MANIFEST_BASE}/${target}.json`).pipe(
      Effect.flatMap(HttpClientResponse.filterStatusOk),
      Effect.flatMap((response) => response.json),
      Effect.map((json) => parseAntigravityCliRelease(json, platform, arch, musl)),
      Effect.timeout("10 seconds"),
      Effect.orElseSucceed(() => null),
    );
    if (latest === null) return;
    if (yield* isWithdrawn(latest.version)) {
      releaseAsset = null;
      return;
    }
    releaseAsset = latest;
    yield* SubscriptionRef.updateEffect(state, (value) =>
      isRunning(value)
        ? Effect.succeed(value)
        : Effect.gen(function* () {
            const keepInstalled =
              value.installedVersion !== null &&
              compareSemverVersions(value.installedVersion, latest.version) > 0 &&
              !(yield* isWithdrawn(value.installedVersion));
            return {
              ...value,
              version: keepInstalled ? value.installedVersion : latest.version,
              totalBytes: null,
            };
          }),
    );
  });

  const start = Effect.gen(function* () {
    const current = yield* SubscriptionRef.get(state);
    if (isRunning(current)) return current;
    yield* refreshRelease(true);
    return yield* gate.withPermit(
      Effect.gen(function* () {
        const current = yield* SubscriptionRef.get(state);
        if (isRunning(current)) return current;
        if (!supported) {
          return yield* installationError(
            "start",
            `Google does not publish an Antigravity runtime for ${platform}-${arch}. Use a supported remote environment or a custom executable.`,
          );
        }
        const asset =
          releaseAsset !== null && !(yield* isWithdrawn(releaseAsset.version))
            ? releaseAsset
            : null;
        const installed = yield* resolve().pipe(Effect.option);
        const reuse =
          Option.isSome(installed) &&
          installed.value.source === "managed" &&
          installed.value.harnessPath === null &&
          (asset === null || compareSemverVersions(installed.value.version!, asset.version) > 0)
            ? installed.value
            : undefined;
        if (asset === null && reuse === undefined)
          return yield* installationError(
            "start",
            "Could not find a native Antigravity CLI release. Check the network connection and try again.",
          );
        const operationId = yield* random.uuidV4();
        const next: ProviderInstallState = {
          driver: DRIVER,
          operationId,
          phase: reuse === undefined ? "downloading" : "verifying",
          downloadedBytes: 0,
          totalBytes: asset !== null && "archiveBytes" in asset ? asset.archiveBytes : null,
          version: reuse?.version ?? asset?.version ?? null,
          installedVersion: current.installedVersion,
          canRemove: current.canRemove,
          message:
            reuse === undefined
              ? "Downloading Google's official Antigravity runtime."
              : "Checking the installed runtime.",
        };
        yield* SubscriptionRef.set(state, next);
        const work = (
          reuse === undefined
            ? install(asset!)
            : validate(reuse, reuse.version!).pipe(
                Effect.scoped,
                Effect.timeout(VALIDATION_TIMEOUT),
                Effect.andThen(ensureEligible(reuse.version!)),
                Effect.andThen(
                  SubscriptionRef.update(state, (value) => ({
                    ...value,
                    phase: "succeeded" as const,
                    installedVersion: reuse.version,
                    message: null,
                  })),
                ),
              )
        ).pipe(
          Effect.mapError(
            wrapFailure("verify", "Could not verify the installed Antigravity runtime."),
          ),
          Effect.onExit((exit) =>
            Exit.isFailure(exit)
              ? SubscriptionRef.update(state, (value) => {
                  if (value.operationId !== operationId || value.phase === "succeeded")
                    return value;
                  const error = Cause.findErrorOption(exit.cause);
                  const cancelled = Cause.hasInterruptsOnly(exit.cause);
                  return {
                    ...value,
                    phase: cancelled ? "cancelled" : "failed",
                    message: cancelled
                      ? "Installation cancelled. The previous runtime is unchanged."
                      : Option.isSome(error)
                        ? error.value.detail
                        : "Could not finish the Antigravity installation. Check disk space and directory access.",
                  } satisfies ProviderInstallState;
                })
              : Effect.void,
          ),
          Effect.ignoreCause,
          Effect.ensuring(
            Effect.sync(() => {
              if (running?.operationId === operationId) running = undefined;
            }),
          ),
        );
        const fiber = yield* Effect.forkIn(Effect.interruptible(work), serviceScope);
        running = { operationId, fiber };
        return next;
      }).pipe(Effect.uninterruptible),
    );
  }).pipe(Effect.mapError(wrapFailure("start", "Could not start the Antigravity installation.")));

  const cancel = Effect.fn("AntigravityInstallation.cancel")(function* (operationId: string) {
    return yield* gate.withPermit(
      Effect.gen(function* () {
        const current = yield* SubscriptionRef.get(state);
        if (current.operationId !== operationId) {
          return yield* installationError(
            "cancel",
            "This installation is no longer current. Refresh its status before cancelling.",
          );
        }
        if (running?.operationId === operationId && isRunning(current)) {
          yield* Fiber.interrupt(running.fiber);
        }
        return yield* SubscriptionRef.get(state);
      }),
    );
  });

  const remove = Effect.fn("AntigravityInstallation.remove")(
    function* (protectedBinaryPaths: ReadonlyArray<string> = []) {
      yield* gate.withPermit(
        Effect.gen(function* () {
          if (isRunning(yield* SubscriptionRef.get(state)) || leases.size > 0) {
            return yield* installationError(
              "remove",
              "Stop Antigravity sessions and sign-in flows before removing its managed runtime.",
            );
          }
          const realManaged = yield* fs.realPath(managedDirectory).pipe(Effect.option);
          if (Option.isSome(realManaged)) {
            for (const binaryPath of protectedBinaryPaths) {
              if (!binaryPath.trim()) continue;
              const selected = yield* resolve(binaryPath).pipe(Effect.option);
              if (Option.isSome(selected) && selected.value.managedVersionDirectory) {
                return yield* installationError(
                  "remove",
                  "A provider instance has a custom path inside this managed runtime. Clear that path before removing it.",
                );
              }
              const resolved = yield* fs.realPath(binaryPath).pipe(Effect.option);
              const candidate = Option.getOrElse(resolved, () => path.resolve(binaryPath));
              if (candidate.startsWith(`${realManaged.value}${path.sep}`)) {
                return yield* installationError(
                  "remove",
                  "A provider instance has a custom path inside this managed runtime. Clear that path before removing it.",
                );
              }
            }
          }
          yield* fs.remove(managedDirectory, { recursive: true, force: true });
          yield* SubscriptionRef.update(
            state,
            (current) =>
              ({
                ...current,
                operationId: null,
                phase: "idle",
                downloadedBytes: 0,
                installedVersion: null,
                canRemove: false,
                message: null,
              }) satisfies ProviderInstallState,
          );
        }).pipe(Effect.uninterruptible),
      );
    },
    Effect.mapError(
      wrapFailure(
        "remove",
        "Could not remove the managed Antigravity runtime. Check for open processes and try again.",
      ),
    ),
  );

  yield* Effect.gen(function* () {
    const canRemove = yield* fs.exists(managedDirectory);
    yield* SubscriptionRef.update(state, (current) => ({ ...current, canRemove }));
    if (!(yield* fs.exists(activePath))) return;
    const active = yield* readRecord(activePath, ActiveRelease);
    const installed = yield* completedRelease(active.releaseId);
    yield* SubscriptionRef.update(state, (current) => ({
      ...current,
      installedVersion: installed.version,
    }));
  }).pipe(
    Effect.catch(() =>
      SubscriptionRef.update(
        state,
        (current) =>
          ({
            ...current,
            phase: "failed",
            message: "The managed Antigravity runtime is incomplete. Remove it and reinstall.",
          }) satisfies ProviderInstallState,
      ),
    ),
  );

  return AntigravityInstallation.of({
    managedDirectory,
    resolve,
    acquire,
    start,
    cancel,
    state: SubscriptionRef.get(state),
    changes: SubscriptionRef.changes(state),
    checkForUpdate: refreshRelease().pipe(Effect.ignore),
    remove,
  });
});