@prismatic-io/lux 0.0.2-preview.27 → 0.0.2-preview.28

package/src/core/case.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import type { AssertionPlugin } from "./assertion.js";
 import { collectEvalCaseExtensions, setEvalCaseExtensions } from "./case-authoring-state.js";
 import { DriverCapabilitySchema } from "./driver.js";
+import { DriverExecutionSchema } from "./driver-execution.js";
 import { EvaluationMetadataSchema } from "./evaluation-clusters.js";
 import { HarnessMatrixSchema } from "./harness-matrix.js";
 import type { LifecycleHooksPlugin } from "./lifecycle-hooks.js";
@@ -20,7 +21,13 @@ export type FixturesRef = z.infer<typeof FixturesRefSchema>;
 // `defineEvalCase` discriminate the config type on `name`.
 export const DriverRefSchema = z.union([
   z.string(),
-  z.object({ name: z.string(), config: z.unknown().optional() }).strict(),
+  z
+    .object({
+      name: z.string(),
+      config: z.unknown().optional(),
+      execution: DriverExecutionSchema.optional(),
+    })
+    .strict(),
 ]);
 export type DriverRef = z.infer<typeof DriverRefSchema>;
 

package/src/core/driver-execution.ts

@@ -0,0 +1,84 @@
+import { z } from "zod";
+
+const homePath = z
+  .string()
+  .min(1)
+  .refine(
+    (value) =>
+      !value.startsWith("/") &&
+      !value.includes("\\") &&
+      value.split("/").every((part) => part !== ".." && part !== "." && part !== ""),
+    "must be a relative path within the container home",
+  );
+
+export const ContainerExecutionSchema = z
+  .object({
+    kind: z.literal("container"),
+    /** A locally available image containing Lux and the selected Linux harness. */
+    image: z.string().min(1),
+    command: z.string().min(1).optional(),
+    /** The worker shipped with the same Lux build as the host. */
+    worker: z.string().min(1).optional(),
+    /** Optional module in the image exporting a custom DriverPlugin as default. */
+    driverModule: z.string().min(1).optional(),
+    mounts: z
+      .array(
+        z
+          .object({
+            source: z.string().min(1),
+            target: z.string().min(1).optional(),
+            readOnly: z.boolean().optional(),
+          })
+          .strict(),
+      )
+      .optional(),
+    /** Only these host environment variables enter the container. */
+    passEnv: z.array(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/)).optional(),
+    env: z.record(z.string().regex(/^[A-Za-z_][A-Za-z0-9_]*$/), z.string()).optional(),
+    /** Private copies, never host-home mounts; deleted after the run. */
+    homeFiles: z
+      .array(
+        z
+          .object({
+            destination: homePath,
+            source: z.discriminatedUnion("kind", [
+              z.object({ kind: z.literal("file"), path: z.string().min(1) }).strict(),
+              z
+                .object({
+                  kind: z.literal("keychain"),
+                  service: z.string().min(1),
+                  account: z.string().min(1),
+                  encoding: z.enum(["utf8", "go-keyring-base64"]).optional(),
+                })
+                .strict(),
+            ]),
+          })
+          .strict(),
+      )
+      .max(32)
+      .optional(),
+    network: z.enum(["bridge", "none"]).optional(),
+    user: z.string().min(1).optional(),
+    memory: z
+      .string()
+      .regex(/^[1-9][0-9]*[bkmgt]?$/i)
+      .optional(),
+    cpus: z.number().positive().optional(),
+    pidsLimit: z.number().int().positive().optional(),
+    startupTimeoutMs: z.number().int().positive().optional(),
+  })
+  .strict();
+
+export const DriverExecutionSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("host") }).strict(),
+  ContainerExecutionSchema,
+]);
+export type DriverExecution = z.infer<typeof DriverExecutionSchema>;
+export type ContainerExecution = z.infer<typeof ContainerExecutionSchema>;
+
+export const driverExecutionOf = (reference: unknown): DriverExecution | undefined => {
+  if (!reference || typeof reference !== "object" || !("execution" in reference)) return undefined;
+  return reference.execution === undefined
+    ? undefined
+    : DriverExecutionSchema.parse(reference.execution);
+};

