ai-maestro 1.0.0

package/src/orchestration/fallback-recommendation.mjs

@@ -0,0 +1,73 @@
+import { planFallback } from './fallback-graph.mjs';
+import { computeNextAttemptTime, getHealthState } from './provider-health.mjs';
+
+const TAXONOMY_TO_GRAPH_CATEGORY = {
+  infrastructure: 'provider_unavailable',
+  authentication: 'authentication_error',
+  quota: 'quota_exceeded',
+  rate_limit: 'rate_limit',
+  timeout: 'network_error',
+  network: 'network_error',
+  stream_interruption: 'network_error',
+  provider_unavailable: 'provider_unavailable',
+  model_unavailable: 'provider_unavailable',
+  engine_resolution: 'unknown_failure',
+  worker_failure: 'unknown_failure',
+  deliverable_rejection: 'test_failure',
+  safety_block: 'policy_violation',
+  human_decision: 'unknown_failure',
+  unknown: 'unknown_failure'
+};
+
+function graphCategoryFor(failureClass) {
+  return TAXONOMY_TO_GRAPH_CATEGORY[failureClass] || 'unknown_failure';
+}
+
+function alternativeAllowed(rule) {
+  return ['try-equivalent-provider', 'retry-then-successor', 'switch-provider', 'escalate-capability', 'escalate-context', 'require-capability'].includes(rule && rule.action);
+}
+
+export async function recommendFallback({ healthTargetId, failureClass = 'unknown', taskClassification = null, timestamp = null } = {}) {
+  if (!healthTargetId || typeof healthTargetId !== 'string') {
+    throw new TypeError('healthTargetId is required');
+  }
+  const health = await getHealthState(healthTargetId, { timestamp });
+  const underlyingRule = await planFallback({ category: graphCategoryFor(failureClass), taskClassification });
+  const reason = [];
+  let recommendation = 'use_current';
+
+  if (health.state === 'OPEN') {
+    const nextAttempt = computeNextAttemptTime(health);
+    if (nextAttempt) {
+      recommendation = alternativeAllowed(underlyingRule) ? 'try_alternative' : 'wait_cooldown';
+      reason.push('current health target is OPEN until ' + nextAttempt);
+    } else {
+      recommendation = 'wait_cooldown';
+      reason.push('current health target is OPEN and waiting for cooldown evaluation');
+    }
+  } else if (health.state === 'HALF_OPEN') {
+    if (health.halfOpenProbeAvailable === false) {
+      recommendation = 'wait_cooldown';
+      reason.push('HALF_OPEN probe is already reserved in this process');
+    } else {
+      recommendation = 'use_current';
+      reason.push('HALF_OPEN allows at most one probe; no successor engine is selected in 03H1');
+    }
+  } else {
+    recommendation = 'use_current';
+    reason.push('current health target is CLOSED');
+  }
+
+  if (underlyingRule && underlyingRule.action) {
+    reason.push('fallback graph action would be ' + underlyingRule.action + ', but 03H1 only recommends');
+  }
+
+  return {
+    recommendation,
+    currentState: health.state,
+    cooldownUntil: health.cooldownUntil || null,
+    halfOpenProbeAvailable: health.state === 'HALF_OPEN' ? health.halfOpenProbeAvailable !== false : false,
+    underlyingRule,
+    reason
+  };
+}

package/src/orchestration/file-conflict-detector.mjs

