ai-maestro 1.0.0

package/src/commands.mjs

@@ -0,0 +1,809 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { execCmdFile, execFileRaw } from './shell.mjs';
+import { getCodexEnv } from './codex-home.mjs';
+import { stampSchemaVersion } from './schema.mjs';
+
+function isWindows() {
+  return process.platform === 'win32';
+}
+
+function isWindowsPlatform(platform = process.platform) {
+  return platform === 'win32';
+}
+
+function pathApiForPlatform(platform = process.platform) {
+  return isWindowsPlatform(platform) ? path.win32 : path.posix;
+}
+
+function commandKind(commandPath) {
+  const ext = path.extname(commandPath).toLowerCase();
+  if (ext === '.cmd' || ext === '.bat') {
+    return 'cmd';
+  }
+  return 'direct';
+}
+
+function isJsPath(filePath) {
+  return path.extname(filePath).toLowerCase() === '.js';
+}
+
+async function pathExists(filePath) {
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+async function pathExistsWith(filePath, existsSync = null) {
+  if (existsSync) {
+    return existsSync(filePath);
+  }
+  return pathExists(filePath);
+}
+
+export function absoluteWhereExe() {
+  return 'C:\\Windows\\System32\\where.exe';
+}
+
+function normalizeDirForCompare(dir, platform, cwd) {
+  const pathApi = pathApiForPlatform(platform);
+  const resolved = pathApi.resolve(cwd, dir);
+  return isWindowsPlatform(platform) ? resolved.toLowerCase() : resolved;
+}
+
+function stripTrailingPathSeparators(value, pathApi) {
+  const root = pathApi.parse(value).root;
+  let next = value;
+  while (next.length > root.length && /[\\/]/.test(next[next.length - 1])) {
+    next = next.slice(0, -1);
+  }
+  return next;
+}
+
+function normalizePathForContainment(value, platform, cwd) {
+  const pathApi = pathApiForPlatform(platform);
+  const resolved = stripTrailingPathSeparators(pathApi.normalize(pathApi.resolve(cwd, value)), pathApi);
+  return isWindowsPlatform(platform) ? resolved.toLowerCase() : resolved;
+}
+
+function isSameOrDescendantPath(candidate, boundary, platform) {
+  const pathApi = pathApiForPlatform(platform);
+  if (candidate === boundary) {
+    return true;
+  }
+  const boundaryWithSep = boundary.endsWith(pathApi.sep) ? boundary : boundary + pathApi.sep;
+  return candidate.startsWith(boundaryWithSep);
+}
+
+function isSafeWhereResult(candidate, {
+  platform = process.platform,
+  cwd = process.cwd(),
+  projectRoot = cwd
+} = {}) {
+  const pathApi = pathApiForPlatform(platform);
+  if (!pathApi.isAbsolute(candidate)) {
+    return false;
+  }
+
+  const candidateKey = normalizePathForContainment(candidate, platform, cwd);
+  const cwdKey = normalizePathForContainment(cwd, platform, cwd);
+  const projectRootKey = normalizePathForContainment(projectRoot, platform, cwd);
+  return !isSameOrDescendantPath(candidateKey, cwdKey, platform)
+    && !isSameOrDescendantPath(candidateKey, projectRootKey, platform);
+}
+
+export function resolveViaPath(command, {
+  env = process.env,
+  platform = process.platform,
+  existsSync = fsSync.existsSync,
+  cwd = process.cwd()
+} = {}) {
+  if (!command) {
+    return null;
+  }
+
+  const pathApi = pathApiForPlatform(platform);
+  if (pathApi.isAbsolute(command)) {
+    return existsSync(command) ? pathApi.resolve(command) : null;
+  }
+
+  const delimiter = isWindowsPlatform(platform) ? ';' : ':';
+  const cwdKey = normalizeDirForCompare('.', platform, cwd);
+  const entries = String(env.PATH || env.Path || '')
+    .split(delimiter)
+    .map(entry => entry.replace(/^"|"$/g, ''));
+
+  const extensions = isWindowsPlatform(platform) && !pathApi.extname(command)
+    ? String(env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean)
+    : [''];
+
+  for (const entry of entries) {
+    if (!entry || entry === '.') {
+      continue;
+    }
+    if (normalizeDirForCompare(entry, platform, cwd) === cwdKey) {
+      continue;
+    }
+
+    for (const ext of extensions) {
+      const candidate = pathApi.resolve(pathApi.join(entry, command + ext));
+      if (existsSync(candidate)) {
+        return candidate;
+      }
+    }
+  }
+
+  return null;
+}
+
+async function findWithWhere(command, {
+  env = process.env,
+  platform = process.platform,
+  execFileRawFn = execFileRaw,
+  cwd = process.cwd(),
+  projectRoot = cwd,
+  whereExe = null
+} = {}) {
+  if (!isWindowsPlatform(platform)) {
+    return null;
+  }
+
+  try {
+    const result = await execFileRawFn(whereExe || absoluteWhereExe(), [command], { quiet: true, shell: false });
+    if (result.code !== 0) {
+      return null;
+    }
+
+    const lines = result.stdout
+      .split(/\r?\n/)
+      .map(line => line.trim())
+      .filter(Boolean);
+    for (const line of lines) {
+      if (isSafeWhereResult(line, { platform, cwd, projectRoot })) {
+        return pathApiForPlatform(platform).resolve(cwd, line);
+      }
+    }
+    return null;
+  } catch (error) {
+    return null;
+  }
+}
+
+function expandCmdVariables(match, cmdPath) {
+  const cmdDir = path.dirname(cmdPath);
+  const expanded = match
+    .replace(/%~dp0%?[\\/]?/gi, cmdDir + path.sep)
+    .replace(/%dp0%?[\\/]?/gi, cmdDir + path.sep)
+    .replace(/\\/g, path.sep);
+  return path.normalize(expanded);
+}
+
+async function findCodexJsFromCmd(cmdPath, { existsSync = null } = {}) {
+  try {
+    const content = await fs.readFile(cmdPath, 'utf-8');
+    const matches = content.match(/["']?[^"'\r\n]*node_modules[^"'\r\n]*codex[^"'\r\n]*\.js["']?/gi) || [];
+    for (const rawMatch of matches) {
+      const candidate = expandCmdVariables(rawMatch.replace(/^["']|["']$/g, ''), cmdPath);
+      if (await pathExistsWith(candidate, existsSync)) {
+        return candidate;
+      }
+    }
+  } catch (error) {
+    return null;
+  }
+
+  return null;
+}
+
+async function findCodexJsCommonPath({ env = process.env, existsSync = null } = {}) {
+  if (!env.APPDATA) {
+    return null;
+  }
+
+  const npmModules = path.join(env.APPDATA, 'npm', 'node_modules');
+  const candidates = [
+    path.join(npmModules, '@openai', 'codex', 'bin', 'codex.js'),
+    path.join(npmModules, 'codex', 'bin', 'codex.js'),
+    path.join(npmModules, '@openai', 'codex', 'dist', 'cli.js'),
+    path.join(npmModules, 'codex', 'dist', 'cli.js')
+  ];
+
+  for (const candidate of candidates) {
+    if (await pathExistsWith(candidate, existsSync)) {
+      return candidate;
+    }
+  }
+
+  return null;
+}
+
+function codexNotFoundError() {
+  const error = new Error('Codex nao encontrado pelo Node. Rode `where.exe codex` e configure `setx MAESTRO_CODEX_PATH "CAMINHO_COMPLETO_DO_CODEX"`.');
+  error.code = 'ENOENT';
+  return error;
+}
+
+function npxNotFoundError() {
+  const error = new Error('npx não encontrado pelo Node. Rode `where.exe npx` e configure `setx MAESTRO_NPX_PATH "CAMINHO_COMPLETO_DO_NPX_CMD"`.');
+  error.code = 'ENOENT';
+  return error;
+}
+
+function buildResolutionFailure(error, strategy, args) {
+  return {
+    code: 127,
+    signal: null,
+    timedOut: false,
+    stdout: '',
+    stderr: error.message,
+    invocation: null,
+    resolved: null,
+    strategy,
+    invocationMode: null,
+    args,
+    infrastructureFailure: true,
+    failureCategory: 'missing_tool',
+    runtimeDecision: 'BLOCK'
+  };
+}
+
+export function buildCmdOnlyFailure(invocation, strategy, args) {
+  return {
+    code: 2,
+    signal: null,
+    timedOut: false,
+    stdout: '',
+    stderr: 'engine_resolution_cmd_only: resolved to a .cmd/.bat wrapper (' + invocation.command + ') with no real .js/binary behind it; refusing to spawn via cmd.exe.',
+    invocation,
+    resolved: invocation,
+    strategy,
+    invocationMode: invocation.mode || null,
+    args,
+    infrastructureFailure: true,
+    failureCategory: 'engine_resolution_cmd_only',
+    runtimeDecision: 'BLOCK'
+  };
+}
+
+async function resolveDiscoveredCodex(command, source, deps) {
+  if (commandKind(command) === 'cmd') {
+    const scriptPath = await findCodexJsFromCmd(command, deps);
+    if (scriptPath) {
+      return {
+        command: process.execPath,
+        argsPrefix: [scriptPath],
+        kind: 'direct',
+        source: 'codex-js from ' + source
+      };
+    }
+  }
+
+  return {
+    command,
+    argsPrefix: [],
+    kind: commandKind(command),
+    source,
+    warning: commandKind(command) === 'cmd'
+      ? 'Usando fallback codex.cmd; prompts longos podem quebrar. Configure MAESTRO_CODEX_JS.'
+      : ''
+  };
+}
+
+async function discoverCommand(command, deps) {
+  return resolveViaPath(command, deps) || await findWithWhere(command, deps);
+}
+
+export async function resolveCodexInvocation(options = {}) {
+  const env = options.env || process.env;
+  const platform = options.platform || process.platform;
+  const deps = {
+    env,
+    platform,
+    existsSync: options.existsSync || fsSync.existsSync,
+    cwd: options.cwd || process.cwd(),
+    projectRoot: options.projectRoot || options.cwd || process.cwd(),
+    whereExe: options.whereExe || null,
+    execFileRawFn: options.execFileRawFn || options.execFileRaw || execFileRaw
+  };
+
+  if (env.MAESTRO_CODEX_JS) {
+    return {
+      command: process.execPath,
+      argsPrefix: [env.MAESTRO_CODEX_JS],
+      kind: 'direct',
+      source: 'MAESTRO_CODEX_JS'
+    };
+  }
+
+  const configured = env.MAESTRO_CODEX_PATH;
+  if (configured && isJsPath(configured)) {
+    return {
+      command: process.execPath,
+      argsPrefix: [configured],
+      kind: 'direct',
+      source: 'MAESTRO_CODEX_PATH js'
+    };
+  }
+
+  if (configured && commandKind(configured) === 'cmd') {
+    const scriptPath = await findCodexJsFromCmd(configured, deps);
+    if (scriptPath) {
+      return {
+        command: process.execPath,
+        argsPrefix: [scriptPath],
+        kind: 'direct',
+        source: 'codex-js from MAESTRO_CODEX_PATH'
+      };
+    }
+  }
+
+  const commonScriptPath = await findCodexJsCommonPath(deps);
+  if (commonScriptPath) {
+    return {
+      command: process.execPath,
+      argsPrefix: [commonScriptPath],
+      kind: 'direct',
+      source: 'codex-js'
+    };
+  }
+
+  if (configured) {
+    const pathApi = pathApiForPlatform(platform);
+    if (pathApi.isAbsolute(configured)) {
+      return resolveDiscoveredCodex(configured, 'MAESTRO_CODEX_PATH fallback', deps);
+    }
+
+    const found = await discoverCommand(configured, deps);
+    if (found) {
+      return resolveDiscoveredCodex(found, 'MAESTRO_CODEX_PATH PATH fallback', deps);
+    }
+
+    throw codexNotFoundError();
+  }
+
+  if (isWindowsPlatform(platform)) {
+    const candidates = ['codex.exe', 'codex.cmd', 'codex'];
+    for (const candidate of candidates) {
+      const found = await discoverCommand(candidate, deps);
+      if (found) {
+        return resolveDiscoveredCodex(found, 'PATH/where.exe ' + candidate, deps);
+      }
+    }
+
+    throw codexNotFoundError();
+  }
+
+  return {
+    command: CONFIG.codexPath,
+    argsPrefix: [],
+    kind: commandKind(CONFIG.codexPath),
+    source: 'fallback'
+  };
+}
+
+export function getDefaultCodexCmdPath() {
+  if (process.env.MAESTRO_CODEX_CMD) {
+    return process.env.MAESTRO_CODEX_CMD;
+  }
+  if (process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'npm', 'codex.cmd');
+  }
+  return 'C:\\Users\\PC\\AppData\\Roaming\\npm\\codex.cmd';
+}
+
+export function getDefaultCodexJsPath() {
+  if (process.env.MAESTRO_CODEX_JS) {
+    return process.env.MAESTRO_CODEX_JS;
+  }
+  if (process.env.APPDATA) {
+    return path.join(process.env.APPDATA, 'npm', 'node_modules', '@openai', 'codex', 'bin', 'codex.js');
+  }
+  return 'C:\\Users\\PC\\AppData\\Roaming\\npm\\node_modules\\@openai\\codex\\bin\\codex.js';
+}
+
+export function getCodexComparePath() {
+  return path.join(CONFIG.maestroPath, 'codex-compare.json');
+}
+
+export async function readCodexCompare() {
+  try {
+    return JSON.parse(await fs.readFile(getCodexComparePath(), 'utf-8'));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    return null;
+  }
+}
+
+export async function writeCodexCompare(value) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const payload = stampSchemaVersion({
+    timestamp: new Date().toISOString(),
+    ...value
+  });
+  await fs.writeFile(getCodexComparePath(), JSON.stringify(payload, null, 2));
+  return payload;
+}
+
+// Hotfix A.2: auto mode only ever picks an ISOLATED-home invocation. The
+// normal-home modes ('codex-js-normal-home', 'codex-cmd') silently shared
+// the Codex Desktop config (plugins, elevated Windows sandbox, normal
+// CODEX_HOME) with Maestro workers — exactly the mixing this hotfix
+// removes. They remain available only via an explicit
+// MAESTRO_CODEX_INVOCATION override and inside `maestro codex-compare`
+// diagnostics.
+function chooseInvocationFromCompare(compare) {
+  const tests = compare && Array.isArray(compare.tests) ? compare.tests : [];
+  const byInvocation = new Map();
+  for (const test of tests) {
+    if (test.invocation) {
+      byInvocation.set(test.invocation, test);
+    }
+  }
+  for (const candidate of ['codex-js-isolated', 'codex-cmd-isolated']) {
+    const test = byInvocation.get(candidate);
+    if (test && test.ok) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+export async function resolveCodexInvocationMode() {
+  if (CONFIG.codexInvocation && CONFIG.codexInvocation !== 'auto') {
+    return CONFIG.codexInvocation;
+  }
+  const compare = await readCodexCompare();
+  return chooseInvocationFromCompare(compare) || 'codex-js-isolated';
+}
+
+export async function resolveCodexInvocationForMode(mode = 'auto') {
+  const selected = mode === 'auto' ? await resolveCodexInvocationMode() : mode;
+  if (selected === 'codex-cmd' || selected === 'codex-cmd-isolated') {
+    return {
+      command: getDefaultCodexCmdPath(),
+      argsPrefix: [],
+      kind: 'cmd',
+      source: selected,
+      mode: selected,
+      usesIsolatedHome: selected === 'codex-cmd-isolated'
+    };
+  }
+  if (selected === 'codex-js-normal-home' || selected === 'codex-js-isolated' || selected === 'codex-js') {
+    const normalized = selected === 'codex-js' ? 'codex-js-isolated' : selected;
+    return {
+      command: process.execPath,
+      argsPrefix: [getDefaultCodexJsPath()],
+      kind: 'direct',
+      source: normalized,
+      mode: normalized,
+      usesIsolatedHome: normalized === 'codex-js-isolated'
+    };
+  }
+  return resolveCodexInvocation();
+}
+
+export function buildCodexEnvForInvocation(invocation, baseEnv = process.env) {
+  const env = { ...baseEnv };
+  if (invocation.usesIsolatedHome) {
+    env.CODEX_HOME = CONFIG.codexHome;
+    if (!env.NINEROUTER_API_KEY && env.MAESTRO_ALLOW_LOCAL_TEST_KEY === '1') {
+      env.NINEROUTER_API_KEY = 'local-test';
+    }
+  } else {
+    delete env.CODEX_HOME;
+  }
+  return env;
+}
+
+export async function resolveCodexCommand() {
+  const invocation = await resolveCodexInvocation();
+  return {
+    command: invocation.command,
+    kind: invocation.kind || commandKind(invocation.command),
+    source: invocation.source,
+    argsPrefix: invocation.argsPrefix,
+    warning: invocation.warning
+  };
+}
+
+export async function runCodex(args, options = {}) {
+  const {
+    execFileRaw: execFileRawOption,
+    execFileRawFn = execFileRawOption || execFileRaw,
+    invocation: injectedInvocation,
+    strategyName: injectedStrategyName,
+    ...execOptions
+  } = options;
+
+  try {
+    const invocation = injectedInvocation || await resolveCodexInvocationForMode('auto');
+    const strategyName = injectedStrategyName || await resolveRunCodexStrategy();
+    const strategyArgs = await applyCodexStrategy(args, strategyName);
+    const fullArgs = [...invocation.argsPrefix, ...strategyArgs];
+    const kind = invocation.kind || commandKind(invocation.command);
+    const env = execOptions.env ? execOptions.env : buildCodexEnvForInvocation(invocation);
+    if (kind === 'cmd') {
+      return buildCmdOnlyFailure(invocation, strategyName, strategyArgs);
+    }
+    const result = await execFileRawFn(invocation.command, fullArgs, { ...execOptions, env, shell: false });
+    return { ...result, invocation, resolved: invocation, strategy: strategyName, invocationMode: invocation.mode, args: strategyArgs };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return buildResolutionFailure(codexNotFoundError(), injectedStrategyName || null, args);
+    }
+    throw error;
+  }
+}
+
+// 'workspace-permissions' was removed in Hotfix A.2: its profile layer was
+// never loaded by any default run (doctor always reported
+// "default_permissions used: false"), and `default_permissions` cannot be
+// combined with the `sandbox_mode` mechanism this project standardizes on.
+// 'trusted-workspace' is deliberately NOT in this list: it
+// bypasses Codex's internal sandbox and may only be enabled explicitly via
+// MAESTRO_CODEX_STRATEGY=trusted-workspace (see evaluateTrustedWorkspaceStrategy),
+// never adopted automatically from a validated-strategy file.
+export const SAFE_CODEX_STRATEGIES = ['basic', 'global-approval', 'config-override', 'ignore-rules'];
+
+// Guard for the explicit, audited Windows-sandbox fallback. When Codex's
+// internal Windows sandbox is broken (helper_unknown_error: apply deny-read
+// ACLs), the ONLY sanctioned escape hatch is MAESTRO_CODEX_STRATEGY=
+// trusted-workspace, and it still runs inside every Maestro-side guard
+// (safety guard, runtime gate, deletion guard, workspace diff, engine
+// policy, budget). This function is pure so tests can exercise it without
+// touching the environment.
+export function evaluateTrustedWorkspaceStrategy({
+  envStrategy = process.env.MAESTRO_CODEX_STRATEGY,
+  cwd = process.cwd(),
+  projectRoot = process.cwd()
+} = {}) {
+  if (envStrategy !== 'trusted-workspace') {
+    return {
+      allowed: false,
+      reason: 'trusted-workspace requires the explicit environment variable MAESTRO_CODEX_STRATEGY=trusted-workspace; it is never a silent default.'
+    };
+  }
+  const resolvedCwd = path.resolve(String(cwd));
+  const resolvedRoot = path.resolve(String(projectRoot));
+  const normalizedCwd = resolvedCwd.toLowerCase();
+  const normalizedRoot = resolvedRoot.toLowerCase();
+  const inside = normalizedCwd === normalizedRoot || normalizedCwd.startsWith(normalizedRoot + path.sep.toLowerCase());
+  if (!inside) {
+    return {
+      allowed: false,
+      reason: 'trusted-workspace only operates inside the projectRoot (' + resolvedRoot + '); current cwd is ' + resolvedCwd + '.'
+    };
+  }
+  return {
+    allowed: true,
+    reason: 'explicit MAESTRO_CODEX_STRATEGY=trusted-workspace inside the projectRoot.'
+  };
+}
+
+// Runtime wrapper: on top of the pure guard, require an initialized Maestro
+// project root (.maestro present) so the bypass can never run against an
+// arbitrary directory.
+export async function resolveTrustedWorkspaceGuard() {
+  const guard = evaluateTrustedWorkspaceStrategy();
+  if (!guard.allowed) {
+    return guard;
+  }
+  if (!(await pathExists(path.join(process.cwd(), CONFIG.maestroPath)))) {
+    return {
+      allowed: false,
+      reason: 'trusted-workspace requires an initialized Maestro project root (.maestro not found in ' + process.cwd() + ').'
+    };
+  }
+  return guard;
+}
+
+export function getCodexStrategyPath() {
+  return path.join(CONFIG.maestroPath, 'codex-strategy.json');
+}
+
+export async function readValidatedCodexStrategy() {
+  try {
+    const value = JSON.parse(await fs.readFile(getCodexStrategyPath(), 'utf-8'));
+    return value && value.strategy ? value : null;
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return null;
+    }
+    return null;
+  }
+}
+
+export async function writeValidatedCodexStrategy(entry) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const value = stampSchemaVersion({
+    timestamp: new Date().toISOString(),
+    ...entry
+  });
+  await fs.writeFile(getCodexStrategyPath(), JSON.stringify(value, null, 2));
+  return value;
+}
+
+export async function resolveRunCodexStrategy() {
+  const configured = CONFIG.codexStrategy;
+  if (configured === 'trusted-workspace') {
+    // Explicit, audited fallback only: if the guard refuses (not enabled
+    // explicitly, outside the projectRoot, or no .maestro root), fall back
+    // to the sandboxed 'basic' strategy instead of bypassing silently.
+    const guard = await resolveTrustedWorkspaceGuard();
+    return guard.allowed ? 'trusted-workspace' : 'basic';
+  }
+  if (configured && configured !== 'auto') {
+    return configured;
+  }
+  const validated = await readValidatedCodexStrategy();
+  if (validated && SAFE_CODEX_STRATEGIES.includes(validated.strategy)) {
+    return validated.strategy;
+  }
+  return 'basic';
+}
+
+function removeOptionPair(args, optionName) {
+  const next = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === optionName) {
+      i++;
+      continue;
+    }
+    next.push(args[i]);
+  }
+  return next;
+}
+
+export async function applyCodexStrategy(args, strategyName) {
+  if (!args.length || args[0] !== 'exec') {
+    return args;
+  }
+
+  if (strategyName === 'global-approval') {
+    return ['--ask-for-approval', 'never', ...args];
+  }
+  if (strategyName === 'config-override') {
+    const prompt = args[args.length - 1];
+    const head = args.slice(0, -1);
+    return [...head, '-c', 'approval_policy="never"', '-c', 'sandbox_mode="workspace-write"', prompt];
+  }
+  if (strategyName === 'global-config-override') {
+    return ['-c', 'approval_policy="never"', '-c', 'sandbox_mode="workspace-write"', ...args];
+  }
+  if (strategyName === 'ignore-rules') {
+    const prompt = args[args.length - 1];
+    const head = args.slice(0, -1);
+    return [...head, '--ignore-rules', prompt];
+  }
+  if (strategyName === 'trusted-workspace') {
+    const guard = await resolveTrustedWorkspaceGuard();
+    if (!guard.allowed) {
+      // Never bypass silently: without the explicit env opt-in inside the
+      // projectRoot, keep the normal sandboxed args.
+      return args;
+    }
+    const prompt = args[args.length - 1];
+    const head = removeOptionPair(args.slice(0, -1), '--sandbox');
+    return [...head, '--dangerously-bypass-approvals-and-sandbox', prompt];
+  }
+  if (strategyName === 'dangerous-yolo') {
+    const prompt = args[args.length - 1];
+    const head = args.slice(0, -1);
+    return [...head, '--dangerously-bypass-approvals-and-sandbox', prompt];
+  }
+  return args;
+}
+
+export async function getCodexHelpMatrix() {
+  const globalHelp = await runCodexRaw(['--help'], { quiet: true, env: getCodexEnv() });
+  const execHelp = await runCodexRaw(['exec', '--help'], { quiet: true, env: getCodexEnv() });
+  const globalOutput = (globalHelp.stdout || '') + '\n' + (globalHelp.stderr || '');
+  const execOutput = (execHelp.stdout || '') + '\n' + (execHelp.stderr || '');
+  return {
+    globalHelp,
+    execHelp,
+    hasGlobalAskForApproval: /--ask-for-approval\b/.test(globalOutput),
+    hasGlobalShortApproval: /(^|\s)-a[,=\s]/.test(globalOutput) || /-a,\s*--ask-for-approval/.test(globalOutput),
+    hasExecSandbox: /--sandbox\b/.test(execOutput),
+    hasExecConfig: /--config\b/.test(execOutput),
+    hasExecShortConfig: /(^|\s)-c[,=\s]/.test(execOutput) || /-c,\s*--config/.test(execOutput),
+    hasExecIgnoreRules: /--ignore-rules\b/.test(execOutput),
+    hasDangerousBypass: /--dangerously-bypass-approvals-and-sandbox\b/.test(globalOutput + '\n' + execOutput)
+  };
+}
+
+export async function runCodexRaw(args, options = {}) {
+  const {
+    execFileRaw: execFileRawOption,
+    execFileRawFn = execFileRawOption || execFileRaw,
+    invocation: injectedInvocation,
+    invocationMode = 'auto',
+    ...execOptions
+  } = options;
+
+  try {
+    const invocation = injectedInvocation || await resolveCodexInvocationForMode(invocationMode);
+    const fullArgs = [...invocation.argsPrefix, ...args];
+    const kind = invocation.kind || commandKind(invocation.command);
+    const env = execOptions.env ? execOptions.env : buildCodexEnvForInvocation(invocation);
+    if (kind === 'cmd') {
+      return buildCmdOnlyFailure(invocation, null, args);
+    }
+    const result = await execFileRawFn(invocation.command, fullArgs, { ...execOptions, env, shell: false });
+    return { ...result, invocation, resolved: invocation, args };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return buildResolutionFailure(codexNotFoundError(), null, args);
+    }
+    throw error;
+  }
+}
+
+export async function resolveNpxInvocation() {
+  if (process.env.MAESTRO_NPX_PATH) {
+    return {
+      command: process.env.MAESTRO_NPX_PATH,
+      argsPrefix: [],
+      kind: commandKind(process.env.MAESTRO_NPX_PATH),
+      source: 'MAESTRO_NPX_PATH'
+    };
+  }
+
+  if (isWindows()) {
+    const candidates = ['npx.cmd', 'npx'];
+    for (const candidate of candidates) {
+      const found = await findWithWhere(candidate);
+      if (found) {
+        return {
+          command: found,
+          argsPrefix: [],
+          kind: commandKind(found),
+          source: 'where.exe ' + candidate
+        };
+      }
+    }
+
+    throw npxNotFoundError();
+  }
+
+  return {
+    command: CONFIG.npxPath,
+    argsPrefix: [],
+    kind: commandKind(CONFIG.npxPath),
+    source: 'fallback'
+  };
+}
+
+export async function runNpx(args, options = {}) {
+  const invocation = await resolveNpxInvocation();
+  const fullArgs = [...invocation.argsPrefix, ...args];
+  const kind = invocation.kind || commandKind(invocation.command);
+
+  try {
+    const result = kind === 'cmd'
+      ? await execCmdFile(invocation.command, fullArgs, options)
+      : await execFileRaw(invocation.command, fullArgs, options);
+    return { ...result, invocation, resolved: invocation };
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      error.message = npxNotFoundError().message;
+    }
+    throw error;
+  }
+}
+
+export async function checkCommand(command, args = []) {
+  try {
+    const result = await execFileRaw(command, args, { quiet: true });
+    return { ok: result.code === 0, ...result };
+  } catch (error) {
+    return { ok: false, code: error.code || 1, stdout: '', stderr: error.message };
+  }
+}