package/src/core/driver.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { DriverExecution } from "./driver-execution.js";
 import type { EventHandler } from "./emitter.js";
 import type { Answer, Done, ErrorEvent, Interrupt, Progress, ReadyState } from "./events.js";
 import type { ReasoningEffort } from "./harness-catalog.js";
@@ -28,6 +29,8 @@ export type ResolvedFixtures = z.infer<typeof ResolvedFixturesSchema>;
 export type StartContext = {
   /** Stable selected case id, available to drivers that multiplex scenarios. */
   caseId?: string;
+  /** Private home owned by an outer execution boundary; never the caller’s home. */
+  isolatedHome?: string;
   prompt: string;
   fixtures?: ResolvedFixtures | undefined;
   /** Authored fixture values selected for this case. */
@@ -139,4 +142,9 @@ export const defineDriver = <S extends z.ZodType>(
 export const driverRef = <S extends z.ZodType>(
   plugin: { name: string; configSchema: S },
   config: z.input<S>,
-): { name: string; config: z.input<S> } => ({ name: plugin.name, config });
+  execution?: DriverExecution,
+): { name: string; config: z.input<S>; execution?: DriverExecution } => ({
+  name: plugin.name,
+  config,
+  ...(execution ? { execution } : {}),
+});

package/src/core/harness-matrix.ts

@@ -1,6 +1,11 @@
 import { z } from "zod";
 import type { DriverRef } from "./case.js";
 import type { DriverPlugin } from "./driver.js";
+import {
+  type DriverExecution,
+  DriverExecutionSchema,
+  driverExecutionOf,
+} from "./driver-execution.js";
 import {
   type CatalogModels,
   catalogEfforts,
@@ -24,6 +29,7 @@ type CatalogEntry<C extends HarnessCatalog> = {
   models: C["models"] extends CatalogModels ? (keyof C["models"] & string)[] : string[];
   efforts?: C["efforts"][number][];
   config?: unknown;
+  execution?: DriverExecution;
 };
 
 export type BuiltInHarnessMatrixEntry = {
@@ -37,6 +43,7 @@ export type CustomHarnessMatrixEntry = {
   models?: string[];
   efforts?: ReasoningEffort[];
   config?: unknown;
+  execution?: DriverExecution;
 };
 
 export type HarnessMatrixEntry = BuiltInHarnessMatrixEntry | CustomHarnessMatrixEntry;
@@ -54,6 +61,7 @@ const catalogEntrySchema = (catalog: HarnessCatalog) => {
       models: z.array(models).min(1),
       efforts: z.array(nonEmptyEnum(catalog.efforts)).min(1).optional(),
       config: z.unknown().optional(),
+      execution: DriverExecutionSchema.optional(),
     })
     .strict()
     .superRefine((entry, ctx) => {
@@ -86,6 +94,7 @@ const CustomHarnessMatrixEntrySchema = z
     models: z.array(z.string().min(1)).min(1).optional(),
     efforts: z.array(ReasoningEffortSchema).min(1).optional(),
     config: z.unknown().optional(),
+    execution: DriverExecutionSchema.optional(),
   })
   .strict();
 
@@ -109,6 +118,7 @@ export type HarnessPermutation = {
   model?: string | undefined;
   effort?: ReasoningEffort | undefined;
   config?: unknown;
+  execution?: DriverExecution;
 };
 
 export const permutationId = (permutation: HarnessPermutation): string =>
@@ -125,6 +135,7 @@ const entryPermutation = (
   ...(model !== undefined ? { model } : {}),
   ...(effort !== undefined ? { effort } : {}),
   ...(entry.config !== undefined ? { config: entry.config } : {}),
+  ...(entry.execution !== undefined ? { execution: entry.execution } : {}),
 });
 
 const expandEntry = (entry: HarnessMatrixEntry): HarnessPermutation[] => {
@@ -294,5 +305,12 @@ export const permutationDriverRef = (
     }
     config = plugin.selectHarness(config, { model: selected.model, effort: selected.effort });
   }
-  return config === undefined ? selected.driver : { name: selected.driver, config };
+  const execution =
+    selected.execution ??
+    (fallback && driverNameOf(fallback) === selected.driver
+      ? driverExecutionOf(fallback)
+      : undefined);
+  return config === undefined && execution === undefined
+    ? selected.driver
+    : { name: selected.driver, config, ...(execution ? { execution } : {}) };
 };

