@golba98/codexa 1.0.5 → 1.0.7

package/src/config/updateCheckCache.ts

@@ -9,11 +9,16 @@ export interface UpdateCheckCache {
   updateAvailable: boolean;
 }
 
-const CACHE_FILE = join(homedir(), ".codexa-update-check.json");
+// Resolved per call (not at module load) so HOME changes — e.g. test isolation —
+// are honored. See the same pattern in src/core/models/providerModelCache.ts.
+export function getUpdateCheckCacheFilePath(): string {
+  const home = process.env.USERPROFILE ?? process.env.HOME ?? homedir();
+  return join(home, ".codexa-update-check.json");
+}
 
-export function loadUpdateCheckCache(): UpdateCheckCache | null {
+export function loadUpdateCheckCache(filePath = getUpdateCheckCacheFilePath()): UpdateCheckCache | null {
   try {
-    const text = readFileSync(CACHE_FILE, "utf-8");
+    const text = readFileSync(filePath, "utf-8");
     const data = JSON.parse(text) as Record<string, unknown>;
     if (typeof data.lastChecked !== "number") return null;
     if (typeof data.currentVersion !== "string") return null;
@@ -28,12 +33,12 @@ export function loadUpdateCheckCache(): UpdateCheckCache | null {
   }
 }
 
-export function saveUpdateCheckCache(cache: UpdateCheckCache): void {
+export function saveUpdateCheckCache(cache: UpdateCheckCache, filePath = getUpdateCheckCacheFilePath()): void {
   try {
-    mkdirSync(dirname(CACHE_FILE), { recursive: true });
-    const tmp = `${CACHE_FILE}.tmp`;
+    mkdirSync(dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
     writeFileSync(tmp, JSON.stringify(cache, null, 2), "utf-8");
-    renameSync(tmp, CACHE_FILE);
+    renameSync(tmp, filePath);
   } catch {
     // Best-effort — never crash on cache write failure.
   }
@@ -43,6 +48,11 @@ function stripV(v: string): string {
   return v.startsWith("v") ? v.slice(1) : v;
 }
 
+/** Returns true when a cache entry was created by the running Codexa version. */
+export function isCacheForRunningVersion(cache: UpdateCheckCache, runningVersion: string): boolean {
+  return stripV(cache.currentVersion) === stripV(runningVersion);
+}
+
 /**
  * Returns true only when the cache is still usable:
  * - `runningVersion` matches the version the cache was written for (version-mismatch = stale)
@@ -54,7 +64,7 @@ export function isCacheValid(
   runningVersion?: string,
 ): boolean {
   if (runningVersion !== undefined) {
-    if (stripV(cache.currentVersion) !== stripV(runningVersion)) {
+    if (!isCacheForRunningVersion(cache, runningVersion)) {
       return false;
     }
   }

package/src/core/debug/modelStateDebug.ts

@@ -1,5 +1,6 @@
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { dirname } from "path";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 type ModelStateDebugDetails = Record<string, unknown>;
 
@@ -12,7 +13,7 @@ export function isModelStateDebugEnabled(): boolean {
 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");
+    || resolveCodexaDebugLogPath();
 }
 
 export function traceModelStateDebug(event: string, details: ModelStateDebugDetails = {}): void {

package/src/core/models/providerModelCache.ts

@@ -46,30 +46,18 @@ function readCacheFile(cacheFile: string): ProviderModelCacheFile | null {
   }
 }
 
-// A model id is passed straight to a provider CLI, so it must be a bare token.
-// Discovery scrapes CLI output, and a buggy build can bake an ANSI escape into
-// an id (e.g. "claude-fable-5\x1b[1m"). Reject rather than repair: a cached id
-// we cannot vouch for is dropped so discovery re-probes for a clean one.
-const VALID_MODEL_ID = /^[A-Za-z0-9._:\/-]+$/;
-
-function isUsableModel(model: unknown): model is ProviderModel {
-  if (typeof model !== "object" || model === null) {
-    return false;
-  }
-  const candidate = model as ProviderModel;
-  return typeof candidate.id === "string"
-    && typeof candidate.modelId === "string"
-    && typeof candidate.label === "string"
-    && VALID_MODEL_ID.test(candidate.id)
-    && VALID_MODEL_ID.test(candidate.modelId);
-}
-
 function isValidEntry(entry: unknown): entry is CachedProviderModels {
   if (typeof entry !== "object" || entry === null) {
     return false;
   }
   const candidate = entry as CachedProviderModels;
-  return typeof candidate.discoveredAt === "number" && Array.isArray(candidate.models);
+  return typeof candidate.discoveredAt === "number"
+    && Array.isArray(candidate.models)
+    && candidate.models.every((model) =>
+      typeof model === "object" && model !== null
+      && typeof model.id === "string"
+      && typeof model.modelId === "string"
+      && typeof model.label === "string");
 }
 
 export function loadCachedProviderModels(
@@ -78,14 +66,10 @@ export function loadCachedProviderModels(
 ): CachedProviderModels | null {
   const cache = readCacheFile(cacheFile);
   const entry = cache?.providers?.[providerId];
-  if (!entry || !isValidEntry(entry)) {
-    return null;
-  }
-  const models = entry.models.filter(isUsableModel);
-  if (models.length === 0) {
+  if (!entry || !isValidEntry(entry) || entry.models.length === 0) {
     return null;
   }
-  return { discoveredAt: entry.discoveredAt, models };
+  return entry;
 }
 
 export function saveCachedProviderModels(

package/src/core/perf/renderDebug.ts

@@ -1,6 +1,7 @@
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
-import { useEffect, useRef } from "react";
+import { dirname } from "path";
+import { useEffect, useRef } from "react";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 type DebugEnv = Record<string, string | undefined>;
 
@@ -11,7 +12,7 @@ let renderTraceEnabled = false;
 let lifecycleEnabled = false;
 let flickerEnabled = false;
 let plainActionsEnabled = false;
-let logPath = join(process.cwd(), ".codexa", "debug", "render-status.log");
+let logPath = resolveCodexaDebugLogPath();
 let sessionId = `${Date.now()}-${process.pid}`;
 const counters = new Map<string, number>();
 
@@ -29,7 +30,7 @@ function configureFromEnv(env: DebugEnv = process.env): void {
   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-status.log");
+  logPath = env["CODEXA_RENDER_DEBUG_FILE"]?.trim() || resolveCodexaDebugLogPath(env);
   sessionId = `${Date.now()}-${process.pid}`;
   configured = true;
 }

package/src/core/providerLauncher/launcher.ts

@@ -39,7 +39,7 @@ export function buildProviderLaunchSpec(provider: ProviderConfig, cwd: string):
   if (!provider.enabled) {
     return {
       status: "disabled",
-      message: `${provider.displayName} is disabled. Configure a command in .codexa/providers.json before launching it.`,
+      message: `${provider.displayName} is disabled. Configure a command in Codexa's provider settings before launching it.`,
     };
   }
 

package/src/core/providerLauncher/workspaceConfig.ts

@@ -1,7 +1,8 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
-import { DEFAULT_MODEL } from "../../config/settings.js";
-import { normalizeWorkspaceRoot } from "../workspace/workspaceRoot.js";
+import { DEFAULT_MODEL } from "../../config/settings.js";
+import { resolveCodexaWorkspaceDataDir } from "../workspace/appData.js";
+import { normalizeWorkspaceRoot } from "../workspace/workspaceRoot.js";
 import { isKnownProviderId } from "./registry.js";
 import { getDefaultRouteModel, getProviderRuntime, isProviderRouteConfigured, isProviderRoutableInCodexa } from "../providerRuntime/registry.js";
 import { normalizeGeminiModelId } from "../providerRuntime/models.js";
@@ -17,8 +18,12 @@ const DEPRECATED_ANTIGRAVITY_PROVIDER_ID = "antigravity";
 const DEPRECATED_ANTIGRAVITY_BACKENDS = new Set(["antigravity-cli-auth", "agy"]);
 const DEPRECATED_GOOGLE_PROVIDER_ID = "google";
 
-export function getProviderWorkspaceConfigFile(workspaceRoot: string): string {
-  return join(normalizeWorkspaceRoot(workspaceRoot), ".codexa", "providers.json");
+export function getProviderWorkspaceConfigFile(workspaceRoot: string): string {
+  return join(resolveCodexaWorkspaceDataDir(normalizeWorkspaceRoot(workspaceRoot)), "providers.json");
+}
+
+export function getLegacyProviderWorkspaceConfigFile(workspaceRoot: string): string {
+  return join(normalizeWorkspaceRoot(workspaceRoot), ".codexa", "providers.json");
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -345,15 +350,24 @@ export function serializeProviderWorkspaceConfig(config: ProviderWorkspaceConfig
   };
 }
 
-export function loadProviderWorkspaceConfig(workspaceRoot: string): ProviderWorkspaceConfig {
-  const filePath = getProviderWorkspaceConfigFile(workspaceRoot);
-  if (!existsSync(filePath)) return {};
-  try {
-    return parseProviderWorkspaceConfig(JSON.parse(readFileSync(filePath, "utf-8")));
-  } catch {
-    return {};
-  }
-}
+export function loadProviderWorkspaceConfig(workspaceRoot: string): ProviderWorkspaceConfig {
+  const filePath = getProviderWorkspaceConfigFile(workspaceRoot);
+  if (existsSync(filePath)) {
+    try {
+      return parseProviderWorkspaceConfig(JSON.parse(readFileSync(filePath, "utf-8")));
+    } catch {
+      return {};
+    }
+  }
+
+  const legacyFilePath = getLegacyProviderWorkspaceConfigFile(workspaceRoot);
+  if (!existsSync(legacyFilePath)) return {};
+  try {
+    return parseProviderWorkspaceConfig(JSON.parse(readFileSync(legacyFilePath, "utf-8")));
+  } catch {
+    return {};
+  }
+}
 
 export function saveProviderWorkspaceConfig(workspaceRoot: string, config: ProviderWorkspaceConfig): void {
   const filePath = getProviderWorkspaceConfigFile(workspaceRoot);

package/src/core/providerRuntime/antigravity.ts

@@ -165,7 +165,18 @@ export function getAgyModelSelector(
 }
 
 export function getAntigravityModelLabel(modelId: string): string {
-  return getActiveAgyModels().find((m) => m.id === modelId)?.label ?? modelId;
+  const discovered = getActiveAgyModels().find((m) => m.id === modelId || m.modelId === modelId);
+  if (discovered) return discovered.label;
+
+  const normalizedId = migrateAntigravityLegacyModelId(modelId).modelId;
+  const knownLabels: Record<string, string> = {
+    "gemini-3.5-flash": "Gemini 3.5 Flash",
+    "gemini-3.1-pro": "Gemini 3.1 Pro",
+    "claude-sonnet-4.6-thinking": "Claude Sonnet 4.6 (Thinking)",
+    "claude-opus-4.6-thinking": "Claude Opus 4.6 (Thinking)",
+    "gpt-oss-120b-medium": "GPT-OSS 120B",
+  };
+  return knownLabels[normalizedId] ?? modelId;
 }
 
 // ---------------------------------------------------------------------------

package/src/core/providerRuntime/registry.ts

@@ -199,17 +199,21 @@ export function resolveActiveProviderRoute(options: {
       route.modelId = resolveGeminiModelId(route.modelSelection);
     } else if (route.providerId === "google") {
       route.modelId = normalizeGeminiModelId(route.modelId);
-    } else if (route.providerId === "anthropic") {
-      const discovery = discoverProviderModels("anthropic");
+    } else if (route.providerId === "anthropic") {
+      const discovery = discoverProviderModels("anthropic");
       const stillAvailable = discovery.models.some((model) =>
         model.modelId === route.modelId ||
         model.id === route.modelId ||
         model.canonicalId === route.modelId
       );
-      const hasNonFallbackModels = discovery.models.some((model) => model.source !== "fallback");
-      if (discovery.status === "ready" && hasNonFallbackModels && discovery.models.length > 0 && !stillAvailable) {
-        route.modelId = discovery.models[0]!.modelId;
-      }
+      const hasNonFallbackModels = discovery.models.some((model) => model.source !== "fallback");
+      // Preserve explicit versioned Claude IDs even when the current discovery
+      // output does not advertise that historical model. Short aliases are the
+      // values that need migration to the first currently discovered model.
+      const isKnownShortAlias = ANTHROPIC_FALLBACK_MODELS.some((model) => model.modelId === route.modelId);
+      if (discovery.status === "ready" && hasNonFallbackModels && discovery.models.length > 0 && !stillAvailable && isKnownShortAlias) {
+        route.modelId = discovery.models[0]!.modelId;
+      }
     } else if (route.providerId === "local") {
       const discovery = discoverProviderModels("local");
       const selectedModel = typeof discovery.diagnostics?.selectedModel === "string"

package/src/core/shared/attachments.ts

@@ -74,16 +74,16 @@ export async function importExternalFile(
   return destPath;
 }
 
-export function rewritePromptWithImportedPaths(
-  prompt: string,
-  replacements: Array<{ rawPath: string; workspaceRelativePath: string }>,
-): string {
-  let result = prompt;
-  for (const { rawPath, workspaceRelativePath } of replacements) {
-    const needsQuotes = /\s/.test(workspaceRelativePath);
-    const quotedReplacement = needsQuotes
-      ? `"${workspaceRelativePath}"`
-      : workspaceRelativePath;
+export function rewritePromptWithImportedPaths(
+  prompt: string,
+  replacements: Array<{ rawPath: string; replacementPath: string }>,
+): string {
+  let result = prompt;
+  for (const { rawPath, replacementPath } of replacements) {
+    const needsQuotes = /\s/.test(replacementPath);
+    const quotedReplacement = needsQuotes
+      ? `"${replacementPath}"`
+      : replacementPath;
     // Replace quoted forms first so the unquoted pass doesn't double-replace
     result = result.split(`"${rawPath}"`).join(quotedReplacement);
     result = result.split(`'${rawPath}'`).join(quotedReplacement);

package/src/core/terminal/frameLock.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 import { isTerminalResizing } from "./terminalControl.js";
 
 export interface FrameLockOptions {
@@ -28,7 +29,7 @@ export function wrapStdoutWithFrameLock({
   if (env.CODEXA_RENDER_DEBUG === "1") {
     try {
       const logPath = env.CODEXA_RENDER_DEBUG_FILE?.trim()
-        || path.join(process.cwd(), ".codexa", "debug", "render-status.log");
+        || resolveCodexaDebugLogPath(env);
       const logDir = path.dirname(logPath);
       if (!fs.existsSync(logDir)) {
         fs.mkdirSync(logDir, { recursive: true });

package/src/core/terminal/terminalTitle.ts

@@ -1,7 +1,8 @@
 import { APP_NAME, type TerminalTitleMode, formatTerminalTitlePath } from "../../config/settings.js";
 import { appendFileSync, mkdirSync } from "fs";
-import { dirname, join } from "path";
+import { dirname } from "path";
 import * as renderDebug from "../perf/renderDebug.js";
+import { resolveCodexaDebugLogPath } from "../workspace/appData.js";
 
 export const DEFAULT_TERMINAL_TITLE = APP_NAME;
 
@@ -52,7 +53,7 @@ function findIncompleteOscTitleStart(text: string): number {
 
 const TERMINAL_TITLE_DEBUG_LOG_PATH = process.env["CODEXA_TERMINAL_TITLE_DEBUG_FILE"]?.trim()
   || process.env["CODEXA_RENDER_DEBUG_FILE"]?.trim()
-  || join(process.cwd(), ".codexa", "debug", "render-status.log");
+  || resolveCodexaDebugLogPath();
 
 let terminalTitleLifecycleState = "unknown";
 

package/src/core/version/packageManager.ts

@@ -0,0 +1,119 @@
+import type { ChildProcess } from "child_process";
+import {
+  runCommand,
+  runShellCommand,
+  type CommandResult,
+  type CommandSpec,
+  type CommandStreamHandlers,
+} from "../process/CommandRunner.js";
+import { CODEXA_NPM_PACKAGE } from "./updateCheck.js";
+
+export type GlobalPackageManager = "npm" | "pnpm" | "yarn" | "bun";
+
+const UPDATE_TIMEOUT_MS = 300_000;
+
+const PACKAGE_SPEC = `${CODEXA_NPM_PACKAGE}@latest`;
+
+// Yarn Classic only — Yarn Berry (v2+) removed `yarn global`, but Berry installs
+// don't produce the global launcher paths we detect, so Classic is the only case.
+const UPDATE_ARGV: Record<GlobalPackageManager, readonly string[]> = {
+  npm: ["npm", "install", "-g", PACKAGE_SPEC],
+  pnpm: ["pnpm", "add", "-g", PACKAGE_SPEC],
+  yarn: ["yarn", "global", "add", PACKAGE_SPEC],
+  bun: ["bun", "add", "-g", PACKAGE_SPEC],
+};
+
+/**
+ * Infers which package manager owns the global Codexa install from the
+ * launcher script location (CODEXA_LAUNCHER_SCRIPT, set by bin/codexa.js).
+ */
+export function detectGlobalPackageManager(
+  env: NodeJS.ProcessEnv = process.env,
+  launcherPathOverride?: string,
+): GlobalPackageManager {
+  const launcherPath = launcherPathOverride ?? env.CODEXA_LAUNCHER_SCRIPT ?? process.argv[1] ?? "";
+  const normalized = launcherPath.toLowerCase().replace(/\\/g, "/");
+  if (!normalized) return "npm";
+
+  if (normalized.includes("pnpm")) return "pnpm";
+  if (normalized.includes("/.bun/") || normalized.includes("/bun/install/global/")) return "bun";
+  if (normalized.includes("/.yarn/") || normalized.includes("/yarn/") || normalized.includes(".config/yarn")) {
+    return "yarn";
+  }
+  return "npm";
+}
+
+export function getUpdateCommand(pm: GlobalPackageManager): {
+  displayCommand: string;
+  argv: readonly string[];
+} {
+  const argv = UPDATE_ARGV[pm];
+  return { displayCommand: argv.join(" "), argv };
+}
+
+export interface RunUpdateCommandDeps {
+  platform?: NodeJS.Platform;
+  cwd?: string;
+  runCommandFn?: (
+    spec: CommandSpec,
+    handlers?: CommandStreamHandlers,
+  ) => { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void };
+  runShellCommandFn?: (
+    command: string,
+    options: Pick<CommandSpec, "cwd" | "env" | "timeoutMs">,
+    handlers?: CommandStreamHandlers,
+  ) => { child: ChildProcess; result: Promise<CommandResult>; cancel: () => void };
+}
+
+/**
+ * Runs the global update command for the detected package manager.
+ * POSIX spawns the argv directly; Windows routes the constant, whitelisted
+ * command string through cmd.exe so .cmd shims (npm.cmd, pnpm.cmd) resolve —
+ * spawning them without a shell throws EINVAL on Node >= 18.20.
+ */
+export function runUpdateCommand(
+  pm: GlobalPackageManager,
+  handlers: CommandStreamHandlers = {},
+  deps: RunUpdateCommandDeps = {},
+): { result: Promise<CommandResult>; cancel: () => void } {
+  const platform = deps.platform ?? process.platform;
+  const cwd = deps.cwd ?? process.cwd();
+  const { displayCommand, argv } = getUpdateCommand(pm);
+
+  if (platform === "win32") {
+    const runShell = deps.runShellCommandFn ?? runShellCommand;
+    const { result, cancel } = runShell(displayCommand, { cwd, timeoutMs: UPDATE_TIMEOUT_MS }, handlers);
+    return { result, cancel };
+  }
+
+  const run = deps.runCommandFn ?? runCommand;
+  const { result, cancel } = run(
+    { executable: argv[0]!, args: [...argv.slice(1)], cwd, timeoutMs: UPDATE_TIMEOUT_MS },
+    handlers,
+  );
+  return { result, cancel };
+}
+
+const PERMISSION_STDERR_RE = /EACCES|EPERM|permission denied/i;
+
+/** npm reports EACCES via stderr with a nonzero exit, not as a spawn error. */
+export function isPermissionError(result: CommandResult): boolean {
+  if (result.errorCode === "EACCES" || result.errorCode === "EPERM") return true;
+  return result.exitCode !== 0 && PERMISSION_STDERR_RE.test(result.stderr);
+}
+
+export function formatPermissionGuidance(pm: GlobalPackageManager): string {
+  const { displayCommand } = getUpdateCommand(pm);
+  const lines = [
+    `${pm} could not write to its global package directory, so the update was not installed.`,
+  ];
+  if (pm === "npm") {
+    lines.push(
+      "Check where global packages are installed with `npm config get prefix` and make sure that directory is writable by your user, or switch to a user-writable prefix (for example `npm config set prefix ~/.npm-global`, then add its bin directory to PATH).",
+    );
+  } else {
+    lines.push(`Make sure the ${pm} global package directory is writable by your user.`);
+  }
+  lines.push(`You can also run the command manually in a terminal with the right permissions: ${displayCommand}`);
+  return lines.join("\n");
+}

package/src/core/version/updateCheck.ts

@@ -154,7 +154,10 @@ export async function checkForUpdates(
   }
 }
 
-export function formatUpdateInstructions(result: UpdateCheckResult | null): string {
+export function formatUpdateInstructions(
+  result: UpdateCheckResult | null,
+  updateCommand: string = CODEXA_UPDATE_COMMAND,
+): string {
   const current = result?.currentVersion ?? APP_VERSION;
   const latest = result?.latestVersion ?? "unknown";
 
@@ -166,21 +169,24 @@ export function formatUpdateInstructions(result: UpdateCheckResult | null): stri
     ].join("\n");
   }
 
-  let statusLine: string;
-  if (result?.status === "update-available" && result.latestVersion) {
-    statusLine = `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`;
-  } else if (result?.status === "up-to-date") {
-    statusLine = "Already up to date.";
-  } else {
-    statusLine = "Status unknown — could not reach npm registry.";
+  if (result?.status === "up-to-date") {
+    return [
+      "Codexa is up to date.",
+      `Current installed version: ${current}`,
+      `npm latest version:        ${latest}`,
+    ].join("\n");
   }
 
+  const statusLine = result?.status === "update-available" && result.latestVersion
+    ? `Update available: Codexa ${formatVersionLabel(result.latestVersion)}`
+    : "Status unknown — could not reach npm registry.";
+
   return [
     `Current installed version: ${current}`,
     `npm latest version:        ${latest}`,
     `Status:          ${statusLine}`,
     "",
-    `Run: ${CODEXA_UPDATE_COMMAND}`,
+    `Run: ${updateCommand}`,
   ].join("\n");
 }
 

package/src/core/workspace/appData.ts

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize } from "node:path";
+
+type Platform = "win32" | "darwin" | "linux" | string;
+type Environment = Record<string, string | undefined>;
+
+export function resolveCodexaDataDir(
+  platformOverride?: Platform,
+  env: Environment = process.env,
+  home = homedir(),
+): string {
+  const configuredDir = env["CODEXA_DATA_DIR"]?.trim();
+  if (configuredDir) return configuredDir;
+
+  const platform = platformOverride ?? process.platform;
+  if (platform === "win32") {
+    return join(env["LOCALAPPDATA"]?.trim() || env["APPDATA"]?.trim() || join(home, "AppData", "Local"), "Codexa");
+  }
+  if (platform === "darwin") {
+    return join(home, "Library", "Application Support", "Codexa");
+  }
+
+  return join(env["XDG_DATA_HOME"]?.trim() || join(home, ".local", "share"), "codexa");
+}
+
+export function workspaceStorageKey(workspaceRoot: string): string {
+  return createHash("sha256").update(workspaceRoot).digest("hex").slice(0, 16);
+}
+
+export function resolveCodexaWorkspaceDataDir(workspaceRoot: string): string {
+  return join(resolveCodexaDataDir(), "workspaces", workspaceStorageKey(workspaceRoot));
+}
+
+export function resolveCodexaAttachmentDir(workspaceRoot: string, configuredDir: string): string {
+  if (isAbsolute(configuredDir)) return configuredDir;
+
+  const normalized = configuredDir.trim().replace(/\\/g, "/").replace(/^\.codexa\/?/, "") || "attachments";
+  const safeRelativeDir = normalize(normalized).replace(/^(\.\.([/\\]|$))+/, "") || "attachments";
+  return join(resolveCodexaWorkspaceDataDir(workspaceRoot), safeRelativeDir);
+}
+
+export function resolveCodexaDebugLogPath(env: Environment = process.env): string {
+  return join(resolveCodexaDataDir(undefined, env), "debug", "render-status.log");
+}

package/src/core/workspace/planStorage.ts

@@ -1,9 +1,10 @@
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
-import { isNoiseLine } from "../providers/codexTranscript.js";
-import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { homedir } from "os";
+import { join } from "path";
+import { isNoiseLine } from "../providers/codexTranscript.js";
+import { sanitizeTerminalOutput } from "../terminal/terminalSanitize.js";
+import { resolveCodexaDataDir } from "./appData.js";
 
 type Platform = "win32" | "darwin" | "linux" | string;
 
@@ -91,15 +92,8 @@ export function resolvePlanDir(platformOverride?: Platform): string {
     return join(homedir(), "AppData", "Local", "Codexa", "plans");
   }
 
-  if (platform === "darwin") {
-    return join(homedir(), "Library", "Application Support", "Codexa", "plans");
-  }
-
-  // Linux and other Unix-like
-  const xdgDataHome = process.env["XDG_DATA_HOME"];
-  if (xdgDataHome) return join(xdgDataHome, "codexa", "plans");
-  return join(homedir(), ".local", "share", "codexa", "plans");
-}
+  return join(resolveCodexaDataDir(platform), "plans");
+}
 
 // SHA-256 of the workspace path ensures filename uniqueness across projects with the same name.
 function workspaceHash(workspaceRoot: string): string {