orizu 0.5.21 → 0.5.22

package/dist/instruction-sets-cli.js

@@ -33,6 +33,15 @@ async function responsePayload(response, action) {
 const SAFE_SEGMENT = /^[A-Za-z0-9._-]+$/u;
 function safeSegment(value) { if (!SAFE_SEGMENT.test(value) || value === '.' || value === '..' || value.startsWith('.'))
     throw new Error('instruction_set_path_unsafe'); }
+function isSafeSegment(value) {
+    try {
+        safeSegment(value);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 function slug(identity) { return identity.replaceAll('/', '__').replace(/[^A-Za-z0-9._-]/gu, '_'); }
 function stable(value) { return `${JSON.stringify(value, null, 2)}\n`; }
 function sha256(value) { return createHash('sha256').update(value, 'utf8').digest('hex'); }
@@ -65,19 +74,62 @@ function removeOwnScratch(paths) {
         if (path && existsSync(path))
             rmSync(path, { recursive: true, force: true });
 }
-function existingDestinationIsSynced(destination, name) {
+function existingDestinationIsSynced(destination, set) {
+    if (set.slug &&
+        set.projectId === undefined &&
+        set.instructionSetId === undefined) {
+        return existingDestinationIsLegacySynced(destination, set.name, set.slug);
+    }
+    try {
+        if (!statSync(destination).isDirectory())
+            return false;
+        const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8'));
+        return manifest.manifestVersion === 1 && (set.slug
+            ? manifest.slug === set.slug &&
+                manifest.projectId === set.projectId &&
+                manifest.instructionSetId === set.instructionSetId
+            : manifest.name === set.name);
+    }
+    catch {
+        return false;
+    }
+}
+function existingDestinationIsLegacySynced(destination, name, slug) {
     try {
         if (!statSync(destination).isDirectory())
             return false;
         const manifest = JSON.parse(readFileSync(join(destination, 'manifest.json'), 'utf8'));
-        return manifest.manifestVersion === 1 && manifest.name === name;
+        return manifest.manifestVersion === 1 &&
+            manifest.name === name &&
+            manifest.slug === slug;
     }
     catch {
         return false;
     }
 }
+function removePublishedBackups(paths, remove) {
+    let firstError = null;
+    for (const path of paths) {
+        if (!existsSync(path))
+            continue;
+        try {
+            remove(path, { recursive: true, force: true });
+        }
+        catch (error) {
+            firstError ??= error;
+        }
+    }
+    if (firstError)
+        throw new Error('instruction_set_sync_cleanup_failed');
+}
 export function syncToDisk(out, set, fileOps = { writeFileSync }) {
-    safeSegment(set.name);
+    const directoryName = set.slug || set.name;
+    safeSegment(directoryName);
+    const hasProjectId = set.projectId !== undefined;
+    const hasInstructionSetId = set.instructionSetId !== undefined;
+    if (set.slug && hasProjectId !== hasInstructionSetId) {
+        throw new Error('instruction_set_sync_identity_missing');
+    }
     for (const key of set.shape)
         safeSegment(key);
     const profileSlugs = new Set();
@@ -89,12 +141,28 @@ export function syncToDisk(out, set, fileOps = { writeFileSync }) {
         profileSlugs.add(value);
     }
     mkdirSync(out, { recursive: true });
-    const destination = join(out, set.name);
-    if (existsSync(destination) && !existingDestinationIsSynced(destination, set.name))
+    const destination = join(out, directoryName);
+    const legacyDestination = set.slug && set.name !== set.slug && isSafeSegment(set.name)
+        ? join(out, set.name)
+        : null;
+    if (existsSync(destination)) {
+        if (set.slug && existingDestinationIsLegacySynced(destination, set.name)) {
+            throw new Error('instruction_set_sync_legacy_identity_required');
+        }
+        if (!existingDestinationIsSynced(destination, set)) {
+            throw new Error('instruction_set_sync_destination_not_synced');
+        }
+    }
+    if (legacyDestination && existsSync(legacyDestination)) {
+        if (existingDestinationIsLegacySynced(legacyDestination, set.name)) {
+            throw new Error('instruction_set_sync_legacy_identity_required');
+        }
         throw new Error('instruction_set_sync_destination_not_synced');
-    const temp = join(out, `.${set.name}.${randomUUID()}.tmp`);
+    }
+    const priorDestinations = [destination];
+    const temp = join(out, `.${directoryName}.${randomUUID()}.tmp`);
     const move = fileOps.renameSync || renameSync;
-    let backup = null;
+    const backups = [];
     mkdirSync(temp);
     try {
         const defaultMaterial = writeMaterial(temp, set.default, set.shape, 'default', fileOps);
@@ -108,28 +176,40 @@ export function syncToDisk(out, set, fileOps = { writeFileSync }) {
                 ? Object.entries(profile.production.files).map(([key, path]) => ({ key, modelConfig: profile.modelConfigIdentity, path, syncedContentSha256: profile.production.syncedContentSha256[key] }))
                 : []),
         ];
-        const manifest = { manifestVersion: 1, name: set.name, ...(Object.hasOwn(set, 'description') ? { description: set.description ?? null } : {}), shape: set.shape, components, default: defaultMaterial, profiles, ...(set.filteredTo ? { filteredTo: [...set.filteredTo].sort() } : {}) };
+        const manifest = {
+            manifestVersion: 1,
+            ...(set.projectId ? { projectId: set.projectId } : {}),
+            ...(set.instructionSetId ? { instructionSetId: set.instructionSetId } : {}),
+            name: set.name,
+            ...(set.slug ? { slug: set.slug } : {}),
+            ...(Object.hasOwn(set, 'description') ? { description: set.description ?? null } : {}),
+            shape: set.shape,
+            components,
+            default: defaultMaterial,
+            profiles,
+            ...(set.filteredTo ? { filteredTo: [...set.filteredTo].sort() } : {}),
+        };
         fileOps.writeFileSync(join(temp, 'manifest.json'), stable(manifest));
-        backup = join(out, `.${set.name}.${randomUUID()}.bak`);
-        if (existsSync(destination))
-            move(destination, backup);
-        try {
-            move(temp, destination);
-        }
-        catch (error) {
-            if (existsSync(backup))
-                move(backup, destination);
-            throw error;
+        for (const prior of priorDestinations) {
+            if (!existsSync(prior))
+                continue;
+            const backup = join(out, `.${directoryName}.${randomUUID()}.bak`);
+            move(prior, backup);
+            backups.push({ original: prior, backup });
         }
-        removeOwnScratch([backup]);
+        move(temp, destination);
     }
     catch (error) {
         removeOwnScratch([temp]);
-        if (backup && existsSync(backup) && !existsSync(destination))
-            move(backup, destination);
-        removeOwnScratch([backup]);
+        for (const { original, backup } of [...backups].reverse()) {
+            if (existsSync(backup) && !existsSync(original))
+                move(backup, original);
+        }
+        removeOwnScratch(backups.map(entry => entry.backup));
         throw error;
     }
+    removePublishedBackups(backups.map(entry => entry.backup), fileOps.rmSync || rmSync);
+    return destination;
 }
 export async function instructionSetsCommand(args, io) {
     const positionals = positionalArgs(args);
@@ -148,6 +228,36 @@ export async function instructionSetsCommand(args, io) {
         writeManifest = loadInstructionSetManifest(reference);
     }
     const project = await io.resolveProjectSlug(argValue(args, '--project'));
+    if (subcommand === 'scorers') {
+        const action = reference;
+        const set = positionals[2];
+        const componentKey = argValue(args, '--key');
+        const scorerVersionId = argValue(args, '--scorer-version');
+        if ((action !== 'set-headline' && action !== 'add') ||
+            !set ||
+            !componentKey ||
+            !scorerVersionId) {
+            throw new Error('Usage: orizu instructions scorers set-headline|add <set> --key <component-key> --scorer-version <id> --project <team/project> [--dataset-version <id> --split-set <id> --split <name>] [--json]');
+        }
+        const payload = await responsePayload(await authedFetch(`/api/cli/instruction-sets/${encodeURIComponent(set)}/scorers?project=${encodeURIComponent(project)}`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({
+                componentKey,
+                scorerVersionId,
+                role: action === 'set-headline' ? 'headline' : 'tracked',
+                datasetVersionId: argValue(args, '--dataset-version') || undefined,
+                splitSetId: argValue(args, '--split-set') || undefined,
+                splitName: argValue(args, '--split') || undefined,
+            }),
+        }), `Instruction sets scorers ${action}`);
+        if (io.json)
+            io.print(JSON.stringify(payload));
+        else {
+            io.print(`${action === 'set-headline' ? 'Set headline' : 'Added'} scorer ${sanitizeTerminalText(scorerVersionId)} for ${sanitizeTerminalText(set)} / ${sanitizeTerminalText(componentKey)}`);
+        }
+        return 0;
+    }
     if (subcommand === 'default') {
         const operation = reference;
         const set = positionals[2];
@@ -318,11 +428,11 @@ export async function instructionSetsCommand(args, io) {
         if (!set || (set.slug !== reference && set.name !== reference) || (modelConfig && (!Array.isArray(set.filteredTo) || set.filteredTo.length !== 1 || set.filteredTo[0] !== modelConfig))) {
             throw new Error('instruction_set_sync_response_mismatch');
         }
-        syncToDisk(output, set);
+        const destination = syncToDisk(output, set);
         if (io.json)
             io.print(JSON.stringify(payload));
         else
-            io.print(`Synced ${set.name} to ${join(output, set.name)}`);
+            io.print(`Synced ${set.name} to ${destination}`);
         return 0;
     }
     if (subcommand === 'show' && (!reference || reference.startsWith('--')))

package/dist/skilled-proposer-config.d.ts

@@ -0,0 +1,2 @@
+export declare function normalizedSkilledProposerConfig(value: string): string;
+//# sourceMappingURL=skilled-proposer-config.d.ts.map

package/dist/skilled-proposer-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skilled-proposer-config.d.ts","sourceRoot":"","sources":["../src/skilled-proposer-config.ts"],"names":[],"mappings":"AAoJA,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CA0CrE"}

package/dist/skilled-proposer-config.js

@@ -0,0 +1,212 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, statSync } from 'node:fs';
+import { basename, dirname, extname, relative, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+const CONFIG_KEYS = new Set(['schemaVersion', 'skills', 'additionalInstructionsFile', 'baseInstructionsFile',
+    'maxWords', 'maxTokens', 'maxExamples', 'onError',
+]);
+const PATH_SKILL_KEYS = new Set(['path', 'name', 'description']);
+const INLINE_SKILL_KEYS = new Set(['name', 'description', 'inline']);
+function configError(field, detail) { throw new Error(`--candidate-proposer-config ${field} ${detail}`); }
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function rejectUnknownKeys(value, allowed, field = '') {
+    const unknown = Object.keys(value).find(key => !allowed.has(key));
+    if (unknown)
+        configError(field ? `${field}.${unknown}` : unknown, 'is not supported');
+}
+function sha256(bytes) { return createHash('sha256').update(bytes).digest('hex'); }
+function decodeUtf8(bytes, field) {
+    try {
+        return new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(bytes);
+    }
+    catch {
+        configError(field, 'must contain valid UTF-8 text');
+    }
+}
+function readRegularFile(path, field) {
+    try {
+        if (!statSync(path).isFile())
+            configError(field, 'must resolve to a file');
+        return readFileSync(path);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('--candidate-proposer-config'))
+            throw error;
+        configError(field, `is missing or unreadable: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function logicalSource(configDirectory, path) {
+    return relative(configDirectory, path).split(sep).join('/') || basename(path);
+}
+function normalizedText(bytes, source, field) {
+    const content = decodeUtf8(bytes, field);
+    if (!content.trim())
+        configError(field, 'must not be empty');
+    return { source, content, sha256: sha256(bytes), byteLength: bytes.byteLength };
+}
+function parseFrontmatter(content, field) {
+    const lines = content.split(/\r?\n/);
+    if (lines[0]?.replace(/^\uFEFF/, '').trim() !== '---')
+        return { body: content };
+    const end = lines.slice(1).findIndex(line => line.trim() === '---');
+    if (end < 0)
+        configError(field, 'has malformed frontmatter without a closing ---');
+    const metadata = {};
+    for (const raw of lines.slice(1, end + 1)) {
+        if (/^[ \t]/.test(raw) || !raw.includes(':'))
+            continue;
+        const colon = raw.indexOf(':');
+        metadata[raw.slice(0, colon).trim()] = raw.slice(colon + 1).trim().replace(/^(['"])(.*)\1$/, '$2');
+    }
+    return {
+        name: metadata.name || undefined,
+        description: metadata.description || undefined,
+        body: lines.slice(end + 2).join('\n'),
+    };
+}
+function wellFormedString(value, field) {
+    if (!value.isWellFormed()) {
+        configError(field, 'must contain well-formed Unicode text');
+    }
+    return value;
+}
+function nonEmptyString(value, field) {
+    if (typeof value !== 'string' || !value.trim())
+        configError(field, 'must be a non-empty string');
+    return wellFormedString(value, field);
+}
+function nullableDescription(value, field) {
+    if (value === null)
+        return null;
+    if (typeof value !== 'string')
+        configError(field, 'must be a string or null');
+    return wellFormedString(value, field) || null;
+}
+function normalizePathSkill(entry, index, configDirectory) {
+    const field = `skills[${index}]`;
+    rejectUnknownKeys(entry, PATH_SKILL_KEYS, field);
+    const configuredPath = nonEmptyString(entry.path, `${field}.path`);
+    let resolvedPath = resolve(configDirectory, configuredPath);
+    try {
+        if (statSync(resolvedPath).isDirectory()) {
+            resolvedPath = resolve(resolvedPath, 'SKILL.md');
+            try {
+                if (!statSync(resolvedPath).isFile())
+                    configError(`${field}.path`, 'directory must contain SKILL.md');
+            }
+            catch (error) {
+                if (error instanceof Error && error.message.startsWith('--candidate-proposer-config'))
+                    throw error;
+                configError(`${field}.path`, 'directory must contain SKILL.md');
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.message.startsWith('--candidate-proposer-config'))
+            throw error;
+        configError(`${field}.path`, 'is missing or unreadable');
+    }
+    const text = normalizedText(readRegularFile(resolvedPath, `${field}.path`), logicalSource(configDirectory, resolvedPath), `${field}.path`);
+    const frontmatter = parseFrontmatter(text.content, `${field}.path`);
+    if (!frontmatter.body.trim())
+        configError(`${field}.path`, 'must contain non-empty skill content');
+    const fallbackName = extname(resolvedPath)
+        ? basename(resolvedPath, extname(resolvedPath))
+        : basename(resolvedPath);
+    const name = entry.name === undefined
+        ? frontmatter.name ?? (basename(resolvedPath) === 'SKILL.md' ? basename(dirname(resolvedPath)) : fallbackName)
+        : nonEmptyString(entry.name, `${field}.name`);
+    const description = entry.description === undefined
+        ? frontmatter.description ?? null
+        : nullableDescription(entry.description, `${field}.description`);
+    return { name, description, ...text };
+}
+function normalizeInlineSkill(entry, index) {
+    const field = `skills[${index}]`;
+    rejectUnknownKeys(entry, INLINE_SKILL_KEYS, field);
+    const name = nonEmptyString(entry.name, `${field}.name`);
+    const description = nonEmptyString(entry.description, `${field}.description`);
+    const content = nonEmptyString(entry.inline, `${field}.inline`);
+    const bytes = Buffer.from(content, 'utf8');
+    return { name, description, source: `inline:${name}`, content,
+        sha256: sha256(bytes), byteLength: bytes.byteLength };
+}
+function normalizeSkill(value, index, configDirectory) {
+    const field = `skills[${index}]`;
+    if (!isRecord(value))
+        configError(field, 'must be an object');
+    const hasPath = Object.hasOwn(value, 'path');
+    const hasInline = Object.hasOwn(value, 'inline');
+    if (hasPath === hasInline)
+        configError(field, 'must contain exactly one of path or inline');
+    return hasPath ? normalizePathSkill(value, index, configDirectory) : normalizeInlineSkill(value, index);
+}
+function optionalPositiveInteger(value, field) {
+    if (value === undefined || value === null)
+        return null;
+    if (!Number.isSafeInteger(value) || value <= 0)
+        configError(field, 'must be a positive integer or null');
+    return value;
+}
+function normalizeInstructionFile(value, field, configDirectory) {
+    if (value === undefined || value === null)
+        return null;
+    const configuredPath = nonEmptyString(value, field);
+    const resolvedPath = resolve(configDirectory, configuredPath);
+    return normalizedText(readRegularFile(resolvedPath, field), logicalSource(configDirectory, resolvedPath), field);
+}
+function lockedPackageVersion() {
+    const lockPath = fileURLToPath(new URL('../requirements/skilled-proposer.lock', import.meta.url));
+    const match = /^skilled-proposer==([^\s\\]+)/m.exec(readFileSync(lockPath, 'utf8'));
+    if (!match)
+        throw new Error('ALI_1505_SKILLED_PROPOSER_LOCK_VERSION_MISSING');
+    return match[1];
+}
+export function normalizedSkilledProposerConfig(value) {
+    const suppliedPath = nonEmptyString(value.startsWith('@') ? value.slice(1) : value, 'path');
+    const configPath = resolve(suppliedPath);
+    const configBytes = readRegularFile(configPath, 'path');
+    const raw = decodeUtf8(configBytes, 'path').replace(/^\uFEFF/, '');
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        configError('path', `must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (!isRecord(parsed))
+        configError('path', 'must contain a JSON object');
+    rejectUnknownKeys(parsed, CONFIG_KEYS);
+    if (parsed.schemaVersion !== 1)
+        configError('schemaVersion', 'must be 1');
+    if (!Array.isArray(parsed.skills))
+        configError('skills', 'must be an array');
+    const configDirectory = dirname(configPath);
+    const skills = parsed.skills.map((skill, index) => normalizeSkill(skill, index, configDirectory));
+    const names = new Set();
+    for (const skill of skills) {
+        if (names.has(skill.name))
+            configError('skills', `contains duplicate resolved name ${skill.name}`);
+        names.add(skill.name);
+    }
+    const onError = parsed.onError ?? 'keep';
+    if (onError !== 'keep' && onError !== 'raise')
+        configError('onError', 'must be keep or raise');
+    const normalized = {
+        schemaVersion: 1,
+        implementation: 'cmpnd-ai/skilled-proposer',
+        packageVersion: lockedPackageVersion(),
+        skills,
+        additionalInstructions: normalizeInstructionFile(parsed.additionalInstructionsFile, 'additionalInstructionsFile', configDirectory),
+        baseInstructions: normalizeInstructionFile(parsed.baseInstructionsFile, 'baseInstructionsFile', configDirectory),
+        maxWords: optionalPositiveInteger(parsed.maxWords, 'maxWords'),
+        maxTokens: optionalPositiveInteger(parsed.maxTokens, 'maxTokens'),
+        maxExamples: optionalPositiveInteger(parsed.maxExamples, 'maxExamples'),
+        onError,
+    };
+    const configFileSha256 = sha256(configBytes);
+    const configSha256 = sha256(Buffer.from(JSON.stringify({ configFileSha256, ...normalized }), 'utf8'));
+    return JSON.stringify({ ...normalized, configFileSha256, configSha256 });
+}

package/dist/skilled-proposer-launch.d.ts

@@ -3,5 +3,9 @@ export interface SkilledProposerLaunch {
     python: string;
     environment: NodeJS.ProcessEnv;
 }
+export declare function spawnSkilledProposerChild(command: string, args: string[], engine: GepaEngine, environment: NodeJS.ProcessEnv): Promise<{
+    status: number | null;
+    error?: Error;
+}>;
 export declare function prepareSkilledProposerLaunch(python: string, engine: GepaEngine, environment: NodeJS.ProcessEnv): SkilledProposerLaunch;
 //# sourceMappingURL=skilled-proposer-launch.d.ts.map

package/dist/skilled-proposer-launch.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skilled-proposer-launch.d.ts","sourceRoot":"","sources":["../src/skilled-proposer-launch.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAa3D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAC,UAAU,CAAA;CAC/B;AAwCD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,CAAC,UAAU,GAC7B,qBAAqB,CAwBvB"}
+{"version":3,"file":"skilled-proposer-launch.d.ts","sourceRoot":"","sources":["../src/skilled-proposer-launch.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAa3D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAC,UAAU,CAAA;CAC/B;AAiBD,wBAAsB,yBAAyB,CAC7C,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,UAAU;YA4B9C,MAAM,GAAG,IAAI;YAAU,KAAK;GAUlE;AAwCD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,UAAU,EAClB,WAAW,EAAE,MAAM,CAAC,UAAU,GAC7B,qBAAqB,CAwBvB"}

package/dist/skilled-proposer-launch.js

@@ -1,8 +1,72 @@
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'fs';
+import { tmpdir } from 'os';
 import { join } from 'path';
 import { fileURLToPath } from 'url';
 import { bundledOfficialGepaPythonPath } from './gepa-python-paths.js';
 import { sanitizeTerminalText } from './json-response.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) {
     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));

package/package.json

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

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[] {