package/src/drivers/antigravity/README.md

@@ -32,7 +32,7 @@ response is also retained as message evidence when it was not already streamed.
 Both `DONE` and `ERROR` tool steps close the corresponding tool call; failed
 steps retain their error message. A result with `denied_actions` is an error even
 when Antigravity reports `SUCCESS`. `WAITING` and other non-success statuses are
-also errors. Configure the required scoped permissions in Antigravity before a
+also errors. Configure the required scoped permissions for the
 headless evaluation; Lux does not retry a denial with broader permissions.
 
 Lux explicitly selects `mode: "accept-edits"` for coding tasks. Set `mode: "plan"`
@@ -41,14 +41,61 @@ workspaces read-only even when native file tools can edit them and scoped write
 grants exist. `accept-edits` permits workspace writes within the terminal sandbox;
 it does not disable that sandbox or authorize outside-sandbox execution.
 
-For sandboxed headless coding, set `sandbox: true` and configure the CLI with
-`enableTerminalSandbox: true` and `toolPermission: "proceed-in-sandbox"`.
+## Run-scoped configuration
+
+Lux can own the CLI settings for a run:
+
+```ts
+{
+  name: "antigravity",
+  config: {
+    model: "gemini-3.1-pro",
+    reasoningEffort: "low",
+    sandbox: true,
+    permissionMode: "proceed-in-sandbox",
+    permissions: { allow: ["read_url(registry.npmjs.org)"] },
+  },
+}
+```
+
+This mode gives only the child process a private home directory. Lux writes
+`enableTerminalSandbox: true`, `toolPermission: "proceed-in-sandbox"`, and the
+configured `permissions` there. It does not edit the user's settings, copy their
+history/plugins, or reuse their project records. Concurrent runs get distinct
+homes. `permissionMode: "inherit"` is the default and preserves the previous
+behavior. Scoped mode requires `sandbox: true`, rejects `skipPermissions: true`
+and a host `project`, and supports scoped `allow`, `deny`, and `ask` lists.
+
+Authentication must work in that private home. An inherited `GEMINI_API_KEY` is
+passed to the CLI. For file-based OAuth, Lux copies only the CLI's
+`antigravity-oauth-token` into the private runtime, using the normal CLI token
+path by default or an explicit `authTokenFile`. The copy has mode 0600 inside
+a mode-0700 runtime directory; token refresh cannot modify the source file.
+On macOS, `reuseKeychain: true` explicitly opts into reading Antigravity’s own
+Keychain entry (service `gemini`, account `antigravity`) when the default token
+file is absent. Lux writes that credential only to the private runtime and
+removes it on close. This option defaults to false. Do not put secret values in
+committed Lux configuration.
+
+Before deleting a private runtime, Lux snapshots native deliverables from its
+`brain` directory under `antigravity-artifacts/` in the task artifacts. This keeps
+handoff documents available to graders even when the final response only links
+to them. Hidden CLI logs, revision copies, metadata, and symlinks are excluded;
+collection fails explicitly above 500 files or 32 MiB. Existing user-home brain
+history is never scanned in inherited mode.
+
+The runtime is outside task artifacts and removed on driver close, collection,
+and startup failure. A force-killed Lux process cannot run cleanup; private
+runtime directories have the `lux-antigravity-home-` prefix in the OS temp root.
+This is configuration separation, not a complete OS security boundary; the
+driver continues declaring `isolation: false`.
+
 Grant scoped file and documentation access as needed, including read access to
-language runtimes installed outside system directories. In 1.2.10, `command(...)`
-allow rules also authorize outside-sandbox execution, and `unsandboxed(...)`
-rules are ignored. Keep command allow rules absent when outside-sandbox
-execution must remain unapproved. The terminal sandbox is not full driver
-isolation; native file tools still use the CLI's file permissions.
+language runtimes installed outside system directories. `command(...)` allow
+rules can authorize outside-sandbox execution too. Keep them absent when that
+execution must remain unapproved; `unsandboxed(...)` rules were ignored in the
+observed macOS CLI. The terminal sandbox and native file-tool permissions are
+separate. Extra CLI arguments remain caller-controlled.
 
 Each run creates a fresh Antigravity project and passes its canonical working
 directory through `--add-dir` and an explicit task-workspace prompt preamble.
