orizu 0.5.18 → 0.5.20

package/README.md

@@ -25,6 +25,29 @@ Note: the one task we do _not_ let you perform from your CLI is any reviews assi
 
 By default, the CLI talks to `https://orizu.ai`.
 
+## Updating bundled GEPA
+
+The CLI ships a verified, source-only copy of official GEPA so optimization
+users never need `pip` or a network connection. To upgrade it, make a PR that
+updates the version, release commit, and SHA-256 pin in
+`scripts/vendor-gepa-python.mjs`, then re-runs the refresh command with the
+matching downloaded wheel:
+
+```bash
+node scripts/vendor-gepa-python.mjs --refresh --archive /path/to/gepa-<version>-py3-none-any.whl
+```
+
+Commit the refreshed `gepa-python-source.zip` and run the CLI packaging test.
+`npm pack` verifies that archive and materializes only the shipped source tree;
+it never downloads GEPA.
+
+For a development checkout, materialize that same verified source before local
+work that imports GEPA:
+
+```bash
+node scripts/vendor-gepa-python.mjs
+```
+
 ## Install
 
 Install the CLI globally with your package manager:

package/dist/diff-comments-cli.js

@@ -1,5 +1,6 @@
 import { extractErrorMessage, isJsonErrorResponsePayload, } from './error-response.js';
 import { sanitizeHumanInlineText } from './json-response.js';
