@workbench-ai/workbench 0.0.48 → 0.0.50

package/dist/index.js

@@ -5,7 +5,7 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { Writable } from "node:stream";
-import { createSubjectFilePreview, createBaselineSubjectJob as createRuntimeBaselineSubjectJob, evaluationScorecardId, executeWorkbenchExecutionJob, engineResolveBindingForSpec, filterSubjectSourceFiles, workbenchExecutionPurpose, createWorkbenchAdapterAuthBundle, createSubjectEvaluationTraceInputFiles, createSubjectRevisionTraceInputFiles, DOCKER_SANDBOX_BACKEND, localWorkbenchAdapterAuthStore, materializeWorkbenchRunResult, normalizeSurfaceFiles, planWorkbenchExecutionJobsForPurpose, runWorkbenchExecutionDag, resolveEngineCaseExecutionConfig, resolveWorkbenchResolvedSourceYaml, summarizeSubjectFiles, validateWorkbenchRunEnvelope, parseWorkbenchAdapterAuthTarget, } from "@workbench-ai/workbench-core";
+import { createCandidateFilePreview, createBaselineCandidateJob as createRuntimeBaselineCandidateJob, evaluationScorecardId, evaluationMeanMetrics, executeWorkbenchExecutionJob, engineResolveBindingForSpec, filterCandidateSourceFiles, workbenchExecutionPurpose, workbenchRunExecutionFingerprint, createWorkbenchAdapterAuthBundle, createOptimizerTraceInputFiles, DOCKER_SANDBOX_BACKEND, localWorkbenchAdapterAuthStore, materializeWorkbenchRunResult, normalizeSurfaceFiles, planWorkbenchExecutionJobsForPurpose, runWorkbenchExecutionDag, resolveEngineCaseExecutionConfig, resolveWorkbenchResolvedSourceYaml, summarizeCandidateFiles, validateWorkbenchRunEnvelope, parseWorkbenchAdapterAuthTarget, } from "@workbench-ai/workbench-core";
 import { assertWorkbenchAdapterOperationResultOk, collectWorkbenchAdapterAuthRequirements, WORKBENCH_ADAPTER_RESULT_FILE, WORKBENCH_ADAPTER_RESULT_PROTOCOL, normalizeWorkbenchAdapterOperationRequest, readWorkbenchAdapterOperationResult, workbenchAdapterOperationCommand, workbenchAdapterOperationResultPath, withDefaultWorkbenchAdapterAuthProfiles as applyDefaultWorkbenchAdapterAuthProfiles, } from "@workbench-ai/workbench-protocol";
 import { builtinLocalTraceAdapter, builtinLocalTraceAdapters, sortLocalTraceRefs, } from "@workbench-ai/workbench-built-in-adapters/local-traces";
 import { commandUsage, HOSTED_WATCH_LIFECYCLE_NOTE, LOCAL_DEV_OPEN_LIFECYCLE_NOTE, rootUsage, } from "./command-model.js";
@@ -13,10 +13,10 @@ import { startLocalWorkbenchDevServer } from "./dev-open-server.js";
 import { createWorkbenchInitScaffold, } from "./init-scaffold.js";
 import { defaultAdapterManifests, composeRuntimeDockerfileWithAdapters, resolveDefaultWorkbenchAdapter, resolveProjectAdapterSource, resolveWorkbenchAdaptersForProject, WORKBENCH_ADAPTER_MANIFEST_FILE, } from "./adapter-project.js";
 import { createAdapterCommandEnv } from "./adapter-command-env.js";
-import { appendLocalRun, loadLocalArchive, loadLocalArchiveIndex, materializeSubjectRoot, readLocalSubject, readLocalSubjectFiles, saveLocalArchive, saveLocalJobs, setLocalActive, upsertLocalSubject, upsertLocalEvaluation, } from "./local-archive.js";
+import { loadLocalArchive, loadLocalArchiveIndex, materializeCandidateRoot, readLocalCandidate, readLocalCandidateFiles, readLocalJobs, saveLocalArchive, saveLocalJobs, setLocalActive, upsertLocalRun, upsertLocalCandidate, upsertLocalEvaluation, } from "./local-archive.js";
 import { WorkspaceSnapshotError, } from "./workspace-snapshot.js";
 import { readLocalProjectSource, WORKBENCH_BENCHMARK_FILE, } from "./project-source.js";
