@kyo-so/cli 0.9.0 → 0.10.0

package/dist/index.js

@@ -169500,6 +169500,9 @@ function defineConfig(config) {
 // src/core/runReview.ts
 import { resolve as resolve6 } from "node:path";
 
+// src/config/schema.ts
+import { isAbsolute } from "node:path";
+
 // node_modules/zod/v4/classic/external.js
 var exports_external = {};
 __export(exports_external, {
@@ -183777,7 +183780,10 @@ function date4(params) {
 // node_modules/zod/v4/classic/external.js
 config(en_default());
 // src/config/schema.ts
-var agentSchema = exports_external.object({
+var CODEX_OPENROUTER_PROVIDER = "openrouter";
+var CODEX_DEFAULT_PROVIDER = "default";
+var CODEX_OPENROUTER_MODEL_REQUIRED_ISSUE = "codex_openrouter_model_required";
+var baseAgentSchema = exports_external.object({
   enabled: exports_external.boolean().default(true),
   type: exports_external.literal("acp").default("acp"),
   command: exports_external.string(),
@@ -183799,6 +183805,24 @@ var agentSchema = exports_external.object({
     envWhitelist: exports_external.array(exports_external.string())
   })
 });
+var codexAgentSchema = baseAgentSchema.extend({
+  provider: exports_external.enum([CODEX_OPENROUTER_PROVIDER, CODEX_DEFAULT_PROVIDER]).optional(),
+  allowProjectProvider: exports_external.array(exports_external.string().min(1).refine(isAbsolute, {
+    message: "must contain only absolute project directory paths for exact matching"
+  })).default([])
+}).superRefine((agent, context) => {
+  if (agent.provider !== CODEX_OPENROUTER_PROVIDER || (agent.model?.trim().length ?? 0) > 0) {
+    return;
+  }
+  context.addIssue({
+    code: exports_external.ZodIssueCode.custom,
+    path: ["model"],
+    message: 'model must be a non-empty string when provider is "openrouter".',
+    params: {
+      kyosoIssue: CODEX_OPENROUTER_MODEL_REQUIRED_ISSUE
+    }
+  });
+});
 var kyosoConfigSchema = exports_external.object({
   entrypoints: exports_external.object({
     mcp: exports_external.boolean(),
@@ -183811,8 +183835,8 @@ var kyosoConfigSchema = exports_external.object({
     diffReview: exports_external.boolean()
   }),
   agents: exports_external.object({
-    codex: agentSchema,
-    claude: agentSchema
+    codex: codexAgentSchema,
+    claude: baseAgentSchema
   }),
   workspace: exports_external.object({
     mode: exports_external.literal("temp_snapshot"),
@@ -183865,7 +183889,7 @@ var kyosoConfigSchema = exports_external.object({
   })
 });
 function agentConfigLeafPaths(agent) {
-  return [
+  const paths = [
     `agents.${agent}.enabled`,
     `agents.${agent}.type`,
     `agents.${agent}.command`,
@@ -183881,6 +183905,10 @@ function agentConfigLeafPaths(agent) {
     `agents.${agent}.auth.recommendedEnv`,
     `agents.${agent}.auth.envWhitelist`
   ];
+  if (agent === "codex") {
+    paths.push("agents.codex.provider", "agents.codex.allowProjectProvider");
+  }
+  return paths;
 }
 var kyosoConfigKnownLeafPaths = [
   "entrypoints.mcp",
@@ -183953,9 +183981,10 @@ var defaultConfig = {
       enabled: true,
       type: "acp",
       command: "npx",
-      args: ["-y", "@agentclientprotocol/codex-acp@1.1.0"],
+      args: ["-y", "@agentclientprotocol/codex-acp@1.1.2"],
       role: "implementation_reviewer",
       timeoutMs: 120000,
+      allowProjectProvider: [],
       env: {
         INITIAL_AGENT_MODE: "read-only",
         KYOSO_CHILD_AGENT: "1"
@@ -183977,7 +184006,7 @@ var defaultConfig = {
       enabled: true,
       type: "acp",
       command: "npx",
-      args: ["-y", "@agentclientprotocol/claude-agent-acp@0.57.0"],
+      args: ["-y", "@agentclientprotocol/claude-agent-acp@0.58.1"],
       role: "architecture_security_reviewer",
       timeoutMs: 300000,
       env: {
@@ -184068,17 +184097,21 @@ var defaultConfig = {
 };
 
 // src/config/loadConfig.ts
-import { access, readFile as readFile3 } from "node:fs/promises";
+import { access, readFile as readFile3, realpath } from "node:fs/promises";
 import { homedir as homedir2 } from "node:os";
 import { stderr, stdin } from "node:process";
-import { extname as extname2, join as join2, resolve as resolve2 } from "node:path";
+import { dirname as dirname3, extname as extname2, isAbsolute as isAbsolute2, join as join2, resolve as resolve2 } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // src/config/projectScope.ts
 var PROJECT_GLOBAL_ONLY_MESSAGE = "Move global-only settings to the user global config:";
+var PROJECT_GLOBAL_ONLY_REASONS = {
+  "agents.codex.allowProjectProvider": "must be a user-global exact project-directory allowlist"
+};
 var kyosoConfigOverridePaths = [
   "agents.codex.enabled",
   "agents.codex.model",
+  "agents.codex.provider",
   "agents.codex.effort",
   "agents.codex.role",
   "agents.codex.timeoutMs",
@@ -184118,6 +184151,11 @@ function collectProjectScopeViolations(config2) {
   const violations = [];
   for (const leaf of leaves) {
     const path = leaf.path.join(".");
+    const globalOnlyReason = PROJECT_GLOBAL_ONLY_REASONS[path];
+    if (globalOnlyReason) {
+      violations.push({ path, reason: globalOnlyReason });
+      continue;
+    }
     if (!isAllowedProjectPath(leaf.path)) {
       violations.push({ path });
       continue;
@@ -184278,7 +184316,7 @@ function sanitizeText(value) {
   return SENSITIVE_TEXT_PATTERNS.reduce((text, pattern) => text.replace(pattern, REDACTION), value);
 }
 function sanitizeTextForDisplay(value, maxChars = 240) {
-  const compact = sanitizeText(value).replace(/\s+/g, " ").trim();
+  const compact = sanitizeText(value).replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "").replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, "").replace(/\s+/g, " ").trim();
   if (compact.length <= maxChars)
     return compact;
   return `${compact.slice(0, Math.max(0, maxChars - 3))}...`;
@@ -185322,6 +185360,25 @@ function isMissingPathError(error51) {
 }
 
 // src/config/loadConfig.ts
+var configValidationContexts = new WeakMap;
+class ProjectOpenRouterAuthorizationError extends Error {
+  code = "PROJECT_OPENROUTER_AUTHORIZATION_REQUIRED";
+  projectPath;
+  projectDirectory;
+  layer;
+  globalConfigPath;
+  constructor(input) {
+    const projectPath = sanitizeWarningText(input.projectPath);
+    const projectDirectory = sanitizeWarningText(input.projectDirectory);
+    const globalConfigPath = sanitizeWarningText(input.globalConfigPath);
+    super(`Project config ${projectPath} changes Codex OpenRouter routing, but its directory ${projectDirectory} is not in the user-global allowlist. Add ${JSON.stringify(projectDirectory)} to agents.codex.allowProjectProvider in ${globalConfigPath} to permit project-level external provider routing.`);
+    this.name = "ProjectOpenRouterAuthorizationError";
+    this.projectPath = projectPath;
+    this.projectDirectory = projectDirectory;
+    this.layer = input.layer;
+    this.globalConfigPath = globalConfigPath;
+  }
+}
 var KNOWN_GLOBAL_CONFIG_LEAF_PATHS = new Set(kyosoConfigKnownLeafPaths);
 var GLOBAL_CONFIG_RECORD_PREFIXES = kyosoConfigRecordPrefixes.map((path) => path.split("."));
 var SECURITY_SENSITIVE_GLOBAL_PREFIXES = kyosoConfigSecuritySensitivePrefixes.map((path) => path.split("."));
@@ -185349,11 +185406,12 @@ async function loadConfig(options = {}) {
     }
     if (options.configPath) {
       const explicitConfigPath = resolve2(cwd, options.configPath);
-      if (!await exists(explicitConfigPath)) {
+      const projectConfig = await resolveProjectConfigIdentity(explicitConfigPath);
+      if (!projectConfig) {
         throw new Error(`Config file not found: ${explicitConfigPath} (from --config)`);
       }
       const loaded = await loadProjectConfig({
-        configPath: explicitConfigPath,
+        projectConfig,
         baseConfig: mergedConfig,
         globalConfigPath,
         options
@@ -185367,19 +185425,29 @@ async function loadConfig(options = {}) {
     } else {
       const projectTomlPath = resolve2(cwd, "kyoso.toml");
       const projectTsPath = resolve2(cwd, "kyoso.config.ts");
-      const hasProjectToml = await exists(projectTomlPath);
-      const hasProjectTs = await exists(projectTsPath);
-      if (hasProjectToml) {
-        mergedConfig = mergeProjectTomlConfig(mergedConfig, await loadTomlConfigFile(projectTomlPath), { projectPath: projectTomlPath, globalConfigPath });
-        configPath = projectTomlPath;
-        sources.push({ path: projectTomlPath, layer: "project_toml" });
-        if (hasProjectTs) {
+      const projectToml = await resolveProjectConfigIdentity(projectTomlPath);
+      const projectTs = await resolveProjectConfigIdentity(projectTsPath);
+      if (projectToml) {
+        const loaded = await loadProjectConfig({
+          projectConfig: projectToml,
+          baseConfig: mergedConfig,
+          globalConfigPath,
+          options
+        });
+        mergedConfig = loaded.mergedConfig;
+        configPath = loaded.configPath;
+        configHash = loaded.configHash;
+        configTrustStatus = loaded.configTrustStatus;
+        sources.push(loaded.source);
+        warnings.push(...loaded.warnings);
+        if (projectTs) {
           warnings.push(`kyoso.config.ts was ignored because kyoso.toml takes precedence: ${projectTsPath}`);
         }
-      } else if (hasProjectTs) {
+      } else if (projectTs) {
         const loaded = await loadProjectTsConfig({
-          configPath: projectTsPath,
+          projectConfig: projectTs,
           baseConfig: mergedConfig,
+          globalConfigPath,
           options
         });
         mergedConfig = loaded.mergedConfig;
@@ -185391,9 +185459,17 @@ async function loadConfig(options = {}) {
       }
     }
   }
-  const parsed = kyosoConfigSchema.parse(mergedConfig);
+  const parsed = kyosoConfigSchema.safeParse(mergedConfig);
+  if (!parsed.success) {
+    const source = sources.at(-1);
+    configValidationContexts.set(parsed.error, {
+      source,
+      projectTsExecuted: source?.layer === "project_ts" && isTrustedProjectConfigExecution(configTrustStatus)
+    });
+    throw parsed.error;
+  }
   return {
-    config: parsed,
+    config: parsed.data,
     configPath,
     configHash,
     configTrustStatus,
@@ -185441,62 +185517,170 @@ function pathStartsWith(path, prefix) {
   return path.length >= prefix.length && prefix.every((part, index) => path[index] === part);
 }
 async function loadProjectConfig(input) {
-  const extension = extname2(input.configPath);
+  const { canonicalDirectory, canonicalPath, requestedPath } = input.projectConfig;
+  const extension = extname2(requestedPath);
   if (extension === ".toml") {
+    const projectTomlConfig = await loadTomlConfigFile(canonicalPath);
+    const projectChangesOpenRouterRoute = projectConfigChangesOpenRouterRoute(projectTomlConfig, input.baseConfig);
+    await assertProjectOpenRouterAuthorization({
+      projectConfig: projectTomlConfig,
+      projectPath: requestedPath,
+      projectDirectory: canonicalDirectory,
+      layer: "project_toml",
+      baseConfig: input.baseConfig,
+      globalConfigPath: input.globalConfigPath
+    });
+    const projectMergedConfig = mergeProjectTomlConfig(input.baseConfig, projectTomlConfig, {
+      projectPath: requestedPath,
+      globalConfigPath: input.globalConfigPath
+    });
     return {
-      mergedConfig: mergeProjectTomlConfig(input.baseConfig, await loadTomlConfigFile(input.configPath), {
-        projectPath: input.configPath,
-        globalConfigPath: input.globalConfigPath
-      }),
-      configPath: input.configPath,
+      mergedConfig: applyProjectCodexProviderReset(input.baseConfig, projectTomlConfig, projectMergedConfig),
+      configPath: requestedPath,
       configTrustStatus: "not_found",
-      source: { path: input.configPath, layer: "project_toml" },
-      warnings: []
+      source: { path: requestedPath, layer: "project_toml" },
+      warnings: projectChangesOpenRouterRoute ? [openRouterProjectConfigWarning(requestedPath)] : []
     };
   }
   if (extension === ".ts") {
     return await loadProjectTsConfig(input);
   }
-  throw new Error(`Unsupported config file extension for ${input.configPath}. Expected .toml or .ts.`);
+  throw new Error(`Unsupported config file extension for ${requestedPath}. Expected .toml or .ts.`);
+}
+function projectConfigSelectsOpenRouter(config2) {
+  return flattenLeaves(config2).some((leaf) => leaf.path.join(".") === "agents.codex.provider" && leaf.value === CODEX_OPENROUTER_PROVIDER);
+}
+function projectConfigSelectsDefaultProvider(config2) {
+  return flattenLeaves(config2).some((leaf) => leaf.path.join(".") === "agents.codex.provider" && leaf.value === CODEX_DEFAULT_PROVIDER);
+}
+function projectConfigSuppliesCodexModel(config2) {
+  return flattenLeaves(config2).some((leaf) => leaf.path.join(".") === "agents.codex.model");
+}
+function projectConfigChangesOpenRouterRoute(projectConfig, baseConfig) {
+  return projectConfigSelectsOpenRouter(projectConfig) || configSelectsOpenRouter(baseConfig) && projectConfigSuppliesCodexModel(projectConfig) && !projectConfigSelectsDefaultProvider(projectConfig);
+}
+function configSelectsOpenRouter(config2) {
+  return flattenLeaves(config2).some((leaf) => leaf.path.join(".") === "agents.codex.provider" && leaf.value === CODEX_OPENROUTER_PROVIDER);
+}
+function applyProjectCodexProviderReset(baseConfig, projectConfig, mergedConfig) {
+  if (!projectConfigSelectsDefaultProvider(projectConfig) || projectConfigSuppliesCodexModel(projectConfig) || !configSelectsOpenRouter(baseConfig) || !isRecord3(mergedConfig) || !isRecord3(mergedConfig.agents) || !isRecord3(mergedConfig.agents.codex)) {
+    return mergedConfig;
+  }
+  const codexWithoutInheritedModel = Object.fromEntries(Object.entries(mergedConfig.agents.codex).filter(([key]) => key !== "model"));
+  return {
+    ...mergedConfig,
+    agents: {
+      ...mergedConfig.agents,
+      codex: codexWithoutInheritedModel
+    }
+  };
+}
+function openRouterProjectConfigWarning(configPath) {
+  return `Project config ${sanitizeWarningText(configPath)} changes Codex OpenRouter routing under user-global authorization; it can route Codex review content through OpenRouter.`;
+}
+async function assertProjectOpenRouterAuthorization(input) {
+  if (!projectConfigChangesOpenRouterRoute(input.projectConfig, input.baseConfig)) {
+    return;
+  }
+  if (await projectProviderIsAuthorized(input.baseConfig, input.projectDirectory)) {
+    return;
+  }
+  throw new ProjectOpenRouterAuthorizationError({
+    projectPath: input.projectPath,
+    projectDirectory: input.projectDirectory,
+    layer: input.layer,
+    globalConfigPath: input.globalConfigPath
+  });
+}
+async function projectProviderIsAuthorized(config2, projectDirectory) {
+  if (!isRecord3(config2))
+    return false;
+  const agents = config2.agents;
+  if (!isRecord3(agents))
+    return false;
+  const codex = agents.codex;
+  if (!isRecord3(codex) || !Array.isArray(codex.allowProjectProvider)) {
+    return false;
+  }
+  for (const directory of codex.allowProjectProvider) {
+    if (typeof directory !== "string" || !isAbsolute2(directory))
+      continue;
+    const allowedDirectory = await existingRealpath(directory);
+    if (allowedDirectory === projectDirectory)
+      return true;
+  }
+  return false;
+}
+async function resolveProjectConfigIdentity(requestedPath) {
+  const canonicalPath = await existingRealpath(requestedPath);
+  return canonicalPath === undefined ? undefined : {
+    requestedPath,
+    canonicalPath,
+    canonicalDirectory: dirname3(canonicalPath)
+  };
+}
+async function existingRealpath(path) {
+  try {
+    return await realpath(path);
+  } catch {
+    return;
+  }
 }
 async function loadProjectTsConfig(input) {
+  const { canonicalDirectory, canonicalPath, requestedPath } = input.projectConfig;
   const warnings = [
     'kyoso.config.ts is deprecated; migrate to kyoso.toml (see README "Configuration")'
   ];
-  const source = await readFile3(input.configPath, "utf8");
+  const source = await readFile3(canonicalPath, "utf8");
   const configHash = hashConfigSource(source);
   const trustStorePath = input.options.trustStorePath ?? defaultTrustedConfigStorePath(input.options.env);
-  const trusted = await isTrustedConfig(trustStorePath, input.configPath, configHash);
+  const trusted = await isTrustedConfig(trustStorePath, canonicalPath, configHash);
   const trustDecision = await resolveTrustDecision({
-    configPath: input.configPath,
+    configPath: requestedPath,
     configHash,
     trusted,
     options: input.options
   });
   if (trustDecision.execute) {
-    const userConfig = await loadUserConfig(input.configPath, source);
+    const userConfig = await loadUserConfig(canonicalPath, source);
+    const projectChangesOpenRouterRoute = projectConfigChangesOpenRouterRoute(userConfig, input.baseConfig);
+    await assertProjectOpenRouterAuthorization({
+      projectConfig: userConfig,
+      projectPath: requestedPath,
+      projectDirectory: canonicalDirectory,
+      layer: "project_ts",
+      baseConfig: input.baseConfig,
+      globalConfigPath: input.globalConfigPath
+    });
     if (trustDecision.shouldPersist) {
-      await trustConfig(trustStorePath, input.configPath, configHash);
+      await trustConfig(trustStorePath, canonicalPath, configHash);
+    }
+    const projectMergedConfig = deepMerge2(input.baseConfig, userConfig);
+    if (projectChangesOpenRouterRoute) {
+      warnings.push(openRouterProjectConfigWarning(requestedPath));
     }
     return {
-      mergedConfig: deepMerge2(input.baseConfig, userConfig),
-      configPath: input.configPath,
+      mergedConfig: applyProjectCodexProviderReset(input.baseConfig, userConfig, projectMergedConfig),
+      configPath: requestedPath,
       configHash,
       configTrustStatus: trustDecision.status,
-      source: { path: input.configPath, layer: "project_ts" },
+      source: { path: requestedPath, layer: "project_ts" },
       warnings
     };
   }
-  warnings.push(`untrusted config was not executed: ${input.configPath}; run \`kyoso doctor --trust-config\` or pass \`--trust-config\` once to trust it`);
+  warnings.push(`untrusted config was not executed: ${requestedPath}; run \`kyoso doctor --trust-config\` or pass \`--trust-config\` once to trust it`);
   return {
     mergedConfig: input.baseConfig,
-    configPath: input.configPath,
+    configPath: requestedPath,
     configHash,
     configTrustStatus: trustDecision.status,
-    source: { path: input.configPath, layer: "project_ts" },
+    source: { path: requestedPath, layer: "project_ts" },
     warnings
   };
 }
+function isTrustedProjectConfigExecution(status) {
+  return status === "trusted" || status === "trusted_by_flag" || status === "trusted_interactively";
+}
 async function loadUserConfig(configPath, source) {
   try {
     const loaded = await loadConfigModule(configPath, source);
@@ -185575,6 +185759,8 @@ function applyConfigOverrides(config2, assignments) {
   for (const override of overrides) {
     writePath2(overridden, override.path, parseConfigOverrideValue(override.value, readPath2(baseConfig, override.path)));
   }
+  clearInheritedOpenRouterModelForProviderReset(baseConfig, overridden, overrides);
+  assertOpenRouterProviderOverrideIncludesModel(baseConfig, overridden, overrides);
   const parsed = kyosoConfigSchema.safeParse(overridden);
   if (parsed.success)
     return parsed.data;
@@ -185583,6 +185769,29 @@ function applyConfigOverrides(config2, assignments) {
   const assignment = findAssignmentForPath(overrides, issuePath) ?? assignments.at(-1) ?? "";
   throw new Error(`Invalid --set value ${JSON.stringify(assignment)}: ${issuePath}: ${issue2?.message ?? "config validation failed"}.`);
 }
+function assertOpenRouterProviderOverrideIncludesModel(baseConfig, overridden, overrides) {
+  const providerPath = ["agents", "codex", "provider"];
+  const modelPath = ["agents", "codex", "model"];
+  const selectsOpenRouter = readPath2(overridden, providerPath) === CODEX_OPENROUTER_PROVIDER;
+  const alreadySelected = readPath2(baseConfig, providerPath) === CODEX_OPENROUTER_PROVIDER;
+  const suppliesModel = overrides.some((override) => override.path.join(".") === modelPath.join("."));
+  if (!selectsOpenRouter || alreadySelected || suppliesModel)
+    return;
+  const assignment = findAssignmentForPath(overrides, providerPath.join(".")) ?? "agents.codex.provider=openrouter";
+  throw new Error(`Invalid --set value ${JSON.stringify(assignment)}: selecting agents.codex.provider=openrouter requires agents.codex.model in the same --set invocation.`);
+}
+function clearInheritedOpenRouterModelForProviderReset(baseConfig, overridden, overrides) {
+  const providerPath = ["agents", "codex", "provider"];
+  const modelPath = ["agents", "codex", "model"];
+  const selectsDefaultProvider = overrides.some((override) => override.path.join(".") === providerPath.join(".") && override.value === CODEX_DEFAULT_PROVIDER);
+  const suppliesModel = overrides.some((override) => override.path.join(".") === modelPath.join("."));
+  if (!selectsDefaultProvider || suppliesModel || readPath2(baseConfig, providerPath) !== CODEX_OPENROUTER_PROVIDER || readPath2(overridden, providerPath) !== CODEX_DEFAULT_PROVIDER) {
+    return;
+  }
+  const codex = readPath2(overridden, ["agents", "codex"]);
+  if (isRecord4(codex))
+    delete codex.model;
+}
 function findAssignmentForPath(overrides, path) {
   for (let index = overrides.length - 1;index >= 0; index -= 1) {
     const override = overrides[index];
@@ -185650,8 +185859,8 @@ function isRecord4(value) {
 
 // src/acp/AcpAgentProcess.ts
 import { spawn } from "node:child_process";
-import { readFile as readFile4, realpath } from "node:fs/promises";
-import { isAbsolute, relative, resolve as resolve3 } from "node:path";
+import { readFile as readFile4, realpath as realpath2 } from "node:fs/promises";
+import { isAbsolute as isAbsolute3, relative, resolve as resolve3 } from "node:path";
 import { Readable, Writable } from "node:stream";
 
 // node_modules/@agentclientprotocol/sdk/dist/schema/index.js
@@ -189583,6 +189792,7 @@ var legacyClientNotificationMethods = new Set([
 ]);
 
 // src/utils/env.ts
+import { stderr as stderr2 } from "node:process";
 var MINIMAL_ENV_KEYS = [
   "PATH",
   "HOME",
@@ -189596,29 +189806,110 @@ var MINIMAL_ENV_KEYS = [
   "USERNAME",
   "SystemRoot"
 ];
+var CREDENTIAL_ENV_KEYS = new Set([
+  "ANTHROPIC_API_KEY",
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "CODEX_ACCESS_TOKEN",
+  "CODEX_API_KEY",
+  "OPENAI_API_KEY",
+  "OPENROUTER_API_KEY"
+]);
+var CREDENTIAL_LIKE_ENV_KEY_PATTERN = /(?:^|_)(?:KEY|TOKEN|SECRET|PASSWORD)$/i;
+var UNEXPANDED_ENV_PLACEHOLDER_PATTERN = /^\s*(?:\$\{[A-Za-z_][A-Za-z0-9_]*\}|\$[A-Za-z_][A-Za-z0-9_]*|%[A-Za-z_][A-Za-z0-9_]*%)\s*$/;
+var OPENROUTER_EXCLUDED_CREDENTIAL_ENV_KEYS = [
+  "OPENAI_API_KEY",
+  "CODEX_API_KEY",
+  "CODEX_ACCESS_TOKEN"
+];
+var OPENROUTER_API_KEY_ENV = "OPENROUTER_API_KEY";
+var KYOSO_OPENROUTER_PROVIDER_ID = "kyoso-openrouter";
+var OPENROUTER_BASE_URL = "https://openrouter.ai/api/v1";
+var OPENROUTER_PROVIDER_PRESET = {
+  name: "OpenRouter",
+  base_url: OPENROUTER_BASE_URL,
+  env_key: OPENROUTER_API_KEY_ENV,
+  wire_api: "responses",
+  requires_openai_auth: false
+};
+
+class ChildEnvPreflightError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.code = code;
+    this.name = "ChildEnvPreflightError";
+  }
+}
 function buildChildEnv(parentEnv, whitelist, explicit, options = {}) {
   if (!parentEnv.PATH) {
     throw new Error("PATH is required to launch ACP child agents.");
   }
   const env = {};
+  const warnedCredentialPlaceholderKeys = new Set;
+  const onCredentialPlaceholderDiscarded = (key) => {
+    if (warnedCredentialPlaceholderKeys.has(key))
+      return;
+    warnedCredentialPlaceholderKeys.add(key);
+    (options.onCredentialPlaceholderDiscarded ?? warnCredentialPlaceholderDiscarded)(key);
+  };
+  const openRouterSelected = options.agent === "codex" && options.provider === CODEX_OPENROUTER_PROVIDER;
   for (const key of MINIMAL_ENV_KEYS) {
     if (parentEnv[key])
       env[key] = parentEnv[key];
   }
   for (const key of whitelist) {
-    if (parentEnv[key])
+    if (key === OPENROUTER_API_KEY_ENV && !openRouterSelected)
+      continue;
+    if (parentEnv[key] && canCopyEnvValue(key, parentEnv[key], onCredentialPlaceholderDiscarded)) {
       env[key] = parentEnv[key];
+    }
   }
   for (const [key, value] of Object.entries(explicit)) {
-    env[key] = value;
+    if (key === OPENROUTER_API_KEY_ENV && !openRouterSelected) {
+      if (value.trim().length > 0) {
+        (options.onOpenRouterCredentialWithheld ?? warnOpenRouterCredentialWithheld)(key);
+      }
+      continue;
+    }
+    if (canCopyEnvValue(key, value, onCredentialPlaceholderDiscarded)) {
+      env[key] = value;
+    }
+  }
+  if (openRouterSelected) {
+    discardOpenRouterExcludedCredentials(env);
+    applyOpenRouterConfig(env, parentEnv, options.model, onCredentialPlaceholderDiscarded, options.onOpenRouterProvidersDiscarded ?? warnOpenRouterProvidersDiscarded);
+  } else {
+    applyModelConfig(env, options.agent, options.model);
   }
-  applyModelConfig(env, options.agent, options.model);
   env.KYOSO_CHILD_AGENT = "1";
   if (options.agent === "claude") {
     applyClaudeAuthPreference(env, options.preferApiKey === true);
   }
   return env;
 }
+function canCopyEnvValue(key, value, onCredentialPlaceholderDiscarded) {
+  if (!isUnexpandedCredentialEnvValue(key, value))
+    return true;
+  (onCredentialPlaceholderDiscarded ?? warnCredentialPlaceholderDiscarded)(key);
+  return false;
+}
+function warnCredentialPlaceholderDiscarded(key) {
+  stderr2.write(`kyoso: ignored an unexpanded credential placeholder for ${key}; ensure the client expands it before starting Kyoso.
+`);
+}
+function warnOpenRouterCredentialWithheld(key) {
+  stderr2.write(`kyoso: ignored explicit ${key} because the OpenRouter provider is not selected for this child.
+`);
+}
+function warnOpenRouterProvidersDiscarded(count) {
+  stderr2.write(`kyoso: discarded foreign CODEX_CONFIG.model_providers entries: ${count}; provider IDs and configuration values were not displayed.
+`);
+}
+function discardOpenRouterExcludedCredentials(env) {
+  for (const key of OPENROUTER_EXCLUDED_CREDENTIAL_ENV_KEYS) {
+    delete env[key];
+  }
+}
 function applyModelConfig(env, agent, model) {
   if (!model)
     return;
@@ -189630,7 +189921,67 @@ function applyModelConfig(env, agent, model) {
     env.CODEX_CONFIG = JSON.stringify({ model });
   }
 }
+function applyOpenRouterConfig(env, parentEnv, model, onCredentialPlaceholderDiscarded, onOpenRouterProvidersDiscarded) {
+  const configuredModel = model?.trim();
+  if (!configuredModel) {
+    throw new ChildEnvPreflightError("AGENT_CONFIG_INVALID", 'agents.codex.provider="openrouter" requires a non-empty agents.codex.model.');
+  }
+  if (!hasEnv(env, OPENROUTER_API_KEY_ENV)) {
+    const parentKey = nonEmptyEnv(parentEnv, OPENROUTER_API_KEY_ENV);
+    if (parentKey)
+      env[OPENROUTER_API_KEY_ENV] = parentKey;
+    else if (isUnexpandedCredentialEnvValue(OPENROUTER_API_KEY_ENV, parentEnv[OPENROUTER_API_KEY_ENV] ?? "")) {
+      onCredentialPlaceholderDiscarded(OPENROUTER_API_KEY_ENV);
+    }
+  }
+  if (!hasEnv(env, OPENROUTER_API_KEY_ENV)) {
+    throw new ChildEnvPreflightError("OPENROUTER_KEY_MISSING", 'agents.codex.provider="openrouter" requires OPENROUTER_API_KEY, but it is not visible to the Kyoso process. Add OPENROUTER_API_KEY to the MCP registration, restart the client, then run `kyoso doctor`.');
+  }
+  const config2 = parseCodexConfig(env.CODEX_CONFIG);
+  assertOpenRouterConfigDoesNotSelectProfile(config2);
+  if (config2.model_providers !== undefined && !isPlainObject2(config2.model_providers)) {
+    throw new ChildEnvPreflightError("AGENT_CONFIG_INVALID", "CODEX_CONFIG.model_providers must be a JSON object for the OpenRouter provider.");
+  }
+  reportDiscardedOpenRouterProviders(config2.model_providers, onOpenRouterProvidersDiscarded);
+  env.MODEL_PROVIDER = KYOSO_OPENROUTER_PROVIDER_ID;
+  env.CODEX_CONFIG = JSON.stringify({
+    ...config2,
+    model: configuredModel,
+    model_provider: KYOSO_OPENROUTER_PROVIDER_ID,
+    model_providers: {
+      [KYOSO_OPENROUTER_PROVIDER_ID]: OPENROUTER_PROVIDER_PRESET
+    }
+  });
+}
+function reportDiscardedOpenRouterProviders(modelProviders, onDiscarded) {
+  if (!isPlainObject2(modelProviders))
+    return;
+  const foreignProviderCount = Object.keys(modelProviders).filter((providerId) => providerId !== KYOSO_OPENROUTER_PROVIDER_ID).length;
+  if (foreignProviderCount > 0)
+    onDiscarded(foreignProviderCount);
+}
+function parseCodexConfig(value) {
+  if (!value)
+    return {};
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    throw new ChildEnvPreflightError("AGENT_CONFIG_INVALID", "CODEX_CONFIG must contain a JSON object for the OpenRouter provider.");
+  }
+  if (!isPlainObject2(parsed)) {
+    throw new ChildEnvPreflightError("AGENT_CONFIG_INVALID", "CODEX_CONFIG must contain a JSON object for the OpenRouter provider.");
+  }
+  return parsed;
+}
+function assertOpenRouterConfigDoesNotSelectProfile(config2) {
+  if (Object.hasOwn(config2, "profile") || Object.hasOwn(config2, "profiles")) {
+    throw new ChildEnvPreflightError("AGENT_CONFIG_INVALID", "CODEX_CONFIG.profile and CODEX_CONFIG.profiles are not supported for the OpenRouter provider.");
+  }
+}
 function applyClaudeAuthPreference(env, preferApiKey) {
+  discardUnusableEnvValue(env, "ANTHROPIC_API_KEY");
+  discardUnusableEnvValue(env, "CLAUDE_CODE_OAUTH_TOKEN");
   const hasApiKey = hasEnv(env, "ANTHROPIC_API_KEY");
   const hasOAuthToken = hasEnv(env, "CLAUDE_CODE_OAUTH_TOKEN");
   if (!hasApiKey || !hasOAuthToken)
@@ -189641,8 +189992,32 @@ function applyClaudeAuthPreference(env, preferApiKey) {
     delete env.ANTHROPIC_API_KEY;
   }
 }
+function discardUnusableEnvValue(env, key) {
+  if (env[key] !== undefined && !hasEnv(env, key)) {
+    delete env[key];
+  }
+}
+function hasUsableEnvValue(env, key) {
+  return nonEmptyEnv(env, key) !== undefined;
+}
+function isUnexpandedEnvPlaceholder(value) {
+  return typeof value === "string" && UNEXPANDED_ENV_PLACEHOLDER_PATTERN.test(value);
+}
 function hasEnv(env, key) {
-  return typeof env[key] === "string" && env[key].trim().length > 0;
+  return hasUsableEnvValue(env, key);
+}
+function nonEmptyEnv(env, key) {
+  const value = env[key];
+  return typeof value === "string" && value.trim().length > 0 && !isUnexpandedCredentialEnvValue(key, value) ? value : undefined;
+}
+function isUnexpandedCredentialEnvValue(key, value) {
+  return (CREDENTIAL_ENV_KEYS.has(key) || CREDENTIAL_LIKE_ENV_KEY_PATTERN.test(key)) && isUnexpandedEnvPlaceholder(value);
+}
+function isPlainObject2(value) {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return Object.getPrototypeOf(value) === Object.prototype;
 }
 
 // src/acp/AcpAgentManager.ts
@@ -189828,31 +190203,59 @@ function isRecord6(value) {
 // src/acp/AcpAgentProcess.ts
 class SubprocessAcpAgentManager extends BaseAcpAgentManager {
   config;
-  constructor(config2) {
+  parentEnv;
+  constructor(config2, parentEnv = process.env) {
     super();
     this.config = config2;
+    this.parentEnv = parentEnv;
   }
   async runAgent(input) {
     const agentConfig = this.config.agents[input.agent];
+    const startedAt = new Date().toISOString();
     if (!agentConfig.enabled) {
       return {
         agent: input.agent,
         role: input.role,
         status: "skipped",
-        startedAt: new Date().toISOString(),
-        completedAt: new Date().toISOString()
+        startedAt,
+        completedAt: startedAt
+      };
+    }
+    const provider = input.agent === "codex" ? this.config.agents.codex.provider : undefined;
+    let env;
+    try {
+      env = buildChildEnv(this.parentEnv, agentConfig.auth.envWhitelist, agentConfig.env, {
+        agent: input.agent,
+        model: agentConfig.model,
+        provider,
+        preferApiKey: agentConfig.auth.preferApiKey
+      });
+    } catch (error51) {
+      return {
+        agent: input.agent,
+        role: input.role,
+        status: "failed",
+        startedAt,
+        completedAt: new Date().toISOString(),
+        error: buildPreflightFailure(error51)
+      };
+    }
+    try {
+      return await runSubprocessAgent(input.agent, agentConfig, input, env);
+    } catch (error51) {
+      return {
+        agent: input.agent,
+        role: input.role,
+        status: "failed",
+        startedAt,
+        completedAt: new Date().toISOString(),
+        error: buildAgentFailure(formatAgentErrorDetail(error51), "Agent process failed.")
       };
     }
-    return runSubprocessAgent(input.agent, agentConfig, input);
   }
 }
-async function runSubprocessAgent(agent, agentConfig, input) {
+async function runSubprocessAgent(agent, agentConfig, input, env) {
   const startedAt = new Date().toISOString();
-  const env = buildChildEnv(process.env, agentConfig.auth.envWhitelist, agentConfig.env, {
-    agent,
-    model: agentConfig.model,
-    preferApiKey: agentConfig.auth.preferApiKey
-  });
   return new Promise((resolveResult) => {
     const child = spawn(agentConfig.command, agentConfig.args, {
       cwd: input.workspaceDir,
@@ -189860,15 +190263,23 @@ async function runSubprocessAgent(agent, agentConfig, input) {
       stdio: ["pipe", "pipe", "pipe"]
     });
     let stdout = "";
-    let stderr2 = "";
+    let stderr3 = "";
     let settled = false;
+    let startedWrite;
+    child.once("spawn", () => {
+      if (settled)
+        return;
+      startedWrite = Promise.resolve().then(() => input.onStarted?.()).catch(() => {
+        return;
+      });
+    });
     const abortController = new AbortController;
     const resolveOnce = (result) => {
       if (settled)
         return;
       settled = true;
       clearTimeout(timeout);
-      resolveResult(result);
+      (startedWrite ?? Promise.resolve()).then(() => resolveResult(result));
     };
     const timeout = setTimeout(() => {
       abortController.abort(new Error("Kyoso agent timeout"));
@@ -189886,7 +190297,7 @@ async function runSubprocessAgent(agent, agentConfig, input) {
       });
     }, input.timeoutMs);
     child.stderr.on("data", (chunk) => {
-      stderr2 += chunk.toString("utf8");
+      stderr3 += chunk.toString("utf8");
     });
     child.on("error", (error51) => {
       const failure = buildAgentFailure(error51.message, "Agent process could not be started.");
@@ -189915,7 +190326,7 @@ async function runSubprocessAgent(agent, agentConfig, input) {
     }).catch((error51) => {
       if (abortController.signal.aborted)
         return;
-      const failureText = [stderr2, formatAgentErrorDetail(error51)].filter((part) => part.trim().length > 0).join(`
+      const failureText = [stderr3, formatAgentErrorDetail(error51)].filter((part) => part.trim().length > 0).join(`
 `);
       resolveOnce({
         agent,
@@ -189940,7 +190351,7 @@ async function runSubprocessAgent(agent, agentConfig, input) {
         rawText: stdout,
         startedAt,
         completedAt: new Date().toISOString(),
-        error: buildAgentFailure(stderr2, fallback)
+        error: buildAgentFailure(stderr3, fallback)
       });
     });
   });
@@ -190024,7 +190435,7 @@ function resolveEffortConfigOption(agent, effort) {
   return;
 }
 async function readWorkspaceFile(workspaceDir, requestedPath, line, limit) {
-  const workspaceRoot = await realpath(workspaceDir);
+  const workspaceRoot = await realpath2(workspaceDir);
   const candidates = resolveReadablePaths(workspaceRoot, requestedPath);
   let content;
   for (const absolute of candidates) {
@@ -190047,7 +190458,7 @@ async function readWorkspaceFile(workspaceDir, requestedPath, line, limit) {
 `);
 }
 async function resolveReadableFile(workspaceRoot, absolute) {
-  const realPath = await realpath(absolute).catch((error51) => {
+  const realPath = await realpath2(absolute).catch((error51) => {
     if (isMissingPathError2(error51))
       return;
     throw error51;
@@ -190066,7 +190477,7 @@ function resolveReadablePaths(workspaceRoot, requestedPath) {
   }
   const repoPath = resolve3(workspaceRoot, "repo", relativePath);
   assertWithinWorkspace(workspaceRoot, repoPath);
-  return isAbsolute(requestedPath) ? [primary, repoPath] : [repoPath, primary];
+  return isAbsolute3(requestedPath) ? [primary, repoPath] : [repoPath, primary];
 }
 function assertWithinWorkspace(workspaceRoot, absolute) {
   const relativePath = relative(workspaceRoot, absolute);
@@ -190098,6 +190509,20 @@ function buildAgentFailure(rawDetail, fallbackMessage) {
     ...detail ? { detail } : {}
   };
 }
+function buildPreflightFailure(error51) {
+  if (error51 instanceof ChildEnvPreflightError) {
+    return {
+      code: error51.code,
+      message: error51.message
+    };
+  }
+  const detail = sanitizeTextForDisplay(formatAgentErrorDetail(error51));
+  return {
+    code: "AGENT_CONFIG_INVALID",
+    message: "Agent configuration is invalid. Run kyoso doctor and check agent configuration.",
+    ...detail ? { detail } : {}
+  };
+}
 function safeAgentFailureMessage(code, fallbackMessage) {
   if (code === "AUTH_FAILED") {
     return "Agent authentication failed. Run kyoso doctor and check configured credentials.";
@@ -190113,15 +190538,15 @@ function safeAgentFailureMessage(code, fallbackMessage) {
   }
   return sanitizeTextForDisplay(fallbackMessage);
 }
-function classifyAgentFailure(stderr2) {
-  if (/spawn/i.test(stderr2))
+function classifyAgentFailure(stderr3) {
+  if (/spawn/i.test(stderr3))
     return "AGENT_SPAWN_FAILED";
-  if (/ENOTFOUND|ENOTCACHED|ECONNREFUSED|ETIMEDOUT|registry\.npmjs\.org|network request|cache mode/i.test(stderr2)) {
+  if (/ENOTFOUND|ENOTCACHED|ECONNREFUSED|ETIMEDOUT|registry\.npmjs\.org|network request|cache mode/i.test(stderr3)) {
     return "AGENT_NETWORK_FAILED";
   }
-  if (/auth|api key|login|credential/i.test(stderr2))
+  if (/auth|api key|login|credential/i.test(stderr3))
     return "AUTH_FAILED";
-  if (/permission|policy|write|terminal/i.test(stderr2))
+  if (/permission|policy|write|terminal/i.test(stderr3))
     return "PERMISSION_DENIED";
   return "AGENT_FAILED";
 }
@@ -190158,9 +190583,24 @@ class FakeAgentManager extends BaseAcpAgentManager {
     this.calls.push(input);
     const startedAt = new Date().toISOString();
     if (input.role === "finding_verifier") {
+      await input.onStarted?.();
       return verifierResult(input, startedAt, this.verifierScenarios[input.agent] ?? "confirmed");
     }
     const scenario = this.scenarios[input.agent] ?? "success";
+    if (scenario === "preflight_failure" || scenario === "openrouter_key_missing") {
+      return {
+        agent: input.agent,
+        role: input.role,
+        status: "failed",
+        startedAt,
+        completedAt: new Date().toISOString(),
+        error: {
+          code: scenario === "openrouter_key_missing" ? "OPENROUTER_KEY_MISSING" : "AGENT_CONFIG_INVALID",
+          message: scenario === "openrouter_key_missing" ? "Fake OpenRouter key is missing." : "Fake agent configuration is invalid."
+        }
+      };
+    }
+    await input.onStarted?.();
     if (scenario === "timeout") {
       return {
         agent: input.agent,
@@ -190784,8 +191224,8 @@ function normalizeTitle(value) {
 
 // src/audit/stateRoot.ts
 import { createHash as createHash2 } from "node:crypto";
-import { lstat, mkdir as mkdir2, realpath as realpath2 } from "node:fs/promises";
-import { basename, dirname as dirname3, isAbsolute as isAbsolute2, join as join3, resolve as resolve5 } from "node:path";
+import { lstat, mkdir as mkdir2, realpath as realpath3 } from "node:fs/promises";
+import { basename, dirname as dirname4, isAbsolute as isAbsolute4, join as join3, resolve as resolve5 } from "node:path";
 
 // src/context/pathPolicy.ts
 import { normalize, sep } from "node:path";
@@ -190876,7 +191316,7 @@ async function resolveAuditStateRoot(options) {
     return { warnings: [...warnings, AUDIT_WARNING_UNSUPPORTED_CAPABILITY] };
   }
   try {
-    const workspaceRoot = await realpath2(resolve5(options.cwd));
+    const workspaceRoot = await realpath3(resolve5(options.cwd));
     const candidate = resolveStateBaseCandidate(options.env ?? process.env);
     if (!candidate)
       throw new Error("missing trusted state base");
@@ -190905,7 +191345,7 @@ async function resolveAuditStateRoot(options) {
   }
 }
 async function ensureTrustedDirectory(options) {
-  const realRoot = await realpath2(options.root);
+  const realRoot = await realpath3(options.root);
   assertSafeDirectory(realRoot, options.uid, await lstat(realRoot));
   if (options.workspaceRoot && isPathWithin(realRoot, options.workspaceRoot)) {
     throw new Error("trusted directory resolves inside workspace");
@@ -190922,7 +191362,7 @@ async function ensureTrustedDirectory(options) {
       entry = await lstat(next);
     }
     assertSafeDirectory(next, options.uid, entry);
-    const realNext = await realpath2(next);
+    const realNext = await realpath3(next);
     if (!isPathWithin(realNext, realRoot)) {
       throw new Error("managed directory escaped trusted root");
     }
@@ -190938,7 +191378,7 @@ function isResolvedAuditStateRoot(resolution) {
 }
 function validateAuditDirectory(directory, warnings) {
   try {
-    if (directory.trim().length === 0 || isAbsolute2(directory) || directory.split(/[\\/]+/).includes("..")) {
+    if (directory.trim().length === 0 || isAbsolute4(directory) || directory.split(/[\\/]+/).includes("..")) {
       throw new Error("unsafe logical directory");
     }
     const normalized = normalizeRelativePath(directory);
@@ -190953,11 +191393,11 @@ function validateAuditDirectory(directory, warnings) {
 }
 function resolveStateBaseCandidate(env) {
   const xdgStateHome = env.XDG_STATE_HOME?.trim();
-  if (xdgStateHome && isAbsolute2(xdgStateHome)) {
+  if (xdgStateHome && isAbsolute4(xdgStateHome)) {
     return resolve5(xdgStateHome);
   }
   const home = env.HOME?.trim();
-  if (!home || !isAbsolute2(home))
+  if (!home || !isAbsolute4(home))
     return;
   return join3(resolve5(home), ".local", "state");
 }
@@ -190969,7 +191409,7 @@ async function ensureTrustedStateBase(options) {
   assertSafeDirectory(existing.path, options.uid, await lstat(existing.path), {
     allowFilesystemRoot: true
   });
-  const realExisting = await realpath2(existing.path);
+  const realExisting = await realpath3(existing.path);
   if (isPathWithin(realExisting, options.workspaceRoot)) {
     throw new Error("state base resolves inside workspace");
   }
@@ -190980,7 +191420,7 @@ async function ensureTrustedStateBase(options) {
     await createDirectory(current);
     const entry = await lstat(current);
     assertSafeDirectory(current, options.uid, entry);
-    const realCurrent = await realpath2(current);
+    const realCurrent = await realpath3(current);
     if (!isPathWithin(realCurrent, realExisting)) {
       throw new Error("state base changed while being created");
     }
@@ -190989,7 +191429,7 @@ async function ensureTrustedStateBase(options) {
     }
     current = realCurrent;
   }
-  const stateBase = await realpath2(current);
+  const stateBase = await realpath3(current);
   assertSafeDirectory(stateBase, options.uid, await lstat(stateBase));
   if (isPathWithin(stateBase, options.workspaceRoot)) {
     throw new Error("state base resolves inside workspace");
@@ -191008,7 +191448,7 @@ async function findExistingAncestor(candidate) {
       }
       return { path: current, missingSegments };
     }
-    const parent = dirname3(current);
+    const parent = dirname4(current);
     if (parent === current)
       throw new Error("state base has no existing ancestor");
     missingSegments.unshift(basename(current));
@@ -191041,12 +191481,12 @@ function getCurrentUid(getuid) {
   }
 }
 function isFilesystemRoot(path) {
-  return dirname3(path) === path;
+  return dirname4(path) === path;
 }
 async function assertTrustedAncestorChain(path, uid) {
   let child = path;
   while (!isFilesystemRoot(child)) {
-    const parent = dirname3(child);
+    const parent = dirname4(child);
     const [parentStat, childStat] = await Promise.all([
       lstat(parent),
       lstat(child)
@@ -191094,7 +191534,7 @@ function isAlreadyExistsError(error51) {
 
 // src/audit/safeTraceFile.ts
 import { constants } from "node:fs";
-import { lstat as lstat2, open, realpath as realpath3, stat } from "node:fs/promises";
+import { lstat as lstat2, open, realpath as realpath4, stat } from "node:fs/promises";
 import { join as join4 } from "node:path";
 var AUDIT_WARNING_UNSUPPORTED_OPEN_CAPABILITY = "AUDIT_DISABLED_UNSUPPORTED_CAPABILITY: Audit trace writing requires unavailable filesystem capabilities.";
 async function openVerifiedTraceFile(options) {
@@ -191124,7 +191564,7 @@ async function openVerifiedTraceFile(options) {
     const [handleStat, pathStat, realTracePath] = await Promise.all([
       handle.stat({ bigint: true }),
       stat(tracePath, { bigint: true }),
-      realpath3(tracePath)
+      realpath4(tracePath)
     ]);
     if (!handleStat.isFile() || !pathStat.isFile() || handleStat.dev !== pathStat.dev || handleStat.ino !== pathStat.ino || !isPathWithin(realTracePath, options.kyosoRoot)) {
       throw new Error("trace file identity could not be verified");
@@ -192020,7 +192460,7 @@ function decide(input) {
 
 // src/workspace/createSnapshot.ts
 import { chmod, mkdir as mkdir3, mkdtemp, writeFile as writeFile2 } from "node:fs/promises";
-import { dirname as dirname4, join as join5 } from "node:path";
+import { dirname as dirname5, join as join5 } from "node:path";
 import { tmpdir } from "node:os";
 async function createSnapshot(traceId, tool, request, options = {}) {
   const root = await mkdtemp(join5(tmpdir(), `kyoso-${traceId}-`));
@@ -192036,7 +192476,7 @@ async function createSnapshot(traceId, tool, request, options = {}) {
     if (!isAllowedPath(relative2, options.allowPatterns ?? []))
       continue;
     const dest = join5(repoDir, relative2);
-    await mkdir3(dirname4(dest), { recursive: true });
+    await mkdir3(dirname5(dest), { recursive: true });
     await writeFile2(dest, file2.content, "utf8");
     await chmod(dest, 292).catch(() => {
       return;
@@ -192374,7 +192814,7 @@ async function runReview(tool, request, options = {}) {
       fileCount: snapshot.fileCount,
       timestamp: new Date().toISOString()
     });
-    const manager = options.agentManager ?? defaultAgentManager(loaded.config);
+    const manager = options.agentManager ?? defaultAgentManager(loaded.config, options.env ?? process.env);
     const agentResults = await runAgents({
       tool,
       request: built.request,
@@ -192383,7 +192823,8 @@ async function runReview(tool, request, options = {}) {
       workspaceDir: snapshot.root,
       networkMode,
       manager,
-      trace
+      trace,
+      warnings
     });
     warnings.push(...agentResults.flatMap((result) => (result.warnings ?? []).map((warning) => `Agent ${result.agent} ${warning}`)));
     const normalizedAgentResults = agentResults.map(normalizeAgentRunResult);
@@ -192658,24 +193099,51 @@ function buildCrossModelAnalysis(judge, reviewMode) {
 }
 async function runAgents(input) {
   const agentRoles = resolveAgentRoles(input.config);
-  const agentInputs = ["codex", "claude"].filter((agent) => input.config.agents[agent].enabled).map((agent) => ({
-    traceId: input.traceId,
-    agent,
-    role: agentRoles[agent] ?? input.config.agents[agent].role,
-    tool: input.tool,
-    prompt: buildAgentPrompt(input.tool, input.request, agent, agentRoles[agent] ?? input.config.agents[agent].role),
-    workspaceDir: input.workspaceDir,
-    timeoutMs: input.request.options?.maxAgentTimeoutMs ?? input.config.agents[agent].timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS,
-    networkMode: input.networkMode
-  }));
-  await Promise.all(agentInputs.map((agentInput) => input.trace.write({
-    type: "agent_started",
-    traceId: input.traceId,
-    agent: agentInput.agent,
-    role: agentInput.role,
-    timestamp: new Date().toISOString()
-  })));
+  const startedWrites = [];
+  let acceptingStartedEvents = true;
+  const agentInputs = ["codex", "claude"].filter((agent) => input.config.agents[agent].enabled).map((agent) => {
+    const agentConfig = input.config.agents[agent];
+    const role = agentRoles[agent] ?? agentConfig.role;
+    return {
+      traceId: input.traceId,
+      agent,
+      role,
+      tool: input.tool,
+      prompt: buildAgentPrompt(input.tool, input.request, agent, role),
+      workspaceDir: input.workspaceDir,
+      timeoutMs: input.request.options?.maxAgentTimeoutMs ?? agentConfig.timeoutMs ?? DEFAULT_AGENT_TIMEOUT_MS,
+      networkMode: input.networkMode,
+      onStarted: () => {
+        if (!acceptingStartedEvents)
+          return Promise.resolve();
+        const event = {
+          type: "agent_started",
+          traceId: input.traceId,
+          agent,
+          role,
+          timestamp: new Date().toISOString()
+        };
+        if (agentConfig.model) {
+          event.model = sanitizeTextForDisplay(agentConfig.model);
+        }
+        if (agent === "codex" && input.config.agents.codex.provider === CODEX_OPENROUTER_PROVIDER) {
+          event.provider = CODEX_OPENROUTER_PROVIDER;
+        }
+        const write = (async () => {
+          try {
+            await input.trace.write(event);
+          } catch {
+            input.warnings.push("AUDIT_WRITE_FAILED: agent_started event could not be recorded.");
+          }
+        })();
+        startedWrites.push(write);
+        return write;
+      }
+    };
+  });
   const results = await input.manager.runAll(agentInputs);
+  acceptingStartedEvents = false;
+  await Promise.all(startedWrites);
   await Promise.all(results.map((result) => {
     const event = {
       type: "agent_completed",
@@ -192707,10 +193175,11 @@ function resolveAgentRoles(config2) {
   }
   return roles;
 }
-function defaultAgentManager(config2) {
-  if (process.env.KYOSO_TEST_FAKE_AGENTS === "1")
+function defaultAgentManager(config2, parentEnv) {
+  if (parentEnv.KYOSO_TEST_FAKE_AGENTS === "1") {
     return new FakeAgentManager;
-  return new SubprocessAcpAgentManager(config2);
+  }
+  return new SubprocessAcpAgentManager(config2, parentEnv);
 }
 function normalizeAgentRunResult(result) {
   if (result.status === "completed" && result.rawText && !result.normalized) {