ai-maestro 1.0.0

package/src/session-commands.mjs

@@ -0,0 +1,521 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { pathExists, writeUtf8TextFile } from './files.mjs';
+import { execFile, execCmdFile, execFileRaw } from './shell.mjs';
+import { runNpx, resolveCodexInvocation, getCodexHelpMatrix, readValidatedCodexStrategy, resolveRunCodexStrategy, readCodexCompare, resolveCodexInvocationMode, resolveCodexInvocationForMode } from './commands.mjs';
+import { buildSmartTasks } from './smart-planner.mjs';
+import { ensureCodexHome, getLegacyWorkspacePermissionsConfigPath } from './codex-home.mjs';
+import { getEffectiveCodexRuntime, formatEffectiveRuntimeLines } from './debug.mjs';
+import { generateCheckpoint } from './checkpoint.mjs';
+import { getRecentRuns } from './runner.mjs';
+import { generatePlan } from './planner.mjs';
+import { getTasks, sortRunnableTasks } from './tasks.mjs';
+import { ensureSafetyConfig } from './safety.mjs';
+import { getUsageSummary } from './usage.mjs';
+import { logMemory, memoryDecision } from './memory-log.mjs';
+import { doctorLine, summarizeText } from './format.mjs';
+import { validateTask, validateRunEntry, validateUsageSummary } from './schema.mjs';
+import { readJsonSafe } from './files.mjs';
+import { codexHomeCommand, codexTestInvocation, hasRecentCodexTest } from './codex-diagnostics.mjs';
+import { countTasksByStatus, getPlatformGuidance, decideTaskStatus } from './task-commands.mjs';
+import { detectWindowsShellMismatch, validateChangedFile, isAnalysisOnlyTask } from './run-diagnostics.mjs';
+import { snapshotWorkspace, diffWorkspace } from './workspace-diff.mjs';
+import { getFullHealthSnapshot } from './orchestration/provider-health.mjs';
+import os from 'os';
+
+export function getHelpText() {
+  return [
+    'AI-MAESTRO',
+    'The project remembers. Workers execute.',
+    '',
+    'Fluxo recomendado:',
+    '',
+    '1. maestro start "pedido"',
+    '2. maestro ui',
+    '3. maestro task list',
+    '4. maestro run-task <id>',
+    '5. maestro checkpoint',
+    '6. maestro handoff',
+    '',
+    'Comandos principais:',
+    '',
+    '- maestro start "pedido"',
+    '- maestro ui',
+    '- maestro status',
+    '- maestro doctor',
+    '- maestro task list',
+    '- maestro task show <id>',
+    '- maestro run-one',
+    '- maestro run-task <id>',
+    '- maestro run-task <id> --failover [--dry-run] [--resume]',
+    '- maestro run-all --limit 3',
+    '- maestro run-log <run-id>',
+    '- maestro report <run-id>',
+    '- maestro checkpoint',
+    '- maestro handoff',
+    '- maestro release-check',
+    '- maestro readiness',
+    '- maestro provider-health [--json]',
+    '- maestro canary <path>',
+    '',
+    'Exemplos:',
+    '',
+    '  maestro start "os botoes nao funcionam, termine de fazer o app"',
+    '  maestro run-one',
+    '  maestro run-one --quiet',
+    '  maestro ui',
+    '',
+    'Use "maestro help", "maestro --help" ou "maestro -h" para ver esta mensagem novamente.'
+  ].join('\n');
+}
+
+export function printHelp() {
+  console.log(getHelpText());
+}
+
+export async function init() {
+  if (!(await pathExists(CONFIG.memoryPath))) {
+    const npxResult = await runNpx(['ai-universal-memory', 'init']);
+    if (npxResult.code !== 0) {
+      throw new Error('npx ai-universal-memory init failed: ' + npxResult.stderr);
+    }
+  }
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  for (const file of ['TASKS.json', 'PLAN.md', 'RUNS.jsonl']) {
+    const filePath = path.join(CONFIG.maestroPath, file);
+    if (!(await pathExists(filePath))) {
+      await fs.writeFile(filePath, file === 'TASKS.json' ? '[]' : '');
+    }
+  }
+  await ensureSafetyConfig();
+  await ensureWorkerPolicy();
+  await logMemory('AI Maestro project initialized.');
+  console.log('AI Maestro initialization complete.');
+}
+
+export async function status() {
+  console.log('AI Maestro Status:');
+  doctorLine(await pathExists(CONFIG.memoryPath) ? 'OK' : 'AVISO', 'Memory path', CONFIG.memoryPath);
+  doctorLine(await pathExists(CONFIG.maestroPath) ? 'OK' : 'AVISO', 'Maestro path', CONFIG.maestroPath);
+  const tasks = await getTasks();
+  console.log('- Tasks: ' + tasks.length);
+  console.log('- Task status counts: ' + JSON.stringify(countTasksByStatus(tasks)));
+  const recentRuns = await getRecentRuns(10);
+  const withWarnings = recentRuns.filter(run => (run.warnings || []).length > 0);
+  console.log('- Recent runs with warnings: ' + withWarnings.length + '/' + recentRuns.length);
+  for (const run of withWarnings.slice(-5)) {
+    console.log('  - Task #' + run.taskId + ' [' + run.status + ']: ' + (run.warnings || []).join('; '));
+  }
+}
+
+export async function plan(request) {
+  let briefContent = '';
+  try {
+    briefContent = await fs.readFile(path.join(CONFIG.memoryPath, 'BRIEF.md'), 'utf-8');
+  } catch (error) {
+    briefContent = '';
+  }
+  const result = await generatePlan(request, briefContent);
+  if (result.archive && result.archive.archived.length > 0) {
+    await logMemory('Archived active tasks before plan: ' + result.archive.archived.length + ' to ' + result.archive.archivePath);
+  }
+  await logMemory('Planned for request: "' + request + '"');
+  await memoryDecision('Generated structured task plan for "' + request + '" without premium AI.');
+  console.log('Plan generated in .maestro/PLAN.md and .maestro/TASKS.json');
+}
+
+export const WORKER_POLICY_CONTENT = [
+  '# AI Maestro Worker Policy',
+  '',
+  '- Do not modify `.env` files.',
+  '- Do not deploy.',
+  '- Do not delete files.',
+  '- Do not modify the normal Codex home.',
+  '- Do not modify `C:\\AI-Router`.',
+  '- Record files changed in the final response.',
+  '- Run relevant validations.',
+  '- Log meaningful work to `.memory/` when possible.',
+  '',
+  '## Windows/PowerShell',
+  '',
+  '- Use `Get-ChildItem -Force` instead of `ls -la`.',
+  '- Use `Get-Content file | Select-Object -Last N` instead of `tail`.',
+  '- Do not use Bash heredoc (`cat > file << EOF`).',
+  '- To write large files, prefer a temporary Node script instead of complex PowerShell quoting.',
+  '- Always validate a changed file before concluding the task.',
+  '',
+  '## Encoding (UTF-8)',
+  '',
+  '- Do not use `Set-Content -Encoding UTF8` or `Out-File -Encoding UTF8`: Windows PowerShell 5.1 writes a UTF-8 BOM with that flag, which has broken JSON/Markdown parsing in this project before.',
+  "- Do not compose file content with a PowerShell here-string (`@'...'@` or `@\"...\"@`) when it contains accented characters, backticks, or `${}` template syntax: PowerShell's quoting has repeatedly mangled these into mojibake or broken syntax.",
+  '- Prefer writing content with a temporary Node script using UTF-8 explicitly, e.g. `node -e "require(\'fs\').writeFileSync(path, content, { encoding: \'utf8\' })"`.',
+  '- If PowerShell must write the file directly, use `[System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding($false)))` (no BOM), never `-Encoding UTF8`.',
+  '- After writing, verify with `Get-Content -Raw` or a byte-level check that no BOM (`EF BB BF`) was introduced and that accented words were not replaced with `?` or a Unicode replacement character.',
+  ''
+].join('\n');
+
+export async function ensureWorkerPolicy(maestroPath = CONFIG.maestroPath) {
+  await fs.mkdir(maestroPath, { recursive: true });
+  const policyPath = path.join(maestroPath, 'worker-policy.md');
+  if (!(await pathExists(policyPath))) {
+    await writeUtf8TextFile(policyPath, WORKER_POLICY_CONTENT);
+  }
+  return policyPath;
+}
+
+export async function checkpoint() {
+  await generateCheckpoint();
+  await logMemory('Project checkpoint generated.');
+  console.log('Checkpoint generated in .maestro/CHECKPOINT.md');
+}
+
+export async function handoff() {
+  await execFile('node', [path.join(CONFIG.memoryPath, 'tools', 'cli.mjs'), 'handoff']);
+  try {
+    const memoryHandoff = await fs.readFile(path.join(CONFIG.memoryPath, 'handoff.md'), 'utf-8');
+    await writeUtf8TextFile(path.join(CONFIG.maestroPath, 'HANDOFF.md'), memoryHandoff);
+  } catch (error) {
+    await writeUtf8TextFile(path.join(CONFIG.maestroPath, 'HANDOFF.md'), '# AI Maestro Handoff\n\nNo memory handoff available.\n');
+  }
+  console.log('Handoff report generated in .memory/handoff.md');
+}
+
+export function shouldRunWorkerValidation({ validateWorker, hasPriorValidation }) {
+  return !!validateWorker || !hasPriorValidation;
+}
+
+async function hasAnyPriorValidation() {
+  if (await hasRecentCodexTest()) {
+    return true;
+  }
+  const validated = await readValidatedCodexStrategy();
+  if (validated) {
+    return true;
+  }
+  const compare = await readCodexCompare();
+  return !!(compare && compare.winner);
+}
+
+export async function startCommand(request, options = {}) {
+  if (!request) {
+    console.log('Usage: maestro start "<pedido>" [--validate-worker]');
+    return;
+  }
+  await init();
+  await doctor();
+  await codexHomeCommand();
+  const hasPriorValidation = await hasAnyPriorValidation();
+  if (shouldRunWorkerValidation({ validateWorker: options.validateWorker, hasPriorValidation })) {
+    await codexTestInvocation();
+  } else {
+    console.log('Codex validation already on record; skipping smoke test. Use --validate-worker to force it.');
+  }
+  await plan(request);
+  await generateCheckpoint();
+  console.log('Next commands:');
+  console.log('- maestro task list');
+  console.log('- maestro run-one');
+  console.log('- maestro run-all --limit 3');
+  console.log('- maestro handoff');
+}
+
+export async function continueCommand() {
+  let brief = '';
+  let handoffText = '';
+  try { brief = await fs.readFile(path.join(CONFIG.memoryPath, 'BRIEF.md'), 'utf-8'); } catch (error) { brief = 'No .memory/BRIEF.md found.'; }
+  try { handoffText = await fs.readFile(path.join(CONFIG.maestroPath, 'HANDOFF.md'), 'utf-8'); } catch (error) {
+    try { handoffText = await fs.readFile(path.join(CONFIG.memoryPath, 'handoff.md'), 'utf-8'); } catch (inner) { handoffText = 'No handoff found.'; }
+  }
+  const tasks = await getTasks();
+  const pending = sortRunnableTasks(tasks.filter(task => task.status === 'pending'));
+  console.log('Brief:\n' + brief.split(/\r?\n/).slice(0, 8).join('\n'));
+  console.log('\nHandoff:\n' + handoffText.split(/\r?\n/).slice(0, 12).join('\n'));
+  console.log('\nPending tasks: ' + pending.length);
+  pending.slice(0, 10).forEach(task => console.log('- #' + task.id + ' [' + task.priority + '] ' + (task.title || task.description)));
+  console.log('\nSuggested next command: ' + (pending.length ? 'maestro run-one' : 'maestro plan "..."'));
+}
+
+async function readJsonlSafe(filePath) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    return null;
+  }
+}
+
+export async function schemaCheck() {
+  const checks = [];
+
+  const tasks = await readJsonSafe(path.join(CONFIG.maestroPath, 'TASKS.json'), []);
+  const taskErrors = tasks.flatMap(task => validateTask(task).errors.map(error => '#' + task.id + ': ' + error));
+  checks.push({ name: '.maestro/TASKS.json', ok: taskErrors.length === 0, errors: taskErrors });
+
+  const runs = await readJsonlSafe(path.join(CONFIG.maestroPath, 'RUNS.jsonl'));
+  const runErrors = runs === null ? ['file could not be parsed'] : runs.flatMap(entry => validateRunEntry(entry).errors);
+  checks.push({ name: '.maestro/RUNS.jsonl', ok: runErrors.length === 0, errors: runErrors });
+
+  const summary = await readJsonSafe(path.join(CONFIG.maestroPath, 'usage-summary.json'), null);
+  const summaryErrors = summary ? validateUsageSummary(summary).errors : [];
+  checks.push({ name: '.maestro/usage-summary.json', ok: summaryErrors.length === 0, errors: summaryErrors });
+
+  const ok = checks.every(check => check.ok);
+  for (const check of checks) {
+    console.log((check.ok ? 'OK' : 'FAIL') + ': ' + check.name + (check.errors && check.errors.length ? ' -> ' + check.errors.join('; ') : ''));
+  }
+  if (!ok) {
+    process.exitCode = 1;
+  }
+  return { ok, checks };
+}
+
+export async function releaseCheck() {
+  const checks = [];
+  async function runCheck(name, command, args) {
+    const result = command.endsWith('.cmd')
+      ? await execCmdFile(command, args, { quiet: true })
+      : await execFileRaw(command, args, { quiet: true });
+    checks.push({ name, command: command + ' ' + args.join(' '), exitCode: result.code, ok: result.code === 0, stdout: summarizeText(result.stdout, 500), stderr: summarizeText(result.stderr, 500) });
+    return result.code === 0;
+  }
+  await runCheck('syntax bin', 'node', ['--check', 'bin/maestro.mjs']);
+  await runCheck('syntax config', 'node', ['--check', 'src/config.mjs']);
+  await runCheck('syntax commands', 'node', ['--check', 'src/commands.mjs']);
+  await runCheck('syntax codex-home', 'node', ['--check', 'src/codex-home.mjs']);
+  await runCheck('syntax debug', 'node', ['--check', 'src/debug.mjs']);
+  await runCheck('syntax safety', 'node', ['--check', 'src/safety.mjs']);
+  await runCheck('syntax planner', 'node', ['--check', 'src/planner.mjs']);
+  await runCheck('syntax usage', 'node', ['--check', 'src/usage.mjs']);
+  await runCheck('syntax schema', 'node', ['--check', 'src/schema.mjs']);
+  await runCheck('syntax lock', 'node', ['--check', 'src/lock.mjs']);
+  await runCheck('syntax engines', 'node', ['--check', 'src/engines/registry.mjs']);
+  await runCheck('syntax codex-diagnostics', 'node', ['--check', 'src/codex-diagnostics.mjs']);
+  await runCheck('syntax codex-home-inspect', 'node', ['--check', 'src/codex-home-inspect.mjs']);
+  await runCheck('syntax task-commands', 'node', ['--check', 'src/task-commands.mjs']);
+  await runCheck('syntax session-commands', 'node', ['--check', 'src/session-commands.mjs']);
+  await runCheck('syntax smart-planner', 'node', ['--check', 'src/smart-planner.mjs']);
+  await runCheck('syntax run-diagnostics', 'node', ['--check', 'src/run-diagnostics.mjs']);
+  await runCheck('syntax workspace-diff', 'node', ['--check', 'src/workspace-diff.mjs']);
+  await runCheck('syntax ui server', 'node', ['--check', 'src/ui/server.mjs']);
+  await runCheck('syntax ui state', 'node', ['--check', 'src/ui/state.mjs']);
+  await runCheck('syntax ui commands', 'node', ['--check', 'src/ui/commands.mjs']);
+  await runCheck('syntax ui events', 'node', ['--check', 'src/ui/events.mjs']);
+  if (process.platform === 'win32') {
+    await runCheck('npm test', 'cmd.exe', ['/d', '/s', '/c', 'npm test']);
+  } else {
+    await runCheck('npm test', 'npm', ['test']);
+  }
+  await runCheck('doctor', 'node', ['bin/maestro.mjs', 'doctor']);
+  await runCheck('codex-test', 'node', ['bin/maestro.mjs', 'codex-test']);
+  await runCheck('stats', 'node', ['bin/maestro.mjs', 'stats']);
+  await runCheck('checkpoint', 'node', ['bin/maestro.mjs', 'checkpoint']);
+  await runCheck('handoff', 'node', ['bin/maestro.mjs', 'handoff']);
+  await runCheck('ui endpoints', 'node', ['--input-type=module', '-e', "const { startUiServer } = await import('./src/ui/server.mjs'); const ui = await startUiServer({ port: 0 }); try { const stateRes = await fetch(ui.url + '/api/state'); if (!stateRes.ok) throw new Error('/api/state status ' + stateRes.status); const handoffRes = await fetch(ui.url + '/api/handoff'); if (!handoffRes.ok) throw new Error('/api/handoff status ' + handoffRes.status); const state = await stateRes.json(); const handoff = await handoffRes.json(); if (!Array.isArray(state.timeline)) throw new Error('timeline missing'); if (typeof handoff.content !== 'string') throw new Error('handoff content missing'); if (!state.statusMap || !state.statusMap.completed_with_warnings) throw new Error('statusMap missing completed_with_warnings'); console.log('ui endpoints ok'); } finally { await new Promise(resolve => ui.server.close(resolve)); }"]);
+  await runCheck('help shown for no args', 'node', ['bin/maestro.mjs']);
+  const helpProbe = checks[checks.length - 1];
+  checks[checks.length - 1] = { ...helpProbe, ok: helpProbe.ok && /AI-MAESTRO/.test(helpProbe.stdout) };
+  const plannerProbe = buildSmartTasks('os botões não funcionam, termine de fazer o app, botões funcionando, e acesso aos arquivos pelo painel');
+  checks.push({
+    name: 'planner kind smart-heuristic-v1',
+    ok: plannerProbe.plannerKind === 'smart-heuristic-v1' && plannerProbe.kind === 'ui-app'
+  });
+  checks.push({
+    name: 'schema accepts completed_with_warnings',
+    ok: validateTask({ id: 1, description: 'x', status: 'completed_with_warnings' }).ok === true
+  });
+  const platformGuidance = getPlatformGuidance('win32');
+  checks.push({
+    name: 'platform guidance forbids Unix commands on Windows',
+    ok: platformGuidance.includes('ls -la') && platformGuidance.includes('Get-ChildItem')
+  });
+  checks.push({
+    name: 'windowsShellCommandMismatch detector',
+    ok: detectWindowsShellMismatch("tail : O termo 'tail' não é reconhecido") === true
+      && detectWindowsShellMismatch('tudo certo, nenhum erro aqui') === false
+  });
+  const syntaxProbeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'maestro-release-check-'));
+  try {
+    const badJsPath = path.join(syntaxProbeDir, 'bad.js');
+    await fs.writeFile(badJsPath, 'function( { const x = ;');
+    const badJsonPath = path.join(syntaxProbeDir, 'bad.json');
+    await fs.writeFile(badJsonPath, '{ invalid json');
+    const badJs = await validateChangedFile(badJsPath);
+    const badJson = await validateChangedFile(badJsonPath);
+    checks.push({ name: 'validateChangedFile rejects broken JS/JSON', ok: badJs.ok === false && badJson.ok === false });
+  } finally {
+    await fs.rm(syntaxProbeDir, { recursive: true, force: true });
+  }
+  checks.push({
+    name: 'isAnalysisOnlyTask classifies mapear/analisar tasks',
+    ok: isAnalysisOnlyTask({ title: 'Mapear stack e estrutura real do app', description: '', acceptance: [] }) === true
+      && isAnalysisOnlyTask({ title: 'Corrigir interacoes dos botoes', description: '', acceptance: [] }) === false
+  });
+  const workspaceProbeDir = await fs.mkdtemp(path.join(os.tmpdir(), 'maestro-workspace-check-'));
+  try {
+    await fs.writeFile(path.join(workspaceProbeDir, 'app.js'), 'const x = 1;');
+    const before = await snapshotWorkspace(workspaceProbeDir);
+    await fs.writeFile(path.join(workspaceProbeDir, 'app.js'), 'const x = 2;');
+    const after = await snapshotWorkspace(workspaceProbeDir);
+    const diff = diffWorkspace(before, after);
+    checks.push({ name: 'workspace diff detects a changed file', ok: diff.changedFiles.includes('app.js') });
+  } finally {
+    await fs.rm(workspaceProbeDir, { recursive: true, force: true });
+  }
+  checks.push({
+    name: 'decideTaskStatus fails analysis-only code changes and deletions',
+    ok: decideTaskStatus({ exitCode: 0, analysisTaskChangedCode: true, deletedOutOfScope: false, syntaxValidationFailed: false, unsupportedToolCall: false, suspectedFalsePositive: false, windowsShellCommandMismatch: false }) === 'failed'
+      && decideTaskStatus({ exitCode: 0, analysisTaskChangedCode: false, deletedOutOfScope: true, syntaxValidationFailed: false, unsupportedToolCall: false, suspectedFalsePositive: false, windowsShellCommandMismatch: false }) === 'failed'
+  });
+  const schemaResult = await schemaCheck();
+  checks.push({ name: 'schema-check', ok: schemaResult.ok });
+  const readmeOk = await pathExists('README.md');
+  const uiAssetsOk = await Promise.all([
+    pathExists(path.join('src', 'ui', 'public', 'index.html')),
+    pathExists(path.join('src', 'ui', 'public', 'app.js')),
+    pathExists(path.join('src', 'ui', 'public', 'style.css'))
+  ]);
+  const packageJson = JSON.parse(await fs.readFile('package.json', 'utf-8'));
+  const packageOk = !!(packageJson.bin && packageJson.bin.maestro);
+  const helpText = 'help start continue codex-home codex-test codex-compare task run-one run-task run-all checkpoint handoff stats release-check schema-check task-pending ui --quiet --validate-worker';
+  checks.push({ name: 'README exists', ok: readmeOk });
+  checks.push({ name: 'ui assets exist', ok: uiAssetsOk.every(Boolean) });
+  checks.push({ name: 'package bin.maestro', ok: packageOk });
+  checks.push({ name: 'command list expected', ok: ['run-task', 'task-pending', 'ui'].every(item => helpText.includes(item)), commands: helpText });
+  const ok = checks.every(check => check.ok);
+  const report = '# AI Maestro Release Check\n\n- Date: ' + new Date().toISOString() + '\n- Status: ' + (ok ? 'PASS' : 'FAIL') + '\n\n## Checks\n\n' + checks.map(check => '- ' + (check.ok ? 'OK' : 'FAIL') + ' ' + check.name + (check.exitCode !== undefined ? ' exit=' + check.exitCode : '')).join('\n') + '\n';
+  await writeUtf8TextFile(path.join(CONFIG.maestroPath, 'RELEASE_CHECK.md'), report);
+  console.log(report);
+  if (!ok) process.exitCode = 1;
+}
+
+export async function doctor() {
+  console.log('Running AI Maestro doctor...');
+  doctorLine('OK', 'Project root', process.cwd());
+  doctorLine('OK', 'CODEX_HOME', CONFIG.codexHome);
+  doctorLine('OK', 'Profile', CONFIG.codexProfile);
+  doctorLine('OK', 'Configured strategy', CONFIG.codexStrategy);
+  doctorLine('OK', 'Current strategy', await resolveRunCodexStrategy());
+  doctorLine('OK', 'Configured invocation', CONFIG.codexInvocation);
+  doctorLine('OK', 'Current invocation', await resolveCodexInvocationMode());
+  if (process.env.NINEROUTER_API_KEY) {
+    doctorLine('OK', 'NINEROUTER_API_KEY', 'set');
+  } else if (process.env.MAESTRO_ALLOW_LOCAL_TEST_KEY === '1') {
+    doctorLine('AVISO', 'NINEROUTER_API_KEY', 'missing; using explicit MAESTRO_ALLOW_LOCAL_TEST_KEY=1 fallback local-test');
+  } else {
+    doctorLine('ERRO', 'NINEROUTER_API_KEY', 'missing; set it or explicitly set MAESTRO_ALLOW_LOCAL_TEST_KEY=1 for local diagnostics');
+  }
+  const compare = await readCodexCompare();
+  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;
+  }
+  doctorLine(compare ? 'OK' : 'AVISO', 'Last codex-compare', compare ? 'winner=' + (compare.winner || 'none') : 'none');
+  if (compare && compare.tests) {
+    doctorLine('OK', 'codex-compare tests', compare.tests.map(test => test.id + '=' + (test.ok ? 'ok' : 'fail')).join(', '));
+    doctorLine(compare.winner ? 'OK' : 'ERRO', 'codex-compare recommendation', compare.recommendation || 'none');
+  }
+  doctorLine(homeDiff ? 'OK' : 'AVISO', 'Last codex-home-diff', homeDiff ? 'normalFiles=' + homeDiff.normal.files.length + ', maestroFiles=' + homeDiff.maestro.files.length : 'none');
+  doctorLine(repair ? 'OK' : 'AVISO', 'Last codex-home-repair', repair ? 'backup=' + repair.backupPath : 'none');
+  doctorLine(probe ? (probe.winner ? 'OK' : 'AVISO') : 'AVISO', 'Last codex-home-probe', probe ? ('winner=' + (probe.winner ? probe.winner.candidate : 'none') + ', tested=' + probe.candidatesTested) : 'none');
+  const currentInvocation = await resolveCodexInvocationMode();
+  if (currentInvocation.includes('normal-home') || currentInvocation === 'codex-cmd') {
+    doctorLine('ERRO', 'Normal-home in use', 'O worker está usando o CODEX_HOME normal (configuração Desktop compartilhada). Isso só acontece com MAESTRO_CODEX_INVOCATION explícito; o modo auto usa somente o home isolado.');
+  }
+  const validated = await readValidatedCodexStrategy();
+  doctorLine(validated ? 'OK' : 'AVISO', 'Last validated strategy', validated ? validated.strategy : 'none');
+  const home = await ensureCodexHome();
+  doctorLine('OK', 'Config file', home.configPath);
+  if (home.sanitized) {
+    doctorLine('AVISO', 'Isolated config sanitized', 'configuração Desktop contaminada foi salva em backup e reescrita minimal (backup: ' + home.backupPath + ')');
+  }
+  doctorLine(home.analysis && home.analysis.contaminated ? 'ERRO' : 'OK', 'Isolated config clean of Desktop/normal-home refs', !(home.analysis && home.analysis.contaminated));
+  doctorLine('OK', 'Legacy workspace-permissions config (unused)', getLegacyWorkspacePermissionsConfigPath());
+  doctorLine('OK', 'default_permissions used', home.checks.usesDefaultPermissions + ' (não usado pelo Maestro: conflita com sandbox_mode, que é o mecanismo adotado; o antigo workspace-permissions.config.toml nunca era carregado)');
+  doctorLine(home.checks.mixesDefaultPermissionsAndSandboxMode ? 'ERRO' : 'OK', 'default_permissions + sandbox_mode mix', home.checks.mixesDefaultPermissionsAndSandboxMode);
+  try {
+    const runtime = await getEffectiveCodexRuntime();
+    console.log('Effective Codex runtime (Hotfix A.2):');
+    for (const line of formatEffectiveRuntimeLines(runtime)) {
+      console.log(line);
+    }
+    doctorLine(runtime.isolatedHome ? 'OK' : 'ERRO', 'Effective CODEX_HOME isolated', runtime.isolatedHome);
+    doctorLine(runtime.referencesNormalCodexHome ? 'ERRO' : 'OK', 'Effective config references normal .codex', runtime.referencesNormalCodexHome);
+    doctorLine(runtime.desktopPluginsEnabled || runtime.mcpServersConfigured ? 'ERRO' : 'OK', 'Desktop plugins/MCP in effective config', runtime.desktopPluginsEnabled || runtime.mcpServersConfigured);
+    doctorLine(runtime.provider === '9router' ? 'OK' : 'ERRO', 'Effective provider', runtime.provider);
+    doctorLine(runtime.windowsSandboxElevated ? 'ERRO' : 'OK', 'Windows sandbox "elevated" in effective config', runtime.windowsSandboxElevated);
+  } catch (error) {
+    doctorLine('ERRO', 'Effective Codex runtime', error.message);
+  }
+  try {
+    const invocation = await resolveCodexInvocation();
+    doctorLine('OK', 'Codex command', invocation.command + ' (' + invocation.source + ')');
+    doctorLine('OK', 'Codex args prefix', invocation.argsPrefix.join(' '));
+    const selectedInvocation = await resolveCodexInvocationForMode(await resolveCodexInvocationMode());
+    doctorLine('OK', 'Selected Codex command', selectedInvocation.command + ' (' + selectedInvocation.source + ')');
+    doctorLine('OK', 'Selected Codex args prefix', selectedInvocation.argsPrefix.join(' '));
+  } catch (error) {
+    doctorLine('ERRO', 'Codex command', error.message);
+  }
+  try {
+    const help = await getCodexHelpMatrix();
+    doctorLine(help.hasGlobalAskForApproval ? 'OK' : 'AVISO', '--ask-for-approval global', help.hasGlobalAskForApproval);
+    doctorLine(help.hasExecSandbox ? 'OK' : 'ERRO', '--sandbox exec', help.hasExecSandbox);
+    doctorLine(help.hasExecShortConfig ? 'OK' : 'AVISO', '-c exec', help.hasExecShortConfig);
+    doctorLine(help.hasExecIgnoreRules ? 'OK' : 'AVISO', '--ignore-rules exec', help.hasExecIgnoreRules);
+    doctorLine(help.hasDangerousBypass ? 'OK' : 'AVISO', 'danger bypass flag present', help.hasDangerousBypass);
+    const output = help.globalHelp.stdout + help.globalHelp.stderr + help.execHelp.stdout + help.execHelp.stderr;
+    doctorLine(/api\.openai\.com/i.test(output) ? 'ERRO' : 'OK', 'api.openai.com check', /api\.openai\.com/i.test(output) ? 'detected' : 'not detected');
+  } catch (error) {
+    doctorLine('ERRO', 'Codex help', error.message);
+  }
+}
+
+export async function stats() {
+  console.log(JSON.stringify(await getUsageSummary(), null, 2));
+}
+
+export async function providerHealthCommand(options = {}) {
+  const snapshot = await getFullHealthSnapshot();
+  if (options.json) {
+    console.log(JSON.stringify(snapshot, null, 2));
+  } else {
+    console.log('Provider health:');
+    const targetIds = Object.keys(snapshot.targets || {}).sort();
+    if (snapshot.diagnostics && snapshot.diagnostics.degraded) {
+      doctorLine('AVISO', 'Provider health snapshot', 'could not be read; assuming safe empty state (' + snapshot.diagnostics.degradedReason + ')');
+    }
+    if (targetIds.length === 0) {
+      console.log('- No provider health data yet; all targets are assumed CLOSED.');
+    } else {
+      for (const targetId of targetIds) {
+        const entry = snapshot.targets[targetId];
+        const cooldown = entry.cooldownUntil ? ' cooldownUntil=' + entry.cooldownUntil : '';
+        const retryAfter = entry.observedRetryAfterMs != null ? ' observedRetryAfterMs=' + entry.observedRetryAfterMs : '';
+        console.log('- ' + targetId + ': ' + entry.state + ' failures=' + entry.consecutiveFailures + ' successes=' + entry.consecutiveSuccesses + cooldown + retryAfter);
+      }
+    }
+    console.log('Consistency: eventually consistent; same-process Node lock only; no cross-process lock.');
+  }
+  if (snapshot.diagnostics && snapshot.diagnostics.degradedReason === 'io-error') {
+    process.exitCode = 1;
+  }
+  return snapshot;
+}

