@kbediako/codex-orchestrator 0.1.0

package/dist/orchestrator/src/cli/utils/packageInfo.js

@@ -0,0 +1,25 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+export function findPackageRoot(fromUrl = import.meta.url) {
+    let current = dirname(fileURLToPath(fromUrl));
+    while (current) {
+        const candidate = join(current, 'package.json');
+        if (existsSync(candidate)) {
+            return current;
+        }
+        const parent = dirname(current);
+        if (parent === current) {
+            current = null;
+            continue;
+        }
+        current = parent;
+    }
+    throw new Error('Unable to locate package.json');
+}
+export function loadPackageInfo(fromUrl = import.meta.url) {
+    const root = findPackageRoot(fromUrl);
+    const pkgPath = join(root, 'package.json');
+    const raw = readFileSync(pkgPath, 'utf8');
+    return JSON.parse(raw);
+}

package/dist/orchestrator/src/cli/utils/planFormatter.js

@@ -0,0 +1,49 @@
+export function formatPlanPreview(result) {
+    const lines = [];
+    lines.push(`Pipeline: ${result.pipeline.id} — ${result.pipeline.title} [${result.pipeline.source}]`);
+    if (result.pipeline.description) {
+        lines.push(`Description: ${result.pipeline.description}`);
+    }
+    lines.push('Stages:');
+    if (result.stages.length === 0) {
+        lines.push('  (none)');
+    }
+    else {
+        for (const stage of result.stages) {
+            lines.push(...formatStage(stage));
+        }
+    }
+    if (result.plan.notes) {
+        lines.push(`Notes: ${result.plan.notes}`);
+    }
+    return lines.join('\n');
+}
+function formatStage(stage) {
+    if (stage.kind === 'command') {
+        const lines = [
+            `  ${stage.index}. [command] ${stage.title} (${stage.id})`,
+            `     command: ${stage.command}`
+        ];
+        if (stage.cwd) {
+            lines.push(`     cwd: ${stage.cwd}`);
+        }
+        if (stage.env && Object.keys(stage.env).length > 0) {
+            lines.push(`     env: ${Object.entries(stage.env).map(([key, value]) => `${key}=${value}`).join(', ')}`);
+        }
+        if (stage.allowFailure) {
+            lines.push('     allowFailure: true');
+        }
+        if (stage.summaryHint) {
+            lines.push(`     summaryHint: ${stage.summaryHint}`);
+        }
+        return lines;
+    }
+    const lines = [
+        `  ${stage.index}. [subpipeline] ${stage.title} (${stage.id})`,
+        `     pipeline: ${stage.pipeline}`
+    ];
+    if (stage.optional) {
+        lines.push('     optional: true');
+    }
+    return lines;
+}

package/dist/orchestrator/src/cli/utils/runId.js

@@ -0,0 +1,7 @@
+import { randomBytes } from 'node:crypto';
+import { timestampForRunId } from './time.js';
+export function generateRunId() {
+    const ts = timestampForRunId();
+    const suffix = randomBytes(4).toString('hex');
+    return `${ts}-${suffix}`;
+}

package/dist/orchestrator/src/cli/utils/specGuardRunner.js

@@ -0,0 +1,26 @@
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { logger } from '../../logger.js';
+const specGuardPath = join(process.cwd(), 'scripts', 'spec-guard.mjs');
+if (!existsSync(specGuardPath)) {
+    logger.warn(`[spec-guard] skipped: ${specGuardPath} not found`);
+    process.exit(0);
+}
+const child = spawn(process.execPath, [specGuardPath, ...process.argv.slice(2)], {
+    stdio: 'inherit'
+});
+child.on('error', (error) => {
+    logger.error(`[spec-guard] failed: ${error.message}`);
+    process.exit(1);
+});
+child.on('exit', (code, signal) => {
+    if (typeof code === 'number') {
+        process.exit(code);
+    }
+    if (signal) {
+        logger.error(`[spec-guard] exited with signal ${signal}`);
+    }
+    process.exit(1);
+});

package/dist/orchestrator/src/cli/utils/strings.js

@@ -0,0 +1,8 @@
+export function slugify(value, fallback = 'command') {
+    const cleaned = value.trim().replace(/[^a-zA-Z0-9]+/g, '-').replace(/-+/g, '-');
+    const normalized = cleaned.replace(/^-|-$/g, '');
+    if (!normalized) {
+        return fallback;
+    }
+    return normalized.slice(0, 80);
+}