+import { formatFiniteLengthCount, } from './prompt-length-wire.js';
 const DETAIL_LEVELS = ['hunk', 'diff', 'full'];
 const CONTEXT_UNAVAILABLE_WITHOUT_REASON = '    Context unavailable (no reason supplied)';
 function isCandidatePair(pair) {
@@ -47,6 +48,72 @@ function humanLineNumber(ctx, line) {
         ? '-'
         : sanitizeHumanInlineText(ctx.sanitizeTerminalText, String(line + 1));
 }
+function formatStats(stats) {
+    const tokens = formatFiniteLengthCount(stats.tokens);
+    return `${tokens === null ? '—' : `~${tokens}`} tokens · ` +
+        `${formatFiniteLengthCount(stats.lines) ?? '—'} lines · ` +
+        `${formatFiniteLengthCount(stats.chars) ?? '—'} chars · ` +
+        `${formatFiniteLengthCount(stats.words) ?? '—'} words`;
+}
+function formatDeltaValue(value, metric, signed = false) {
+    const formatted = formatFiniteLengthCount(value, signed);
+    if (formatted === null)
+        return '—';
+    return metric === 'tokens' ? `~${formatted}` : formatted;
+}
+function isLengthMetricDelta(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const delta = value;
+    const isNullableFiniteNumber = (candidate) => candidate === null || (typeof candidate === 'number' && Number.isFinite(candidate));
+    return isNullableFiniteNumber(delta.removed) &&
+        isNullableFiniteNumber(delta.added) &&
+        isNullableFiniteNumber(delta.net);
+}
+function printLengthMeasurements(ctx, pair) {
+    function unavailableSuffix(reason) {
+        if (typeof reason !== 'string' || reason.length === 0)
+            return '';
+        return ` (${sanitizeHumanInlineText(ctx.sanitizeTerminalText, reason)})`;
+    }
+    if (!pair.lengthStats && !pair.lengthDelta) {
+        ctx.printLine(`  Length: unavailable${unavailableSuffix(pair.lengthDeltaUnavailableReason ?? pair.degraded?.reason)}`);
+        return;
+    }
+    if (pair.lengthStats) {
+        ctx.printLine(pair.lengthStats.from
+            ? `  From: ${formatStats(pair.lengthStats.from)}`
+            : `  From: unavailable${unavailableSuffix(pair.lengthStats.fromUnavailableReason)}`);
+        ctx.printLine(pair.lengthStats.to
+            ? `  To: ${formatStats(pair.lengthStats.to)}`
+            : `  To: unavailable${unavailableSuffix(pair.lengthStats.toUnavailableReason)}`);
+    }
+    if (!pair.lengthDelta) {
+        ctx.printLine(`  Length delta: unavailable${unavailableSuffix(pair.lengthDeltaUnavailableReason ?? pair.degraded?.reason)}`);
+        return;
+    }
+    const splitUnavailableReason = pair.lengthDelta.splitUnavailableReason;
+    if (typeof splitUnavailableReason === 'string' &&
+        splitUnavailableReason.length > 0) {
+        ctx.printLine(`  Split unavailable: ${sanitizeHumanInlineText(ctx.sanitizeTerminalText, splitUnavailableReason)}`);
+    }
+    for (const [metric, label] of [
+        ['tokens', 'Tokens'],
+        ['lines', 'Lines'],
+        ['chars', 'Chars'],
+        ['words', 'Words'],
+    ]) {
+        const delta = pair.lengthDelta[metric];
+        if (!isLengthMetricDelta(delta)) {
+            ctx.printLine(`  ${label}: unavailable`);
+            continue;
+        }
+        ctx.printLine(`  ${label}: removed ${formatDeltaValue(delta.removed, metric)} · ` +
+            `added ${formatDeltaValue(delta.added, metric)} · ` +
+            `net ${formatDeltaValue(delta.net, metric, true)}`);
+    }
+}
 function buildParams(ctx) {
     const runId = ctx.getArg('--run');
     const promptId = ctx.getArg('--prompt');
@@ -106,6 +173,7 @@ function printDiffComments(ctx, payload) {
         ctx.printLine(`${hasCandidateIds ? 'Candidates' : 'Versions'} ` +
             `${sanitizeHumanInlineText(ctx.sanitizeTerminalText, from)} → ` +
             `${sanitizeHumanInlineText(ctx.sanitizeTerminalText, to)}`);
+        printLengthMeasurements(ctx, pair);
         if (pair.degraded) {
             ctx.printLine(`  Context unavailable: ${sanitizeHumanInlineText(ctx.sanitizeTerminalText, pair.degraded.reason)}`);
         }

package/dist/gepa-engine-dispatch.js

@@ -0,0 +1,261 @@
+import { existsSync, readFileSync } from 'fs';
+const VALUE_OPTIONS = [
+    { flag: '--optimizer-version-id', environment: 'ORIZU_OPTIMIZER_VERSION_ID' },
+    { flag: '--candidate-version-id', environment: 'ORIZU_PROMPT_VERSION_ID' },
+    { flag: '--runner-version-id', environment: 'ORIZU_RUNNER_VERSION_ID' },
+    { flag: '--candidate-runner-dir', environment: 'ORIZU_CANDIDATE_RUNNER_DIR' },
+    { flag: '--scorer-version-id', environment: 'ORIZU_SCORER_VERSION_ID' },
+    { flag: '--scorer-runner-version-id', environment: 'ORIZU_SCORER_RUNNER_VERSION_ID' },
+    { flag: '--scorer-runner-dir', environment: 'ORIZU_SCORER_RUNNER_DIR' },
+    { flag: '--scorer-input-contract', environment: 'ORIZU_SCORER_INPUT_CONTRACT' },
+    { flag: '--scorer-candidate-field', environment: 'ORIZU_SCORER_CANDIDATE_FIELD' },
+    { flag: '--dataset-version-id', environment: 'ORIZU_DATASET_VERSION_ID' },
+    { flag: '--split-set-id', environment: 'ORIZU_SPLIT_SET_ID' },
+    { flag: '--train-split', environment: 'ORIZU_TRAIN_SPLIT', allowEmpty: true },
+    { flag: '--val-split', environment: 'ORIZU_VALIDATION_SPLIT', allowEmpty: true },
+    { flag: '--budget', environment: 'ORIZU_BUDGET' },
+    { flag: '--max-iterations', environment: 'ORIZU_MAX_ITERATIONS' },
+    { flag: '--max-candidate-proposals', environment: 'ORIZU_MAX_CANDIDATE_PROPOSALS' },
+    { flag: '--max-full-evals', environment: 'ORIZU_MAX_FULL_EVALS' },
+    { flag: '--max-metric-calls', environment: 'ORIZU_MAX_METRIC_CALLS' },
+    { flag: '--minibatch-size', environment: 'ORIZU_MINIBATCH_SIZE' },
+    { flag: '--num-threads', environment: 'ORIZU_NUM_THREADS' },
+    { flag: '--candidate-selection-strategy', environment: 'ORIZU_CANDIDATE_SELECTION_STRATEGY' },
+    { flag: '--epsilon', environment: 'ORIZU_EPSILON' },
+    { flag: '--reflection-model', environment: 'ORIZU_REFLECTION_MODEL' },
+    { flag: '--reflection-temperature', environment: 'ORIZU_REFLECTION_TEMPERATURE' },
+    { flag: '--reflection-max-tokens', environment: 'ORIZU_REFLECTION_MAX_TOKENS' },
+    { flag: '--reflection-retry-attempts', environment: 'ORIZU_REFLECTION_RETRY_ATTEMPTS' },
+    { flag: '--reflection-http-timeout-seconds', environment: 'ORIZU_REFLECTION_HTTP_TIMEOUT_SECONDS' },
+    { flag: '--reflection-prompt-template', environment: 'ORIZU_REFLECTION_PROMPT_TEMPLATE', readFile: true },
+    { flag: '--reflection-provider-settings', environment: 'ORIZU_REFLECTION_PROVIDER_SETTINGS', readFile: true, json: true },
+    { flag: '--objective', environment: 'ORIZU_OBJECTIVE', allowEmpty: true },
+    { flag: '--seed', environment: 'ORIZU_SEED' },
+    { flag: '--promotion-label', environment: 'ORIZU_PROMOTION_LABEL', allowEmpty: true },
+    { flag: '--log-dir', environment: 'ORIZU_LOCAL_LOG_DIR' },
+];
+const BOOLEAN_OPTIONS = [
+    ['--allow-degenerate-seed', 'ORIZU_ALLOW_DEGENERATE_SEED', '1'],
+    ['--disable-evaluation-cache', 'ORIZU_DISABLE_EVALUATION_CACHE', '1'],
+    ['--auto-promote', 'ORIZU_AUTO_PROMOTE', '1'],
+    ['--log-row-snapshots', 'ORIZU_LOG_ROW_SNAPSHOTS', '1'],
+    ['--no-local-log', 'ORIZU_NO_LOCAL_LOG', '1'],
+    ['--skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '1'],
+    ['--no-skip-perfect-parent-reflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', '0'],
+];
+function textValue(value) {
+    if (value.startsWith('@'))
+        return readFileSync(value.slice(1), 'utf8');
+    const path = value;
+    return existsSync(path) ? readFileSync(path, 'utf8') : value;
+}
+function jsonObjectValue(value, flag) {
+    const raw = textValue(value);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error(`${flag} must be a JSON object`);
+    }
+    // Validate in JavaScript, but preserve the raw spelling for Python's JSON
+    // parser so large numbers and exponent forms do not lose precision here.
+    return raw;
+}
+function removeEngine(args) {
+    let engine;
+    const forwarded = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--engine') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--engine must be one of official, legacy');
+            }
+            if (engine !== undefined && engine !== value) {
+                throw new Error('--engine must select exactly one of official, legacy');
+            }
+            engine = value;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--engine=')) {
+            const value = argument.slice('--engine='.length);
+            if (engine !== undefined && engine !== value) {
+                throw new Error('--engine must select exactly one of official, legacy');
+            }
+            engine = value;
+            continue;
+        }
+        forwarded.push(argument);
+    }
+    if (engine !== undefined && engine !== 'official' && engine !== 'legacy') {
+        throw new Error(`--engine must be one of official, legacy; received ${engine}`);
+    }
+    return { engine: engine ?? 'official', args: forwarded };
+}
+function validateLegacyMetadata(args) {
+    let raw;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === '--metadata') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--metadata must be a JSON object');
+            }
+            raw = value;
+            index += 1;
+            continue;
+        }
+        if (args[index].startsWith('--metadata=')) {
+            raw = args[index].slice('--metadata='.length);
+        }
+    }
+    let metadata = {};
+    if (raw !== undefined) {
+        try {
+            // The frozen legacy CLI hands this value directly to json.loads. Do not
+            // add @file/path expansion here: only reflection inputs support it.
+            metadata = JSON.parse(raw);
+        }
+        catch {
+            throw new Error('--metadata must be a JSON object containing valid JSON');
+        }
+    }
+    if (typeof metadata !== 'object' || metadata === null || Array.isArray(metadata)) {
+        throw new Error('--metadata must be a JSON object');
+    }
+    // The frozen CLI consumes the original argv with json.loads. Keep the raw
+    // spelling so Python, not JavaScript, owns JSON number precision and adds
+    // the selected legacy-engine tag to the run metadata.
+}
+// Parsing starts from an arbitrary command-line string. Keep the literal
+// tuples above checked, then widen only the map boundary used for lookup.
+const VALUE_OPTIONS_BY_FLAG = new Map(VALUE_OPTIONS.map(option => [option.flag, option]));
+const BOOLEAN_OPTIONS_BY_FLAG = new Map(BOOLEAN_OPTIONS.map(([flag, environment, value]) => [flag, { environment, value }]));
+const CONTROLLED_ENVIRONMENT_NAMES = new Set([
+    'ORIZU_PROJECT',
+    'ORIZU_METADATA',
+    ...VALUE_OPTIONS.map(option => option.environment),
+    ...BOOLEAN_OPTIONS.map(([, environment]) => environment),
+    'ORIZU_USE_MERGE',
+    'ORIZU_MAX_MERGE_INVOCATIONS',
+    'ORIZU_SAMPLING_STRATEGY',
+    'ORIZU_SELECTION_STRATEGY',
+    'ORIZU_MAX_PAYLOAD_CHARS',
+]);
+function optionValueOrThrow(args, index, flag, allowEmpty = false) {
+    const argument = args[index];
+    const equalsPrefix = `${flag}=`;
+    if (argument.startsWith(equalsPrefix)) {
+        const value = argument.slice(equalsPrefix.length);
+        if ((!allowEmpty && value === '') || value.startsWith('--')) {
+            throw new Error(`${flag} requires a value that does not start with --`);
+        }
+        return { value, nextIndex: index };
+    }
+    const value = args[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+        throw new Error(`${flag} requires a value that does not start with --`);
+    }
+    return { value, nextIndex: index + 1 };
+}
+function translateOfficialOptions(args, project, environment) {
+    const connectorEnvironment = { ...environment };
+    for (const name of CONTROLLED_ENVIRONMENT_NAMES) {
+        delete connectorEnvironment[name];
+    }
+    connectorEnvironment.ORIZU_PROJECT = project;
+    let metadata;
+    const budgetFlags = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (!argument.startsWith('--')) {
+            throw new Error(`Unexpected run-gepa argument ${argument}`);
+        }
+        const flag = argument.includes('=') ? argument.slice(0, argument.indexOf('=')) : argument;
+        if (flag === '--project') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            connectorEnvironment.ORIZU_PROJECT = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        if (flag === '--metadata') {
+            const parsed = optionValueOrThrow(args, index, flag);
+            metadata = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        const option = VALUE_OPTIONS_BY_FLAG.get(flag);
+        if (option) {
+            const parsed = optionValueOrThrow(args, index, flag, option.allowEmpty);
+            if (flag === '--budget') {
+                if (!['auto', 'light', 'medium', 'heavy'].includes(parsed.value)) {
+                    throw new Error('--budget must be one of auto, light, medium, heavy');
+                }
+                budgetFlags.push(flag);
+            }
+            if (['--max-metric-calls', '--max-full-evals', '--max-iterations', '--max-candidate-proposals'].includes(flag)) {
+                budgetFlags.push(flag);
+            }
+            if (flag === '--candidate-selection-strategy' && !['pareto', 'current_best', 'epsilon_greedy'].includes(parsed.value)) {
+                throw new Error('--candidate-selection-strategy must be one of pareto, current_best, epsilon_greedy');
+            }
+            if (flag === '--scorer-input-contract' && !['gepa', 'flat_row'].includes(parsed.value)) {
+                throw new Error('--scorer-input-contract must be one of gepa, flat_row');
+            }
+            connectorEnvironment[option.environment] = option.json
+                ? jsonObjectValue(parsed.value, option.flag)
+                : option.readFile ? textValue(parsed.value) : parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+        const boolean = BOOLEAN_OPTIONS_BY_FLAG.get(flag);
+        if (boolean) {
+            if (argument.includes('=')) {
+                throw new Error(`${flag} does not accept a value`);
+            }
+            if (args[index + 1] !== undefined && !args[index + 1].startsWith('--')) {
+                throw new Error(`${flag} does not accept a value`);
+            }
+            connectorEnvironment[boolean.environment] = boolean.value;
+            continue;
+        }
+        throw new Error(`Unknown run-gepa option ${flag}`);
+    }
+    if (budgetFlags.length > 1) {
+        throw new Error('Budget options are mutually exclusive; choose at most one of --budget, --max-metric-calls, --max-full-evals, --max-iterations, --max-candidate-proposals');
+    }
+    const reflectionModel = connectorEnvironment.ORIZU_REFLECTION_MODEL ?? 'anthropic/claude-opus-4-7';
+    if (!reflectionModel.startsWith('openai/') && connectorEnvironment.ORIZU_REFLECTION_MAX_TOKENS === undefined) {
+        throw new Error('--reflection-max-tokens is required for Anthropic reflection models');
+    }
+    connectorEnvironment.ORIZU_METADATA = validatedMetadata(metadata);
+    return connectorEnvironment;
+}
+function validatedMetadata(raw) {
+    if (raw === undefined)
+        return '{}';
+    try {
+        const value = JSON.parse(raw);
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            throw new Error();
+    }
+    catch {
+        throw new Error('--metadata must be a JSON object containing valid JSON');
+    }
+    return raw;
+}
+export function dispatchGepaEngine(args, project, environment) {
+    const selected = removeEngine(args);
+    if (selected.engine === 'legacy') {
+        if (selected.args.some(argument => argument === '--max-candidate-proposals' || argument.startsWith('--max-candidate-proposals='))) {
+            throw new Error('--max-candidate-proposals is supported by the official GEPA engine only');
+        }
+        validateLegacyMetadata(selected.args);
+        return {
+            engine: 'legacy',
+            args: selected.args,
+            environment,
+            module: 'orizu_gepa.cli',
+        };
+    }
+    const connectorEnvironment = translateOfficialOptions(selected.args, project, environment);
+    return { engine: 'official', args: [], environment: connectorEnvironment, module: 'orizu_gepa_connector' };
+}

package/dist/gepa-python-command.js

@@ -0,0 +1,26 @@
+export function getGepaPythonCommand(args, environment) {
+    let python = environment.PYTHON || 'python3';
+    const forwarded = [];
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === '--python') {
+            const value = args[index + 1];
+            if (!value || value.startsWith('--')) {
+                throw new Error('--python requires a value that does not start with --');
+            }
+            python = value;
+            index += 1;
+            continue;
+        }
+        if (argument.startsWith('--python=')) {
+            const value = argument.slice('--python='.length);
+            if (!value || value.startsWith('--')) {
+                throw new Error('--python requires a value that does not start with --');
+            }
+            python = value;
+            continue;
+        }
+        forwarded.push(argument);
+    }
+    return { python, args: forwarded };
+}