@@ -0,0 +1,126 @@
+import fsSync from 'fs';
+import path from 'path';
+
+// Canonical detectFileConflicts implementation (spec section 4 of
+// .maestro/v0.5.2/02_PART_B_DELEGATION_AND_SUBTASKS.md). Previously
+// duplicated between here and delegation-executor.mjs; delegation-executor.mjs
+// now imports from this module instead of keeping its own copy.
+
+// "Does this subtask write/modify a file?" must use the same signal
+// task-classifier.mjs already computes (requires.filesystemWrite), not an
+// invented taskKind vocabulary like 'write'/'modify' — no taskKind in
+// TASK_KINDS (task-classifier.mjs) is ever literally 'write' or 'modify'.
+// A subtask missing `requires` entirely (e.g. a hand-built fixture) is
+// treated as a write task, matching this function's original conservative
+// behavior of flagging any subtask with no expectedFiles.
+function isWriteSubtask(subtask) {
+  return subtask.requires ? subtask.requires.filesystemWrite !== false : true;
+}
+
+function normalizeForPlatform(filePath, platform) {
+  const normalized = path.normalize(filePath);
+  return platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+function isOutsideRoot(rootPath, candidatePath) {
+  const relative = path.relative(rootPath, candidatePath);
+  return relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative);
+}
+
+function existingPathForRealpath(candidatePath, rootPath) {
+  let current = candidatePath;
+  while (current && current !== path.dirname(current)) {
+    if (fsSync.existsSync(current)) return current;
+    if (path.resolve(current) === path.resolve(rootPath)) return rootPath;
+    current = path.dirname(current);
+  }
+  return rootPath;
+}
+
+function containmentConflict(file, projectRoot) {
+  const root = path.resolve(projectRoot || process.cwd());
+  const candidate = path.resolve(root, String(file));
+  if (isOutsideRoot(root, candidate)) {
+    return {
+      type: 'sensitive-path',
+      severity: 'high',
+      path: String(file),
+      reason: 'expectedFiles entry resolves outside the project root'
+    };
+  }
+
+  try {
+    const rootReal = fsSync.realpathSync.native(root);
+    const existing = existingPathForRealpath(candidate, root);
+    const existingReal = fsSync.realpathSync.native(existing);
+    if (isOutsideRoot(rootReal, existingReal)) {
+      return {
+        type: 'sensitive-path',
+        severity: 'high',
+        path: String(file),
+        reason: 'expectedFiles entry traverses a symlink outside the project root'
+      };
+    }
+  } catch (error) {
+    return null;
+  }
+
+  return null;
+}
+
+export function detectFileConflicts(subtasks, options = {}) {
+  if (!Array.isArray(subtasks) || subtasks.length === 0) {
+    return [];
+  }
+
+  const conflicts = [];
+  const fileMap = new Map(); // arquivo => array de índices de subtarefas
+  const fileLabels = new Map();
+  const projectRoot = options.projectRoot || process.cwd();
+  const platform = options.platform || process.platform;
+
+  subtasks.forEach((subtask, idx) => {
+    const files = subtask.expectedFiles || [];
+    if (files.length === 0 && isWriteSubtask(subtask)) {
+      conflicts.push({
+        subtaskId: subtask.id,
+        type: 'missing-expected-files',
+        severity: 'medium',
+        reason: 'Subtarefa não declara expectedFiles, pode causar confusão sobre qual arquivo altera.'
+      });
+    }
+    files.forEach(file => {
+      const containment = containmentConflict(file, projectRoot);
+      if (containment) {
+        conflicts.push({
+          ...containment,
+          subtaskId: subtask.id
+        });
+      }
+      const resolved = path.resolve(projectRoot, String(file));
+      const key = normalizeForPlatform(resolved, platform);
+      if (!fileMap.has(key)) {
+        fileMap.set(key, []);
+        fileLabels.set(key, file);
+      }
+      fileMap.get(key).push(idx);
+    });
+  });
+
+  // Detecta overlaps de arquivo: duas ou mais subtarefas alterando o mesmo
+  // arquivo, o que também representa risco de sobrescrita e conflito para
+  // execução paralela.
+  fileMap.forEach((indices, key) => {
+    if (indices.length > 1) {
+      conflicts.push({
+        file: fileLabels.get(key),
+        subtaskIds: indices.map(i => subtasks[i].id),
+        type: 'file-write-conflict',
+        severity: 'high',
+        reason: `Múltiplas subtarefas alteram o mesmo arquivo: ${indices.map(i => subtasks[i].title).join(', ')}`
+      });
+    }
+  });
+
+  return conflicts;
+}

package/src/orchestration/host-validation.mjs

