@citeark/agent 0.3.20

package/src/reproduction/lifecycle.mjs

@@ -0,0 +1,253 @@
+import { stageReferenceMaterials } from "../research/reference-materials.mjs";
+import { hasResearchWorkspace } from "./workspace-mode.mjs";
+import path from "node:path";
+import { lstat, rename } from "node:fs/promises";
+import { restoreRunRecovery } from "../compute/coordinator-recovery.mjs";
+import { preserveIncompleteInitialization } from './incomplete-initialization.mjs';
+import { initialResearchPlan, resolveResearchPlan, stageResearchPlanTools, PLAN_FILE } from "./plan.mjs";
+
+import { redactSensitive } from "../cap/redaction.mjs";
+import { validateComputeDecision } from "../compute/scheduler.mjs";
+import { buildRunnerAudit } from "../execution/runner-audit.mjs";
+import { ensureFinalWorkspaceCapture, prepareRunBundle, updateRunState } from "../job.mjs";
+import { loadAndNormalizeTask, validateResultFile } from "../protocol.mjs";
+import { publicAgentRuntime, resolveAgentRuntime } from "../runtime/config.mjs";
+import { readAgentUsage } from "../telemetry/usage.mjs";
+import { CiteArkError, writeJson } from "../util.mjs";
+
+export async function prepareReproduction({
+  taskPath,
+  referenceMaterialsPath,
+  runsDirectory,
+  imageOverride,
+  repositoryOverride,
+  paperOverride,
+  computeDecision,
+  runId,
+  agentRuntime,
+  requireApi = true,
+  sandboxProvider = "docker",
+  validateScientificComputeDecision = true,
+}) {
+  if (computeDecision && imageOverride) {
+    throw new CiteArkError("使用 compute decision 时不能再用 imageOverride 改写已记录的执行环境");
+  }
+  const loaded = await loadAndNormalizeTask(taskPath);
+  if (computeDecision && validateScientificComputeDecision) {
+    validateComputeDecision(computeDecision, loaded.task);
+  }
+  const runtimeAgent = resolveAgentRuntime({
+    taskAgent: loaded.task.agent,
+    ...agentRuntime,
+    requireApi,
+  });
+  const restored = await restoreRunRecovery({ runsDirectory, runId, task: loaded.task });
+  if (!restored && runId) await preserveIncompleteInitialization({ runsDirectory, runId, task: loaded.task });
+  const bundle = restored ?? await prepareRunBundle({
+    ...loaded,
+    runsDirectory,
+    runId,
+    imageOverride,
+    repositoryOverride,
+    paperOverride,
+  });
+  if (restored && hasResearchWorkspace(bundle.runtimeTask)) {
+    await stageResearchPlanTools(bundle.directories.input);
+  }
+  await stageReferenceMaterials(referenceMaterialsPath, bundle.directories.input);
+  bundle.runtimeAgent = runtimeAgent;
+  bundle.computeDecision = computeDecision ?? null;
+  bundle.executionEnvironment = structuredClone(computeDecision?.environment ?? bundle.runtimeTask.environment);
+  bundle.sandboxProvider = sandboxProvider;
+  if (computeDecision) {
+    await writeJson(path.join(bundle.directories.input, "compute-decision.json"), computeDecision);
+  }
+  await updateRunState(bundle, {
+    runtime: runtimeAgent.runtime,
+    agent: publicAgentRuntime(runtimeAgent),
+    sandbox: sandboxProvider,
+    image: bundle.executionEnvironment.image,
+    executionEnvironment: bundle.executionEnvironment,
+    computeDecision: computeDecision ?? null,
+  });
+  return bundle;
+}
+
+export async function finalizeReproduction({
+  bundle,
+  validation,
+  attempts,
+  timedOut = false,
+  sandboxImageIdentity = null,
+  cloudExecution = null,
+}) {
+  bundle.sandboxImageIdentity = sandboxImageIdentity;
+  await ensureFinalWorkspaceCapture(bundle);
+  const usage = await readAgentUsage(path.join(bundle.directories.execution, "trace.jsonl"), {
+    runtimeHome: bundle.directories.runtimeHome,
+    model: bundle.runtimeAgent.model,
+  });
+  const runStatus = timedOut ? "timed_out" : validation.issues.length === 0 ? "completed" : "invalid_result";
+  await updateRunState(bundle, {
+    status: runStatus,
+    finishedAt: new Date().toISOString(),
+    attempts,
+    validationIssues: validation.issues,
+    resultRecovery: validation.recovery ?? null,
+    verificationStatus: validation.protocolVerification?.status ?? null,
+    ...(validation.executionPlanDigest ? { executionPlanDigest: validation.executionPlanDigest } : {}),
+    sandboxImageIdentity: bundle.sandboxImageIdentity,
+    cloudExecution,
+    usage,
+  });
+  const runnerAudit = await buildRunnerAudit({
+    runDirectory: bundle.directories.run,
+    runtime: bundle.runtimeAgent.runtime,
+    sandbox: bundle.sandboxProvider ?? "docker",
+  });
+  await updateRunState(bundle, {
+    runnerAudit: {
+      status: runnerAudit.audit.status,
+      auditDigest: runnerAudit.audit.auditDigest,
+      captureBoundary: runnerAudit.audit.captureBoundary,
+      commandRecordCount: runnerAudit.audit.commandRecordCount,
+    },
+  });
+  if (validation.issues.length > 0) {
+    throw new CiteArkError(`最终结果未通过协议校验：\n- ${validation.issues.join("\n- ")}`, { exitCode: 2 });
+  }
+  return { dryRun: false, bundle, runStatus, validation, attempts, runnerAudit };
+}
+
+/**
+ * Preserve an honest execution record when semantic retries are exhausted but
+ * the remaining problem is the Agent's result envelope. This never creates a
+ * metric or success verdict; the normal verifier will classify it as
+ * inconclusive from a platform-authored failure record.
+ */
+export async function recoverInvalidExecutionResult({
+  bundle,
+  validation,
+  attempts,
+  timedOut = false,
+}) {
+  if (
+    validation.issues.length === 0
+    || bundle.runtimeTask?.kind !== "citeark.execution-contract"
+  ) {
+    return validation;
+  }
+  const evidencePath = "citeark-execution-failure.json";
+  const originalIssues = validation.issues.map((issue) => String(issue));
+  let rejectedPlan = null;
+  if (hasResearchWorkspace(bundle.runtimeTask)) {
+    try { await resolveResearchPlan(bundle.runtimeTask, bundle.directories.output); }
+    catch {
+      const filename = path.join(bundle.directories.output, PLAN_FILE);
+      const stat = await lstat(filename).catch(() => null);
+      if (stat?.isFile()) {
+        rejectedPlan = "rejected-research-plan.json";
+        await rename(filename, path.join(bundle.directories.output, rejectedPlan));
+      }
+      if (!stat || stat.isFile()) {
+        const fallback = initialResearchPlan(bundle.runtimeTask);
+        fallback.reason = "Platform failure-envelope recovery after invalid plan; no scientific success is asserted. See citeark-execution-failure.json.";
+        await writeJson(filename, fallback);
+      }
+    }
+  }
+  await writeJson(
+    path.join(bundle.directories.output, evidencePath),
+    redactSensitive({
+      schemaVersion: "1.0",
+      kind: "citeark.execution-failure",
+      runId: bundle.runId,
+      contractDigest: bundle.runtimeTask.contractDigest,
+      timedOut,
+      attempts,
+      resultValidationIssues: originalIssues,
+      recordedAt: new Date().toISOString(),
+    }),
+  );
+
+  const submitted = validation.result && typeof validation.result === "object"
+    ? validation.result
+    : {};
+  const submittedExperiment = submitted.experiment && typeof submitted.experiment === "object"
+    ? submitted.experiment
+    : {};
+  const commands = Array.isArray(submittedExperiment.commands)
+    ? submittedExperiment.commands.filter(
+        (command) => typeof command === "string" && command.trim(),
+      )
+    : [];
+  const reason = timedOut
+    ? "The execution exhausted its time budget before producing a valid evidence envelope."
+    : "The execution did not produce a valid evidence envelope after the available semantic repair attempts.";
+  const diagnosis = [
+    typeof submitted.diagnosis === "string" ? submitted.diagnosis.trim() : "",
+    "CiteArk preserved this run as an honest failed execution instead of discarding the paper-level workflow because of result-envelope errors.",
+    `Authoritative validation issues: ${originalIssues.join("; ")}`,
+  ].filter(Boolean).join("\n\n");
+  await writeJson(
+    path.join(bundle.directories.output, "result.json"),
+    redactSensitive({
+      schemaVersion: "1.0",
+      execution: {
+        status: "failed",
+        summary: reason,
+        failure: {
+          category: timedOut ? "timeout" : "execution_error",
+          stage: "unknown",
+          retryable: false,
+          reason: `${reason} Fix the listed submission errors using preserved evidence; do not start another experiment attempt for this envelope.`,
+        },
+      },
+      ...(bundle.runtimeTask.protocol?.preflight ? {
+        preflight: {
+          source: "platform_recovery",
+          status: "failed",
+          evidencePath,
+          checks: (bundle.runtimeTask.protocol.preflight.checks ?? []).map((check) => ({
+            id: check.id,
+            status: "failed",
+            detail: "The Agent did not submit a protocol-valid preflight record; see the platform recovery evidence.",
+          })),
+        },
+      } : {}),
+      experiment: {
+        commands,
+        entrypoint: typeof bundle.runtimeTask.protocol?.entrypoint === "string"
+          ? bundle.runtimeTask.protocol.entrypoint
+          : null,
+        checkpoint: typeof submittedExperiment.checkpoint === "string"
+          ? submittedExperiment.checkpoint
+          : null,
+      },
+      codeChanges: [],
+      evidence: [{
+        path: evidencePath,
+        description: "CiteArk platform record of execution attempts and result-envelope validation failures",
+      }, ...(rejectedPlan ? [{ path: rejectedPlan, description: "Rejected Agent plan retained without promoting its interpretation" }] : [])],
+      outputs: [],
+      limitations: [
+        "No trustworthy claim metric is asserted by this conservative recovery record.",
+        "Agent-declared evidence and outputs were not promoted because their final envelope did not pass authoritative validation.",
+      ],
+      diagnosis,
+    }),
+  );
+  const recovered = await validateResultFile(
+    path.join(bundle.directories.output, "result.json"),
+    bundle.runtimeTask,
+    bundle.directories.output,
+  );
+  return {
+    ...recovered,
+    recovery: {
+      kind: "conservative-failure-envelope",
+      evidencePath,
+      originalValidationIssues: redactSensitive(originalIssues),
+    },
+  };
+}