package/dist/gepa-python-paths.js

@@ -0,0 +1,39 @@
+import { existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import { isOrizuSourceCheckout } from '../scripts/orizu-source-checkout.mjs';
+function prefersLiveSource() {
+    // The source candidates belong to this monorepo only when the candidate
+    // root identifies itself as Orizu. A consumer's .git marker is not proof:
+    // npm installs commonly live inside another repository.
+    return isOrizuSourceCheckout(fileURLToPath(new URL('../../../package.json', import.meta.url)));
+}
+export function resolveGepaPythonPath(candidates, pathExists = existsSync) {
+    return candidates.find(pathExists) ?? null;
+}
+export function bundledOrizuGepaPythonPath() {
+    const source = fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url));
+    const vendor = fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url));
+    const candidates = prefersLiveSource() ? [source, vendor] : [vendor];
+    return resolveGepaPythonPath(candidates);
+}
+export function bundledOrizuGepaConnectorPythonPath() {
+    const source = fileURLToPath(new URL('../../orizu-gepa/src', import.meta.url));
+    const vendor = fileURLToPath(new URL('../vendor/orizu-gepa/src', import.meta.url));
+    const candidates = prefersLiveSource() ? [source, vendor] : [vendor];
+    return resolveGepaPythonPath(candidates);
+}
+export function bundledOfficialGepaPythonPath() {
+    const candidates = [
+        fileURLToPath(new URL('../vendor/gepa-python/src', import.meta.url)),
+    ];
+    return resolveGepaPythonPath(candidates);
+}
+export function getGepaPythonPathEntries(existingPythonPath) {
+    const pythonPathEntries = [
+        bundledOrizuGepaConnectorPythonPath(),
+        bundledOrizuGepaPythonPath(),
+        bundledOfficialGepaPythonPath(),
+        existingPythonPath,
+    ].filter((entry) => Boolean(entry));
+    return pythonPathEntries;
+}