package/dist/orchestrator/src/cli/utils/time.js

@@ -0,0 +1,6 @@
+export function isoTimestamp(date = new Date()) {
+    return date.toISOString();
+}
+export function timestampForRunId(date = new Date()) {
+    return isoTimestamp(date).replace(/[:.]/g, '-');
+}

package/dist/orchestrator/src/control-plane/drift-reporter.js

@@ -0,0 +1,109 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { CONTROL_PLANE_RUN_REQUEST_SCHEMA, CONTROL_PLANE_RUN_REQUEST_VERSION } from '../../../packages/control-plane-schemas/src/index.js';
+const DEFAULT_MAX_ENTRIES = 50;
+export class ControlPlaneDriftReporter {
+    options;
+    reportPath;
+    read;
+    write;
+    ensureDir;
+    maxEntries;
+    constructor(options) {
+        this.options = options;
+        this.reportPath =
+            options.outputPath ??
+                join(options.repoRoot, 'out', options.taskId, 'control-plane', 'drift.json');
+        this.read = options.fs?.readFile ?? readFile;
+        this.write = options.fs?.writeFile ?? writeFile;
+        this.ensureDir = options.fs?.mkdir ?? mkdir;
+        this.maxEntries = options.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    get path() {
+        return this.reportPath;
+    }
+    async record(entry) {
+        const state = await this.load();
+        state.total_samples += 1;
+        if (!entry.valid) {
+            state.invalid_samples += 1;
+        }
+        state.invalid_rate =
+            state.total_samples === 0 ? 0 : state.invalid_samples / state.total_samples;
+        state.last_sampled_at = entry.timestamp;
+        state.mode = entry.mode;
+        if (!entry.valid) {
+            state.entries.push({
+                request_id: entry.requestId,
+                timestamp: entry.timestamp,
+                status: 'failed',
+                mode: entry.mode,
+                errors: entry.errors.map((error) => ({ ...error }))
+            });
+        }
+        else if (state.entries.length === 0) {
+            // Keep at least one success sample for context when no failures are present.
+            state.entries.push({
+                request_id: entry.requestId,
+                timestamp: entry.timestamp,
+                status: 'passed',
+                mode: entry.mode
+            });
+        }
+        if (state.entries.length > this.maxEntries) {
+            state.entries.splice(0, state.entries.length - this.maxEntries);
+        }
+        await this.persist(state);
+        return {
+            mode: state.mode,
+            absoluteReportPath: this.reportPath,
+            totalSamples: state.total_samples,
+            invalidSamples: state.invalid_samples,
+            invalidRate: state.invalid_rate,
+            lastSampledAt: state.last_sampled_at
+        };
+    }
+    async load() {
+        try {
+            const raw = await this.read(this.reportPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (!parsed || typeof parsed !== 'object') {
+                return this.createInitialState();
+            }
+            const entries = Array.isArray(parsed.entries) ? parsed.entries : [];
+            return {
+                schema_id: parsed.schema_id ?? CONTROL_PLANE_RUN_REQUEST_SCHEMA,
+                schema_version: parsed.schema_version ?? CONTROL_PLANE_RUN_REQUEST_VERSION,
+                total_samples: typeof parsed.total_samples === 'number' ? parsed.total_samples : 0,
+                invalid_samples: typeof parsed.invalid_samples === 'number' ? parsed.invalid_samples : 0,
+                invalid_rate: typeof parsed.invalid_rate === 'number' ? parsed.invalid_rate : 0,
+                last_sampled_at: typeof parsed.last_sampled_at === 'string' ? parsed.last_sampled_at : null,
+                mode: parsed.mode ?? 'shadow',
+                entries
+            };
+        }
+        catch (error) {
+            if (error?.code === 'ENOENT') {
+                return this.createInitialState();
+            }
+            throw error;
+        }
+    }
+    async persist(state) {
+        await this.ensureDir(dirname(this.reportPath), { recursive: true });
+        const serialized = JSON.stringify(state, null, 2);
+        await this.write(this.reportPath, `${serialized}\n`, 'utf8');
+    }
+    createInitialState() {
+        return {
+            schema_id: CONTROL_PLANE_RUN_REQUEST_SCHEMA,
+            schema_version: CONTROL_PLANE_RUN_REQUEST_VERSION,
+            total_samples: 0,
+            invalid_samples: 0,
+            invalid_rate: 0,
+            last_sampled_at: null,
+            mode: 'shadow',
+            entries: []
+        };
+    }
+}

package/dist/orchestrator/src/control-plane/index.js

@@ -0,0 +1,3 @@
+export { buildRunRequestV2 } from './request-builder.js';
+export { ControlPlaneDriftReporter } from './drift-reporter.js';
+export { ControlPlaneValidator, ControlPlaneValidationError } from './validator.js';

package/dist/orchestrator/src/control-plane/request-builder.js

@@ -0,0 +1,217 @@
+import { CONTROL_PLANE_RUN_REQUEST_SCHEMA, CONTROL_PLANE_RUN_REQUEST_VERSION } from '../../../packages/control-plane-schemas/src/index.js';
+import { logger } from '../logger.js';
+const DEFAULT_HEARTBEAT_INTERVAL_SECONDS = 30;
+const DEFAULT_HEARTBEAT_TIMEOUT_SECONDS = 120;
+const DEFAULT_RECOVERY_RETRIES = 3;
+const DEFAULT_MAX_SUBSCRIBERS = 8;
+const DEFAULT_BACKPRESSURE_MS = 250;
+const DEFAULT_POLICY_VERSION = '2025-10-01';
+const DEFAULT_METRIC_INTERVAL_SECONDS = 30;
+const DEFAULT_REQUIRED_DIMENSIONS = ['instanceId', 'phase', 'status'];
+const DEFAULT_TFGRPO_EPOCHS = 3;
+const DEFAULT_TFGRPO_SAMPLE_SIZE = 100;
+const DEFAULT_TFGRPO_TRAIN_TEMP = 0.7;
+const DEFAULT_TFGRPO_EVAL_TEMP = 0.3;
+const DEFAULT_TFGRPO_GROUP_SIZE = 2;
+export function buildRunRequestV2(options) {
+    const { runId, task, pipeline, manifest, env } = options;
+    const now = options.now ?? (() => new Date());
+    const capabilities = pipeline.tags && pipeline.tags.length > 0 ? [...pipeline.tags] : ['general'];
+    const stages = pipeline.stages.map((stage) => {
+        if (stage.kind === 'command') {
+            const entry = {
+                id: stage.id,
+                kind: 'command',
+                title: stage.title,
+                optional: Boolean(stage.allowFailure)
+            };
+            if (stage.session?.id) {
+                entry.capabilities = [`session:${stage.session.id}`];
+            }
+            return entry;
+        }
+        return {
+            id: stage.id,
+            kind: 'subpipeline',
+            title: stage.title,
+            optional: Boolean(stage.optional)
+        };
+    });
+    const fanOut = capabilities.map((capability) => ({
+        capability,
+        weight: 1,
+        maxConcurrency: capability === 'general' ? 2 : 1
+    }));
+    const fanOutCapacity = computeFanOutCapacity(fanOut);
+    const groupSize = resolveGroupSize(manifest);
+    const scheduleBounds = resolveScheduleBounds({
+        defaultMin: 1,
+        defaultMax: Math.max(1, fanOut.length),
+        fanOutCapacity,
+        groupSize
+    });
+    const constraints = {
+        privacyLevel: 'standard',
+        policyVersion: DEFAULT_POLICY_VERSION
+    };
+    const metadata = {
+        artifactRoot: manifest.artifact_root,
+        runsRoot: env.runsRoot,
+        outRoot: env.outRoot,
+        pipelineId: pipeline.id,
+        taskSlug: task.metadata?.slug ?? null
+    };
+    const tfgrpoMetadata = resolveTfgrpoMetadata(groupSize);
+    if (tfgrpoMetadata) {
+        metadata.tfgrpo = tfgrpoMetadata;
+    }
+    return {
+        schema: CONTROL_PLANE_RUN_REQUEST_SCHEMA,
+        version: CONTROL_PLANE_RUN_REQUEST_VERSION,
+        requestId: runId,
+        task: {
+            id: task.id,
+            slug: task.metadata?.slug ? String(task.metadata.slug) : undefined,
+            title: task.title,
+            description: task.description,
+            metadata: task.metadata,
+            tags: capabilities
+        },
+        pipeline: {
+            id: pipeline.id,
+            version: '1.0.0',
+            title: pipeline.title,
+            capabilities,
+            stages
+        },
+        schedule: {
+            strategy: 'auto',
+            minInstances: scheduleBounds.minInstances,
+            maxInstances: scheduleBounds.maxInstances,
+            fanOut,
+            recovery: {
+                heartbeatIntervalSeconds: DEFAULT_HEARTBEAT_INTERVAL_SECONDS,
+                missingHeartbeatTimeoutSeconds: DEFAULT_HEARTBEAT_TIMEOUT_SECONDS,
+                maxRetries: DEFAULT_RECOVERY_RETRIES
+            }
+        },
+        streaming: {
+            handles: true,
+            resumeSupported: true,
+            observers: {
+                maxSubscribers: DEFAULT_MAX_SUBSCRIBERS,
+                defaultBackpressureMs: DEFAULT_BACKPRESSURE_MS
+            }
+        },
+        constraints,
+        metrics: {
+            emitIntervalSeconds: DEFAULT_METRIC_INTERVAL_SECONDS,
+            requiredDimensions: DEFAULT_REQUIRED_DIMENSIONS
+        },
+        requestedAt: now().toISOString(),
+        requestedBy: options.requestedBy ?? {
+            actorId: 'codex-cli',
+            channel: 'cli',
+            name: 'Codex CLI'
+        },
+        metadata
+    };
+}
+function resolveTfgrpoMetadata(groupSize) {
+    const sampleSize = parsePositiveInteger(process.env.TFGRPO_SAMPLE_SIZE);
+    const epochs = parsePositiveInteger(process.env.TFGRPO_EPOCHS);
+    const trainTemp = parseFloatSafe(process.env.TFGRPO_TRAIN_TEMP);
+    const evalTemp = parseFloatSafe(process.env.TFGRPO_EVAL_TEMP);
+    const hasGroupSize = groupSize !== null;
+    if (!hasGroupSize && sampleSize === null && epochs === null && trainTemp === null && evalTemp === null) {
+        return null;
+    }
+    const metadata = {
+        sampleSize: sampleSize ?? DEFAULT_TFGRPO_SAMPLE_SIZE,
+        epochs: epochs ?? DEFAULT_TFGRPO_EPOCHS,
+        temperature: {
+            train: trainTemp ?? DEFAULT_TFGRPO_TRAIN_TEMP,
+            eval: evalTemp ?? DEFAULT_TFGRPO_EVAL_TEMP
+        }
+    };
+    if (hasGroupSize && groupSize !== null) {
+        metadata.groupSize = groupSize;
+    }
+    return metadata;
+}
+function parsePositiveInteger(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseInt(value, 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        return null;
+    }
+    return parsed;
+}
+function parseFloatSafe(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Number.parseFloat(value);
+    if (Number.isNaN(parsed)) {
+        return null;
+    }
+    return parsed;
+}
+function computeFanOutCapacity(fanOut) {
+    return fanOut.reduce((total, entry) => {
+        const capacity = entry?.maxConcurrency ?? 1;
+        return total + Math.max(1, capacity);
+    }, 0);
+}
+function resolveGroupSize(manifest, env = process.env) {
+    const envSize = parsePositiveInteger(env.TFGRPO_GROUP_SIZE);
+    if (envSize !== null) {
+        return envSize;
+    }
+    const manifestSize = typeof manifest.tfgrpo?.group_size === 'number' && Number.isFinite(manifest.tfgrpo.group_size)
+        ? manifest.tfgrpo.group_size
+        : null;
+    if (manifestSize !== null && manifestSize > 0) {
+        return manifestSize;
+    }
+    if (isFeatureEnabled(env.FEATURE_TFGRPO_GROUP)) {
+        return DEFAULT_TFGRPO_GROUP_SIZE;
+    }
+    return null;
+}
+function resolveScheduleBounds(params) {
+    if (params.groupSize === null) {
+        const maxInstances = Math.min(params.defaultMax, params.fanOutCapacity);
+        return {
+            minInstances: params.defaultMin,
+            maxInstances: Math.max(params.defaultMin, maxInstances)
+        };
+    }
+    if (params.groupSize < 2) {
+        logGroupGuard(`TF-GRPO groupSize ${params.groupSize} violates guardrail (must be ≥ 2). ` +
+            'Set TFGRPO_GROUP_SIZE>=2 or disable FEATURE_TFGRPO_GROUP.');
+        throw new Error('TF-GRPO groupSize guardrail violated (expected ≥ 2).');
+    }
+    if (params.groupSize > params.fanOutCapacity) {
+        logGroupGuard(`TF-GRPO groupSize ${params.groupSize} exceeds available fan-out capacity (${params.fanOutCapacity}). ` +
+            'Increase pipeline fan-out or lower TFGRPO_GROUP_SIZE.');
+        throw new Error('TF-GRPO groupSize exceeds available scheduling capacity.');
+    }
+    const cappedMax = Math.min(params.fanOutCapacity, params.groupSize);
+    return {
+        minInstances: params.groupSize,
+        maxInstances: cappedMax
+    };
+}
+function isFeatureEnabled(value) {
+    if (!value) {
+        return false;
+    }
+    const normalized = value.trim().toLowerCase();
+    return ['1', 'true', 'on', 'yes'].includes(normalized);
+}
+function logGroupGuard(message) {
+    logger.error(`[control-plane.guard] ${message}`);
+}

package/dist/orchestrator/src/control-plane/types.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrator/src/control-plane/validator.js

@@ -0,0 +1,50 @@
+import { validateRunRequestV2 } from '../../../packages/control-plane-schemas/src/index.js';
+const DEFAULT_MODE = 'shadow';
+export class ControlPlaneValidationError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.result = result;
+        this.name = 'ControlPlaneValidationError';
+    }
+}
+export class ControlPlaneValidator {
+    mode;
+    driftReporter;
+    now;
+    constructor(options = {}) {
+        this.mode = options.mode ?? DEFAULT_MODE;
+        this.driftReporter = options.driftReporter;
+        this.now = options.now ?? (() => new Date());
+    }
+    async validate(request) {
+        const timestamp = this.now().toISOString();
+        const evaluation = validateRunRequestV2(request);
+        const canonicalRequest = evaluation.valid ? evaluation.value : request;
+        const errors = evaluation.valid ? [] : evaluation.errors.map((error) => ({ ...error }));
+        const drift = this.driftReporter
+            ? await this.driftReporter.record({
+                requestId: canonicalRequest.requestId,
+                timestamp,
+                mode: this.mode,
+                valid: evaluation.valid,
+                errors
+            })
+            : undefined;
+        const outcome = {
+            mode: this.mode,
+            status: evaluation.valid ? 'passed' : 'failed',
+            timestamp,
+            errors,
+            drift
+        };
+        const result = {
+            request: canonicalRequest,
+            outcome
+        };
+        if (!evaluation.valid && this.mode === 'enforce') {
+            throw new ControlPlaneValidationError(`Control plane validation failed (${errors.length} error${errors.length === 1 ? '' : 's'}).`, result);
+        }
+        return result;
+    }
+}

