@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/cli/mcp.js

@@ -0,0 +1,124 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import process from 'node:process';
+import { logger } from '../logger.js';
+const MCP_HEADER_TOKEN = 'Content-Length:';
+const MCP_HEADER_DELIMITER = '\r\n\r\n';
+export async function serveMcp(options) {
+    const repoRoot = resolve(options.repoRoot ?? process.cwd());
+    if (!existsSync(repoRoot)) {
+        throw new Error(`Repository root not found: ${repoRoot}`);
+    }
+    if (options.dryRun) {
+        logger.warn(`[mcp] repo root: ${repoRoot}`);
+        logger.warn('[mcp] codex CLI must be available in PATH.');
+        return;
+    }
+    const args = ['-C', repoRoot, 'mcp-server', ...options.extraArgs];
+    const child = spawn('codex', args, { stdio: ['inherit', 'pipe', 'pipe'] });
+    if (child.stdout) {
+        if (isStrictMcpStdout()) {
+            attachMcpStdoutGuard(child.stdout);
+        }
+        else {
+            child.stdout.pipe(process.stdout);
+        }
+    }
+    if (child.stderr) {
+        child.stderr.pipe(process.stderr);
+    }
+    await new Promise((resolvePromise) => {
+        child.once('exit', (code) => {
+            if (typeof code === 'number') {
+                process.exitCode = code;
+            }
+            else {
+                process.exitCode = 1;
+            }
+            resolvePromise();
+        });
+        child.once('error', (error) => {
+            logger.error(error?.message ?? String(error));
+            process.exitCode = 1;
+            resolvePromise();
+        });
+    });
+}
+function isStrictMcpStdout() {
+    const value = process.env.CODEX_MCP_STDIO_STRICT;
+    if (!value) {
+        return true;
+    }
+    const normalized = value.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes';
+}
+function attachMcpStdoutGuard(stream) {
+    let buffer = Buffer.alloc(0);
+    let expectedLength = null;
+    const flushLog = (data) => {
+        if (data.length > 0) {
+            process.stderr.write(data);
+        }
+    };
+    const processBuffer = () => {
+        while (buffer.length > 0) {
+            if (expectedLength !== null) {
+                if (buffer.length < expectedLength) {
+                    return;
+                }
+                const body = buffer.slice(0, expectedLength);
+                buffer = buffer.slice(expectedLength);
+                process.stdout.write(body);
+                expectedLength = null;
+                continue;
+            }
+            const headerIndex = buffer.indexOf(MCP_HEADER_TOKEN);
+            if (headerIndex > 0) {
+                flushLog(buffer.slice(0, headerIndex));
+                buffer = buffer.slice(headerIndex);
+                continue;
+            }
+            if (headerIndex === -1) {
+                const newlineIndex = buffer.indexOf('\n');
+                if (newlineIndex !== -1) {
+                    flushLog(buffer.slice(0, newlineIndex + 1));
+                    buffer = buffer.slice(newlineIndex + 1);
+                    continue;
+                }
+                return;
+            }
+            const headerEnd = buffer.indexOf(MCP_HEADER_DELIMITER);
+            if (headerEnd === -1) {
+                return;
+            }
+            const headerBytes = buffer.slice(0, headerEnd + MCP_HEADER_DELIMITER.length);
+            const headerText = headerBytes.toString('utf8');
+            const match = headerText.match(/Content-Length:\s*(\d+)/i);
+            if (!match) {
+                flushLog(headerBytes);
+                buffer = buffer.slice(headerEnd + MCP_HEADER_DELIMITER.length);
+                continue;
+            }
+            const length = Number(match[1]);
+            if (!Number.isFinite(length) || length < 0) {
+                flushLog(headerBytes);
+                buffer = buffer.slice(headerEnd + MCP_HEADER_DELIMITER.length);
+                continue;
+            }
+            expectedLength = length;
+            process.stdout.write(headerBytes);
+            buffer = buffer.slice(headerEnd + MCP_HEADER_DELIMITER.length);
+        }
+    };
+    stream.on('data', (chunk) => {
+        buffer = Buffer.concat([buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+        processBuffer();
+    });
+    stream.on('error', (error) => {
+        logger.error(error?.message ?? String(error));
+    });
+    if (typeof stream.resume === 'function') {
+        stream.resume();
+    }
+}

package/dist/orchestrator/src/cli/metrics/metricsAggregator.js

@@ -0,0 +1,404 @@
+import { appendFile, mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { acquireLockWithRetry } from '../../persistence/lockFile.js';
+const REQUIRED_COMPLETENESS_FIELDS = [
+    'instance_stats',
+    'privacy_events',
+    'control_plane_status'
+];
+const METRICS_LOCK_FILENAME = 'metrics.lock';
+const METRICS_PENDING_DIRNAME = 'metrics.pending';
+const DEFAULT_LOCK_STALE_MS = 5 * 60 * 1000;
+const DEFAULT_LOCK_RETRY = {
+    maxAttempts: 4,
+    initialDelayMs: 50,
+    backoffFactor: 2,
+    maxDelayMs: 200
+};
+function getMetricsRoot(env) {
+    return join(env.runsRoot, env.taskId);
+}
+function getMetricsPath(env) {
+    return join(getMetricsRoot(env), 'metrics.json');
+}
+function getMetricsPendingDir(env) {
+    return join(getMetricsRoot(env), METRICS_PENDING_DIRNAME);
+}
+function getMetricsLockPath(env) {
+    return join(getMetricsRoot(env), METRICS_LOCK_FILENAME);
+}
+async function cleanupStaleMetricsLock(lockPath, staleMs) {
+    if (staleMs <= 0) {
+        return false;
+    }
+    try {
+        const stats = await stat(lockPath);
+        const ageMs = Date.now() - stats.mtimeMs;
+        if (!Number.isFinite(ageMs) || ageMs <= staleMs) {
+            return false;
+        }
+        await rm(lockPath, { force: true });
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return false;
+        }
+        throw error;
+    }
+}
+class MetricsLockError extends Error {
+    taskId;
+    constructor(message, taskId) {
+        super(message);
+        this.taskId = taskId;
+        this.name = 'MetricsLockError';
+    }
+}
+async function drainMetricsEntryFile(env, path) {
+    let raw = '';
+    try {
+        raw = await readFile(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return 0;
+        }
+        throw error;
+    }
+    const lines = raw.trim().split('\n').filter(Boolean);
+    if (lines.length === 0) {
+        await rm(path, { force: true });
+        return 0;
+    }
+    await mkdir(getMetricsRoot(env), { recursive: true });
+    const payload = `${lines.join('\n')}\n`;
+    await appendFile(getMetricsPath(env), payload, 'utf8');
+    await rm(path, { force: true });
+    return lines.length;
+}
+export async function mergePendingMetricsEntries(env) {
+    const pendingDir = getMetricsPendingDir(env);
+    let merged = 0;
+    const staleTmpMs = DEFAULT_LOCK_STALE_MS;
+    for (let pass = 0; pass < 2; pass += 1) {
+        let entries = [];
+        try {
+            entries = await readdir(pendingDir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return merged;
+            }
+            throw error;
+        }
+        const now = Date.now();
+        for (const entry of entries) {
+            if (!entry.isFile() || !entry.name.endsWith('.tmp')) {
+                continue;
+            }
+            const tmpPath = join(pendingDir, entry.name);
+            try {
+                const stats = await stat(tmpPath);
+                if (now - stats.mtimeMs > staleTmpMs) {
+                    await rm(tmpPath, { force: true });
+                }
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    throw error;
+                }
+            }
+        }
+        const files = entries
+            .filter((entry) => entry.isFile() && entry.name.endsWith('.jsonl'))
+            .map((entry) => entry.name)
+            .sort();
+        if (files.length === 0) {
+            break;
+        }
+        for (const file of files) {
+            merged += await drainMetricsEntryFile(env, join(pendingDir, file));
+        }
+    }
+    return merged;
+}
+export async function withMetricsLock(env, action, options = {}) {
+    const overrides = options.retry ?? {};
+    const sanitizedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== undefined));
+    const lockRetry = { ...DEFAULT_LOCK_RETRY, ...sanitizedOverrides };
+    const lockPath = getMetricsLockPath(env);
+    const staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_MS;
+    await cleanupStaleMetricsLock(lockPath, staleMs);
+    try {
+        await acquireLockWithRetry({
+            taskId: env.taskId,
+            lockPath,
+            retry: lockRetry,
+            ensureDirectory: async () => {
+                await mkdir(dirname(lockPath), { recursive: true });
+            },
+            createError: (taskId, attempts) => new MetricsLockError(`Failed to acquire metrics lock for ${taskId} after ${attempts} attempts`, taskId)
+        });
+    }
+    catch (error) {
+        if (error instanceof MetricsLockError) {
+            return { acquired: false };
+        }
+        throw error;
+    }
+    try {
+        const result = await action();
+        return { acquired: true, result };
+    }
+    finally {
+        await rm(lockPath, { force: true });
+    }
+}
+export async function updateMetricsAggregates(env) {
+    const metricsRoot = getMetricsRoot(env);
+    const metricsPath = getMetricsPath(env);
+    const entries = await loadMetricsEntries(metricsPath);
+    if (entries.length === 0) {
+        return;
+    }
+    const metricsDir = join(metricsRoot, 'metrics');
+    await mkdir(metricsDir, { recursive: true });
+    await Promise.all([
+        ensureBaseline(metricsDir, entries[0]),
+        writePostRollout(metricsDir, entries),
+        writeCompleteness(metricsDir, entries),
+        writeMttrDelta(env, entries),
+        writeTfgrpoEpochAggregates(metricsDir, entries),
+        writeLearningState(env, entries)
+    ]);
+}
+async function ensureBaseline(dir, entry) {
+    const baselinePath = join(dir, 'baseline.json');
+    try {
+        await stat(baselinePath);
+        return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+    const baseline = {
+        run_id: entry.run_id,
+        recorded_at: entry.recorded_at,
+        status: entry.status,
+        duration_seconds: entry.duration_seconds,
+        completion_rate: entry.status === 'succeeded' ? 1 : 0
+    };
+    await writeFile(baselinePath, `${JSON.stringify(baseline, null, 2)}\n`, 'utf8');
+}
+async function writePostRollout(dir, entries) {
+    const totalRuns = entries.length;
+    const succeededRuns = entries.filter((entry) => entry.status === 'succeeded').length;
+    const completionRate = totalRuns > 0 ? succeededRuns / totalRuns : 0;
+    const payload = {
+        total_runs: totalRuns,
+        succeeded_runs: succeededRuns,
+        completion_rate: completionRate,
+        meets_threshold: completionRate >= 0.95,
+        updated_at: new Date().toISOString()
+    };
+    await writeFile(join(dir, 'post-rollout.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+async function writeCompleteness(dir, entries) {
+    const fieldChecks = REQUIRED_COMPLETENESS_FIELDS.length * entries.length;
+    if (fieldChecks === 0) {
+        return;
+    }
+    const missingCounts = Object.fromEntries(REQUIRED_COMPLETENESS_FIELDS.map((field) => [field, 0]));
+    for (const entry of entries) {
+        if (!Array.isArray(entry.instance_stats) || entry.instance_stats.length === 0) {
+            missingCounts.instance_stats += 1;
+        }
+        if (!Array.isArray(entry.privacy_events) || entry.privacy_events.length === 0) {
+            missingCounts.privacy_events += 1;
+        }
+        if (!entry.control_plane_status || entry.control_plane_status === 'unknown') {
+            missingCounts.control_plane_status += 1;
+        }
+    }
+    const totalMissing = Object.values(missingCounts).reduce((sum, value) => sum + value, 0);
+    const ratio = totalMissing / fieldChecks;
+    const payload = {
+        checked_fields: REQUIRED_COMPLETENESS_FIELDS,
+        missing_counts: missingCounts,
+        missing_field_ratio: ratio,
+        meets_threshold: ratio < 0.05,
+        updated_at: new Date().toISOString()
+    };
+    await writeFile(join(dir, 'completeness.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+async function writeMttrDelta(env, entries) {
+    const durations = entries
+        .map((entry) => entry.duration_seconds)
+        .filter((value) => typeof value === 'number' && Number.isFinite(value));
+    if (durations.length === 0) {
+        return;
+    }
+    const currentMttr = average(durations);
+    const metricsDir = join(env.runsRoot, env.taskId, 'metrics');
+    const baselinePath = join(metricsDir, 'baseline.json');
+    let baselineMttr = currentMttr;
+    try {
+        const raw = await readFile(baselinePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.duration_seconds === 'number') {
+            baselineMttr = parsed.duration_seconds;
+        }
+    }
+    catch (error) {
+        // baseline already ensured by ensureBaseline
+    }
+    const reductionPercent = baselineMttr > 0 ? (baselineMttr - currentMttr) / baselineMttr : 0;
+    const payload = {
+        baseline_mttr_seconds: baselineMttr,
+        current_mttr_seconds: currentMttr,
+        reduction_percent: reductionPercent,
+        meets_threshold: baselineMttr <= 0 ? true : currentMttr <= baselineMttr * 0.6,
+        updated_at: new Date().toISOString()
+    };
+    const outDir = join(env.outRoot, env.taskId, 'metrics');
+    await mkdir(outDir, { recursive: true });
+    await writeFile(join(outDir, 'mttr-delta.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+async function writeTfgrpoEpochAggregates(dir, entries) {
+    const grouped = new Map();
+    for (const entry of entries) {
+        if (typeof entry.tfgrpo_epoch !== 'number') {
+            continue;
+        }
+        const bucket = grouped.get(entry.tfgrpo_epoch) ?? [];
+        bucket.push(entry);
+        grouped.set(entry.tfgrpo_epoch, bucket);
+    }
+    if (grouped.size === 0) {
+        return;
+    }
+    const epochs = Array.from(grouped.entries())
+        .sort(([a], [b]) => a - b)
+        .map(([epoch, group]) => summarizeEpoch(epoch, group));
+    const payload = {
+        epochs,
+        updated_at: new Date().toISOString()
+    };
+    await writeFile(join(dir, 'per-epoch.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+async function writeLearningState(env, entries) {
+    const validationStatuses = entries
+        .map((entry) => entry.learning_validation_status)
+        .filter((value) => typeof value === 'string');
+    const validationSummary = {
+        passed: validationStatuses.filter((status) => status === 'validated').length,
+        failed: validationStatuses.filter((status) => status === 'snapshot_failed').length,
+        stalled: validationStatuses.filter((status) => status === 'stalled_snapshot').length,
+        manual: validationStatuses.filter((status) => status === 'needs_manual_scenario').length
+    };
+    const reviewerRejections = entries.reduce((sum, entry) => sum + (entry.learning_review_rejections ?? 0), 0);
+    const reviewerLatencies = entries
+        .map((entry) => entry.learning_review_latency_ms)
+        .filter((value) => typeof value === 'number' && Number.isFinite(value));
+    const reviewerLatencyMs = reviewerLatencies.length > 0
+        ? reviewerLatencies.reduce((sum, value) => sum + value, 0) / reviewerLatencies.length
+        : null;
+    const regressions = entries.reduce((sum, entry) => sum + (entry.learning_regressions_detected ?? 0), 0);
+    const patternPromotions = entries.reduce((sum, entry) => sum + (entry.learning_pattern_promoted ?? 0), 0);
+    const patternDeprecations = entries.reduce((sum, entry) => sum + (entry.learning_pattern_deprecated ?? 0), 0);
+    const throughputCandidates = entries.reduce((sum, entry) => sum + (entry.learning_throughput_candidates ?? 0), 0);
+    const alerts = {
+        total: entries.reduce((sum, entry) => sum + (entry.learning_alerts ?? 0), 0),
+        snapshot_failed: entries.filter((entry) => entry.learning_snapshot_status === 'snapshot_failed').length,
+        stalled_snapshot: entries.filter((entry) => entry.learning_snapshot_status === 'stalled_snapshot').length,
+        needs_manual_scenario: validationSummary.manual
+    };
+    const payload = {
+        updated_at: new Date().toISOString(),
+        safety: {
+            validation: validationSummary,
+            reviewer: { rejections: reviewerRejections, average_latency_ms: reviewerLatencyMs },
+            regression_detection: { detected: regressions },
+            pattern_hygiene: { promoted: patternPromotions, deprecated: patternDeprecations }
+        },
+        throughput: { candidates: throughputCandidates },
+        alerts
+    };
+    const outDir = join(env.outRoot, env.taskId);
+    await mkdir(outDir, { recursive: true });
+    await writeFile(join(outDir, 'state.json'), `${JSON.stringify(payload, null, 2)}\n`, 'utf8');
+}
+function summarizeEpoch(epoch, entries) {
+    const runs = entries.length;
+    const toolCalls = entries.reduce((sum, entry) => sum + (entry.tool_calls ?? 0), 0);
+    const tokenTotal = entries.reduce((sum, entry) => sum + (entry.token_total ?? 0), 0);
+    const costUsd = roundCurrency(entries.reduce((sum, entry) => sum + (entry.cost_usd ?? 0), 0));
+    const latencyMs = entries.reduce((sum, entry) => sum + (entry.latency_ms ?? 0), 0);
+    const groupSizes = entries
+        .map((entry) => entry.tfgrpo_group_size)
+        .filter((value) => typeof value === 'number');
+    const groupSizeAvg = groupSizes.length > 0 ? groupSizes.reduce((sum, value) => sum + value, 0) / groupSizes.length : null;
+    return {
+        epoch,
+        runs,
+        tool_calls: toolCalls,
+        token_total: tokenTotal,
+        cost_usd: costUsd,
+        latency_ms: latencyMs,
+        group_size_avg: groupSizeAvg,
+        tools: aggregateToolStats(entries)
+    };
+}
+function aggregateToolStats(entries) {
+    const aggregates = new Map();
+    for (const entry of entries) {
+        const stats = entry.tool_stats ?? [];
+        for (const stat of stats) {
+            if (typeof stat.tool !== 'string' || !stat.tool) {
+                continue;
+            }
+            const current = aggregates.get(stat.tool) ?? { runs: 0, tokens: 0, costUsd: 0, latencyMs: 0 };
+            current.runs += 1;
+            current.tokens += typeof stat.tokens === 'number' ? stat.tokens : 0;
+            current.costUsd += typeof stat.cost_usd === 'number' ? stat.cost_usd : 0;
+            current.latencyMs += typeof stat.latency_ms === 'number' ? stat.latency_ms : 0;
+            aggregates.set(stat.tool, current);
+        }
+    }
+    return Array.from(aggregates.entries()).map(([tool, aggregate]) => ({
+        tool,
+        runs: aggregate.runs,
+        tokens: aggregate.tokens,
+        cost_usd: roundCurrency(aggregate.costUsd),
+        latency_ms: aggregate.latencyMs
+    }));
+}
+async function loadMetricsEntries(path) {
+    try {
+        const raw = await readFile(path, 'utf8');
+        return raw
+            .trim()
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => JSON.parse(line));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT') {
+            return [];
+        }
+        throw error;
+    }
+}
+function average(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sum = values.reduce((total, value) => total + value, 0);
+    return sum / values.length;
+}
+function roundCurrency(value) {
+    return Math.round(value * 1_000_000) / 1_000_000;
+}

package/dist/orchestrator/src/cli/metrics/metricsRecorder.js

@@ -0,0 +1,138 @@
+import { randomUUID } from 'node:crypto';
+import { appendFile, mkdir, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { ensureGuardrailStatus, appendSummary, upsertGuardrailSummary } from '../run/manifest.js';
+import { isoTimestamp } from '../utils/time.js';
+import { persistManifest } from '../run/manifestPersister.js';
+import { logger } from '../../logger.js';
+import { mergePendingMetricsEntries, updateMetricsAggregates, withMetricsLock } from './metricsAggregator.js';
+import { EnvUtils } from '../../../../packages/shared/config/index.js';
+const TERMINAL_STATES = new Set(['succeeded', 'failed', 'cancelled']);
+const METRICS_PENDING_DIRNAME = 'metrics.pending';
+export async function appendMetricsEntry(env, paths, manifest, persister) {
+    if (manifest.metrics_recorded) {
+        return;
+    }
+    if (!TERMINAL_STATES.has(manifest.status)) {
+        return;
+    }
+    const startedAt = manifest.started_at ? Date.parse(manifest.started_at) : NaN;
+    const completedAt = manifest.completed_at ? Date.parse(manifest.completed_at) : NaN;
+    const durationSeconds = Number.isNaN(startedAt) || Number.isNaN(completedAt)
+        ? null
+        : Math.max(0, (completedAt - startedAt) / 1000);
+    const commandsPassed = manifest.commands.filter((cmd) => cmd.status === 'succeeded').length;
+    const commandsFailed = manifest.commands.filter((cmd) => cmd.status === 'failed').length;
+    const guardrailStatus = ensureGuardrailStatus(manifest);
+    const guardrailsPresent = guardrailStatus.present;
+    const learning = manifest.learning ?? null;
+    const privacyDecisions = manifest.privacy?.decisions ?? [];
+    const privacyEventCount = privacyDecisions.length;
+    const maxPrivacyEvents = EnvUtils.getInt('CODEX_METRICS_PRIVACY_EVENTS_MAX', -1);
+    const shouldTruncatePrivacy = maxPrivacyEvents >= 0 && privacyEventCount > maxPrivacyEvents;
+    const privacyEvents = shouldTruncatePrivacy
+        ? privacyDecisions.slice(0, maxPrivacyEvents)
+        : privacyDecisions;
+    const metricsRoot = join(env.runsRoot, env.taskId);
+    const metricsPath = join(metricsRoot, 'metrics.json');
+    const pendingDir = join(metricsRoot, METRICS_PENDING_DIRNAME);
+    const entry = {
+        run_id: manifest.run_id,
+        task_id: manifest.task_id,
+        pipeline_id: manifest.pipeline_id,
+        status: manifest.status,
+        started_at: manifest.started_at,
+        completed_at: manifest.completed_at,
+        duration_seconds: durationSeconds,
+        commands_passed: commandsPassed,
+        commands_failed: commandsFailed,
+        guardrails_present: guardrailsPresent,
+        recorded_at: isoTimestamp(),
+        artifact_path: manifest.artifact_root,
+        child_runs: manifest.child_runs.length,
+        control_plane_status: manifest.control_plane?.validation.status ?? 'unknown',
+        scheduler_mode: manifest.scheduler?.mode ?? null,
+        instance_stats: (manifest.scheduler?.assignments ?? []).map((assignment) => ({
+            instance_id: assignment.instance_id,
+            capability: assignment.capability,
+            status: assignment.status,
+            attempts: assignment.attempts.length,
+            recovery_events: assignment.attempts.reduce((sum, attempt) => sum + attempt.recovery_checkpoints.length, 0)
+        })),
+        privacy_mode: manifest.privacy?.mode ?? null,
+        privacy_log_path: manifest.privacy?.log_path ?? null,
+        privacy_event_count: privacyEventCount,
+        privacy_events_truncated: shouldTruncatePrivacy ? true : undefined,
+        privacy_events: privacyEvents,
+        handle_count: manifest.handles?.length ?? 0,
+        tfgrpo_epoch: manifest.tfgrpo?.epoch ?? null,
+        tfgrpo_group_id: manifest.tfgrpo?.group_id ?? null,
+        tfgrpo_group_size: manifest.tfgrpo?.group_size ?? null,
+        tool_calls: manifest.tfgrpo?.tool_metrics?.tool_calls ?? 0,
+        token_total: manifest.tfgrpo?.tool_metrics?.token_total ?? 0,
+        cost_usd: manifest.tfgrpo?.tool_metrics?.cost_usd ?? 0,
+        latency_ms: manifest.tfgrpo?.tool_metrics?.latency_ms ?? 0,
+        tool_stats: manifest.tfgrpo?.tool_metrics?.per_tool ?? [],
+        learning_validation_status: learning?.validation?.status ?? null,
+        learning_snapshot_status: learning?.snapshot?.status ?? null,
+        learning_scenario_status: learning?.scenario?.status ?? null,
+        learning_crystalizer_status: learning?.crystalizer?.status ?? null,
+        learning_alerts: learning?.alerts?.length ?? 0,
+        learning_group_id: learning?.validation?.grouping?.id ?? null,
+        learning_review_rejections: learning?.review?.rejections ?? 0,
+        learning_review_latency_ms: learning?.review?.latency_ms ?? null,
+        learning_regressions_detected: learning?.regressions?.detected ?? 0,
+        learning_pattern_promoted: learning?.pattern_hygiene?.promoted ?? 0,
+        learning_pattern_deprecated: learning?.pattern_hygiene?.deprecated ?? 0,
+        learning_throughput_candidates: learning?.throughput?.candidates ??
+            (learning?.crystalizer?.candidate_path ? 1 : 0)
+    };
+    await mkdir(metricsRoot, { recursive: true });
+    const appendEntry = async () => {
+        await appendFile(metricsPath, `${JSON.stringify(entry)}\n`, 'utf8');
+    };
+    const appendPendingEntry = async () => {
+        const safeRunId = entry.run_id.replace(/[^a-zA-Z0-9._-]+/g, '_');
+        await mkdir(pendingDir, { recursive: true });
+        for (let attempt = 0; attempt < 5; attempt += 1) {
+            const pendingName = `${safeRunId}-${Date.now()}-${randomUUID()}.jsonl`;
+            const pendingPath = join(pendingDir, pendingName);
+            const tmpPath = `${pendingPath}.tmp`;
+            try {
+                await writeFile(tmpPath, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', flag: 'wx' });
+                await rename(tmpPath, pendingPath);
+                return pendingPath;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST') {
+                    throw error;
+                }
+            }
+        }
+        throw new Error(`Failed to create pending metrics entry for ${entry.run_id}`);
+    };
+    const finalizeManifest = async (metricsRecorded) => {
+        if (!guardrailsPresent && guardrailStatus.recommendation) {
+            logger.warn(guardrailStatus.recommendation);
+            appendSummary(manifest, guardrailStatus.recommendation);
+        }
+        upsertGuardrailSummary(manifest);
+        manifest.metrics_recorded = metricsRecorded;
+        await persistManifest(paths, manifest, persister, { force: true });
+    };
+    const { acquired } = await withMetricsLock(env, async () => {
+        await mergePendingMetricsEntries(env);
+        await appendEntry();
+        await finalizeManifest(true);
+        await updateMetricsAggregates(env);
+        const mergedAfter = await mergePendingMetricsEntries(env);
+        if (mergedAfter > 0) {
+            await updateMetricsAggregates(env);
+        }
+    });
+    if (!acquired) {
+        const pendingPath = await appendPendingEntry();
+        await finalizeManifest(false);
+        logger.warn(`Metrics aggregation skipped for ${env.taskId}: queued metrics entry in ${pendingPath}.`);
+    }
+}