-import { localBenchmarkFingerprint, localSubjectFingerprint, } from "./benchmark-fingerprint.js";
+import { localBenchmarkFingerprint, localCandidateFingerprint, } from "./benchmark-fingerprint.js";
 const require = createRequire(import.meta.url);
 function getCliVersion() {
     const manifest = require("../package.json");
@@ -87,7 +87,10 @@ export async function runCli(argv, io = {
             return await runRemoteCommand(argv.slice(1), io);
         }
         if (argv[0] === "eval") {
-            return await localEvaluateSubject(argv.slice(1), io, runtimeOptions);
+            return await localEvaluateCandidate(argv.slice(1), io, runtimeOptions);
+        }
+        if (argv[0] === "retry") {
+            return await localRetry(argv.slice(1), io, runtimeOptions);
         }
         if (argv[0] === "improve") {
             return await localRun(argv.slice(1), io, runtimeOptions);
@@ -117,14 +120,14 @@ export async function runCli(argv, io = {
                 return await localRunList(rest, io);
             case "runs show":
                 return await localRunShow(rest, io);
-            case "subjects list":
-                return await localSubjectList(rest, io);
-            case "subjects show":
-                return await localSubjectShow(rest, io);
-            case "subjects files":
-                return await localSubjectFiles(rest, io);
-            case "subjects preview":
-                return await localSubjectPreview(rest, io);
+            case "candidates list":
+                return await localCandidateList(rest, io);
+            case "candidates show":
+                return await localCandidateShow(rest, io);
+            case "candidates files":
+                return await localCandidateFiles(rest, io);
+            case "candidates preview":
+                return await localCandidatePreview(rest, io);
             default:
                 break;
         }
@@ -163,7 +166,7 @@ function commandPathForHelp(argv) {
         ["list", "show"].includes(positionals[1] ?? "")) {
         return positionals.slice(0, 2).join(" ");
     }
-    if (positionals[0] === "subjects" &&
+    if (positionals[0] === "candidates" &&
         ["list", "show", "files", "preview"].includes(positionals[1] ?? "")) {
         return positionals.slice(0, 2).join(" ");
     }
@@ -175,6 +178,8 @@ async function runCloudCommand(argv, io) {
     switch (command) {
         case "eval":
             return await startHostedWorkflow("eval", rest, io);
+        case "retry":
+            return await retryHostedWorkflow(rest, io);
         case "improve":
             return await startHostedWorkflow("improve", rest, io);
         case "open":
@@ -209,20 +214,20 @@ async function runCloudCommand(argv, io) {
             return await runShow(subRest, io);
         case "runs cancel":
             return await runCancel(subRest, io);
-        case "subjects list":
-            return await subjectList(subRest, io);
-        case "subjects show":
-            return await subjectShow(subRest, io);
-        case "subjects files":
-            return await subjectFiles(subRest, io);
-        case "subjects preview":
-            return await subjectPreview(subRest, io);
-        case "subjects pull":
-            return await subjectExport(subRest, io);
-        case "subjects publish":
-            return await subjectVisibility(subRest, io, "public");
-        case "subjects unpublish":
-            return await subjectVisibility(subRest, io, "private");
+        case "candidates list":
+            return await candidateList(subRest, io);
+        case "candidates show":
+            return await candidateShow(subRest, io);
+        case "candidates files":
+            return await candidateFiles(subRest, io);
+        case "candidates preview":
+            return await candidatePreview(subRest, io);
+        case "candidates pull":
+            return await candidateExport(subRest, io);
+        case "candidates publish":
+            return await candidateVisibility(subRest, io, "public");
+        case "candidates unpublish":
+            return await candidateVisibility(subRest, io, "private");
         default:
             throw new UsageError(`Unknown command: cloud ${argv.join(" ")}`);
     }
@@ -313,7 +318,7 @@ async function localInit(argv, io) {
         specPath,
         kind: scaffold.kind,
         name: scaffold.name,
-        subjectRoot: scaffold.subjectRoot,
+        candidateRoot: scaffold.candidateRoot,
     }, parsed, io, () => `Initialized ${scaffold.kind} Workbench source directory at ${workspace}`);
     return 0;
 }
@@ -358,20 +363,20 @@ function buildWorkbenchCheckPlan(source) {
             files: sourceFileCount(source),
             yaml: [
                 path.relative(source.dir, source.benchmarkPath) || "benchmark.yaml",
-                path.relative(source.dir, source.subjectSpecPath) || "subject YAML",
-                ...(source.optimizerSource !== undefined
-                    ? [path.relative(source.dir, source.optimizerPath ?? "") || "optimizer YAML"]
-                    : []),
+                path.relative(source.dir, source.candidateSpecPath) || "candidate YAML",
             ],
             dockerfile: source.dockerfilePath,
         },
-        subject: {
-            filesPath: source.spec.subject.files.path,
-            files: source.subjectFiles.length,
+        candidate: {
+            name: source.spec.candidate.name,
+            selectedRunId: source.spec.candidate.selectedRunId,
+            runCount: Object.keys(source.spec.candidate.runs).length,
+            filesPath: source.spec.candidate.files.path,
+            files: source.candidateFiles.length,
         },
-        optimizer: source.spec.optimizer
+        improve: source.spec.candidate.improve
             ? {
-                edits: [...source.spec.optimizer.edits],
+                edits: [...source.spec.candidate.improve.edits],
             }
             : null,
         engine: {
@@ -394,8 +399,8 @@ function buildWorkbenchCheckPlan(source) {
     };
 }
 function formatWorkbenchCheckPlan(plan, warningSuffix) {
-    const edits = plan.optimizer?.edits.length
-        ? plan.optimizer.edits.join(", ")
+    const edits = plan.improve?.edits.length
+        ? plan.improve.edits.join(", ")
         : "-";
     const network = plan.environment.network.egress;
     const resources = plan.environment.resources;
@@ -404,11 +409,12 @@ function formatWorkbenchCheckPlan(plan, warningSuffix) {
         `Benchmark: ${plan.benchmarkName}`,
         `Description: ${plan.benchmarkDescription}`,
         `Source: ${plan.source.files} file(s) (${plan.source.yaml.join(", ")}, ${plan.source.dockerfile})`,
-        `Subject files: ${plan.subject.filesPath} (${plan.subject.files} file(s))`,
-        `Optimizer edits: ${edits}`,
+        `Candidate: ${plan.candidate.name} (${plan.candidate.runCount} run(s), selected ${plan.candidate.selectedRunId})`,
+        `Candidate files: ${plan.candidate.filesPath} (${plan.candidate.files} file(s))`,
+        `Improve edits: ${edits}`,
         `Engine cases: ${plan.engine.cases} case(s) from ${formatAdapterSummary(plan.engine.resolver)} at ${plan.engine.path} (${plan.engine.files} file(s))`,
         `Environment: ${plan.environment.dockerfile}, network ${network}, ${resources.cpu} CPU, ${resources.memoryGb}GB RAM, ${resources.timeoutMinutes}m timeout`,
-        `Execution: improve ${plan.adapters.improve ? formatAdapterSummary(plan.adapters.improve) : "not configured"}, subject ${formatAdapterSummary(plan.adapters.run)}, engine ${formatAdapterSummary(plan.adapters.engine)}`,
+        `Execution: improve ${plan.adapters.improve ? formatAdapterSummary(plan.adapters.improve) : "not configured"}, candidate run ${formatAdapterSummary(plan.adapters.run)}, engine ${formatAdapterSummary(plan.adapters.engine)}`,
         ...adapterSourceLines(plan.adapters.sources),
     ].join("\n");
 }
@@ -493,18 +499,206 @@ function splitWorkspaceError(error) {
     const message = error instanceof Error ? error.message : String(error);
     return message.split(/\n+/u).map((entry) => entry.trim()).filter(Boolean);
 }
+async function localRetry(argv, io, runtimeOptions) {
+    const parsed = parseArgs(argv);
+    rejectUnknownFlags(parsed, new Set(["dir", "json"]));
+    rejectUnexpectedPositionals(parsed, "workbench retry", 1);
+    const targetId = parsed.positionals[0];
+    if (!targetId) {
+        throw new UsageError("Missing required TARGET_ID.");
+    }
+    const workspace = resolveDir(parsed);
+    const target = await resolveLocalRetryTarget(workspace, targetId);
+    const captured = createCapturingIo(io);
+    const code = target.workflow === "eval"
+        ? await localEvaluateCandidate([
+            "--dir",
+            workspace,
+            "--candidate",
+            target.candidateId,
+            "--runs",
+            target.candidateRunId,
+            "--samples",
+            String(target.samples),
+            "--json",
+        ], captured.io, runtimeOptions)
+        : await localRun([
+            "--dir",
+            workspace,
+            "--from",
+            target.candidateId,
+            "--runs",
+            target.candidateRunId,
+            "--budget",
+            String(target.budget ?? 1),
+            "--samples",
+            String(target.samples),
+            "--json",
+        ], captured.io, runtimeOptions);
+    const commandOutput = parseCapturedJson(captured.stdoutText());
+    await preserveLocalActiveCandidate(workspace, target.preserveActiveId);
+    const outputRecord = readRecord(commandOutput) ?? {};
+    const result = {
+        ok: code === 0 && outputRecord.ok !== false,
+        retried: {
+            id: target.sourceId,
+            kind: target.sourceKind,
+            workflow: target.workflow,
+        },
+    };
+    assignRetryResultString(result, "runId", outputRecord.runId);
+    assignRetryResultString(result, "evaluationId", outputRecord.evaluationId);
+    assignRetryResultString(result, "candidateId", outputRecord.candidateId);
+    assignRetryResultString(result, "activeCandidateId", outputRecord.activeCandidateId);
+    const localView = localRetryViewHint(outputRecord.localView);
+    if (localView) {
+        result.localView = localView;
+    }
+    const failedJobCount = numberValue(outputRecord.failedJobCount);
+    if (failedJobCount !== null) {
+        result.failedJobCount = failedJobCount;
+    }
+    const error = stringValue(outputRecord.error);
+    if (error) {
+        result.error = error;
+    }
+    writeOutput(result, parsed, io, formatRetryCommandResult);
+    return code;
+}
+async function resolveLocalRetryTarget(workspace, targetId) {
+    const snapshot = await loadLocalArchive(workspace);
+    const evaluation = snapshot.evaluations.find((entry) => entry.id === targetId);
+    if (evaluation) {
+        const run = snapshot.runs.find((entry) => entry.id === evaluation.runId) ?? null;
+        return localEvaluationRetryTarget(snapshot, evaluation, run, "evaluation", targetId);
+    }
+    const run = snapshot.runs.find((entry) => entry.id === targetId);
+    if (!run) {
+        throw new UsageError(`Run or evaluation not found: ${targetId}`);
+    }
+    if (run.status !== "finished") {
+        throw new UsageError(`Run ${run.id} is ${run.status}; wait for it to finish before retrying.`);
+    }
+    if (!runSummaryFailed(run)) {
+        throw new UsageError(`Run ${run.id} did not fail; use workbench ${run.workflow} to intentionally run it again.`);
+    }
+    if (run.workflow === "eval") {
+        const evaluations = snapshot.evaluations.filter((entry) => entry.runId === run.id);
+        if (evaluations.length !== 1) {
+            throw new UsageError(evaluations.length === 0
+                ? `Run ${run.id} has no evaluation record to retry.`
+                : `Run ${run.id} has multiple evaluations; retry a specific evaluation id instead.`);
+        }
+        return localEvaluationRetryTarget(snapshot, evaluations[0], run, "run", targetId);
+    }
+    const candidateRunId = run.candidateRunId;
+    if (!run.candidateId || !candidateRunId) {
+        throw new UsageError(`Run ${run.id} is missing retry metadata; use workbench improve --from with an explicit candidate id.`);
+    }
+    return {
+        sourceId: targetId,
+        sourceKind: "run",
+        workflow: "improve",
+        candidateId: run.candidateId,
+        candidateRunId,
+        samples: run.samples,
+        budget: run.budget,
+        preserveActiveId: snapshot.activeId,
+    };
+}
+function localEvaluationRetryTarget(snapshot, evaluation, run, sourceKind, sourceId) {
+    if (!evaluationScorecardFailed(evaluation, run)) {
+        throw new UsageError(`Evaluation ${evaluation.id} did not fail; use workbench eval to intentionally run it again.`);
+    }
+    if (!snapshot.candidates.some((entry) => entry.id === evaluation.candidateId)) {
+        throw new UsageError(`Candidate not found for evaluation ${evaluation.id}: ${evaluation.candidateId}`);
+    }
+    const candidateRunId = evaluation.candidateRunId ?? run?.candidateRunId;
+    if (!candidateRunId) {
+        throw new UsageError(`Evaluation ${evaluation.id} is missing its candidate run configuration.`);
+    }
+    return {
+        sourceId,
+        sourceKind,
+        workflow: "eval",
+        candidateId: evaluation.candidateId,
+        candidateRunId,
+        samples: evaluation.sampleCount || run?.samples || 1,
+        preserveActiveId: snapshot.activeId,
+    };
+}
+async function preserveLocalActiveCandidate(workspace, activeId) {
+    let snapshot = await loadLocalArchive(workspace);
+    if (activeId && !snapshot.candidates.some((candidate) => candidate.id === activeId)) {
+        return;
+    }
+    if (snapshot.activeId === activeId) {
+        return;
+    }
+    snapshot = setLocalActive(snapshot, activeId);
+    await saveLocalArchive(workspace, snapshot);
+}
+function evaluationScorecardFailed(evaluation, run) {
+    return evaluation.errorSampleCount > 0 ||
+        evaluation.status !== "completed" ||
+        runSummaryFailed(run);
+}
+function runSummaryFailed(run) {
+    return run?.outcome === "error" || run?.outcome === "cancelled";
+}
+function createCapturingIo(io) {
+    const chunks = [];
+    const stdout = new class extends Writable {
+        _write(chunk, _encoding, callback) {
+            chunks.push(Buffer.isBuffer(chunk) ? chunk.toString("utf8") : String(chunk));
+            callback();
+        }
+    }();
+    return {
+        io: {
+            stdin: io.stdin,
+            stdout,
+            stderr: io.stderr,
+        },
+        stdoutText: () => chunks.join(""),
+    };
+}
+function parseCapturedJson(value) {
+    const trimmed = value.trim();
+    if (!trimmed) {
+        return {};
+    }
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        return { output: trimmed };
+    }
+}
+function localRetryViewHint(value) {
+    const record = readRecord(value);
+    const command = stringValue(record?.command);
+    const note = stringValue(record?.note);
+    return command && note ? { command, note } : undefined;
+}
+function assignRetryResultString(result, key, value) {
+    const normalized = stringValue(value);
+    if (normalized) {
+        result[key] = normalized;
+    }
+}
 async function localRun(argv, io, runtimeOptions) {
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "optimizer", "from", "budget", "samples", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "runs", "from", "budget", "samples", "rerun", "json"]));
     const budget = parsePositiveInt(parsed.flags.budget, 1, "budget");
     const samples = parsePositiveInt(parsed.flags.samples, 1, "samples");
     const sourceArg = resolveSourceDir(parsed);
     const projectSource = await readLocalProjectSource(sourceArg, {
-        optimizerPath: asOptionalString(parsed.flags.optimizer),
+        runId: singleRequestedRunId(asOptionalString(parsed.flags.runs), "workbench improve"),
     });
     const workspace = projectSource.dir;
-    if (!projectSource.spec.optimizer) {
-        throw new UsageError("Optimizer YAML is required for workbench improve.");
+    if (!projectSource.spec.improve || !projectSource.spec.candidate.improve) {
+        throw new UsageError("Candidate improve configuration is required for workbench improve.");
     }
     const executionProject = await resolveLocalProjectForExecution(workspace, projectSource.specSource);
     const { spec, adapterManifests } = executionProject;
@@ -522,10 +716,8 @@ async function localRun(argv, io, runtimeOptions) {
     });
     const environmentRefs = await ensureLocalDockerfileEnvironments(workspace, spec, engineCases);
     const benchmarkFingerprint = await readLocalBenchmarkFingerprint(workspace);
-    const runId = `run_local_${Date.now().toString(36)}`;
-    const startedAt = new Date().toISOString();
-    let snapshot = await loadLocalArchive(workspace);
-    const baseSubject = await ensureLocalImproveBaseSubject({
+    const executionFingerprint = localRunExecutionFingerprint(projectSource);
+    const baseCandidate = await ensureLocalImproveBaseCandidate({
         parsed,
         sourceArg,
         workspace,
@@ -534,9 +726,47 @@ async function localRun(argv, io, runtimeOptions) {
         io,
         runtimeOptions,
     });
-    let currentBaseId = baseSubject.id;
+    let snapshot = await loadLocalArchive(workspace);
+    if (parsed.flags.rerun !== true) {
+        const reusableRun = findReusableLocalImproveRun(snapshot.runs, {
+            benchmarkFingerprint,
+            candidateId: baseCandidate.id,
+            candidateRunId: projectSource.spec.candidate.selectedRunId,
+            executionFingerprint,
+            budget,
+            samples,
+        });
+        if (reusableRun) {
+            const evaluation = snapshot.evaluations.find((entry) => entry.runId === reusableRun.id) ?? null;
+            const outputCandidateId = reusableRun.outputCandidateId ?? reusableRun.candidateId ?? baseCandidate.id;
+            const outputCandidate = readLocalCandidate(snapshot, outputCandidateId);
+            const activeCandidate = snapshot.activeId
+                ? readLocalCandidate(snapshot, snapshot.activeId)
+                : null;
+            const result = {
+                ok: true,
+                reused: true,
+                runId: reusableRun.id,
+                evaluationId: evaluation?.id ?? null,
+                outputCandidateId,
+                outputCandidate,
+                activeCandidateId: snapshot.activeId,
+                activeCandidate,
+                completedJobCount: 0,
+                failedJobCount: 0,
+                localView: localDevViewHint(workspace, reusableRun.id),
+            };
+            writeOutput(result, parsed, io, () => `Reused improve run ${reusableRun.id}. Use --rerun to intentionally run it again.`);
+            return 0;
+        }
+    }
+    const runId = `run_local_${Date.now().toString(36)}`;
+    const startedAt = new Date().toISOString();
+    let currentBaseId = baseCandidate.id;
+    let outputCandidateId = null;
     let completedJobCount = 0;
     let failedJobCount = 0;
+    let attemptsExecuted = 0;
     const failedJobs = [];
     const events = [
         createLocalEvent("run_started", startedAt, {
@@ -544,232 +774,313 @@ async function localRun(argv, io, runtimeOptions) {
             detail: { budget, samples, strategy: "greedy" },
         }),
     ];
-    const devCapacity = await localDevelopmentCapacity(workspace);
-    const runTraceJobs = [];
-    const attempts = budget;
-    for (let attemptIndex = 0; attemptIndex < attempts; attemptIndex += 1) {
-        snapshot = await loadLocalArchive(workspace);
-        const activeSubject = readLocalSubject(snapshot, currentBaseId);
-        const baseFiles = filterSubjectSourceFiles(readLocalSubjectFiles(snapshot, activeSubject.id));
-        if (baseFiles.length === 0) {
-            throw new UsageError("Subject snapshot must include at least one file.");
-        }
-        const subjectRevisionTraceFiles = [
-            ...createSubjectEvaluationTraceInputFiles({ subject: activeSubject }),
-            ...createSubjectRevisionTraceInputFiles({
-                runId,
-                jobs: runTraceJobs,
-                events,
-            }),
-        ];
-        const subjectId = `subject_${runId.replace(/^run_/u, "")}_${String(attemptIndex + 1).padStart(3, "0")}`;
-        const plannedSubjectRevision = planWorkbenchExecutionJobsForPurpose({
-            ownerUserId: "local",
-            projectId: "local",
-            runId,
-            subjectId,
-            attemptIndex,
-            samples,
-            caseIds,
-            engineCases,
-            spec,
-            workflow: "improve",
-            purpose: "improve",
-            now: new Date().toISOString(),
-            baseFiles,
-            traceFiles: subjectRevisionTraceFiles,
-            ...(environmentRefs.defaultRef ? { environmentRef: environmentRefs.defaultRef } : {}),
-            baseId: activeSubject.id,
-        })[0];
-        const subjectRevisionJobs = await executeLocalDevelopmentDag({
-            jobs: [plannedSubjectRevision],
-            spec,
-            adapterManifests,
-            adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
-            baseFiles,
-            engineResolveFiles,
-            engineCases,
-            traceFiles: subjectRevisionTraceFiles,
-            capacity: devCapacity,
+    const runningRun = {
+        id: runId,
+        workflow: "improve",
+        benchmarkFingerprint,
+        status: "running",
+        candidateId: baseCandidate.id,
+        candidateRunId: projectSource.spec.candidate.selectedRunId,
+        candidateRunName: projectSource.spec.candidate.selectedRunName,
+        startedAt,
+        improver: formatSpecImprover(spec),
+        engineRun: spec.engineRun.use,
+        strategy: "greedy",
+        budget,
+        repairBudget: 0,
+        attemptsRequested: budget,
+        attemptsExecuted: 0,
+        samples,
+        executionFingerprint,
+        activeCandidateId: snapshot.activeId,
+        outputCandidateId: null,
+    };
+    snapshot = upsertLocalRun(snapshot, runningRun, events);
+    await saveLocalArchive(workspace, snapshot);
+    try {
+        const devCapacity = await localDevelopmentCapacity(workspace);
+        const baselineTraceJobs = selectLocalOptimizerBaselineTraceJobs(snapshot, await readLocalJobs(workspace), {
+            benchmarkFingerprint,
+            candidateId: baseCandidate.id,
+            candidateRunId: projectSource.spec.candidate.selectedRunId,
+            executionFingerprint,
         });
-        const subjectRevision = subjectRevisionJobs[0];
-        const completedJobs = [subjectRevision];
-        if (subjectRevision.status === "succeeded") {
-            const subjectRevisionFiles = completedJobOutputFiles(subjectRevision).length > 0
-                ? normalizeSurfaceFiles(completedJobOutputFiles(subjectRevision).filter((file) => !file.path.startsWith(".workbench/")))
-                : baseFiles;
-            const attemptJobs = planWorkbenchExecutionJobsForPurpose({
+        const runTraceJobs = [];
+        const attempts = budget;
+        for (let attemptIndex = 0; attemptIndex < attempts; attemptIndex += 1) {
+            snapshot = await loadLocalArchive(workspace);
+            const activeCandidate = readLocalCandidate(snapshot, currentBaseId);
+            const baseFiles = filterCandidateSourceFiles(readLocalCandidateFiles(snapshot, activeCandidate.id));
+            if (baseFiles.length === 0) {
+                throw new UsageError("Candidate snapshot must include at least one file.");
+            }
+            const candidateRevisionTraceFiles = createOptimizerTraceInputFiles({
+                jobs: [...baselineTraceJobs, ...runTraceJobs],
+            });
+            const candidateId = `candidate_${runId.replace(/^run_/u, "")}_${String(attemptIndex + 1).padStart(3, "0")}`;
+            const plannedCandidateRevision = planWorkbenchExecutionJobsForPurpose({
                 ownerUserId: "local",
                 projectId: "local",
                 runId,
-                subjectId,
+                candidateId,
                 attemptIndex,
                 samples,
-                now: new Date().toISOString(),
                 caseIds,
                 engineCases,
                 spec,
-                environmentRefsByCase: environmentRefs.byCase,
                 workflow: "improve",
-                purpose: "attempt",
-            });
-            const dagJobs = await executeLocalDevelopmentDag({
-                jobs: [subjectRevision, ...attemptJobs],
+                purpose: "improve",
+                now: new Date().toISOString(),
+                baseFiles,
+                traceFiles: candidateRevisionTraceFiles,
+                ...(environmentRefs.defaultRef ? { environmentRef: environmentRefs.defaultRef } : {}),
+                baseId: activeCandidate.id,
+            })[0];
+            const candidateRevisionJobs = await executeLocalDevelopmentDag({
+                jobs: [plannedCandidateRevision],
                 spec,
                 adapterManifests,
                 adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
-                baseFiles: subjectRevisionFiles,
+                baseFiles,
                 engineResolveFiles,
                 engineCases,
+                traceFiles: candidateRevisionTraceFiles,
                 capacity: devCapacity,
             });
-            completedJobs.splice(0, completedJobs.length, ...dagJobs);
-        }
-        runTraceJobs.push(...completedJobs);
-        const materialized = materializeWorkbenchRunResult({
-            runId,
-            benchmarkFingerprint,
-            sourceYaml: projectSource.specSource,
-            benchmarkSourceFiles: authoredBenchmarkSourceFiles(projectSource),
-            startedAt,
-            spec,
-            jobs: completedJobs,
-            previousSubject: activeSubject,
-            existingSubjectCount: snapshot.subjects.length,
-        });
-        for (const subject of materialized.subjects) {
-            snapshot = upsertLocalSubject(snapshot, subject, materialized.subjectFiles[subject.id] ?? []);
-            events.push(createLocalEvent("subject_created", subject.createdAt, {
+            const candidateRevision = candidateRevisionJobs[0];
+            const completedJobs = [candidateRevision];
+            if (candidateRevision.status === "succeeded") {
+                const candidateRevisionFiles = completedJobOutputFiles(candidateRevision).length > 0
+                    ? normalizeSurfaceFiles(completedJobOutputFiles(candidateRevision).filter((file) => !file.path.startsWith(".workbench/")))
+                    : baseFiles;
+                const attemptJobs = planWorkbenchExecutionJobsForPurpose({
+                    ownerUserId: "local",
+                    projectId: "local",
+                    runId,
+                    candidateId,
+                    attemptIndex,
+                    samples,
+                    now: new Date().toISOString(),
+                    caseIds,
+                    engineCases,
+                    spec,
+                    environmentRefsByCase: environmentRefs.byCase,
+                    workflow: "improve",
+                    purpose: "attempt",
+                });
+                const dagJobs = await executeLocalDevelopmentDag({
+                    jobs: [candidateRevision, ...attemptJobs],
+                    spec,
+                    adapterManifests,
+                    adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
+                    baseFiles: candidateRevisionFiles,
+                    engineResolveFiles,
+                    engineCases,
+                    capacity: devCapacity,
+                });
+                completedJobs.splice(0, completedJobs.length, ...dagJobs);
+            }
+            runTraceJobs.push(...completedJobs);
+            const materialized = materializeWorkbenchRunResult({
+                runId,
+                benchmarkFingerprint,
+                sourceYaml: projectSource.specSource,
+                benchmarkSourceFiles: authoredBenchmarkSourceFiles(projectSource),
+                startedAt,
+                spec,
+                jobs: completedJobs,
+                previousCandidate: activeCandidate,
+                existingCandidateCount: snapshot.candidates.length,
+            });
+            for (const candidate of materialized.candidates) {
+                outputCandidateId = candidate.id;
+                snapshot = upsertLocalCandidate(snapshot, candidate, materialized.candidateFiles[candidate.id] ?? []);
+                events.push(createLocalEvent("candidate_created", candidate.createdAt, {
+                    runId,
+                    candidateId: candidate.id,
+                    baseId: candidate.baseId,
+                    status: candidate.status,
+                    metrics: evaluationMeanMetrics(candidate.eval),
+                }));
+            }
+            for (const evaluation of materialized.evaluations) {
+                snapshot = upsertLocalEvaluation(snapshot, evaluation);
+            }
+            snapshot = setLocalActive(snapshot, materialized.activeCandidateId);
+            currentBaseId = materialized.activeCandidateId ?? currentBaseId;
+            completedJobCount += materialized.completedJobCount;
+            failedJobCount += materialized.failedJobCount;
+            failedJobs.push(...completedJobs
+                .filter((job) => job.status === "failed")
+                .map((job) => ({
+                id: job.id,
+                purpose: workbenchExecutionPurpose(job),
+                error: job.error ?? "Job failed without an error message.",
+            })));
+            events.push(createLocalEvent("active_changed", new Date().toISOString(), {
                 runId,
-                subjectId: subject.id,
-                baseId: subject.baseId,
-                status: subject.status,
-                metrics: subject.metrics,
+                candidateId: materialized.activeCandidateId ?? undefined,
+                activeId: materialized.activeCandidateId ?? undefined,
+                status: materialized.selectedCandidate?.status,
+                metrics: evaluationMeanMetrics(materialized.selectedCandidate?.eval),
             }));
+            await saveLocalJobs(workspace, completedJobs);
+            await saveLocalArchive(workspace, snapshot);
+            attemptsExecuted += 1;
         }
-        for (const evaluation of materialized.evaluations) {
-            snapshot = upsertLocalEvaluation(snapshot, evaluation);
-        }
-        snapshot = setLocalActive(snapshot, materialized.activeSubjectId);
-        currentBaseId = materialized.activeSubjectId ?? currentBaseId;
-        completedJobCount += materialized.completedJobCount;
-        failedJobCount += materialized.failedJobCount;
-        failedJobs.push(...completedJobs
-            .filter((job) => job.status === "failed")
-            .map((job) => ({
-            id: job.id,
-            purpose: workbenchExecutionPurpose(job),
-            error: job.error ?? "Job failed without an error message.",
-        })));
-        events.push(createLocalEvent("active_changed", new Date().toISOString(), {
+        snapshot = await loadLocalArchive(workspace);
+        const finishedAt = new Date().toISOString();
+        const run = {
+            id: runId,
+            workflow: "improve",
+            benchmarkFingerprint,
+            status: "finished",
+            candidateId: baseCandidate.id,
+            candidateRunId: projectSource.spec.candidate.selectedRunId,
+            candidateRunName: projectSource.spec.candidate.selectedRunName,
+            startedAt,
+            finishedAt,
+            durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
+            improver: formatSpecImprover(spec),
+            engineRun: spec.engineRun.use,
+            strategy: "greedy",
+            budget,
+            repairBudget: 0,
+            attemptsRequested: budget,
+            attemptsExecuted,
+            samples,
+            executionFingerprint,
+            stoppedReason: "budget_exhausted",
+            outcome: failedJobCount > 0 ? "error" : "ok",
+            activeCandidateId: snapshot.activeId,
+            outputCandidateId: outputCandidateId ?? snapshot.activeId,
+        };
+        events.push(createLocalEvent("run_finished", finishedAt, {
             runId,
-            subjectId: materialized.activeSubjectId ?? undefined,
-            activeId: materialized.activeSubjectId ?? undefined,
-            status: materialized.selectedSubject?.status,
-            metrics: materialized.selectedSubject?.metrics,
+            detail: {
+                outcome: run.outcome ?? null,
+                attemptsExecuted: run.attemptsExecuted,
+                durationMs: run.durationMs ?? null,
+            },
         }));
-        await saveLocalJobs(workspace, completedJobs);
+        snapshot = upsertLocalRun(snapshot, run, events.slice(1));
         await saveLocalArchive(workspace, snapshot);
+        const outputCandidate = run.outputCandidateId
+            ? readLocalCandidate(snapshot, run.outputCandidateId)
+            : null;
+        const activeCandidate = snapshot.activeId
+            ? readLocalCandidate(snapshot, snapshot.activeId)
+            : null;
+        const result = {
+            ok: failedJobCount === 0,
+            runId,
+            outputCandidateId: run.outputCandidateId,
+            outputCandidate,
+            activeCandidateId: snapshot.activeId,
+            activeCandidate,
+            completedJobCount,
+            failedJobCount,
+            failedJobs,
+            localView: localDevViewHint(workspace, runId),
+        };
+        writeOutput(result, parsed, io, () => {
+            const outputMetricValue = outputCandidate ? formatCandidateEvaluationScore(outputCandidate) : "n/a";
+            const activeMetricValue = activeCandidate ? formatCandidateEvaluationScore(activeCandidate) : "n/a";
+            const firstFailure = result.failedJobs[0];
+            const failureDetail = firstFailure
+                ? `\nFirst failed job ${firstFailure.id}${firstFailure.purpose ? ` (${firstFailure.purpose})` : ""}: ${firstFailure.error}`
+                : "";
+            const viewDetail = failedJobCount === 0
+                ? `\nOpen local view: ${result.localView.command}\n${result.localView.note}`
+                : "";
+            return `Run ${runId} finished. Output candidate: ${formatLocalCandidateLabel(outputCandidate)} (score: ${outputMetricValue}). Active candidate: ${formatLocalCandidateLabel(activeCandidate)} (score: ${activeMetricValue}).${failureDetail}${viewDetail}`;
+        });
+        return failedJobCount === 0 ? 0 : 1;
+    }
+    catch (error) {
+        await markLocalRunFailed({
+            workspace,
+            run: {
+                ...runningRun,
+                attemptsExecuted,
+                outputCandidateId,
+            },
+            startedAt,
+            error,
+        }).catch(() => undefined);
+        throw error;
     }
-    snapshot = await loadLocalArchive(workspace);
-    const finishedAt = new Date().toISOString();
-    const run = {
-        id: runId,
-        workflow: "improve",
-        benchmarkFingerprint,
-        status: "finished",
-        startedAt,
-        finishedAt,
-        durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
-        optimizer: formatSpecOptimizer(spec),
-        engineRun: spec.engineRun.use,
-        strategy: "greedy",
-        budget,
-        repairBudget: 0,
-        attemptsRequested: budget,
-        attemptsExecuted: budget,
-        samples,
-        stoppedReason: "budget_exhausted",
-        outcome: failedJobCount > 0 ? "error" : "ok",
-    };
-    events.push(createLocalEvent("run_finished", finishedAt, {
-        runId,
-        detail: {
-            outcome: run.outcome ?? null,
-            attemptsExecuted: run.attemptsExecuted,
-            durationMs: run.durationMs ?? null,
-        },
-    }));
-    snapshot = appendLocalRun(snapshot, run, events);
-    await saveLocalArchive(workspace, snapshot);
-    const selected = snapshot.activeId
-        ? readLocalSubject(snapshot, snapshot.activeId)
-        : null;
-    const result = {
-        ok: failedJobCount === 0,
-        runId,
-        activeSubjectId: snapshot.activeId,
-        selectedSubject: selected,
-        completedJobCount,
-        failedJobCount,
-        failedJobs,
-        localView: localDevViewHint(workspace, runId),
-    };
-    writeOutput(result, parsed, io, () => {
-        const metricValue = selected?.metrics?.score ?? "n/a";
-        const firstFailure = result.failedJobs[0];
-        const failureDetail = firstFailure
-            ? `\nFirst failed job ${firstFailure.id}${firstFailure.purpose ? ` (${firstFailure.purpose})` : ""}: ${firstFailure.error}`
-            : "";
-        const viewDetail = failedJobCount === 0
-            ? `\nOpen local view: ${result.localView.command}\n${result.localView.note}`
-            : "";
-        return `Run ${runId} finished. Active subject: ${snapshot.activeId ?? "none"} (score: ${metricValue}).${failureDetail}${viewDetail}`;
-    });
-    return failedJobCount === 0 ? 0 : 1;
 }
-async function ensureLocalImproveBaseSubject(args) {
+async function ensureLocalImproveBaseCandidate(args) {
     let snapshot = await loadLocalArchive(args.workspace);
     const explicitBase = asOptionalString(args.parsed.flags.from);
     const benchmarkFingerprint = await readLocalBenchmarkFingerprint(args.workspace);
     if (explicitBase) {
-        let subject = readLocalSubject(snapshot, explicitBase);
-        if (subject.benchmarkFingerprint !== benchmarkFingerprint) {
-            throw new UsageError(`Base subject ${explicitBase} belongs to benchmark ${subject.benchmarkFingerprint}, not ${benchmarkFingerprint}.`);
+        let candidate = readLocalCandidate(snapshot, explicitBase);
+        if (candidate.benchmarkFingerprint !== benchmarkFingerprint) {
+            throw new UsageError(`Base candidate ${explicitBase} belongs to benchmark ${candidate.benchmarkFingerprint}, not ${benchmarkFingerprint}.`);
         }
-        if (!subject.subjectFingerprint) {
-            throw new UsageError(`Base subject ${explicitBase} is missing a subject fingerprint.`);
+        if (!candidate.candidateFingerprint) {
+            throw new UsageError(`Base candidate ${explicitBase} is missing a candidate fingerprint.`);
         }
-        if (subject.status !== "evaluated" && !subject.eval) {
-            const code = await localEvaluateSubject(["--dir", args.workspace, "--subject", explicitBase, "--samples", String(args.samples), "--json"], createSilentIo(args.io), args.runtimeOptions);
+        if (candidate.status !== "evaluated" && !candidate.eval) {
+            const code = await localEvaluateCandidate([
+                "--dir",
+                args.workspace,
+                "--candidate",
+                explicitBase,
+                "--runs",
+                args.projectSource.spec.candidate.selectedRunId,
+                "--samples",
+                String(args.samples),
+                ...(args.parsed.flags.rerun === true ? ["--rerun"] : []),
+                "--json",
+            ], createSilentIo(args.io), args.runtimeOptions);
             if (code !== 0) {
-                throw new UsageError(`Base subject ${explicitBase} eval failed; improve was not started.`);
+                throw new UsageError(`Base candidate ${explicitBase} eval failed; improve was not started.`);
             }
             snapshot = await loadLocalArchive(args.workspace);
-            subject = readLocalSubject(snapshot, explicitBase);
+            candidate = readLocalCandidate(snapshot, explicitBase);
         }
-        return subject;
+        return candidate;
     }
-    const subjectFingerprint = localSubjectFingerprint(args.projectSource);
-    const existing = snapshot.subjects.find((subject) => subject.benchmarkFingerprint === benchmarkFingerprint &&
-        subject.subjectFingerprint === subjectFingerprint &&
-        (subject.status === "evaluated" || Boolean(subject.eval)));
+    const candidateFingerprint = localCandidateFingerprint(args.projectSource);
+    const existing = snapshot.candidates.find((candidate) => candidate.benchmarkFingerprint === benchmarkFingerprint &&
+        candidate.candidateFingerprint === candidateFingerprint &&
+        (candidate.status === "evaluated" || Boolean(candidate.eval)));
     if (existing) {
         return existing;
     }
     const evalArgs = args.parsed.positionals.length > 0
-        ? [args.sourceArg, "--samples", String(args.samples), "--json"]
-        : ["--dir", args.workspace, "--samples", String(args.samples), "--json"];
-    const code = await localEvaluateSubject(evalArgs, createSilentIo(args.io), args.runtimeOptions);
+        ? [
+            args.sourceArg,
+            "--runs",
+            args.projectSource.spec.candidate.selectedRunId,
+            "--samples",
+            String(args.samples),
+            ...(args.parsed.flags.rerun === true ? ["--rerun"] : []),
+            "--json",
+        ]
+        : [
+            "--dir",
+            args.workspace,
+            "--runs",
+            args.projectSource.spec.candidate.selectedRunId,
+            "--samples",
+            String(args.samples),
+            ...(args.parsed.flags.rerun === true ? ["--rerun"] : []),
+            "--json",
+        ];
+    const code = await localEvaluateCandidate(evalArgs, createSilentIo(args.io), args.runtimeOptions);
     if (code !== 0) {
-        throw new UsageError("Parent subject eval failed; improve was not started.");
+        throw new UsageError("Parent candidate eval failed; improve was not started.");
     }
     snapshot = await loadLocalArchive(args.workspace);
-    const evaluated = snapshot.subjects.find((subject) => subject.benchmarkFingerprint === benchmarkFingerprint &&
-        subject.subjectFingerprint === subjectFingerprint &&
-        (subject.status === "evaluated" || Boolean(subject.eval)));
+    const evaluated = snapshot.candidates.find((candidate) => candidate.benchmarkFingerprint === benchmarkFingerprint &&
+        candidate.candidateFingerprint === candidateFingerprint &&
+        (candidate.status === "evaluated" || Boolean(candidate.eval)));
     if (!evaluated) {
-        throw new UsageError("Parent subject eval did not produce an evaluated subject.");
+        throw new UsageError("Parent candidate eval did not produce an evaluated candidate.");
     }
     return evaluated;
 }
@@ -785,13 +1096,62 @@ function createSilentIo(io) {
         stderr: io.stderr,
     };
 }
-async function localEvaluateSubject(argv, io, runtimeOptions) {
+function selectLocalOptimizerBaselineTraceJobs(snapshot, jobs, target) {
+    const runById = new Map(snapshot.runs.map((run) => [run.id, run]));
+    const evaluation = snapshot.evaluations
+        .filter((entry) => {
+        const run = runById.get(entry.runId);
+        return entry.benchmarkFingerprint === target.benchmarkFingerprint &&
+            entry.candidateId === target.candidateId &&
+            entry.candidateRunId === target.candidateRunId &&
+            run?.executionFingerprint === target.executionFingerprint;
+    })
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) ||
+        right.runId.localeCompare(left.runId))[0] ?? null;
+    if (!evaluation) {
+        return [];
+    }
+    return jobs.filter((job) => job.runId === evaluation.runId);
+}
+async function localEvaluateCandidate(argv, io, runtimeOptions) {
     void runtimeOptions;
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "subject", "samples", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "candidate", "runs", "samples", "rerun", "json"]));
     const samples = parsePositiveInt(parsed.flags.samples, 1, "samples");
     const sourceArg = resolveSourceDir(parsed);
-    const projectSource = await readLocalProjectSource(sourceArg);
+    const runsFlag = asOptionalString(parsed.flags.runs);
+    const defaultProjectSource = await readLocalProjectSource(sourceArg);
+    const selectedRunIds = resolveCandidateRunSelection(defaultProjectSource, runsFlag);
+    if (selectedRunIds.length > 1) {
+        let failed = 0;
+        for (const runId of selectedRunIds) {
+            const args = [
+                "--dir",
+                defaultProjectSource.dir,
+                "--runs",
+                runId,
+                "--samples",
+                String(samples),
+                ...(readOptionalCandidateFlag(parsed) ? ["--candidate", readOptionalCandidateFlag(parsed)] : []),
+                ...(parsed.flags.rerun === true ? ["--rerun"] : []),
+                "--json",
+            ];
+            const code = await localEvaluateCandidate(args, createSilentIo(io), runtimeOptions);
+            if (code !== 0) {
+                failed += 1;
+            }
+        }
+        writeOutput({
+            ok: failed === 0,
+            candidateId: defaultProjectSource.candidateName,
+            candidateRunIds: selectedRunIds,
+            failedRunCount: failed,
+        }, parsed, io, () => `Evaluated ${selectedRunIds.length} candidate run(s); ${failed} failed.`);
+        return failed === 0 ? 0 : 1;
+    }
+    const projectSource = selectedRunIds[0] === defaultProjectSource.candidateRunId
+        ? defaultProjectSource
+        : await readLocalProjectSource(sourceArg, { runId: selectedRunIds[0] });
     const workspace = projectSource.dir;
     const executionProject = await resolveLocalProjectForExecution(workspace, projectSource.specSource);
     const { spec, adapterManifests } = executionProject;
@@ -810,114 +1170,367 @@ async function localEvaluateSubject(argv, io, runtimeOptions) {
     const environmentRefs = await ensureLocalDockerfileEnvironments(workspace, spec, engineCases);
     let snapshot = await loadLocalArchive(workspace);
     const benchmarkFingerprint = await readLocalBenchmarkFingerprint(workspace);
-    const sourceSubjectFingerprint = localSubjectFingerprint(projectSource);
-    const explicitSubjectId = asOptionalString(parsed.flags.subject);
-    const existingSourceSubject = snapshot.subjects.find((subject) => subject.benchmarkFingerprint === benchmarkFingerprint &&
-        subject.subjectFingerprint === sourceSubjectFingerprint);
-    const subjectId = explicitSubjectId ?? existingSourceSubject?.id ?? `subject_${sourceSubjectFingerprint.slice(0, 12)}`;
-    const existingSubject = snapshot.subjects.find((subject) => subject.id === subjectId);
-    const files = filterSubjectSourceFiles(existingSubject
-        ? readLocalSubjectFiles(snapshot, subjectId)
-        : normalizeSurfaceFiles(projectSource.subjectFiles));
+    const executionFingerprint = localRunExecutionFingerprint(projectSource);
+    const sourceCandidateFingerprint = localCandidateFingerprint(projectSource);
+    const explicitCandidateId = readOptionalCandidateFlag(parsed);
+    const existingSourceCandidate = snapshot.candidates.find((candidate) => candidate.benchmarkFingerprint === benchmarkFingerprint &&
+        candidate.candidateFingerprint === sourceCandidateFingerprint);
+    const candidateId = explicitCandidateId ?? existingSourceCandidate?.id ?? `candidate_${sourceCandidateFingerprint.slice(0, 12)}`;
+    const existingCandidate = snapshot.candidates.find((candidate) => candidate.id === candidateId);
+    const activeCandidateIdBeforeEval = snapshot.activeId;
+    const selectedCandidateRunId = projectSource.spec.candidate.selectedRunId;
+    const files = filterCandidateSourceFiles(existingCandidate
+        ? readLocalCandidateFiles(snapshot, candidateId)
+        : normalizeSurfaceFiles(projectSource.candidateFiles));
+    const evaluationWork = parsed.flags.rerun !== true
+        ? await resolveLocalEvaluationWork(workspace, snapshot, {
+            benchmarkFingerprint,
+            candidateId,
+            candidateFingerprint: existingCandidate?.candidateFingerprint ?? sourceCandidateFingerprint,
+            candidateRunId: selectedCandidateRunId,
+            executionFingerprint,
+            samples,
+            caseIds,
+        })
+        : null;
+    const reusableEvaluation = evaluationWork?.reusableEvaluation ?? null;
+    if (reusableEvaluation) {
+        const result = {
+            ok: true,
+            reused: true,
+            runId: reusableEvaluation.runId,
+            evaluation: reusableEvaluation,
+            evaluationId: reusableEvaluation.id,
+            candidateId,
+            completedJobCount: 0,
+            failedJobCount: 0,
+            localView: localDevViewHint(workspace, reusableEvaluation.runId),
+        };
+        writeOutput(result, parsed, io, () => `Reused evaluation ${reusableEvaluation.id}. Use --rerun to intentionally run it again.`);
+        return 0;
+    }
+    const selectedPairs = evaluationWork?.missingPairs.length
+        ? evaluationWork.missingPairs
+        : allCaseSamplePairs(caseIds, samples);
     const runId = `eval_local_${Date.now().toString(36)}`;
-    const evaluatedSubjectId = subjectId;
+    const evaluatedCandidateId = candidateId;
     const startedAt = new Date().toISOString();
-    const baseline = createRuntimeBaselineSubjectJob({
-        ownerUserId: "local",
-        projectId: "local",
+    const runStartedEvent = createLocalEvent("run_started", startedAt, {
         runId,
-        subjectId: evaluatedSubjectId,
-        attemptIndex: 0,
-        files,
-        now: startedAt,
-        baseId: null,
+        candidateId: evaluatedCandidateId,
+        detail: { samples, strategy: "direct" },
     });
-    const completedJobs = [baseline];
-    const attemptJobs = planWorkbenchExecutionJobsForPurpose({
-        ownerUserId: "local",
-        projectId: "local",
-        runId,
-        subjectId: evaluatedSubjectId,
-        attemptIndex: 0,
-        samples,
-        now: startedAt,
-        caseIds,
-        engineCases,
-        spec,
-        environmentRefsByCase: environmentRefs.byCase,
-        workflow: "eval",
-        purpose: "attempt",
-    });
-    const dagJobs = await executeLocalDevelopmentDag({
-        jobs: [baseline, ...attemptJobs],
-        spec,
-        adapterManifests,
-        adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
-        baseFiles: files,
-        engineResolveFiles,
-        engineCases,
-        capacity: await localDevelopmentCapacity(workspace),
-    });
-    completedJobs.splice(0, completedJobs.length, ...dagJobs);
-    const materialized = materializeWorkbenchRunResult({
-        runId,
-        benchmarkFingerprint,
-        sourceYaml: projectSource.specSource,
-        benchmarkSourceFiles: authoredBenchmarkSourceFiles(projectSource),
-        subjectFingerprint: existingSubject?.subjectFingerprint ?? sourceSubjectFingerprint,
-        ...(!existingSubject || existingSubject.subjectFingerprint === sourceSubjectFingerprint
-            ? { subjectSourceFiles: authoredSubjectSourceFiles(projectSource) }
-            : {}),
-        startedAt,
-        spec,
-        jobs: completedJobs,
-        previousSubject: null,
-        existingSubjectCount: snapshot.subjects.length,
-    });
-    for (const subjectRecord of materialized.subjects) {
-        snapshot = upsertLocalSubject(snapshot, subjectRecord, materialized.subjectFiles[subjectRecord.id] ?? []);
-    }
-    if (materialized.activeSubjectId) {
-        snapshot = setLocalActive(snapshot, materialized.activeSubjectId);
-    }
-    for (const evaluation of materialized.evaluations) {
-        snapshot = upsertLocalEvaluation(snapshot, evaluation);
-    }
-    const finishedAt = new Date().toISOString();
-    snapshot = appendLocalRun(snapshot, {
+    const runningRun = {
         id: runId,
         workflow: "eval",
         benchmarkFingerprint,
-        status: "finished",
+        status: "running",
+        candidateId: evaluatedCandidateId,
+        candidateRunId: projectSource.spec.candidate.selectedRunId,
+        candidateRunName: projectSource.spec.candidate.selectedRunName,
         startedAt,
-        finishedAt,
-        durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
-        optimizer: "none",
+        improver: "none",
         engineRun: spec.engineRun.use,
         strategy: "direct",
         budget: 1,
         repairBudget: 0,
         attemptsRequested: 1,
-        attemptsExecuted: 1,
+        attemptsExecuted: 0,
         samples,
-        stoppedReason: "completed",
-        outcome: materialized.failedJobCount > 0 ? "error" : "ok",
-    }, []);
-    await saveLocalJobs(workspace, completedJobs);
+        executionFingerprint,
+        activeCandidateId: activeCandidateIdBeforeEval,
+        outputCandidateId: evaluatedCandidateId,
+    };
+    snapshot = upsertLocalRun(snapshot, runningRun, [runStartedEvent]);
     await saveLocalArchive(workspace, snapshot);
-    const evaluation = materialized.evaluations[0] ?? null;
-    const result = {
-        ok: materialized.failedJobCount === 0,
-        runId,
-        evaluation,
-        evaluationId: evaluation?.id ?? null,
-        subjectId: evaluatedSubjectId,
-        completedJobCount: materialized.completedJobCount,
-        failedJobCount: materialized.failedJobCount,
-        localView: localDevViewHint(workspace, runId),
+    try {
+        const baseline = createRuntimeBaselineCandidateJob({
+            ownerUserId: "local",
+            projectId: "local",
+            runId,
+            candidateId: evaluatedCandidateId,
+            attemptIndex: 0,
+            files,
+            now: startedAt,
+            baseId: null,
+        });
+        const attemptJobs = planWorkbenchExecutionJobsForPurpose({
+            ownerUserId: "local",
+            projectId: "local",
+            runId,
+            candidateId: evaluatedCandidateId,
+            attemptIndex: 0,
+            samples,
+            now: startedAt,
+            caseIds: orderedCaseIdsForPairs(caseIds, selectedPairs),
+            sampleIndexesByCase: sampleIndexesByCase(selectedPairs),
+            engineCases,
+            spec,
+            environmentRefsByCase: environmentRefs.byCase,
+            workflow: "eval",
+            purpose: "attempt",
+        });
+        const dagJobs = await executeLocalDevelopmentDag({
+            jobs: [baseline, ...attemptJobs],
+            spec,
+            adapterManifests,
+            adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
+            baseFiles: files,
+            engineResolveFiles,
+            engineCases,
+            capacity: await localDevelopmentCapacity(workspace),
+        });
+        const materializationJobs = [
+            ...(evaluationWork?.priorAttemptJobs ?? []),
+            ...dagJobs,
+        ];
+        const currentRunJobs = dagJobs.filter((job) => job.runId === runId);
+        const currentRunCompletedJobCount = currentRunJobs.filter((job) => job.status === "succeeded").length;
+        const currentRunFailedJobCount = currentRunJobs.filter((job) => job.status === "failed").length;
+        const materialized = materializeWorkbenchRunResult({
+            runId,
+            benchmarkFingerprint,
+            sourceYaml: projectSource.specSource,
+            benchmarkSourceFiles: authoredBenchmarkSourceFiles(projectSource),
+            candidateFingerprint: existingCandidate?.candidateFingerprint ?? sourceCandidateFingerprint,
+            ...(!existingCandidate || existingCandidate.candidateFingerprint === sourceCandidateFingerprint
+                ? { candidateSourceFiles: authoredCandidateSourceFiles(projectSource) }
+                : {}),
+            startedAt,
+            spec,
+            jobs: materializationJobs,
+            previousCandidate: existingCandidate ?? null,
+            existingCandidateCount: snapshot.candidates.length,
+        });
+        for (const candidateRecord of materialized.candidates) {
+            snapshot = upsertLocalCandidate(snapshot, candidateRecord, materialized.candidateFiles[candidateRecord.id] ?? []);
+        }
+        if (materialized.activeCandidateId) {
+            snapshot = setLocalActive(snapshot, materialized.activeCandidateId);
+        }
+        for (const evaluation of materialized.evaluations) {
+            snapshot = upsertLocalEvaluation(snapshot, evaluation);
+        }
+        const activeCandidateId = activeCandidateIdBeforeEval ?? materialized.activeCandidateId ?? null;
+        const finishedAt = new Date().toISOString();
+        if (activeCandidateId) {
+            snapshot = setLocalActive(snapshot, activeCandidateId);
+        }
+        const runFinishedEvent = createLocalEvent("run_finished", finishedAt, {
+            runId,
+            candidateId: evaluatedCandidateId,
+            detail: {
+                outcome: currentRunFailedJobCount > 0 ? "error" : "ok",
+                attemptsExecuted: 1,
+                durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
+            },
+        });
+        snapshot = upsertLocalRun(snapshot, {
+            id: runId,
+            workflow: "eval",
+            benchmarkFingerprint,
+            status: "finished",
+            candidateId: evaluatedCandidateId,
+            candidateRunId: projectSource.spec.candidate.selectedRunId,
+            candidateRunName: projectSource.spec.candidate.selectedRunName,
+            startedAt,
+            finishedAt,
+            durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(startedAt)),
+            improver: "none",
+            engineRun: spec.engineRun.use,
+            strategy: "direct",
+            budget: 1,
+            repairBudget: 0,
+            attemptsRequested: 1,
+            attemptsExecuted: 1,
+            samples,
+            executionFingerprint,
+            stoppedReason: "completed",
+            outcome: currentRunFailedJobCount > 0 ? "error" : "ok",
+            activeCandidateId,
+            outputCandidateId: evaluatedCandidateId,
+        }, [runFinishedEvent]);
+        await saveLocalJobs(workspace, currentRunJobs);
+        await saveLocalArchive(workspace, snapshot);
+        const evaluation = materialized.evaluations[0] ?? null;
+        const result = {
+            ok: currentRunFailedJobCount === 0,
+            runId,
+            evaluation,
+            evaluationId: evaluation?.id ?? null,
+            candidateId: evaluatedCandidateId,
+            activeCandidateId,
+            completedJobCount: currentRunCompletedJobCount,
+            failedJobCount: currentRunFailedJobCount,
+            localView: localDevViewHint(workspace, runId),
+        };
+        writeOutput(result, parsed, io, ({ evaluationId, candidateId }) => `Evaluation ${evaluationId ?? runId} finished for candidate ${candidateId}.\nOpen local view: ${result.localView.command}\n${result.localView.note}`);
+        return currentRunFailedJobCount === 0 ? 0 : 1;
+    }
+    catch (error) {
+        await markLocalRunFailed({
+            workspace,
+            run: runningRun,
+            startedAt,
+            error,
+        }).catch(() => undefined);
+        throw error;
+    }
+}
+async function resolveLocalEvaluationWork(workspace, snapshot, target) {
+    const runById = new Map(snapshot.runs.map((run) => [run.id, run]));
+    const matchingEvaluations = snapshot.evaluations.filter((evaluation) => {
+        const run = runById.get(evaluation.runId);
+        return evaluation.benchmarkFingerprint === target.benchmarkFingerprint &&
+            evaluation.candidateId === target.candidateId &&
+            evaluation.candidateFingerprint === target.candidateFingerprint &&
+            evaluation.candidateRunId === target.candidateRunId &&
+            run?.executionFingerprint === target.executionFingerprint;
+    });
+    const reusableEvaluation = matchingEvaluations
+        .filter((evaluation) => evaluation.status === "completed" &&
+        evaluation.errorSampleCount === 0 &&
+        evaluation.completedSampleCount >= target.samples)
+        .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) ||
+        right.id.localeCompare(left.id))[0] ?? null;
+    if (reusableEvaluation) {
+        return {
+            reusableEvaluation,
+            missingPairs: [],
+            priorAttemptJobs: [],
+        };
+    }
+    const matchingRunIds = new Set(matchingEvaluations.map((evaluation) => evaluation.runId));
+    if (matchingRunIds.size === 0) {
+        return null;
+    }
+    const allPairs = allCaseSamplePairs(target.caseIds, target.samples);
+    const desiredKeys = new Set(allPairs.map(caseSamplePairKey));
+    const previousJobs = await readLocalJobs(workspace);
+    const priorAttemptJobsByPair = latestCompletedAttemptJobsByPair(previousJobs.filter((job) => matchingRunIds.has(job.runId) &&
+        job.candidateId === target.candidateId), desiredKeys);
+    const missingPairs = allPairs.filter((pair) => !priorAttemptJobsByPair.has(caseSamplePairKey(pair)));
+    if (missingPairs.length === allPairs.length) {
+        return null;
+    }
+    return {
+        reusableEvaluation: null,
+        missingPairs,
+        priorAttemptJobs: [...priorAttemptJobsByPair.values()],
     };
-    writeOutput(result, parsed, io, ({ evaluationId, subjectId: evaluatedSubjectId }) => `Evaluation ${evaluationId ?? runId} finished for ${evaluatedSubjectId}.\nOpen local view: ${result.localView.command}\n${result.localView.note}`);
-    return materialized.failedJobCount === 0 ? 0 : 1;
+}
+async function markLocalRunFailed(args) {
+    const latest = await loadLocalArchive(args.workspace);
+    const current = latest.runs.find((run) => run.id === args.run.id);
+    if (current?.status === "finished") {
+        return;
+    }
+    const finishedAt = new Date().toISOString();
+    const message = errorMessage(args.error);
+    const failedRun = {
+        ...args.run,
+        status: "finished",
+        finishedAt,
+        durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(args.startedAt)),
+        outcome: "error",
+        error: message,
+    };
+    await saveLocalArchive(args.workspace, upsertLocalRun(latest, failedRun, [
+        createLocalEvent("run_finished", finishedAt, {
+            runId: args.run.id,
+            candidateId: args.run.candidateId ?? undefined,
+            detail: {
+                outcome: "error",
+                error: message,
+                attemptsExecuted: failedRun.attemptsExecuted,
+                durationMs: failedRun.durationMs ?? null,
+            },
+        }),
+    ]));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function allCaseSamplePairs(caseIds, samples) {
+    return caseIds.flatMap((caseId) => Array.from({ length: samples }, (_, sampleIndex) => ({
+        caseId,
+        sampleIndex,
+    })));
+}
+function orderedCaseIdsForPairs(caseIds, pairs) {
+    const selected = new Set(pairs.map((pair) => pair.caseId));
+    return caseIds.filter((caseId) => selected.has(caseId));
+}
+function sampleIndexesByCase(pairs) {
+    const byCase = new Map();
+    for (const pair of pairs) {
+        byCase.set(pair.caseId, [...(byCase.get(pair.caseId) ?? []), pair.sampleIndex]);
+    }
+    for (const [caseId, indexes] of byCase.entries()) {
+        byCase.set(caseId, [...new Set(indexes)].sort((left, right) => left - right));
+    }
+    return byCase;
+}
+function latestCompletedAttemptJobsByPair(jobs, desiredKeys) {
+    const byPair = new Map();
+    for (const job of jobs) {
+        if (job.status !== "succeeded" || executionPurposeFromJobInput(job.input) !== "attempt") {
+            continue;
+        }
+        const pair = caseSamplePairFromJob(job);
+        if (!pair) {
+            continue;
+        }
+        const key = caseSamplePairKey(pair);
+        if (!desiredKeys.has(key)) {
+            continue;
+        }
+        const previous = byPair.get(key);
+        if (!previous || compareJobRecency(job, previous) > 0) {
+            byPair.set(key, job);
+        }
+    }
+    return byPair;
+}
+function caseSamplePairFromJob(job) {
+    const input = readRecord(job.input);
+    const execution = readRecord(input?.execution);
+    const metadata = readRecord(execution?.metadata);
+    const caseId = stringValue(input?.caseId) ?? stringValue(metadata?.caseId);
+    const sampleIndex = integerValue(input?.sampleIndex) ?? integerValue(metadata?.sampleIndex);
+    return caseId && sampleIndex !== null
+        ? { caseId, sampleIndex }
+        : null;
+}
+function executionPurposeFromJobInput(inputValue) {
+    const input = readRecord(inputValue);
+    const execution = readRecord(input?.execution);
+    return stringValue(execution?.purpose);
+}
+function caseSamplePairKey(pair) {
+    return `${pair.caseId}\0${pair.sampleIndex}`;
+}
+function compareJobRecency(left, right) {
+    return jobRecencyTimestamp(left).localeCompare(jobRecencyTimestamp(right)) ||
+        left.id.localeCompare(right.id);
+}
+function jobRecencyTimestamp(job) {
+    return job.finishedAt ?? job.updatedAt ?? job.startedAt ?? job.createdAt ?? "";
+}
+function findReusableLocalImproveRun(runs, target) {
+    return runs
+        .filter((run) => run.workflow === "improve" &&
+        run.benchmarkFingerprint === target.benchmarkFingerprint &&
+        run.candidateId === target.candidateId &&
+        run.candidateRunId === target.candidateRunId &&
+        run.executionFingerprint === target.executionFingerprint &&
+        run.budget === target.budget &&
+        run.samples === target.samples &&
+        run.status === "finished" &&
+        run.outcome === "ok" &&
+        Boolean(run.outputCandidateId))
+        .sort((left, right) => (right.finishedAt ?? right.startedAt).localeCompare(left.finishedAt ?? left.startedAt) ||
+        right.id.localeCompare(left.id))[0] ?? null;
 }
 function localDevViewHint(workspace, runId) {
     const runFlag = runId ? ` --run ${shellQuote(runId)}` : "";
@@ -935,20 +1548,26 @@ function localDevOpenUrl(baseUrl, snapshot, runId) {
         .reverse()
         .find((entry) => entry.runId === runId);
     if (!evaluation) {
-        return new URL("subjects", baseUrl).toString();
+        return new URL("candidates", baseUrl).toString();
     }
     const params = new URLSearchParams({ evaluation: evaluation.id });
-    return new URL(`subjects/${encodeURIComponent(evaluation.subjectId)}?${params.toString()}`, baseUrl).toString();
+    return new URL(`candidates/${encodeURIComponent(evaluation.candidateId)}?${params.toString()}`, baseUrl).toString();
 }
 async function readLocalBenchmarkFingerprint(workspace) {
     return localBenchmarkFingerprint(await readLocalProjectSource(workspace));
 }
-function authoredSubjectSourceFiles(projectSource) {
+function localRunExecutionFingerprint(projectSource) {
+    return workbenchRunExecutionFingerprint({
+        sourceYaml: projectSource.specSource,
+        adapterFiles: normalizeSurfaceFiles(projectSource.adapterFiles),
+    });
+}
+function authoredCandidateSourceFiles(projectSource) {
     return [{
-            path: path.relative(projectSource.dir, projectSource.subjectSpecPath).split(path.sep).join("/"),
+            path: path.relative(projectSource.dir, projectSource.candidateSpecPath).split(path.sep).join("/"),
             kind: "text",
             encoding: "utf8",
-            content: projectSource.subjectSource,
+            content: projectSource.candidateSource,
             executable: false,
         }];
 }
@@ -1155,72 +1774,72 @@ function requireValidRunEnvelope(args) {
 }
 async function localRestore(argv, io) {
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "subject", "dry-run", "yes", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "candidate", "dry-run", "yes", "json"]));
     const workspace = resolveDir(parsed);
     const spec = await readLocalSpecIfValid(workspace);
     if (!spec) {
         throw new UsageError("restore requires a valid Workbench project.");
     }
-    const subjectRoot = spec.subject.files.path;
+    const candidateRoot = spec.candidate.files.path;
     const snapshot = await loadLocalArchive(workspace);
-    const subjectId = readSubjectIdFlag(parsed, snapshot);
-    const files = readLocalSubjectFiles(snapshot, subjectId);
+    const candidateId = readCandidateIdFlag(parsed, snapshot);
+    const files = readLocalCandidateFiles(snapshot, candidateId);
     if (parsed.flags["dry-run"] === true) {
-        writeOutput({ ok: true, subjectId, fileCount: files.length }, parsed, io, () => `Restore would write ${files.length} file(s) from ${subjectId}.`);
+        writeOutput({ ok: true, candidateId: candidateId, fileCount: files.length }, parsed, io, () => `Restore would write ${files.length} file(s) from ${candidateId}.`);
         return 0;
     }
     if (parsed.flags.yes !== true) {
         throw new UsageError("restore requires --dry-run to preview or --yes to apply source directory changes.");
     }
-    const changedPaths = await materializeSubjectRoot(workspace, subjectRoot, files);
-    const next = setLocalActive(snapshot, subjectId);
+    const changedPaths = await materializeCandidateRoot(workspace, candidateRoot, files);
+    const next = setLocalActive(snapshot, candidateId);
     await saveLocalArchive(workspace, next);
-    writeOutput({ ok: true, activeAfter: subjectId, changedPaths }, parsed, io, () => `Restored ${subjectId} to ${subjectRoot}.`);
+    writeOutput({ ok: true, activeCandidateId: candidateId, changedPaths }, parsed, io, () => `Restored ${candidateId} to ${candidateRoot}.`);
     return 0;
 }
-async function localSubjectList(argv, io) {
+async function localCandidateList(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "json"]));
     const snapshot = await loadLocalArchive(resolveDir(parsed));
-    writeOutput(snapshot.subjects, parsed, io, (subjects) => subjects
-        .map((subject) => `${subject.id}\t${subject.status}\tmetrics ${formatMetricSummary(subject.metrics)}${snapshot.activeId === subject.id ? "\tactive" : ""}`)
-        .join("\n") || "No subjects.");
+    writeOutput(snapshot.candidates, parsed, io, (candidates) => candidates
+        .map((candidate) => `${candidate.id}\t${candidate.status}\tevaluation ${formatCandidateEvaluationScore(candidate)}${snapshot.activeId === candidate.id ? "\tactive" : ""}`)
+        .join("\n") || "No candidates.");
     return 0;
 }
-async function localSubjectShow(argv, io) {
+async function localCandidateShow(argv, io) {
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "subject", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "candidate", "json"]));
     const snapshot = await loadLocalArchive(resolveDir(parsed));
-    const subjectId = readSubjectIdFlag(parsed, snapshot);
-    const subject = readLocalSubject(snapshot, subjectId);
-    writeOutput(subject, parsed, io, (record) => [
+    const candidateId = readCandidateIdFlag(parsed, snapshot);
+    const candidate = readLocalCandidate(snapshot, candidateId);
+    writeOutput(candidate, parsed, io, (record) => [
         `${record.id}\t${record.status}`,
         `benchmark\t${record.benchmarkFingerprint}`,
-        `subject\t${record.subjectFingerprint}`,
-        `metrics\t${formatMetricSummary(record.metrics)}`,
+        `candidate\t${record.candidateFingerprint ?? record.candidateFingerprint}`,
+        `evaluation\t${formatCandidateEvaluationSummary(record)}`,
         ...(record.baseId ? [`base\t${record.baseId}`] : []),
     ].join("\n"));
     return 0;
 }
-async function localSubjectFiles(argv, io) {
+async function localCandidateFiles(argv, io) {
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "subject", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "candidate", "json"]));
     const snapshot = await loadLocalArchive(resolveDir(parsed));
-    const subjectId = readSubjectIdFlag(parsed, snapshot);
-    const subject = readLocalSubject(snapshot, subjectId);
-    const files = summarizeSubjectFiles(readLocalSubjectFiles(snapshot, subjectId), subject.fileChanges);
+    const candidateId = readCandidateIdFlag(parsed, snapshot);
+    const candidate = readLocalCandidate(snapshot, candidateId);
+    const files = summarizeCandidateFiles(readLocalCandidateFiles(snapshot, candidateId), candidate.fileChanges);
     writeOutput(files, parsed, io, (records) => records
         .map((file) => `${file.path}\t${file.status}\t${file.preview_kind}`)
         .join("\n") || "No files.");
     return 0;
 }
-async function localSubjectPreview(argv, io) {
+async function localCandidatePreview(argv, io) {
     const parsed = parseArgs(argv);
-    rejectUnknownFlags(parsed, new Set(["dir", "subject", "path", "output", "view", "json"]));
+    rejectUnknownFlags(parsed, new Set(["dir", "candidate", "path", "output", "view", "json"]));
     const snapshot = await loadLocalArchive(resolveDir(parsed));
-    const subjectId = readSubjectIdFlag(parsed, snapshot);
-    const preview = createSubjectFilePreview({
-        files: readLocalSubjectFiles(snapshot, subjectId),
+    const candidateId = readCandidateIdFlag(parsed, snapshot);
+    const preview = createCandidateFilePreview({
+        files: readLocalCandidateFiles(snapshot, candidateId),
         path: requireFlag(parsed, "path"),
         view: readPreviewMode(parsed),
     });
@@ -1755,7 +2374,7 @@ function createAdapterScaffoldFiles(id) {
         "setup:",
         "  - npm install --global .",
         "operations:",
-        "  subject.run: {}",
+        "  candidate.run: {}",
         "",
     ].join("\n");
     const packageJson = `${JSON.stringify({
@@ -1777,11 +2396,11 @@ const request = requestPath && fs.existsSync(requestPath)
   ? JSON.parse(fs.readFileSync(requestPath, "utf8"))
   : {};
 fs.mkdirSync(outputRoot, { recursive: true });
-const operation = request.operation || "subject.run";
+const operation = request.operation || "candidate.run";
 const resultPath = process.env.WORKBENCH_RESULT || request.paths?.result || path.join(outputRoot, "workbench-result.json");
 
 let value;
-if (operation === "subject.run") {
+if (operation === "candidate.run") {
   const task = request.context?.case?.prompt || "No case prompt was provided.";
   fs.writeFileSync(path.join(outputRoot, "adapter-output.txt"), [
     "adapter: ${id}",
@@ -1790,7 +2409,7 @@ if (operation === "subject.run") {
     "",
   ].join("\\n"));
 } else {
-  console.error("${id} only implements subject.run.");
+  console.error("${id} only implements candidate.run.");
   process.exit(2);
 }
 
@@ -2065,7 +2684,7 @@ async function resolveAdapterForAuthTarget(dir, targetRaw) {
     const adapters = await resolveWorkbenchAdaptersForProject(dir, spec);
     const adapter = adapters.find((entry) => entry.manifest.id === target.adapterId);
     if (!adapter) {
-        throw new UsageError(`Adapter ${target.adapterId} is not used by this benchmark source. Add it to the benchmark, subject, or optimizer YAML before connecting auth.`);
+        throw new UsageError(`Adapter ${target.adapterId} is not used by this benchmark source. Add it to the benchmark or candidate YAML before connecting auth.`);
     }
     if (!adapter.manifest.auth) {
         throw new UsageError(`Adapter ${target.adapterId} does not declare auth.`);
@@ -2728,15 +3347,209 @@ async function starProject(argv, io, starred) {
     });
     return 0;
 }
+async function retryHostedWorkflow(argv, io) {
+    const parsed = parseArgs(argv);
+    rejectUnknownFlags(parsed, new Set([
+        "dir",
+        "benchmark",
+        "watch",
+        "interval-ms",
+        "timeout-ms",
+        "json",
+    ]));
+    rejectUnexpectedPositionals(parsed, "workbench cloud retry", 1);
+    const targetId = parsed.positionals[0];
+    if (!targetId) {
+        throw new UsageError("Missing required TARGET_ID.");
+    }
+    if (parsed.flags.watch !== true && (parsed.flags["interval-ms"] !== undefined ||
+        parsed.flags["timeout-ms"] !== undefined)) {
+        throw new UsageError("--interval-ms and --timeout-ms require --watch.");
+    }
+    const target = await resolveHostedTarget(parsed, { requireProjectIdentity: true });
+    const retryTarget = await resolveHostedRetryTarget(target, targetId);
+    const watchIntervalMs = parsed.flags.watch === true
+        ? parsePositiveInt(parsed.flags["interval-ms"], 1000, "interval-ms")
+        : undefined;
+    const watchTimeoutMs = parsed.flags.watch === true
+        ? parseOptionalPositiveInt(parsed.flags["timeout-ms"], "timeout-ms")
+        : undefined;
+    const response = await apiRequest(projectApiPath(target.projectId, "/runs"), {
+        method: "POST",
+        body: retryTarget.request,
+    }, target.baseUrl);
+    const startedRun = withRunUrls(target, response.run);
+    if (parsed.flags.watch === true) {
+        if (parsed.flags.json !== true) {
+            io.stdout.write(`${formatHostedRunStarted(startedRun, retryTarget.workflow).trimEnd()}\n${HOSTED_WATCH_LIFECYCLE_NOTE}\n`);
+        }
+        const watched = await watchHostedRun({
+            parsed,
+            target,
+            runId: response.run.id,
+            intervalMs: watchIntervalMs ?? 1000,
+            timeoutMs: watchTimeoutMs,
+        });
+        const outputRun = withRunUrls(target, await withHostedRunFailureSummary(target, watched));
+        const result = {
+            ok: hostedRunSucceeded(watched),
+            retried: {
+                id: retryTarget.sourceId,
+                kind: retryTarget.sourceKind,
+                workflow: retryTarget.workflow,
+            },
+            runId: outputRun.id,
+            candidateId: outputRun.outputCandidateId ?? outputRun.candidateId,
+            activeCandidateId: outputRun.activeCandidateId ?? null,
+            run: outputRun,
+            ...(outputRun.urls ? { urls: outputRun.urls } : {}),
+            ...(outputRun.failedJobCount !== undefined ? { failedJobCount: outputRun.failedJobCount } : {}),
+            ...(outputRun.error ? { error: outputRun.error } : {}),
+        };
+        writeOutput(result, parsed, io, formatRetryCommandResult);
+        return hostedRunSucceeded(watched) ? 0 : 1;
+    }
+    const result = {
+        ok: true,
+        retried: {
+            id: retryTarget.sourceId,
+            kind: retryTarget.sourceKind,
+            workflow: retryTarget.workflow,
+        },
+        runId: startedRun.id,
+        candidateId: startedRun.outputCandidateId ?? startedRun.candidateId,
+        activeCandidateId: startedRun.activeCandidateId ?? null,
+        run: startedRun,
+        ...(startedRun.urls ? { urls: startedRun.urls } : {}),
+    };
+    writeOutput(result, parsed, io, formatRetryCommandResult);
+    return 0;
+}
+async function resolveHostedRetryTarget(target, targetId) {
+    if (targetId.startsWith("eval_")) {
+        return await resolveHostedEvaluationRetryTarget(target, targetId);
+    }
+    const detail = await readHostedRunDetail(target, targetId);
+    const run = detail.run;
+    if (run.status !== "finished") {
+        throw new UsageError(`Run ${run.id} is ${run.status}; wait for it to finish before retrying.`);
+    }
+    if (!hostedRunRecordFailed(run)) {
+        throw new UsageError(`Run ${run.id} did not fail; use workbench cloud ${run.workflow ?? "eval"} to intentionally run it again.`);
+    }
+    if (run.workflow === "eval") {
+        const candidateId = hostedRunEvaluationCandidateId(run, detail.jobs);
+        if (!candidateId) {
+            throw new UsageError(`Run ${run.id} has no candidate id to retry.`);
+        }
+        return {
+            sourceId: targetId,
+            sourceKind: "run",
+            workflow: "eval",
+            request: {
+                workflow: "eval",
+                samples: run.samples ?? 1,
+                candidateId,
+                sourceYaml: hostedRetrySourceYaml(run, run.id),
+                preserveActive: true,
+                ...retrySampleSelectionFromJobs(detail.jobs),
+            },
+        };
+    }
+    if (run.workflow === "improve") {
+        const baseCandidateId = stringValue(readRecord(run.input)?.baseCandidateId);
+        if (!baseCandidateId) {
+            throw new UsageError(`Run ${run.id} is missing its base candidate id.`);
+        }
+        return {
+            sourceId: targetId,
+            sourceKind: "run",
+            workflow: "improve",
+            request: {
+                workflow: "improve",
+                samples: run.samples ?? 1,
+                budget: run.budget ?? run.attemptsRequested ?? 1,
+                candidateId: baseCandidateId,
+                sourceYaml: hostedRetrySourceYaml(run, run.id),
+                preserveActive: true,
+            },
+        };
+    }
+    throw new UsageError(`Run ${run.id} has no retryable workflow.`);
+}
+async function resolveHostedEvaluationRetryTarget(target, evaluationId) {
+    const snapshot = await apiRequest(projectApiPath(target.projectId, "/workbench/snapshot"), {}, target.baseUrl);
+    const evaluation = snapshot.evaluations.find((entry) => entry.id === evaluationId);
+    if (!evaluation) {
+        throw new UsageError(`Hosted evaluation not found: ${evaluationId}`);
+    }
+    const run = snapshot.runs.find((entry) => entry.id === evaluation.runId) ?? null;
+    if (!evaluationScorecardFailed(evaluation, run)) {
+        throw new UsageError(`Evaluation ${evaluation.id} did not fail; use workbench cloud eval to intentionally run it again.`);
+    }
+    if (!run) {
+        throw new UsageError(`Evaluation ${evaluation.id} is missing its run record.`);
+    }
+    const detail = await readHostedRunDetail(target, run.id);
+    const detailedRun = detail.run;
+    return {
+        sourceId: evaluationId,
+        sourceKind: "evaluation",
+        workflow: "eval",
+        request: {
+            workflow: "eval",
+            samples: evaluation.sampleCount || detailedRun.samples || 1,
+            candidateId: evaluation.candidateId,
+            sourceYaml: hostedRetrySourceYaml(detailedRun, detailedRun.id),
+            preserveActive: true,
+            ...retrySampleSelectionFromJobs(detail.jobs),
+        },
+    };
+}
+function retrySampleSelectionFromJobs(jobs) {
+    const selectedSamples = uniqueCaseSamplePairs(jobs
+        .filter((job) => job.status !== "succeeded" &&
+        executionPurposeFromJobInput(job.input) === "attempt")
+        .map(caseSamplePairFromJob)
+        .filter((pair) => pair !== null));
+    return selectedSamples.length > 0
+        ? { selectedSamples }
+        : {};
+}
+function uniqueCaseSamplePairs(pairs) {
+    const byKey = new Map();
+    for (const pair of pairs) {
+        byKey.set(caseSamplePairKey(pair), pair);
+    }
+    return [...byKey.values()].sort((left, right) => left.caseId.localeCompare(right.caseId) ||
+        left.sampleIndex - right.sampleIndex);
+}
+async function readHostedRunDetail(target, runId) {
+    return await apiRequest(projectApiPath(target.projectId, `/runs/${encodeURIComponent(runId)}`), {}, target.baseUrl);
+}
+function hostedRetrySourceYaml(run, runId) {
+    const sourceYaml = stringValue(readRecord(run.input)?.sourceYaml);
+    if (!sourceYaml) {
+        throw new UsageError(`Run ${runId} is missing its recorded source configuration.`);
+    }
+    return sourceYaml;
+}
+function hostedRunRecordFailed(run) {
+    return run.outcome === "error" ||
+        run.outcome === "cancelled" ||
+        (run.failedJobCount ?? 0) > 0 ||
+        Boolean(run.error);
+}
 async function startHostedWorkflow(workflow, argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set([
         "dir",
         "benchmark",
         "base",
-        "optimizer",
+        "runs",
         "budget",
         "samples",
+        "rerun",
         "watch",
         "dry-run",
         "interval-ms",
@@ -2746,42 +3559,69 @@ async function startHostedWorkflow(workflow, argv, io) {
     if (parsed.positionals.length > 1) {
         throw new UsageError(`workbench cloud ${workflow} accepts at most one source file or directory argument.`);
     }
-    const optimizerPath = asOptionalString(parsed.flags.optimizer);
     const sourceArg = parsed.positionals[0] ?? asOptionalString(parsed.flags.dir) ?? process.cwd();
     if (parsed.positionals.length > 0 && parsed.flags.dir !== undefined) {
         throw new UsageError("Use either --dir or SOURCE, not both.");
     }
-    const baseSubjectId = asOptionalString(parsed.flags.base);
+    const samples = parsePositiveInt(parsed.flags.samples, 1, "samples");
+    const budget = workflow === "improve"
+        ? parsePositiveInt(parsed.flags.budget, 1, "budget")
+        : undefined;
+    if (parsed.flags.watch !== true && (parsed.flags["interval-ms"] !== undefined ||
+        parsed.flags["timeout-ms"] !== undefined)) {
+        throw new UsageError("--interval-ms and --timeout-ms require --watch.");
+    }
+    const runsFlag = asOptionalString(parsed.flags.runs);
+    const defaultProjectSource = await readLocalProjectSource(path.resolve(sourceArg));
+    const selectedRunIds = workflow === "eval"
+        ? resolveCandidateRunSelection(defaultProjectSource, runsFlag)
+        : [singleRequestedRunId(runsFlag, `workbench cloud ${workflow}`) ?? defaultProjectSource.candidateRunId];
+    if (workflow === "eval" && selectedRunIds.length > 1) {
+        let failed = 0;
+        const results = [];
+        for (const runId of selectedRunIds) {
+            const captured = createCapturingIo(io);
+            const code = await startHostedWorkflow(workflow, hostedWorkflowArgsForRun({
+                parsed,
+                sourceDir: defaultProjectSource.dir,
+                runId,
+            }), captured.io);
+            if (code !== 0) {
+                failed += 1;
+            }
+            results.push(parseCapturedJson(captured.stdoutText()));
+        }
+        writeOutput({
+            ok: failed === 0,
+            candidateRunIds: selectedRunIds,
+            failedRunCount: failed,
+            results,
+        }, parsed, io, () => `Processed ${selectedRunIds.length} hosted candidate run(s); ${failed} failed.`);
+        return failed === 0 ? 0 : 1;
+    }
+    const baseCandidateId = asOptionalString(parsed.flags.base);
     const request = workflow === "improve"
         ? {
             workflow,
-            budget: parsePositiveInt(parsed.flags.budget, 1, "budget"),
-            samples: parsePositiveInt(parsed.flags.samples, 1, "samples"),
-            ...(baseSubjectId ? { subjectId: baseSubjectId } : {}),
+            budget,
+            samples,
+            ...(baseCandidateId ? { candidateId: baseCandidateId } : {}),
         }
         : {
             workflow,
-            samples: parsePositiveInt(parsed.flags.samples, 1, "samples"),
-            ...(baseSubjectId ? { subjectId: baseSubjectId } : {}),
+            samples,
+            ...(baseCandidateId ? { candidateId: baseCandidateId } : {}),
         };
-    if (workflow === "improve" && !optimizerPath) {
-        throw new UsageError("workbench cloud improve requires --optimizer OPTIMIZER_YAML.");
-    }
-    if (parsed.flags.watch !== true && (parsed.flags["interval-ms"] !== undefined ||
-        parsed.flags["timeout-ms"] !== undefined)) {
-        throw new UsageError("--interval-ms and --timeout-ms require --watch.");
-    }
-    const projectSource = await readLocalProjectSource(path.resolve(sourceArg), {
-        optimizerPath,
-    });
-    if (workflow === "eval") {
-        request.subjectSource = projectSource.subjectSource;
-        request.subjectFiles = projectSource.subjectFiles;
-        request.adapterFiles = projectSource.adapterFiles;
+    const projectSource = selectedRunIds[0] === defaultProjectSource.candidateRunId
+        ? defaultProjectSource
+        : await readLocalProjectSource(path.resolve(sourceArg), { runId: selectedRunIds[0] });
+    request.sourceYaml = projectSource.specSource;
+    request.adapterFiles = projectSource.adapterFiles;
+    if (workflow === "eval" && !baseCandidateId) {
+        request.candidateFiles = projectSource.candidateFiles;
     }
-    if (workflow === "improve" && projectSource.optimizerSource) {
-        request.optimizerSource = projectSource.optimizerSource;
-        request.adapterFiles = projectSource.adapterFiles;
+    if (parsed.flags.rerun === true) {
+        request.rerun = true;
     }
     const watchIntervalMs = parsed.flags.watch === true
         ? parsePositiveInt(parsed.flags["interval-ms"], 1000, "interval-ms")
@@ -2808,11 +3648,13 @@ async function startHostedWorkflow(workflow, argv, io) {
         sourceDir: projectSource.dir,
     });
     if (workflow === "improve") {
-        request.subjectId = await ensureHostedImproveBaseSubject({
+        request.candidateId = await ensureHostedImproveBaseCandidate({
             parsed,
             target,
             samples: request.samples,
-            subjectId: baseSubjectId,
+            candidateId: baseCandidateId,
+            sourceYaml: projectSource.specSource,
+            adapterFiles: projectSource.adapterFiles,
             intervalMs: watchIntervalMs ?? 1000,
             timeoutMs: watchTimeoutMs,
         });
@@ -2822,6 +3664,19 @@ async function startHostedWorkflow(workflow, argv, io) {
         body: request,
     }, target.baseUrl);
     const startedRun = withRunUrls(target, response.run);
+    const startedRunOutput = response.reused === true
+        ? { ...startedRun, reused: true }
+        : startedRun;
+    if (response.reused === true && response.run.status === "finished") {
+        writeOutput({
+            ok: hostedRunSucceeded(response.run),
+            reused: true,
+            workflow,
+            runId: startedRun.id,
+            ...startedRun,
+        }, parsed, io, () => `Reused hosted ${workflow} ${startedRun.id}. Use --rerun to intentionally run it again.`);
+        return hostedRunSucceeded(response.run) ? 0 : 1;
+    }
     if (parsed.flags.watch === true) {
         if (parsed.flags.json !== true) {
             io.stdout.write(`${formatHostedRunStarted(startedRun, workflow).trimEnd()}\n${HOSTED_WATCH_LIFECYCLE_NOTE}\n`);
@@ -2837,23 +3692,23 @@ async function startHostedWorkflow(workflow, argv, io) {
         writeOutput(withRunUrls(target, outputRun), parsed, io, formatHostedRunResult);
         return hostedRunSucceeded(watched) ? 0 : 1;
     }
-    writeOutput(startedRun, parsed, io, (run) => formatHostedRunStarted(run, workflow).trimEnd());
+    writeOutput(startedRunOutput, parsed, io, (run) => formatHostedRunStarted(run, workflow).trimEnd());
     return 0;
 }
-async function ensureHostedImproveBaseSubject(args) {
-    if (args.subjectId) {
-        const subject = await readHostedSubjectSummary(args.target, args.subjectId);
-        if (!subject) {
-            throw new UsageError(`Base subject ${args.subjectId} was not found for the current benchmark.`);
+async function ensureHostedImproveBaseCandidate(args) {
+    if (args.candidateId) {
+        const candidate = await readHostedCandidateSummary(args.target, args.candidateId);
+        if (!candidate) {
+            throw new UsageError(`Base candidate ${args.candidateId} was not found for the current benchmark.`);
         }
-        if (hostedSubjectIsEvaluated(subject)) {
-            return args.subjectId;
+        if (hostedCandidateIsEvaluated(candidate)) {
+            return args.candidateId;
         }
     }
     else {
-        const activeSubject = await readEvaluatedActiveHostedSubject(args.target);
-        if (activeSubject) {
-            return activeSubject.id;
+        const activeCandidate = await readEvaluatedActiveHostedCandidate(args.target);
+        if (activeCandidate) {
+            return activeCandidate.id;
         }
     }
     const response = await apiRequest(projectApiPath(args.target.projectId, "/runs"), {
@@ -2861,7 +3716,9 @@ async function ensureHostedImproveBaseSubject(args) {
         body: {
             workflow: "eval",
             samples: args.samples,
-            ...(args.subjectId ? { subjectId: args.subjectId } : {}),
+            ...(args.candidateId ? { candidateId: args.candidateId } : {}),
+            sourceYaml: args.sourceYaml,
+            ...(args.adapterFiles.length > 0 ? { adapterFiles: args.adapterFiles } : {}),
         },
     }, args.target.baseUrl);
     const watched = await watchHostedRun({
@@ -2872,28 +3729,52 @@ async function ensureHostedImproveBaseSubject(args) {
         timeoutMs: args.timeoutMs,
     });
     if (!hostedRunSucceeded(watched)) {
-        throw new UsageError(`Parent subject eval ${watched.id} failed; improve was not started.`);
+        throw new UsageError(`Parent candidate eval ${watched.id} failed; improve was not started.`);
     }
-    if (!watched.subjectId) {
-        throw new UsageError(`Parent subject eval ${watched.id} did not produce a subject.`);
+    if (!watched.candidateId) {
+        throw new UsageError(`Parent candidate eval ${watched.id} did not produce a candidate.`);
     }
-    return watched.subjectId;
+    return watched.candidateId;
 }
-async function readHostedSubjectSummary(target, subjectId) {
-    const response = await apiRequest(projectApiPath(target.projectId, "/subjects"), {}, target.baseUrl);
-    return response.subjects.find((entry) => entry.id === subjectId) ?? null;
+function hostedWorkflowArgsForRun(args) {
+    const next = ["--dir", args.sourceDir, "--runs", args.runId, "--json"];
+    appendStringFlag(next, "benchmark", asOptionalString(args.parsed.flags.benchmark));
+    appendStringFlag(next, "base", asOptionalString(args.parsed.flags.base));
+    appendStringFlag(next, "samples", asOptionalString(args.parsed.flags.samples));
+    appendStringFlag(next, "budget", asOptionalString(args.parsed.flags.budget));
+    appendStringFlag(next, "interval-ms", asOptionalString(args.parsed.flags["interval-ms"]));
+    appendStringFlag(next, "timeout-ms", asOptionalString(args.parsed.flags["timeout-ms"]));
+    if (args.parsed.flags.watch === true) {
+        next.push("--watch");
+    }
+    if (args.parsed.flags["dry-run"] === true) {
+        next.push("--dry-run");
+    }
+    if (args.parsed.flags.rerun === true) {
+        next.push("--rerun");
+    }
+    return next;
+}
+function appendStringFlag(args, name, value) {
+    if (value !== undefined) {
+        args.push(`--${name}`, value);
+    }
+}
+async function readHostedCandidateSummary(target, candidateId) {
+    const response = await apiRequest(projectApiPath(target.projectId, "/candidates"), {}, target.baseUrl);
+    return response.candidates.find((entry) => entry.id === candidateId) ?? null;
 }
-async function readEvaluatedActiveHostedSubject(target) {
+async function readEvaluatedActiveHostedCandidate(target) {
     const response = await apiRequest(projectApiPath(target.projectId), {}, target.baseUrl);
-    const activeSubjectId = response.benchmark.activeSubjectId;
-    if (!activeSubjectId) {
+    const activeCandidateId = response.benchmark.activeCandidateId;
+    if (!activeCandidateId) {
         return null;
     }
-    const subject = await readHostedSubjectSummary(target, activeSubjectId);
-    return subject && hostedSubjectIsEvaluated(subject) ? subject : null;
+    const candidate = await readHostedCandidateSummary(target, activeCandidateId);
+    return candidate && hostedCandidateIsEvaluated(candidate) ? candidate : null;
 }
-function hostedSubjectIsEvaluated(subject) {
-    return subject.status === "evaluated" || subject.eval != null;
+function hostedCandidateIsEvaluated(candidate) {
+    return candidate.status === "evaluated" || candidate.eval != null;
 }
 async function benchmarkList(argv, io) {
     const parsed = parseArgs(argv);
@@ -2905,7 +3786,7 @@ async function benchmarkList(argv, io) {
             return "No hosted Workbench benchmarks.";
         }
         return projects
-            .map((project) => `${project.id}\t${project.name}\t${project.runCount} runs\t${project.subjectCount} subjects`)
+            .map((project) => `${project.id}\t${project.name}\t${project.runCount} runs\t${project.candidateCount} candidates`)
             .join("\n");
     });
     return 0;
@@ -2924,7 +3805,7 @@ async function benchmarkShow(argv, io) {
     const response = await apiRequest(benchmarkApiPath(projectRef), {}, await effectiveBaseUrl(origin?.baseUrl));
     writeOutput(response.benchmark, parsed, io, (project) => {
         const record = project;
-        return `${record.name} (${record.id})\n${record.runs.length} runs\n${record.subjects.length} subjects`;
+        return `${record.name} (${record.id})\n${record.runs.length} runs\n${record.candidates.length} candidates`;
     });
     return 0;
 }
@@ -3012,61 +3893,61 @@ async function benchmarkStarred(argv, io) {
     });
     return 0;
 }
-async function subjectList(argv, io) {
+async function candidateList(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "json"]));
-    rejectUnexpectedPositionals(parsed, "workbench cloud subjects list", 0);
+    rejectUnexpectedPositionals(parsed, "workbench cloud candidates list", 0);
     const target = await resolveHostedTarget(parsed);
-    const response = await apiRequest(projectApiPath(target.projectId, "/subjects"), {}, target.baseUrl);
-    writeOutput(response.subjects, parsed, io, (subjects) => {
-        if (subjects.length === 0) {
-            return "No subjects yet.";
+    const response = await apiRequest(projectApiPath(target.projectId, "/candidates"), {}, target.baseUrl);
+    writeOutput(response.candidates, parsed, io, (candidates) => {
+        if (candidates.length === 0) {
+            return "No candidates yet.";
         }
-        return subjects
-            .map((subject) => `${subject.id}\t${subject.status}\tmetrics ${formatMetricSummary(subject.metrics)}\t${subject.fileChanges?.length ?? 0} files`)
+        return candidates
+            .map((candidate) => `${candidate.id}\t${candidate.status}\t${candidate.fileChanges?.length ?? 0} files`)
             .join("\n");
     });
     return 0;
 }
-async function subjectShow(argv, io) {
+async function candidateShow(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "json"]));
-    rejectUnexpectedPositionals(parsed, "workbench cloud subjects show", 1);
+    rejectUnexpectedPositionals(parsed, "workbench cloud candidates show", 1);
     const target = await resolveHostedTarget(parsed);
-    const subjectId = readRequiredSubjectId(parsed);
-    const params = new URLSearchParams({ id: subjectId });
-    const subject = await apiRequest(projectApiPath(target.projectId, `/workbench/record?${params.toString()}`), {}, target.baseUrl);
-    writeOutput(subject, parsed, io, (record) => {
+    const candidateId = readRequiredCandidateId(parsed);
+    const params = new URLSearchParams({ id: candidateId });
+    const candidate = await apiRequest(projectApiPath(target.projectId, `/workbench/record?${params.toString()}`), {}, target.baseUrl);
+    writeOutput(candidate, parsed, io, (record) => {
         const value = record;
         return [
-            `${value.id ?? subjectId}\t${value.status ?? "unknown"}`,
+            `${value.id ?? candidateId}\t${value.status ?? "unknown"}`,
             ...(value.benchmarkFingerprint ? [`Benchmark version: ${shortDigest(value.benchmarkFingerprint)}`] : []),
-            ...(value.subjectFingerprint ? [`Subject digest: ${shortDigest(value.subjectFingerprint)}`] : []),
+            ...(value.candidateFingerprint ? [`Candidate digest: ${shortDigest(value.candidateFingerprint)}`] : []),
         ].join("\n");
     });
     return 0;
 }
-async function subjectFiles(argv, io) {
+async function candidateFiles(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "json"]));
-    rejectUnexpectedPositionals(parsed, "workbench cloud subjects files", 1);
+    rejectUnexpectedPositionals(parsed, "workbench cloud candidates files", 1);
     const target = await resolveHostedTarget(parsed);
-    const subjectId = readRequiredSubjectId(parsed);
-    const response = await apiRequest(projectApiPath(target.projectId, `/subjects/${encodeURIComponent(subjectId)}/files`), {}, target.baseUrl);
+    const candidateId = readRequiredCandidateId(parsed);
+    const response = await apiRequest(projectApiPath(target.projectId, `/candidates/${encodeURIComponent(candidateId)}/files`), {}, target.baseUrl);
     writeOutput(response.files, parsed, io, (files) => files
         .map((file) => `${file.path}\t${file.status}\t${file.preview_kind}`)
         .join("\n") || "No files.");
     return 0;
 }
-async function subjectPreview(argv, io) {
+async function candidatePreview(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "path", "output", "json"]));
-    rejectUnexpectedPositionals(parsed, "workbench cloud subjects preview", 1);
+    rejectUnexpectedPositionals(parsed, "workbench cloud candidates preview", 1);
     const target = await resolveHostedTarget(parsed);
-    const subjectId = readRequiredSubjectId(parsed);
+    const candidateId = readRequiredCandidateId(parsed);
     const filePath = requireFlag(parsed, "path");
     const params = new URLSearchParams({ path: filePath });
-    const response = await apiRequest(projectApiPath(target.projectId, `/subjects/${encodeURIComponent(subjectId)}/files?${params.toString()}`), {}, target.baseUrl);
+    const response = await apiRequest(projectApiPath(target.projectId, `/candidates/${encodeURIComponent(candidateId)}/files?${params.toString()}`), {}, target.baseUrl);
     const content = response.preview.source?.content ??
         response.preview.rendered_html ??
         response.preview.diff ??
@@ -3084,14 +3965,14 @@ async function subjectPreview(argv, io) {
     }
     return 0;
 }
-async function subjectExport(argv, io) {
+async function candidateExport(argv, io) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "out", "json"]));
-    rejectUnexpectedPositionals(parsed, "workbench cloud subjects pull", 1);
+    rejectUnexpectedPositionals(parsed, "workbench cloud candidates pull", 1);
     const target = await resolveHostedTarget(parsed);
-    const subjectId = readRequiredSubjectId(parsed);
+    const candidateId = readRequiredCandidateId(parsed);
     const outputDir = requireOutDir(parsed);
-    const response = await apiRequest(projectApiPath(target.projectId, `/subjects/${encodeURIComponent(subjectId)}/export`), {}, target.baseUrl);
+    const response = await apiRequest(projectApiPath(target.projectId, `/candidates/${encodeURIComponent(candidateId)}/export`), {}, target.baseUrl);
     await writeFiles(outputDir, response.files);
     writeOutput({ ok: true, outputDir, files: response.files.length }, parsed, io, (result) => {
         const record = result;
@@ -3099,14 +3980,14 @@ async function subjectExport(argv, io) {
     });
     return 0;
 }
-async function subjectVisibility(argv, io, visibility) {
+async function candidateVisibility(argv, io, visibility) {
     const parsed = parseArgs(argv);
     rejectUnknownFlags(parsed, new Set(["dir", "benchmark", "json"]));
-    rejectUnexpectedPositionals(parsed, `workbench cloud subjects ${visibility === "public" ? "publish" : "unpublish"}`, 1);
+    rejectUnexpectedPositionals(parsed, `workbench cloud candidates ${visibility === "public" ? "publish" : "unpublish"}`, 1);
     const target = await resolveHostedTarget(parsed, { requireProjectIdentity: true });
-    const subjectId = readRequiredSubjectId(parsed);
-    const response = await apiRequest(projectApiPath(target.projectId, `/subjects/${encodeURIComponent(subjectId)}/publish`), { method: visibility === "public" ? "PUT" : "DELETE" }, target.baseUrl);
-    writeOutput({ ok: true, visibility, subject: response.subject }, parsed, io, () => `${visibility === "public" ? "Published" : "Unpublished"} subject ${subjectId}.`);
+    const candidateId = readRequiredCandidateId(parsed);
+    const response = await apiRequest(projectApiPath(target.projectId, `/candidates/${encodeURIComponent(candidateId)}/publish`), { method: visibility === "public" ? "PUT" : "DELETE" }, target.baseUrl);
+    writeOutput({ ok: true, visibility, candidate: response.candidate }, parsed, io, () => `${visibility === "public" ? "Published" : "Unpublished"} candidate ${candidateId}.`);
     return 0;
 }
 async function runList(argv, io) {
@@ -3116,7 +3997,7 @@ async function runList(argv, io) {
     const target = await resolveHostedTarget(parsed);
     const response = await apiRequest(projectApiPath(target.projectId, "/runs"), {}, target.baseUrl);
     writeOutput(response.runs, parsed, io, (runs) => runs
-        .map((run) => `${run.id}\t${run.status}\t${run.subjectId ?? "pending"}`)
+        .map((run) => `${run.id}\t${run.status}\t${run.candidateId ?? "pending"}`)
         .join("\n") || "No runs.");
     return 0;
 }
@@ -3191,7 +4072,7 @@ async function runLogs(argv, io) {
 function formatRunLogs(record) {
     const value = record;
     return (value.jobs
-        .map((job) => `${job.id}\t${job.kind}\t${job.status}\t${job.subjectId ?? "-"}${job.error ? `\t${job.error}` : ""}`)
+        .map((job) => `${job.id}\t${job.kind}\t${job.status}\t${job.candidateId ?? "-"}${job.error ? `\t${job.error}` : ""}`)
         .join("\n") || `No jobs for ${value.runId}.`);
 }
 async function openWorkbench(argv, io) {
@@ -3226,7 +4107,7 @@ function buildWorkbenchWebUrl(target, ref) {
     if (ref.startsWith("run_")) {
         return benchmarkUrl;
     }
-    return buildWorkbenchResourceUrls(target, { subjectId: ref }).subjectEvaluation;
+    return buildWorkbenchResourceUrls(target, { candidateId: ref }).candidateEvaluation;
 }
 async function resolveHostedTarget(parsed, options = {}) {
     if (options.sourceArg !== undefined && parsed.flags.dir !== undefined) {
@@ -3313,7 +4194,7 @@ async function resolveOpenTarget(parsed) {
     const ref = parsed.positionals[0];
     if (ref &&
         !ref.startsWith("run_") &&
-        !ref.startsWith("subject_")) {
+        !ref.startsWith("candidate_")) {
         const baseUrl = await effectiveBaseUrl();
         if (ref.includes("/")) {
             const parsedRef = parseBenchmarkRef(ref);
@@ -3347,13 +4228,13 @@ function buildWorkbenchResourceUrls(target, refs = {}) {
     const projectRef = `${encodeURIComponent(target.owner)}/${encodeURIComponent(target.projectName)}`;
     const benchmark = `${target.baseUrl}/benchmarks/${projectRef}`;
     const urls = { benchmark };
-    if (refs.subjectId) {
+    if (refs.candidateId) {
         const evaluationId = refs.runId
-            ? evaluationScorecardId(refs.runId, refs.subjectId)
+            ? evaluationScorecardId(refs.runId, refs.candidateId)
             : null;
-        urls.subjectEvaluation = evaluationId
-            ? `${benchmark}/subjects/${encodeURIComponent(refs.subjectId)}?evaluation=${encodeURIComponent(evaluationId)}`
-            : `${benchmark}/subjects/${encodeURIComponent(refs.subjectId)}`;
+        urls.candidateEvaluation = evaluationId
+            ? `${benchmark}/candidates/${encodeURIComponent(refs.candidateId)}?evaluation=${encodeURIComponent(evaluationId)}`
+            : `${benchmark}/candidates/${encodeURIComponent(refs.candidateId)}`;
     }
     return urls;
 }
@@ -3423,15 +4304,15 @@ function withRunUrls(target, run) {
         ...run,
         urls: buildWorkbenchResourceUrls(target, {
             runId: run.id,
-            subjectId: run.outputSubjectId ?? run.subjectId,
+            candidateId: run.outputCandidateId ?? run.candidateId,
         }),
     };
 }
 function withRunDetailUrls(target, detail) {
-    const subjectId = hostedRunEvaluationSubjectId(detail.run, detail.jobs);
+    const candidateId = hostedRunEvaluationCandidateId(detail.run, detail.jobs);
     const run = withRunUrls(target, {
         ...detail.run,
-        outputSubjectId: detail.run.outputSubjectId ?? subjectId,
+        outputCandidateId: detail.run.outputCandidateId ?? candidateId,
     });
     return {
         run,
@@ -3439,15 +4320,15 @@ function withRunDetailUrls(target, detail) {
         urls: run.urls ?? buildWorkbenchResourceUrls(target, { runId: run.id }),
     };
 }
-function hostedRunEvaluationSubjectId(run, jobs = []) {
-    if (run.outputSubjectId) {
-        return run.outputSubjectId;
+function hostedRunEvaluationCandidateId(run, jobs = []) {
+    if (run.outputCandidateId) {
+        return run.outputCandidateId;
     }
-    const attemptSubjects = jobs
+    const attemptCandidates = jobs
         .filter((job) => readRunJobPurpose(job) === "attempt")
-        .map((job) => job.subjectId)
-        .filter((subjectId) => Boolean(subjectId));
-    return attemptSubjects.at(-1) ?? run.subjectId ?? null;
+        .map((job) => job.candidateId)
+        .filter((candidateId) => Boolean(candidateId));
+    return attemptCandidates.at(-1) ?? run.candidateId ?? null;
 }
 function sourceFileCount(source) {
     return source.sourceFiles.length;
@@ -3456,7 +4337,7 @@ function hostedProjectSourceRequest(source) {
     const { network, resources } = hostedEnvironmentOptions(source);
     return {
         source: source.specSource,
-        subjectFiles: source.subjectFiles,
+        candidateFiles: source.candidateFiles,
         engineResolveFiles: hostedEngineResolveFiles(source),
         engineResolveBinding: engineResolveBindingForSpec(source.spec),
         adapterFiles: source.adapterFiles,
@@ -3539,24 +4420,45 @@ async function watchHostedRun(args) {
     }
 }
 function formatHostedRunResult(run) {
-    const subjectId = run.outputSubjectId ?? run.subjectId;
-    const activeDetail = run.activeSubjectId && subjectId && run.activeSubjectId !== subjectId
-        ? `; active ${run.activeSubjectId}`
+    const candidateId = run.outputCandidateId ?? run.candidateId;
+    const activeDetail = run.activeCandidateId && candidateId && run.activeCandidateId !== candidateId
+        ? `; active ${run.activeCandidateId}`
         : "";
-    const summary = `Run ${run.id} reached ${run.status}; ${run.outcome ? `outcome ${run.outcome}; ` : ""}subject ${subjectId ?? "pending"}${activeDetail}; ${run.completedJobCount ?? 0}/${run.jobCount ?? 0} jobs completed.`;
+    const summary = `Run ${run.id} reached ${run.status}; ${run.outcome ? `outcome ${run.outcome}; ` : ""}candidate ${candidateId ?? "pending"}${activeDetail}; ${run.completedJobCount ?? 0}/${run.jobCount ?? 0} jobs completed.`;
     return [
         run.error ? `${summary}\nError: ${run.error}` : summary,
-        ...(run.urls?.subjectEvaluation
-            ? [`Open evaluation: ${run.urls.subjectEvaluation}`]
+        ...(run.urls?.candidateEvaluation
+            ? [`Open evaluation: ${run.urls.candidateEvaluation}`]
             : [`Open benchmark: ${run.urls?.benchmark ?? ""}`].filter(Boolean)),
     ].join("\n");
 }
+function formatRetryCommandResult(result) {
+    const run = result.run;
+    const runId = run?.id ?? result.runId ?? "unknown";
+    const scope = `${result.retried.kind} ${result.retried.id}`;
+    const verb = run
+        ? run.status === "finished" ? "finished as hosted run" : "started as hosted run"
+        : "finished as local run";
+    return [
+        `Retry of ${scope} ${verb} ${runId}.`,
+        ...(result.evaluationId ? [`Evaluation: ${result.evaluationId}`] : []),
+        ...(result.candidateId ? [`Candidate: ${result.candidateId}`] : []),
+        ...(result.failedJobCount ? [`Failed jobs: ${result.failedJobCount}`] : []),
+        ...(result.error ? [`Error: ${result.error}`] : []),
+        ...(result.localView
+            ? [`Open local view: ${result.localView.command}`, result.localView.note]
+            : []),
+        ...(result.urls?.candidateEvaluation
+            ? [`Open evaluation: ${result.urls.candidateEvaluation}`]
+            : result.urls?.benchmark ? [`Open benchmark: ${result.urls.benchmark}`] : []),
+    ].join("\n");
+}
 function formatHostedRunStarted(run, fallbackWorkflow) {
-    const subjectId = run.outputSubjectId ?? run.subjectId;
+    const candidateId = run.outputCandidateId ?? run.candidateId;
     return [
-        `Started ${run.workflow ?? fallbackWorkflow} run ${run.id}; ${subjectId ? `subject ${subjectId}` : `${run.jobCount ?? 0} jobs queued`}.`,
-        ...(run.urls?.subjectEvaluation
-            ? [`Open evaluation: ${run.urls.subjectEvaluation}`]
+        `Started ${run.workflow ?? fallbackWorkflow} run ${run.id}; ${candidateId ? `candidate ${candidateId}` : `${run.jobCount ?? 0} jobs queued`}.`,
+        ...(run.urls?.candidateEvaluation
+            ? [`Open evaluation: ${run.urls.candidateEvaluation}`]
             : run.urls?.benchmark ? [`Open benchmark: ${run.urls.benchmark}`] : []),
         "",
     ].join("\n");
@@ -3566,13 +4468,13 @@ function formatRunDetail(record) {
     const { run, jobs, urls } = detail;
     const cost = sumJobCostUsd(jobs);
     const firstFailedJob = jobs.find((job) => job.status === "failed" && job.error);
-    const subjectId = hostedRunEvaluationSubjectId(run, jobs);
+    const candidateId = hostedRunEvaluationCandidateId(run, jobs);
     return [
         `Run ${run.id}: ${run.status}${run.outcome ? ` (${run.outcome})` : ""}`,
         `Workflow: ${run.workflow ?? "improve"}`,
-        `Subject: ${subjectId ?? "pending"}`,
-        ...(run.activeSubjectId && subjectId && run.activeSubjectId !== subjectId
-            ? [`Active subject: ${run.activeSubjectId}`]
+        `Candidate: ${candidateId ?? "pending"}`,
+        ...(run.activeCandidateId && candidateId && run.activeCandidateId !== candidateId
+            ? [`Active candidate: ${run.activeCandidateId}`]
             : []),
         `Samples: ${run.samples ?? 0}`,
         `Attempts: ${run.attemptsExecuted ?? 0}/${run.attemptsRequested ?? run.attemptsExecuted ?? 0}`,
@@ -3584,8 +4486,8 @@ function formatRunDetail(record) {
         ...(firstFailedJob?.error
             ? [`First failed job ${firstFailedJob.id}: ${firstFailedJob.error}`]
             : []),
-        ...(urls.subjectEvaluation
-            ? [`Open evaluation: ${urls.subjectEvaluation}`]
+        ...(urls.candidateEvaluation
+            ? [`Open evaluation: ${urls.candidateEvaluation}`]
             : [`Open benchmark: ${urls.benchmark}`]),
         ...(jobs.length > 0 ? ["", "Jobs:", ...jobs.map(formatRunJobLine)] : []),
     ].join("\n");
@@ -3595,7 +4497,7 @@ function formatRunJobLine(job) {
         job.id,
         readRunJobPurpose(job) ?? job.kind ?? "job",
         job.status,
-        job.subjectId ?? "-",
+        job.candidateId ?? "-",
         job.error ?? "",
     ].filter((value, index) => index < 4 || value !== "").join("\t");
 }
@@ -3621,7 +4523,7 @@ function costUsdFromUsage(value) {
     if (direct !== null) {
         return direct;
     }
-    return ["total", "optimizer", "runner", "engine"].reduce((sum, key) => {
+    return ["total", "improver", "runner", "engine"].reduce((sum, key) => {
         const nested = readRecord(usage[key]);
         return sum + (readFiniteNumber(nested?.costUsd) ?? 0);
     }, 0);
@@ -3631,6 +4533,15 @@ function readRecord(value) {
         ? value
         : null;
 }
+function stringValue(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function numberValue(value) {
+    return readFiniteNumber(value);
+}
+function integerValue(value) {
+    return Number.isSafeInteger(value) ? value : null;
+}
 function readFiniteNumber(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : null;
 }
@@ -3763,15 +4674,15 @@ async function readWorkbenchProfileStatus(config) {
         return { authenticated: true, profile: null };
     }
 }
-function readOptionalSubjectId(parsed) {
-    return asOptionalString(parsed.flags.subject) ?? parsed.positionals[0];
+function readOptionalCandidateId(parsed) {
+    return asOptionalString(parsed.flags.candidate) ?? parsed.positionals[0];
 }
-function readRequiredSubjectId(parsed) {
-    const subjectId = readOptionalSubjectId(parsed);
-    if (!subjectId) {
-        throw new UsageError("Missing required SUBJECT_ID.");
+function readRequiredCandidateId(parsed) {
+    const candidateId = readOptionalCandidateId(parsed);
+    if (!candidateId) {
+        throw new UsageError("Missing required CANDIDATE_ID.");
     }
-    return subjectId;
+    return candidateId;
 }
 function readRequiredRunId(parsed) {
     const runId = parsed.positionals[0];
@@ -4002,6 +4913,38 @@ function readInitAgent(parsed, kind) {
 function asOptionalString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function singleRequestedRunId(value, command) {
+    if (!value || value.trim() === "") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed === "all" || trimmed.includes(",")) {
+        throw new UsageError(`${command} accepts one candidate run id for --runs; use workbench eval --runs all to evaluate every run.`);
+    }
+    return trimmed;
+}
+function resolveCandidateRunSelection(source, value) {
+    const available = source.candidateRunIds;
+    if (available.length === 0) {
+        throw new UsageError("Candidate must declare at least one run.");
+    }
+    if (!value || value.trim() === "") {
+        return [source.candidateRunId];
+    }
+    const trimmed = value.trim();
+    if (trimmed === "all") {
+        return available;
+    }
+    const requested = [...new Set(trimmed.split(",").map((entry) => entry.trim()).filter(Boolean))];
+    if (requested.length === 0) {
+        throw new UsageError("--runs must include at least one run id or all.");
+    }
+    const missing = requested.filter((runId) => !available.includes(runId));
+    if (missing.length > 0) {
+        throw new UsageError(`Unknown candidate run(s): ${missing.join(", ")}. Available: ${available.join(", ")}.`);
+    }
+    return requested;
+}
 function readOptionalStringFlag(value, name) {
     if (value == null || value === false) {
         return undefined;
@@ -4226,6 +5169,27 @@ function parsePortFlag(value) {
     }
     return port;
 }
+function formatCandidateEvaluationScore(candidate) {
+    const score = candidate.eval?.metrics?.score?.mean;
+    return typeof score === "number" && Number.isFinite(score)
+        ? formatMetricValue(score)
+        : "n/a";
+}
+function formatLocalCandidateLabel(candidate) {
+    if (!candidate) {
+        return "none";
+    }
+    const name = candidate.name?.trim() || candidate.id;
+    const displayName = candidate.version > 0
+        ? `${name} v${candidate.version}`
+        : name;
+    return `${displayName} (${candidate.id})`;
+}
+function formatCandidateEvaluationSummary(candidate) {
+    return formatMetricSummary(evaluationMeanMetrics(candidate.eval), {
+        limit: Number.POSITIVE_INFINITY,
+    });
+}
 function formatMetricSummary(metrics, options = {}) {
     const entries = Object.entries(metrics ?? {}).filter((entry) => Number.isFinite(entry[1]));
     if (entries.length === 0) {
@@ -4263,15 +5227,18 @@ function resolveSourceDir(parsed) {
 function isWorkbenchSourceYamlPath(filePath) {
     return path.basename(filePath) === WORKBENCH_BENCHMARK_FILE;
 }
-function readSubjectIdFlag(parsed, snapshot) {
-    const explicit = asOptionalString(parsed.flags.subject) ?? asOptionalString(parsed.flags.subject);
+function readCandidateIdFlag(parsed, snapshot) {
+    const explicit = readOptionalCandidateFlag(parsed);
     if (explicit) {
         return explicit;
     }
     if (snapshot.activeId) {
         return snapshot.activeId;
     }
-    throw new UsageError("Missing required --subject; no active subject exists.");
+    throw new UsageError("Missing required --candidate; no active candidate exists.");
+}
+function readOptionalCandidateFlag(parsed) {
+    return asOptionalString(parsed.flags.candidate);
 }
 function readPreviewMode(parsed) {
     const view = asOptionalString(parsed.flags.view) ?? "rendered";
@@ -4375,8 +5342,8 @@ async function copyInitSeedIfProvided(parsed, workspace, seed) {
         }
     });
 }
-function formatSpecOptimizer(spec) {
-    return spec.improve ? `adapter:${spec.improve.use}` : "optimizer not configured";
+function formatSpecImprover(spec) {
+    return spec.improve ? `adapter:${spec.improve.use}` : "improve not configured";
 }
 async function writeFiles(outputDir, files) {
     await fs.mkdir(outputDir, { recursive: true });