package/src/reproduction/plan.mjs

@@ -0,0 +1,132 @@
+import path from "node:path";
+import { cp, lstat, mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { validateEvidenceParserDescriptor } from "../evidence/parser-registry.mjs";
+import { CiteArkError, pathExists, sha256Value, writeJson } from "../util.mjs";
+import { hasResearchWorkspace } from "./workspace-mode.mjs";
+
+export const PLAN_FILE = "research-plan.json";
+
+// Stage the same implementation used by the coordinator, not a second schema
+// validator that can disagree with it. All dependencies here use Node builtins.
+export async function stageResearchPlanTools(inputDirectory) {
+  for (const relative of ["scripts/run-research-plan.mjs", "src/reproduction/plan.mjs", "src/reproduction/workspace-mode.mjs", "src/reproduction/evidence-feedback.mjs",
+    "src/util.mjs", "src/evidence/parser-registry.mjs", "src/evidence/parsers"]) {
+    const destination = path.join(inputDirectory, "runtime-tools", relative);
+    await mkdir(path.dirname(destination), { recursive: true });
+    await cp(new URL(`../../${relative}`, import.meta.url), destination, { recursive: true });
+  }
+  await writeFile(path.join(inputDirectory, "run-research-plan.mjs"),
+    'import "./runtime-tools/scripts/run-research-plan.mjs";\n');
+}
+
+export function initialResearchPlan(contract) {
+  return {
+    schemaVersion: "1.0",
+    baseContractDigest: contract.contractDigest,
+    protocol: structuredClone(contract.protocol),
+    measurements: structuredClone(contract.measurements),
+    reason: "Initial plan; verify its interpretation against the source materials before execution.",
+    sources: [],
+  };
+}
+
+export async function initializeResearchPlan(contract, outputDirectory) {
+  if (!hasResearchWorkspace(contract)) return;
+  const filename = path.join(outputDirectory, PLAN_FILE);
+  // Recovery must retain the Agent's plan, including an unfinished edit.
+  if (!(await pathExists(filename))) await writeJson(filename, initialResearchPlan(contract));
+}
+
+/** Resolve an execution view without rewriting the signed input contract. */
+export async function resolveResearchPlan(contract, outputDirectory) {
+  if (!hasResearchWorkspace(contract)) return contract;
+  const filename = path.join(outputDirectory, PLAN_FILE);
+  const stat = await lstat(filename);
+  if (!stat.isFile()) throw new CiteArkError("research-plan.json must be a regular file");
+  const plan = JSON.parse(await readFile(filename, "utf8"));
+  if (!plan || typeof plan !== "object" || Array.isArray(plan)) {
+    throw new CiteArkError("Research plan invalid: research-plan.json must be an object");
+  }
+  const issues = [];
+  if (plan.schemaVersion !== "1.0" || plan.baseContractDigest !== contract.contractDigest) issues.push("plan must reference the original contract");
+  if (!plan.protocol || typeof plan.protocol.objective !== "string" || !plan.protocol.objective.trim()) issues.push("plan.protocol.objective is required");
+  if (typeof plan.reason !== "string" || !plan.reason.trim() || !Array.isArray(plan.sources)) issues.push("plan reason and sources are required");
+  const measurements = Array.isArray(plan.measurements) ? plan.measurements : [];
+  if (!Array.isArray(plan.measurements)) issues.push("plan.measurements must be an array");
+  const goals = contract.workspacePlan.measurements;
+  const ids = measurements.map((item) => item?.measurementId);
+  if (new Set(ids).size !== ids.length) issues.push("plan measurement IDs must be unique");
+  for (const original of contract.measurements) {
+    if (!ids.includes(original.measurementId)) issues.push(`retain assigned measurement ${original.measurementId}; report missing evidence rather than deleting the goal`);
+  }
+  for (const measurement of measurements) {
+    if (!measurement || typeof measurement !== "object") {
+      issues.push("each plan measurement must be an object");
+      continue;
+    }
+    const goal = goals.find((item) => item.measurementId === measurement.measurementId);
+    if (!goal) issues.push(`measurement is outside the assigned claim: ${measurement.measurementId}`);
+    if (typeof measurement.metric !== "string" || typeof measurement.unit !== "string") issues.push("measurement metric and unit are required");
+    issues.push(...validateEvidenceParserDescriptor(measurement.parser, measurement)
+      .map((issue) => `measurements[${measurement.measurementId}].parser: ${issue}`));
+  }
+  const changed = sha256Value(plan.protocol) !== sha256Value(contract.protocol)
+    || sha256Value(measurements) !== sha256Value(contract.measurements);
+  if (changed && Array.isArray(plan.sources) && !plan.sources.some((source) =>
+    typeof source === "string" ? source.trim()
+      : source && typeof source === "object" && !Array.isArray(source)
+        && typeof source.sourceId === "string" && source.sourceId.trim()
+        && typeof source.locator === "string" && source.locator.trim())) {
+    issues.push('plan.sources needs a nonempty locator string or {"sourceId":"paper","locator":"Section / table / file path"} for a revised interpretation');
+  }
+  if (issues.length) throw new CiteArkError(`Research plan invalid:\n- ${issues.join("\n- ")}`);
+  // Resource limits belong to the runner, not the editable interpretation.
+  const protocol = { ...plan.protocol, executionMode: contract.protocol.executionMode };
+  if (contract.protocol.preflight && protocol.preflight) {
+    protocol.preflight = { ...protocol.preflight,
+      maxMinutes: contract.protocol.preflight.maxMinutes };
+  }
+  const uncoveredMeasurementIds = contract.research.claimMeasurementIds.filter((id) => !ids.includes(id));
+  return {
+    ...contract,
+    protocol,
+    measurements,
+    research: { ...contract.research, measurementIds: ids, uncoveredMeasurementIds,
+      claimCoverage: uncoveredMeasurementIds.length ? "partial" : "complete" },
+    executionPlan: {
+      digest: `sha256:${sha256Value(plan)}`,
+      changed,
+      plan,
+      originalProtocol: contract.protocol,
+      originalMeasurements: contract.measurements,
+    },
+  };
+}
+
+export async function planEvidencePaths(outputDirectory) {
+  const files = [PLAN_FILE];
+  if (await pathExists(path.join(outputDirectory, "cpu-preparation.json"))) files.push("cpu-preparation.json");
+  const phases = path.join(outputDirectory, "phase-history");
+  if (await pathExists(phases)) {
+    if (!(await lstat(phases)).isDirectory()) throw new CiteArkError("phase-history must be a directory");
+    for (const name of await readdir(phases)) {
+      if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+      const receipt = path.join(phases, name);
+      if (!(await lstat(receipt)).isFile()) throw new CiteArkError("phase receipt must be a regular file");
+      files.push(`phase-history/${name}`);
+    }
+  }
+  const directory = path.join(outputDirectory, "plan-history");
+  if (await pathExists(directory)) {
+    if (!(await lstat(directory)).isDirectory()) throw new CiteArkError("plan-history must be a directory");
+    for (const name of await readdir(directory)) {
+      if (!/^[a-f0-9]{64}\.json$/.test(name)) continue;
+      const filename = path.join(directory, name);
+      if (!(await lstat(filename)).isFile()) throw new CiteArkError("plan snapshot must be a regular file");
+      const snapshot = JSON.parse(await readFile(filename, "utf8"));
+      if (`${sha256Value(snapshot)}.json` !== name) throw new CiteArkError("plan snapshot digest mismatch");
+      files.push(`plan-history/${name}`);
+    }
+  }
+  return files;
+}

package/src/reproduction/prompts.mjs

@@ -0,0 +1,70 @@
+import { RESUME_HANDOFF_PROMPT } from "../deployment/handoff.mjs";
+import { hasResearchWorkspace } from "./workspace-mode.mjs";
+import { agentPlansExecution } from "../contracts/execution-mode.mjs";
+
+export function initialReproductionPrompt(bundle) {
+  if (bundle.deploymentHandoff) return RESUME_HANDOFF_PROMPT;
+  if (hasResearchWorkspace(bundle.runtimeTask)) return [
+    `Run ID: ${bundle.runId}`,
+    "Read /job/input/agent-instructions.md and /job/output/research-plan.json. Complete the assigned claim using the persistent research workspace. The initial scientific interpretation is revisable, with source-grounded reasons and retained plan snapshots.",
+    "When workspacePlan.sourceInventory is present, read its source context, including qualitative findings, negative results, relations and ambiguities. Reopen the referenced original paper and fixed code where needed. The preparation plan is an initial interpretation: investigate inputs and define or revise comparisons and decision rules with source-grounded reasons before expensive execution. Preserve every original source claim and reported value; do not silently drop hard findings or turn a source statement into observed evidence. Context outside the assigned measurement scope does not authorize new experiments; retain relevant unresolved findings in progress.md and result limitations for assessment.",
+    "Task measurements are assigned to this run; workspacePlan.measurements lists the allowed scope; on graded tasks it is restricted to the assigned experiment. Finish assigned work first, then fill feasible gaps using existing evidence or justified work within the same budget. Use the current plan for execution and evidence bindings. Correct known source-resolvable defects before delivery, preserve valid raw outputs and negative results, and never reset the cumulative budget or silently replace the original goal.",
+  ].join("\n");
+  const agentPlanned = agentPlansExecution(bundle.runtimeTask?.protocol);
+  const executionStrategy = agentPlanned
+    ? [
+        "This contract uses protocol.executionMode=agent_planned. The scientific objective, repository identity, measurement dimensions, aggregation, parser bindings, and resource ceiling are immutable; the concrete shell command is not.",
+        "Treat protocol.entrypoint as a grounded starting point. Inspect the fixed implementation, run small probes, and choose or revise the concrete command, batching, helper scripts, and evidence adapters needed to satisfy protocol.objective efficiently. Record the decisive commands and every helper as execution evidence. Do not change the scientific scope to make the run easier.",
+      ]
+    : [
+        "This legacy contract uses fixed_entrypoint semantics. Treat protocol.entrypoint as immutable. If it is a placeholder or embeds a reported result, fail closed as protocol_ambiguous instead of inventing a replacement scientific command.",
+        "Capture the complete stdout and stderr of the fixed entrypoint on its first successful full run. Group compound commands before applying tee or redirection, and do not rerun an expensive successful entrypoint merely to repair a logging wrapper.",
+      ];
+  return [
+    `Run ID: ${bundle.runId}`,
+    "Read /job/input/task.json and complete the scientific reproduction autonomously.",
+    "If /job/input/compute-decision.json exists, treat its environment as the actual allocated compute and task.json as the immutable scientific contract.",
+    "Inspect /job/input/dataset-source-registry.json for platform-observed candidate transports, but verify every selected archive at runtime and preserve an acquisition manifest; registry confidence is not a scientific verdict.",
+    "Inspect /job/assets, /job/runtime-cache, and /job/runtime-venv for optional bytes prepared by an earlier low-cost cache phase. Reuse them only when useful; missing, partial, or incompatible cache content is not a blocker. You retain full authority to ignore it, download from the original declared URLs, choose another paper-grounded transport, and replace task-local dependencies.",
+    "In legacy contracts, asset.acquisition.requiredPaths is a selective-download hint and may list alternative formats together. Do not require every pattern to exist. Determine which concrete files the real implementation needs, record any unmatched hints, and verify the selected files during preflight.",
+    "Treat transient public-download failures as resumable execution work. Create the acquisition manifest before a large archive or checkpoint download, write to an atomic temporary file under a checkpointed root, use redirects plus bounded all-error retries and resume support (for curl: --fail --location --retry 8 --retry-all-errors --retry-delay 2 --continue-at -), and verify size and digest before promotion. One 5xx or timeout must not end the task; after repeated failures, try a materially distinct paper-grounded public transport and record both attempts without claiming unverified equivalence. For a failing public Hugging Face resolve URL, the identical owner/repository/revision/path under https://hf-mirror.com is a candidate transport only and must pass content-identity and checkpoint-format verification against the declared asset.",
+    "The repository is ready at /job/workspace/repository.",
+    "Before execution, make a checklist from every measurement's dimensions, aggregation, repetition or seed schedule, hardware scope, and parser evidence path; preserve that exact scientific scope.",
+    "For every deterministic evidence adapter, write down the declared metric equation and unit before coding, then trace each operand to raw outputs from the required scientific commands. Never hardcode observed arrays or checkpoint/log values into adapter source, and never substitute a conveniently available statistic such as a minimum for a declared ratio, mean, percentage, or cross-command comparison.",
+    "A smoke test, synthetic carrier, one-sample round trip, structural invariant, or configuration calculation cannot be promoted into a paper-reported full-dataset metric. If the contract binds a reduced run to a broader dataset, sample-count, split, repetition, aggregation, or evaluator scope, fail closed as protocol_ambiguous instead of emitting a convenient scalar.",
+    ...executionStrategy,
+    "Do not infer protocol equivalence from a similar model name or architecture. Audit the exact checkpoint/model, preprocessing and feature construction, dataset version and split, label mapping, training objective, optimizer, evaluation implementation, repetitions, aggregation, and hardware-sensitive metrics against the immutable contract.",
+    "For checkpoint evaluation, training history is provenance rather than required computation: run fresh full evaluation of the fixed model with its controls. Missing weights do not authorize retraining a replacement. Do not convert an explicitly assigned training-process question into final-weight evaluation; report a contract mismatch for replanning.",
+    "Named model variants are protocol inputs, not presentation labels. Trace each dimensions.model_variant to the exact function, branch, checkpoint, and command it selects; an unused selector, two names mapped to the same code path, or duplicated raw output under different filenames must fail preflight instead of being reported as two measurements.",
+    "Treat task.json.protocol.preflight as a hard phase boundary and bounded repair phase: write its declared evidence file, create an isolated locked environment when needed, repair invalid operational probes, and pass every runtime, dependency, required-asset, entrypoint, parser, and smoke-path check before starting full training or evaluation. Required public_unverified assets must be acquired from their sourceUrls or exact registryDatasetId and identity-verified; an initially empty /job/assets directory is work to perform, not proof that the asset is unavailable. Let resumable acquisition and a still-progressing locked dependency install use the declared preflight budget instead of imposing a smaller ad hoc timeout.",
+    "For every required dataset, complete the dataset_loader preflight with the real evaluator loader: resolve the declared configuration and split, read representative rows, and verify schema and identity before downloading a large checkpoint or starting full evaluation. A package import, HTTP reachability probe, or dataset-card request is not enough.",
+    "For a hardware-sensitive measurement, protocol.benchmark is immutable scientific scope. Verify batch size, dtype, warmup count, timed iteration count, timer, device synchronization, input construction, and every exact implementation callable before timing. Do not guess a missing comparator or benchmark condition during execution; report protocol_ambiguous so the Research Plan can be repaired.",
+    "For dependency repair, inspect the preinstalled baseline and /opt/citeark/wheels before downloading or building packages. The baseline saves downloads; it is not a version policy. Inside /job/runtime-venv you may upgrade, downgrade, or replace any Python package when repository metadata, package metadata, a known compatibility boundary, or a direct preflight gives a concrete reason. Record the change and test the resulting stack. The fixed Rust/Cargo toolchain is already present, so do not invoke rustup.",
+    "No global PIP_CONSTRAINT or UV_CONSTRAINT should restrict task packages. If a repair changes Torch/CUDA or another major numerical stack, verify imports, device availability, ABI-sensitive operators, and the repository's real entrypoint before scientific execution; this is a validation obligation, not a prohibition.",
+    "Before corpus-scale execution, verify that the chosen portable enumerator resolves exactly the contract-declared sample count and unique identities. POSIX `sh` does not implement recursive `**` globbing; repair an agent-planned command that depends on it, and fail closed only when a fixed_entrypoint contract cannot preserve scope.",
+    "Run a representative duration probe after assets and runtime are ready. Preserve the timing, allocated device, workload extrapolation, contract timeout, and evidence-writing reserve. For agent_planned execution, improve orchestration or batching while preserving scope when the first strategy does not fit; for fixed_entrypoint execution, fail preflight rather than changing the command. A checkpoint-load or one-item smoke test is not throughput evidence.",
+    "If the duration probe predicts that a decisive command will outlive the shell tool's default per-command timeout, set an explicit tool timeout that covers the extrapolated run within the remaining ledger, or launch one checkpoint-safe background process with its PID and complete log under /job/workspace or /job/output and poll it. Before retrying, inspect the prior PID, process state, log, and output; never launch a duplicate while the earlier command may still be alive. A shell tool timeout is not a scientific timeout and must not kill an otherwise viable full evaluation.",
+    "Repository identity is fixed in task.json.repository and runner-owned audit; /job/input/repository-identity.json is intentionally unavailable during execution and must never be required. An agent-planned helper may call fixed official functions or independently implement a declared CiteArk reconstruction, but it must preserve provenance and scientific scope.",
+    "Use the available uv and managed Python 3.12 baseline for repositories that declare them. Stop with an honest failed or partial result only after materially distinct bounded setup repairs are exhausted or a genuine private/unverifiable asset blocks progress; a preflight result is never the scientific measurement.",
+    "If the observed result is surprising, audit implementation and protocol comparability once using the existing evidence before interpreting it. Never change the claim, reported target, tolerance, split, metric, or conclusion to make the run look successful; record the concrete mismatch or failure when the contract cannot be satisfied.",
+    "Write all deliverables under /job/output and finish by writing /job/output/result.json.",
+    "As soon as the decisive evidence and a schema-valid result.json are stable, stop the task instead of continuing optional exploration.",
+  ].join("\n");
+}
+
+export function retryReproductionPrompt(validationIssues, task) {
+  if (hasResearchWorkspace(task)) return [
+    "The submitted research plan or result needs correction:",
+    ...validationIssues.map((issue) => `- ${issue}`),
+    "Continue from research-plan.json, progress.md and the existing evidence. Repair the listed defects within the remaining cumulative budget. You may correct the scientific interpretation with sources; preserve the original goals and prior results. Reuse successful computation, record the final plan using run-research-plan.mjs, then write a valid result.json. Do not seek a favorable number or restart completed experiments merely to repair an envelope.",
+  ].join("\n");
+  return [
+    "CiteArk validated the submitted result and found protocol errors:",
+    ...validationIssues.map((issue) => `- ${issue}`),
+    "Inspect the existing result and evidence first. Reuse already-successful experiment outputs and parser inputs; repair only the listed envelope defects with the minimum necessary change.",
+    "Do not rerun an expensive experiment, overwrite valid parser evidence, or reinterpret a completed scientific run unless a listed validation issue proves that evidence is unusable.",
+    "After rewriting /job/output/result.json, verify every referenced path and stop immediately once the listed defects are resolved.",
+    "Do not change scientific conclusions merely to satisfy validation.",
+    "Do not replace a failed or mismatching condition with an easier model, split, preprocessing path, seed count, or metric. If the immutable contract itself is infeasible, preserve the evidence and report the blocker instead of silently changing the question.",
+  ].join("\n");
+}

package/src/reproduction/runner.mjs

@@ -0,0 +1,188 @@
+import { saveRunRecovery } from '../compute/coordinator-recovery.mjs';
+import { stageExecutionHandoff } from "../deployment/handoff.mjs";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+import { updateRunState } from "../job.mjs";
+import { previewEgressProxy, startEgressProxy } from "../network/egress-proxy.mjs";
+import {
+  previewProviderSession,
+  startProviderSession,
+} from "../provider/relay.mjs";
+import { buildAgentInvocation } from "../runtime/index.mjs";
+import {
+  assertLocalRunStopped, buildDockerRun,
+  inspectDockerImage,
+  requireRuntimeCredentials,
+  runDockerInvocation,
+  writeInvocation,
+} from "../sandbox/docker.mjs";
+import {
+  prepareReproduction,
+} from "./lifecycle.mjs";
+import { agentWorkloadMetadata } from "../workloads/definition.mjs";
+import { createAutonomousReproductionWorkload } from "../workloads/reproduction.mjs";
+
+export async function executeReproduction({
+  taskPath,
+  referenceMaterialsPath,
+  handoff,
+  localEnvironment,
+  localPreflight,
+  runsDirectory,
+  imageOverride,
+  repositoryOverride,
+  paperOverride,
+  computeDecision,
+  runId,
+  agentRuntime,
+  dryRun = false,
+  progress = () => {},
+}) {
+  const bundle = await prepareReproduction({
+    taskPath,
+    referenceMaterialsPath,
+    runsDirectory,
+    runId,
+    imageOverride,
+    repositoryOverride,
+    paperOverride,
+    computeDecision,
+    agentRuntime,
+    requireApi: !dryRun,
+    sandboxProvider: "docker",
+  });
+  if (handoff) await stageExecutionHandoff(bundle, handoff);
+  if (handoff && localEnvironment) {
+    bundle.executionEnvironment = structuredClone(localEnvironment);
+    bundle.runtimeTask.environment = structuredClone(localEnvironment);
+    const { writeJson } = await import('../util.mjs');
+    await writeJson(path.join(bundle.directories.input, 'task.json'), bundle.runtimeTask);
+    await writeJson(path.join(bundle.directories.input, 'local-environment.json'), { environment: localEnvironment, preflight: localPreflight });
+    await updateRunState(bundle, { executionEnvironment: localEnvironment, localPreflight });
+  }
+  const workload = createAutonomousReproductionWorkload();
+  await updateRunState(bundle, agentWorkloadMetadata(workload));
+  const runtimeAgent = bundle.runtimeAgent;
+  const attempts = bundle.state.attempts ?? [];
+  const firstAttempt = bundle.restored && bundle.state.status !== "prepared" ? Math.max(1, ...attempts.map(a => a.attempt)) + 1 : 1;
+  await saveRunRecovery(bundle, async () => {});
+  let validation = { result: null, issues: ["尚未运行 Agent"], protocolVerification: null };
+  if (!dryRun) { await assertLocalRunStopped(bundle); requireRuntimeCredentials(runtimeAgent); }
+  const providerSession = dryRun
+    ? previewProviderSession(runtimeAgent)
+    : await startProviderSession(runtimeAgent, {
+        correlation: { runId: bundle.runId, workload: "reproduction" },
+      });
+  let egressSession = previewEgressProxy();
+
+  try {
+  if (!dryRun) egressSession = await startEgressProxy();
+  const instructions = await workload.instructions(bundle);
+  if (bundle.restored && !dryRun && bundle.state.status === 'completed') {
+    const retained = await workload.validate({ bundle });
+    if (retained.issues.length === 0) return await workload.finalize({ bundle, validation: retained, attempts, timedOut: false, sandboxImageIdentity: bundle.sandboxImageIdentity });
+    throw Error('Saved completed results failed validation. The experiment was not restarted.');
+  }
+  const firstRuntimeInvocation = await buildAgentInvocation({
+    bundle,
+    attempt: firstAttempt,
+    prompt: workload.prompt({ bundle, attempt: firstAttempt, validation }),
+    instructions,
+    providerSession,
+  });
+  const firstDockerInvocation = {
+    ...buildDockerRun({
+      bundle,
+      runtimeCommand: firstRuntimeInvocation.command,
+      runtimeArgs: firstRuntimeInvocation.args,
+      attempt: firstAttempt,
+      providerSession,
+      egressSession,
+    }),
+    attempt: firstAttempt,
+  };
+  const recordedInvocations = [firstDockerInvocation];
+  await writeInvocation(bundle, recordedInvocations);
+  await mkdir(path.join(bundle.directories.execution, "prompts"), { recursive: true });
+  await writeFile(path.join(bundle.directories.execution, "prompts", `attempt-${firstAttempt}.txt`), `${firstRuntimeInvocation.prompt}\n`);
+
+  if (dryRun) {
+    await updateRunState(bundle, { status: "prepared" });
+    return { dryRun: true, bundle, invocation: firstDockerInvocation };
+  }
+
+  await updateRunState(bundle, { status: "running", startedAt: new Date().toISOString() });
+  const maxAttempts = 1 + runtimeAgent.validationRetries;
+  let timedOut = false;
+  for (let attempt = firstAttempt; attempt < firstAttempt + maxAttempts; attempt += 1) {
+    const runtimeInvocation = attempt === firstAttempt
+      ? firstRuntimeInvocation
+      : await buildAgentInvocation({
+          bundle,
+          attempt,
+          prompt: workload.prompt({ bundle, attempt, validation }),
+          instructions,
+          providerSession,
+        });
+    const dockerInvocation = attempt === firstAttempt
+      ? firstDockerInvocation
+      : {
+          ...buildDockerRun({
+            bundle,
+            runtimeCommand: runtimeInvocation.command,
+            runtimeArgs: runtimeInvocation.args,
+            attempt,
+            providerSession,
+            egressSession,
+          }),
+          attempt,
+        };
+    if (attempt > firstAttempt) {
+      recordedInvocations.push(dockerInvocation);
+      await writeInvocation(bundle, recordedInvocations);
+      await writeFile(path.join(bundle.directories.execution, "prompts", `attempt-${attempt}.txt`), `${runtimeInvocation.prompt}\n`);
+    }
+    progress(`CiteArk reproduction ${bundle.runId}: attempt ${attempt - firstAttempt + 1}/${maxAttempts}`);
+    const startedAt = new Date().toISOString();
+    const processResult = await runDockerInvocation(dockerInvocation, {
+      bundle,
+      attempt,
+      timeoutMs: bundle.executionEnvironment.timeoutMinutes * 60_000,
+    });
+    timedOut ||= processResult.timedOut;
+    attempts.push({
+      attempt,
+      startedAt,
+      finishedAt: new Date().toISOString(),
+      exitCode: processResult.code,
+      signal: processResult.signal,
+      timedOut: processResult.timedOut,
+    });
+    validation = await workload.validate({
+      bundle,
+      completionPath: path.join(bundle.directories.output, "result.json"),
+    });
+    if (validation.issues.length === 0) break;
+    if (attempt < firstAttempt + maxAttempts - 1) progress(`结果协议校验失败，继续同一 session：${validation.issues.join("；")}`);
+  }
+
+  validation = await workload.recover({
+    bundle,
+    validation,
+    attempts,
+    timedOut,
+  });
+  await writeInvocation(bundle, recordedInvocations);
+  return await workload.finalize({
+    bundle,
+    validation,
+    attempts,
+    timedOut,
+    sandboxImageIdentity: await inspectDockerImage(bundle.executionEnvironment.image),
+  });
+  } finally {
+    await saveRunRecovery(bundle, async () => {});
+    await Promise.all([providerSession.close(), egressSession.close()]);
+  }
+}