package/src/shell.mjs

@@ -0,0 +1,93 @@
+import { spawn } from 'child_process';
+import { redactCredentials } from './format.mjs';
+
+export async function exec(command, args = [], options = {}) {
+  return execFile(command, args, { ...options, shell: false });
+}
+
+export async function execFile(command, args = [], options = {}) {
+  const result = await spawnCollect(command, args, options);
+  if (result.code !== 0) {
+    const error = new Error('Command failed with exit code ' + result.code + '. Stderr: ' + result.stderr);
+    error.code = result.code;
+    error.stdout = result.stdout;
+    error.stderr = result.stderr;
+    throw error;
+  }
+  return result;
+}
+
+export async function execFileRaw(command, args = [], options = {}) {
+  return spawnCollect(command, args, options);
+}
+
+function quoteCmdArg(value) {
+  const text = String(value);
+  const singleLine = text.replace(/\r?\n/g, '\\n');
+  return '"' + singleLine.replace(/(["^&|<>()%])/g, '^$1') + '"';
+}
+
+export async function execCmdFile(commandPath, args = [], options = {}) {
+  const innerCommand = [quoteCmdArg(commandPath), ...args.map(quoteCmdArg)].join(' ');
+  const commandLine = '"' + innerCommand + '"';
+  return execFileRaw('cmd.exe', ['/d', '/s', '/c', commandLine], {
+    ...options,
+    windowsVerbatimArguments: true
+  });
+}
+
+async function spawnCollect(command, args = [], options = {}) {
+  return new Promise((resolve, reject) => {
+    const timeoutMs = options.timeoutMs || options.timeout_ms || 0;
+    const child = spawn(command, args, {
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      ...options
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      const text = data.toString();
+      stdout += text;
+      if (!options.quiet) {
+        process.stdout.write(redactCredentials(text));
+      }
+    });
+
+    child.stderr.on('data', (data) => {
+      const text = data.toString();
+      stderr += text;
+      if (!options.quiet) {
+        process.stderr.write(redactCredentials(text));
+      }
+    });
+
+    let timedOut = false;
+    let timer = null;
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill('SIGTERM');
+      }, timeoutMs);
+    }
+
+    child.on('close', (code, signal) => {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      resolve({
+        code: timedOut ? 124 : code,
+        signal,
+        timedOut,
+        stdout,
+        stderr: timedOut ? stderr + '\nTimed out after ' + timeoutMs + 'ms.' : stderr
+      });
+    });
+
+    child.on('error', (err) => {
+      reject(err);
+    });
+  });
+}