package/dist/orchestrator/src/credentials/CredentialBroker.js

@@ -0,0 +1 @@
+export {};

package/dist/orchestrator/src/events/EventBus.js

@@ -0,0 +1,25 @@
+import { EventEmitter } from 'node:events';
+/**
+ * Lightweight typed event bus so the manager can notify downstream subscribers
+ * (e.g. cloud-sync worker) whenever orchestration milestones complete.
+ */
+export class EventBus {
+    emitter = new EventEmitter({ captureRejections: false });
+    emit(event) {
+        this.emitter.emit(event.type, event);
+    }
+    on(event, listener) {
+        const wrapped = (payload) => listener(payload);
+        this.emitter.on(event, wrapped);
+        return () => {
+            this.emitter.off(event, wrapped);
+        };
+    }
+    once(event, listener) {
+        const wrapped = (payload) => listener(payload);
+        this.emitter.once(event, wrapped);
+        return () => {
+            this.emitter.off(event, wrapped);
+        };
+    }
+}

package/dist/orchestrator/src/learning/crystalizer.js

@@ -0,0 +1,108 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { mkdtemp, readFile, writeFile, mkdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, relative } from 'node:path';
+import { isoTimestamp } from '../cli/utils/time.js';
+import { slugify } from '../cli/utils/strings.js';
+import { appendLearningAlert, ensureLearningSection } from './manifest.js';
+import { computePromptPackStamp, loadPromptPacks } from '../../../packages/orchestrator/src/instructions/promptPacks.js';
+const DEFAULT_PROMPT_PACK = 'crystalizer-v1';
+const DEFAULT_OUTPUT_DIR = '.agent/patterns/candidates';
+const DEFAULT_MODEL = process.env.CRYSTALIZER_MODEL || 'gpt-5.1-codex-max';
+const DEFAULT_BUDGET = 0.5;
+export async function runCrystalizer(options) {
+    const { manifest, client, problemStatement, validatedPatch, scenarioSummary = null, repoRoot = process.cwd(), outputDir = DEFAULT_OUTPUT_DIR, promptPackId = DEFAULT_PROMPT_PACK, model = DEFAULT_MODEL, budgetUsd = DEFAULT_BUDGET } = options;
+    if (outputDir.includes('docs/patterns')) {
+        throw new Error('Crystalizer output may not be written to docs/patterns; use .agent/patterns instead.');
+    }
+    const learning = ensureLearningSection(manifest);
+    const packs = await loadPromptPacks(repoRoot);
+    const pack = packs.find((entry) => entry.id === promptPackId);
+    if (!pack) {
+        throw new Error(`Prompt pack ${promptPackId} not found`);
+    }
+    const packStamp = computePromptPackStamp(pack.sources);
+    const promptSources = pack.sources.map((source) => source.content).join('\n\n');
+    const prompt = composePrompt(promptSources, packStamp, problemStatement, validatedPatch, scenarioSummary ?? '');
+    const response = await client.generate(prompt, { model });
+    const cost = typeof response.costUsd === 'number' ? response.costUsd : 0;
+    if (cost > budgetUsd) {
+        appendLearningAlert(manifest, {
+            type: 'budget_exceeded',
+            channel: 'slack',
+            target: '#learning-alerts',
+            message: `Crystalizer cost ${cost.toFixed(2)} exceeded budget ${budgetUsd.toFixed(2)}`
+        });
+        learning.crystalizer = {
+            candidate_path: null,
+            model,
+            prompt_pack: promptPackId,
+            prompt_pack_stamp: packStamp,
+            budget_usd: budgetUsd,
+            cost_usd: cost,
+            status: 'failed',
+            error: 'budget_exceeded',
+            created_at: isoTimestamp()
+        };
+        return { manifest, candidatePath: null };
+    }
+    const candidateDir = join(repoRoot, outputDir);
+    await mkdir(candidateDir, { recursive: true });
+    const baseSlug = slugify(problemStatement || 'learning');
+    const slug = baseSlug.slice(0, 60) || 'learning';
+    const candidatePath = join(candidateDir, `${slug}.md`);
+    const markdown = [
+        '# Problem',
+        problemStatement || 'Not provided',
+        '',
+        '## Solution',
+        response.content.trim(),
+        '',
+        '## Rationale',
+        scenarioSummary ? scenarioSummary : 'Captured from validation run.'
+    ].join('\n');
+    await writeFile(candidatePath, markdown, 'utf8');
+    learning.crystalizer = {
+        candidate_path: relative(repoRoot, candidatePath),
+        model: response.model ?? model,
+        prompt_pack: promptPackId,
+        prompt_pack_stamp: packStamp,
+        budget_usd: budgetUsd,
+        cost_usd: cost,
+        status: 'succeeded',
+        created_at: isoTimestamp()
+    };
+    return { manifest, candidatePath };
+}
+function composePrompt(promptBody, packStamp, problem, patch, scenarioSummary) {
+    const segments = [
+        `Prompt-Pack: ${packStamp}`,
+        promptBody,
+        'You are the crystalizer. Produce a concise pattern with Problem, Solution, and Rationale.',
+        `Problem:\n${problem}`,
+        `Patch:\n${patch}`,
+        scenarioSummary ? `Scenario:\n${scenarioSummary}` : ''
+    ];
+    return segments.filter(Boolean).join('\n\n');
+}
+export async function createCodexCliCrystalizerClient(binary = process.env.CODEX_CLI_BIN ?? 'codex') {
+    const execFileAsync = promisify(execFile);
+    return {
+        async generate(prompt, options) {
+            const workDir = await mkdtemp(join(tmpdir(), 'crystalizer-'));
+            try {
+                const promptPath = join(workDir, 'prompt.txt');
+                const outputPath = join(workDir, 'output.txt');
+                await writeFile(promptPath, prompt, 'utf8');
+                const args = ['chat', '--model', options.model, '--input-file', promptPath, '--output-file', outputPath];
+                await execFileAsync(binary, args, { env: { ...process.env } });
+                const content = await readFile(outputPath, 'utf8');
+                return { content: content.trim(), model: options.model };
+            }
+            finally {
+                await rm(workDir, { recursive: true, force: true });
+            }
+        }
+    };
+}