orizu 0.5.19 → 0.5.21

package/src/index.ts

@@ -66,11 +66,15 @@ import {
   workspaceExists,
 } from './workspace.js'
 import { connectorsCommand } from './connectors-cli.js'
+import { modelConfigsCommand } from './model-configs-cli.js'
 import { ARTIFACT_MAX_BYTES, runnerOptimizerCommand } from './artifact-pull.js'
 import { killSwitchCommand } from './kill-switch-cli.js'
 import { egressAllowlistCommand } from './egress-allowlist-cli.js'
 import { acceptScoreRunCommand } from './scores-accept-cli.js'
 import { listOptimizationRunsCommand } from './optimizations-list-cli.js'
+import { promoteOptimizationCommand } from './optimizations-promote-cli.js'
+import { scorersCommand } from './scorers-cli.js'
+import { verifyScorerParityCommand } from './scorers-verify-parity.js'
 import {
   archiveArtifactCommand,
   listAssignmentsCommand,
@@ -85,9 +89,12 @@ import { workbenchCommand } from './workbench-cli.js'
 import { hostedCommand } from './hosted-session-cli.js'
 import { workspaceSyncCommand } from './workspace-sync.js'
 import { runGitCredentialInvocation } from './git-credential.js'
+import { instructionSetsCommand, syncToDisk } from './instruction-sets-cli.js'; export { loadInstructionSet } from './instruction-set-loader.js'
+import { runnerInputInstructionSet, runnerInputPrompt, runnerInstructionSetSyncSet, type RunnerInstructionSet } from './runner-instruction-set-contract.js'
 import { pushPromptDraft } from './prompt-draft-push.js'
 import { readMarkdownReportInput } from './markdown-report-input.js'
 import { promptPushErrorMessage, promptReportCommand } from './prompt-report-cli.js'
+import { setPromptLabel } from './prompt-label-cli.js'
 import { printPromptSummaryTable } from './prompt-summary-table.js'
 import type {
   CliLengthMeasurementUnavailableReason,
@@ -98,6 +105,7 @@ import { runScorersRegister } from './scorer-draft-push.js'
 import { runZipArtifactPush } from './zip-draft-push.js'
 import { type GithubLinkResult, runGithubLink, runInteractiveHostedSetup } from './github-setup.js'
 import { parseJsonResponse, sanitizeTerminalText } from './json-response.js'
+import { reportReplacementWarning } from './report-replacement-warning.js'
 import {
   reportCommentsCommand,
   throwDeprecatedPromptCommentsCommand,
@@ -105,6 +113,11 @@ import {
 } from './report-comments-cli.js'
 import { diffCommentsCommand } from './diff-comments-cli.js'
 import { exportOptimizationRunCommand } from './optimization-export-cli.js'
+import { dispatchGepaEngine } from './gepa-engine-dispatch.js'
+import { resolveGepaInstructionSetProfileVersion } from './instruction-set-gepa-launch.js'
+import { getGepaPythonCommand } from './gepa-python-command.js'
+import { getGepaPythonPathEntries } from './gepa-python-paths.js'
+import { prepareSkilledProposerLaunch } from './skilled-proposer-launch.js'
 
 export { parseJsonResponse, sanitizeTerminalText } from './json-response.js'
 
@@ -191,6 +204,10 @@ interface PromptSummary {
   lengthStatsUnavailableReason?: CliLengthMeasurementUnavailableReason
   lengthStatsVersionId?: string
   lengthStatsVersionNumber?: number
+  owner?: {
+    instructionSetSlug: string
+    componentKey: string
+  } | null
 }
 
 interface TaskReportPayload {
@@ -225,7 +242,7 @@ interface ScoreSubmitInput {
 
 interface RunnerExecContext {
   prompt: {
-    body: string | null
+    body?: string | null
     bodyKind: string
     providerSettings: Record<string, unknown>
     promptId?: string
@@ -237,6 +254,7 @@ interface RunnerExecContext {
     metricKey: string
     higherIsBetter: boolean
   } | null
+  instructionSet?: RunnerInstructionSet
   rows: Array<{
     id: string
     row: Record<string, unknown>
@@ -473,6 +491,14 @@ function printError(message: string): void {
   console.error(sanitizeTerminalText(message))
 }
 
+function printPushDisclosures(data: Record<string, unknown>): void {
+  const warning = reportReplacementWarning(data)
+  if (warning) printError(warning)
+  if (data.metadata_updated === true) {
+    printError('Updated prompt metadata on the identical existing version')
+  }
+}
+
 export function validateBrowserUrl(url: string, expectedOrigin?: string): URL {
   let parsed: URL
   try {
@@ -1514,7 +1540,10 @@ async function pushPromptArtifact(kind: 'prompt' | 'judge') {
       report,
     })
     if (hasJsonFlag()) printJson(data)
-    else printLine(message)
+    else {
+      printPushDisclosures(data)
+      printLine(message)
+    }
     return
   }
 
@@ -1564,6 +1593,7 @@ async function pushPromptArtifact(kind: 'prompt' | 'judge') {
     return
   }
 
+  printPushDisclosures(data)
   printLine(`Pushed ${kind} ${sanitizeTerminalText(String(manifest.name || promptDir))} (${sanitizeTerminalText(String(data.prompt_version_id || 'unknown version'))})`)
 }
 
@@ -1618,6 +1648,10 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       metricKey: string
       higherIsBetter: boolean
     }>
+    owner?: {
+      instructionSetSlug: string
+      componentKey: string
+    } | null
   }>(response, `${kind} pull`)
 
   const targetDir = expandHomePath(outDir)
@@ -1704,6 +1738,7 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       scorer_version_id: data.scorerVersionId || undefined,
       scorer_version_ids: scorerVersions.map(item => item.id),
       path: targetDir,
+      owner: data.owner || undefined,
     })
     return
   }
@@ -1719,73 +1754,17 @@ async function pullPromptArtifact(kind: 'prompt' | 'judge') {
       `Warning: prompt version ${sanitizeTerminalText(data.version.id)} does not map to an executable scorer version.`
     )
   }
-}
-
-async function setPromptLabel() {
-  const promptName = getPositionalArg(3)
-  const label = getPositionalArg(4)
-  const project = getArg('--project') || await resolveProjectSlug(null)
-  const promptVersionId = getArg('--version')
-
-  if (!promptName || !label || !promptVersionId) {
-    throw new Error('Usage: orizu prompts labels set <prompt-name> <label> --version <prompt-version-id> [--project <team/project>] [--json]')
-  }
-
-  const response = await authedFetch(`/api/cli/prompts/labels?project=${encodeURIComponent(project)}`, {
-    method: 'POST',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({
-      promptName,
-      label,
-      promptVersionId,
-    }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to set prompt label: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt label set')
-  if (hasJsonFlag()) {
-    printJson(data)
-    return
+  if (kind === 'prompt' && data.owner) {
+    printLine(
+      `Owner: ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)}) -> ` +
+      `${sanitizeTerminalText(data.owner.instructionSetSlug)} / ${sanitizeTerminalText(data.owner.componentKey)}`
+    )
   }
-
-  printLine(`Moved ${sanitizeTerminalText(label)} to ${sanitizeTerminalText(promptVersionId)}`)
 }
 
-async function setPromptArchivedState(archived: boolean) {
-  const promptRef = getPositionalArg(2)
-  const project = getArg('--project') || await resolveProjectSlug(null)
-  const command = archived ? 'archive' : 'restore'
-
-  if (!promptRef) {
-    throw new Error(`Usage: orizu prompts ${command} <prompt-id-or-name> --project <team/project> [--json]`)
-  }
-
-  const response = await authedFetch(`/api/cli/prompts/${encodeURIComponent(promptRef)}?project=${encodeURIComponent(project)}`, {
-    method: 'PATCH',
-    headers: { 'Content-Type': 'application/json' },
-    body: JSON.stringify({ archived }),
-  })
-
-  if (!response.ok) {
-    throw new Error(`Failed to ${command} prompt: ${await response.text()}`)
-  }
-
-  const data = await parseJsonResponse<{
-    prompt: {
-      id: string
-      name: string
-      status: string
-    }
-  }>(response, `Prompt ${command}`)
-  if (hasJsonFlag()) {
-    printJson(data)
-    return
-  }
-
-  printLine(`${archived ? 'Archived' : 'Restored'} prompt ${sanitizeTerminalText(data.prompt.name)} (${sanitizeTerminalText(data.prompt.id)})`)
+function refusePromptMutation(replacement: string): never {
+  process.exitCode = 1
+  throw new Error(`Use: orizu instructions ${replacement}`)
 }
 
 async function bindPromptScorer(role: 'headline' | 'tracked') {
@@ -1814,13 +1793,25 @@ async function bindPromptScorer(role: 'headline' | 'tracked') {
     throw new Error(`Failed to bind prompt scorer: ${await response.text()}`)
   }
 
-  const data = await parseJsonResponse<Record<string, unknown>>(response, 'Prompt scorer bind')
+  const data = await parseJsonResponse<{
+    promptScorer: Record<string, unknown>
+    owner?: {
+      instructionSetSlug: string
+      componentKey: string
+    }
+  }>(response, 'Prompt scorer bind')
   if (hasJsonFlag()) {
     printJson(data)
     return
   }
 
   printLine(`${role === 'headline' ? 'Set headline' : 'Added'} scorer ${sanitizeTerminalText(scorerVersionId)} for ${sanitizeTerminalText(promptId)}`)
+  if (data.owner) {
+    printLine(
+      `Owner: ${sanitizeTerminalText(promptId)} -> ` +
+      `${sanitizeTerminalText(data.owner.instructionSetSlug)} / ${sanitizeTerminalText(data.owner.componentKey)}`
+    )
+  }
 }
 
 function getPositionalArg(index: number): string | null {
@@ -2506,35 +2497,12 @@ async function updateOptimizationRunLifecycle(action: OptimizationLifecycleActio
 
 // ALI-1073 list moved to optimizations-list-cli.ts (line ratchet, ALI-976);
 // ALI-1175 labels its best scores as agent-reported evidence there.
-
-function removeFlagWithValue(args: string[], flag: string): string[] {
-  const filtered: string[] = []
-  for (let index = 0; index < args.length; index += 1) {
-    if (args[index] === flag) {
-      index += 1
-      continue
-    }
-    filtered.push(args[index])
-  }
-  return filtered
-}
-
-function bundledOrizuGepaPythonPath(): string | null {
-  const candidates = [
-    fileURLToPath(new URL('../vendor/orizu-gepa-python/src', import.meta.url)),
-    fileURLToPath(new URL('../../orizu-gepa-python/src', import.meta.url)),
-  ]
-
-  return candidates.find(candidate => existsSync(candidate)) ?? null
-}
-
 async function runGepaOptimization() {
   const project = getArg('--project') || await resolveProjectSlug(null)
   const baseUrl = getBaseUrl()
-  const python = getArg('--python') || process.env.PYTHON || 'python3'
-  const bundledPythonPath = bundledOrizuGepaPythonPath()
-  let forwardedArgs = removeFlagWithValue(cliArgs.slice(2), '--python')
-
+  const runGepa = getGepaPythonCommand(cliArgs.slice(2), process.env)
+  const python = runGepa.python
+  let forwardedArgs = runGepa.args
   // ALI-1159 (ADR-007): GEPA executes ad-hoc local runner dirs while
   // attributing records to registered runner version ids — verify the bytes
   // ARE those versions before the optimizer spawns. Scans the forwarded argv
@@ -2543,8 +2511,8 @@ async function runGepaOptimization() {
   // so a post-hash mutation of the original dirs cannot change what runs.
   const verified = await verifyGepaRunnerDirsFromArgs(forwardedArgs)
   forwardedArgs = verified.args
-
   let result
+  let selectedEngine = 'official'
   try {
     // Uniform resolution (ALI-1090): honors ORIZU_TOKEN / ORIZU_TOKEN_FILE before
     // credentials.json so hosted sandboxes can run optimizations. Read at spawn
@@ -2552,40 +2520,35 @@ async function runGepaOptimization() {
     // rotation crossing the hash + lookup round-trips cannot hand the child a
     // stale bearer.
     const token = resolveAuthTokenForBaseUrl(baseUrl)
-
     if (!forwardedArgs.includes('--project')) {
       forwardedArgs = ['--project', project, ...forwardedArgs]
     }
-
-    const pythonPathEntries = [
-      bundledPythonPath,
-      process.env.PYTHONPATH,
-    ].filter((entry): entry is string => Boolean(entry))
-
-    result = spawnSync(python, ['-m', 'orizu_gepa.cli', ...forwardedArgs], {
-      stdio: 'inherit',
-      env: {
-        ...process.env,
-        ORIZU_API_URL: baseUrl,
-        ORIZU_TOKEN: token,
-        ORIZU_PROJECT: project,
-        // Integrity handshake (ALI-1159): the Python entrypoint refuses
-        // runner dirs that are not in this wrapper-verified list.
-        ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
-        PYTHONPATH: pythonPathEntries.join(delimiter),
-        PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
-      },
+    const dispatch = dispatchGepaEngine(forwardedArgs, project, {
+      ...process.env,
+      ORIZU_API_URL: baseUrl,
+      ORIZU_TOKEN: token,
+      ORIZU_PROJECT: project,
+      ORIZU_VERIFIED_RUNNER_DIRS: JSON.stringify(verified.verifiedDirs),
+      PYTHONPATH: getGepaPythonPathEntries(process.env.PYTHONPATH).join(delimiter),
+      PYTHONUNBUFFERED: process.env.PYTHONUNBUFFERED || '1',
     })
+    const instructionSetName = dispatch.environment.ORIZU_INSTRUCTION_SET_NAME
+    const modelConfigIdentity = dispatch.environment.ORIZU_MODEL_CONFIG_IDENTITY
+    const instructionSetProfileVersionId = instructionSetName && modelConfigIdentity
+      ? await resolveGepaInstructionSetProfileVersion(instructionSetName, modelConfigIdentity, project) : undefined
+    if (instructionSetProfileVersionId) dispatch.environment.ORIZU_INSTRUCTION_SET_PROFILE_VERSION_ID = instructionSetProfileVersionId
+    selectedEngine = dispatch.engine
+    const launch = prepareSkilledProposerLaunch(python, dispatch.engine, dispatch.environment)
+    result = spawnSync(launch.python, ['-m', dispatch.module, ...dispatch.args], { stdio: 'inherit', env: launch.environment })
   } finally {
     verified.cleanup()
   }
-
   if (result.error) {
-    throw result.error
+    throw new Error(`${selectedEngine} GEPA engine failed: ${result.error.message}`, { cause: result.error })
   }
 
   if (result.status !== 0) {
-    throw new Error(`orizu-gepa failed with exit code ${result.status}`)
+    throw new Error(`${selectedEngine} GEPA engine failed with exit code ${result.status}`)
   }
 
   if (hasJsonFlag()) {
@@ -5785,7 +5748,7 @@ async function downloadAnnotations() {
   printLine(`Saved ${format.toUpperCase()} export to ${sanitizeTerminalText(filename)}`)
 }
 
-function readRunnerManifest(runnerDir: string): { command: string[]; supports_body_kind?: string[] } {
+export function readRunnerManifest(runnerDir: string): { command: string[]; supports_body_kind?: string[] } {
   const manifestPath = join(runnerDir, 'manifest.json')
   const raw = readSourceFile(manifestPath)
   const manifest = JSON.parse(raw) as {
@@ -5813,9 +5776,9 @@ function readRunnerManifest(runnerDir: string): { command: string[]; supports_bo
   }
 }
 
-const RUNNER_TIMEOUT_MS = 120_000
-const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
-const RUNNER_ENV_ALLOWLIST = new Set([
+export const RUNNER_TIMEOUT_MS = 120_000
+export const RUNNER_OUTPUT_MAX_BYTES = 2 * 1024 * 1024
+export const RUNNER_ENV_ALLOWLIST = new Set([
   'PATH',
   'SystemRoot',
   'WINDIR',
@@ -5833,7 +5796,7 @@ const RUNNER_ENV_ALLOWLIST = new Set([
   'GOOGLE_API_KEY',
 ])
 
-function runnerSubprocessEnv(inputPath: string, outputPath: string): NodeJS.ProcessEnv {
+export function runnerSubprocessEnv(inputPath: string, outputPath: string, instructionSetDir?: string): NodeJS.ProcessEnv {
   const env = {} as NodeJS.ProcessEnv
   for (const key of RUNNER_ENV_ALLOWLIST) {
     const value = process.env[key]
@@ -5843,6 +5806,8 @@ function runnerSubprocessEnv(inputPath: string, outputPath: string): NodeJS.Proc
   }
   env.ORIZU_RUNNER_INPUT_PATH = inputPath
   env.ORIZU_RUNNER_OUTPUT_PATH = outputPath
+  delete env.ORIZU_INSTRUCTION_SET_DIR
+  if (instructionSetDir) env.ORIZU_INSTRUCTION_SET_DIR = instructionSetDir
   return env
 }
 
@@ -5855,7 +5820,7 @@ function boundedRunnerOutput(value: string | Buffer | null | undefined): string
   return `${buffer.subarray(0, RUNNER_OUTPUT_MAX_BYTES).toString('utf8')}\n[truncated]`
 }
 
-async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runnerDir: string; cleanup: () => void }> {
+export async function materializeRunnerVersion(runnerVersionId: string): Promise<{ runnerDir: string; cleanup: () => void }> {
   const response = await authedFetch(`/api/cli/runner-versions/${encodeURIComponent(runnerVersionId)}/download`)
   if (!response.ok) {
     throw new Error(`Failed to download runner version: ${await response.text()}`)
@@ -5949,7 +5914,6 @@ async function runnersExec() {
       })()
     : await materializeRunnerVersion(resolvedRunnerVersionId)
   const runnerDir = materializedRunner.runnerDir
-
   try {
     assertSnapshotManifestConfined(runnerDir, runnerDirArg ? '--runner-dir' : '--runner-version')
     // Inside the try (codex round-6 P3): a bad manifest must not leak the dir.
@@ -5959,22 +5923,19 @@ async function runnersExec() {
         `Runner does not support prompt body kind '${context.prompt.bodyKind}'. Supported kinds: ${manifest.supports_body_kind.join(', ')}`
       )
     }
-
     const resultLines: string[] = []
     for (const row of context.rows) {
       const tempDir = mkdtempSync(join(tmpdir(), 'orizu-runner-'))
       const inputPath = join(tempDir, 'input.json')
       const outputPath = join(tempDir, 'output.json')
-
+      const instructionSetDir = context.instructionSet ? join(tempDir, 'instruction-set') : undefined
       try {
         const modelOutput = row.row.model_output ?? row.row.modelOutput ?? row.row.output ?? null
+        if (instructionSetDir && context.instructionSet) syncToDisk(instructionSetDir, runnerInstructionSetSyncSet(context.instructionSet))
         writeFileSync(inputPath, JSON.stringify({
           row: row.row,
-          prompt: {
-            body: context.prompt.body,
-            body_kind: context.prompt.bodyKind,
-            provider_settings: context.prompt.providerSettings,
-          },
+          prompt: runnerInputPrompt(context.prompt),
+          ...(context.instructionSet ? { instruction_set: runnerInputInstructionSet(context.instructionSet) } : {}),
           subject: scorerVersion
             ? {
                 type: 'scorer_row',
@@ -6002,7 +5963,7 @@ async function runnersExec() {
 
         const result = spawnSync(manifest.command[0], manifest.command.slice(1), {
           cwd: runnerDir,
-          env: runnerSubprocessEnv(inputPath, outputPath),
+          env: runnerSubprocessEnv(inputPath, outputPath, instructionSetDir),
           encoding: 'utf8',
           maxBuffer: RUNNER_OUTPUT_MAX_BYTES,
           timeout: RUNNER_TIMEOUT_MS,
@@ -6234,8 +6195,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   if (command === 'prompts' && subcommand === 'push') {
-    await pushPromptArtifact('prompt')
-    return
+    if (getArg('--session')) {
+      await pushPromptArtifact('prompt')
+      return
+    }
+    refusePromptMutation('push <manifest> --project <team/project>')
   }
 
   if (
@@ -6249,17 +6213,25 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
 
   if (command === 'prompts' && subcommand === 'archive') {
-    await setPromptArchivedState(true)
-    return
+    refusePromptMutation('archive <slug-or-exact-name> --project <team/project>')
   }
 
   if (command === 'prompts' && subcommand === 'restore') {
-    await setPromptArchivedState(false)
-    return
+    refusePromptMutation('restore <slug-or-exact-name> --project <team/project>')
   }
 
   if (command === 'prompts' && subcommand === 'labels' && cliArgs[2] === 'set') {
-    await setPromptLabel()
+    if (getPositionalArg(4) === 'production') {
+      refusePromptMutation('profiles promote <set> --project <team/project> --model-config <identity> --version <n>')
+    }
+    await setPromptLabel({
+      getArg,
+      getPositionalArg,
+      json: hasJsonFlag(),
+      printJson,
+      printLine,
+      resolveProjectSlug,
+    })
     return
   }
 
@@ -6310,29 +6282,17 @@ export async function main(rawArgs = process.argv.slice(2)) {
     return
   }
 
-  if (command === 'scorers' && subcommand === 'list') {
-    await listScorers()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'register') {
-    await registerScorer()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'detail') {
-    await showScorerDetail()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'labels' && cliArgs[2] === 'set') {
-    await setScorerLabel()
-    return
-  }
-
-  if (command === 'scorers' && subcommand === 'exec') {
-    await execScorer()
-    return
+  if (command === 'scorers') {
+    const scorersExit = await scorersCommand(cliArgs, {
+      list: listScorers, register: registerScorer, detail: showScorerDetail,
+      labelsSet: setScorerLabel, exec: execScorer,
+      verifyParity: args => verifyScorerParityCommand(args, {
+        json: hasJsonFlag(), print: printLine, printErr: printError,
+        materializeRunnerVersion, readRunnerManifest, runnerSubprocessEnv,
+        timeoutMs: RUNNER_TIMEOUT_MS, maxOutputBytes: RUNNER_OUTPUT_MAX_BYTES,
+      }),
+    })
+    if (scorersExit !== null) { process.exitCode = scorersExit; return }
   }
 
   if ((command === 'runners' || command === 'optimizers') && subcommand === 'push') {
@@ -6393,7 +6353,12 @@ export async function main(rawArgs = process.argv.slice(2)) {
     await listOptimizationRunsCommand(cliArgs.slice(2), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
     return
   }
-
+  if (command === 'optimizations' && subcommand === 'promote') {
+    await promoteOptimizationCommand(cliArgs.slice(2), {
+      json: hasJsonFlag(), print: printLine, resolveProjectSlug, fetcher: authedFetch,
+    })
+    return
+  }
   if (
     command === 'optimizations' &&
     (
@@ -6557,11 +6522,11 @@ export async function main(rawArgs = process.argv.slice(2)) {
   }
   if (command === 'git-credential') { process.exitCode = await runGitCredentialInvocation(cliArgs.slice(1), { stdin: readFileSync(0, 'utf8'), cwd: process.cwd(), print: printLine, printErr: printError }); return }
   if (command === 'github' && subcommand === 'link') { const noInput = hasArg('--no-input') || hasArg('--non-interactive') || !isInteractiveTerminal(); const team = getOptionalArgValue('--team') || (await resolveSetupTeam(null, noInput, false)).slug; await runGithubLink(team, { print: printLine, fetcher: authedFetch, openUrl: openInBrowser, confirm: (org) => askYesNo(`Connect this team to GitHub org '${org}'?`, true) }); return }
-  if (command === 'connectors' || command === 'manifests') {
-    const moduleCommand = command === 'connectors' ? connectorsCommand : manifestsCommand
-    process.exitCode = await moduleCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
+  if (command === 'connectors' || command === 'manifests' || command === 'model-configs') {
+    process.exitCode = await (command === 'connectors' ? connectorsCommand : command === 'manifests' ? manifestsCommand : modelConfigsCommand)(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug })
     return
   }
+  if (command === 'instructions' || command === 'instruction-sets') { process.exitCode = await instructionSetsCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, resolveProjectSlug }); return }
   if (command === 'team' && (subcommand === 'kill-agents' || subcommand === 'release-agents')) {
     process.exitCode = await killSwitchCommand(cliArgs.slice(1), { json: hasJsonFlag(), print: printLine, printErr: printError })
     return

package/src/instruction-set-gepa-launch.ts

@@ -0,0 +1,28 @@
+import { authedFetch } from './http.js'
+import { parseJsonResponse } from './json-response.js'
+
+interface InstructionSetResolution {
+  instructionSet?: {
+    default?: { profileVersionId?: string } | null
+    profiles?: Array<{
+      modelConfigIdentity?: string | null
+      production?: { profileVersionId?: string } | null
+    }>
+  }
+}
+
+/** Resolve the same production-or-default tuple served for a model identity. */
+export async function resolveGepaInstructionSetProfileVersion(
+  instructionSetName: string,
+  modelConfigIdentity: string,
+  project: string,
+): Promise<string> {
+  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<InstructionSetResolution>(response, 'Instruction set resolution')
+  const instructionSet = payload.instructionSet
+  const profile = instructionSet?.profiles?.find(candidate => candidate.modelConfigIdentity === modelConfigIdentity)
+  const profileVersionId = profile?.production?.profileVersionId || instructionSet?.default?.profileVersionId
+  if (!profileVersionId) throw new Error('instruction_set_profile_version_unresolvable')
+  return profileVersionId
+}

package/src/instruction-set-loader.ts

@@ -0,0 +1,37 @@
+import { existsSync, realpathSync, readFileSync, statSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+
+export class InstructionSetLoaderError extends Error {
+  constructor(readonly code: string) { super(code); this.name = 'InstructionSetLoaderError' }
+}
+
+interface Material { files: Record<string, string>; pinnedComponents?: Record<string, unknown> }
+interface Manifest { manifestVersion: number; name: string; shape: string[]; default: Material; profiles: Array<{ modelConfigIdentity: string; production: Material | null }>; filteredTo?: string[] }
+
+function inside(root: string, candidate: string) { return candidate === root || candidate.startsWith(`${root}${sep}`) }
+
+export function loadInstructionSet(directory: string, name: string, modelConfigIdentity: string): Record<string, string> {
+  const unresolvedRoot = resolve(directory, name)
+  if (!existsSync(unresolvedRoot) || !statSync(unresolvedRoot).isDirectory()) throw new InstructionSetLoaderError('instruction_set_not_synced')
+  const setRoot = realpathSync(unresolvedRoot)
+  const manifestPath = resolve(setRoot, 'manifest.json')
+  if (!existsSync(manifestPath)) throw new InstructionSetLoaderError('instruction_set_manifest_missing')
+  let manifest: Manifest
+  try { manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Manifest } catch { throw new InstructionSetLoaderError('instruction_set_manifest_missing') }
+  if (manifest.manifestVersion !== 1) throw new InstructionSetLoaderError('instruction_set_manifest_version_unsupported')
+  if (manifest.filteredTo && !manifest.filteredTo.includes(modelConfigIdentity)) throw new InstructionSetLoaderError('instruction_set_profile_not_synced')
+  const selected = manifest.profiles.find(profile => profile.modelConfigIdentity === modelConfigIdentity)?.production || manifest.default
+  const result: Record<string, string> = {}
+  for (const key of manifest.shape) {
+    if (selected.pinnedComponents?.[key]) throw new InstructionSetLoaderError('instruction_set_component_unavailable')
+    const relativePath = selected.files?.[key]
+    if (!relativePath) throw new InstructionSetLoaderError('instruction_set_profile_key_missing')
+    const unresolvedPath = resolve(setRoot, relativePath)
+    if (!inside(setRoot, unresolvedPath)) throw new InstructionSetLoaderError('instruction_set_path_unsafe')
+    let path: string
+    try { path = realpathSync(unresolvedPath) } catch { throw new InstructionSetLoaderError('instruction_set_component_unreadable') }
+    if (!inside(setRoot, path)) throw new InstructionSetLoaderError('instruction_set_path_unsafe')
+    try { result[key] = readFileSync(path, 'utf8') } catch { throw new InstructionSetLoaderError('instruction_set_component_unreadable') }
+  }
+  return result
+}