orizu 0.5.21 → 0.5.23

package/dist/skilled-proposer-launch.js

@@ -1,14 +1,78 @@
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
+import { existsSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
-import { bundledOfficialGepaPythonPath } from './gepa-python-paths.js';
+import { bundledOfficialGepaPythonPath, getGepaPythonPathEntries } from './gepa-python-paths.js';
 import { sanitizeTerminalText } from './json-response.js';
-function ensureSelectedSkilledProposerVenv(python, vendoredGepaPath) {
+import { SKILLED_PROPOSER_BAKE_REPORT_FIELDS } from './skilled-proposer-bake-report.js';
+function materializeConfigPayload(engine, environment) {
+    const payload = environment.ORIZU_SKILLED_PROPOSER_CONFIG;
+    if (engine !== 'official' || environment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer' || payload === undefined)
+        return undefined;
+    const root = mkdtempSync(join(tmpdir(), 'orizu-skilled-proposer-payload-'));
+    try {
+        const path = join(root, 'config.json');
+        writeFileSync(path, payload, { encoding: 'utf8', mode: 0o600 });
+        environment.ORIZU_SKILLED_PROPOSER_CONFIG = `@${path}`;
+    }
+    catch (error) {
+        rmSync(root, { recursive: true, force: true });
+        throw error;
+    }
+    return () => rmSync(root, { recursive: true, force: true });
+}
+export async function spawnSkilledProposerChild(command, args, engine, environment) {
+    const childEnvironment = { ...environment };
+    const shouldMaterialize = engine === 'official'
+        && childEnvironment.ORIZU_CANDIDATE_PROPOSER === 'skilled-proposer'
+        && childEnvironment.ORIZU_SKILLED_PROPOSER_CONFIG !== undefined;
+    if (!shouldMaterialize)
+        return spawnSync(command, args, { stdio: 'inherit', env: childEnvironment });
+    let child;
+    let cleanup = () => { };
+    const signals = ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGQUIT'];
+    const handlers = signals.map(signal => ({
+        signal,
+        handle: () => {
+            try {
+                cleanup();
+            }
+            finally {
+                try {
+                    child?.kill(signal);
+                }
+                finally {
+                    for (const entry of handlers)
+                        process.off(entry.signal, entry.handle);
+                    process.kill(process.pid, signal);
+                }
+            }
+        },
+    }));
+    for (const entry of handlers)
+        process.once(entry.signal, entry.handle);
+    try {
+        cleanup = materializeConfigPayload(engine, childEnvironment) ?? cleanup;
+        await new Promise(resolve => setImmediate(resolve));
+        return await new Promise(resolve => {
+            let error;
+            child = spawn(command, args, { stdio: 'inherit', env: childEnvironment });
+            child.once('error', cause => { error = cause; });
+            child.once('close', status => resolve(error ? { status, error } : { status }));
+        });
+    }
+    finally {
+        for (const entry of handlers)
+            process.off(entry.signal, entry.handle);
+        cleanup();
+    }
+}
+function ensureSelectedSkilledProposerVenv(python, vendoredGepaPath, cacheRoot = existsSync('/opt/orizu/prebaked.json')
+    ? '/opt/orizu/cache/skilled-proposer'
+    : join(process.cwd(), '.orizu', 'cache', 'skilled-proposer')) {
     const manager = fileURLToPath(new URL('../scripts/ensure-skilled-proposer-venv.mjs', import.meta.url));
     const lock = fileURLToPath(new URL('../requirements/skilled-proposer.lock', import.meta.url));
-    // This is a regenerable workspace cache. The manager's publish key further
-    // separates interpreters, platforms, and lock revisions inside it.
-    const cacheRoot = join(process.cwd(), '.orizu', 'cache', 'skilled-proposer');
     const result = spawnSync(process.execPath, [manager, '--python', python, '--cache-root', cacheRoot, '--lock', lock,
         '--vendored-gepa-path', vendoredGepaPath, '--json'], {
         env: process.env,
@@ -34,6 +98,38 @@ function ensureSelectedSkilledProposerVenv(python, vendoredGepaPath) {
     }
     return report;
 }
+const packageRoot = join(fileURLToPath(new URL('.', import.meta.url)), '..');
+const managerPath = join(packageRoot, 'scripts/ensure-skilled-proposer-venv.mjs');
+const lockPath = join(packageRoot, 'requirements/skilled-proposer.lock');
+const vendoredGepaPath = join(packageRoot, 'vendor/gepa-python/src');
+const packagedPythonPathEntries = ['vendor/orizu-gepa/src', 'vendor/orizu-gepa-python/src', 'vendor/gepa-python/src'].map(path => join(packageRoot, path));
+const bakedCacheRoot = '/opt/orizu/cache/skilled-proposer';
+export function skilledProposerBakeCommand(io, verify = false) {
+    try {
+        const python = process.env.PYTHON || 'python3';
+        if (!verify) {
+            io.print(JSON.stringify(ensureSelectedSkilledProposerVenv(python, vendoredGepaPath, bakedCacheRoot)));
+            return 0;
+        }
+        if (!readdirSync(join(bakedCacheRoot, 'venvs'), { withFileTypes: true }).some(entry => entry.isDirectory() && existsSync(join(bakedCacheRoot, 'venvs', entry.name, '.orizu-skilled-proposer-venv.json'))))
+            throw new Error('ALI_1588_VENV_MARKER_MISSING');
+        const environment = { ...process.env, ORIZU_CANDIDATE_PROPOSER: 'skilled-proposer' };
+        const launch = prepareSkilledProposerLaunch(python, 'official', environment);
+        const report = launch.report;
+        if (report.publishedVenv !== false || report.executedPipArgv !== null)
+            throw new Error('ALI_1588_DEPENDENCY_SETUP_NOT_REUSED');
+        const pythonPathEntries = getGepaPythonPathEntries(undefined);
+        if (JSON.stringify(pythonPathEntries) !== JSON.stringify(packagedPythonPathEntries))
+            throw new Error('ALI_1588_PYTHON_ROOT_MISSING');
+        const completeReport = { ...report, pythonPathEntries, marker: 'ALI_1588_DEPENDENCY_SETUP_REUSED', python: launch.python, packageRoot, manager: managerPath, lock: lockPath, vendoredGepaPath, launcherVenv: launch.environment.ORIZU_SKILLED_PROPOSER_VENV ?? null, launcherSslCertFile: launch.environment.SSL_CERT_FILE ?? null };
+        io.print(JSON.stringify(Object.fromEntries(SKILLED_PROPOSER_BAKE_REPORT_FIELDS.map(key => [key, completeReport[key]]))));
+        return 0;
+    }
+    catch (error) {
+        io.printErr?.(`${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+}
 export function prepareSkilledProposerLaunch(python, engine, environment) {
     if (engine !== 'official' || environment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer') {
         return { python, environment };
@@ -56,5 +152,6 @@ export function prepareSkilledProposerLaunch(python, engine, environment) {
             ? join(report.venv, 'Scripts', 'python.exe')
             : join(report.venv, 'bin', 'python'),
         environment,
+        report,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orizu",
-  "version": "0.5.21",
+  "version": "0.5.23",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",

package/scripts/vendor-gepa-python.mjs

@@ -19,6 +19,10 @@ const archiveArgumentIndex = process.argv.indexOf('--archive')
 const suppliedArchive = archiveArgumentIndex === -1
   ? null
   : process.argv[archiveArgumentIndex + 1]
+const destinationArgumentIndex = process.argv.indexOf('--destination')
+const suppliedDestination = destinationArgumentIndex === -1
+  ? null
+  : process.argv[destinationArgumentIndex + 1]
 const sourceSrc = resolve(sourceRoot, 'src')
 const sourcePyproject = resolve(sourceRoot, 'pyproject.toml')
 const sourceManifest = resolve(sourceRoot, 'manifest.json')
@@ -31,6 +35,7 @@ const GEPA_VERSION = '0.1.4'
 const GEPA_RELEASE_COMMIT = '8b0ce6cd99a234f6b74daf37558a2ac0ce18f975'
 const GEPA_WHEEL_FILENAME = 'gepa-0.1.4-py3-none-any.whl'
 const GEPA_WHEEL_SHA256 = '12b971039599625c156d2231f6d72a29c31a22e9c237689459b5f1a3c353f532'
+const GEPA_TREE_SHA256 = '8cb2ef66ca4212f416d1c4b23421f0de377b4997c1c50fd41ac16ca31015de99'
 const hasSourcePackage = existsSync(sourceSrc)
   && existsSync(sourcePyproject)
   && existsSync(sourceManifest)
@@ -75,19 +80,55 @@ function collectFileHashes(root, prefix = '') {
   return files
 }
 
-function assertOfficialVendoredManifest() {
+function fileInventoryDigest(files) {
+  const entries = Object.entries(files).sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+  return createHash('sha256').update(JSON.stringify(entries)).digest('hex')
+}
+
+function assertOfficialVendoredManifest(root = officialVendorRoot) {
+  const manifestPath = resolve(root, 'manifest.json')
   let manifest
   try {
-    manifest = JSON.parse(readFileSync(officialVendoredManifest, 'utf8'))
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
   } catch (error) {
     throw new Error(`Official GEPA vendored manifest is unreadable: ${error.message}`)
   }
 
+  if (manifest.schemaVersion !== 'gepa-vendor.v1') {
+    throw new Error('Official GEPA vendored manifest identity mismatch: schemaVersion')
+  }
+  if (!manifest.upstream || typeof manifest.upstream !== 'object' || Array.isArray(manifest.upstream)) {
+    throw new Error('Official GEPA vendored manifest identity mismatch: upstream')
+  }
+  for (const [field, expected] of [
+    ['package', 'gepa'],
+    ['version', GEPA_VERSION],
+    ['repositoryCommit', GEPA_RELEASE_COMMIT],
+  ]) {
+    if (manifest.upstream[field] !== expected) {
+      throw new Error(`Official GEPA vendored manifest identity mismatch: ${field}`)
+    }
+  }
+  if (!manifest.upstream.wheel || typeof manifest.upstream.wheel !== 'object' || Array.isArray(manifest.upstream.wheel)) {
+    throw new Error('Official GEPA vendored manifest identity mismatch: wheel')
+  }
+  for (const [field, expected] of [['filename', GEPA_WHEEL_FILENAME], ['sha256', GEPA_WHEEL_SHA256]]) {
+    if (manifest.upstream.wheel[field] !== expected) {
+      throw new Error(`Official GEPA vendored manifest identity mismatch: wheel.${field}`)
+    }
+  }
+
   if (!manifest.files || typeof manifest.files !== 'object' || Array.isArray(manifest.files)) {
     throw new Error('Official GEPA vendored manifest is missing file hashes')
   }
+  if (!Object.hasOwn(manifest.files, 'LICENSE')) {
+    throw new Error('Official GEPA vendored manifest is missing required LICENSE')
+  }
+  if (!Object.hasOwn(manifest.files, 'src/gepa/__init__.py')) {
+    throw new Error('Official GEPA vendored manifest is missing required GEPA package entry')
+  }
 
-  const actualFiles = collectFileHashes(officialVendorRoot)
+  const actualFiles = collectFileHashes(root)
   delete actualFiles['manifest.json']
   const expectedEntries = Object.entries(manifest.files).sort(([left], [right]) => left.localeCompare(right))
   const actualEntries = Object.entries(actualFiles).sort(([left], [right]) => left.localeCompare(right))
@@ -102,9 +143,28 @@ function assertOfficialVendoredManifest() {
       throw new Error(`Official GEPA vendored manifest mismatch at ${expectedPath}`)
     }
   }
+  const treeSha256 = fileInventoryDigest(actualFiles)
+  if (treeSha256 !== GEPA_TREE_SHA256) {
+    throw new Error(`Official GEPA vendored tree digest mismatch: expected ${GEPA_TREE_SHA256}, got ${treeSha256}`)
+  }
+
+  return {
+    marker: 'ALI_1588_GEPA_VENDOR_VERIFIED',
+    schemaVersion: manifest.schemaVersion,
+    wheelSha256: manifest.upstream.wheel.sha256,
+    treeSha256,
+    fileCount: actualEntries.length,
+  }
 }
 
-function extractPinnedGepa(archivePath) {
+function writeValidationReceipt(receipt) {
+  if (!receipt || receipt.marker !== 'ALI_1588_GEPA_VENDOR_VERIFIED') {
+    throw new Error('Official GEPA vendored manifest validation produced no receipt')
+  }
+  process.stdout.write(`${JSON.stringify(receipt)}\n`)
+}
+
+function extractPinnedGepa(archivePath, destinationRoot) {
   const extractor = String.raw`
 from pathlib import Path, PurePosixPath
 import shutil
@@ -132,7 +192,7 @@ with zipfile.ZipFile(archive_path) as archive:
         with archive.open(member) as source, destination.open('wb') as output:
             shutil.copyfileobj(source, output)
 `
-  const result = spawnSync('python3', ['-c', extractor, archivePath, officialVendorRoot], {
+  const result = spawnSync('python3', ['-c', extractor, archivePath, destinationRoot], {
     encoding: 'utf8',
   })
   if (result.status !== 0) {
@@ -141,14 +201,14 @@ with zipfile.ZipFile(archive_path) as archive:
   }
 }
 
-function vendorOfficialGepa(archivePath) {
+function vendorOfficialGepa(archivePath, destinationRoot = officialVendorRoot) {
   assertPinnedGepaArchive(archivePath)
-  rmSync(officialVendorRoot, { recursive: true, force: true })
-  mkdirSync(officialVendorRoot, { recursive: true })
-  extractPinnedGepa(archivePath)
+  rmSync(destinationRoot, { recursive: true, force: true })
+  mkdirSync(destinationRoot, { recursive: true })
+  extractPinnedGepa(archivePath, destinationRoot)
 
-  const files = collectFileHashes(officialVendorRoot)
-  writeFileSync(officialVendoredManifest, `${JSON.stringify({
+  const files = collectFileHashes(destinationRoot)
+  writeFileSync(resolve(destinationRoot, 'manifest.json'), `${JSON.stringify({
     schemaVersion: 'gepa-vendor.v1',
     upstream: {
       package: 'gepa',
@@ -161,11 +221,20 @@ function vendorOfficialGepa(archivePath) {
     },
     files,
   }, null, 2)}\n`)
+  return assertOfficialVendoredManifest(destinationRoot)
 }
 
 if (archiveArgumentIndex !== -1 && (!suppliedArchive || suppliedArchive.startsWith('--'))) {
   throw new Error('Expected a source archive path after --archive')
 }
+if (destinationArgumentIndex !== -1 && (!suppliedDestination || suppliedDestination.startsWith('--'))) {
+  throw new Error('Expected a destination directory after --destination')
+}
+
+if (suppliedArchive && suppliedDestination) {
+  writeValidationReceipt(vendorOfficialGepa(suppliedArchive, suppliedDestination))
+  process.exit(0)
+}
 
 if (shouldRefresh) {
   if (!suppliedArchive) {
@@ -190,7 +259,7 @@ if (shouldClean) {
 
 if (!hasSourcePackage || !hasConnectorSourcePackage) {
   if (hasVendoredPackage && hasVendoredConnectorPackage && hasOfficialVendoredPackage) {
-    assertOfficialVendoredManifest()
+    writeValidationReceipt(assertOfficialVendoredManifest())
     process.exit(0)
   }
   if (hasVendoredPackage || hasVendoredConnectorPackage || hasOfficialVendoredPackage) {

package/src/cleanup.ts

@@ -0,0 +1,37 @@
+export type Cleanup = () => void
+
+function collectCleanupFailures(cleanups: readonly Cleanup[]): unknown[] {
+  const failures: unknown[] = []
+  for (const cleanup of cleanups) {
+    try {
+      cleanup()
+    } catch (error) {
+      failures.push(error)
+    }
+  }
+  return failures
+}
+
+/** Attempt every disposer even when an earlier cleanup fails. */
+export function cleanupAll(
+  cleanups: readonly Cleanup[],
+  message: string
+): void {
+  const failures = collectCleanupFailures(cleanups)
+  if (failures.length > 0) {
+    throw new AggregateError(failures, message)
+  }
+}
+
+/** Preserve the operation failure together with every cleanup failure. */
+export function throwWithCleanup(
+  operationError: unknown,
+  cleanups: readonly Cleanup[],
+  message: string
+): never {
+  const cleanupFailures = collectCleanupFailures(cleanups)
+  if (cleanupFailures.length > 0) {
+    throw new AggregateError([operationError, ...cleanupFailures], message)
+  }
+  throw operationError
+}

package/src/gepa-engine-dispatch.ts

@@ -1,5 +1,7 @@
 import { existsSync, readFileSync } from 'fs'
 
+import { normalizedSkilledProposerConfig } from './skilled-proposer-config.js'
+
 export type GepaEngine = 'official' | 'legacy'
 
 export interface GepaEngineDispatch {
@@ -179,6 +181,7 @@ const CONTROLLED_ENVIRONMENT_NAMES = new Set([
   // translation prevents an inherited environment from selecting a proposer
   // on an otherwise byte-for-byte normal official-GEPA launch.
   'ORIZU_CANDIDATE_PROPOSER',
+  'ORIZU_SKILLED_PROPOSER_CONFIG',
   'ORIZU_COMPONENT_SELECTOR',
 ])
 
@@ -208,6 +211,7 @@ function translateOfficialOptions(args: string[], project: string, environment:
   connectorEnvironment.ORIZU_PROJECT = project
 
   let metadata: string | undefined
+  let candidateProposerConfig: string | undefined
   let hasInstructionSet = false
   let hasCandidateVersion = false
   const budgetFlags: string[] = []
@@ -240,6 +244,12 @@ function translateOfficialOptions(args: string[], project: string, environment:
       index = parsed.nextIndex
       continue
     }
+    if (flag === '--candidate-proposer-config') {
+      const parsed = optionValueOrThrow(args, index, flag)
+      candidateProposerConfig = parsed.value
+      index = parsed.nextIndex
+      continue
+    }
     const option = VALUE_OPTIONS_BY_FLAG.get(flag)
     if (option) {
       const parsed = optionValueOrThrow(args, index, flag, option.allowEmpty)
@@ -297,6 +307,16 @@ function translateOfficialOptions(args: string[], project: string, environment:
       && connectorEnvironment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer') {
     throw new Error('--proposal-max-calls and --proposal-max-tokens require --candidate-proposer skilled-proposer')
   }
+  if (candidateProposerConfig !== undefined) {
+    if (connectorEnvironment.ORIZU_CANDIDATE_PROPOSER !== 'skilled-proposer') {
+      throw new Error('--candidate-proposer-config requires --candidate-proposer skilled-proposer')
+    }
+    connectorEnvironment.ORIZU_SKILLED_PROPOSER_CONFIG = normalizedSkilledProposerConfig(candidateProposerConfig)
+  }
+  if (connectorEnvironment.ORIZU_CANDIDATE_PROPOSER === 'skilled-proposer'
+      && connectorEnvironment.ORIZU_REFLECTION_PROMPT_TEMPLATE !== undefined) {
+    throw new Error('--reflection-prompt-template is incompatible with --candidate-proposer skilled-proposer')
+  }
 
   const reflectionModel = connectorEnvironment.ORIZU_REFLECTION_MODEL ?? 'anthropic/claude-opus-4-7'
   if (!reflectionModel.startsWith('openai/') && connectorEnvironment.ORIZU_REFLECTION_MAX_TOKENS === undefined) {
@@ -321,7 +341,7 @@ function validatedMetadata(raw: string | undefined): string {
 export function dispatchGepaEngine(args: string[], project: string, environment: NodeJS.ProcessEnv): GepaEngineDispatch {
   const selected = removeEngine(args)
   if (selected.engine === 'legacy') {
-    for (const flag of ['--instruction-set', '--model-config', '--component-selector', '--max-candidate-proposals', '--candidate-proposer', '--proposal-max-calls', '--proposal-max-tokens']) {
+    for (const flag of ['--instruction-set', '--model-config', '--component-selector', '--max-candidate-proposals', '--candidate-proposer', '--candidate-proposer-config', '--proposal-max-calls', '--proposal-max-tokens']) {
       if (selected.args.some(argument => argument === flag || argument.startsWith(`${flag}=`))) {
         throw new Error(`${flag} is supported by the official GEPA engine only`)
       }

package/src/gepa-python-paths.ts

@@ -1,4 +1,5 @@
 import { existsSync } from 'fs'
+import { execFileSync } from 'child_process'
 import { fileURLToPath } from 'url'
 
 import { isOrizuSourceCheckout } from '../scripts/orizu-source-checkout.mjs'
@@ -34,14 +35,31 @@ export function bundledOrizuGepaConnectorPythonPath(): string | null {
 }
 
 export function bundledOfficialGepaPythonPath(): string | null {
-  const sourceArchive = fileURLToPath(new URL('../gepa-python-source.zip', import.meta.url))
   const vendor = fileURLToPath(new URL('../vendor/gepa-python/src', import.meta.url))
-  // The checked-in pinned wheel is directly importable from PYTHONPATH in a
-  // source checkout. Published packages intentionally omit that archive and
-  // must resolve only the verified tree materialized by prepack.
-  const candidates = prefersLiveSource() ? [sourceArchive, vendor] : [vendor]
+  if (prefersLiveSource()) {
+    const requiredVendorFiles = [
+      fileURLToPath(new URL('../vendor/gepa-python/manifest.json', import.meta.url)),
+      fileURLToPath(new URL('../vendor/gepa-python/src/gepa/__init__.py', import.meta.url)),
+      fileURLToPath(new URL('../vendor/gepa-python/src/gepa/adapters/optimize_anything_adapter/optimize_anything_adapter.py', import.meta.url)),
+    ]
+    if (!requiredVendorFiles.every(existsSync)) {
+      const vendoringScript = fileURLToPath(new URL('../scripts/vendor-gepa-python.mjs', import.meta.url))
+      try {
+        execFileSync(process.execPath, [vendoringScript], { stdio: 'pipe' })
+      } catch (error) {
+        const details = error instanceof Error ? error.message : String(error)
+        throw new Error(`Unable to materialize bundled official GEPA: ${details}`)
+      }
+      if (!requiredVendorFiles.every(existsSync)) {
+        throw new Error('Unable to materialize bundled official GEPA: extracted tree is incomplete')
+      }
+    }
+  }
 
-  return resolveGepaPythonPath(candidates)
+  // zipimport cannot resolve GEPA's namespace-package adapters on every
+  // supported Python minor. Both source and published CLIs execute only the
+  // verified tree materialized from the pinned wheel.
+  return resolveGepaPythonPath([vendor])
 }
 
 export function getGepaPythonPathEntries(existingPythonPath: string | undefined): string[] {

package/src/help.ts

@@ -89,6 +89,40 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   { path: ['instructions', 'archive'], aliases: [['instruction-sets', 'archive']], usage: 'orizu instructions archive <slug-or-exact-name> --project <team/project> [--json]', summary: 'Archive an instruction set without changing resolution or sync.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions archive planner --project core/evals'] },
   { path: ['instructions', 'restore'], aliases: [['instruction-sets', 'restore']], usage: 'orizu instructions restore <slug-or-exact-name> --project <team/project> [--json]', summary: 'Restore an archived instruction set.', group: 'Instruction sets', options: [{ name: '--project <team/project>', help: 'Project slug.', required: true }, { name: '--json', help: 'Print JSON.' }], examples: ['orizu instructions restore planner --project core/evals'] },
+  {
+    path: ['instructions', 'scorers', 'set-headline'],
+    aliases: [['instruction-sets', 'scorers', 'set-headline']],
+    usage: 'orizu instructions scorers set-headline <set> --key <component-key> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]',
+    summary: 'Bind the headline scorer for one instruction-set component.',
+    group: 'Instruction sets',
+    options: [
+      { name: '--key <component-key>', help: 'Instruction-set component key.', required: true },
+      { name: '--scorer-version <id>', help: 'Scorer version to bind.', required: true },
+      { name: '--dataset-version <id>', help: 'Default dataset version.' },
+      { name: '--split-set <id>', help: 'Default dataset split set.' },
+      { name: '--split <name>', help: 'Default split name.' },
+      { name: '--project <team/project>', help: 'Project slug.' },
+      { name: '--json', help: 'Print JSON.' },
+    ],
+    examples: ['orizu instructions scorers set-headline planner --key system --scorer-version <id> --project core/evals'],
+  },
+  {
+    path: ['instructions', 'scorers', 'add'],
+    aliases: [['instruction-sets', 'scorers', 'add']],
+    usage: 'orizu instructions scorers add <set> --key <component-key> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]',
+    summary: 'Track an additional scorer for one instruction-set component.',
+    group: 'Instruction sets',
+    options: [
+      { name: '--key <component-key>', help: 'Instruction-set component key.', required: true },
+      { name: '--scorer-version <id>', help: 'Scorer version to bind.', required: true },
+      { name: '--dataset-version <id>', help: 'Default dataset version.' },
+      { name: '--split-set <id>', help: 'Default dataset split set.' },
+      { name: '--split <name>', help: 'Default split name.' },
+      { name: '--project <team/project>', help: 'Project slug.' },
+      { name: '--json', help: 'Print JSON.' },
+    ],
+    examples: ['orizu instructions scorers add planner --key system --scorer-version <id> --project core/evals'],
+  },
   {
     path: ['login'],
     usage: 'orizu login [--no-prompt-if-logged-in]',
@@ -119,7 +153,7 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['log'],
-    usage: 'orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json',
+    usage: 'orizu log <event_type> --run-id <id> --sequence <n> --payload @event.json [--event-id <id>] [--event-layer <layer>] [--optimizer-family <family>] [--iteration <n>] [--candidate-id <id>] [--parent-candidate-id <id>] [--child-candidate-id <id>]',
     summary: 'Submit an optimization event payload.',
     group: 'Optimizations',
   },
@@ -413,18 +447,6 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
     summary: 'Move or set a non-production prompt label; use instructions profiles promote for production.',
     group: 'Prompts and judges',
   },
-  {
-    path: ['prompts', 'scorers', 'set-headline'],
-    usage: 'orizu prompts scorers set-headline <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]',
-    summary: 'Bind the headline scorer for a prompt.',
-    group: 'Scorers and runners',
-  },
-  {
-    path: ['prompts', 'scorers', 'add'],
-    usage: 'orizu prompts scorers add <prompt-id> --scorer-version <id> [--dataset-version <id> --split-set <id> --split <name>] [--project <team/project>] [--json]',
-    summary: 'Track an additional scorer for a prompt.',
-    group: 'Scorers and runners',
-  },
   {
     path: ['judges', 'list'],
     usage: 'orizu judges list --project <team/project> [--status active|archived|all]',
@@ -578,8 +600,8 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['optimizations', 'run-gepa'],
-    usage: 'orizu optimizations run-gepa --project <team/project> --optimizer-version-id <id> (--candidate-version-id <id> | --instruction-set <name> --model-config <identity> [--component-selector round-robin|all]) --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. --instruction-set requires --model-config and cannot be combined with --candidate-version-id; round-robin updates one component-map entry per round and all updates every component. --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).',
+    usage: 'orizu optimizations run-gepa [--hosted [--launch-intent-id <uuid>]] --project <team/project> --optimizer-version-id <id> (--candidate-version-id <id> | --instruction-set <name> --model-config <identity> [--component-selector round-robin|all]) --runner-version-id <id> [--candidate-runner-dir <dir>] --scorer-version-id <id> --scorer-runner-version-id <id> [--scorer-runner-dir <dir>] [--engine official|legacy] [--candidate-proposer skilled-proposer [--candidate-proposer-config <@file|path>] [--proposal-max-calls <n>] [--proposal-max-tokens <n>]] [--scorer-input-contract gepa|flat_row] [--scorer-candidate-field <row-field>] [--allow-degenerate-seed] [--seed <n>] --dataset-version-id <id> --split-set-id <id> [--train-split train] [--val-split validation] [--minibatch-size <n>] [--candidate-selection-strategy pareto|current_best|epsilon_greedy] [--epsilon <n>] [--objective <text>] [--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-model <provider/model>] [--reflection-temperature <n>] [--reflection-prompt-template <text|@file>] [--reflection-max-tokens N] [--reflection-provider-settings <json|@file>] [--reflection-retry-attempts N] [--reflection-http-timeout-seconds N] [--skip-perfect-parent-reflection|--no-skip-perfect-parent-reflection] [--disable-evaluation-cache] [--auto-promote] [--promotion-label <label>] [--log-row-snapshots] [--metadata <json>] [--python <command>] [--log-dir logs] [--no-local-log] [--json]',
+    summary: 'Run official GEPA locally and stream events, or use --hosted for a queued Orizu launch. Hosted mode does not require --candidate-runner-dir or --scorer-runner-dir, accepts only a named --budget preset, and supports response-loss recovery with --launch-intent-id. Local runner version ids materialize registered bytes, while optional runner dirs are additionally byte-verified before execution. Pass --engine legacy only for the frozen safety hatch. Skilled-proposer is official-only, its config requires that selection, and the selection cannot be combined with --reflection-prompt-template. --instruction-set requires --model-config and cannot be combined with --candidate-version-id; round-robin updates one component-map entry per round and all updates every component. --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/src/hosted-commands.ts

@@ -0,0 +1,4 @@
+import { runHostedGepaOptimization } from './hosted-gepa-cli.js'
+import { hostedCommand } from './hosted-session-cli.js'
+interface HostedCommandContext { environment: NodeJS.ProcessEnv; getArg: (name: string) => string | null; json: boolean; printJson: (value: Record<string, unknown>) => void; printLine: (value?: string) => void; printErr: (value: string) => void; resolveProjectSlug: (projectArg: string | null) => Promise<string>; setExitCode: (code: number) => void }
+export async function dispatchHostedCommands(args: string[], context: HostedCommandContext): Promise<boolean> { const [command, subcommand] = args; if (command === 'optimizations' && subcommand === 'run-gepa' && args.includes('--hosted')) { const project = context.getArg('--project') || await context.resolveProjectSlug(null); await runHostedGepaOptimization({ args: args.slice(2), project, environment: context.environment, json: context.json, printJson: context.printJson, printLine: context.printLine }); return true } if (command === 'internal' || (command === 'session' && subcommand === 'start' && args.includes('--hosted'))) { context.setExitCode(await hostedCommand(args, { json: context.json, print: context.printLine, printErr: context.printErr })); return true } return false }

package/src/hosted-gepa-cli.ts

@@ -0,0 +1,107 @@
+import { randomUUID } from 'node:crypto'
+
+import { dispatchGepaEngine } from './gepa-engine-dispatch.js'
+import { parseHostedGepaNumericValue } from './hosted-gepa-numeric-values.js'
+import { authedFetch } from './http.js'
+import { hostedProviderSettingsError } from './hosted-provider-settings.js'
+import { parseJsonResponse } from './json-response.js'
+
+interface HostedGepaOptions {
+  args: string[]
+  project: string
+  environment: NodeJS.ProcessEnv
+  json: boolean
+  printJson: (value: Record<string, unknown>) => void
+  printLine: (value: string) => void
+}
+
+function argumentValue(args: string[], name: string): string | null {
+  const index = args.indexOf(name)
+  if (index >= 0 && index + 1 < args.length) return args[index + 1]
+  return args.find(argument => argument.startsWith(`${name}=`))?.slice(name.length + 1) ?? null
+}
+
+function dispatchArgs(args: string[]): string[] {
+  const filtered: string[] = []
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] === '--hosted') continue
+    if (args[index] === '--launch-intent-id') { index += 1; continue }
+    if (args[index].startsWith('--launch-intent-id=')) continue
+    filtered.push(args[index])
+  }
+  return filtered
+}
+
+export async function runHostedGepaOptimization(options: HostedGepaOptions): Promise<void> {
+  const hasLaunchIntent = options.args.some(argument =>
+    argument === '--launch-intent-id' || argument.startsWith('--launch-intent-id='))
+  const explicitLaunchIntent = argumentValue(options.args, '--launch-intent-id')
+  if (hasLaunchIntent && (!explicitLaunchIntent || explicitLaunchIntent.startsWith('-')
+    || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(explicitLaunchIntent))) {
+    throw new Error('--launch-intent-id must be a UUIDv4 value when provided.')
+  }
+  const args = dispatchArgs(options.args)
+  if (['--max-iterations', '--max-full-evals', '--max-metric-calls', '--max-candidate-proposals']
+    .some(flag => args.some(argument => argument === flag || argument.startsWith(`${flag}=`)))) {
+    throw new Error('Hosted optimization requires a named --budget preset; numeric budget controls are not accepted.')
+  }
+  const dispatch = dispatchGepaEngine(args, options.project, options.environment)
+  if (dispatch.engine !== 'official') throw new Error('Hosted optimization requires the official GEPA engine.')
+  const env = dispatch.environment
+  const required = [
+    ['ORIZU_OPTIMIZER_VERSION_ID', '--optimizer-version-id'], ['ORIZU_RUNNER_VERSION_ID', '--runner-version-id'],
+    ['ORIZU_SCORER_VERSION_ID', '--scorer-version-id'], ['ORIZU_SCORER_RUNNER_VERSION_ID', '--scorer-runner-version-id'],
+    ['ORIZU_DATASET_VERSION_ID', '--dataset-version-id'], ['ORIZU_SPLIT_SET_ID', '--split-set-id'],
+  ] as const
+  for (const [name, flag] of required) if (!env[name]) throw new Error(`${flag} is required for hosted optimization.`)
+  const providerSettings = JSON.parse(env.ORIZU_REFLECTION_PROVIDER_SETTINGS ?? '{}') as Record<string, unknown>
+  const providerSettingsError = hostedProviderSettingsError(providerSettings,
+    env.ORIZU_REFLECTION_MODEL ?? 'anthropic/', env.ORIZU_REFLECTION_TEMPERATURE)
+  if (providerSettingsError) throw new Error(providerSettingsError)
+  const optional: Record<string, unknown> = {}
+  const fields: Array<[string, string, 'number' | 'json' | 'boolean' | 'string']> = [
+    ['candidateProposer', 'ORIZU_CANDIDATE_PROPOSER', 'string'], ['candidateProposerConfig', 'ORIZU_SKILLED_PROPOSER_CONFIG', 'json'],
+    ['proposalMaxCalls', 'ORIZU_PROPOSAL_MAX_CALLS', 'number'], ['proposalMaxTokens', 'ORIZU_PROPOSAL_MAX_TOKENS', 'number'],
+    ['minibatchSize', 'ORIZU_MINIBATCH_SIZE', 'number'], ['numThreads', 'ORIZU_NUM_THREADS', 'number'],
+    ['candidateSelectionStrategy', 'ORIZU_CANDIDATE_SELECTION_STRATEGY', 'string'], ['epsilon', 'ORIZU_EPSILON', 'number'],
+    ['reflectionModel', 'ORIZU_REFLECTION_MODEL', 'string'], ['reflectionTemperature', 'ORIZU_REFLECTION_TEMPERATURE', 'number'],
+    ['reflectionMaxTokens', 'ORIZU_REFLECTION_MAX_TOKENS', 'number'], ['reflectionRetryAttempts', 'ORIZU_REFLECTION_RETRY_ATTEMPTS', 'number'],
+    ['reflectionHttpTimeoutSeconds', 'ORIZU_REFLECTION_HTTP_TIMEOUT_SECONDS', 'number'],
+    ['reflectionPromptTemplate', 'ORIZU_REFLECTION_PROMPT_TEMPLATE', 'string'],
+    ['reflectionProviderSettings', 'ORIZU_REFLECTION_PROVIDER_SETTINGS', 'json'], ['objective', 'ORIZU_OBJECTIVE', 'string'],
+    ['seed', 'ORIZU_SEED', 'number'], ['disableEvaluationCache', 'ORIZU_DISABLE_EVALUATION_CACHE', 'boolean'],
+    ['allowDegenerateSeed', 'ORIZU_ALLOW_DEGENERATE_SEED', 'boolean'],
+    ['skipPerfectParentReflection', 'ORIZU_SKIP_PERFECT_PARENT_REFLECTION', 'boolean'],
+  ]
+  for (const [field, name, kind] of fields) {
+    if (env[name] === undefined) continue
+    optional[field] = kind === 'number' ? parseHostedGepaNumericValue(field, env[name]!)
+      : kind === 'json' ? JSON.parse(env[name]!) : kind === 'boolean' ? env[name] === '1' : env[name]
+  }
+  const launchIntentId = explicitLaunchIntent || randomUUID()
+  const body = {
+    hosted: true, launchIntentId, optimizerVersionId: env.ORIZU_OPTIMIZER_VERSION_ID,
+    promptVersionIds: env.ORIZU_PROMPT_VERSION_ID ? [env.ORIZU_PROMPT_VERSION_ID] : [],
+    ...(env.ORIZU_INSTRUCTION_SET_NAME ? { instructionSetName: env.ORIZU_INSTRUCTION_SET_NAME,
+      modelConfigIdentity: env.ORIZU_MODEL_CONFIG_IDENTITY, componentSelector: env.ORIZU_COMPONENT_SELECTOR } : {}),
+    runnerVersionId: env.ORIZU_RUNNER_VERSION_ID,
+    scorers: [{ scorerVersionId: env.ORIZU_SCORER_VERSION_ID,
+      scorerRunnerVersionId: env.ORIZU_SCORER_RUNNER_VERSION_ID, role: 'selection', scorerConfig: {} }],
+    datasetVersionId: env.ORIZU_DATASET_VERSION_ID, splitSetId: env.ORIZU_SPLIT_SET_ID,
+    trainSplitName: env.ORIZU_TRAIN_SPLIT ?? 'train', validationSplitName: env.ORIZU_VALIDATION_SPLIT ?? 'validation',
+    engine: 'official', scorerInputContract: env.ORIZU_SCORER_INPUT_CONTRACT ?? 'gepa',
+    scorerCandidateField: env.ORIZU_SCORER_CANDIDATE_FIELD ?? null, budget: env.ORIZU_BUDGET ?? 'auto', ...optional,
+  }
+  const response = await authedFetch(`/api/cli/optimization-runs?project=${encodeURIComponent(options.project)}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+  })
+  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Hosted optimization launch')
+  if (!response.ok) {
+    if (options.json) { options.printJson(data); process.exitCode = 1; return }
+    throw new Error(JSON.stringify(data))
+  }
+  if (options.json) { options.printJson(data); return }
+  options.printLine('Queued hosted optimization.')
+  options.printLine(`Launch intent: ${launchIntentId}`)
+  options.printLine(String(data.monitorUrl))
+}