package/dist/help.js

@@ -343,13 +343,13 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['prompts', 'report', 'set'],
-        usage: 'orizu prompts report set --prompt <id-or-name> --project <team/project> (--version <n> | --version-id <id>) (--report <markdown|@file> | --report-file <path>) [--json]',
+        usage: 'orizu prompts report set --prompt <id-or-name> [--project <team/project>] (--version <n> | --version-id <id>) (--report <markdown|@file> | --report-file <path>) [--json]',
         summary: 'Upload or replace the Markdown report for one explicit prompt version.',
         group: 'Prompts and judges',
         aliases: [['prompts', 'report', 'upload']],
         options: [
             { name: '--prompt <id-or-name>', help: 'Prompt ID or name.', required: true },
-            { name: '--project <team/project>', help: 'Project slug containing the prompt.', required: true },
+            { name: '--project <team/project>', help: 'Project slug containing the prompt.' },
             { name: '--version <n>', help: 'Positive prompt version number.' },
             { name: '--version-id <id>', help: 'Explicit prompt version ID.' },
             { name: '--report <markdown|@file>', help: 'Inline Markdown or an @file reference.' },
@@ -525,8 +525,8 @@ export const COMMAND_DOCS = [
     },
     {
         path: ['optimizations', 'run-gepa'],
-        usage: 'orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs]',
-        summary: 'Run the bundled GEPA-style optimizer locally and stream events. Validates the scorer contract on the seed before iterating; judge runners built for flat-row score runs need --scorer-input-contract flat_row (ALI-1158).',
+        usage: 'orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> --candidate-version-id <id> --runner-version-id <id> --candidate-runner-dir <dir> --scorer-version-id <id> --scorer-runner-version-id <id> --scorer-runner-dir <dir> [--engine official|legacy] [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--budget auto|light|medium|heavy | --max-metric-calls <n> | --max-full-evals <n> | --max-iterations <n> | --max-candidate-proposals <n>] [--num-threads auto|N] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--log-dir logs]',
+        summary: 'Run official GEPA locally and stream events; pass --engine legacy only for the frozen safety hatch. --max-candidate-proposals is official-engine-only. Validates the scorer contract on the seed before iterating; judge runners built for flat-row score runs need --scorer-input-contract flat_row (ALI-1158).',
         group: 'Optimizations',
     },
     {

package/dist/index.js

@@ -43,14 +43,19 @@ import { runGitCredentialInvocation } from './git-credential.js';
 import { pushPromptDraft } from './prompt-draft-push.js';
 import { readMarkdownReportInput } from './markdown-report-input.js';
 import { promptPushErrorMessage, promptReportCommand } from './prompt-report-cli.js';
+import { printPromptSummaryTable } from './prompt-summary-table.js';
 import { assertSnapshotManifestConfined, verifyGepaRunnerDirsFromArgs, verifyRunnerDirRegistered } from './runner-dir-verify.js';
 import { runScorersRegister } from './scorer-draft-push.js';
 import { runZipArtifactPush } from './zip-draft-push.js';
 import { runGithubLink, runInteractiveHostedSetup } from './github-setup.js';
 import { parseJsonResponse, sanitizeTerminalText } from './json-response.js';
+import { reportReplacementWarning } from './report-replacement-warning.js';
 import { reportCommentsCommand, throwDeprecatedPromptCommentsCommand, } from './report-comments-cli.js';
 import { diffCommentsCommand } from './diff-comments-cli.js';
 import { exportOptimizationRunCommand } from './optimization-export-cli.js';
+import { dispatchGepaEngine } from './gepa-engine-dispatch.js';
+import { getGepaPythonCommand } from './gepa-python-command.js';
+import { getGepaPythonPathEntries } from './gepa-python-paths.js';
 export { parseJsonResponse, sanitizeTerminalText } from './json-response.js';
 function getErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
@@ -184,6 +189,14 @@ export function createCodeChallenge(verifier) {
 function printError(message) {
     console.error(sanitizeTerminalText(message));
 }
+function printPushDisclosures(data) {
+    const warning = reportReplacementWarning(data);
+    if (warning)
+        printError(warning);
+    if (data.metadata_updated === true) {
+        printError('Updated prompt metadata on the identical existing version');
+    }
+}
 export function validateBrowserUrl(url, expectedOrigin) {
     let parsed;
     try {
@@ -246,27 +259,6 @@ export function formatTerminalLink(url) {
 function shellQuote(value) {
     return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
 }
-function printPromptSummaries(items, emptyMessage) {
-    if (items.length === 0) {
-        printLine(emptyMessage);
-        return;
-    }
-    const rows = items.map(item => ({
-        id: sanitizeTerminalText(item.id),
-        name: sanitizeTerminalText(item.name),
-        role: sanitizeTerminalText(item.role),
-        status: sanitizeTerminalText(item.status || 'active'),
-    }));
-    const idWidth = Math.max('ID'.length, ...rows.map(row => row.id.length));
-    const nameWidth = Math.max('NAME'.length, ...rows.map(row => row.name.length));
-    const roleWidth = Math.max('ROLE'.length, ...rows.map(row => row.role.length));
-    const statusWidth = Math.max('STATUS'.length, ...rows.map(row => row.status.length));
-    printLine(`${'ID'.padEnd(idWidth)}  ${'NAME'.padEnd(nameWidth)}  ${'ROLE'.padEnd(roleWidth)}  ${'STATUS'.padEnd(statusWidth)}`);
-    printLine(`${'-'.repeat(idWidth)}  ${'-'.repeat(nameWidth)}  ${'-'.repeat(roleWidth)}  ${'-'.repeat(statusWidth)}`);
-    rows.forEach(row => {
-        printLine(`${row.id.padEnd(idWidth)}  ${row.name.padEnd(nameWidth)}  ${row.role.padEnd(roleWidth)}  ${row.status.padEnd(statusWidth)}`);
-    });
-}
 function readJsonObjectArg(valueArg, label) {
     if (!valueArg) {
         return {};
@@ -905,7 +897,7 @@ async function listPrompts() {
         printJson(data);
         return;
     }
-    printPromptSummaries(data.prompts, 'No prompts found.');
+    printPromptSummaryTable(data.prompts, 'No prompts found.', printLine);
 }
 async function listJudges() {
     const project = getArg('--project') || await resolveProjectSlug(null);
@@ -923,7 +915,7 @@ async function listJudges() {
         printJson(data);
         return;
     }
-    printPromptSummaries(data.judges, 'No judges found.');
+    printPromptSummaryTable(data.judges, 'No judges found.', printLine);
 }
 async function listScorers() {
     const project = getArg('--project') || await resolveProjectSlug(null);
@@ -1034,8 +1026,10 @@ async function pushPromptArtifact(kind) {
         });
         if (hasJsonFlag())
             printJson(data);
-        else
+        else {
+            printPushDisclosures(data);
             printLine(message);
+        }
         return;
     }
     // LEGACY SESSIONLESS PATH (no branch to commit to; the server dual-writes
@@ -1081,6 +1075,7 @@ async function pushPromptArtifact(kind) {
         printJson(data);
         return;
     }
+    printPushDisclosures(data);
     printLine(`Pushed ${kind} ${sanitizeTerminalText(String(manifest.name || promptDir))} (${sanitizeTerminalText(String(data.prompt_version_id || 'unknown version'))})`);
 }
 async function pullPromptArtifact(kind) {
@@ -1815,30 +1810,12 @@ async function updateOptimizationRunLifecycle(action) {
 }
 // ALI-1073 list moved to optimizations-list-cli.ts (line ratchet, ALI-976);
 // ALI-1175 labels its best scores as agent-reported evidence there.
-function removeFlagWithValue(args, flag) {
-    const filtered = [];
-    for (let index = 0; index < args.length; index += 1) {
-        if (args[index] === flag) {
-            index += 1;
-            continue;
-        }
-        filtered.push(args[index]);
-    }
-    return filtered;
-}
-function bundledOrizuGepaPythonPath() {
-    const candidates = [
-        fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url)),
-        fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url)),
-    ];
-    return candidates.find(candidate => existsSync(candidate)) ?? null;
-}
 async function runGepaOptimization() {
     const project = getArg('--project') || await resolveProjectSlug(null);
     const baseUrl = getBaseUrl();
-    const python = getArg('--python') || process.env.PYTHON || 'python3';
-    const bundledPythonPath = bundledOrizuGepaPythonPath();
-    let forwardedArgs = removeFlagWithValue(cliArgs.slice(2), '--python');
+    const runGepa = getGepaPythonCommand(cliArgs.slice(2), process.env);
+    const python = runGepa.python;
+    let forwardedArgs = runGepa.args;
     // ALI-1159 (ADR-007): GEPA executes ad-hoc local runner dirs while
     // attributing records to registered runner version ids — verify the bytes
     // ARE those versions before the optimizer spawns. Scans the forwarded argv
@@ -1848,6 +1825,7 @@ async function runGepaOptimization() {
     const verified = await verifyGepaRunnerDirsFromArgs(forwardedArgs);
     forwardedArgs = verified.args;
     let result;
+    let selectedEngine = 'official';
     try {
         // Uniform resolution (ALI-1090): honors ORIZU_TOKEN / ORIZU_TOKEN_FILE before
         // credentials.json so hosted sandboxes can run optimizations. Read at spawn
@@ -1858,33 +1836,29 @@ async function runGepaOptimization() {
         if (!forwardedArgs.includes('--project')) {
             forwardedArgs = ['--project', project, ...forwardedArgs];
         }
-        const pythonPathEntries = [
-            bundledPythonPath,
-            process.env.PYTHONPATH,
-        ].filter((entry) => Boolean(entry));
-        result = spawnSync(python, ['-m', 'orizu_gepa.cli', ...forwardedArgs], {
+        const dispatch = dispatchGepaEngine(forwardedArgs, project, {
+            ...process.env,
+            ORIZU_API_URL: baseUrl,
+            ORIZU_TOKEN: token,
+            ORIZU_PROJECT: project,
+            ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
+            PYTHONPATH: getGepaPythonPathEntries(process.env.PYTHONPATH).join(delimiter),
+            PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
+        });
+        selectedEngine = dispatch.engine;
+        result = spawnSync(python, ['-m', dispatch.module, ...dispatch.args], {
             stdio: 'inherit',
-            env: {
-                ...process.env,
-                ORIZU_API_URL: baseUrl,
-                ORIZU_TOKEN: token,
-                ORIZU_PROJECT: project,
-                // Integrity handshake (ALI-1159): the Python entrypoint refuses
-                // runner dirs that are not in this wrapper-verified list.
-                ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
-                PYTHONPATH: pythonPathEntries.join(delimiter),
-                PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
-            },
+            env: dispatch.environment,
         });
     }
     finally {
         verified.cleanup();
     }
     if (result.error) {
-        throw result.error;
+        throw new Error(`${selectedEngine} GEPA engine failed: ${result.error.message}`, { cause: result.error });
     }
     if (result.status !== 0) {
-        throw new Error(`orizu-gepa failed with exit code ${result.status}`);
+        throw new Error(`${selectedEngine} GEPA engine failed with exit code ${result.status}`);
     }
     if (hasJsonFlag()) {
         printJson({ status: 'completed', exitCode: 0 });