@@ -60,14 +107,65 @@ permissions: Antigravity 1.2.10 can still deny workspace writes in headless mode
 bypass tool permission checks.
 
 The headless protocol carries no user questions or permission prompts, so the
-driver is not interactive and declares no isolation: Antigravity still reads
-its user settings and conversation history. Controlled experiments are not
+driver is not interactive. In inherited mode, Antigravity still reads user
+settings and conversation history. Controlled experiments are not
 declared.
 
 Regression tests cover the `ERROR` tool step followed by `SUCCESS` with denied
 actions observed in an authenticated Antigravity 1.2.10 session.
 
+## Live readiness checks
+
+From a Lux checkout, after installing locked dependencies and authenticating `agy`:
+
+```sh
+LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro mise run smoke:antigravity
+```
+
+This opt-in smoke test consumes model usage. It runs four bounded checks in
+fresh artifact workspaces: a tool-free protocol response, a Node write/read
+check, native handoff-document capture, and a local HTTP server/client check. It stops on the first failure and
+retains events, fixtures, and results under `.lux-runs/antigravity-smoke/`.
+After building, select one stage with
+`LUX_ANTIGRAVITY_MODEL=gemini-3.1-pro node scripts/smoke-antigravity.mjs protocol`
+(or `workspace` / `artifact` / `loopback`); `--list` makes no model calls.
+
+The script uses `permissionMode: "proceed-in-sandbox"` with scoped read access to
+the running Node installation, plus localhost grants for the loopback stage.
+It never changes global settings. Authenticate
+with an inherited `GEMINI_API_KEY`, a normal CLI OAuth token file, or
+`LUX_ANTIGRAVITY_AUTH_TOKEN_FILE` pointing to such a file. To opt into macOS
+Keychain reuse, set `LUX_ANTIGRAVITY_REUSE_KEYCHAIN=1`. On macOS with CLI 1.2.12,
+private-runtime authentication and sandboxed file writes passed on 2026-09-29.
+The loopback check failed with `connect EPERM 127.0.0.1`; its missing fixture
+evidence correctly failed the smoke test despite normal agent completion.
+
+`--sandbox` alone does not select an execution policy: a native 1.2.12 probe on
+macOS with only `enableTerminalSandbox: true` denied the command, then returned
+`SUCCESS` with empty text and `denied_actions`. Lux correctly classifies that
+result as an error. A separate tool-free live probe passed in inherited mode;
+it does not establish private-runtime authentication.
+
+A passing protocol check establishes authentication and streaming only.
+Workspace and loopback checks require fixture-produced evidence; a completed
+agent response alone cannot pass them. These checks do not establish skill
+quality, package-install access, or complete sandbox isolation. Scoped access
+to a runtime outside system directories may also be necessary.
+
+On macOS, native 1.2.11 probes could write/build in editing mode but could
+not connect to their own loopback HTTP server: direct connections returned
+`EPERM`, and proxy requests rejected literal IPs or nonstandard HTTP ports.
+That failure occurred without Lux. Recheck the installed CLI with `loopback`
+before running suites that depend on local HTTP fixtures. Domain grants alone
+have not been shown to resolve this restriction. Keep a native reproduction
+separate from driver traces when diagnosing it; do not treat it as skill failure
+or bypass the sandbox to obtain a passing score.
+
 Protocol references:
 
 - [Antigravity CLI headless mode](https://antigravity.google/docs/cli/headless/)
 - [Antigravity CLI](https://github.com/google-antigravity/antigravity-cli)
+
+- [Antigravity terminal sandbox](https://antigravity.google/docs/sandbox?tab=cli)
+- [CLI settings reference](https://antigravity.google/docs/cli/reference/)
+- [Native artifacts](https://antigravity.google/docs/cli/artifacts/)

package/src/drivers/antigravity/artifacts.ts

@@ -0,0 +1,37 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, sep } from "node:path";
+import { writeArtifactSnapshot } from "../../core/artifact-snapshot.js";
+import { walkArtifacts } from "../shared/artifacts.js";
+
+export const captureAntigravityArtifacts = async (
+  home: string,
+  destination: string,
+): Promise<void> => {
+  const brain = join(home, ".gemini/antigravity-cli/brain");
+  let root: string;
+  try {
+    root = await realpath(brain);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  if (!root.startsWith(`${await realpath(home)}${sep}`))
+    throw new Error("Antigravity artifact directory escaped its private runtime");
+  // Native revisions and CLI bookkeeping are not authored deliverables.
+  const artifacts = (await walkArtifacts(brain)).filter(
+    ({ path }) => !/\.(?:metadata\.json|resolved(?:\.\d+)?)$/.test(path),
+  );
+  if (!artifacts.length) return;
+  const maxBytes = 32 * 1024 * 1024;
+  if (artifacts.reduce((total, artifact) => total + (artifact.size ?? 0), 0) > maxBytes)
+    throw new Error("Antigravity native artifacts exceed the 32 MiB collection limit");
+  const files = Object.fromEntries(
+    await Promise.all(artifacts.map(async ({ path }) => [path, await readFile(join(brain, path))])),
+  );
+  await writeArtifactSnapshot({
+    artifactsDir: destination,
+    name: "antigravity-artifacts",
+    files,
+    maxBytes,
+  });
+};

package/src/drivers/antigravity/config.ts

@@ -21,6 +21,20 @@ export const AntigravityDriverConfigSchema = z
     skipPermissions: z.boolean().default(false),
     /** Enable Antigravity's terminal sandbox restrictions. */
     sandbox: z.boolean().default(false),
+    /** Own the CLI settings in a private runtime home instead of changing user settings. */
+    permissionMode: z.enum(["inherit", "proceed-in-sandbox"]).default("inherit"),
+    permissions: z
+      .object({
+        allow: z.array(z.string().min(1)).default([]),
+        deny: z.array(z.string().min(1)).default([]),
+        ask: z.array(z.string().min(1)).default([]),
+      })
+      .strict()
+      .optional(),
+    /** Optional CLI-format OAuth token file for the private runtime; never logged. */
+    authTokenFile: z.string().min(1).optional(),
+    /** Explicitly authorize copying this application's macOS Keychain credential. */
+    reuseKeychain: z.boolean().default(false),
     cwd: z.string().optional(),
     env: z.record(z.string(), z.string()).optional(),
     extraArgs: z.array(z.string()).optional(),
@@ -28,6 +42,27 @@ export const AntigravityDriverConfigSchema = z
     maxLineBytes: z.number().positive().default(10_000_000),
   })
   .strict()
+  .superRefine((config, ctx) => {
+    if (config.permissionMode === "proceed-in-sandbox") {
+      if (!config.sandbox || config.skipPermissions)
+        ctx.addIssue({
+          code: "custom",
+          message: "proceed-in-sandbox requires sandbox: true and skipPermissions: false",
+        });
+      if (config.project)
+        ctx.addIssue({
+          code: "custom",
+          path: ["project"],
+          message: "A private Antigravity runtime cannot reuse a host project",
+        });
+    } else if (config.permissions || config.authTokenFile || config.reuseKeychain) {
+      ctx.addIssue({
+        code: "custom",
+        message:
+          "permissions, authTokenFile, and reuseKeychain require permissionMode: proceed-in-sandbox",
+      });
+    }
+  })
   .transform(applyCatalogEffort(antigravityCatalog));
 
 export type AntigravityDriverConfig = z.infer<typeof AntigravityDriverConfigSchema>;

package/src/drivers/antigravity/index.ts

@@ -19,12 +19,15 @@ import {
   formatAntigravityPrompt,
 } from "./config.js";
 import { makeParseEvent } from "./events.js";
+import { prepareAntigravityRuntime } from "./runtime.js";
 
 class AntigravityDriver implements AgentDriver {
   private inner: AgentDriver | null = null;
   private pendingAttach: Array<(inner: AgentDriver) => void> = [];
   private cwd: string | null = null;
   private artifactsDir: string | null = null;
+  private runtime: Awaited<ReturnType<typeof prepareAntigravityRuntime>> | null = null;
+  private started = false;
   private readonly config: AntigravityDriverConfig;
 
   constructor(config: AntigravityDriverConfig) {
@@ -42,30 +45,37 @@ class AntigravityDriver implements AgentDriver {
   }
 
   async start(ctx: StartContext): Promise<ReadyState> {
-    if (this.inner) throw new Error("Antigravity driver cannot be started twice");
+    if (this.started) throw new Error("Antigravity driver cannot be started twice");
+    this.started = true;
     this.cwd = await realpath(this.config.cwd ?? ctx.artifactsDir);
     this.artifactsDir = ctx.artifactsDir;
     const cliVersion = await discoverCliVersion(this.config.command);
-    const inner = await subprocessDriver.create({
-      command: this.config.command,
-      args: buildAntigravityArgs(this.config, this.cwd),
-      cwd: this.cwd,
-      env: this.config.env,
-      protocol: "custom",
-      parseEvent: makeParseEvent(this.config, cliVersion),
-      formatPrompt: (prompt) =>
-        formatAntigravityPrompt(
-          `The task workspace is ${JSON.stringify(this.cwd)}. Treat that directory as the current directory for this task and create task artifacts there.\n\n${prompt}`,
-        ),
-      closeStdinAfterPrompt: true,
-      idleTimeout: this.config.idleTimeout,
-      maxLineBytes: this.config.maxLineBytes,
-      maxInterrupts: 1,
-    });
-    for (const attach of this.pendingAttach) attach(inner);
-    this.pendingAttach = [];
-    this.inner = inner;
-    return inner.start(ctx);
+    this.runtime = await prepareAntigravityRuntime(this.config, ctx.isolatedHome);
+    try {
+      const inner = await subprocessDriver.create({
+        command: this.config.command,
+        args: buildAntigravityArgs(this.config, this.cwd),
+        cwd: this.cwd,
+        env: this.runtime.env,
+        protocol: "custom",
+        parseEvent: makeParseEvent(this.config, cliVersion),
+        formatPrompt: (prompt) =>
+          formatAntigravityPrompt(
+            `The task workspace is ${JSON.stringify(this.cwd)}. Treat that directory as the current directory for this task and create task artifacts there.\n\n${prompt}`,
+          ),
+        closeStdinAfterPrompt: true,
+        idleTimeout: this.config.idleTimeout,
+        maxLineBytes: this.config.maxLineBytes,
+        maxInterrupts: 1,
+      });
+      for (const attach of this.pendingAttach) attach(inner);
+      this.pendingAttach = [];
+      this.inner = inner;
+      return await inner.start(ctx);
+    } catch (error) {
+      await this.close();
+      throw error;
+    }
   }
 
   async respond(_answer: Answer): Promise<void> {
@@ -79,6 +89,11 @@ class AntigravityDriver implements AgentDriver {
   async collect(): Promise<Artifact[]> {
     await this.quiesce();
     if (!this.cwd) return [];
+    try {
+      await this.runtime?.collect(this.cwd);
+    } finally {
+      await this.runtime?.close();
+    }
     const artifacts = await walkArtifacts(this.cwd);
     return this.cwd === this.artifactsDir
       ? artifacts
@@ -86,7 +101,11 @@ class AntigravityDriver implements AgentDriver {
   }
 
   async close(): Promise<void> {
-    await this.inner?.close();
+    try {
+      await this.inner?.close();
+    } finally {
+      await this.runtime?.close();
+    }
   }
 }
 

package/src/drivers/antigravity/runtime.ts

@@ -0,0 +1,88 @@
+import { chmod, copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { temporaryDirectory } from "tempy";
+import { exec } from "../../core/exec.js";
+import { captureAntigravityArtifacts } from "./artifacts.js";
+import type { AntigravityDriverConfig } from "./config.js";
+
+export const prepareAntigravityRuntime = async (
+  config: AntigravityDriverConfig,
+  isolatedHome?: string,
+): Promise<{
+  env: Record<string, string> | undefined;
+  collect: (destination: string) => Promise<void>;
+  close: () => Promise<void>;
+}> => {
+  if (config.permissionMode === "inherit")
+    return {
+      env: config.env,
+      collect: async (destination) => {
+        if (isolatedHome) await captureAntigravityArtifacts(isolatedHome, destination);
+      },
+      close: async () => {},
+    };
+
+  const runtimeHome = temporaryDirectory({ prefix: "lux-antigravity-home-" });
+  const close = () => rm(runtimeHome, { recursive: true, force: true });
+  try {
+    await chmod(runtimeHome, 0o700);
+    const cliRoot = join(runtimeHome, ".gemini", "antigravity-cli");
+    await mkdir(cliRoot, { recursive: true, mode: 0o700 });
+    await writeFile(
+      join(cliRoot, "settings.json"),
+      JSON.stringify({
+        enableTerminalSandbox: true,
+        toolPermission: "proceed-in-sandbox",
+        permissions: config.permissions,
+      }),
+      { mode: 0o600 },
+    );
+    const source =
+      config.authTokenFile ??
+      join(config.env?.HOME ?? homedir(), ".gemini", "antigravity-cli", "antigravity-oauth-token");
+    try {
+      // Copy only the CLI's own token, never settings, conversations, or plugins.
+      // A private copy prevents token refresh from mutating the caller's login.
+      const target = join(cliRoot, "antigravity-oauth-token");
+      await copyFile(source, target);
+      await chmod(target, 0o600);
+      // Reject empty files early without including credential contents in diagnostics.
+      if ((await readFile(target)).length === 0) throw new Error("Antigravity token file is empty");
+    } catch (error) {
+      if (config.authTokenFile || (error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+      if (config.reuseKeychain) {
+        if (platform() !== "darwin") throw new Error("Antigravity Keychain reuse requires macOS");
+        const credential = await exec(
+          "/usr/bin/security",
+          ["find-generic-password", "-s", "gemini", "-a", "antigravity", "-w"],
+          { timeoutMs: 10_000, maxBuffer: 1_000_000 },
+        );
+        if (credential.exitCode !== 0 || credential.stdoutTruncated)
+          throw new Error("Could not read the authorized Antigravity Keychain credential");
+        let token = credential.stdout.trim();
+        if (token.startsWith("go-keyring-base64:"))
+          token = Buffer.from(token.slice("go-keyring-base64:".length), "base64").toString("utf8");
+        try {
+          const parsed = JSON.parse(token);
+          if (!parsed?.token?.refresh_token || !parsed.auth_method) throw new Error();
+        } catch {
+          throw new Error("Antigravity Keychain credential has an unsupported format");
+        }
+        await writeFile(join(cliRoot, "antigravity-oauth-token"), token, { mode: 0o600 });
+      }
+    }
+    return {
+      env: {
+        ...config.env,
+        HOME: runtimeHome,
+        ...(process.platform === "win32" ? { USERPROFILE: runtimeHome } : {}),
+      },
+      collect: (destination) => captureAntigravityArtifacts(runtimeHome, destination),
+      close,
+    };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+};

package/src/index.ts

@@ -265,6 +265,12 @@ export {
   type StartContext,
   selectModelAndReasoningEffort,
 } from "./core/driver.js";
+export {
+  type ContainerExecution,
+  ContainerExecutionSchema,
+  type DriverExecution,
+  DriverExecutionSchema,
+} from "./core/driver-execution.js";
 export {
   type DriverMetric,
   type DriverMetricDescriptor,

package/src/orchestrator/config.ts

@@ -74,7 +74,7 @@ const LifecycleHooksPluginSchema = z.custom<LifecycleHooksPlugin>().superRefine(
   if (issue) ctx.addIssue({ code: "custom", message: issue });
 });
 
-const LuxConfigSchema = z
+export const LuxConfigSchema = z
   .object({
     environment: EnvironmentDeclarationSchema.optional(),
     casesRoot: z.string().optional(),
@@ -194,6 +194,9 @@ const builtinDrivers: DriverPlugin<never>[] = [
   subprocessDriver,
   mcpProbeDriver,
 ];
+export const isBuiltinDriver = (plugin: DriverPlugin): boolean =>
+  builtinDrivers.some((builtin) => builtin === plugin);
+
 const builtinAnswerers: AnswererPlugin<never>[] = [
   personaAnswerer,
   claudeCodeAnswerer,