ai-maestro 1.0.0

package/src/ui/state.mjs

@@ -0,0 +1,504 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from '../config.mjs';
+import { readJsonSafe } from '../files.mjs';
+import { summarizeText } from '../format.mjs';
+import { countTasksByStatus } from '../task-commands.mjs';
+import { sortRunnableTasks } from '../tasks.mjs';
+import { listEngineRecords } from '../orchestration/capability-registry.mjs';
+import { loadBudget } from '../orchestration/budget-manager.mjs';
+import { loadFallbackGraph } from '../orchestration/fallback-graph.mjs';
+import { DELEGATION_LIMITS } from '../orchestration/delegation-manager.mjs';
+import { SECTOR_MANAGERS } from '../orchestration/sector-managers.mjs';
+
+const JSONL_RECENT_LIMIT = 100;
+const TIMELINE_LIMIT = 100;
+
+const STATUS_META = {
+  idle: { key: 'idle', label: 'parado', icon: '⏸', tone: 'idle' },
+  running: { key: 'running', label: 'executando', icon: '▶', tone: 'running' },
+  in_progress: { key: 'running', label: 'executando', icon: '▶', tone: 'running' },
+  thinking: { key: 'thinking', label: 'pensando', icon: '☁', tone: 'thinking' },
+  planning: { key: 'thinking', label: 'pensando', icon: '☁', tone: 'thinking' },
+  completed: { key: 'completed', label: 'finalizado', icon: '✓', tone: 'success' },
+  success: { key: 'completed', label: 'finalizado', icon: '✓', tone: 'success' },
+  done: { key: 'completed', label: 'finalizado', icon: '✓', tone: 'success' },
+  completed_with_warnings: { key: 'completed_with_warnings', label: 'finalizado com alertas', icon: '⚠', tone: 'warning' },
+  blocked: { key: 'blocked', label: 'bloqueado', icon: '⛔', tone: 'blocked' },
+  needs_human: { key: 'needs_human', label: 'precisa de decisão humana', icon: '❔', tone: 'blocked' },
+  failed: { key: 'failed', label: 'erro', icon: '⚠', tone: 'error' },
+  error: { key: 'failed', label: 'erro', icon: '⚠', tone: 'error' },
+  warning: { key: 'warning', label: 'atenção', icon: '!', tone: 'warning' },
+  stopped: { key: 'idle', label: 'parado', icon: '⏸', tone: 'idle' }
+};
+
+const GROUP_META = {
+  maestro: { key: 'maestro', label: 'Maestro', icon: '▣' },
+  codex: { key: 'codex', label: 'Codex', icon: '⬢' },
+  memory: { key: 'memory', label: 'Memory', icon: '◌' },
+  safety: { key: 'safety', label: 'Safety', icon: '⚑' },
+  engine: { key: 'engine', label: 'Engine', icon: '◈' },
+  ui: { key: 'ui', label: 'UI', icon: '▤' },
+  issue: { key: 'issue', label: 'Erros/Bloqueios', icon: '⚠' }
+};
+
+function readTextSafe(filePath, fallback = '') {
+  return fs.readFile(filePath, 'utf-8').catch(error => {
+    if (error.code === 'ENOENT') return fallback;
+    throw error;
+  });
+}
+
+export async function readJsonlRecent(filePath, limit = JSONL_RECENT_LIMIT) {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return content
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .slice(-limit)
+      .map(line => JSON.parse(line));
+  } catch (error) {
+    if (error.code === 'ENOENT') return [];
+    if (error instanceof SyntaxError) return [{ parseError: 'Invalid JSONL in ' + filePath, source: filePath }];
+    throw error;
+  }
+}
+
+export function normalizeStatus(value, fallback = 'idle') {
+  const key = String(value || fallback || 'idle').toLowerCase();
+  return STATUS_META[key] || STATUS_META[fallback] || STATUS_META.idle;
+}
+
+export function normalizeGroup(agent = '', entry = {}) {
+  const raw = String(agent || entry.agent || entry.source || '').toLowerCase();
+  if (raw.includes('memory') || raw.includes('ai-universal-memory')) return GROUP_META.memory;
+  if (raw.includes('ui')) return GROUP_META.ui;
+  if (raw.includes('safety')) return GROUP_META.safety;
+  if (raw.includes('engine')) return GROUP_META.engine;
+  if (raw.includes('codex')) return GROUP_META.codex;
+  return GROUP_META.maestro;
+}
+
+function parseTimestamp(value, fallback = new Date().toISOString()) {
+  if (!value) return fallback;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) ? fallback : date.toISOString();
+}
+
+function compactSummary(text, limit = 260) {
+  return summarizeText(String(text || ''), limit);
+}
+
+function stringifyRaw(entry) {
+  try {
+    return JSON.stringify(entry, null, 2);
+  } catch (error) {
+    return String(entry);
+  }
+}
+
+export function formatRelativeTime(value, now = Date.now()) {
+  if (!value) return 'agora';
+  const time = new Date(value).getTime();
+  if (Number.isNaN(time)) return 'agora';
+  const delta = Math.max(0, now - time);
+  const minutes = Math.floor(delta / 60000);
+  if (minutes < 1) return 'agora';
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h`;
+  const days = Math.floor(hours / 24);
+  return `${days}d`;
+}
+
+function makeTimelineEntry({
+  timestamp,
+  agent,
+  kind,
+  status,
+  summary,
+  source,
+  raw,
+  taskId,
+  commandId,
+  issue = false,
+  warnings = []
+}) {
+  const normalizedStatus = normalizeStatus(status, issue ? 'error' : 'idle');
+  const group = normalizeGroup(agent, { agent, status, issue, commandId, taskId, source });
+  return {
+    timestamp: parseTimestamp(timestamp),
+    agent: agent || 'maestro-cli',
+    group: group.key,
+    groupLabel: group.label,
+    icon: issue ? GROUP_META.issue.icon : group.icon,
+    kind: kind || 'event',
+    status: normalizedStatus.key,
+    statusLabel: normalizedStatus.label,
+    statusIcon: normalizedStatus.icon,
+    tone: normalizedStatus.tone,
+    issue,
+    warnings,
+    summary: compactSummary(summary || kind || 'evento'),
+    source: source || 'unknown',
+    taskId: taskId === undefined ? null : taskId,
+    commandId: commandId || null,
+    rawText: stringifyRaw(raw),
+    collapsedByDefault: true
+  };
+}
+
+function fromMemoryEvent(row) {
+  return makeTimelineEntry({
+    timestamp: row.time || row.timestamp,
+    agent: row.agent || 'ai-universal-memory',
+    kind: row.action || 'note',
+    status: row.status || 'completed',
+    summary: row.summary || row.error || row.action || 'memory event',
+    source: '.memory/events.jsonl',
+    raw: row,
+    issue: String(row.status || '').toLowerCase() === 'failed'
+  });
+}
+
+function fromRunEntry(row) {
+  const blockedBySafety = row.blockedBySafety === true;
+  const blockedByGate = row.blockedByGate === true;
+  const blocked = blockedBySafety || row.status === 'blocked' || row.status === 'needs_human';
+  const warningBits = [];
+  if (row.status === 'completed_with_warnings') warningBits.push('concluído com alertas');
+  if (row.suspectedFalsePositive) warningBits.push('possível falsa conclusão');
+  if (row.unsupportedToolCall) warningBits.push('ferramenta não suportada usada pelo worker');
+  if (row.windowsShellCommandMismatch) warningBits.push('comando incompatível com PowerShell');
+  if (row.syntaxValidationFailed) warningBits.push('arquivo alterado pode estar com sintaxe quebrada');
+  if (row.analysisTaskChangedCode) warningBits.push('task de análise alterou código');
+  if (row.deletedFiles && row.deletedFiles.length) warningBits.push('worker deletou arquivos: ' + row.deletedFiles.join(', '));
+  // v0.5.1 runtime gate fields (present on every run that went through
+  // src/task-commands.mjs's runTask after the gate was wired in; absent on
+  // older rows, which is fine — this is purely additive summary text).
+  if (row.runtimeDecision && row.runtimeDecision !== 'EXECUTE') {
+    warningBits.push('gate: ' + row.runtimeDecision + (row.blockedReasonCategory ? ' (' + row.blockedReasonCategory + ')' : ''));
+  }
+  if (row.forced === true) warningBits.push('executado com --force');
+  const gateSuffix = [
+    row.selectedManager ? 'gerente=' + row.selectedManager : null,
+    row.selectedEngine ? 'engine=' + row.selectedEngine : null,
+    row.preflightDecision ? 'preflight=' + row.preflightDecision : null
+  ].filter(Boolean).join(' ');
+  const baseSummary = 'Task #' + row.taskId + ' ' + (row.status || (row.exitCode === 0 ? 'finalizado' : 'erro')) + (gateSuffix ? ' [' + gateSuffix + ']' : '');
+  return makeTimelineEntry({
+    timestamp: row.endTime || row.startTime || row.timestamp,
+    agent: blockedBySafety ? 'safety' : (blockedByGate ? 'engine' : (row.engine || 'codex9-worker')),
+    kind: 'run',
+    status: row.status || (row.exitCode === 0 ? 'completed' : 'failed'),
+    summary: warningBits.length ? baseSummary + ' — ' + warningBits.join('; ') : baseSummary,
+    source: '.maestro/RUNS.jsonl',
+    raw: row,
+    taskId: row.taskId,
+    warnings: row.warnings && row.warnings.length ? row.warnings : warningBits,
+    issue: row.status === 'failed' || blocked || row.status === 'completed_with_warnings' || row.unsupportedToolCall === true || row.suspectedFalsePositive === true || row.windowsShellCommandMismatch === true || row.syntaxValidationFailed === true
+  });
+}
+
+function fromUsageEntry(row) {
+  const blocked = row.blockedBySafety === true || row.exitCode === 2;
+  const status = blocked ? 'blocked' : (row.exitCode === 0 ? 'completed' : 'failed');
+  const summary = [
+    row.command || 'usage',
+    row.strategy ? 'via ' + row.strategy : null,
+    row.taskId ? '#' + row.taskId : null
+  ].filter(Boolean).join(' ');
+  return makeTimelineEntry({
+    timestamp: row.timestamp,
+    agent: blocked ? 'safety' : 'engine',
+    kind: 'usage',
+    status,
+    summary: summary || 'usage event',
+    source: '.maestro/usage.jsonl',
+    raw: row,
+    commandId: row.command || null,
+    issue: blocked || status === 'failed'
+  });
+}
+
+function fromUiRunEntry(row) {
+  const status = row.exitCode === 0 ? 'completed' : 'failed';
+  const summary = [
+    'UI',
+    row.commandId || 'command',
+    row.taskId ? '#' + row.taskId : null,
+    status
+  ].filter(Boolean).join(' ');
+  return makeTimelineEntry({
+    timestamp: row.timestamp,
+    agent: 'ui',
+    kind: 'ui-command',
+    status,
+    summary,
+    source: '.maestro/ui-runs.jsonl',
+    raw: row,
+    commandId: row.commandId || null,
+    taskId: row.taskId === undefined ? null : row.taskId,
+    issue: status === 'failed'
+  });
+}
+
+export function buildTimelineEntries({ memoryEvents = [], runs = [], usage = [], uiRuns = [] } = {}) {
+  return [...memoryEvents.map(fromMemoryEvent), ...runs.map(fromRunEntry), ...usage.map(fromUsageEntry), ...uiRuns.map(fromUiRunEntry)]
+    .sort((a, b) => b.timestamp.localeCompare(a.timestamp))
+    .slice(0, TIMELINE_LIMIT);
+}
+
+export function buildTaskView(task) {
+  const statusView = normalizeStatus(task.status);
+  const actions = [];
+  const taskId = Number(task.id);
+  if (Number.isInteger(taskId) && taskId > 0 && ['pending', 'failed', 'in_progress'].includes(String(task.status))) {
+    actions.push({
+      id: 'run-task',
+      command: 'run-task',
+      label: 'Run Task',
+      taskId,
+      tone: 'primary'
+    });
+  }
+  if (Number.isInteger(taskId) && taskId > 0 && ['blocked', 'needs_human'].includes(String(task.status))) {
+    actions.push({
+      id: 'task-pending',
+      command: 'task-pending',
+      label: 'Reabrir',
+      taskId,
+      tone: 'secondary'
+    });
+  }
+  return {
+    ...task,
+    id: taskId,
+    statusView,
+    statusLabel: statusView.label,
+    statusIcon: statusView.icon,
+    statusTone: statusView.tone,
+    lastUpdatedAt: task.updatedAt || task.createdAt || null,
+    lastUpdatedAgo: formatRelativeTime(task.updatedAt || task.createdAt || null),
+    actions
+  };
+}
+
+export function buildCardViews({ timeline = [], tasks = [], memorySummary = '', taskCounts = {}, lockStatus = {}, currentEngine = 'codex9' } = {}) {
+  const latestByGroup = group => timeline.find(entry => entry.group === group) || null;
+  const maestroEvent = latestByGroup('maestro');
+  const codexEvent = latestByGroup('codex');
+  const memoryEvent = latestByGroup('memory');
+  const safetyEvent = latestByGroup('safety') || timeline.find(entry => entry.issue) || null;
+  const engineEvent = latestByGroup('engine') || latestByGroup('codex');
+  const projectEvent = timeline[0] || null;
+
+  return [
+    {
+      id: 'maestro',
+      title: 'Maestro',
+      status: lockStatus.locked ? 'running' : (taskCounts.blocked ? 'blocked' : (tasks.some(task => task.status === 'pending' || task.status === 'in_progress') ? 'thinking' : (safetyEvent ? 'warning' : 'idle'))),
+      detail: lockStatus.locked ? 'Lock ativo: ' + (lockStatus.command || 'maestro') : 'Pronto',
+      lastEvent: maestroEvent,
+      lastEventLabel: maestroEvent ? maestroEvent.summary : 'Sem evento recente'
+    },
+    {
+      id: 'codex',
+      title: 'Codex',
+      status: tasks.some(task => task.status === 'in_progress' || task.status === 'pending') ? 'thinking' : 'idle',
+      detail: 'Engine atual: ' + currentEngine,
+      lastEvent: codexEvent,
+      lastEventLabel: codexEvent ? codexEvent.summary : 'Sem evento recente'
+    },
+    {
+      id: 'memory',
+      title: 'Memory',
+      status: memorySummary ? 'completed' : 'warning',
+      detail: memorySummary || 'Sem resumo de memória',
+      lastEvent: memoryEvent,
+      lastEventLabel: memoryEvent ? memoryEvent.summary : 'Sem evento recente'
+    },
+    {
+      id: 'safety',
+      title: 'Safety',
+      status: taskCounts.blocked ? 'blocked' : 'idle',
+      detail: (taskCounts.blocked || 0) + ' bloqueadas',
+      lastEvent: safetyEvent,
+      lastEventLabel: safetyEvent ? safetyEvent.summary : 'Sem evento recente'
+    },
+    {
+      id: 'router',
+      title: 'Engine Router',
+      status: 'idle',
+      detail: 'Display local',
+      lastEvent: engineEvent,
+      lastEventLabel: engineEvent ? engineEvent.summary : 'Sem evento recente'
+    },
+    {
+      id: 'project',
+      title: 'Projeto',
+      status: taskCounts.failed ? 'error' : (tasks.some(task => task.status === 'pending' || task.status === 'in_progress') ? 'running' : 'completed'),
+      detail: tasks.length + ' tarefas',
+      lastEvent: projectEvent,
+      lastEventLabel: projectEvent ? projectEvent.summary : 'Sem evento recente'
+    }
+  ];
+}
+
+export async function readHandoffSnapshot(projectRoot = process.cwd()) {
+  const memoryHandoffPath = path.join(projectRoot, CONFIG.memoryPath, 'handoff.md');
+  const maestroHandoffPath = path.join(projectRoot, CONFIG.maestroPath, 'HANDOFF.md');
+  try {
+    const memoryContent = await fs.readFile(memoryHandoffPath, 'utf-8');
+    return { content: memoryContent, source: memoryHandoffPath, exists: true };
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  try {
+    const maestroContent = await fs.readFile(maestroHandoffPath, 'utf-8');
+    return { content: maestroContent, source: maestroHandoffPath, exists: true };
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+  return {
+    content: '# Handoff indisponível\n\nNenhum handoff encontrado em .memory/handoff.md ou .maestro/HANDOFF.md.\n',
+    source: null,
+    exists: false
+  };
+}
+
+// Read-only orchestra snapshot for the UI (Phase 16). Deliberately exposes
+// no way to edit engines.json/budget.json/fallback-graph.json from here —
+// project rule: "Não permitir editar configurações sensíveis pela UI nessa
+// versão." Callers that omit engines/budget/fallbackGraph (e.g. existing
+// tests built before this field existed) get safe empty defaults instead
+// of a crash.
+export function buildOrchestraView({ engines = [], budget = null, fallbackGraph = null } = {}) {
+  const engineSummaries = engines.map(engine => ({
+    id: engine.id,
+    displayName: engine.displayName || engine.id,
+    enabled: engine.enabled === true,
+    validated: engine.validated === true,
+    provider: engine.provider || 'unknown',
+    costClass: engine.cost ? engine.cost.class : 'unknown',
+    roles: engine.roles || []
+  }));
+  return {
+    engines: engineSummaries,
+    enabledEngineCount: engineSummaries.filter(engine => engine.enabled).length,
+    budget: budget ? {
+      allowPaid: budget.allowPaid === true,
+      allowClaudeReview: budget.allowClaudeReview === true,
+      allowDirectOpenAI: budget.allowDirectOpenAI === true,
+      preferFree: budget.preferFree === true,
+      estimatedTokenBudget: budget.estimatedTokenBudget ?? null,
+      maxRunsPerTask: budget.maxRunsPerTask ?? null,
+      maxSubagentsPerTask: budget.maxSubagentsPerTask ?? null,
+      maxDepth: budget.maxDepth ?? null
+    } : null,
+    fallbackRuleCount: fallbackGraph && fallbackGraph.rules ? Object.keys(fallbackGraph.rules).length : 0,
+    delegationLimits: DELEGATION_LIMITS,
+    sectorManagers: SECTOR_MANAGERS.map(sector => sector.id)
+  };
+}
+
+export function buildUiStateFromFiles({
+  projectRoot,
+  tasks,
+  memoryEvents,
+  runs,
+  usage,
+  uiRuns,
+  usageSummary,
+  lock,
+  memoryBrief,
+  checkpoint,
+  handoff,
+  engines = [],
+  budget = null,
+  fallbackGraph = null
+}) {
+  const taskViews = sortRunnableTasks(tasks).map(buildTaskView);
+  const taskCounts = countTasksByStatus(tasks);
+  const lockStatus = lock ? { locked: true, ...lock } : { locked: false };
+  const timeline = buildTimelineEntries({ memoryEvents, runs, usage, uiRuns });
+  const currentEngine = taskViews.find(task => task.status === 'in_progress' || task.status === 'pending')?.engine || 'codex9';
+  const memorySummarySource = memoryBrief || handoff || checkpoint || '';
+  const memorySummary = summarizeText(memorySummarySource.replace(/^#+\s*/gm, ''), 700);
+  const warnings = [];
+  if (lockStatus.locked) warnings.push('Lock ativo');
+  if (taskCounts.blocked) warnings.push('Tarefas bloqueadas');
+  if (taskCounts.needs_human) warnings.push('Tarefas aguardando decisão humana (' + taskCounts.needs_human + ')');
+  if (usageSummary && usageSummary.apiOpenAiDetected) warnings.push('api.openai.com detectado');
+
+  return {
+    projectRoot,
+    memorySummary,
+    handoff,
+    tasks: taskViews,
+    taskCounts,
+    timeline,
+    recentEvents: timeline,
+    recentRuns: runs.slice(-10),
+    recentUsage: usage.slice(-10),
+    recentMemoryEvents: memoryEvents.slice(-10),
+    recentUiRuns: uiRuns.slice(-10),
+    lockStatus,
+    currentEngine,
+    warnings,
+    cards: buildCardViews({ timeline, tasks: taskViews, memorySummary, taskCounts, lockStatus, currentEngine }),
+    statusMap: STATUS_META,
+    groupMap: GROUP_META,
+    orchestra: buildOrchestraView({ engines, budget, fallbackGraph })
+  };
+}
+
+export async function readUiState(projectRoot = process.cwd()) {
+  const memoryPath = path.join(projectRoot, CONFIG.memoryPath);
+  const maestroPath = path.join(projectRoot, CONFIG.maestroPath);
+  const tasks = await readJsonSafe(path.join(maestroPath, 'TASKS.json'), []);
+  const memoryEvents = await readJsonlRecent(path.join(memoryPath, 'events.jsonl'), JSONL_RECENT_LIMIT);
+  const runs = await readJsonlRecent(path.join(maestroPath, 'RUNS.jsonl'), JSONL_RECENT_LIMIT);
+  const usage = await readJsonlRecent(path.join(maestroPath, 'usage.jsonl'), JSONL_RECENT_LIMIT);
+  const uiRuns = await readJsonlRecent(path.join(maestroPath, 'ui-runs.jsonl'), JSONL_RECENT_LIMIT);
+  const usageSummary = await readJsonSafe(path.join(maestroPath, 'usage-summary.json'), null);
+  const lock = await readJsonSafe(path.join(maestroPath, '.lock.json'), null);
+  const memoryBrief = await readTextSafe(path.join(memoryPath, 'BRIEF.md'));
+  const checkpoint = await readTextSafe(path.join(maestroPath, 'CHECKPOINT.md'));
+  const handoff = await readTextSafe(path.join(maestroPath, 'HANDOFF.md'));
+  const engines = await listEngineRecords();
+  const budget = await loadBudget();
+  const fallbackGraph = await loadFallbackGraph();
+  return buildUiStateFromFiles({
+    projectRoot,
+    tasks,
+    memoryEvents,
+    runs,
+    usage,
+    uiRuns,
+    usageSummary,
+    lock,
+    memoryBrief,
+    checkpoint,
+    handoff,
+    engines,
+    budget,
+    fallbackGraph
+  });
+}
+
+export function getUiWatchFiles(projectRoot = process.cwd()) {
+  return [
+    path.join(projectRoot, CONFIG.memoryPath, 'BRIEF.md'),
+    path.join(projectRoot, CONFIG.memoryPath, 'handoff.md'),
+    path.join(projectRoot, CONFIG.memoryPath, 'events.jsonl'),
+    path.join(projectRoot, CONFIG.maestroPath, 'TASKS.json'),
+    path.join(projectRoot, CONFIG.maestroPath, 'RUNS.jsonl'),
+    path.join(projectRoot, CONFIG.maestroPath, 'usage.jsonl'),
+    path.join(projectRoot, CONFIG.maestroPath, 'usage-summary.json'),
+    path.join(projectRoot, CONFIG.maestroPath, 'CHECKPOINT.md'),
+    path.join(projectRoot, CONFIG.maestroPath, 'HANDOFF.md'),
+    path.join(projectRoot, CONFIG.maestroPath, '.lock.json'),
+    path.join(projectRoot, CONFIG.maestroPath, 'ui-runs.jsonl')
+  ];
+}

package/src/usage.mjs

@@ -0,0 +1,178 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { CONFIG } from './config.mjs';
+import { stampSchemaVersion, validateUsageSummary, inferRunKind } from './schema.mjs';
+import { listEngineRecords } from './orchestration/capability-registry.mjs';
+
+const usagePath = path.join(CONFIG.maestroPath, 'usage.jsonl');
+const summaryPath = path.join(CONFIG.maestroPath, 'usage-summary.json');
+
+// Hotfix A.2: safety/cost policy fields the usage-summary schema requires
+// (validateUsageSummary in src/schema.mjs). Old summary files predate these
+// fields; they are migrated automatically by adding the defaults below —
+// history counters are never dropped, and an existing explicit boolean is
+// never overwritten.
+export const USAGE_POLICY_DEFAULTS = Object.freeze({
+  preferFree: true,
+  allowPaid: false,
+  allowClaudeReview: false,
+  allowDirectOpenAI: false
+});
+
+export function applyUsagePolicyDefaults(summary = {}) {
+  const migrated = { ...summary };
+  for (const [key, value] of Object.entries(USAGE_POLICY_DEFAULTS)) {
+    if (typeof migrated[key] !== 'boolean') {
+      migrated[key] = value;
+    }
+  }
+  return migrated;
+}
+
+async function readSummaryFileSafe() {
+  try {
+    return JSON.parse(await fs.readFile(summaryPath, 'utf-8'));
+  } catch (error) {
+    return null;
+  }
+}
+
+function estimateTokens(text) {
+  return Math.ceil((text || '').length / 4);
+}
+
+async function readUsageRows() {
+  try {
+    const content = await fs.readFile(usagePath, 'utf-8');
+    return content.split(/\r?\n/).filter(Boolean).map(line => JSON.parse(line));
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      return [];
+    }
+    throw error;
+  }
+}
+
+export async function recordUsage(entry) {
+  await fs.mkdir(CONFIG.maestroPath, { recursive: true });
+  const promptChars = entry.prompt ? entry.prompt.length : (entry.promptChars || 0);
+  const estimatedInputTokens = entry.estimatedInputTokens || estimateTokens(entry.prompt || '');
+  const estimatedOutputTokens = entry.output ? estimateTokens(entry.output) : (entry.estimatedOutputTokens || 0);
+  const row = stampSchemaVersion({
+    timestamp: new Date().toISOString(),
+    engine: 'codex9',
+    profile: CONFIG.codexProfile,
+    // runKind separates real task work from diagnostics/preflight/verification/
+    // subagent runs so stats don't conflate them (Phase 14). Explicit
+    // entry.runKind always wins; otherwise infer from entry.command; a
+    // command this project doesn't recognize yet stays 'unknown', never a
+    // guessed 'task'.
+    runKind: entry.runKind || inferRunKind(entry.command),
+    promptChars,
+    estimatedInputTokens,
+    estimatedOutputTokens,
+    estimatedTotalTokens: estimatedInputTokens + estimatedOutputTokens,
+    claudeAvoided: true,
+    ...entry
+  });
+  delete row.prompt;
+  delete row.output;
+  await fs.appendFile(usagePath, JSON.stringify(row) + '\n');
+  await writeUsageSummary();
+  return row;
+}
+
+// Best-effort engine -> cost-class lookup for the summary breakdown below.
+// This is an ESTIMATE, never a real billing figure (project rule: "Nunca
+// chamar a estimativa de billing real"). An engine id not found in
+// .maestro/engines.json (or the registry file missing) counts as 'unknown',
+// not 'free' — absence of data is not evidence of being free.
+async function buildCostClassLookup() {
+  const engines = await listEngineRecords();
+  const lookup = new Map();
+  for (const engine of engines) {
+    lookup.set(engine.id, engine.cost ? engine.cost.class : 'unknown');
+  }
+  return lookup;
+}
+
+function groupCounts(rows, keyFn) {
+  return rows.reduce((acc, row) => {
+    const key = keyFn(row) || 'unknown';
+    acc[key] = (acc[key] || 0) + 1;
+    return acc;
+  }, {});
+}
+
+export async function writeUsageSummary() {
+  const rows = await readUsageRows();
+  const existingSummary = await readSummaryFileSafe();
+  // Carry over any policy booleans a previous summary already had; add the
+  // defaults for the missing ones (automatic migration of old files).
+  const policy = applyUsagePolicyDefaults(existingSummary || {});
+  const costLookup = await buildCostClassLookup();
+  const executionByCost = rows.reduce((acc, row) => {
+    const costClass = costLookup.get(row.engine) || 'unknown';
+    const bucket = (costClass === 'free' || costClass === 'local') ? 'free'
+      : costClass === 'free-tier' ? 'free'
+      : costClass === 'paid' ? 'paid'
+      : 'unknown';
+    acc[bucket] = (acc[bucket] || 0) + 1;
+    return acc;
+  }, { free: 0, paid: 0, unknown: 0 });
+
+  const summary = stampSchemaVersion({
+    preferFree: policy.preferFree,
+    allowPaid: policy.allowPaid,
+    allowClaudeReview: policy.allowClaudeReview,
+    allowDirectOpenAI: policy.allowDirectOpenAI,
+    totalRuns: rows.length,
+    completed: rows.filter(row => row.exitCode === 0).length,
+    failed: rows.filter(row => row.exitCode && row.exitCode !== 0).length,
+    blocked: rows.filter(row => row.blockedBySafety).length,
+    estimatedTotalTokens: rows.reduce((sum, row) => sum + (row.estimatedTotalTokens || 0), 0),
+    estimatedClaudeAvoidedTokens: rows.reduce((sum, row) => sum + (row.claudeAvoided ? (row.estimatedTotalTokens || 0) : 0), 0),
+    engines: groupCounts(rows, row => row.engine),
+    // byRunKind separates real task work from diagnostics/doctor/codex-test/
+    // ui-command/release-check/preflight/verification/subagent runs (Phase 14).
+    // Rows recorded before this field existed have no `runKind` and land in
+    // 'unknown', not 'task' — see inferRunKind() in src/schema.mjs.
+    byRunKind: groupCounts(rows, row => row.runKind),
+    // ESTIMATED execution split by cost class, never real billing data (see
+    // buildCostClassLookup() above). 'unknown' includes both engines absent
+    // from .maestro/engines.json and engines whose cost.class is 'unknown'.
+    executionByCost,
+    // v0.5.1: how the runtime gate (src/orchestration/runtime-gate.mjs)
+    // resolved each run that went through it. Rows from before the gate was
+    // wired in (or non-task commands) have no runtimeDecision and land in
+    // 'unknown' — never assumed to be EXECUTE.
+    byGateDecision: groupCounts(rows, row => row.runtimeDecision),
+    // Only meaningful for rows where runtimeDecision === 'BLOCK'; answers
+    // "blocked by preflight / budget / policy / no-candidate" per project
+    // rule that stats must be able to count each separately.
+    byBlockReason: groupCounts(rows.filter(row => row.runtimeDecision === 'BLOCK'), row => row.blockedReasonCategory),
+    lastRuns: rows.slice(-10)
+  });
+  const result = validateUsageSummary(summary);
+  if (!result.ok) {
+    console.warn('Usage summary failed schema validation: ' + result.errors.join(', '));
+  }
+  await fs.writeFile(summaryPath, JSON.stringify(summary, null, 2));
+  return summary;
+}
+
+export async function getUsageSummary() {
+  try {
+    const parsed = JSON.parse(await fs.readFile(summaryPath, 'utf-8'));
+    const migrated = applyUsagePolicyDefaults(parsed);
+    const needsMigration = Object.keys(USAGE_POLICY_DEFAULTS).some(key => parsed[key] !== migrated[key]);
+    if (needsMigration) {
+      // Automatic in-place migration of an old summary file: only the
+      // missing policy defaults are added; every historical counter stays.
+      await fs.writeFile(summaryPath, JSON.stringify(migrated, null, 2));
+    }
+    return migrated;
+  } catch (error) {
+    return writeUsageSummary();
+  }
+}