@@ -0,0 +1,241 @@
+import fs from 'fs/promises';
+import { existsSync } from 'fs';
+import path from 'path';
+import { spawn } from 'child_process';
+
+export const DEFAULT_HOST_VALIDATION_POLICY = {
+  allowHostValidationFallback: true,
+  hostValidationCommands: ['npm-test', 'npm-run-check', 'node-check']
+};
+
+const COMMANDS = {
+  'npm-test': { kind: 'npm', args: ['test'] },
+  'npm-run-check': { kind: 'npm', args: ['run', 'check'] },
+  'node-check': { executable: process.execPath, args: null }
+};
+
+export function resolveNpmInvocation(args = []) {
+  if (process.platform !== 'win32') {
+    return { executable: 'npm', args };
+  }
+  const candidates = [];
+  if (process.env.MAESTRO_NPX_PATH) {
+    candidates.push(path.join(path.dirname(process.env.MAESTRO_NPX_PATH), 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  }
+  if (process.env.APPDATA) {
+    candidates.push(path.join(process.env.APPDATA, 'npm', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  }
+  if (process.env.ProgramFiles) {
+    candidates.push(path.join(process.env.ProgramFiles, 'nodejs', 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  }
+  candidates.push(path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'));
+  const cli = candidates.find(candidate => existsSync(candidate));
+  if (cli) {
+    return { executable: process.execPath, args: [cli, ...args] };
+  }
+  return { executable: 'npm', args };
+}
+
+const SECRET_PATTERNS = [
+  /sk-[A-Za-z0-9_-]{10,}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g,
+  /(NINEROUTER_API_KEY|OPENAI_API_KEY|ANTHROPIC_API_KEY|TOKEN|SECRET|PASSWORD)=([^\s]+)/gi
+];
+
+function redact(text) {
+  let value = String(text || '');
+  for (const pattern of SECRET_PATTERNS) {
+    value = value.replace(pattern, (match, key) => key ? key + '=[REDACTED]' : '[REDACTED]');
+  }
+  return value;
+}
+
+function ensureProjectRoot(projectRoot) {
+  if (typeof projectRoot !== 'string' || projectRoot.trim() === '') {
+    throw new Error('projectRoot is required');
+  }
+  return path.resolve(projectRoot);
+}
+
+function isInside(root, candidate) {
+  const rel = path.relative(root, candidate);
+  return rel === '' || (!!rel && !rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+function assertNoFreeFormCommand(input) {
+  if (input.command || input.commandLine || input.cmd || input.args || input.argv || input.shell === true) {
+    throw new Error('free-form host commands are not allowed');
+  }
+  if (input.fromWorkerOutput === true || input.source === 'worker-output') {
+    throw new Error('commands copied from worker output are not allowed');
+  }
+}
+
+function validateNodeCheckFile(projectRoot, file) {
+  if (typeof file !== 'string' || file.trim() === '') {
+    throw new Error('node-check requires a file');
+  }
+  const normalizedInput = file.replace(/\\/g, path.sep);
+  const fullPath = path.resolve(projectRoot, normalizedInput);
+  if (!isInside(projectRoot, fullPath)) {
+    throw new Error('node-check file must stay inside projectRoot');
+  }
+  const relative = path.relative(projectRoot, fullPath);
+  const segments = relative.split(path.sep).map(segment => segment.toLowerCase());
+  if (segments.includes('.env') || path.basename(fullPath).toLowerCase() === '.env') {
+    throw new Error('node-check refuses .env');
+  }
+  const ext = path.extname(fullPath).toLowerCase();
+  if (ext !== '.js' && ext !== '.mjs') {
+    throw new Error('node-check only accepts .js or .mjs files');
+  }
+  return { fullPath, relative };
+}
+
+export function normalizeHostValidationPolicy(policy = {}) {
+  const allowHostValidationFallback = policy.allowHostValidationFallback !== false;
+  const configured = Array.isArray(policy.hostValidationCommands)
+    ? policy.hostValidationCommands.filter(commandId => Object.prototype.hasOwnProperty.call(COMMANDS, commandId))
+    : DEFAULT_HOST_VALIDATION_POLICY.hostValidationCommands;
+  return { allowHostValidationFallback, hostValidationCommands: configured };
+}
+
+export function validateHostCommand(input = {}) {
+  assertNoFreeFormCommand(input);
+  const commandId = input.commandId;
+  if (!Object.prototype.hasOwnProperty.call(COMMANDS, commandId)) {
+    throw new Error('unknown host validation command: ' + String(commandId || ''));
+  }
+  const projectRoot = ensureProjectRoot(input.projectRoot);
+  const policy = normalizeHostValidationPolicy(input.policy || DEFAULT_HOST_VALIDATION_POLICY);
+  if (!policy.allowHostValidationFallback) {
+    throw new Error('host validation fallback is disabled by policy');
+  }
+  if (!policy.hostValidationCommands.includes(commandId)) {
+    throw new Error('host validation command is not allowlisted: ' + commandId);
+  }
+  if (commandId === 'npm-install' || /install/i.test(commandId)) {
+    throw new Error('npm install is not allowed');
+  }
+  const command = COMMANDS[commandId];
+  const invocation = command.kind === 'npm'
+    ? resolveNpmInvocation(command.args || [])
+    : { executable: command.executable, args: [...(command.args || [])] };
+  let args = [...invocation.args];
+  let file = null;
+  if (commandId === 'node-check') {
+    file = validateNodeCheckFile(projectRoot, input.file);
+    args = ['--check', file.fullPath];
+  }
+  return {
+    commandId,
+    projectRoot,
+    executable: invocation.executable,
+    args,
+    shell: false,
+    timeoutMs: Number.isFinite(input.timeoutMs) ? input.timeoutMs : 120000,
+    file: file ? file.relative : null
+  };
+}
+
+function spawnCollect(command, args, options, spawnFn = spawn) {
+  return new Promise(resolve => {
+    const startedAt = Date.now();
+    const child = spawnFn(command, args, {
+      cwd: options.cwd,
+      shell: false,
+      stdio: ['ignore', 'pipe', 'pipe']
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer = null;
+    const finish = result => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      resolve({ ...result, durationMs: Date.now() - startedAt });
+    };
+    timer = setTimeout(() => {
+      if (child && typeof child.kill === 'function') child.kill('SIGTERM');
+      finish({ code: 124, stdout, stderr: stderr + '\nTimed out after ' + options.timeoutMs + 'ms.' });
+    }, options.timeoutMs);
+    if (child.stdout && typeof child.stdout.on === 'function') {
+      child.stdout.on('data', data => { stdout += data.toString(); });
+    }
+    if (child.stderr && typeof child.stderr.on === 'function') {
+      child.stderr.on('data', data => { stderr += data.toString(); });
+    }
+    child.on('error', error => finish({ code: error.code || 1, stdout, stderr: error.message }));
+    child.on('close', code => finish({ code, stdout, stderr }));
+  });
+}
+
+export async function runHostValidation(input = {}, options = {}) {
+  let validated;
+  try {
+    validated = validateHostCommand(input);
+  } catch (error) {
+    return {
+      ok: false,
+      result: 'rejected',
+      error: error.message,
+      commandId: input.commandId || null,
+      metadata: { rejected: true }
+    };
+  }
+  try {
+    await fs.access(validated.projectRoot);
+  } catch (error) {
+    return {
+      ok: false,
+      result: 'rejected',
+      error: 'projectRoot is not accessible: ' + error.message,
+      commandId: validated.commandId,
+      metadata: { rejected: true }
+    };
+  }
+  const raw = await spawnCollect(validated.executable, validated.args, {
+    cwd: validated.projectRoot,
+    timeoutMs: validated.timeoutMs
+  }, options.spawnFn);
+  const result = raw.code === 0 ? 'passed' : 'failed';
+  return {
+    ok: raw.code === 0,
+    result,
+    commandId: validated.commandId,
+    exitCode: raw.code,
+    stdout: redact(raw.stdout),
+    stderr: redact(raw.stderr),
+    metadata: {
+      commandId: validated.commandId,
+      executable: validated.executable,
+      args: validated.args,
+      cwd: validated.projectRoot,
+      shell: false,
+      timeoutMs: validated.timeoutMs,
+      durationMs: raw.durationMs,
+      file: validated.file
+    }
+  };
+}
+
+export function summarizeHostValidation(result) {
+  if (!result) {
+    return { used: false, commands: [], result: 'not_run' };
+  }
+  if (Array.isArray(result)) {
+    return {
+      used: result.length > 0,
+      commands: result.map(item => item.commandId).filter(Boolean),
+      result: result.length > 0 && result.every(item => item.ok) ? 'passed' : 'failed',
+      metadata: result.map(item => item.metadata).filter(Boolean)
+    };
+  }
+  return {
+    used: true,
+    commands: [result.commandId].filter(Boolean),
+    result: result.result || (result.ok ? 'passed' : 'failed'),
+    metadata: result.metadata ? [result.metadata] : []
+  };
+}