orizu 0.5.30 → 0.5.31

package/dist/instruction-set-gepa-launch.js

@@ -1,17 +1,137 @@
 import { authedFetch } from './http.js';
+import { MAX_VERSION_NUMBER, parseSpecifier } from './instruction-set-lock/index.js';
 import { parseJsonResponse } from './json-response.js';
-/** Resolve the requested Profile's Production tuple for optimization. */
-export async function resolveGepaInstructionSetProfileVersion(instructionSetName, modelConfigIdentity, project) {
+/**
+ * A version runs and promotes only when its component keys equal the set's
+ * current shape exactly: promotion refuses any other key set
+ * (instruction_set_candidate_shape_mismatch). Returns null when they match.
+ */
+function shapeDifference(shape, version) {
+    const keys = new Set(version.componentKeys ?? []);
+    const shapeKeys = new Set(shape);
+    const missing = shape.filter(key => !keys.has(key));
+    const extra = [...keys].filter(key => !shapeKeys.has(key)).sort();
+    return missing.length === 0 && extra.length === 0 ? null : { missing, extra };
+}
+function describeDifference({ missing, extra }) {
+    const quote = (keys) => keys.map(key => `"${key}"`).join(', ');
+    return [
+        ...(missing.length > 0 ? [`missing ${quote(missing)}`] : []),
+        ...(extra.length > 0 ? [`extra ${quote(extra)}`] : []),
+    ].join('; ');
+}
+function newestMatchingVersion(shape, versions) {
+    return versions
+        .filter(candidate => Array.isArray(candidate.componentKeys) && shapeDifference(shape, candidate) === null)
+        .reduce((max, candidate) => {
+        const number = candidate.versionNumber ?? 0;
+        return max === null || number > max ? number : max;
+    }, null);
+}
+/**
+ * ORI-2128: a version made before a shape change can lack a component of the
+ * set's current shape, or carry one the set has since removed. The runner or
+ * promotion would refuse it later; refuse it here, before a run is spawned or
+ * queued. A server that predates per-version component keys sends none; the
+ * runner remains the backstop.
+ */
+function requireMatchingSeed(shape, versions, version, modelConfigIdentity, role) {
+    if (!Array.isArray(shape) || !Array.isArray(version.componentKeys))
+        return;
+    const difference = shapeDifference(shape, version);
+    if (difference === null)
+        return;
+    const newest = newestMatchingVersion(shape, versions);
+    const detail = describeDifference(difference);
+    if (role === 'production') {
+        const newestNote = newest === null ? 'no version of this profile matches it yet' : `newest matching: v${newest}`;
+        throw new Error(`instruction_set_profile_production_incomplete: ${modelConfigIdentity} production v${version.versionNumber} does not match the current shape (${detail}); promote a version that matches it, or name one with @vN (${newestNote})`);
+    }
+    const advice = newest === null
+        ? 'no version of this profile matches the current shape yet'
+        : `pick v${newest}`;
+    throw new Error(`instruction_set_profile_version_incomplete: ${modelConfigIdentity} v${version.versionNumber} does not match the current shape (${detail}); ${advice}`);
+}
+function profileVersionNumber(value) {
+    const match = /^v?([1-9][0-9]*)$/u.exec(value);
+    const versionNumber = match ? Number(match[1]) : Number.NaN;
+    if (!Number.isSafeInteger(versionNumber) || versionNumber > MAX_VERSION_NUMBER) {
+        throw new Error(`--profile-version must be a version number such as 3 or v3; received ${value}`);
+    }
+    return versionNumber;
+}
+/**
+ * Combine `--instruction-set`, `--model-config` and `--profile-version` into
+ * one Seed. A value with `/` or `@` is a specifier (`set/profile@vN`); any
+ * other value is a set slug or exact name, passed through unchanged. Values
+ * named twice must agree, the same rule `sync` applies to `--version`.
+ */
+export function gepaSeedSelector(instructionSetArg, modelConfigFlag, versionFlag) {
+    const flagVersion = versionFlag === undefined ? undefined : profileVersionNumber(versionFlag);
+    if (!instructionSetArg.includes('/') && !instructionSetArg.includes('@')) {
+        return { instructionSetName: instructionSetArg, modelConfigIdentity: modelConfigFlag, versionNumber: flagVersion };
+    }
+    const parsed = parseSpecifier(instructionSetArg);
+    if (parsed.profile !== undefined && modelConfigFlag !== undefined && parsed.profile !== modelConfigFlag) {
+        throw new Error(`instruction_set_seed_conflict: specifier names profile ${parsed.profile} but --model-config is ${modelConfigFlag}`);
+    }
+    if (parsed.versionNumber !== undefined && flagVersion !== undefined && parsed.versionNumber !== flagVersion) {
+        throw new Error(`instruction_set_seed_conflict: specifier names v${parsed.versionNumber} but --profile-version is v${flagVersion}`);
+    }
+    return {
+        instructionSetName: parsed.set,
+        modelConfigIdentity: parsed.profile ?? modelConfigFlag,
+        versionNumber: parsed.versionNumber ?? flagVersion,
+    };
+}
+/**
+ * Resolve the Seed's profile version id: the named version when one is
+ * given, otherwise the requested Profile's Production.
+ */
+async function resolveGepaInstructionSetProfileVersion(instructionSetName, modelConfigIdentity, project, versionNumber) {
     const response = await authedFetch(`/api/cli/instruction-sets/${encodeURIComponent(instructionSetName)}?project=${encodeURIComponent(project)}`);
     if (!response.ok)
         throw new Error(`Instruction set resolution failed: ${await response.text()}`);
     const payload = await parseJsonResponse(response, 'Instruction set resolution');
     const instructionSet = payload.instructionSet;
     const profile = instructionSet?.profiles?.find(candidate => candidate.modelConfigIdentity === modelConfigIdentity);
-    if (!profile)
+    // An archived model config's profile is not resolvable: the same refusal
+    // the server's resolve_instruction_set gives hosted runs.
+    if (!profile || profile.modelConfigArchivedAt)
         throw new Error(`instruction_set_profile_not_found: ${modelConfigIdentity}`);
+    const versions = profile.versions ?? [];
+    if (versionNumber !== undefined) {
+        const version = versions.find(candidate => candidate.versionNumber === versionNumber);
+        if (version?.profileVersionId) {
+            requireMatchingSeed(instructionSet?.shape, versions, version, modelConfigIdentity, 'named');
+            return version.profileVersionId;
+        }
+        const newest = versions.reduce((max, candidate) => Math.max(max, candidate.versionNumber ?? 0), 0);
+        throw new Error(`instruction_set_profile_version_not_found: ${modelConfigIdentity} has no v${versionNumber}; ${newest > 0 ? `newest is v${newest}` : 'it has no versions'}`);
+    }
     const profileVersionId = profile.production?.profileVersionId;
     if (!profileVersionId)
         throw new Error(`instruction_set_profile_not_promoted: ${modelConfigIdentity}`);
+    const production = versions.find(candidate => candidate.profileVersionId === profileVersionId);
+    if (production)
+        requireMatchingSeed(instructionSet?.shape, versions, production, modelConfigIdentity, 'production');
     return profileVersionId;
 }
+/**
+ * Resolve the Seed that dispatch normalised into the connector environment.
+ * Returns undefined when no instruction set was selected. When no version is
+ * named, `unversioned: 'production'` resolves the profile's Production here
+ * (local runs); `unversioned: 'server'` leaves it to the hosted launch route,
+ * which resolves Production itself in the same call that queues the run.
+ */
+export async function resolveGepaSeedFromEnvironment(environment, project, unversioned) {
+    const instructionSetName = environment.ORIZU_INSTRUCTION_SET_NAME;
+    const modelConfigIdentity = environment.ORIZU_MODEL_CONFIG_IDENTITY;
+    if (!instructionSetName || !modelConfigIdentity)
+        return undefined;
+    const rawVersion = environment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_NUMBER;
+    const versionNumber = rawVersion === undefined ? undefined : profileVersionNumber(rawVersion);
+    if (versionNumber === undefined && unversioned === 'server')
+        return undefined;
+    return resolveGepaInstructionSetProfileVersion(instructionSetName, modelConfigIdentity, project, versionNumber);
+}

package/dist/optimizations-promote-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"optimizations-promote-cli.d.ts","sourceRoot":"","sources":["../src/optimizations-promote-cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAEpD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACjE;AA0DD,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiD1G"}
+{"version":3,"file":"optimizations-promote-cli.d.ts","sourceRoot":"","sources":["../src/optimizations-promote-cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAGpD,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,OAAO,CAAA;IACb,MAAM,EAAE,WAAW,CAAA;IACnB,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAC7B,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAA;IAChC,kBAAkB,EAAE,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,KAAK,OAAO,CAAC,MAAM,CAAC,CAAA;IAClE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;CACjE;AAqED,wBAAsB,0BAA0B,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,sBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC,CAuD1G"}

package/dist/optimizations-promote-cli.js

@@ -54,6 +54,17 @@ function productionPromotionReplay(runId, candidateId, project, origin) {
             : '';
     return `Promote this profile with: orizu${originArguments} optimizations promote ${shellArgument(runId)} --candidate ${shellArgument(candidateId)} --label production --project ${shellArgument(project)}`;
 }
+/**
+ * ORI-2128: a candidate grown from a Seed older than Production does not
+ * contain the changes made since that Seed. Warn; never refuse (ORI-2132).
+ */
+function staleSeedWarningFor(data) {
+    const seed = data.runSeedVersionNumber;
+    const production = data.productionVersionNumber;
+    if (typeof seed !== 'number' || typeof production !== 'number' || seed >= production)
+        return null;
+    return `Warning: this run started from v${seed}; production is v${production}. Changes made since v${seed} are not in this candidate.`;
+}
 export async function promoteOptimizationCommand(args, io) {
     const runId = args.find(arg => !arg.startsWith('--') && arg !== option(args, '--candidate') && arg !== option(args, '--label') && arg !== option(args, '--project'));
     const candidateId = option(args, '--candidate');
@@ -72,15 +83,21 @@ export async function promoteOptimizationCommand(args, io) {
     const replay = isProfilePromotion && data.appliedLabel !== 'production'
         ? productionPromotionReplay(runId, candidateId, project, io.origin)
         : null;
+    const staleSeedWarning = isProfilePromotion ? staleSeedWarningFor(data) : null;
     if (io.json) {
         io.print(JSON.stringify(isProfilePromotion
             ? {
                 profileVersionId: data.profileVersionId,
                 versionNumber: data.versionNumber,
                 appliedLabel: data.appliedLabel,
+                // JSON.stringify omits these when an older server did not send them.
+                runSeedVersionNumber: data.runSeedVersionNumber,
+                productionVersionNumber: data.productionVersionNumber,
                 components: data.components,
             }
             : { promptVersionId: data.promptVersionId }));
+        if (staleSeedWarning)
+            io.printErr(staleSeedWarning);
         if (isProfilePromotion && data.appliedLabel === undefined) {
             io.printErr(APPLIED_LABEL_VERSION_SKEW_NOTE);
             io.printErr(replay);
@@ -88,6 +105,8 @@ export async function promoteOptimizationCommand(args, io) {
         return;
     }
     if (isProfilePromotion) {
+        if (staleSeedWarning)
+            io.printErr(staleSeedWarning);
         io.print(`Promoted profile version ${sanitizeTerminalText(data.profileVersionId)}`);
         if (data.appliedLabel === undefined) {
             io.printErr(APPLIED_LABEL_VERSION_SKEW_NOTE);

package/dist/seed-against-production.d.ts

@@ -0,0 +1,11 @@
+/**
+ * ORI-2128: what `optimizations promote` needs to warn about a stale seed.
+ * The run's seed version number, and its profile's production version number
+ * as it stood before this promotion (null when the profile had none).
+ * Shared by the promote handler, both promote routes, and the CLI.
+ */
+export interface SeedAgainstProduction {
+    runSeedVersionNumber: number;
+    productionVersionNumber: number | null;
+}
+//# sourceMappingURL=seed-against-production.d.ts.map

package/dist/seed-against-production.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-against-production.d.ts","sourceRoot":"","sources":["../src/seed-against-production.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,WAAW,qBAAqB;IACpC,oBAAoB,EAAE,MAAM,CAAA;IAC5B,uBAAuB,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC"}

package/dist/seed-against-production.js

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

package/package.json

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

package/src/gepa-engine-dispatch.ts

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync } from 'fs'
 
+import { gepaSeedSelector } from './instruction-set-gepa-launch.js'
 import { providerFromIdentity, protocolRequiresOutputCap } from './provider-registry.js'
 import { normalizedSkilledProposerConfig } from './skilled-proposer-config.js'
 
@@ -58,6 +59,7 @@ const VALUE_OPTIONS: EnvironmentOption[] = [
   { flag: '--log-dir', environment: 'ORIZU_LOCAL_LOG_DIR' },
   { flag: '--instruction-set', environment: 'ORIZU_INSTRUCTION_SET_NAME' },
   { flag: '--model-config', environment: 'ORIZU_MODEL_CONFIG_IDENTITY' },
+  { flag: '--profile-version', environment: 'ORIZU_INSTRUCTION_SET_PROFILE_VERSION_NUMBER' },
 ]
 
 const BOOLEAN_OPTIONS = [
@@ -301,6 +303,21 @@ function translateOfficialOptions(args: string[], project: string, environment:
     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')
   }
   if (hasInstructionSet && hasCandidateVersion) throw new Error('--instruction-set and --candidate-version-id are mutually exclusive')
+  if (!hasInstructionSet && connectorEnvironment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_NUMBER !== undefined) {
+    throw new Error('--profile-version requires --instruction-set')
+  }
+  if (hasInstructionSet) {
+    // ORI-2128: the Seed may be named by a full specifier, by flags, or both;
+    // normalise to the set reference, the profile, and the version number.
+    const seed = gepaSeedSelector(
+      connectorEnvironment.ORIZU_INSTRUCTION_SET_NAME!,
+      connectorEnvironment.ORIZU_MODEL_CONFIG_IDENTITY,
+      connectorEnvironment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_NUMBER,
+    )
+    connectorEnvironment.ORIZU_INSTRUCTION_SET_NAME = seed.instructionSetName
+    if (seed.modelConfigIdentity !== undefined) connectorEnvironment.ORIZU_MODEL_CONFIG_IDENTITY = seed.modelConfigIdentity
+    if (seed.versionNumber !== undefined) connectorEnvironment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_NUMBER = String(seed.versionNumber)
+  }
   if (hasInstructionSet && connectorEnvironment.ORIZU_MODEL_CONFIG_IDENTITY === undefined) throw new Error('--instruction-set requires --model-config')
   if (hasInstructionSet && connectorEnvironment.ORIZU_COMPONENT_SELECTOR === undefined) connectorEnvironment.ORIZU_COMPONENT_SELECTOR = 'round_robin'
   if ((connectorEnvironment.ORIZU_PROPOSAL_MAX_CALLS !== undefined
@@ -355,7 +372,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', '--candidate-proposer-config', '--proposal-max-calls', '--proposal-max-tokens']) {
+    for (const flag of ['--instruction-set', '--model-config', '--profile-version', '--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/help.ts

@@ -682,8 +682,8 @@ export const COMMAND_DOCS: CliCommandDoc[] = [
   },
   {
     path: ['optimizations', 'run-gepa'],
-    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-managed sandbox launch. Hosted eligibility requires a staff-enabled team, capacity below its concurrent-run cap, a launch-project optimizer version whose validated manifest.optimizer_family is gepa, registered candidate/scorer runners, a reflection model from a registered provider, and a named --budget preset within the team ceiling. Hosted eligibility catalog refusals use stable code/remediation JSON with optional bounded detail, and capacity refusals include monitor URLs for running runs. A successful launch prints a durable monitor URL; queued means accepted, not completed. Hosted mode does not require --candidate-runner-dir or --scorer-runner-dir; when supplied, those directories must byte-match their registered versions. Retry response loss with the same --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).',
+    usage: 'orizu optimizations run-gepa [--hosted [--launch-intent-id <uuid>]] --project <team/project> --optimizer-version-id <id> (--candidate-version-id <id> | --instruction-set <set[/profile[@vN]]> [--model-config <identity>] [--profile-version <N>] [--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-managed sandbox launch. Hosted eligibility requires a staff-enabled team, capacity below its concurrent-run cap, a launch-project optimizer version whose validated manifest.optimizer_family is gepa, registered candidate/scorer runners, a reflection model from a registered provider, and a named --budget preset within the team ceiling. Hosted eligibility catalog refusals use stable code/remediation JSON with optional bounded detail, and capacity refusals include monitor URLs for running runs. A successful launch prints a durable monitor URL; queued means accepted, not completed. Hosted mode does not require --candidate-runner-dir or --scorer-runner-dir; when supplied, those directories must byte-match their registered versions. Retry response loss with the same --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 needs a profile, named by --model-config or a set/profile specifier, and cannot be combined with --candidate-version-id. The run starts from the production version of that profile unless @vN or --profile-version <N> names another version (the seed, promoted or not); a specifier and flags that name different values are refused; 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-gepa-cli.ts

@@ -1,6 +1,7 @@
 import { randomUUID } from 'node:crypto'
 
 import { dispatchGepaEngine } from './gepa-engine-dispatch.js'
+import { resolveGepaSeedFromEnvironment } from './instruction-set-gepa-launch.js'
 import { parseHostedGepaNumericValue } from './hosted-gepa-numeric-values.js'
 import { authedFetch } from './http.js'
 import { hostedProviderFromModel, hostedProviderSettingsError, unsupportedHostedProviderMessage } from './hosted-provider-settings.js'
@@ -216,11 +217,16 @@ export async function runHostedGepaOptimization(options: HostedGepaOptions): Pro
       : kind === 'json' ? JSON.parse(env[name]!) : kind === 'boolean' ? env[name] === '1' : env[name]
   }
   const launchIntentId = explicitLaunchIntent || randomUUID()
+  // ORI-2128: a named Seed version is resolved here exactly as a local run
+  // resolves it, and pinned in the body; without one the server keeps its
+  // one-call production lookup.
+  const seedProfileVersionId = await resolveGepaSeedFromEnvironment(env, options.project, 'server')
   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 } : {}),
+      modelConfigIdentity: env.ORIZU_MODEL_CONFIG_IDENTITY, componentSelector: env.ORIZU_COMPONENT_SELECTOR,
+      ...(seedProfileVersionId ? { instructionSetProfileVersionId: seedProfileVersionId } : {}) } : {}),
     runnerVersionId: env.ORIZU_RUNNER_VERSION_ID,
     scorers: [{ scorerVersionId: env.ORIZU_SCORER_VERSION_ID,
       scorerRunnerVersionId: env.ORIZU_SCORER_RUNNER_VERSION_ID, role: 'selection', scorerConfig: {} }],

package/src/hosted-harness-claude.ts

@@ -95,6 +95,7 @@
 
 import { parseModelIdentity } from './provider-registry.js'
 
+import { HARNESS_NAMES } from './hosted-harness.js'
 import type {
   AgentHarness,
   HarnessEvent,
@@ -323,7 +324,7 @@ export function createClaudeAgentHarness(
   }
 
   return {
-    name: 'claude-agent-sdk',
+    name: HARNESS_NAMES.claudeAgentSdk,
 
     async start(opts: HarnessStartOptions): Promise<{ agentSessionId: string }> {
       startModel = opts.model
@@ -471,6 +472,7 @@ export function createClaudeAgentHarness(
                   args: asRecord(block.input),
                   callId,
                   status: 'running',
+                  harness: HARNESS_NAMES.claudeAgentSdk,
                 },
               }
             }
@@ -495,6 +497,7 @@ export function createClaudeAgentHarness(
                   callId,
                   status: block.is_error === true ? 'error' : 'completed',
                   output: toolResultOutput(block.content),
+                  harness: HARNESS_NAMES.claudeAgentSdk,
                 },
               }
             }

package/src/hosted-harness-opencode.ts

@@ -53,11 +53,13 @@ import { readFileSync } from 'fs'
 
 import { findProvider, parseModelIdentity } from './provider-registry.js'
 
+import { HARNESS_NAMES } from './hosted-harness.js'
 import type {
   AgentHarness,
   HarnessEvent,
   HarnessPrompt,
   HarnessStartOptions,
+  HarnessToolPayload,
 } from './hosted-harness.js'
 
 // OpenCode is HARD-PINNED to this version everywhere it is installed/launched.
@@ -121,7 +123,9 @@ class PromptAbortedError extends Error {
 // -- OpenCode ascending id generator (port of OpenCode's id.ts) --------------
 // Monotonic so our user-message id always sorts AFTER any prior assistant
 // message id — this is what prevents OpenCode's prompt loop from early-exiting
-// on `lastUser.id < lastAssistant.id`.
+// on `lastUser.id < lastAssistant.id`. Shape (opencode-ai@1.14.41): prefix, `_`,
+// 12 hex digits holding the low 48 bits of `ms * 4096 + counter`, then 14
+// base62 characters. `nowMs` is a parameter only so tests can pin the clock.
 const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
 let idLastTimestamp = 0
 let idCounter = 0
@@ -134,14 +138,15 @@ function randomBase62(length: number): string {
   return out
 }
 
-function ascendingId(prefix: 'ses' | 'msg' | 'prt'): string {
-  const nowMs = Date.now()
+export function ascendingId(prefix: 'ses' | 'msg' | 'prt', nowMs: number = Date.now()): string {
   if (nowMs !== idLastTimestamp) {
     idLastTimestamp = nowMs
     idCounter = 0
   }
   idCounter += 1
-  const encoded = (nowMs * 0x1000 + idCounter) & 0xffffffffffff
+  // BigInt, as OpenCode does: the JS `&` operator works on 32 bits, which made
+  // short, sometimes negative ids that sorted before OpenCode's own (ORI-2116).
+  const encoded = (BigInt(nowMs) * BigInt(0x1000) + BigInt(idCounter)) & BigInt(0xffffffffffff)
   const hex = encoded.toString(16).padStart(12, '0')
   return `${prefix}_${hex}${randomBase62(14)}`
 }
@@ -495,7 +500,7 @@ export function createOpenCodeHarness(options: OpenCodeHarnessOptions): AgentHar
   }
 
   return {
-    name: 'opencode',
+    name: HARNESS_NAMES.opencode,
 
     async start(opts: HarnessStartOptions): Promise<{ agentSessionId: string }> {
       startModel = opts.model
@@ -598,13 +603,25 @@ export function createOpenCodeHarness(options: OpenCodeHarnessOptions): AgentHar
           if (emittedToolStates.has(toolKey)) return events
           emittedToolStates.add(toolKey)
           const terminal = status === 'completed' || status === 'error'
-          const payload: Record<string, unknown> = {
+          const payload: HarnessToolPayload = {
             tool: typeof part.tool === 'string' ? part.tool : '',
             args: input,
             callId,
             status,
+            harness: HARNESS_NAMES.opencode,
+          }
+          // A failed call keeps its message in `state.error`, not `state.output`
+          // (opencode-ai@1.14.41 ToolStateError); it is that call's output.
+          if (terminal) {
+            payload.output = typeof state.output === 'string' ? state.output
+              : typeof state.error === 'string' ? state.error : ''
+          }
+          // OpenCode's own one-line title and structured extras (ORI-2160),
+          // passed through as given; absent when the state has none.
+          if (typeof state.title === 'string' && state.title.length > 0) payload.title = state.title
+          if (state.metadata && typeof state.metadata === 'object' && !Array.isArray(state.metadata)) {
+            payload.metadata = state.metadata as Record<string, unknown>
           }
-          if (terminal) payload.output = typeof state.output === 'string' ? state.output : ''
           events.push({ kind: terminal ? 'tool_result' : 'tool_call', messageId: msgId, payload })
         } else if (partType === 'step-start') {
           events.push({ kind: 'step_start', messageId: msgId, payload: {} })

package/src/hosted-harness.ts

@@ -117,8 +117,39 @@ export interface HarnessEvent {
   critical?: boolean
 }
 
+/** The drivers' stable names. A tool event's `harness` field is one of these. */
+export const HARNESS_NAMES = {
+  opencode: 'opencode',
+  claudeAgentSdk: 'claude-agent-sdk',
+} as const
+
+type HarnessName = (typeof HARNESS_NAMES)[keyof typeof HARNESS_NAMES]
+
+/**
+ * Payload of a `tool_call` / `tool_result` event (ORI-2160). One chat renderer
+ * shows every tool call whatever harness produced it, so the payload carries:
+ *   • `title`    — the harness's one-line summary of the call (OpenCode's
+ *                  `state.title`). Absent when the harness has none.
+ *   • `metadata` — structured extras such as a diff, an exit code or match
+ *                  counts (OpenCode's `state.metadata`). Absent when none.
+ *   • `harness`  — which driver produced the event.
+ * All three are optional: an event without them is still a valid tool event.
+ * The sink and the digest pass them through unchanged.
+ */
+export interface HarnessToolPayload {
+  [key: string]: unknown
+  tool?: string
+  args?: Record<string, unknown>
+  callId: string
+  status: string
+  output?: string
+  title?: string
+  metadata?: Record<string, unknown>
+  harness?: HarnessName
+}
+
 export interface AgentHarness {
-  /** Stable driver name — "opencode" | "claude-agent-sdk". */
+  /** Stable driver name — one of HARNESS_NAMES. */
   readonly name: string
   /** Boot the agent process/session; returns the resumable agent session id. */
   start(opts: HarnessStartOptions): Promise<{ agentSessionId: string }>

package/src/hosted-tool-hints.ts

@@ -0,0 +1,153 @@
+/**
+ * Tool display hints (ORI-2160, moved here for ORI-2167).
+ *
+ * Each harness driver has its own built-in tools. This module holds, per
+ * driver, what the chat needs to show a call without switching on its name:
+ * a category (icon), a label (the verb on the row), the input key that
+ * summarizes the call, how to show the output, and input keys to hide.
+ *
+ * It has no imports with side effects, so both the CLI and the web app
+ * (the chat renderer, and the activity projection that picks which input
+ * key reaches the browser) import it directly.
+ */
+// Type-only, so the web build never has to load the harness module itself.
+import type { HARNESS_NAMES } from './hosted-harness.js'
+
+type HarnessNames = typeof HARNESS_NAMES
+const OPENCODE: HarnessNames['opencode'] = 'opencode'
+const CLAUDE_AGENT_SDK: HarnessNames['claudeAgentSdk'] = 'claude-agent-sdk'
+
+/** What kind of thing a tool does — the renderer picks an icon/layout from
+ *  this, never from the tool name. */
+export const TOOL_CATEGORIES = {
+  file: 'file',
+  command: 'command',
+  search: 'search',
+  network: 'network',
+  question: 'question',
+  subAgent: 'sub-agent',
+  list: 'list',
+  plug: 'plug',
+  other: 'other',
+} as const
+
+export type ToolCategory = (typeof TOOL_CATEGORIES)[keyof typeof TOOL_CATEGORIES]
+
+/** How the tool's output text should be shown. */
+export const TOOL_OUTPUT_KINDS = {
+  text: 'text',
+  diff: 'diff',
+  markdown: 'markdown',
+  json: 'json',
+  list: 'list',
+} as const
+
+type ToolOutputKind = (typeof TOOL_OUTPUT_KINDS)[keyof typeof TOOL_OUTPUT_KINDS]
+
+/** Per-tool display hint. Each driver owns a table of these for its built-in
+ *  tools, so tool-name knowledge lives behind the seam. */
+export interface ToolHint {
+  category: ToolCategory
+  /** The verb the chat row shows ("Read", "Ran"). A tool without a hint shows
+   *  its own name instead. */
+  label?: string
+  /** The input key whose value summarizes the call (e.g. `command`), or null
+   *  when the tool takes no input worth summarizing. */
+  summaryKey: string | null
+  outputKind: ToolOutputKind
+  /** Input keys whose values must not be shown as-is (large bodies such as a
+   *  file's full new content, or likely secrets). */
+  redactKeys: readonly string[]
+}
+
+export type ToolHintTable = Readonly<Record<string, ToolHint>>
+
+// Argument names that look like they hold a credential. Redacted for every
+// tool, and never used as the fallback summary.
+const SECRET_LOOKING_KEY = /token|secret|password|passwd|api[_-]?key|authorization|credential/i
+
+/**
+ * Look a tool up in a driver's hint table. A tool the table does not know (an
+ * MCP tool, a plug-in) falls back to the `plug` category, summarized by its
+ * first non-empty string argument that does not look like a secret.
+ */
+export function resolveToolHint(
+  table: ToolHintTable,
+  tool: string,
+  args: Record<string, unknown> = {}
+): ToolHint {
+  const known = Object.hasOwn(table, tool) ? table[tool] : undefined
+  const secretKeys = Object.keys(args).filter(key => SECRET_LOOKING_KEY.test(key))
+  const redactKeys = [...new Set([...(known?.redactKeys ?? []), ...secretKeys])]
+  if (known) return { ...known, redactKeys }
+  const summaryKey =
+    Object.keys(args).find(key => {
+      const value = args[key]
+      return typeof value === 'string' && value.length > 0 && !redactKeys.includes(key)
+    }) ?? null
+  return { category: TOOL_CATEGORIES.plug, summaryKey, outputKind: TOOL_OUTPUT_KINDS.text, redactKeys }
+}
+
+// OpenCode's built-in tools, as the pinned opencode-ai@1.14.41 tool registry
+// lists them, with the input key that summarizes each call. Tools not listed
+// here (MCP tools, plug-ins) resolve to `plug` through resolveToolHint.
+export const OPENCODE_TOOL_HINTS: ToolHintTable = {
+  read: { category: 'file', label: 'Read', summaryKey: 'filePath', outputKind: 'text', redactKeys: [] },
+  edit: { category: 'file', label: 'Edited', summaryKey: 'filePath', outputKind: 'diff', redactKeys: ['oldString', 'newString'] },
+  write: { category: 'file', label: 'Wrote', summaryKey: 'filePath', outputKind: 'text', redactKeys: ['content'] },
+  apply_patch: { category: 'file', label: 'Edited', summaryKey: 'patchText', outputKind: 'diff', redactKeys: [] },
+  lsp: { category: 'file', label: 'Checked', summaryKey: 'filePath', outputKind: 'json', redactKeys: [] },
+  bash: { category: 'command', label: 'Ran', summaryKey: 'command', outputKind: 'text', redactKeys: [] },
+  glob: { category: 'search', label: 'Listed', summaryKey: 'pattern', outputKind: 'list', redactKeys: [] },
+  grep: { category: 'search', label: 'Searched', summaryKey: 'pattern', outputKind: 'text', redactKeys: [] },
+  webfetch: { category: 'network', label: 'Fetched', summaryKey: 'url', outputKind: 'markdown', redactKeys: [] },
+  websearch: { category: 'network', label: 'Searched', summaryKey: 'query', outputKind: 'text', redactKeys: [] },
+  question: { category: 'question', label: 'Asked', summaryKey: 'questions', outputKind: 'text', redactKeys: [] },
+  plan_exit: { category: 'question', label: 'Asked', summaryKey: null, outputKind: 'text', redactKeys: [] },
+  task: { category: 'sub-agent', label: 'Sub-agent', summaryKey: 'description', outputKind: 'markdown', redactKeys: [] },
+  todowrite: { category: 'list', label: 'Planned', summaryKey: 'todos', outputKind: 'json', redactKeys: [] },
+  skill: { category: 'other', label: 'Loaded', summaryKey: 'name', outputKind: 'markdown', redactKeys: [] },
+  invalid: { category: 'other', label: 'Invalid', summaryKey: 'tool', outputKind: 'text', redactKeys: [] },
+}
+
+// The Claude Agent SDK's built-in tools (SDK 0.3.201: input types in
+// sdk-tools.d.ts, names from the SDK; `Task` is the older name of `Agent`),
+// with the input key that summarizes each call. MCP tools
+// (`mcp__<server>__<tool>`) are not listed and resolve to `plug` through
+// resolveToolHint. This driver sends no `title` or `metadata`: the SDK has no
+// equivalent of OpenCode's.
+export const CLAUDE_TOOL_HINTS: ToolHintTable = {
+  Read: { category: 'file', label: 'Read', summaryKey: 'file_path', outputKind: 'text', redactKeys: [] },
+  Edit: { category: 'file', label: 'Edited', summaryKey: 'file_path', outputKind: 'text', redactKeys: ['old_string', 'new_string'] },
+  Write: { category: 'file', label: 'Wrote', summaryKey: 'file_path', outputKind: 'text', redactKeys: ['content'] },
+  NotebookEdit: { category: 'file', label: 'Edited', summaryKey: 'notebook_path', outputKind: 'text', redactKeys: ['new_source'] },
+  Bash: { category: 'command', label: 'Ran', summaryKey: 'command', outputKind: 'text', redactKeys: [] },
+  TaskOutput: { category: 'command', label: 'Checked', summaryKey: 'task_id', outputKind: 'text', redactKeys: [] },
+  TaskStop: { category: 'command', label: 'Stopped', summaryKey: 'task_id', outputKind: 'text', redactKeys: [] },
+  Glob: { category: 'search', label: 'Listed', summaryKey: 'pattern', outputKind: 'list', redactKeys: [] },
+  Grep: { category: 'search', label: 'Searched', summaryKey: 'pattern', outputKind: 'text', redactKeys: [] },
+  WebFetch: { category: 'network', label: 'Fetched', summaryKey: 'url', outputKind: 'markdown', redactKeys: [] },
+  WebSearch: { category: 'network', label: 'Searched', summaryKey: 'query', outputKind: 'text', redactKeys: [] },
+  AskUserQuestion: { category: 'question', label: 'Asked', summaryKey: 'questions', outputKind: 'text', redactKeys: [] },
+  ExitPlanMode: { category: 'question', label: 'Asked', summaryKey: null, outputKind: 'markdown', redactKeys: [] },
+  Agent: { category: 'sub-agent', label: 'Sub-agent', summaryKey: 'description', outputKind: 'markdown', redactKeys: [] },
+  Task: { category: 'sub-agent', label: 'Sub-agent', summaryKey: 'description', outputKind: 'markdown', redactKeys: [] },
+  TodoWrite: { category: 'list', label: 'Planned', summaryKey: 'todos', outputKind: 'text', redactKeys: [] },
+  ListMcpResourcesTool: { category: 'plug', label: 'Listed', summaryKey: 'server', outputKind: 'json', redactKeys: [] },
+  ReadMcpResourceTool: { category: 'plug', label: 'Read', summaryKey: 'uri', outputKind: 'text', redactKeys: [] },
+  Skill: { category: 'other', label: 'Loaded', summaryKey: 'skill', outputKind: 'markdown', redactKeys: [] },
+}
+
+const NO_HINTS: ToolHintTable = {}
+
+/**
+ * The hint table for the harness that produced an event. Events recorded
+ * before the seam named its harness came from OpenCode, the default driver.
+ * A harness with no table here (a future pi driver, say) gets none, so every
+ * tool falls back to its own name and first string argument.
+ */
+export function toolHintsFor(harness: string | undefined): ToolHintTable {
+  if (harness === undefined || harness === OPENCODE) return OPENCODE_TOOL_HINTS
+  if (harness === CLAUDE_AGENT_SDK) return CLAUDE_TOOL_HINTS
+  return NO_HINTS
+}