ai-maestro 1.0.0

package/src/codex-diagnostics.mjs

@@ -0,0 +1,682 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { pathExists } from './files.mjs';
+import { execCmdFile, execFileRaw } from './shell.mjs';
+import { runHostValidation, resolveNpmInvocation } from './orchestration/host-validation.mjs';
+import {
+  runCodex, getDefaultCodexCmdPath, getDefaultCodexJsPath, writeCodexCompare,
+  getCodexComparePath, resolveCodexInvocationMode
+} from './commands.mjs';
+import { DEFAULT_CODEX_PROFILE_CONFIG, ensureCodexHome } from './codex-home.mjs';
+import {
+  inspectSensitiveContent, copyDirectorySafe, restoreDirectoryFromBackup,
+  safeProbeName, timestampForPath, inspectHome, summarizeHomeIssues, classifyInventoryPath, sha256File,
+  readSafeStructure
+} from './codex-home-inspect.mjs';
+import { summarizeText, normalizeReadContent, detectField, doctorLine } from './format.mjs';
+import { logMemory, memoryDecision } from './memory-log.mjs';
+import { recordUsage } from './usage.mjs';
+import { getCodexDebugInfo, formatEffectiveRuntimeLines } from './debug.mjs';
+
+const SANDBOX_ACL_FAILURE_PATTERN = /helper_unknown_error|apply deny-read acls/i;
+
+export async function codexHomeCommand() {
+  const result = await ensureCodexHome();
+  doctorLine('OK', 'Codex home', result.codexHome);
+  doctorLine('OK', 'Config path', result.configPath);
+  doctorLine((result.checks.hasProvider9router || result.checks.hasProfile9router) ? 'OK' : 'ERRO', 'Provider 9router', result.checks.hasProvider9router || result.checks.hasProfile9router);
+  doctorLine(result.checks.hasProfile9router ? 'OK' : 'ERRO', 'Profile 9router', result.checks.hasProfile9router);
+  doctorLine(result.checks.mixesDefaultPermissionsAndSandboxMode ? 'ERRO' : 'OK', 'default_permissions + sandbox_mode mix', result.checks.mixesDefaultPermissionsAndSandboxMode);
+}
+
+export async function codexHomeDiff() {
+  const normal = await inspectHome(CONFIG.normalCodexHome);
+  const maestro = await inspectHome(CONFIG.codexHome);
+  const normalPaths = new Set(normal.files.map(file => file.path));
+  const maestroPaths = new Set(maestro.files.map(file => file.path));
+  const payload = {
+    timestamp: new Date().toISOString(),
+    normalHome: CONFIG.normalCodexHome,
+    maestroHome: CONFIG.codexHome,
+    normal: { ...normal, summary: summarizeHomeIssues(normal) },
+    maestro: { ...maestro, summary: summarizeHomeIssues(maestro) },
+    onlyInNormal: [...normalPaths].filter(item => !maestroPaths.has(item)).sort(),
+    onlyInMaestro: [...maestroPaths].filter(item => !normalPaths.has(item)).sort(),
+    common: [...normalPaths].filter(item => maestroPaths.has(item)).sort()
+  };
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const diffPath = path.join(CONFIG.maestroPath, 'codex-home-diff.json');
+  await fs.writeFile(diffPath, JSON.stringify(payload, null, 2));
+  await logMemory('maestro codex-home-diff compared normal and Maestro Codex homes. Maestro summary: ' + JSON.stringify(payload.maestro.summary) + '.');
+  console.log('Codex home diff saved: ' + diffPath);
+  console.log('Normal files: ' + normal.files.length);
+  console.log('Maestro files: ' + maestro.files.length);
+  console.log('Maestro summary: ' + JSON.stringify(payload.maestro.summary));
+}
+
+export async function codexHomeInventory() {
+  const normal = await inspectHome(CONFIG.normalCodexHome);
+  const maestro = await inspectHome(CONFIG.codexHome);
+  const byPath = new Map();
+  for (const file of normal.files) {
+    byPath.set(file.path, { path: file.path, normal: file, maestro: null });
+  }
+  for (const file of maestro.files) {
+    const row = byPath.get(file.path) || { path: file.path, normal: null, maestro: null };
+    row.maestro = file;
+    byPath.set(file.path, row);
+  }
+
+  const entries = [];
+  for (const row of [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path))) {
+    const source = row.normal || row.maestro || {};
+    const classified = classifyInventoryPath(row.path, source);
+    const normalPath = row.normal ? path.join(CONFIG.normalCodexHome, row.path) : null;
+    const maestroPath = row.maestro ? path.join(CONFIG.codexHome, row.path) : null;
+    const canHashNormal = row.normal && row.normal.type === 'file' && !/(sensitive|cache|unknown-sensitive)/.test(classified.classification);
+    const canHashMaestro = row.maestro && row.maestro.type === 'file' && !/(sensitive|cache|unknown-sensitive)/.test(classified.classification);
+    const existsOnlyNormal = !!row.normal && !row.maestro;
+    const differs = row.normal && row.maestro && row.normal.type === 'file' && row.maestro.type === 'file' && row.normal.size !== row.maestro.size;
+    const safeCopyCandidate = classified.safeCopyCandidate && !!row.normal && row.normal.type === 'file' && (existsOnlyNormal || differs);
+    const entry = {
+      path: row.path,
+      existsInNormal: !!row.normal,
+      existsInMaestro: !!row.maestro,
+      normalSize: row.normal && row.normal.type === 'file' ? row.normal.size : null,
+      maestroSize: row.maestro && row.maestro.type === 'file' ? row.maestro.size : null,
+      extension: path.extname(row.path).toLowerCase(),
+      classification: classified.classification,
+      safeCopyCandidate,
+      reason: safeCopyCandidate ? classified.reason : classified.reason + (row.normal && row.maestro && !differs ? '; already present with same size or not a missing candidate' : ''),
+      normalSha256: canHashNormal ? await sha256File(normalPath) : null,
+      maestroSha256: canHashMaestro ? await sha256File(maestroPath) : null,
+      normalStructure: safeCopyCandidate ? await readSafeStructure(CONFIG.normalCodexHome, row.path, classified.classification) : null
+    };
+    if (entry.normalSha256 && entry.maestroSha256 && entry.normalSha256 !== entry.maestroSha256) {
+      entry.differs = true;
+      if (classified.safeCopyCandidate && row.normal && row.maestro) {
+        entry.safeCopyCandidate = true;
+        entry.reason = classified.reason + '; hashes differ';
+      }
+    } else {
+      entry.differs = !!differs;
+    }
+    entries.push(entry);
+  }
+
+  const payload = {
+    timestamp: new Date().toISOString(),
+    normalHome: CONFIG.normalCodexHome,
+    maestroHome: CONFIG.codexHome,
+    entries,
+    candidates: entries.filter(entry => entry.safeCopyCandidate).map(entry => entry.path),
+    counts: entries.reduce((acc, entry) => {
+      acc.total++;
+      acc[entry.classification] = (acc[entry.classification] || 0) + 1;
+      if (entry.safeCopyCandidate) {
+        acc.safeCopyCandidates++;
+      }
+      return acc;
+    }, { total: 0, safeCopyCandidates: 0 })
+  };
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const inventoryPath = path.join(CONFIG.maestroPath, 'codex-home-inventory.json');
+  await fs.writeFile(inventoryPath, JSON.stringify(payload, null, 2));
+  await logMemory('maestro codex-home-inventory generated ' + payload.entries.length + ' entries and ' + payload.candidates.length + ' safe candidates.');
+  console.log('Codex home inventory saved: ' + inventoryPath);
+  console.log('Safe candidates: ' + payload.candidates.length);
+  console.log('Counts: ' + JSON.stringify(payload.counts));
+}
+
+function candidatePriority(pathName) {
+  const lower = pathName.toLowerCase();
+  if (lower.startsWith('.sandbox/') && !lower.includes('secret')) return 0;
+  if (/(trust|trusted|approval|permission|policy|workspace|project|settings)/i.test(lower)) return 1;
+  if (/(config|rules?)/i.test(lower)) return 2;
+  if (/(metadata|state)/i.test(lower)) return 3;
+  return 4;
+}
+
+function isolatedCompareEnv() {
+  const env = { ...process.env, CODEX_HOME: CONFIG.codexHome };
+  if (!env.NINEROUTER_API_KEY && env.MAESTRO_ALLOW_LOCAL_TEST_KEY === '1') {
+    env.NINEROUTER_API_KEY = 'local-test';
+  }
+  return env;
+}
+
+async function runIsolatedProbeFile(fileName, expected) {
+  const expectedPath = path.join(process.cwd(), fileName);
+  try {
+    await fs.unlink(expectedPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+  const jsPath = getDefaultCodexJsPath();
+  const args = [jsPath, 'exec', '--profile', CONFIG.codexProfile, '--sandbox', 'workspace-write', '--skip-git-repo-check', 'Crie ' + fileName + ' com exatamente: ' + expected];
+  const result = await execFileRaw(process.execPath, args, { env: isolatedCompareEnv(), quiet: true, timeoutMs: 60000 });
+  let fileCreated = false;
+  let contentOk = false;
+  let actualContent = '';
+  try {
+    actualContent = normalizeReadContent(await fs.readFile(expectedPath)).trim();
+    fileCreated = true;
+    contentOk = actualContent === expected;
+  } catch (error) {
+    actualContent = '';
+  }
+  const output = result.stdout + '\n' + result.stderr;
+  return {
+    exitCode: result.code,
+    sandbox: detectField(output, 'sandbox'),
+    provider: detectField(output, 'provider'),
+    apiOpenAi: /api\.openai\.com/i.test(output),
+    blockedByPolicy: /blocked by policy/i.test(output),
+    readOnly: /read-only/i.test(output),
+    file: fileName,
+    fileCreated,
+    contentOk,
+    ok: result.code === 0 && fileCreated && contentOk,
+    stdout: summarizeText(result.stdout),
+    stderr: summarizeText(result.stderr)
+  };
+}
+
+export async function codexHomeProbe() {
+  const inventoryPath = path.join(CONFIG.maestroPath, 'codex-home-inventory.json');
+  let inventory;
+  try {
+    inventory = JSON.parse(await fs.readFile(inventoryPath, 'utf-8'));
+  } catch (error) {
+    await codexHomeInventory();
+    inventory = JSON.parse(await fs.readFile(inventoryPath, 'utf-8'));
+  }
+
+  const baseline = await runIsolatedProbeFile('PROBE_BASELINE_ISOLATED.md', 'baseline codex-js-isolated probe.');
+  if (baseline.ok) {
+    const payload = {
+      timestamp: new Date().toISOString(),
+      baseline,
+      candidatesTested: 0,
+      attempts: [],
+      winner: { candidate: '<already-working>', result: baseline },
+      conclusion: 'codex-js-isolated already has workspace-write; no candidate copy needed.'
+    };
+    const probePath = path.join(CONFIG.maestroPath, 'codex-home-probe.json');
+    await fs.writeFile(probePath, JSON.stringify(payload, null, 2));
+    await logMemory('maestro codex-home-probe baseline already works; no candidates copied.');
+    console.log('Codex home probe saved: ' + probePath);
+    console.log('Winner: <already-working>');
+    return;
+  }
+
+  const candidates = inventory.entries
+    .filter(entry => entry.safeCopyCandidate)
+    .filter(entry => !/(auth|token|credential|secret|session|cookie|cache|key|login|account|\.tmp|\/tmp\/|sessions\/)/i.test(entry.path))
+    .sort((a, b) => candidatePriority(a.path) - candidatePriority(b.path) || a.path.localeCompare(b.path))
+    .slice(0, 80);
+
+  const attempts = [];
+  let winner = null;
+  for (const candidate of candidates) {
+    const backupPath = CONFIG.codexHome + '.probe-backup-' + timestampForPath() + '-' + safeProbeName(candidate.path);
+    await copyDirectorySafe(CONFIG.codexHome, backupPath);
+    const source = path.join(CONFIG.normalCodexHome, candidate.path);
+    const target = path.join(CONFIG.codexHome, candidate.path);
+    const sensitiveInspection = await inspectSensitiveContent(source, candidate.path);
+    if (!sensitiveInspection.ok) {
+      attempts.push({ candidate: candidate.path, backupPath, classification: candidate.classification, skipped: true, reason: sensitiveInspection.reason });
+      await restoreDirectoryFromBackup(backupPath, CONFIG.codexHome);
+      console.log(candidate.path + ': skipped=' + sensitiveInspection.reason);
+      continue;
+    }
+    await fs.mkdir(path.dirname(target), { recursive: true });
+    await fs.copyFile(source, target);
+    const probeName = 'PROBE_' + safeProbeName(candidate.path) + '.md';
+    const expected = 'probe ' + candidate.path + ' funcionou.';
+    const result = await runIsolatedProbeFile(probeName, expected);
+    const attempt = { candidate: candidate.path, backupPath, classification: candidate.classification, result };
+    attempts.push(attempt);
+    console.log(candidate.path + ': ok=' + result.ok + ', sandbox=' + (result.sandbox || 'unknown'));
+    if (result.ok) {
+      winner = attempt;
+      break;
+    }
+    await restoreDirectoryFromBackup(backupPath, CONFIG.codexHome);
+  }
+
+  const payload = {
+    timestamp: new Date().toISOString(),
+    baseline,
+    candidatesTested: attempts.length,
+    attempts,
+    winner,
+    conclusion: winner ? 'Found safe candidate that unlocks isolated workspace-write.' : 'No safe candidate unlocked isolated workspace-write; keep normal-home fallback.'
+  };
+  const probePath = path.join(CONFIG.maestroPath, 'codex-home-probe.json');
+  await fs.writeFile(probePath, JSON.stringify(payload, null, 2));
+  await logMemory('maestro codex-home-probe tested ' + attempts.length + ' safe candidates. Winner: ' + (winner ? winner.candidate : 'none') + '.');
+  if (winner) {
+    await memoryDecision('Use safe Codex home candidate "' + winner.candidate + '" to unlock codex-js-isolated.');
+  } else {
+    await memoryDecision('No safe Codex home candidate unlocked codex-js-isolated; keep codex-js-normal-home fallback.');
+  }
+  console.log('Codex home probe saved: ' + probePath);
+  console.log('Winner: ' + (winner ? winner.candidate : 'none'));
+  if (!winner) {
+    process.exitCode = 1;
+  }
+}
+
+export async function codexHomeRepair() {
+  await fs.mkdir(CONFIG.codexHome, { recursive: true });
+  const backupPath = CONFIG.codexHome + '.backup-' + timestampForPath();
+  await copyDirectorySafe(CONFIG.codexHome, backupPath);
+  const profilePath = path.join(CONFIG.codexHome, '9router.config.toml');
+  await fs.writeFile(profilePath, DEFAULT_CODEX_PROFILE_CONFIG);
+  const copiedPolicyFiles = [];
+  const normalSandboxBin = path.join(CONFIG.normalCodexHome, '.sandbox-bin');
+  const maestroSandboxBin = path.join(CONFIG.codexHome, '.sandbox-bin');
+  if (await pathExists(normalSandboxBin)) {
+    await copyDirectorySafe(normalSandboxBin, maestroSandboxBin);
+    copiedPolicyFiles.push(maestroSandboxBin);
+  }
+  const normalSandboxMarker = path.join(CONFIG.normalCodexHome, '.sandbox', 'setup_marker.json');
+  if (await pathExists(normalSandboxMarker)) {
+    const markerInspection = await inspectSensitiveContent(normalSandboxMarker, '.sandbox/setup_marker.json');
+    if (markerInspection.ok) {
+      const maestroSandboxDir = path.join(CONFIG.codexHome, '.sandbox');
+      await fs.mkdir(maestroSandboxDir, { recursive: true });
+      const maestroSandboxMarker = path.join(maestroSandboxDir, 'setup_marker.json');
+      await fs.copyFile(normalSandboxMarker, maestroSandboxMarker);
+      copiedPolicyFiles.push(maestroSandboxMarker);
+    } else {
+      copiedPolicyFiles.push('skipped .sandbox/setup_marker.json: ' + markerInspection.reason);
+    }
+  }
+  const repairPath = path.join(CONFIG.maestroPath, 'codex-home-repair.json');
+  const repair = {
+    timestamp: new Date().toISOString(),
+    maestroHome: CONFIG.codexHome,
+    backupPath,
+    changedFiles: [profilePath, ...copiedPolicyFiles],
+    copiedPolicyFiles,
+    skippedSensitiveCopy: true,
+    note: 'Rewrote 9router.config.toml and copied non-sensitive sandbox runtime files only. No auth/session/token/cookie/cache files copied.'
+  };
+  await fs.writeFile(repairPath, JSON.stringify(repair, null, 2));
+  await logMemory('maestro codex-home-repair backed up ' + CONFIG.codexHome + ' to ' + backupPath + ' and rewrote 9router.config.toml without copying secrets.');
+  console.log('Codex home backup: ' + backupPath);
+  console.log('Repair saved: ' + repairPath);
+}
+
+function withoutPrompt(args) {
+  return args.slice(0, -1).concat(['<prompt>']);
+}
+
+function normalHomeEnv() {
+  const env = { ...process.env };
+  delete env.CODEX_HOME;
+  return env;
+}
+
+async function runCompareTest(test) {
+  const expectedPath = path.join(process.cwd(), test.file);
+  try {
+    await fs.unlink(expectedPath);
+  } catch (error) {
+    if (error.code !== 'ENOENT') {
+      throw error;
+    }
+  }
+
+  const result = test.kind === 'cmd'
+    ? await execCmdFile(test.command, test.args, { env: test.env, quiet: true, timeoutMs: 60000 })
+    : await execFileRaw(test.command, test.args, { env: test.env, quiet: true, timeoutMs: 60000 });
+
+  let fileContent = '';
+  let fileCreated = false;
+  let contentOk = false;
+  try {
+    fileContent = normalizeReadContent(await fs.readFile(expectedPath));
+    fileCreated = true;
+    contentOk = fileContent.trim() === test.expected;
+  } catch (error) {
+    fileContent = error.message;
+  }
+
+  const output = (result.stdout || '') + '\n' + (result.stderr || '');
+  return {
+    id: test.id,
+    invocation: test.invocation,
+    command: test.command,
+    args: withoutPrompt(test.args),
+    codexHome: test.env && test.env.CODEX_HOME ? test.env.CODEX_HOME : null,
+    exitCode: result.code,
+    provider: detectField(output, 'provider'),
+    sandbox: detectField(output, 'sandbox'),
+    apiOpenAi: /api\.openai\.com/i.test(output),
+    blockedByPolicy: /blocked by policy/i.test(output),
+    readOnly: /read-only/i.test(output),
+    file: test.file,
+    fileCreated,
+    contentOk,
+    ok: result.code === 0 && fileCreated && contentOk,
+    stdout: summarizeText(result.stdout),
+    stderr: summarizeText(result.stderr),
+    actualContent: fileCreated ? fileContent.trim() : ''
+  };
+}
+
+function compareRecommendation(tests) {
+  const byId = new Map(tests.map(test => [test.id, test]));
+  const a = byId.get('working-baseline-cmd');
+  const b = byId.get('cmd-with-codex-home');
+  const c = byId.get('node-js-with-normal-codex-home');
+  const d = byId.get('node-js-with-codex-home');
+  if (!a || !a.ok) {
+    return 'Baseline codex.cmd falhou; o ambiente externo mudou.';
+  }
+  if (a.ok && b && !b.ok) {
+    return 'Problema provável no CODEX_HOME isolado ou na config isolada.';
+  }
+  if (a.ok && c && !c.ok) {
+    return 'Problema provável em node.exe + codex.js; usar codex.cmd como compatibilidade.';
+  }
+  if (b && b.ok && d && !d.ok) {
+    return 'Problema provável em node.exe + codex.js com CODEX_HOME; usar codex.cmd com CODEX_HOME.';
+  }
+  if ([a, b, c, d].every(test => test && test.ok)) {
+    return 'Todas as invocações funcionaram; usar a invocação isolada mais segura.';
+  }
+  return 'Comparação inconclusiva; revisar stdout/stderr por teste.';
+}
+
+function chooseCompareWinner(tests) {
+  const order = ['codex-js-isolated', 'codex-cmd-isolated', 'codex-js-normal-home', 'codex-cmd'];
+  for (const invocation of order) {
+    const test = tests.find(item => item.invocation === invocation && item.ok);
+    if (test) {
+      return invocation;
+    }
+  }
+  return null;
+}
+
+export async function codexCompare() {
+  await ensureCodexHome();
+  const cmdPath = getDefaultCodexCmdPath();
+  const jsPath = getDefaultCodexJsPath();
+  const cases = [
+    {
+      id: 'working-baseline-cmd',
+      invocation: 'codex-cmd',
+      kind: 'cmd',
+      command: cmdPath,
+      env: normalHomeEnv(),
+      file: 'WORKING_BASELINE_CMD.md',
+      expected: 'baseline codex.cmd workspace-write funcionou.'
+    },
+    {
+      id: 'cmd-with-codex-home',
+      invocation: 'codex-cmd-isolated',
+      kind: 'cmd',
+      command: cmdPath,
+      env: isolatedCompareEnv(),
+      file: 'WORKING_CMD_CODEX_HOME.md',
+      expected: 'codex.cmd com CODEX_HOME isolado funcionou.'
+    },
+    {
+      id: 'node-js-with-normal-codex-home',
+      invocation: 'codex-js-normal-home',
+      kind: 'direct',
+      command: process.execPath,
+      argsPrefix: [jsPath],
+      env: normalHomeEnv(),
+      file: 'WORKING_NODEJS_NORMAL_HOME.md',
+      expected: 'node codex.js com home normal funcionou.'
+    },
+    {
+      id: 'node-js-with-codex-home',
+      invocation: 'codex-js-isolated',
+      kind: 'direct',
+      command: process.execPath,
+      argsPrefix: [jsPath],
+      env: isolatedCompareEnv(),
+      file: 'WORKING_NODEJS_CODEX_HOME.md',
+      expected: 'node codex.js com CODEX_HOME isolado funcionou.'
+    }
+  ];
+
+  for (const item of cases) {
+    const prompt = 'Crie ' + item.file + ' com exatamente: ' + item.expected;
+    item.args = [...(item.argsPrefix || []), 'exec', '--profile', CONFIG.codexProfile, '--sandbox', 'workspace-write', '--skip-git-repo-check', prompt];
+  }
+
+  const tests = [];
+  for (const item of cases) {
+    console.log('Running compare test: ' + item.id);
+    tests.push(await runCompareTest(item));
+    const last = tests[tests.length - 1];
+    console.log(item.id + ': ok=' + last.ok + ', exit=' + last.exitCode + ', sandbox=' + (last.sandbox || 'unknown'));
+  }
+
+  const winner = chooseCompareWinner(tests);
+  const payload = await writeCodexCompare({
+    winner,
+    recommendation: compareRecommendation(tests),
+    tests
+  });
+  await recordUsage({ command: 'codex-compare', strategy: winner || 'none', promptChars: 0, output: JSON.stringify(tests), exitCode: winner ? 0 : 1 });
+  await logMemory('maestro codex-compare result: ' + tests.map(test => test.id + '=' + (test.ok ? 'ok' : 'fail')).join(', ') + '. Winner: ' + (winner || 'none') + '.');
+  if (winner) {
+    await memoryDecision('Use Codex invocation "' + winner + '" from .maestro/codex-compare.json for MAESTRO_CODEX_INVOCATION=auto.');
+  }
+  console.log('Compare saved: ' + getCodexComparePath());
+  console.log('Winner: ' + (payload.winner || 'none'));
+  console.log('Recommendation: ' + payload.recommendation);
+  if (!winner) {
+    process.exitCode = 1;
+  }
+}
+
+// Hotfix A.2: minimal real workspace test. Asks the worker ONLY to
+// (1) read a probe file inside the project, (2) create a temp file inside
+// .maestro, (3) read it back, (4) delete it, (5) reply success. The read
+// nonce exists only inside the probe file (never in the prompt), so seeing
+// it in the answer proves a real read; the success marker plus the temp
+// file being gone proves write + delete.
+export async function codexTestInvocation() {
+  await ensureCodexHome();
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const nonce = 'MAESTRO-READ-' + Date.now().toString(36) + '-' + Math.random().toString(36).slice(2, 8);
+  const readProbePath = path.join(CONFIG.maestroPath, 'codex-test-read.txt');
+  const tmpPath = path.join(CONFIG.maestroPath, 'codex-test-tmp.txt');
+  await fs.writeFile(readProbePath, nonce + '\n');
+  await fs.rm(tmpPath, { force: true });
+
+  const prompt = [
+    'Minimal workspace access test. Execute exactly these steps, in order:',
+    '1. Read the file .maestro/codex-test-read.txt.',
+    '2. Create the file .maestro/codex-test-tmp.txt whose content is exactly the single line you just read from .maestro/codex-test-read.txt.',
+    '3. Read .maestro/codex-test-tmp.txt back and verify it matches.',
+    '4. Delete .maestro/codex-test-tmp.txt.',
+    '5. If and only if every step succeeded, end your final answer with this single line, replacing <content> with the exact line read in step 1:',
+    'MAESTRO-CODEX-TEST: SUCCESS <content>',
+    'If any step fails, say exactly which step failed and why.',
+    'Do not modify any other file. Do not touch .env files. Do not deploy.'
+  ].join('\n');
+
+  const invocationMode = await resolveCodexInvocationMode();
+  // 300s: the unelevated Windows sandbox adds per-command setup overhead
+  // and the 5-step test issues several tool calls; 60-120s produced false
+  // exit-124 timeouts while the worker was still legitimately executing.
+  const result = await runCodex(['exec', '--profile', CONFIG.codexProfile, '--sandbox', 'workspace-write', '--skip-git-repo-check', prompt], { quiet: true, timeoutMs: 300000 });
+
+  const output = result.stdout + '\n' + result.stderr;
+  const readOk = output.includes(nonce);
+  const successMarkerOk = output.includes('MAESTRO-CODEX-TEST: SUCCESS ' + nonce);
+  const tmpLeftBehind = await pathExists(tmpPath);
+  const sandboxAclFailure = SANDBOX_ACL_FAILURE_PATTERN.test(output);
+  const invocation = result.invocation || {};
+  const attempt = {
+    invocation: invocationMode,
+    strategy: result.strategy,
+    exitCode: result.code,
+    readOk,
+    writeAndDeleteOk: successMarkerOk && !tmpLeftBehind,
+    tmpLeftBehind,
+    sandboxAclFailure,
+    codexHomeIsolated: invocation.usesIsolatedHome === true,
+    sandbox: detectField(output, 'sandbox'),
+    provider: detectField(output, 'provider'),
+    blockedByPolicy: /blocked by policy/i.test(output),
+    readOnly: /read-only/i.test(output),
+    apiOpenAi: /api\.openai\.com/i.test(output),
+    stdout: summarizeText(result.stdout),
+    stderr: summarizeText(result.stderr)
+  };
+  const ok = result.code === 0 && readOk && successMarkerOk && !tmpLeftBehind && !sandboxAclFailure && !attempt.apiOpenAi;
+
+  // Clean up the probe files regardless of outcome.
+  await fs.rm(readProbePath, { force: true });
+  await fs.rm(tmpPath, { force: true });
+
+  await recordUsage({ command: 'codex-test', strategy: invocationMode, prompt, output: JSON.stringify(attempt), exitCode: ok ? 0 : 1, codexTest: true });
+  await logMemory('maestro codex-test used invocation ' + invocationMode + ': readOk=' + readOk + ', writeAndDeleteOk=' + attempt.writeAndDeleteOk + ', sandboxAclFailure=' + sandboxAclFailure + ', exit=' + result.code + '.');
+  console.log(JSON.stringify(attempt, null, 2));
+  if (!ok) {
+    process.exitCode = 1;
+  }
+}
+
+export async function hasRecentCodexTest() {
+  try {
+    const content = await fs.readFile(path.join(CONFIG.maestroPath, 'usage.jsonl'), 'utf-8');
+    const dayMs = 24 * 60 * 60 * 1000;
+    return content.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line)).some(row => {
+      return row.codexTest && row.exitCode === 0 && row.strategy === 'codex-js-isolated' && (Date.now() - new Date(row.timestamp).getTime()) < dayMs;
+    });
+  } catch (error) {
+    return false;
+  }
+}
+
+async function runDiagnosticStep(name, fn) {
+  try {
+    const result = await fn();
+    return { name, ok: result.ok !== false, ...result };
+  } catch (error) {
+    return { name, ok: false, error: error.message };
+  }
+}
+
+export async function codexSandboxTestCommand() {
+  await fs.mkdir(path.join(CONFIG.maestroPath, 'sandbox-test'), { recursive: true });
+  const root = process.cwd();
+  const probe = path.join(CONFIG.maestroPath, 'sandbox-test', 'probe.txt');
+  const checkFile = path.join(CONFIG.maestroPath, 'sandbox-test', 'check-ok.mjs');
+  const unitFile = path.join(CONFIG.maestroPath, 'sandbox-test', 'unit.test.mjs');
+  await fs.writeFile(checkFile, 'const value = 1;\n');
+  await fs.writeFile(unitFile, "import test from 'node:test';\nimport assert from 'node:assert/strict';\ntest('sandbox diagnostic unit', () => assert.equal(1, 1));\n");
+  const steps = [];
+  steps.push(await runDiagnosticStep('filesystem-write', async () => { await fs.writeFile(probe, 'ok\n'); return { ok: true }; }));
+  steps.push(await runDiagnosticStep('filesystem-read', async () => ({ ok: (await fs.readFile(probe, 'utf8')).trim() === 'ok' })));
+  steps.push(await runDiagnosticStep('node', async () => {
+    const result = await execFileRaw(process.execPath, ['--version'], { quiet: true, timeoutMs: 30000 });
+    return { ok: result.code === 0, exitCode: result.code, stdout: summarizeText(result.stdout), stderr: summarizeText(result.stderr) };
+  }));
+  steps.push(await runDiagnosticStep('npm', async () => {
+    const invocation = resolveNpmInvocation(['--version']);
+    const result = await execFileRaw(invocation.executable, invocation.args, { quiet: true, timeoutMs: 30000 });
+    return { ok: result.code === 0, exitCode: result.code, stdout: summarizeText(result.stdout), stderr: summarizeText(result.stderr) };
+  }));
+  steps.push(await runDiagnosticStep('child-process', async () => {
+    const result = await execFileRaw(process.execPath, ['-e', 'process.exit(0)'], { quiet: true, timeoutMs: 30000 });
+    return { ok: result.code === 0, exitCode: result.code, stderr: summarizeText(result.stderr) };
+  }));
+  steps.push(await runDiagnosticStep('node-check', async () => {
+    const result = await runHostValidation({ commandId: 'node-check', projectRoot: root, file: path.relative(root, checkFile) });
+    return { ok: result.ok, exitCode: result.exitCode, stdout: summarizeText(result.stdout), stderr: summarizeText(result.stderr), metadata: result.metadata };
+  }));
+  steps.push(await runDiagnosticStep('unit-test', async () => {
+    const result = await execFileRaw(process.execPath, ['--test', unitFile], { quiet: true, timeoutMs: 60000 });
+    return { ok: result.code === 0, exitCode: result.code, stdout: summarizeText(result.stdout), stderr: summarizeText(result.stderr) };
+  }));
+  steps.push(await runDiagnosticStep('npm-test', async () => {
+    const result = await runHostValidation({ commandId: 'npm-test', projectRoot: root });
+    return { ok: result.ok, exitCode: result.exitCode, stdout: summarizeText(result.stdout), stderr: summarizeText(result.stderr), metadata: result.metadata };
+  }));
+  const payload = { timestamp: new Date().toISOString(), steps, ok: steps.every(step => step.ok) };
+  const reportPath = path.join(CONFIG.maestroPath, 'codex-sandbox-test.json');
+  await fs.writeFile(reportPath, JSON.stringify(payload, null, 2));
+  await fs.rm(path.join(CONFIG.maestroPath, 'sandbox-test'), { recursive: true, force: true });
+  await recordUsage({ command: 'codex-sandbox-test', runKind: 'diagnostic', promptChars: 0, output: JSON.stringify(payload), exitCode: payload.ok ? 0 : 1 });
+  await logMemory('maestro codex-sandbox-test completed: ok=' + payload.ok + ', steps=' + steps.map(step => step.name + '=' + (step.ok ? 'ok' : 'fail')).join(', ') + '.');
+  console.log(JSON.stringify(payload, null, 2));
+  if (!payload.ok) process.exitCode = 1;
+}
+
+export async function codexDebugCommand() {
+  const info = await getCodexDebugInfo();
+  let repair = null;
+  let homeDiff = null;
+  let probe = null;
+  try {
+    repair = JSON.parse(await fs.readFile(path.join(CONFIG.maestroPath, 'codex-home-repair.json'), 'utf-8'));
+  } catch (error) {
+    repair = null;
+  }
+  try {
+    homeDiff = JSON.parse(await fs.readFile(path.join(CONFIG.maestroPath, 'codex-home-diff.json'), 'utf-8'));
+  } catch (error) {
+    homeDiff = null;
+  }
+  try {
+    probe = JSON.parse(await fs.readFile(path.join(CONFIG.maestroPath, 'codex-home-probe.json'), 'utf-8'));
+  } catch (error) {
+    probe = null;
+  }
+  const lines = [
+    'Codex Debug Information',
+    '- Command: ' + info.command,
+    '- Args prefix: ' + info.argsPrefix.join(' '),
+    '- Source: ' + info.source,
+    '- Selected invocation: ' + info.selectedInvocationMode,
+    '- Selected command: ' + info.selectedCommand,
+    '- Selected args prefix: ' + info.selectedArgsPrefix.join(' '),
+    '- Selected uses isolated CODEX_HOME: ' + info.selectedUsesIsolatedHome,
+    '- Normal CODEX_HOME: ' + CONFIG.normalCodexHome,
+    '- CODEX_HOME: ' + info.codexHome,
+    '- Last repair backup: ' + (repair ? repair.backupPath : 'none'),
+    '- Last home diff: ' + (homeDiff ? 'normalFiles=' + homeDiff.normal.files.length + ', maestroFiles=' + homeDiff.maestro.files.length : 'none'),
+    '- Last home probe: ' + (probe ? 'winner=' + (probe.winner ? probe.winner.candidate : 'none') + ', tested=' + probe.candidatesTested : 'none'),
+    '- Isolated probe blocked by policy: ' + (probe && probe.baseline ? probe.baseline.blockedByPolicy : 'unknown'),
+    '- Profile: ' + info.profile,
+    '- Current strategy: ' + info.currentStrategy,
+    '- Last validated strategy: ' + (info.validatedStrategy ? info.validatedStrategy.strategy : 'none'),
+    '- Config file: ' + info.codexConfigPath,
+    '- Profile config file: ' + info.codexProfileConfigPath,
+    '- Legacy workspace-permissions config (unused): ' + info.legacyWorkspacePermissionsConfigPath + ' (exists=' + info.legacyWorkspacePermissionsConfigExists + ')',
+    ...formatEffectiveRuntimeLines(info.effectiveRuntime),
+    '- --ask-for-approval global: ' + !!info.helpMatrix.hasGlobalAskForApproval,
+    '- -a global: ' + !!info.helpMatrix.hasGlobalShortApproval,
+    '- --sandbox exec: ' + !!info.helpMatrix.hasExecSandbox,
+    '- --config exec: ' + !!info.helpMatrix.hasExecConfig,
+    '- -c exec: ' + !!info.helpMatrix.hasExecShortConfig,
+    '- --ignore-rules exec: ' + !!info.helpMatrix.hasExecIgnoreRules,
+    '- dangerous bypass flag present: ' + !!info.helpMatrix.hasDangerousBypass,
+    '- default_permissions used: ' + info.checks.usesDefaultPermissions,
+    '- default_permissions + sandbox_mode mix: ' + info.checks.mixesDefaultPermissionsAndSandboxMode,
+    '- 9Router env active: ' + info.is9RouterActive,
+    '- Last compare winner: ' + (info.lastCompare ? (info.lastCompare.winner || 'none') : 'none'),
+    '- Last compare recommendation: ' + (info.lastCompare ? (info.lastCompare.recommendation || 'none') : 'none'),
+    '- Last compare tests: ' + (info.lastCompare && info.lastCompare.tests ? info.lastCompare.tests.map(test => test.id + '=' + (test.ok ? 'ok' : 'fail')).join(', ') : 'none'),
+    '- Normal-home fallback active: ' + (String(info.selectedInvocationMode).includes('normal-home') || info.selectedInvocationMode === 'codex-cmd')
+  ];
+  await fs.writeFile('codex-debug-output.txt', lines.join('\n'));
+  console.log(lines.join('\n'));
+}