@golba98/codexa 1.0.3 → 1.0.4

package/src/core/agent/tools.ts

@@ -0,0 +1,414 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import { runShellCommand, summarizeCommandResult } from "../process/CommandRunner.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import {
+  getShellWorkspaceGuardMessage,
+  isPathInsideAllowedRoots,
+  resolveWorkspacePath,
+} from "../workspace/workspaceGuard.js";
+import type { AgentToolName } from "./protocol.js";
+
+export interface AgentToolContext {
+  workspaceRoot: string;
+  runtime: ResolvedRuntimeConfig;
+  signal?: AbortSignal;
+}
+
+export interface AgentToolResult {
+  success: boolean;
+  tool: AgentToolName;
+  path?: string;
+  command?: string;
+  paths?: string[];
+  output?: string;
+  stdout?: string;
+  stderr?: string;
+  exitCode?: number | null;
+  durationMs?: number;
+  summary?: string;
+  error?: string;
+}
+
+const MAX_FILE_BYTES = 128 * 1024;
+const MAX_OUTPUT_CHARS = 4_000;
+const MAX_OUTPUT_LINES = 80;
+const SHELL_TIMEOUT_MS = 30_000;
+
+const DANGEROUS_SHELL_PATTERNS: RegExp[] = [
+  /\brm\s+-[^\n;|&]*r[f]?\b/i,
+  /\bsudo\b/i,
+  /\bdoas\b/i,
+  /\bdd\s+.*\bof=/i,
+  /\bmkfs(?:\.[a-z0-9]+)?\b/i,
+  /\bshutdown\b/i,
+  /\breboot\b/i,
+  /\bpoweroff\b/i,
+  /\bchmod\s+-R\s+777\b/i,
+  /:\(\)\s*\{\s*:\|:\s*&\s*\}\s*;/,
+  />\s*\/dev\/(?:sd|hd|nvme|disk)/i,
+];
+
+function preview(text: string, maxChars = MAX_OUTPUT_CHARS): string {
+  const sanitized = sanitizeTerminalOutput(text);
+  return sanitized.length > maxChars ? `${sanitized.slice(0, maxChars)}\n...[truncated]` : sanitized;
+}
+
+function trimOutputLines(text: string, preferTail: boolean): string {
+  const sanitized = sanitizeTerminalOutput(text).replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  const lines = sanitized.split("\n");
+  if (lines.at(-1) === "") lines.pop();
+  if (lines.length <= MAX_OUTPUT_LINES) return sanitized;
+  const visible = preferTail ? lines.slice(-MAX_OUTPUT_LINES) : lines.slice(0, MAX_OUTPUT_LINES);
+  const hidden = lines.length - visible.length;
+  const marker = `[...${hidden} line${hidden === 1 ? "" : "s"} truncated; showing ${preferTail ? "last" : "first"} ${MAX_OUTPUT_LINES} lines...]`;
+  return preferTail
+    ? [marker, ...visible].join("\n")
+    : [...visible, marker].join("\n");
+}
+
+function stringArg(args: Record<string, unknown>, key: string): string | null {
+  const value = args[key];
+  return typeof value === "string" && value.trim() ? value : null;
+}
+
+function isReadOnly(runtime: ResolvedRuntimeConfig): boolean {
+  return runtime.policy.sandboxMode === "read-only";
+}
+
+function canWrite(runtime: ResolvedRuntimeConfig): boolean {
+  return runtime.policy.sandboxMode === "workspace-write"
+    || runtime.policy.sandboxMode === "danger-full-access";
+}
+
+function relativeDisplay(workspaceRoot: string, absolutePath: string): string {
+  const relative = path.relative(workspaceRoot, absolutePath).split(path.sep).join("/");
+  return relative || ".";
+}
+
+function hasCargoManifest(workspaceRoot: string): boolean {
+  return existsSync(path.join(workspaceRoot, "Cargo.toml"));
+}
+
+function rustCommandGuard(command: string, context: AgentToolContext): string | null {
+  if (!hasCargoManifest(context.workspaceRoot)) return null;
+  const normalized = command.trim().replace(/\s+/g, " ");
+  const rustcMatch = /^rustc(?:\s+--?[^\s]+)*\s+([^\s]+\.rs)\b/.exec(normalized);
+  if (!rustcMatch) return null;
+  const target = rustcMatch[1]!;
+  const resolved = path.resolve(context.workspaceRoot, target);
+  const rootMain = path.join(context.workspaceRoot, "main.rs");
+  if (resolved !== rootMain || !existsSync(rootMain)) {
+    return "This workspace has Cargo.toml. Use `cargo check` to validate or `cargo run` to run instead of compiling a Rust source file directly with rustc.";
+  }
+  return null;
+}
+
+function resolveAllowedPath(rawPath: string, context: AgentToolContext): { ok: true; absolutePath: string; relativePath: string } | { ok: false; error: string } {
+  if (!isPathInsideAllowedRoots(rawPath, context.workspaceRoot, context.runtime.policy.writableRoots)) {
+    return { ok: false, error: `Path is outside the workspace: ${rawPath}` };
+  }
+  const absolutePath = resolveWorkspacePath(rawPath, context.workspaceRoot);
+  return {
+    ok: true,
+    absolutePath,
+    relativePath: relativeDisplay(context.workspaceRoot, absolutePath),
+  };
+}
+
+async function listFiles(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  const rawPath = stringArg(args, "path") ?? ".";
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "list_files", path: rawPath, error: resolved.error };
+
+  const entries = await readdir(resolved.absolutePath, { withFileTypes: true });
+  const names = entries
+    .filter((entry) => ![".git", "node_modules", "dist", "build", "coverage"].includes(entry.name))
+    .map((entry) => `${entry.name}${entry.isDirectory() ? "/" : ""}`)
+    .sort();
+  return {
+    success: true,
+    tool: "list_files",
+    path: resolved.relativePath,
+    output: names.slice(0, 200).join("\n"),
+    summary: `Listed ${names.length} item${names.length === 1 ? "" : "s"}.`,
+  };
+}
+
+async function readFileTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  const rawPath = stringArg(args, "path");
+  if (!rawPath) return { success: false, tool: "read_file", error: "Missing path." };
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "read_file", path: rawPath, error: resolved.error };
+
+  const fileStat = await stat(resolved.absolutePath);
+  if (fileStat.size > MAX_FILE_BYTES) {
+    return { success: false, tool: "read_file", path: resolved.relativePath, error: "File is too large to read through the agent tool." };
+  }
+  const content = await readFile(resolved.absolutePath, "utf8");
+  return {
+    success: true,
+    tool: "read_file",
+    path: resolved.relativePath,
+    output: content,
+    summary: `Read ${resolved.relativePath}.`,
+  };
+}
+
+async function writeFileTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime)) {
+    return { success: false, tool: "write_file", error: "write_file is blocked by read-only runtime policy." };
+  }
+  const rawPath = stringArg(args, "path");
+  const content = stringArg(args, "content");
+  if (!rawPath) return { success: false, tool: "write_file", error: "Missing path." };
+  if (content === null) return { success: false, tool: "write_file", path: rawPath, error: "Missing content." };
+  const resolved = resolveAllowedPath(rawPath, context);
+  if (!resolved.ok) return { success: false, tool: "write_file", path: rawPath, error: resolved.error };
+
+  await mkdir(path.dirname(resolved.absolutePath), { recursive: true });
+  await writeFile(resolved.absolutePath, content, "utf8");
+  return {
+    success: true,
+    tool: "write_file",
+    path: resolved.relativePath,
+    paths: [resolved.relativePath],
+    summary: `Wrote ${resolved.relativePath}.`,
+  };
+}
+
+function parseApplyPatchPaths(patch: string): string[] {
+  const paths: string[] = [];
+  for (const line of patch.split(/\r?\n/)) {
+    const marker = /^(?:\*\*\* (?:Add|Update|Delete) File:|--- a\/|\+\+\+ b\/)\s*(.+)$/.exec(line);
+    if (marker?.[1] && marker[1] !== "/dev/null") {
+      paths.push(marker[1].trim());
+    }
+  }
+  return [...new Set(paths)];
+}
+
+function applyPatchFormatToContent(before: string, patchLines: string[]): string {
+  let contentLines = before.replace(/\r\n/g, "\n").replace(/\r/g, "\n").split("\n");
+  if (contentLines.at(-1) === "") contentLines = contentLines.slice(0, -1);
+  let cursor = 0;
+  let index = 0;
+
+  while (index < patchLines.length) {
+    if (!patchLines[index]?.startsWith("@@")) {
+      index += 1;
+      continue;
+    }
+    index += 1;
+    const oldLines: string[] = [];
+    const newLines: string[] = [];
+    while (index < patchLines.length && !patchLines[index]?.startsWith("@@") && !patchLines[index]?.startsWith("*** ")) {
+      const line = patchLines[index] ?? "";
+      if (line.startsWith(" ")) {
+        oldLines.push(line.slice(1));
+        newLines.push(line.slice(1));
+      } else if (line.startsWith("-")) {
+        oldLines.push(line.slice(1));
+      } else if (line.startsWith("+")) {
+        newLines.push(line.slice(1));
+      }
+      index += 1;
+    }
+
+    let matchAt = -1;
+    for (let candidate = cursor; candidate <= contentLines.length - oldLines.length; candidate += 1) {
+      const matches = oldLines.every((line, offset) => contentLines[candidate + offset] === line);
+      if (matches) {
+        matchAt = candidate;
+        break;
+      }
+    }
+    if (matchAt < 0) {
+      throw new Error("Patch context did not match the target file.");
+    }
+    contentLines.splice(matchAt, oldLines.length, ...newLines);
+    cursor = matchAt + newLines.length;
+  }
+
+  return `${contentLines.join("\n")}\n`;
+}
+
+async function applyPatchFormat(patch: string, context: AgentToolContext): Promise<AgentToolResult> {
+  const lines = patch.split(/\r?\n/);
+  const changedPaths: string[] = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    const add = /^\*\*\* Add File:\s*(.+)$/.exec(lines[index] ?? "");
+    const update = /^\*\*\* Update File:\s*(.+)$/.exec(lines[index] ?? "");
+    const del = /^\*\*\* Delete File:\s*(.+)$/.exec(lines[index] ?? "");
+
+    if (add) {
+      const resolved = resolveAllowedPath(add[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: add[1], error: resolved.error };
+      index += 1;
+      const content: string[] = [];
+      while (index < lines.length && !lines[index]?.startsWith("*** ")) {
+        const line = lines[index] ?? "";
+        if (line.startsWith("+")) content.push(line.slice(1));
+        index += 1;
+      }
+      await mkdir(path.dirname(resolved.absolutePath), { recursive: true });
+      await writeFile(resolved.absolutePath, `${content.join("\n")}\n`, "utf8");
+      changedPaths.push(resolved.relativePath);
+      continue;
+    }
+
+    if (update) {
+      const resolved = resolveAllowedPath(update[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: update[1], error: resolved.error };
+      index += 1;
+      const patchLines: string[] = [];
+      while (index < lines.length && !/^\*\*\* (?:Add|Update|Delete|End)/.test(lines[index] ?? "")) {
+        patchLines.push(lines[index] ?? "");
+        index += 1;
+      }
+      const before = await readFile(resolved.absolutePath, "utf8");
+      await writeFile(resolved.absolutePath, applyPatchFormatToContent(before, patchLines), "utf8");
+      changedPaths.push(resolved.relativePath);
+      continue;
+    }
+
+    if (del) {
+      const resolved = resolveAllowedPath(del[1]!, context);
+      if (!resolved.ok) return { success: false, tool: "apply_patch", path: del[1], error: resolved.error };
+      await rm(resolved.absolutePath, { force: true });
+      changedPaths.push(resolved.relativePath);
+      index += 1;
+      continue;
+    }
+
+    index += 1;
+  }
+
+  if (changedPaths.length === 0) {
+    return { success: false, tool: "apply_patch", error: "No supported patch operations were found." };
+  }
+
+  return {
+    success: true,
+    tool: "apply_patch",
+    paths: changedPaths,
+    summary: `Patched ${changedPaths.join(", ")}.`,
+  };
+}
+
+async function applyPatchTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime)) {
+    return { success: false, tool: "apply_patch", error: "apply_patch is blocked by read-only runtime policy." };
+  }
+  const patch = stringArg(args, "patch");
+  if (!patch) return { success: false, tool: "apply_patch", error: "Missing patch." };
+
+  const explicitPath = stringArg(args, "path");
+  const paths = explicitPath ? [explicitPath] : parseApplyPatchPaths(patch);
+  for (const patchPath of paths) {
+    const resolved = resolveAllowedPath(patchPath, context);
+    if (!resolved.ok) return { success: false, tool: "apply_patch", path: patchPath, error: resolved.error };
+  }
+
+  if (!patch.trimStart().startsWith("*** Begin Patch")) {
+    return { success: false, tool: "apply_patch", error: "Only *** Begin Patch format is supported by this agent tool." };
+  }
+
+  return applyPatchFormat(patch, context);
+}
+
+async function runShellTool(args: Record<string, unknown>, context: AgentToolContext): Promise<AgentToolResult> {
+  if (!canWrite(context.runtime) || isReadOnly(context.runtime)) {
+    return { success: false, tool: "run_shell", error: "run_shell is blocked by read-only runtime policy." };
+  }
+  const command = stringArg(args, "command");
+  if (!command) return { success: false, tool: "run_shell", error: "Missing command." };
+
+  if (DANGEROUS_SHELL_PATTERNS.some((pattern) => pattern.test(command))) {
+    return { success: false, tool: "run_shell", command, error: "Shell command blocked as dangerous." };
+  }
+  const rustGuard = rustCommandGuard(command, context);
+  if (rustGuard) {
+    return { success: false, tool: "run_shell", command, exitCode: null, durationMs: 0, stdout: "", stderr: "", error: rustGuard };
+  }
+  const workspaceGuard = getShellWorkspaceGuardMessage(command, context.workspaceRoot, context.runtime.policy.writableRoots);
+  if (workspaceGuard) {
+    return { success: false, tool: "run_shell", command, error: workspaceGuard };
+  }
+
+  const runner = runShellCommand(command, {
+    cwd: context.workspaceRoot,
+    timeoutMs: SHELL_TIMEOUT_MS,
+  });
+  const cancel = () => runner.cancel();
+  context.signal?.addEventListener("abort", cancel, { once: true });
+  try {
+    const result = await runner.result;
+    const success = result.status === "completed" && result.exitCode === 0;
+    const stdout = trimOutputLines(result.stdout, !success);
+    const stderr = trimOutputLines(result.stderr, !success);
+    const output = preview([stdout, stderr].filter(Boolean).join("\n"));
+    return {
+      success,
+      tool: "run_shell",
+      command,
+      exitCode: result.exitCode,
+      durationMs: result.durationMs,
+      stdout,
+      stderr,
+      output,
+      summary: summarizeCommandResult(command, result),
+      error: success ? undefined : result.userMessage,
+    };
+  } finally {
+    context.signal?.removeEventListener("abort", cancel);
+  }
+}
+
+async function getWorkspaceInfo(context: AgentToolContext): Promise<AgentToolResult> {
+  return {
+    success: true,
+    tool: "get_workspace_info",
+    path: ".",
+    output: JSON.stringify({
+      workspaceRoot: context.workspaceRoot,
+      sandboxMode: context.runtime.policy.sandboxMode,
+      writableRoots: context.runtime.policy.writableRoots,
+      packageJson: existsSync(path.join(context.workspaceRoot, "package.json")),
+    }),
+    summary: "Returned workspace info.",
+  };
+}
+
+export async function executeAgentTool(
+  name: AgentToolName,
+  args: Record<string, unknown>,
+  context: AgentToolContext,
+): Promise<AgentToolResult> {
+  try {
+    switch (name) {
+      case "list_files":
+        return await listFiles(args, context);
+      case "read_file":
+        return await readFileTool(args, context);
+      case "write_file":
+        return await writeFileTool(args, context);
+      case "apply_patch":
+        return await applyPatchTool(args, context);
+      case "run_shell":
+        return await runShellTool(args, context);
+      case "get_workspace_info":
+        return await getWorkspaceInfo(context);
+    }
+  } catch (error) {
+    return {
+      success: false,
+      tool: name,
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}

package/src/core/{codexExecArgs.ts → codex/codexExecArgs.ts}

@@ -1,5 +1,5 @@
-import type { ResolvedRuntimeConfig } from "../config/runtimeConfig.js";
-import type { CodexCliCapabilities } from "./models/codexCapabilities.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { CodexCliCapabilities } from "../models/codexCapabilities.js";
 
 export interface BuildCodexExecArgsOptions {
   runtime: ResolvedRuntimeConfig;

package/src/core/{codexLaunch.ts → codex/codexLaunch.ts}

@@ -1,8 +1,8 @@
 import { fileURLToPath } from "url";
 import { buildCodexExecArgs, type BuildCodexExecArgsOptions, type BuildCodexExecArgsResult } from "./codexExecArgs.js";
-import { getCodexCliCapabilities, type CodexCliCapabilities } from "./models/codexCapabilities.js";
-import { resolveCodexExecutable } from "./executables/codexExecutable.js";
-import * as perf from "./perf/profiler.js";
+import { getCodexCliCapabilities, type CodexCliCapabilities } from "../models/codexCapabilities.js";
+import { resolveCodexExecutable } from "../executables/codexExecutable.js";
+import * as perf from "../perf/profiler.js";
 
 // Assumed capability set when probeCapabilities is false — avoids a slow help-output probe on every run.
 const MODERN_CODEX_CLI_CAPABILITIES: CodexCliCapabilities = {

package/src/core/{codexPrompt.ts → codex/codexPrompt.ts}

@@ -1,6 +1,6 @@
-import type { AvailableMode } from "../config/settings.js";
-import type { ResolvedRuntimeConfig } from "../config/runtimeConfig.js";
-import type { ProjectInstructions } from "./projectInstructions.js";
+import type { AvailableMode } from "../../config/settings.js";
+import type { ResolvedRuntimeConfig } from "../../config/runtimeConfig.js";
+import type { ProjectInstructions } from "../workspace/projectInstructions.js";
 
 // ─── Write-intent detection ───────────────────────────────────────────────────
 

package/src/core/debug/modelStateDebug.ts

@@ -0,0 +1,34 @@
+import { appendFileSync, mkdirSync } from "fs";
+import { dirname, join } from "path";
+
+type ModelStateDebugDetails = Record<string, unknown>;
+
+let sequence = 0;
+
+export function isModelStateDebugEnabled(): boolean {
+  return process.env.CODEXA_RENDER_DEBUG === "1" || process.env.CODEXA_DEBUG_MODEL_STATE === "1";
+}
+
+export function getModelStateDebugLogPath(): string {
+  return process.env.CODEXA_RENDER_DEBUG_FILE?.trim()
+    || process.env.CODEXA_DEBUG_MODEL_STATE_LOG?.trim()
+    || join(process.cwd(), ".codexa", "debug", "render-status.log");
+}
+
+export function traceModelStateDebug(event: string, details: ModelStateDebugDetails = {}): void {
+  if (!isModelStateDebugEnabled()) return;
+
+  try {
+    const entry = {
+      ts: new Date().toISOString(),
+      seq: ++sequence,
+      event,
+      ...details,
+    };
+    const logPath = getModelStateDebugLogPath();
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `${JSON.stringify(entry)}\n`, "utf8");
+  } catch {
+    // Debug logging must never affect the TUI.
+  }
+}

package/src/core/executables/antigravityExecutable.ts

@@ -0,0 +1,48 @@
+import { runCommand } from "../process/CommandRunner.js";
+import { resolveExecutable } from "./executableResolver.js";
+
+type CommandRunner = typeof runCommand;
+
+let cachedExecutable: string | null = null;
+
+export function resetAgyExecutableCacheForTests(): void {
+  cachedExecutable = null;
+}
+
+/**
+ * Returns the resolved Antigravity CLI executable (full path or bare name).
+ *
+ * Priority:
+ *   1. Configured path override (antigravityCommandPath)
+ *   2. AGY_EXECUTABLE env var
+ *   3. Windows PATH lookup for real files: agy.exe, agy.cmd, agy.bat, agy
+ *   4. Bare name fallback "agy" (Unix PATH resolution)
+ */
+export async function resolveAgyExecutable(options?: {
+  runCommandImpl?: CommandRunner;
+  cwd?: string;
+  configuredPath?: string | null;
+}): Promise<string> {
+  if (!options?.configuredPath && !options?.runCommandImpl && cachedExecutable !== null) {
+    return cachedExecutable;
+  }
+
+  const result = await resolveExecutable({
+    runCommandImpl: options?.runCommandImpl,
+    cwd: options?.cwd,
+    configuredPath: options?.configuredPath,
+    envOverrides: ["AGY_EXECUTABLE"],
+    commandNames: process.platform === "win32"
+      ? ["agy.exe", "agy.cmd", "agy.bat", "agy"]
+      : ["agy"],
+    knownPathDirectories: [],
+    knownFilePaths: [],
+    label: "antigravity",
+    allowBareFallback: true,
+  });
+
+  if (!options?.configuredPath && !options?.runCommandImpl) {
+    cachedExecutable = result;
+  }
+  return result;
+}

package/src/core/executables/executableResolver.ts

@@ -139,13 +139,17 @@ export async function resolveExecutable(options: ExecutableResolverOptions): Pro
 /**
  * Builds the spawn spec for a resolved executable.
  * .cmd and .bat files must be invoked via `cmd.exe /d /s /c` on Windows.
+ *
+ * `platform` defaults to the host platform; it is injectable so the Windows
+ * wrapping branch can be unit-tested from any OS.
  */
 export function buildSpawnSpec(
   executable: string,
   args: string[],
+  platform: NodeJS.Platform = process.platform,
 ): { executable: string; args: string[] } {
   const validatedExecutable = validateResolvedExecutable(executable, "Executable", process.cwd());
-  if (process.platform === "win32") {
+  if (platform === "win32") {
     const lower = validatedExecutable.toLowerCase();
     if (lower.endsWith(".cmd") || lower.endsWith(".bat")) {
       validateWindowsBatchExecutableForCmd(validatedExecutable, "Windows batch executable");

package/src/core/perf/renderDebug.ts

@@ -4,14 +4,14 @@ import { useEffect, useRef } from "react";
 
 type DebugEnv = Record<string, string | undefined>;
 
-// Global debug state — populated lazily on first check, or eagerly via configureRenderDebug().
+// Global debug state — populated lazily on first check, or eagerly via configureRenderDebug().
 let configured = false;
 let enabled = false;
 let renderTraceEnabled = false;
 let lifecycleEnabled = false;
 let flickerEnabled = false;
 let plainActionsEnabled = false;
-let logPath = join(process.cwd(), ".codexa-debug", "render-debug.log");
+let logPath = join(process.cwd(), ".codexa", "debug", "render-status.log");
 let sessionId = `${Date.now()}-${process.pid}`;
 const counters = new Map<string, number>();
 
@@ -19,13 +19,17 @@ function configureFromEnv(env: DebugEnv = process.env): void {
   renderTraceEnabled = env["CODEXA_DEBUG_RENDER_TRACE"] === "1";
   // Both CODEXA_RENDER_DEBUG and CODEXA_DEBUG_RENDER activate render debugging —
   // two names exist for historical reasons; either one is sufficient.
-  enabled = env["CODEXA_RENDER_DEBUG"] === "1"
-    || env["CODEXA_DEBUG_RENDER"] === "1"
-    || renderTraceEnabled;
+  // CODEXA_TERMINAL_TRACE is a focused alias for diagnosing terminal/clear/resize
+  // render-state issues; it lights up the same `terminal` trace channel.
+  enabled = env["CODEXA_RENDER_DEBUG"] === "1"
+    || env["CODEXA_DEBUG_MODEL_STATE"] === "1"
+    || env["CODEXA_DEBUG_RENDER"] === "1"
+    || env["CODEXA_TERMINAL_TRACE"] === "1"
+    || renderTraceEnabled;
   lifecycleEnabled = env["CODEXA_DEBUG_LIFECYCLE"] === "1";
   flickerEnabled = env["CODEXA_DEBUG_FLICKER"] === "1";
   plainActionsEnabled = env["CODEXA_DEBUG_PLAIN_ACTIONS"] === "1";
-  logPath = env["CODEXA_RENDER_DEBUG_FILE"]?.trim() || join(process.cwd(), ".codexa-debug", "render-debug.log");
+  logPath = env["CODEXA_RENDER_DEBUG_FILE"]?.trim() || join(process.cwd(), ".codexa", "debug", "render-status.log");
   sessionId = `${Date.now()}-${process.pid}`;
   configured = true;
 }

package/src/core/providerLauncher/registry.ts

@@ -14,12 +14,16 @@ import {
   isProviderRoutableInCodexa,
   isProviderRouteConfigured,
 } from "../providerRuntime/registry.js";
-import { normalizeGeminiModelId } from "../providerRuntime/models.js";
-import { setLocalProviderConfig } from "../providerRuntime/local.js";
+import { normalizeGeminiModelId } from "../providerRuntime/models.js";
+import { ANTIGRAVITY_DEFAULT_MODEL_ID } from "../providerRuntime/antigravity.js";
+import { setLocalProviderConfig } from "../providerRuntime/local.js";
 import { formatContextLength, resolveModelContextLengthCached } from "../providerRuntime/contextMetadata.js";
 import { resolveModelCapabilityProfileCached } from "../providerRuntime/capabilityProfile.js";
 
-const PROVIDER_ORDER: readonly ProviderId[] = ["openai", "anthropic", "google", "local"];
+// Google/Gemini remains a recognized legacy config value so existing workspace
+// files can be migrated, but it is no longer a selectable Codexa provider.
+const PROVIDER_ORDER: readonly ProviderId[] = ["openai", "anthropic", "local", "antigravity"];
+const KNOWN_PROVIDER_IDS: readonly ProviderId[] = ["openai", "anthropic", "google", "local", "antigravity"];
 
 const DEFAULT_PROVIDER_ID: ProviderId = "openai";
 
@@ -63,8 +67,8 @@ const DEFAULT_PROVIDERS: Record<ProviderId, ProviderDefault> = {
     isActiveRoute: false,
     routeUnavailableReason: null,
   },
-  local: {
-    id: "local",
+  local: {
+    id: "local",
     displayName: "Local",
     currentModel: () => "Local default",
     backendType: "local-openai-compatible",
@@ -72,12 +76,23 @@ const DEFAULT_PROVIDERS: Record<ProviderId, ProviderDefault> = {
     enabled: false,
     launchCommand: null,
     isActiveRoute: false,
-    routeUnavailableReason: "Local provider unavailable. Start LM Studio, load a model, and enable the local server.",
-  },
-};
+    routeUnavailableReason: "Local provider unavailable. Start LM Studio, load a model, and enable the local server.",
+  },
+  antigravity: {
+    id: "antigravity",
+    displayName: "Antigravity",
+    currentModel: () => ANTIGRAVITY_DEFAULT_MODEL_ID,
+    backendType: "antigravity-cli-auth",
+    routeMode: "in-codexa",
+    enabled: true,
+    launchCommand: { executable: "agy", args: [] },
+    isActiveRoute: false,
+    routeUnavailableReason: null,
+  },
+};
 
-function isProviderId(value: unknown): value is ProviderId {
-  return typeof value === "string" && PROVIDER_ORDER.includes(value as ProviderId);
+function isProviderId(value: unknown): value is ProviderId {
+  return typeof value === "string" && KNOWN_PROVIDER_IDS.includes(value as ProviderId);
 }
 
 function normalizeLaunchCommand(value: ProviderWorkspaceOverride["command"] | undefined): ProviderLaunchCommand | null | undefined {
@@ -128,13 +143,14 @@ function applyOverride(
   };
 }
 
-export function getDefaultProviderId(config: ProviderWorkspaceConfig | null | undefined): ProviderId {
-  return isProviderId(config?.workspaceDefaultProviderId) ? config.workspaceDefaultProviderId : DEFAULT_PROVIDER_ID;
-}
+export function getDefaultProviderId(config: ProviderWorkspaceConfig | null | undefined): ProviderId {
+  const providerId = config?.workspaceDefaultProviderId;
+  return isProviderId(providerId) && providerId !== "google" ? providerId : DEFAULT_PROVIDER_ID;
+}
 
 export function getActiveRouteProviderId(config: ProviderWorkspaceConfig | null | undefined): ProviderId {
   const providerId = config?.activeRoute?.providerId;
-  return isProviderId(providerId) && isProviderRoutableInCodexa(providerId)
+  return isProviderId(providerId) && providerId !== "google" && isProviderRoutableInCodexa(providerId)
     ? providerId
     : DEFAULT_PROVIDER_ID;
 }