ai-maestro 1.0.0

package/src/task-commands.mjs

@@ -0,0 +1,1182 @@
+import { generateCheckpoint } from './checkpoint.mjs';
+import { addTask, archiveTasks, getNextTask, getTaskById, getTasks, sortRunnableTasks, updateTaskStatus } from './tasks.mjs';
+import { executeTaskWithSafety } from './safety.mjs';
+import { recordUsage } from './usage.mjs';
+import { logRun, getLatestRunForTask, getRecentRuns } from './runner.mjs';
+import { logMemory } from './memory-log.mjs';
+import { formatPreview, redactCredentials, summarizeText } from './format.mjs';
+import { getEngine } from './engines/registry.mjs';
+import { detectUnsupportedToolCall, buildRunDiagnostics, detectWindowsShellMismatch, validateChangedFiles, isAnalysisOnlyTask, verifyDeliverableEvidence } from './run-diagnostics.mjs';
+import { snapshotWorkspace, diffWorkspace } from './workspace-diff.mjs';
+import { evaluateTaskRun, countRunsForTask } from './orchestration/runtime-gate.mjs';
+import { classifyFailure } from './orchestration/failure-classifier.mjs';
+import { loadBudget, getHostValidationPolicy } from './orchestration/budget-manager.mjs';
+import { runHostValidation, summarizeHostValidation } from './orchestration/host-validation.mjs';
+import { buildOrchestrationSummary, getLatestOrchestrationForTask } from './orchestration/orchestration-trail.mjs';
+import { execFileRaw } from './shell.mjs';
+import { acquireOrRecover, inspectTaskLock, releaseTaskLock } from './lock.mjs';
+
+export function getPlatformGuidance(platform = process.platform) {
+  if (platform === 'win32') {
+    return [
+      'Você está em Windows PowerShell.',
+      'Não use comandos Unix/Linux quando estiver rodando via PowerShell.',
+      '',
+      'Não use:',
+      '- ls -la',
+      '- tail -50',
+      "- cat > arquivo << EOF",
+      '- rm -rf',
+      '- grep',
+      '- sed -i',
+      '- heredoc bash',
+      '',
+      'Use equivalentes PowerShell:',
+      '- Get-ChildItem -Force',
+      '- Get-Content arquivo | Select-Object -Last 50',
+      '- Remove-Item -Recurse -Force somente se explicitamente permitido',
+      '- Select-String',
+      '- scripts Node para escrita complexa',
+      '',
+      'Para escrever arquivos com conteudo grande, JS/HTML/CSS, ou qualquer texto com acentos:',
+      'Prefira criar um script Node temporario, por exemplo:',
+      'node -e "const fs=require(\'fs\'); fs.writeFileSync(\'static/app.js\', content, { encoding: \'utf8\' })"',
+      'Ou crie um arquivo .tmp-write.mjs temporario, execute, depois remova.',
+      'Evite PowerShell com quoting complexo para JS multilinha.',
+      '',
+      'Nunca use Set-Content -Encoding UTF8 ou Out-File -Encoding UTF8: no Windows PowerShell 5.1 isso grava um BOM UTF-8 no inicio do arquivo, o que ja quebrou parsing de JSON/Markdown neste projeto.',
+      "Nunca componha conteudo com here-string PowerShell (@' ... '@) quando houver acentos, crases ou ${}: isso ja corrompeu arquivos neste projeto (mojibake, template literals quebrados).",
+      'Se precisar escrever diretamente via PowerShell, use: [System.IO.File]::WriteAllText($path, $content, (New-Object System.Text.UTF8Encoding($false))) — sem BOM.'
+    ].join('\n');
+  }
+  return [
+    'You are running on a Unix-like shell (' + platform + ').',
+    'Prefer POSIX-compatible commands and avoid Windows-only syntax.'
+  ].join('\n');
+}
+
+// Codex's internal plan/update_plan tool only accepts these step statuses.
+// Maestro's richer internal statuses (blocked, failed, needs_human,
+// archived, completed_with_warnings) must NEVER cross that boundary as-is:
+// Codex rejects them with "unknown variant `blocked`, expected one of
+// `pending`, `in_progress`, `completed`". Map to a supported variant
+// instead — or don't call the tool.
+export const CODEX_PLAN_TOOL_STATUSES = ['pending', 'in_progress', 'completed'];
+
+export function mapStatusToCodexPlanVariant(status) {
+  switch (status) {
+    case 'pending':
+    case 'in_progress':
+    case 'completed':
+      return status;
+    case 'completed_with_warnings':
+      return 'completed';
+    default:
+      // blocked / failed / needs_human / archived / anything unknown: the
+      // step is not done and not actively running — 'pending' is the only
+      // honest supported variant. The real Maestro status stays in
+      // TASKS.json / RUNS.jsonl untouched.
+      return 'pending';
+  }
+}
+
+export function buildWorkerPrompt(task) {
+  return [
+    'You are a worker agent for AI Maestro.',
+    '',
+    'Read these files first:',
+    '- .memory/BRIEF.md',
+    '- .maestro/PLAN.md',
+    '- .maestro/TASKS.json',
+    '- .maestro/worker-policy.md',
+    '',
+    'Your task is:',
+    task.description,
+    '',
+    'Use the available tools. Do not ask for user input.',
+    'Follow .maestro/worker-policy.md.',
+    'Work from project root: ' + process.cwd(),
+    '',
+    'Mandatory rules for this run:',
+    '- Do not use apply_patch. This environment may not support that tool.',
+    '- To edit files, use PowerShell, Node scripts, or other real commands actually available here.',
+    '- If a command fails, do not claim the change was made.',
+    '- Before concluding, verify changed files with: git diff --stat, git diff, Test-Path, Get-Content, or an equivalent command.',
+    '- In your final response, separate clearly:',
+    '  1. Files actually changed',
+    '  2. Commands executed',
+    '  3. Commands that failed',
+    '  4. Validations performed',
+    '  5. Pending items',
+    '- If this task is analysis-only, do not change any code.',
+    '- If you need to change .maestro/TASKS.json, prefer the Maestro CLI commands (maestro task ...) when they exist instead of editing the file directly.',
+    '- If you use your internal plan/update_plan tool, its step statuses only accept: pending, in_progress, completed. Never pass Maestro statuses such as blocked, failed or needs_human to that tool; report those situations in prose in your final answer instead.',
+    '- Never state that a file was updated without having verified it.',
+    '',
+    getPlatformGuidance()
+  ].join('\n');
+}
+
+export function countTasksByStatus(tasks) {
+  return tasks.reduce((acc, task) => {
+    acc[task.status || 'unknown'] = (acc[task.status || 'unknown'] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+function printSafe(line = '') {
+  console.log(redactCredentials(line));
+}
+
+function printLines(lines) {
+  for (const line of lines) {
+    printSafe(line);
+  }
+}
+
+function shouldSuggestForce(gate) {
+  return gate && gate.forceAllowed === true;
+}
+
+export function formatForceAction(gate, taskId) {
+  if (shouldSuggestForce(gate)) {
+    return 'Acao: revise o risco e use "maestro run-task ' + taskId + ' --force" se aprovado.';
+  }
+  return 'Acao: corrija a causa do bloqueio; --force nao e permitido para este resultado.';
+}
+
+function countChangedFiles(changedFiles = [], createdFiles = [], deletedFiles = []) {
+  return changedFiles.length + createdFiles.length + deletedFiles.length;
+}
+
+function formatChangedSummary(count) {
+  if (count === 0) return '✓ Nenhum arquivo alterado';
+  return count === 1 ? '✓ 1 arquivo alterado' : '✓ ' + count + ' arquivos alterados';
+}
+
+function validationSummary({ syntaxValidationFailed, hostValidationFallback }) {
+  if (syntaxValidationFailed) return 'x Falha na validacao de sintaxe';
+  if (hostValidationFallback && hostValidationFallback.used) {
+    return hostValidationFallback.result === 'passed'
+      ? '✓ Validacao do host passou'
+      : 'x Falha na validacao do host';
+  }
+  return '✓ Validacao de sintaxe OK';
+}
+
+function printVerboseSections({ result, diffText, runId, debug }) {
+  if (!result) return;
+  if (debug) {
+    printSafe('');
+    printSafe('--- stdout completo ---');
+    printSafe(result.stdout || '');
+    printSafe('--- stderr completo ---');
+    printSafe(result.stderr || '');
+    if (diffText) {
+      printSafe('--- diff completo ---');
+      printSafe(diffText);
+    }
+    return;
+  }
+  printSafe('');
+  printSafe('--- stdout preview ---');
+  printSafe(formatPreview(result.stdout || '', { maxLines: 100, maxBytes: 8192, runId }).text || '(vazio)');
+  printSafe('--- stderr preview ---');
+  printSafe(formatPreview(result.stderr || '', { maxLines: 100, maxBytes: 8192, runId }).text || '(vazio)');
+  if (diffText) {
+    printSafe('--- diff preview ---');
+    printSafe(formatPreview(diffText, { maxLines: 50, maxBytes: 4096, runId }).text);
+  }
+}
+
+async function collectDiffText() {
+  try {
+    const result = await execFileRaw('git', ['diff', '--no-ext-diff'], { quiet: true });
+    return (result.stdout || '') + (result.stderr ? '\n' + result.stderr : '');
+  } catch (error) {
+    return '';
+  }
+}
+
+const TERMINAL_RUN_STATUSES = new Set(['completed', 'completed_with_warnings', 'failed', 'blocked', 'needs_human']);
+const CRASH_RECONCILIATION_WARNING = 'reconciled task stranded in_progress after unexpected process termination';
+let accountingChain = Promise.resolve();
+
+function delayMs(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function withTransientJsonRetry(fn) {
+  let lastError;
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      return await fn();
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      lastError = error;
+      await delayMs(attempt + 1);
+    }
+  }
+  throw lastError;
+}
+
+export async function withAccountingLock(fn) {
+  const previous = accountingChain;
+  let release;
+  const current = new Promise(resolve => {
+    release = resolve;
+  });
+  accountingChain = previous.then(() => current, () => current);
+  await previous.catch(() => {});
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (accountingChain === current) {
+      accountingChain = Promise.resolve();
+    }
+  }
+}
+
+function isTerminalRunStatus(status) {
+  return TERMINAL_RUN_STATUSES.has(status);
+}
+
+function parseTimeMs(value) {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function latestRunCoversInProgressEntry(latestOwnRun, task) {
+  if (!latestOwnRun || !isTerminalRunStatus(latestOwnRun.status)) {
+    return false;
+  }
+  const runEnd = parseTimeMs(latestOwnRun.endTime);
+  const taskUpdated = parseTimeMs(task.updatedAt);
+  return runEnd !== null && taskUpdated !== null && runEnd >= taskUpdated;
+}
+
+function needsCrashStatusReconcile(task, latestOwnRun) {
+  return task.status === 'in_progress' && !latestRunCoversInProgressEntry(latestOwnRun, task);
+}
+
+async function hasReconciliationRun(reconcileKey) {
+  const runs = await getRecentRuns(Infinity);
+  return runs.some(run => run && run.reconciledCrash === true && run.reconcileKey === reconcileKey);
+}
+
+async function getRecoveryWorkspaceState() {
+  try {
+    const snapshot = await snapshotWorkspace(process.cwd());
+    if (snapshot.kind === 'git' && Array.isArray(snapshot.lines) && snapshot.lines.length > 0) {
+      return 'dirty-partial';
+    }
+  } catch (error) {
+    return 'clean';
+  }
+  return 'clean';
+}
+
+function recoveryResult(task, fields = {}) {
+  return {
+    taskId: Number(task.id),
+    taskStatus: task.status,
+    action: fields.action || 'noop',
+    lockOutcome: fields.lockOutcome || null,
+    lockCorrupted: fields.lockCorrupted === true,
+    recoveredFromPid: fields.recoveredFromPid ?? null,
+    activeLock: fields.activeLock || null,
+    reconcileKey: fields.reconcileKey || null,
+    run: fields.run || null
+  };
+}
+
+function printRecoverySummary(summary) {
+  printSafe('Crash recovery: ' + summary.reconciled + ' reconciled, ' + summary.releasedLocks + ' orphan locks released, ' + summary.skipped + ' skipped.');
+  for (const result of summary.results) {
+    const suffix = result.lockCorrupted ? ' lockCorrupted=true' : '';
+    printSafe('- #' + result.taskId + ' ' + result.action + (result.lockOutcome ? ' (' + result.lockOutcome + ')' : '') + suffix);
+  }
+}
+
+async function appendCrashReconciliationRun({ task, reconcileKey, recoveredFromPid, lockCorrupted }) {
+  const startTime = new Date().toISOString();
+  const workspaceState = await getRecoveryWorkspaceState();
+  const run = await logRun({
+    taskId: Number(task.id),
+    status: 'needs_human',
+    startTime,
+    endTime: new Date().toISOString(),
+    strategy: 'none',
+    exitCode: 2,
+    reconciledCrash: true,
+    reconcileKey,
+    recoveredFromPid: recoveredFromPid ?? null,
+    crashWindow: 'in_progress_no_terminal_run',
+    failureCategory: 'process_terminated_unexpectedly',
+    infrastructureFailure: true,
+    workspaceState,
+    warnings: [CRASH_RECONCILIATION_WARNING],
+    ...(lockCorrupted ? { lockCorrupted: true } : {})
+  });
+  await logMemory('Task #' + task.id + ' reconciled from crash (in_progress -> needs_human).');
+  return run;
+}
+
+export async function reconcileCrashedTasks(options = {}) {
+  const taskIds = options.taskIds ? new Set(options.taskIds.map(item => String(item))) : null;
+  const dryRun = options.dryRun === true;
+  const includeLockOnly = options.includeLockOnly !== false;
+  const tasks = await getTasks();
+  const summary = {
+    dryRun,
+    scanned: 0,
+    reconciled: 0,
+    releasedLocks: 0,
+    skipped: 0,
+    results: []
+  };
+
+  for (const task of tasks) {
+    if (taskIds && !taskIds.has(String(task.id))) {
+      continue;
+    }
+
+    const inspection = await inspectTaskLock(task.id);
+    if (task.status !== 'in_progress' && (!includeLockOnly || !inspection.exists)) {
+      continue;
+    }
+
+    summary.scanned += 1;
+    const latestOwnRun = await getLatestRunForTask(task.id);
+    const needsStatusReconcile = needsCrashStatusReconcile(task, latestOwnRun);
+    const reconcileKey = String(task.id) + ':' + String(task.updatedAt || '');
+    const recoveredFromPid = inspection.lock && Number.isInteger(inspection.lock.pid) ? inspection.lock.pid : null;
+
+    if (dryRun) {
+      const action = inspection.heldByActive
+        ? 'skip_held_by_active'
+        : needsStatusReconcile
+          ? 'would_reconcile_to_needs_human'
+          : inspection.exists
+            ? 'would_release_orphan_lock_only'
+            : 'noop';
+      if (action.startsWith('skip') || action === 'noop') summary.skipped += 1;
+      summary.results.push(recoveryResult(task, {
+        action,
+        lockOutcome: inspection.heldByActive ? 'held_by_active' : inspection.exists ? 'inspect_only' : 'no_lock',
+        lockCorrupted: inspection.lockCorrupted,
+        recoveredFromPid,
+        activeLock: inspection.activeLock,
+        reconcileKey
+      }));
+      continue;
+    }
+
+    if (inspection.lockCorrupted) {
+      if (!needsStatusReconcile) {
+        summary.skipped += 1;
+        summary.results.push(recoveryResult(task, { action: 'skip_lock_corrupted_no_status_reconcile', lockOutcome: 'lock_corrupted', lockCorrupted: true, reconcileKey }));
+        continue;
+      }
+      if (await hasReconciliationRun(reconcileKey)) {
+        summary.skipped += 1;
+        summary.results.push(recoveryResult(task, { action: 'noop_already_reconciled', lockOutcome: 'lock_corrupted', lockCorrupted: true, reconcileKey }));
+        continue;
+      }
+      await updateTaskStatus(task.id, 'needs_human');
+      const run = await appendCrashReconciliationRun({ task, reconcileKey, recoveredFromPid: null, lockCorrupted: true });
+      summary.reconciled += 1;
+      summary.results.push(recoveryResult(task, { action: 'reconciled_to_needs_human', lockOutcome: 'lock_corrupted', lockCorrupted: true, reconcileKey, run }));
+      continue;
+    }
+
+    const shouldProbeLock = needsStatusReconcile || (includeLockOnly && inspection.exists);
+    if (!shouldProbeLock) {
+      summary.skipped += 1;
+      summary.results.push(recoveryResult(task, { action: 'noop', reconcileKey }));
+      continue;
+    }
+
+    const taskLock = await acquireOrRecover(task.id, { command: 'recover task ' + task.id });
+    if (taskLock.outcome === 'held_by_active') {
+      summary.skipped += 1;
+      summary.results.push(recoveryResult(task, {
+        action: 'skip_held_by_active',
+        lockOutcome: 'held_by_active',
+        activeLock: taskLock.activeLock || null,
+        reconcileKey
+      }));
+      continue;
+    }
+
+    const lockHandle = taskLock.lockHandle;
+    try {
+      if (!needsStatusReconcile) {
+        summary.releasedLocks += 1;
+        summary.results.push(recoveryResult(task, {
+          action: 'released_orphan_lock_only',
+          lockOutcome: taskLock.outcome,
+          recoveredFromPid,
+          reconcileKey
+        }));
+        continue;
+      }
+
+      if (await hasReconciliationRun(reconcileKey)) {
+        summary.skipped += 1;
+        summary.results.push(recoveryResult(task, {
+          action: 'noop_already_reconciled',
+          lockOutcome: taskLock.outcome,
+          recoveredFromPid,
+          reconcileKey
+        }));
+        continue;
+      }
+
+      await updateTaskStatus(task.id, 'needs_human');
+      const run = await appendCrashReconciliationRun({ task, reconcileKey, recoveredFromPid, lockCorrupted: false });
+      summary.reconciled += 1;
+      summary.results.push(recoveryResult(task, {
+        action: 'reconciled_to_needs_human',
+        lockOutcome: taskLock.outcome,
+        recoveredFromPid,
+        reconcileKey,
+        run
+      }));
+    } finally {
+      if (lockHandle) {
+        await releaseTaskLock(lockHandle);
+      }
+    }
+  }
+
+  if (!options.suppressOutput) {
+    printRecoverySummary(summary);
+  }
+  return summary;
+}
+
+async function blockTaskBySafety(task, safety, startTime, options = {}) {
+  const findings = safety.findings || [];
+  const run = await withAccountingLock(async () => {
+    await updateTaskStatus(task.id, 'blocked');
+    const blockedRun = await logRun({
+      taskId: Number(task.id),
+      status: 'blocked',
+      blockedBySafety: true,
+      startTime,
+      endTime: new Date().toISOString(),
+      strategy: 'none',
+      exitCode: 2,
+      safetyFindings: findings,
+      warnings: [],
+      unsupportedToolCall: false,
+      suspectedFalsePositive: false,
+      windowsShellCommandMismatch: false,
+      syntaxValidation: [],
+      syntaxValidationFailed: false,
+      workspaceChanged: false,
+      changedFiles: [],
+      createdFiles: [],
+      deletedFiles: [],
+      analysisTaskChangedCode: false,
+      outOfScopeChanges: []
+    });
+    await recordUsage({
+      command: 'run-task',
+      strategy: 'none',
+      promptChars: ((task.title || '') + '\n' + (task.description || '')).length,
+      estimatedOutputTokens: 0,
+      exitCode: 2,
+      blockedBySafety: true,
+      safetyFindings: findings
+    });
+    return blockedRun;
+  });
+  await logMemory('Task #' + task.id + ' blocked by safety guard: ' + findings.join('; '));
+  if (!options.suppressOutput) {
+    printLines([
+      'Task #' + task.id + ' - ' + (task.title || task.description || ''),
+      'Engine: none',
+      'Status final: blocked',
+      'Erro acionavel: safety guard bloqueou a tarefa.',
+      'Padroes detectados: ' + findings.join('; '),
+      'RunId: ' + run.runId,
+      'Log: ' + run.logPath,
+      'Relatorio: ' + run.reportPath
+    ]);
+  }
+  return run;
+}
+
+// Flattens a runtime-gate.mjs result into the flat field set both
+// RUNS.jsonl (logRun) and usage.jsonl (recordUsage) expect (Phase 6 of
+// v0.5.1: runtimeGate, runtimeDecision, selectedManager, selectedEngine,
+// preflightDecision, budgetDecision, policyDecision, forced).
+function gateMetadataFields(gate) {
+  return {
+    runtimeGate: {
+      decision: gate.decision,
+      blockCategory: gate.blockCategory,
+      taskKind: gate.taskClassification.taskKind,
+      complexity: gate.taskClassification.complexity,
+      risk: gate.taskClassification.risk,
+      reason: gate.reason,
+      fallback: gate.fallback
+    },
+    runtimeDecision: gate.decision,
+    blockedReasonCategory: gate.blockCategory || null,
+    selectedManager: gate.selectedManager ? gate.selectedManager.sector : null,
+    selectedEngine: gate.selectedEngine ? gate.selectedEngine.id : null,
+    preflightDecision: gate.preflight ? gate.preflight.decision : null,
+    budgetDecision: gate.budget && gate.budget.evaluation ? gate.budget.evaluation.allowed : null,
+    policyDecision: gate.policy ? gate.policy.ok : null,
+    forced: gate.forced === true
+  };
+}
+
+// The runtime gate stopped the task before any worker was called
+// (BLOCK/NEEDS_HUMAN/DELEGATE/FALLBACK). Mirrors blockTaskBySafety's shape
+// so RUNS.jsonl/usage.jsonl stay consistent, but carries the gate's own
+// reasoning instead of a safety-guard finding list. Per project rule,
+// --force can only ever turn a NEEDS_HUMAN gate result into EXECUTE — by
+// the time this function runs, that has already happened inside
+// evaluateTaskRun(), so a gate that reaches here truly could not run.
+async function handleGateNonExecute(task, gate, startTime, options = {}) {
+  const newStatus = gate.decision === 'NEEDS_HUMAN' ? 'needs_human' : 'blocked';
+  const gateFields = gateMetadataFields(gate);
+  const run = await withAccountingLock(async () => {
+    await updateTaskStatus(task.id, newStatus);
+    const gateRun = await logRun({
+      taskId: Number(task.id),
+      status: newStatus,
+      blockedBySafety: false,
+      blockedByGate: true,
+      startTime,
+      endTime: new Date().toISOString(),
+      strategy: 'none',
+      exitCode: 2,
+      warnings: gate.reason,
+      unsupportedToolCall: false,
+      suspectedFalsePositive: false,
+      windowsShellCommandMismatch: false,
+      syntaxValidation: [],
+      syntaxValidationFailed: false,
+      workspaceChanged: false,
+      changedFiles: [],
+      createdFiles: [],
+      deletedFiles: [],
+      analysisTaskChangedCode: false,
+      outOfScopeChanges: [],
+      ...gateFields
+    });
+    await recordUsage({
+      command: 'run-task',
+      strategy: 'none',
+      promptChars: ((task.title || '') + '\n' + (task.description || '')).length,
+      estimatedOutputTokens: 0,
+      exitCode: 2,
+      blockedBySafety: false,
+      blockedByGate: true,
+      ...gateFields
+    });
+    return gateRun;
+  });
+  await logMemory('Task #' + task.id + ' stopped by runtime gate: ' + gate.decision + ' (' + gate.reason.join('; ') + ').');
+  if (!options.suppressOutput) {
+    const lines = [
+      'Task #' + task.id + ' - ' + (task.title || task.description || ''),
+      'Engine: ' + (gate.selectedEngine ? gate.selectedEngine.id || 'none' : 'none'),
+      'Status final: ' + newStatus,
+      'Erro acionavel: runtime gate ' + gate.decision + '.',
+      ...gate.reason.map(reason => '- ' + reason),
+      'RunId: ' + run.runId,
+      'Log: ' + run.logPath,
+      'Relatorio: ' + run.reportPath
+    ];
+    if (newStatus === 'needs_human') {
+      lines.push(formatForceAction(gate, task.id));
+    }
+    if (options.debug) {
+      lines.push('');
+      lines.push(JSON.stringify(gate, null, 2));
+    }
+    printLines(lines);
+  }
+  return run;
+}
+
+// Tasks whose legitimate success doesn't touch anything the workspace diff
+// can see: analysis-only tasks (not supposed to touch code), memory-engine
+// tasks (real output lives inside .memory/, excluded from the diff by
+// design), and review/audit tasks (not supposed to touch anything either).
+export function isNoChangeExpectedTask(task, analysisOnly = isAnalysisOnlyTask(task)) {
+  return analysisOnly || task.engine === 'memory' || /revis[aã]o|\breview\b/i.test(task.title || '');
+}
+
+export function decideTaskStatus({
+  exitCode,
+  analysisTaskChangedCode,
+  deletedOutOfScope,
+  syntaxValidationFailed,
+  unsupportedToolCall,
+  suspectedFalsePositive,
+  windowsShellCommandMismatch,
+  explicitWorkerFailure = false,
+  workspaceChanged = false,
+  hostValidationFallbackPassed = false,
+  infrastructureFailure = false,
+  deliverableVerification = null
+}) {
+  if (exitCode !== 0 && !(infrastructureFailure && hostValidationFallbackPassed)) {
+    return 'failed';
+  }
+  if (analysisTaskChangedCode) {
+    return 'failed';
+  }
+  if (deletedOutOfScope) {
+    return 'failed';
+  }
+  if (syntaxValidationFailed) {
+    return 'failed';
+  }
+  if (deliverableVerification && deliverableVerification.required !== false) {
+    if (deliverableVerification.outcome === 'rejected' || deliverableVerification.outcome === 'inconclusive') {
+      return 'failed';
+    }
+    if (deliverableVerification.outcome === 'blocked') {
+      return 'blocked';
+    }
+    if (deliverableVerification.outcome === 'needs_human') {
+      return 'needs_human';
+    }
+  }
+  // The worker's own process can exit 0 while its final answer explicitly
+  // says it could not finish the task -- that can never read as `completed`.
+  // Partial, verified progress (some files really changed) downgrades this
+  // to a warning instead of a hard failure; no verified change at all means
+  // nothing usable was delivered, so it's a real failure.
+  if (explicitWorkerFailure) {
+    return workspaceChanged ? 'completed_with_warnings' : 'failed';
+  }
+  if (hostValidationFallbackPassed) {
+    return 'completed_with_warnings';
+  }
+  if (unsupportedToolCall || suspectedFalsePositive || windowsShellCommandMismatch) {
+    return 'completed_with_warnings';
+  }
+  return 'completed';
+}
+
+function inferHostValidationInputs({ output, projectRoot, changedFiles = [], createdFiles = [], policy }) {
+  const text = String(output || '');
+  const inputs = [];
+  const push = commandId => {
+    if (!inputs.some(item => item.commandId === commandId) && policy.hostValidationCommands.includes(commandId)) {
+      inputs.push({ commandId, projectRoot, policy });
+    }
+  };
+  if (/npm\s+run\s+check/i.test(text)) {
+    push('npm-run-check');
+  }
+  if (/npm(?:\.cmd)?\s+(?:test|[^\r\n]*\btest\b)/i.test(text)) {
+    push('npm-test');
+  }
+  if (/node(?:\.exe)?\s+--check/i.test(text) && policy.hostValidationCommands.includes('node-check')) {
+    for (const file of [...changedFiles, ...createdFiles].filter(item => /\.(mjs|js)$/i.test(item))) {
+      inputs.push({ commandId: 'node-check', projectRoot, file, policy });
+    }
+  }
+  return inputs;
+}
+
+async function runAllowedHostValidationFallback({ output, projectRoot, changedFiles, createdFiles, failure }) {
+  const budget = await loadBudget();
+  const policy = getHostValidationPolicy(budget);
+  if (!policy.allowHostValidationFallback || failure.category !== 'nested_sandbox_process_failure') {
+    return { used: false, commands: [], result: 'not_run', results: [] };
+  }
+  const inputs = inferHostValidationInputs({ output, projectRoot, changedFiles, createdFiles, policy });
+  if (!inputs.length) {
+    return { used: false, commands: [], result: 'not_applicable', results: [] };
+  }
+  const results = [];
+  for (const input of inputs) {
+    results.push(await runHostValidation(input));
+  }
+  return { ...summarizeHostValidation(results), results };
+}
+
+function printRunSummary({ task, engineName, status, warnings, changedFiles, createdFiles, deletedFiles, result, syntaxValidationFailed, hostValidationFallback, run, verbose, debug, diffText }) {
+  const workerLine = result.code === 0 ? '✓ Worker finalizado' : 'x Worker falhou (codigo ' + result.code + ')';
+  printLines([
+    'Task #' + task.id + ' - ' + (task.title || task.description || ''),
+    'Engine: ' + engineName,
+    'Status: running',
+    workerLine,
+    formatChangedSummary(countChangedFiles(changedFiles, createdFiles, deletedFiles)),
+    validationSummary({ syntaxValidationFailed, hostValidationFallback })
+  ]);
+  if (warnings.length) {
+    printSafe('');
+    printSafe('Warnings acionaveis:');
+    for (const warning of warnings) {
+      printSafe('- ' + warning);
+    }
+  }
+  printLines([
+    '',
+    'Status final: ' + status,
+    'RunId: ' + run.runId,
+    'Log: ' + run.logPath,
+    'Relatorio: ' + run.reportPath
+  ]);
+  if (verbose || debug) {
+    printVerboseSections({ result, diffText, runId: run.runId, debug });
+  }
+}
+
+export async function runTask(id, options = {}) {
+  let task = await withTransientJsonRetry(() => getTaskById(id));
+  if (!task) {
+    console.log('Task #' + id + ' not found.');
+    return;
+  }
+  await withTransientJsonRetry(() => reconcileCrashedTasks({ taskIds: [id], dryRun: options.dryRun === true, suppressOutput: options.suppressOutput === true, includeLockOnly: false }));
+  task = await withTransientJsonRetry(() => getTaskById(id));
+  if (task.status === 'completed' || task.status === 'completed_with_warnings' || task.status === 'failed') {
+    console.log('Task #' + id + ' already ' + task.status + '. Use maestro retry ' + id + ' first.');
+    return;
+  }
+  if (task.status === 'blocked') {
+    console.log('Task #' + id + ' is blocked. Use maestro task pending ' + id + ' to reopen it.');
+    return;
+  }
+  if (task.status === 'needs_human' && !options.force) {
+    printSafe('Task #' + id + ' needs a human decision before it can run. Use maestro task pending ' + id + ' to reopen it after review.');
+    return;
+  }
+  if (task.status === 'archived') {
+    console.log('Task #' + id + ' is archived and cannot be run.');
+    return;
+  }
+
+  const runsSoFar = await withTransientJsonRetry(() => countRunsForTask(id));
+  const gate = await withTransientJsonRetry(() => evaluateTaskRun({
+    task,
+    projectRoot: process.cwd(),
+    mode: options.dryRun ? 'dry-run' : 'real',
+    force: !!options.force,
+    runsSoFar
+  }));
+
+  if (options.dryRun) {
+    printSafe(JSON.stringify(gate, null, 2));
+    printSafe('\n(dry-run: no engine, worker, or model was actually called)');
+    return;
+  }
+
+  if (gate.decision !== 'EXECUTE') {
+    const run = await handleGateNonExecute(task, gate, new Date().toISOString(), options);
+    return { taskId: Number(id), status: gate.decision === 'NEEDS_HUMAN' ? 'needs_human' : 'blocked', run };
+  }
+
+  const taskLock = await acquireOrRecover(id, { command: 'run-task ' + id });
+  if (taskLock.outcome === 'held_by_active') {
+    if (!options.suppressOutput) {
+      printLines([
+        'Task #' + task.id + ' - ' + (task.title || task.description || ''),
+        'Status final: blocked',
+        'Erro acionavel: task lock held by active owner.',
+        'PID ativo: ' + (taskLock.activeLock && taskLock.activeLock.pid != null ? taskLock.activeLock.pid : 'unknown')
+      ]);
+    }
+    return {
+      taskId: Number(id),
+      status: 'blocked',
+      lockOutcome: 'held_by_active',
+      activeLock: taskLock.activeLock || null,
+      run: null
+    };
+  }
+
+  const lockHandle = taskLock.lockHandle;
+  const lockOutcome = taskLock.outcome;
+  const lockRecovery = lockOutcome === 'recovered_and_acquired'
+    ? { recovered: true, recoveredFromPid: taskLock.activeLock && taskLock.activeLock.pid != null ? taskLock.activeLock.pid : null }
+    : null;
+
+  try {
+    const prompt = buildWorkerPrompt(task);
+    const startTime = new Date().toISOString();
+    const engine = options.engine || getEngine((gate.selectedEngine && gate.selectedEngine.id) || task.engine);
+    const analysisOnly = isAnalysisOnlyTask(task);
+    const workspaceBefore = await snapshotWorkspace(process.cwd());
+    let blockedRun = null;
+    const safetyResult = await executeTaskWithSafety(
+      task,
+      async () => {
+        await withAccountingLock(() => updateTaskStatus(id, 'in_progress'));
+        return engine.run(prompt, { quiet: true });
+      },
+      async ({ safety }) => {
+        blockedRun = await blockTaskBySafety(task, safety, startTime, options);
+      }
+    );
+    if (safetyResult.blocked) {
+      return { taskId: Number(id), status: 'blocked', run: blockedRun, lockOutcome };
+    }
+    const result = safetyResult.result;
+    const output = (result.stdout || '') + '\n' + (result.stderr || '');
+    const workspaceAfter = await snapshotWorkspace(process.cwd());
+    const { workspaceChanged, changedFiles, createdFiles, deletedFiles, outOfScopeChanges } = diffWorkspace(
+      workspaceBefore,
+      workspaceAfter,
+      { scopeFiles: task.files || [] }
+    );
+    const analysisTaskChangedCode = analysisOnly && (changedFiles.length > 0 || createdFiles.length > 0 || deletedFiles.length > 0);
+    const deletedOutOfScope = deletedFiles.length > 0;
+    const unsupportedToolCall = detectUnsupportedToolCall(output);
+    const windowsShellCommandMismatch = detectWindowsShellMismatch(output);
+    const { syntaxValidation, syntaxValidationFailed } = await validateChangedFiles([...changedFiles, ...createdFiles]);
+    // A memory/documentation task's real output normally lives inside .memory/,
+    // which diffWorkspace excludes by design, and a review/audit task isn't
+    // expected to touch any file either — don't treat either as a lie.
+    const noChangeExpected = isNoChangeExpectedTask(task, analysisOnly);
+    const workerFailure = classifyFailure({ exitCode: result.code, stdout: result.stdout, stderr: result.stderr });
+    const diagnostics = buildRunDiagnostics({ output, unsupportedToolCall, workspaceChanged, noChangeExpected });
+    if (windowsShellCommandMismatch) {
+      diagnostics.warnings.push('comando incompatível com PowerShell foi usado pelo worker');
+    }
+    if (analysisTaskChangedCode) {
+      diagnostics.warnings.push('analysis-only task changed code');
+    }
+    if (deletedOutOfScope) {
+      diagnostics.warnings.push('worker deleted files');
+    }
+    if (syntaxValidationFailed) {
+      for (const entry of syntaxValidation.filter(item => item.ok === false)) {
+        diagnostics.warnings.push('syntax validation failed: ' + entry.path);
+      }
+    }
+    if (workerFailure.category === 'nested_sandbox_process_failure') {
+      diagnostics.warnings.push('worker validation blocked by nested sandbox');
+    }
+    if (lockRecovery) {
+      diagnostics.warnings.push('recovered orphaned task lock before execution');
+    }
+
+    const hostValidationFallback = await runAllowedHostValidationFallback({
+      output,
+      projectRoot: process.cwd(),
+      changedFiles,
+      createdFiles,
+      failure: workerFailure
+    });
+    if (hostValidationFallback.used && hostValidationFallback.result === 'passed') {
+      diagnostics.warnings.push('worker validation blocked by nested sandbox; host validation passed');
+    } else if (hostValidationFallback.used && hostValidationFallback.result === 'failed') {
+      diagnostics.warnings.push('worker validation blocked by nested sandbox; host validation failed');
+    }
+
+    const deliverableVerification = await verifyDeliverableEvidence({
+      task,
+      projectRoot: process.cwd(),
+      changedFiles,
+      createdFiles,
+      deletedFiles,
+      outOfScopeChanges,
+      syntaxValidation,
+      hostValidationFallback,
+      noChangeExpected
+    });
+    for (const warning of deliverableVerification.warnings || []) {
+      diagnostics.warnings.push('deliverable verification warning: ' + warning);
+    }
+    for (const failure of deliverableVerification.failures || []) {
+      diagnostics.warnings.push('deliverable verification failed: ' + failure);
+    }
+    for (const missing of deliverableVerification.missingEvidence || []) {
+      diagnostics.warnings.push('deliverable verification missing evidence: ' + missing);
+    }
+
+    const status = decideTaskStatus({
+      exitCode: result.code,
+      analysisTaskChangedCode,
+      deletedOutOfScope,
+      syntaxValidationFailed,
+      unsupportedToolCall,
+      suspectedFalsePositive: diagnostics.suspectedFalsePositive,
+      windowsShellCommandMismatch,
+      explicitWorkerFailure: diagnostics.explicitWorkerFailure,
+      workspaceChanged,
+      hostValidationFallbackPassed: hostValidationFallback.used && hostValidationFallback.result === 'passed',
+      infrastructureFailure: workerFailure.infrastructureFailure === true,
+      deliverableVerification
+    });
+
+    const diffText = await collectDiffText();
+    await withAccountingLock(() => updateTaskStatus(id, status));
+    const gateFields = gateMetadataFields(gate);
+    const run = await withAccountingLock(() => logRun({
+      taskId: Number(id),
+      status,
+      startTime,
+      endTime: new Date().toISOString(),
+      strategy: result.strategy,
+      exitCode: result.code,
+      signal: result.signal || null,
+      timedOut: result.timedOut === true,
+      stdout: summarizeText(result.stdout),
+      stderr: summarizeText(result.stderr),
+      fullStdout: result.stdout || '',
+      fullStderr: result.stderr || '',
+      diffText,
+      warnings: diagnostics.warnings,
+      workerValidation: {
+        attempted: true,
+        completed: workerFailure.category !== 'nested_sandbox_process_failure',
+        failureCategory: workerFailure.category === 'nested_sandbox_process_failure' ? workerFailure.category : null,
+        infrastructureFailure: workerFailure.infrastructureFailure === true
+      },
+      hostValidationFallback: {
+        used: hostValidationFallback.used,
+        commands: hostValidationFallback.commands || [],
+        result: hostValidationFallback.result,
+        metadata: hostValidationFallback.metadata || []
+      },
+      failureCategory: workerFailure.category,
+      infrastructureFailure: workerFailure.infrastructureFailure === true,
+      unsupportedToolCall: diagnostics.unsupportedToolCall,
+      suspectedFalsePositive: diagnostics.suspectedFalsePositive,
+      explicitWorkerFailure: diagnostics.explicitWorkerFailure,
+      explicitFailureEvidence: diagnostics.explicitFailureEvidence,
+      windowsShellCommandMismatch,
+      syntaxValidation,
+      syntaxValidationFailed,
+      deliverableVerification,
+      workspaceChanged,
+      changedFiles,
+      createdFiles,
+      deletedFiles,
+      analysisTaskChangedCode,
+      outOfScopeChanges,
+      lockOutcome,
+      ...(lockRecovery ? { lockRecovery } : {}),
+      ...gateFields
+    }));
+    await withAccountingLock(() => recordUsage({
+      command: 'run-task',
+      strategy: result.strategy,
+      prompt,
+      output,
+      exitCode: result.code,
+      warnings: diagnostics.warnings,
+      workerValidation: {
+        attempted: true,
+        completed: workerFailure.category !== 'nested_sandbox_process_failure',
+        failureCategory: workerFailure.category === 'nested_sandbox_process_failure' ? workerFailure.category : null,
+        infrastructureFailure: workerFailure.infrastructureFailure === true
+      },
+      hostValidationFallback: {
+        used: hostValidationFallback.used,
+        commands: hostValidationFallback.commands || [],
+        result: hostValidationFallback.result
+      },
+      failureCategory: workerFailure.category,
+      infrastructureFailure: workerFailure.infrastructureFailure === true,
+      unsupportedToolCall: diagnostics.unsupportedToolCall,
+      suspectedFalsePositive: diagnostics.suspectedFalsePositive,
+      explicitWorkerFailure: diagnostics.explicitWorkerFailure,
+      windowsShellCommandMismatch,
+      syntaxValidationFailed,
+      deliverableVerification,
+      analysisTaskChangedCode,
+      deletedFiles,
+      ...gateFields
+    }));
+    await logMemory('Task #' + id + ' finished as ' + status + ' (exit code ' + result.code + ') using engine ' + engine.name + ' (strategy ' + result.strategy + ')' + (diagnostics.warnings.length ? '; warnings: ' + diagnostics.warnings.join('; ') : '') + '.');
+
+    if (!options.suppressOutput) {
+      printRunSummary({
+        task,
+        engineName: engine.name,
+        status,
+        warnings: diagnostics.warnings,
+        changedFiles,
+        createdFiles,
+        deletedFiles,
+        result,
+        syntaxValidationFailed,
+        hostValidationFallback,
+        run,
+        verbose: !!options.verbose,
+        debug: !!options.debug,
+        diffText
+      });
+    }
+    return {
+      taskId: Number(id),
+      status,
+      warnings: diagnostics.warnings,
+      changedFiles,
+      createdFiles,
+      deletedFiles,
+      run,
+      result,
+      diagnostics,
+      output,
+      lockOutcome,
+      ...(lockRecovery ? { lockRecovery } : {})
+    };
+  } finally {
+    await releaseTaskLock(lockHandle);
+  }
+}
+
+export async function runOne(options = {}) {
+  const tasks = await getTasks();
+  const task = getNextTask(tasks);
+  if (!task) {
+    console.log('No pending tasks found.');
+    return;
+  }
+  await runTask(task.id, options);
+}
+
+export async function runAll(options = {}) {
+  const limitArgIndex = process.argv.indexOf('--limit');
+  const limit = limitArgIndex >= 0 ? parseInt(process.argv[limitArgIndex + 1], 10) : Infinity;
+  await reconcileCrashedTasks({ dryRun: options.dryRun === true, suppressOutput: options.suppressOutput === true });
+  const tasks = await getTasks();
+  let count = 0;
+  const summary = { completed: 0, completed_with_warnings: 0, failed: 0, not_started: 0 };
+  let lastReportPath = null;
+  const runnableTasks = sortRunnableTasks(tasks.filter(item => item.status === 'pending')).slice(0, limit);
+  if (options.dryRun) {
+    printSafe('Dry-run: tasks pending que seriam executadas:');
+    if (runnableTasks.length === 0) {
+      printSafe('- nenhuma');
+    }
+    for (const task of runnableTasks) {
+      printSafe('- #' + task.id + ' [' + (task.priority || 'medium') + '] ' + (task.title || task.description || ''));
+    }
+  }
+  for (const task of runnableTasks) {
+    const result = await runTask(task.id, { ...options, suppressOutput: true });
+    count++;
+    const refreshed = await getTaskById(task.id);
+    const status = refreshed ? refreshed.status : (result && result.status) || 'not_started';
+    if (status === 'completed') summary.completed++;
+    else if (status === 'completed_with_warnings') summary.completed_with_warnings++;
+    else if (status === 'failed') summary.failed++;
+    else summary.not_started++;
+    if (result && result.run && result.run.reportPath) {
+      lastReportPath = result.run.reportPath;
+    }
+    const icon = status === 'completed' ? '✓' : status === 'completed_with_warnings' ? '⚠' : status === 'failed' ? 'x' : '-';
+    printSafe(icon + ' #' + task.id + ' ' + status);
+    if (refreshed && (refreshed.status === 'failed' || refreshed.status === 'blocked' || refreshed.status === 'needs_human')) {
+      break;
+    }
+  }
+  if (!options.dryRun) {
+    await generateCheckpoint();
+    await recordUsage({ command: 'run-all', promptChars: 0, estimatedOutputTokens: 0, exitCode: 0, tasksRun: count });
+  }
+  printSafe('Resumo: ' + summary.completed + ' concluidas, ' + summary.completed_with_warnings + ' com avisos, ' + summary.failed + ' falhou, ' + summary.not_started + ' nao iniciada');
+  if (lastReportPath) {
+    printSafe('Relatorio: ' + lastReportPath);
+  }
+}
+
+export async function retry(id, options = {}) {
+  await updateTaskStatus(id, 'pending');
+  await runTask(id, options);
+}
+
+export async function taskCommand(args) {
+  if (args[0] === 'list') {
+    const tasks = await getTasks();
+    const counts = countTasksByStatus(tasks);
+    console.log('Tasks: ' + JSON.stringify(counts));
+    for (const task of sortRunnableTasks(tasks)) {
+      const date = String(task.updatedAt || task.createdAt || '').slice(0, 10);
+      console.log('- #' + task.id + ' [' + task.status + '] [' + (task.priority || 'medium') + '] [' + (task.engine || 'codex9') + '] ' + date + ' ' + (task.title || task.description));
+    }
+    const next = getNextTask(tasks);
+    console.log('Next: ' + (next ? '#' + next.id + ' ' + (next.title || next.description) : 'none'));
+    return;
+  }
+  if (args[0] === 'next') {
+    const next = getNextTask(await getTasks());
+    console.log(next ? JSON.stringify(next, null, 2) : 'No pending task.');
+    return;
+  }
+  if (args[0] === 'archive-failed') {
+    const result = await archiveTasks(task => task.status === 'failed', 'archive-failed');
+    await logMemory('Archived failed tasks: ' + result.archived.length + (result.archivePath ? ' to ' + result.archivePath : ''));
+    console.log('Archived failed tasks: ' + result.archived.length + (result.archivePath ? ' -> ' + result.archivePath : ''));
+    return;
+  }
+  if (args[0] === 'archive-completed') {
+    const result = await archiveTasks(task => task.status === 'completed', 'archive-completed');
+    await logMemory('Archived completed tasks: ' + result.archived.length + (result.archivePath ? ' to ' + result.archivePath : ''));
+    console.log('Archived completed tasks: ' + result.archived.length + (result.archivePath ? ' -> ' + result.archivePath : ''));
+    return;
+  }
+  if (args[0] === 'clean-test') {
+    const testPattern = /(MAESTRO_TESTE\.md|MAESTRO_WORKER_TEST\.md|MAESTRO_CODEX_TEST\.md|WORKING_|PROBE_)/i;
+    const result = await archiveTasks(task => testPattern.test((task.title || '') + ' ' + (task.description || '')), 'clean-test');
+    await logMemory('Archived test tasks: ' + result.archived.length + (result.archivePath ? ' to ' + result.archivePath : ''));
+    console.log('Archived test tasks: ' + result.archived.length + (result.archivePath ? ' -> ' + result.archivePath : ''));
+    return;
+  }
+  if (args[0] === 'show' && args[1]) {
+    const task = await getTaskById(args[1]);
+    if (!task) {
+      console.log('Task not found.');
+      return;
+    }
+    const lastRun = await getLatestRunForTask(args[1]);
+    const lastOrchestration = buildOrchestrationSummary(await getLatestOrchestrationForTask(args[1]));
+    console.log(JSON.stringify({
+      ...task,
+      lastRun: lastRun ? {
+        status: lastRun.status,
+        exitCode: lastRun.exitCode,
+        warnings: lastRun.warnings || [],
+        changedFiles: lastRun.changedFiles || [],
+        createdFiles: lastRun.createdFiles || [],
+        deletedFiles: lastRun.deletedFiles || [],
+        analysisTaskChangedCode: !!lastRun.analysisTaskChangedCode,
+        syntaxValidationFailed: !!lastRun.syntaxValidationFailed,
+        endTime: lastRun.endTime
+      } : null,
+      lastOrchestration
+    }, null, 2));
+    return;
+  }
+  if (args[0] === 'add' && args[1]) {
+    const task = await addTask(args.slice(1).join(' '));
+    console.log('Task #' + task.id + ' added.');
+    return;
+  }
+  if (args[0] === 'complete' && args[1]) {
+    await updateTaskStatus(args[1], 'completed');
+    console.log('Task #' + args[1] + ' marked completed.');
+    return;
+  }
+  if (args[0] === 'fail' && args[1]) {
+    await updateTaskStatus(args[1], 'failed');
+    console.log('Task #' + args[1] + ' marked failed.');
+    return;
+  }
+  if (args[0] === 'pending' && args[1]) {
+    await updateTaskStatus(args[1], 'pending');
+    console.log('Task #' + args[1] + ' reopened as pending. Aviso: a próxima execução pode bloquear de novo pelo safety guard.');
+    return;
+  }
+  console.log('Usage: maestro task list | next | show <id> | add "<description>" | complete <id> | fail <id> | pending <id> | archive-failed | archive-completed | clean-test');
+}