ai-maestro 1.0.0

package/src/orchestration/self-hosting-canary.mjs

@@ -0,0 +1,231 @@
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { execFileRaw } from '../shell.mjs';
+import { redactObject, redactCredentials } from '../format.mjs';
+import { validateOrchestrationEvent } from '../schema.mjs';
+
+export const CANARY_OUTCOMES = Object.freeze({ PASSED: 'PASSED', INFRASTRUCTURE_UNAVAILABLE: 'INFRASTRUCTURE_UNAVAILABLE', FAILED: 'FAILED' });
+export const CANARY_EXPECTED_TEXT = 'AI-MAESTRO-CANARY-OK';
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+const projectRoot = path.resolve(moduleDir, '..', '..');
+const maestroBin = path.join('bin', 'maestro.mjs');
+
+function key(value) {
+  const resolved = path.resolve(String(value));
+  return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+
+function sameOrDescendant(candidate, boundary) {
+  const candidateKey = key(candidate);
+  const boundaryKey = key(boundary);
+  if (candidateKey === boundaryKey) return true;
+  const prefix = boundaryKey.endsWith(path.sep) ? boundaryKey : boundaryKey + path.sep;
+  return candidateKey.startsWith(prefix);
+}
+
+async function exists(filePath) {
+  try { await fs.access(filePath); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function realpathOrResolved(filePath) {
+  try { return await fs.realpath(filePath); } catch (error) { if (error.code === 'ENOENT') return path.resolve(filePath); throw error; }
+}
+
+async function parentWritable(parentDir) {
+  try { await fs.access(parentDir, fsSync.constants.W_OK); return true; } catch { return false; }
+}
+
+export async function preflightControlledCanary({ targetPath } = {}) {
+  if (!targetPath || String(targetPath).trim().length === 0) return { ok: false, reason: 'targetPath is required' };
+  const resolvedTarget = path.resolve(String(targetPath));
+  const resolvedProjectRoot = path.resolve(projectRoot);
+  if (sameOrDescendant(resolvedTarget, resolvedProjectRoot)) return { ok: false, reason: 'targetPath must be outside projectRoot', targetPath: resolvedTarget, projectRoot: resolvedProjectRoot };
+
+  const projectRootReal = await realpathOrResolved(resolvedProjectRoot);
+  const parentDir = path.dirname(resolvedTarget);
+  const parentReal = await realpathOrResolved(parentDir);
+  const realTargetCandidate = path.join(parentReal, path.basename(resolvedTarget));
+  if (sameOrDescendant(realTargetCandidate, projectRootReal)) return { ok: false, reason: 'targetPath realpath containment conflicts with projectRoot', targetPath: realTargetCandidate, projectRoot: projectRootReal };
+  if (await exists(resolvedTarget)) return { ok: false, reason: 'targetPath already exists', targetPath: resolvedTarget };
+
+  let stat;
+  try { stat = await fs.stat(parentDir); } catch (error) { if (error.code === 'ENOENT') return { ok: false, reason: 'targetPath parent does not exist', parentDir }; throw error; }
+  if (!stat.isDirectory()) return { ok: false, reason: 'targetPath parent is not a directory', parentDir };
+  if (!await parentWritable(parentDir)) return { ok: false, reason: 'targetPath parent is not writable', parentDir };
+  return { ok: true, targetPath: resolvedTarget, projectRoot: resolvedProjectRoot, parentDir };
+}
+
+async function textOrNull(filePath) {
+  try { return await fs.readFile(filePath, 'utf-8'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function readJsonl(filePath) {
+  const text = await textOrNull(filePath);
+  return text ? text.trim().split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line)) : [];
+}
+
+function evidence(name, result) {
+  return redactObject({ name, code: result.code, timedOut: result.timedOut === true, stdout: result.stdout || '', stderr: result.stderr || '' });
+}
+
+function infraEvidence(result) {
+  const text = ((result && result.stdout) || '') + '\n' + ((result && result.stderr) || '');
+  return result && (result.timedOut === true || /ENOENT|not found|missing_tool|provider_unavailable|network_error|authentication_error|engine_resolution_cmd_only|Codex nao encontrado|Reconnecting\.\.\.\s*\d+\/\d+|stream disconnected before completion/i.test(text));
+}
+
+function isUnknownCommandResult(result) {
+  const text = ((result && result.stdout) || '') + '\n' + ((result && result.stderr) || '');
+  return !!(result && result.code !== 0 && /Unknown command/i.test(text));
+}
+
+function trimOneTrailingNewline(text) {
+  return String(text || '').replace(/\r?\n$/, '');
+}
+
+async function runStep(name, command, args, options, steps) {
+  const result = await (options.execFileRawFn || execFileRaw)(command, args, options);
+  steps.push(evidence(name, result));
+  return result;
+}
+
+async function createCanaryTask(targetPath, execOptions, steps) {
+  const script = [
+    "import { addTask } from './src/tasks.mjs';",
+    "const task = await addTask('Create CANARY_RESULT.txt containing exactly AI-MAESTRO-CANARY-OK.', {",
+    "  title: '03G controlled canary task',",
+    "  engine: 'codex9',",
+    "  files: ['CANARY_RESULT.txt'],",
+    "  acceptance: ['CANARY_RESULT.txt contains exactly AI-MAESTRO-CANARY-OK']",
+    "});",
+    "console.log(String(task.id));"
+  ].join('\n');
+  const result = await runStep('create-canary-task', process.execPath, ['--input-type=module', '-e', script], { ...execOptions, cwd: targetPath }, steps);
+  if (result.code !== 0) return { ok: false, result };
+  const taskId = String(result.stdout || '').trim().split(/\r?\n/).pop();
+  return { ok: /^\d+$/.test(taskId), taskId, result };
+}
+
+async function validateClone(targetPath, execOptions, steps) {
+  const schema = await runStep('schema-check', process.execPath, [maestroBin, 'schema-check'], { ...execOptions, cwd: targetPath }, steps);
+  if (schema.code !== 0) return { ok: false, reason: 'schema-check failed' };
+  const events = await readJsonl(path.join(targetPath, '.maestro', 'ORCHESTRATIONS.jsonl'));
+  if (events.length === 0) return { ok: false, reason: 'ORCHESTRATIONS.jsonl is empty' };
+  for (const event of events) {
+    const validation = validateOrchestrationEvent(event);
+    if (!validation.ok) return { ok: false, reason: 'invalid orchestration event: ' + validation.errors.join('; ') };
+  }
+  return { ok: true, events: events.length };
+}
+
+async function latestRunForTask(targetPath, taskId) {
+  if (!taskId) return null;
+  try {
+    const runs = await readJsonl(path.join(targetPath, '.maestro', 'RUNS.jsonl'));
+    for (let index = runs.length - 1; index >= 0; index -= 1) {
+      if (String(runs[index]?.taskId) === String(taskId)) return runs[index];
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function runEntryInfraEvidence(entry) {
+  if (!entry) return false;
+  const text = [
+    entry.stdout,
+    entry.stderr,
+    entry.fullStdout,
+    entry.fullStderr,
+    entry.error,
+    entry.message,
+    entry.reason,
+    JSON.stringify(entry)
+  ].filter(value => value !== undefined && value !== null).join('\n');
+  return infraEvidence({ stdout: text, stderr: '', timedOut: entry.timedOut === true });
+}
+
+async function cleanup(registeredTargetPath) {
+  if (!registeredTargetPath) return null;
+  try { await fs.rm(registeredTargetPath, { recursive: true, force: true }); return null; } catch (error) { return 'cleanup failed for registered targetPath: ' + (error.message || String(error)); }
+}
+
+function classify({ cloneResult, initResult, readinessResult, doctorResult, runResult, runLogInfrastructureEvidence, artifactOk, validationOk }) {
+  if (cloneResult && cloneResult.code !== 0) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (initResult && initResult.code !== 0) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (readinessResult && readinessResult.code !== 0 && !isUnknownCommandResult(readinessResult)) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (doctorResult && doctorResult.code !== 0) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (runLogInfrastructureEvidence === true) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (runResult && runResult.code !== 0 && infraEvidence(runResult)) return CANARY_OUTCOMES.INFRASTRUCTURE_UNAVAILABLE;
+  if (runResult && runResult.code !== 0) return CANARY_OUTCOMES.FAILED;
+  if (artifactOk !== true || validationOk !== true) return CANARY_OUTCOMES.FAILED;
+  return CANARY_OUTCOMES.PASSED;
+}
+
+export async function runControlledCanary({ targetPath, timeoutMs = 180000, execFileRawFn = execFileRaw } = {}) {
+  const steps = [];
+  const warnings = [];
+  const preflight = await preflightControlledCanary({ targetPath });
+  if (!preflight.ok) return redactObject({ ok: false, outcome: CANARY_OUTCOMES.FAILED, reason: preflight.reason, preflight, steps, warnings, writesPrevented: true });
+
+  const registeredTargetPath = preflight.targetPath;
+  let cloneResult = null;
+  let initResult = null;
+  let readinessResult = null;
+  let doctorResult = null;
+  let runResult = null;
+  let artifactOk = false;
+  let validationOk = false;
+  let runLogInfrastructureEvidence = false;
+  let validation = null;
+  let taskId = null;
+  const execOptions = { quiet: true, timeoutMs, execFileRawFn };
+  const officialEnv = { ...process.env, MAESTRO_CODEX_INVOCATION: process.env.MAESTRO_CODEX_INVOCATION || 'codex-js-isolated', MAESTRO_CODEX_STRATEGY: process.env.MAESTRO_CODEX_STRATEGY || 'basic', MAESTRO_CODEX_PROFILE: process.env.MAESTRO_CODEX_PROFILE || 'default' };
+
+  let finalResult = null;
+  try {
+    cloneResult = await runStep('git-clone', 'git', ['clone', preflight.projectRoot, registeredTargetPath], execOptions, steps);
+    if (cloneResult.code === 0) initResult = await runStep('maestro-init', process.execPath, [maestroBin, 'init'], { ...execOptions, cwd: registeredTargetPath }, steps);
+    if (initResult && initResult.code === 0) readinessResult = await runStep('maestro-readiness', process.execPath, [maestroBin, 'readiness'], { ...execOptions, cwd: registeredTargetPath }, steps);
+    const readinessOk = readinessResult && readinessResult.code === 0;
+    if (readinessResult && isUnknownCommandResult(readinessResult)) {
+      warnings.push(redactCredentials('maestro readiness is unavailable in the cloned committed snapshot; falling back to maestro doctor'));
+      doctorResult = await runStep('maestro-doctor', process.execPath, [maestroBin, 'doctor'], { ...execOptions, cwd: registeredTargetPath }, steps);
+    }
+    const healthOk = readinessOk || (doctorResult && doctorResult.code === 0);
+    if (healthOk) {
+      const created = await createCanaryTask(registeredTargetPath, execOptions, steps);
+      if (created.ok) {
+        taskId = created.taskId;
+        runResult = await runStep('maestro-orchestrate-real', process.execPath, [maestroBin, 'orchestrate', taskId, '--real', '--force', '--quiet'], { ...execOptions, cwd: registeredTargetPath, env: officialEnv, timeoutMs }, steps);
+        runLogInfrastructureEvidence = runEntryInfraEvidence(await latestRunForTask(registeredTargetPath, taskId));
+      } else {
+        runResult = created.result;
+      }
+    }
+    if (runResult && runResult.code === 0) {
+      const artifact = await textOrNull(path.join(registeredTargetPath, 'CANARY_RESULT.txt'));
+      artifactOk = trimOneTrailingNewline(artifact) === CANARY_EXPECTED_TEXT;
+      validation = await validateClone(registeredTargetPath, execOptions, steps);
+      validationOk = validation.ok === true;
+    }
+    const outcome = classify({ cloneResult, initResult, readinessResult, doctorResult, runResult, runLogInfrastructureEvidence, artifactOk, validationOk });
+    const ok = outcome === CANARY_OUTCOMES.PASSED;
+    finalResult = { ok, outcome, reason: ok ? 'controlled canary passed' : 'controlled canary did not pass', registeredTargetPath, createdResources: [registeredTargetPath], taskId, enginePolicy: { selected: 'codex-official', fallback: 'codex9 only after evidenced official unavailability', concurrency: 1, timeoutMs }, artifactOk, validation, steps, warnings };
+  } finally {
+    const cleanupWarning = await cleanup(registeredTargetPath);
+    if (cleanupWarning) warnings.push(redactCredentials(cleanupWarning));
+  }
+  return redactObject(finalResult || { ok: false, outcome: CANARY_OUTCOMES.FAILED, reason: 'controlled canary ended before classification', registeredTargetPath, createdResources: [registeredTargetPath], steps, warnings });
+}
+
+export async function canaryCommand(targetPath, options = {}) {
+  const result = await runControlledCanary({ targetPath, ...options });
+  console.log(redactCredentials(JSON.stringify(result, null, 2)));
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}

package/src/orchestration/self-hosting-readiness.mjs

@@ -0,0 +1,244 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+import { doctor, init, schemaCheck } from '../session-commands.mjs';
+import { addTask } from '../tasks.mjs';
+import { writeUtf8TextFile } from '../files.mjs';
+import { doctorLine, redactObject } from '../format.mjs';
+import { validateOrchestrationEvent } from '../schema.mjs';
+import { runSerialOrchestration } from './orchestration-runtime.mjs';
+import { DEFAULT_BUDGET } from './budget-manager.mjs';
+
+export const READINESS_STAGE_NAMES = Object.freeze([
+  'doctor', 'schema-check-real-project', 'bootstrap-temp-project',
+  'create-parent-and-children-fixture', 'dry-run-no-side-effects',
+  'serial-real-fake-engine', 'controlled-parallel-real-fake-engine',
+  'audit-trail-start-finish-events', 'schema-check-temp-project',
+  'cleanup-temp-project'
+]);
+
+const TERMINAL = new Set(['completed', 'completed_with_warnings', 'failed', 'blocked', 'needs_human']);
+const OK_TEXT = 'AI-MAESTRO-READINESS-OK';
+
+export function readinessEngineRecord(id = 'codex9') {
+  return {
+    id, displayName: 'Readiness Fake Codex', provider: 'test', model: 'fake', enabled: true, validated: true, source: '03g-readiness',
+    cost: { class: 'free', inputPerMillion: null, outputPerMillion: null, currency: null },
+    capabilities: { reasoning: 3, planning: 3, coding: 3, debugging: 3, review: 3, writing: 3, documentation: 3, vision: false, longContext: null, structuredOutput: null, toolCalling: true },
+    tools: { shell: true, filesystemRead: true, filesystemWrite: true, browser: false, imageInput: false, testExecution: true },
+    roles: ['worker'], limits: { maxContextTokens: null, maxOutputTokens: null, requestsPerMinute: null, requestsPerDay: null, maxParallel: 1 },
+    health: { available: null, lastCheckedAt: null, recentSuccessRate: null, averageLatencyMs: null, consecutiveFailures: 0 },
+    confidence: { capabilities: 'confirmed', cost: 'confirmed', tools: 'confirmed' }
+  };
+}
+
+export function readOnlyReadinessSubtask(id, extra = {}) {
+  return { id, title: 'Review child ' + id, description: 'review child ' + id, expectedFiles: [], blockedBy: [], parallelizable: true, requires: { filesystemWrite: false }, parentTaskId: '1', ...extra };
+}
+
+export function writeReadinessSubtask(id, file = 'evidence.txt', extra = {}) {
+  return { id, title: 'Write child ' + id, description: 'write ' + file + ' for child ' + id, expectedFiles: [file], blockedBy: [], parallelizable: false, requires: { filesystemWrite: true }, parentTaskId: '1', ...extra };
+}
+
+export function readinessDelegation(subtasks) {
+  return { decision: 'READY', manager: { id: 'readiness-manager' }, subtasks, assignments: subtasks.map(subtask => ({ subtaskId: subtask.id, role: 'worker', candidateEngine: 'codex9', reason: ['03g-readiness'] })), executionMode: 'serial', requiresHuman: false, warnings: [] };
+}
+
+export function readinessModuleResults(subtasks) {
+  return {
+    classification: { taskKind: 'simple-edit', complexity: 1, risk: 'low', canDelegate: true },
+    manager: { id: 'maestro', decision: 'decompose' }, engineCandidate: { id: 'codex9' },
+    preflight: { decision: 'ACCEPT', reason: '03g readiness fixture' }, budget: { allowed: true, reason: '03g readiness fixture' }, policy: { ok: true, warnings: [] },
+    runtimeGate: { decision: 'DELEGATE', reasons: ['03g readiness fixture'] }, delegation: readinessDelegation(subtasks)
+  };
+}
+
+function subtaskIdFromPrompt(prompt) {
+  const match = String(prompt || '').match(/\bchild\s+([A-Za-z0-9_-]+)\b/i);
+  return match ? match[1] : null;
+}
+
+function evidenceFileFromPrompt(prompt) {
+  const match = String(prompt || '').match(/\bwrite\s+([^\s]+)\s+for\s+child\b/i);
+  return match ? match[1] : null;
+}
+
+export function createReadinessFakeEngine({ delayMs = 0, codes = [0], stdout = '03G readiness fake worker completed', stderr = '', onRun = async () => {} } = {}) {
+  const calls = [];
+  let active = 0;
+  let maxActive = 0;
+  return {
+    name: 'codex9', calls,
+    get count() { return calls.length; },
+    get maxActive() { return maxActive; },
+    async run(prompt, options) {
+      const callNumber = calls.length + 1;
+      const subtaskId = subtaskIdFromPrompt(prompt);
+      active += 1;
+      maxActive = Math.max(maxActive, active);
+      calls.push({ callNumber, subtaskId, prompt, options, startedAt: Date.now() });
+      try {
+        await onRun({ callNumber, subtaskId, prompt, options, active });
+        if (delayMs > 0) await new Promise(resolve => setTimeout(resolve, delayMs));
+        const file = evidenceFileFromPrompt(prompt);
+        if (file) await fs.writeFile(file, OK_TEXT + '\n', { encoding: 'utf8' });
+        return { code: codes[Math.min(callNumber - 1, codes.length - 1)], stdout, stderr, strategy: '03g-readiness-fake', signal: null, timedOut: false };
+      } finally {
+        active -= 1;
+      }
+    }
+  };
+}
+
+export function acceptedReadinessVerification(outcome = 'verified') {
+  return { schemaVersion: 1, scope: 'consolidated', verificationOutcome: outcome, outcome, warnings: [], failures: [], summary: outcome };
+}
+
+async function textOrNull(file) {
+  try { return await fs.readFile(file, 'utf-8'); } catch (error) { if (error.code === 'ENOENT') return null; throw error; }
+}
+
+async function readJsonl(file) {
+  const text = await textOrNull(file);
+  return text ? text.trim().split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line)) : [];
+}
+
+async function exists(file) {
+  try { await fs.access(file); return true; } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function silence(quiet, fn) {
+  if (!quiet) return fn();
+  const original = [console.log, console.warn, console.error];
+  console.log = () => {}; console.warn = () => {}; console.error = () => {};
+  try { return await fn(); } finally { [console.log, console.warn, console.error] = original; }
+}
+
+export async function bootstrapReadinessProject(projectDir = process.cwd()) {
+  await fs.mkdir(path.join(projectDir, '.memory'), { recursive: true });
+  await fs.writeFile(path.join(projectDir, '.memory', 'BRIEF.md'), '03G readiness temp project\n', { encoding: 'utf8' });
+  await init();
+  await fs.writeFile(path.join(projectDir, '.maestro', 'engines.json'), JSON.stringify({ schemaVersion: 1, engines: [readinessEngineRecord()] }, null, 2), { encoding: 'utf8' });
+  await fs.writeFile(path.join(projectDir, '.maestro', 'budget.json'), JSON.stringify(DEFAULT_BUDGET, null, 2), { encoding: 'utf8' });
+}
+
+export async function createReadinessParent(title = '03G readiness parent') {
+  return addTask('Coordinate 03G self-hosting readiness using deterministic fake workers.', { title, status: 'pending', priority: 'medium', engine: 'codex9', files: [], acceptance: ['All fake child runs complete and the parent is verified.'] });
+}
+
+function assertOk(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+async function runReadinessPipeline() {
+  await bootstrapReadinessProject(process.cwd());
+  const parent = await createReadinessParent();
+  const serialSubtasks = [readOnlyReadinessSubtask('ro1'), readOnlyReadinessSubtask('ro2'), writeReadinessSubtask('wr1')];
+  const beforeTasks = await fs.readFile(path.join('.maestro', 'TASKS.json'), 'utf-8');
+  const beforeRuns = await fs.readFile(path.join('.maestro', 'RUNS.jsonl'), 'utf-8');
+  const dryEngine = createReadinessFakeEngine();
+  const dryRun = await runSerialOrchestration({ taskId: parent.id, mode: 'dry-run', engine: dryEngine, suppressOutput: true, moduleResults: readinessModuleResults(serialSubtasks), concurrency: { enabled: true, maxConcurrent: 2 } });
+  assertOk(dryRun.executed === false && dryEngine.count === 0, 'dry-run executed fake engine');
+  assertOk(await fs.readFile(path.join('.maestro', 'TASKS.json'), 'utf-8') === beforeTasks, 'dry-run mutated TASKS.json');
+  assertOk(await fs.readFile(path.join('.maestro', 'RUNS.jsonl'), 'utf-8') === beforeRuns, 'dry-run mutated RUNS.jsonl');
+
+  const serialEngine = createReadinessFakeEngine({ delayMs: 5 });
+  const serialRun = await runSerialOrchestration({ taskId: parent.id, mode: 'real', engine: serialEngine, suppressOutput: true, moduleResults: readinessModuleResults(serialSubtasks), verifyConsolidatedResult: () => acceptedReadinessVerification() });
+  assertOk(serialRun.executed === true && serialEngine.maxActive === 1 && TERMINAL.has(serialRun.parentStatus), 'serial fake orchestration failed');
+  assertOk(serialRun.consolidation && serialRun.verification, 'serial consolidation or verification missing');
+
+  const parallelParent = await createReadinessParent('03G readiness parallel parent');
+  const parallelSubtasks = [
+    readOnlyReadinessSubtask('pa1', { parentTaskId: String(parallelParent.id) }),
+    readOnlyReadinessSubtask('pa2', { parentTaskId: String(parallelParent.id) }),
+    writeReadinessSubtask('pw1', 'evidence-parallel.txt', { parentTaskId: String(parallelParent.id) })
+  ];
+  const parallelEngine = createReadinessFakeEngine({ delayMs: 30 });
+  const parallelRun = await runSerialOrchestration({ taskId: parallelParent.id, mode: 'real', engine: parallelEngine, suppressOutput: true, moduleResults: readinessModuleResults(parallelSubtasks), concurrency: { enabled: true, maxConcurrent: 2 }, verifyConsolidatedResult: () => acceptedReadinessVerification() });
+  assertOk(parallelRun.executed === true && parallelEngine.maxActive > 1 && TERMINAL.has(parallelRun.parentStatus), 'controlled-parallel fake orchestration failed');
+
+  const events = await readJsonl(path.join('.maestro', 'ORCHESTRATIONS.jsonl'));
+  for (const id of [String(parent.id), String(parallelParent.id)]) {
+    assertOk(events.some(event => event.parentTaskId === id && event.eventType === 'orchestration_started'), 'missing start event for ' + id);
+    assertOk(events.some(event => event.parentTaskId === id && event.eventType === 'orchestration_finished'), 'missing finish event for ' + id);
+  }
+  for (const event of events) {
+    const validation = validateOrchestrationEvent(event);
+    assertOk(validation.ok, 'invalid orchestration event: ' + validation.errors.join('; '));
+  }
+  const tempSchema = await schemaCheck();
+  assertOk(tempSchema.ok, 'schema-check failed in temp project');
+  return redactObject({ parentTaskId: parent.id, parallelParentTaskId: parallelParent.id, dryRun, dryEngine: { count: dryEngine.count, maxActive: dryEngine.maxActive }, serialRun, parallelRun, serialEngine: { count: serialEngine.count, maxActive: serialEngine.maxActive }, parallelEngine: { count: parallelEngine.count, maxActive: parallelEngine.maxActive }, events, tempSchema });
+}
+
+function reportMarkdown(stages, ok) {
+  return '# AI Maestro Readiness Check\n\n- Date: ' + new Date().toISOString() + '\n- Status: ' + (ok ? 'PASS' : 'FAIL') + '\n\n## Checks\n\n' + stages.map(stage => '- ' + (stage.ok ? 'OK' : 'FAIL') + ' ' + stage.name + (stage.error ? ' - ' + stage.error : '')).join('\n') + '\n';
+}
+
+async function writeReport(stages, ok, cwd = process.cwd()) {
+  await fs.mkdir(path.join(cwd, '.maestro'), { recursive: true });
+  const reportPath = path.join(cwd, '.maestro', 'READINESS_CHECK.md');
+  await writeUtf8TextFile(reportPath, reportMarkdown(stages, ok));
+  return reportPath;
+}
+
+function pushStage(stages, name, ok, extra = {}) {
+  stages.push(redactObject({ name, ok, ...extra }));
+}
+
+export async function runReadinessCheck({ quiet = false } = {}) {
+  const invocationCwd = process.cwd();
+  const stages = [];
+  const details = {};
+  let tempDir = null;
+  let tempRemoved = false;
+
+  try { await silence(quiet, () => doctor()); pushStage(stages, 'doctor', true); } catch (error) { pushStage(stages, 'doctor', false, { error: error.message || String(error) }); }
+  try { const result = await silence(quiet, () => schemaCheck()); pushStage(stages, 'schema-check-real-project', result.ok === true, { checks: result.checks }); } catch (error) { pushStage(stages, 'schema-check-real-project', false, { error: error.message || String(error) }); }
+
+  const originalCwd = process.cwd();
+  try {
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'maestro-03g-readiness-'));
+    process.chdir(tempDir);
+    pushStage(stages, 'bootstrap-temp-project', true, { tempDir });
+    const pipeline = await silence(quiet, () => runReadinessPipeline());
+    details.pipeline = pipeline;
+    pushStage(stages, 'create-parent-and-children-fixture', true, { parentTaskId: pipeline.parentTaskId, parallelParentTaskId: pipeline.parallelParentTaskId });
+    pushStage(stages, 'dry-run-no-side-effects', pipeline.dryRun.executed === false && pipeline.dryEngine.count === 0);
+    pushStage(stages, 'serial-real-fake-engine', pipeline.serialRun.executed === true && TERMINAL.has(pipeline.serialRun.parentStatus), { maxActive: pipeline.serialEngine.maxActive });
+    pushStage(stages, 'controlled-parallel-real-fake-engine', pipeline.parallelRun.executed === true && pipeline.parallelEngine.maxActive > 1, { maxActive: pipeline.parallelEngine.maxActive });
+    const started = pipeline.events.filter(event => event.eventType === 'orchestration_started').length;
+    const finished = pipeline.events.filter(event => event.eventType === 'orchestration_finished').length;
+    pushStage(stages, 'audit-trail-start-finish-events', started >= 2 && finished >= 2, { started, finished });
+    pushStage(stages, 'schema-check-temp-project', pipeline.tempSchema.ok === true);
+  } catch (error) {
+    const message = error.message || String(error);
+    for (const name of READINESS_STAGE_NAMES) {
+      if (!stages.some(stage => stage.name === name) && !['doctor', 'schema-check-real-project', 'cleanup-temp-project'].includes(name)) pushStage(stages, name, false, { error: message });
+    }
+  } finally {
+    process.chdir(originalCwd);
+    if (tempDir) {
+      await fs.rm(tempDir, { recursive: true, force: true });
+      tempRemoved = !(await exists(tempDir));
+    }
+    pushStage(stages, 'cleanup-temp-project', tempDir ? tempRemoved : true, tempDir ? { tempDir } : {});
+  }
+
+  const orderedStages = READINESS_STAGE_NAMES.map(name => stages.find(stage => stage.name === name) || { name, ok: false, error: 'stage not executed' });
+  const ok = orderedStages.every(stage => stage.ok);
+  const reportPath = await writeReport(orderedStages, ok, invocationCwd);
+  if (!quiet) {
+    console.log('Running AI Maestro readiness check...');
+    for (const stage of orderedStages) doctorLine(stage.ok ? 'OK' : 'FAIL', stage.name, stage.error || 'done');
+    console.log(reportMarkdown(orderedStages, ok));
+  }
+  return redactObject({ ok, stages: orderedStages, reportPath, tempDir, tempRemoved, details });
+}
+
+export async function readinessCommand() {
+  const result = await runReadinessCheck();
+  if (!result.ok) process.exitCode = 1;
+  return result;
+}