@citeark/agent 0.3.20

package/src/cli.mjs

@@ -0,0 +1,1146 @@
+#!/usr/bin/env node
+
+import { deployLocally, publishLocalCap } from "./deployment/local.mjs";
+import { setupLocalRuntime } from "./deployment/environment.mjs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
+import { cp, mkdtemp, mkdir, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assemblePaper2AgentCompilationCap } from "./adapters/paper2agent.mjs";
+import {
+  packCap,
+  verifyCapArchive,
+} from "./cap/v2/archive.mjs";
+import { assembleResearchCompilationCap } from "./cap/v2/compilation-artifact.mjs";
+import { verifyCapDirectory } from "./cap/v2/verify.mjs";
+import { AutoDlProClient } from "./autodl/client.mjs";
+import { AutoDlSshClient, parseAutoDlSshConnection } from "./autodl/ssh.mjs";
+import {
+  ASSET_QUALIFICATION_BOUNDARY,
+  loadAssetQualificationContext,
+  planAssetQualification,
+  probeAssetQualification,
+  verifyAssetQualification,
+} from "./assets/qualification.mjs";
+import { loadComputeCatalog, loadComputePolicy } from "./compute/catalog.mjs";
+import { loadComputeDecision, scheduleCompute } from "./compute/scheduler.mjs";
+import { executeScheduledReproduction } from "./compute/executor-router.mjs";
+import { createExecutionContract, loadExecutionContract } from "./contracts/execution-contract.mjs";
+import { startDashboardServer } from "./dashboard/server.mjs";
+import { listEvidenceParsers, parseContractEvidence } from "./evidence/registry.mjs";
+import {
+  loadAndNormalizeTask,
+  validateResultFile,
+} from "./protocol.mjs";
+import { executeFullPipeline } from "./pipeline/orchestrator.mjs";
+import { runResearchCompiler } from "./research/compiler.mjs";
+import { loadResearchStructure, normalizeResearchFile } from "./research/structure.mjs";
+import { primaryMetric } from "./records/views.mjs";
+import { dockerDoctor } from "./sandbox/docker.mjs";
+import { CiteArkError, createRunId, shellQuote, writeJson } from "./util.mjs";
+
+const PACKAGE_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const VERSION = JSON.parse(readFileSync(path.join(PACKAGE_ROOT, "package.json"), "utf8")).version;
+
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) await bootstrap().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\nCiteArk Agent: ${message}`);
+  process.exitCode = error?.exitCode ?? 1;
+});
+
+async function bootstrap() {
+  loadLocalEnvironment();
+  await main();
+}
+
+function loadLocalEnvironment() {
+  if (typeof process.loadEnvFile !== "function") return;
+  const candidates = [
+    path.resolve(".env.local"),
+    path.join(PACKAGE_ROOT, ".env.local"),
+  ];
+  for (const candidate of new Set(candidates)) {
+    if (!existsSync(candidate)) continue;
+    process.loadEnvFile(candidate);
+    return;
+  }
+}
+
+export async function main(argv = process.argv.slice(2)) {
+  const [command = process.stdin.isTTY && process.stdout.isTTY ? "start" : "help", ...rest] = argv;
+  if (command === "--help" || command === "-h" || command === "help") {
+    printHelp();
+    return;
+  }
+  if (command === "--version" || command === "-v" || command === "version") {
+    console.log(VERSION);
+    return;
+  }
+  if (command === 'view') {
+    if (!rest[0]) throw Error('Usage: citeark view <workspace-directory>');
+    const filename = path.join(path.resolve(rest[0]), 'session.events.jsonl');
+    if (!process.stdin.isTTY || !process.stdout.isTTY || process.env.TERM === 'dumb') {
+      const { Transcript } = await import('./terminal/transcript.mjs');
+      const transcript = new Transcript();
+      for (const line of readFileSync(filename, 'utf8').split('\n').filter(Boolean)) transcript.add(JSON.parse(line));
+      console.log(transcript.lines(100, true).join('\n'));
+      return;
+    }
+    const { TerminalScreen } = await import('./terminal/screen.mjs');
+    const screen = new TerminalScreen({ version: VERSION }); screen.start();
+    try { await screen.view(filename); } finally { await screen.close(); }
+    return;
+  }
+  if (command === 'paper') return (await import('./research/paper-command.mjs')).paperCommand(rest, parseOptions);
+  if (command === 'session') return (await import('./workspace/jobs.mjs')).sessionCommand(rest, parseOptions);
+  if (command === 'graph') return (await import('./graph/command.mjs')).graphCommand(rest, parseOptions);
+  if (command === 'start' || (command === 'deploy' && !rest.includes('--replay'))) {
+    const { startResearch } = await import('./workspace/command.mjs');
+    return startResearch(rest, { parseOptions, agentEntryOptions, gcpEntryOptions, autoDlEntryOptions, agentRuntimeOptions, executorOptions });
+  }
+  if (command === 'deploy') return deployCommand(rest.filter(value => value !== '--replay'));
+  if (command === "handoff") {
+    const options = parseOptions(rest, { "--cap": { type: "string", required: true },
+      "--research-cap": { type: "string" }, "--output": { type: "string", required: true },
+      "--model": { type: "string", required: true }, "--effort": { type: "string", default: "high" },
+      "--signing-key": { type: "string" } });
+    const { prepareHistoricalHandoff } = await import('./deployment/prepare.mjs');
+    console.log(JSON.stringify(await prepareHistoricalHandoff({ capPath: options['--cap'], researchCapPath: options['--research-cap'],
+      directory: path.resolve(options['--output']), model: options['--model'], effort: options['--effort'], signingKeyPath: options['--signing-key'] }), null, 2));
+    return;
+  }
+  if (command === "setup") {
+    const options = parseOptions(rest, { "--gpu": { type: "boolean", default: false } });
+    console.log(JSON.stringify(await setupLocalRuntime({ gpu: options["--gpu"] }), null, 2));
+    return;
+  }
+  if (command === "publish") return await publishCommand(rest);
+  if (command === "run") return await runCommand(rest);
+  if (command === "compile") return await compileCommand(rest);
+  if (command === "validate") return await validateCommand(rest);
+  if (command === "research") return await researchCommand(rest);
+  if (command === "contract") return await contractCommand(rest);
+  if (command === 'model' || command === 'compute' && rest[0] !== 'plan') {
+    return (await import('./settings/command.mjs')).settingsCommand(command, rest, parseOptions);
+  }
+  if (command === "compute") return await computeCommand(rest);
+  if (command === "assets") return await assetsCommand(rest);
+  if (command === "evidence") return await evidenceCommand(rest);
+  if (command === "pipeline") return await pipelineCommand(rest);
+  if (command === "cap") return await capCommand(rest);
+  if (command === "parsers") return parsersCommand();
+  if (command === "doctor") return await doctorCommand(rest);
+  if (command === "dashboard") return await dashboardCommand(rest);
+  if (command === "autodl") return await autoDlCommand(rest);
+  if (command === "init") return await initCommand(rest);
+  throw new CiteArkError(`Unknown command: ${command}\nRun citeark --help for usage.`);
+}
+
+async function deployCommand(argv) {
+  const reference = argv[0] && !argv[0].startsWith('-') ? argv.shift() : null;
+  const optionalAgent = Object.fromEntries(Object.entries(agentEntryOptions()).map(([key, value]) => [key, { ...value, required: false }]));
+  const options = parseOptions(argv, { ...optionalAgent,
+    "--repository-id": { type: "string" }, "--run": { type: "string" }, "--cap": { type: "string" },
+    "--platform": { type: "string", default: "https://citeark.co" },
+    "--work-dir": { type: "string" }, "--image": { type: "string" },
+    "--device": { type: "string", default: "auto" }, "--non-interactive": { type: "boolean", default: false },
+    "--signing-key": { type: "string" }, "--dry-run": { type: "boolean", default: false },
+  });
+  if ([reference, options['--repository-id'], options['--cap']].filter(Boolean).length !== 1) {
+    throw Error('Provide exactly one paper ID, --repository-id, or --cap.');
+  }
+  if (Number(process.versions.node.split('.')[0]) < 22) throw Error('Install Node.js 22 or later: https://nodejs.org/');
+  const dryRun = options['--dry-run'];
+  const interactive = !dryRun && !options['--non-interactive'] && Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  const { createTerminalPrompter, cancelled } = await import('./deployment/terminal.mjs');
+  const { fetchDeployment, chooseDeployment, readLocalPreferences, writeLocalPreferences,
+    configureLocalModel, ensureGuidedEnvironment, describeDeployment } = await import('./deployment/guided.mjs');
+  const prompt = interactive ? createTerminalPrompter() : null;
+  let repositoryId = options['--repository-id'] ?? reference;
+  let route;
+  if (repositoryId) {
+    const data = await fetchDeployment(repositoryId, { baseUrl: options['--platform'] });
+    repositoryId = data.repositoryId ?? repositoryId;
+    console.log(`\nCiteArk · ${data.title ?? repositoryId}`);
+    route = await chooseDeployment(data, { runId: options['--run'], prompt });
+  }
+  if (options['--api-key'] && options['--api-key-env']) throw Error('Provide either --api-key or --api-key-env.');
+  if (options['--api-key-env'] && !process.env[options['--api-key-env']] && !dryRun) throw Error(`Environment variable ${options['--api-key-env']} is not set`);
+  const explicitRuntime = {
+    runtime: options['--agent'], apiBaseUrl: options['--api-base-url'], model: options['--model'],
+    apiKey: options['--api-key'] ?? process.env[options['--api-key-env']],
+    apiKeySource: options['--api-key-env'] ? `env:${options['--api-key-env']}` : undefined,
+    subagentModel: options['--subagent-model'],
+  };
+  let agentRuntime;
+  if (!interactive) {
+    if (!dryRun && (!explicitRuntime.apiBaseUrl || !explicitRuntime.model)) {
+      throw Error('Use an interactive terminal to configure the model, or pass --api-base-url, --model, and --api-key-env. Use --dry-run to inspect inputs.');
+    }
+    agentRuntime = agentRuntimeOptions({ ...options, '--agent': options['--agent'] ?? 'opencode',
+      '--api-base-url': options['--api-base-url'] ?? 'https://api.invalid', '--model': options['--model'] ?? 'dry-run' }, dryRun);
+  }
+  const workDirectory = options['--work-dir'] ?? path.join(process.cwd(), `citeark-${(reference ?? 'run').replace(/[^a-zA-Z0-9-]/g, '').slice(0, 40)}-${Date.now()}`);
+  const result = await deployLocally({ repositoryId, runId: route?.runId ?? options['--run'], capPath: options['--cap'],
+    baseUrl: options['--platform'], workDirectory, image: options['--image'], device: options['--device'],
+    signingKeyPath: options['--signing-key'], dryRun, agentRuntime,
+    prepareExecution: prompt ? async context => {
+      describeDeployment({ ...context, route });
+      const localPreflight = await ensureGuidedEnvironment({ ...context, prompt });
+      const configured = await configureLocalModel({ options: explicitRuntime, saved: await readLocalPreferences(), prompt });
+      console.log(`\nModel: ${configured.model}\nDirectory: ${context.directory}`);
+      console.log('This will download research materials and run experiments using your model provider.');
+      if (!await prompt.confirm('Start local reproduction?')) throw cancelled();
+      await writeLocalPreferences(configured);
+      return { agentRuntime: configured, localPreflight };
+    } : undefined,
+  });
+  console.log(result.dryRun ? `Prepared (dry run): ${result.runDirectory}` : `Signed local run: ${result.archive}\nAssessment: ${result.conclusion}`);
+  if (prompt && repositoryId && await prompt.confirm('Upload this result to CiteArk?')) {
+    const token = process.env.CITEARK_API_KEY ?? await prompt.ask('CiteArk API key (write access required; hidden)', { secret: true });
+    console.log(JSON.stringify(await publishLocalCap({ capPath: result.archive, repositoryId, baseUrl: options['--platform'], token }), null, 2));
+  }
+}
+
+async function publishCommand(argv) {
+  const options = parseOptions(argv, { "--cap": { type: "string", required: true },
+    "--repository-id": { type: "string" },
+    "--plan": { type: "string" }, "--visibility": { type: "string" },
+    "--platform": { type: "string", default: "https://citeark.co" },
+    "--token-env": { type: "string", default: "CITEARK_API_KEY" }, });
+  if (options['--plan']) await publishLocalCap({ capPath: options['--plan'], repositoryId: options['--repository-id'],
+    baseUrl: options['--platform'], token: process.env[options['--token-env']], visibility: options['--visibility'] });
+  console.log(JSON.stringify(await publishLocalCap({ capPath: options["--cap"], repositoryId: options["--repository-id"],
+    baseUrl: options["--platform"], token: process.env[options["--token-env"]], visibility: options["--visibility"] }), null, 2));
+}
+
+async function compileCommand(argv) {
+  const options = parseOptions(argv, {
+    ...agentEntryOptions(),
+    "--task": { type: "string", required: true },
+    "--runs-dir": { type: "string", default: ".citeark/compilations" },
+    "--run-id": { type: "string" },
+    "--image": { type: "string" },
+    "--cap-output": { type: "string" },
+    "--signing-key": { type: "string" },
+    "--dry-run": { type: "boolean", default: false },
+  });
+  const compilation = await runResearchCompiler({
+    taskPath: options["--task"],
+    runsDirectory: options["--runs-dir"],
+    runId: options["--run-id"],
+    imageOverride: options["--image"],
+    agentRuntime: agentRuntimeOptions(options, options["--dry-run"]),
+    dryRun: options["--dry-run"],
+  });
+  if (compilation.dryRun) {
+    console.log("CiteArk Research Compiler Run bundle prepared (dry run):");
+    console.log(`Run directory: ${compilation.bundle.directories.run}`);
+    console.log(`Command: ${compilation.invocation.printable}`);
+    return;
+  }
+  console.log("Research compilation: completed");
+  console.log(`Research: ${path.join(compilation.bundle.directories.output, "research.normalized.json")}`);
+  if (compilation.research.compilationStage === "inventory") {
+    const capDirectory = path.join(compilation.bundle.directories.run, "research-compilation-cap");
+    const built = await assembleResearchCompilationCap({
+      directory: capDirectory,
+      inventory: compilation.research,
+      compiler: {
+        id: "citeark/compiler",
+        name: "CiteArk Research Compiler",
+        version: compilation.research.provenance?.compiler,
+      },
+      runId: compilation.bundle.runId,
+      createdAt: compilation.bundle.state.finishedAt,
+      signingKeyPath: options["--signing-key"],
+    });
+    const outputPath = path.resolve(
+      options["--cap-output"]
+        ?? path.join(compilation.bundle.directories.run, "research-compilation.cap"),
+    );
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    const archive = await packCap({ directory: capDirectory, outputPath });
+    console.log(`Compilation CAP: ${archive.path}`);
+    console.log(`Compilation Artifact Digest: ${built.artifactDigest}`);
+  }
+}
+
+async function runCommand(argv) {
+  const options = parseOptions(argv, {
+    ...agentEntryOptions(),
+    ...gcpEntryOptions(),
+    ...autoDlEntryOptions(),
+    "--task": { type: "string", required: true },
+    "--runs-dir": { type: "string", default: ".citeark/runs" },
+    "--image": { type: "string" },
+    "--run-id": { type: "string" },
+    "--compute-decision": { type: "string" },
+    "--dry-run": { type: "boolean", default: false },
+  });
+
+  const computeDecision = options["--compute-decision"] ? await loadComputeDecision(options["--compute-decision"]) : null;
+  const usesRemoteSecret = new Set(["gcp-batch", "autodl-pro"])
+    .has(computeDecision?.selectedProfile?.executor);
+  const execution = await executeScheduledReproduction({
+    taskPath: options["--task"],
+    runsDirectory: options["--runs-dir"],
+    runId: options["--run-id"],
+    imageOverride: options["--image"],
+    computeDecision,
+    agentRuntime: agentRuntimeOptions(options, options["--dry-run"], { allowGcpSecret: usesRemoteSecret }),
+    executorOptions: executorOptions(options),
+    dryRun: options["--dry-run"],
+    progress: (message) => console.log(`\n${message}`),
+  });
+  if (execution.dryRun) {
+    console.log("\nCiteArk Agent Run bundle prepared (dry run):");
+    console.log(`Run ID: ${execution.bundle.runId}`);
+    console.log(`Run directory: ${execution.bundle.directories.run}`);
+    console.log(`Command: ${execution.invocation.printable}`);
+    return;
+  }
+  console.log("\nCiteArk Agent Run finished:");
+  console.log(`Status: ${execution.runStatus}`);
+  console.log("Research artifacts are generated by the full pipeline under the Research Plan CAP.");
+}
+
+async function validateCommand(argv) {
+  const options = parseOptions(argv, {
+    "--task": { type: "string", required: true },
+    "--result": { type: "string", required: true },
+    "--output-dir": { type: "string" },
+  });
+  const { task } = await loadAndNormalizeTask(options["--task"]);
+  const resultPath = path.resolve(options["--result"]);
+  const outputDirectory = path.resolve(
+    options["--output-dir"] ?? path.dirname(resultPath),
+  );
+  const validation = await validateResultFile(resultPath, task, outputDirectory);
+  if (validation.issues.length > 0) {
+    throw new CiteArkError(
+      `Result validation failed: \n- ${validation.issues.join("\n- ")}`,
+      { exitCode: 2 },
+    );
+  }
+  console.log("Result protocol: valid");
+  if (validation.protocolVerification) {
+    console.log(`Verification: ${validation.protocolVerification.status}`);
+    console.log(`Absolute difference: ${validation.protocolVerification.absoluteDifference}`);
+  } else {
+    console.log("Verification: deferred to the independent verification engine");
+  }
+}
+
+async function researchCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "validate") throw new CiteArkError("Usage: citeark research validate --input <research.json> [--output <normalized.json>]");
+  const options = parseOptions(rest, {
+    "--input": { type: "string", required: true },
+    "--output": { type: "string" },
+  });
+  const output = options["--output"] ?? options["--input"];
+  const research = await normalizeResearchFile(options["--input"], output);
+  console.log(`Research structure: valid (${research.claims.length} claims, ${research.experiments.length} experiments)`);
+  console.log(`Normalized: ${path.resolve(output)}`);
+}
+
+async function contractCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "create") throw new CiteArkError("Usage: citeark contract create --research <research.json> --claim <id> --output <contract.json> --policy <private.json> --tolerance <number>");
+  const options = parseOptions(rest, {
+    "--research": { type: "string", required: true },
+    "--claim": { type: "string", required: true },
+    "--experiment": { type: "string" },
+    "--output": { type: "string", required: true },
+    "--policy": { type: "string", required: true },
+    "--tolerance": { type: "string", required: true },
+  });
+  const { contract, policy } = await createExecutionContract({
+    researchPath: options["--research"],
+    claimId: options["--claim"],
+    experimentId: options["--experiment"],
+    outputPath: options["--output"],
+    policyPath: options["--policy"],
+    tolerance: options["--tolerance"],
+  });
+  console.log(`Execution contract: ${path.resolve(options["--output"])}`);
+  console.log(`Private policy: ${path.resolve(options["--policy"])}`);
+  console.log(`Contract digest: ${contract.contractDigest}`);
+  console.log(`Policy digest: ${policy.policyDigest}`);
+}
+
+async function computeCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "plan") throw new CiteArkError("Usage: citeark compute plan --research <research.json> --experiment <id> [--contract <contract.json>] [--catalog <catalog.json>] [--policy <policy.json>] [--profile <id>] [--output <decision.json>]");
+  const options = parseOptions(rest, {
+    "--research": { type: "string", required: true },
+    "--experiment": { type: "string", required: true },
+    "--contract": { type: "string" },
+    "--catalog": { type: "string" },
+    "--policy": { type: "string" },
+    "--profile": { type: "string" },
+    "--output": { type: "string" },
+  });
+  const [research, catalog, policy, contract] = await Promise.all([
+    loadResearchStructure(options["--research"]),
+    loadComputeCatalog(options["--catalog"]),
+    loadComputePolicy(options["--policy"]),
+    options["--contract"] ? loadExecutionContract(options["--contract"]) : null,
+  ]);
+  const experiment = research.experiments.find((item) => item.id === options["--experiment"]);
+  if (!experiment) throw new CiteArkError(`Experiment not found: ${options["--experiment"]}`);
+  const decision = await scheduleCompute({
+    experiment,
+    contract,
+    catalog,
+    policy,
+    profileOverride: options["--profile"],
+    outputPath: options["--output"],
+  });
+  console.log(`Compute class: ${decision.requirement.classification}`);
+  console.log(`Selected profile: ${decision.selectedProfile.id}`);
+  console.log(`Executor: ${decision.selectedProfile.executor}`);
+  console.log(`Estimated cost: ${decision.estimate.costUsd ?? "unknown"} USD`);
+  if (options["--output"]) console.log(`Decision: ${path.resolve(options["--output"])}`);
+}
+
+async function evidenceCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "parse") throw new CiteArkError("Usage: citeark evidence parse --contract <contract.json> --output-dir <run/output> --metrics <metrics.json>");
+  const options = parseOptions(rest, {
+    "--contract": { type: "string", required: true },
+    "--output-dir": { type: "string", required: true },
+    "--metrics": { type: "string", required: true },
+  });
+  const contract = await loadExecutionContract(options["--contract"]);
+  const { resolveResearchPlan } = await import("./reproduction/plan.mjs");
+  const effectiveContract = await resolveResearchPlan(contract, options["--output-dir"]);
+  const metrics = await parseContractEvidence({ contract: effectiveContract, outputDirectory: options["--output-dir"], metricsPath: options["--metrics"] });
+  const measurement = metrics.measurements?.[0] ?? metrics;
+  const primary = primaryMetric(metrics);
+  console.log(`Evidence parser: ${measurement.parser.id}@${measurement.parser.version}`);
+  console.log(`Primary metric: ${primary.metric}=${primary.value} ${primary.unit}`);
+}
+
+async function pipelineCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand !== "execute") throw new CiteArkError("Usage: citeark pipeline execute ...");
+  return await pipelineExecuteCommand(rest);
+}
+
+async function pipelineExecuteCommand(argv, { forcedStopAfter } = {}) {
+  const options = parseOptions(argv, {
+    ...agentEntryOptions(),
+    ...gcpEntryOptions(),
+    ...autoDlEntryOptions(),
+    "--compile-task": { type: "string" },
+    "--research": { type: "string" },
+    "--compilation": { type: "string" },
+    "--paper": { type: "string" },
+    "--claim": { type: "string" },
+    "--experiment": { type: "string" },
+    "--tolerance": { type: "string", required: true },
+    "--work-dir": { type: "string", required: true },
+    "--resume": { type: "boolean", default: false },
+    "--signing-key": { type: "string" },
+    "--compute-catalog": { type: "string" },
+    "--compute-policy": { type: "string" },
+    "--compute-profile": { type: "string" },
+    "--dataset-registry": { type: "string" },
+    "--repository": { type: "string" },
+    "--stop-after": { type: "string" },
+    "--dry-run": { type: "boolean", default: false },
+  });
+  if (forcedStopAfter && options["--stop-after"] && options["--stop-after"] !== forcedStopAfter) {
+    throw new CiteArkError(`assets prepare stops at ${forcedStopAfter}`);
+  }
+  const stopAfter = forcedStopAfter ?? options["--stop-after"];
+  const pipeline = await executeFullPipeline({
+    compileTaskPath: options["--compile-task"],
+    researchPath: options["--research"],
+    compilationArtifactPath: options["--compilation"],
+    paperPath: options["--paper"],
+    claimId: options["--claim"],
+    experimentId: options["--experiment"],
+    tolerance: options["--tolerance"],
+    workDirectory: options["--work-dir"],
+    resume: options["--resume"],
+    signingKeyPath: options["--signing-key"],
+    computeCatalogPath: options["--compute-catalog"],
+    computePolicyPath: options["--compute-policy"],
+    computeProfile: options["--compute-profile"],
+    datasetRegistryPath: options["--dataset-registry"],
+    repositoryPath: options["--repository"],
+    stopAfter,
+    agentRuntime: agentRuntimeOptions(options, options["--dry-run"], { allowGcpSecret: true }),
+    executorOptions: executorOptions(options),
+    dryRun: options["--dry-run"],
+    progress: (message) => console.log(message),
+  });
+  if (pipeline.dryRun) {
+    console.log(stopAfter === ASSET_QUALIFICATION_BOUNDARY
+      ? `Asset preparation bundle ready (dry run): ${pipeline.directories.root}`
+      : `Pipeline prepared: ${pipeline.directories.root}`);
+    if (pipeline.compilationArtifact) {
+      console.log(`Input Compilation Artifact: ${pipeline.compilationArtifact.artifactDigest}`);
+    }
+    return;
+  }
+  if (stopAfter === ASSET_QUALIFICATION_BOUNDARY) {
+    console.log("Asset checks passed");
+    console.log("Research execution not started");
+    console.log(`Plan digest: ${pipeline.qualification.planDigest}`);
+    console.log(`Manifest digest: ${pipeline.qualification.manifestDigest}`);
+    console.log(`Cache hit: ${pipeline.qualification.cacheHit}`);
+    console.log(`Checkpoint: ${pipeline.qualification.checkpointPrefix}`);
+    console.log(`Evidence: ${path.join(pipeline.directories.protocol, "asset-qualification.json")}`);
+    return;
+  }
+  console.log(`Pipeline: ${pipeline.state.status}`);
+  console.log(`Verification: ${pipeline.replay.assessment.verificationStatus}`);
+  console.log(`CAP: ${pipeline.directories.cap}`);
+  console.log(`CAP file: ${pipeline.archive.path}`);
+  console.log(`Archive SHA-256: ${pipeline.archive.sha256}`);
+}
+
+async function assetsCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "prepare") {
+    return await pipelineExecuteCommand(rest, {
+      forcedStopAfter: ASSET_QUALIFICATION_BOUNDARY,
+    });
+  }
+  if (subcommand === "verify") {
+    const options = parseOptions(rest, {
+      "--plan": { type: "string", required: true },
+      "--manifest": { type: "string", required: true },
+    });
+    const verification = await verifyAssetQualification({
+      planPath: options["--plan"],
+      manifestPath: options["--manifest"],
+    });
+    if (!verification.valid) {
+      throw new CiteArkError(`Invalid asset manifest: \n- ${verification.issues.join("\n- ")}`, {
+        exitCode: 2,
+      });
+    }
+    console.log("Asset manifest valid");
+    console.log(`Plan digest: ${verification.plan.planDigest}`);
+    console.log(`Manifest digest: ${verification.manifest.manifestDigest}`);
+    return;
+  }
+  if (!new Set(["plan", "probe"]).has(subcommand)) {
+    throw new CiteArkError("Usage: citeark assets plan|probe|prepare|verify ...");
+  }
+  const options = parseOptions(rest, {
+    "--research": { type: "string", required: true },
+    "--claim": { type: "string" },
+    "--experiment": { type: "string" },
+    "--dataset-registry": { type: "string" },
+    "--output": { type: "string" },
+  });
+  const context = await loadAssetQualificationContext({
+    researchPath: options["--research"],
+    claimId: options["--claim"],
+    experimentId: options["--experiment"],
+    datasetRegistryPath: options["--dataset-registry"],
+  });
+  if (subcommand === "plan") {
+    const { plan, failures } = planAssetQualification(context);
+    if (options["--output"]) await writeJson(options["--output"], plan);
+    console.log(`Assets: ${plan.summary.assetCount}`);
+    console.log(`Prepared assets: ${plan.summary.prepareCount}`);
+    console.log(`Streamed assets: ${plan.summary.streamCount}`);
+    console.log(`Metadata only: ${plan.summary.metadataOnlyCount}`);
+    console.log(`Over budget: ${plan.summary.blockedCount}`);
+    console.log(`Estimated download: ${plan.summary.expectedDownloadBytes} bytes`);
+    if (options["--output"]) console.log(`Plan: ${path.resolve(options["--output"])}`);
+    for (const failure of failures) console.log(`Blocked: ${failure.reasonCode} ${failure.message}`);
+    return;
+  }
+  const admission = await probeAssetQualification({
+    ...context,
+    outputPath: options["--output"],
+  });
+  console.log(`Ready targets: ${admission.summary.admittedTargetCount}/${admission.summary.targetCount}`);
+  console.log(`Blocked targets: ${admission.summary.blockedTargetCount}`);
+  console.log(`Retryable targets: ${admission.summary.retryableTargetCount}`);
+  console.log(`URL request attempts: ${admission.summary.requestAttemptCount}`);
+  if (options["--output"]) console.log(`Probe: ${path.resolve(options["--output"])}`);
+  if (admission.summary.admittedTargetCount !== admission.summary.targetCount) process.exitCode = 2;
+}
+
+async function capCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (subcommand === "import-paper2agent") {
+    const options = parseOptions(rest, {
+      "--delivery": { type: "string", required: true },
+      "--inventory": { type: "string", required: true },
+      "--paper2agent-version": { type: "string" },
+      "--run-id": { type: "string" },
+      "--signing-key": { type: "string" },
+      "--output": { type: "string", required: true },
+    });
+    const inventory = await loadResearchStructure(options["--inventory"]);
+    const temporary = await mkdtemp(path.join(os.tmpdir(), "citeark-import-paper2agent-"));
+    try {
+      const artifactDirectory = path.join(temporary, "artifact");
+      const built = await assemblePaper2AgentCompilationCap({
+        directory: artifactDirectory,
+        inventory,
+        deliveryPath: options["--delivery"],
+        paper2AgentVersion: options["--paper2agent-version"],
+        runId: options["--run-id"] ?? createRunId(),
+        signingKeyPath: options["--signing-key"],
+      });
+      const outputPath = path.resolve(options["--output"]);
+      await mkdir(path.dirname(outputPath), { recursive: true });
+      const archive = await packCap({ directory: artifactDirectory, outputPath });
+      console.log(`Paper2Agent delivery: ${built.delivery.kind}`);
+      console.log(`Compilation CAP: ${archive.path}`);
+      console.log(`Artifact Digest: ${built.artifactDigest}`);
+      return;
+    } finally {
+      await rm(temporary, { recursive: true, force: true });
+    }
+  }
+  if (subcommand === "create-compilation") {
+    const options = parseOptions(rest, {
+      "--inventory": { type: "string", required: true },
+      "--compiler-id": { type: "string", required: true },
+      "--compiler-name": { type: "string", required: true },
+      "--compiler-version": { type: "string" },
+      "--run-id": { type: "string" },
+      "--signing-key": { type: "string" },
+      "--output": { type: "string", required: true },
+    });
+    const inventory = await loadResearchStructure(options["--inventory"]);
+    const temporary = await mkdtemp(path.join(os.tmpdir(), "citeark-create-compilation-"));
+    try {
+      const built = await assembleResearchCompilationCap({
+        directory: path.join(temporary, "artifact"),
+        inventory,
+        compiler: {
+          id: options["--compiler-id"],
+          name: options["--compiler-name"],
+          version: options["--compiler-version"],
+        },
+        runId: options["--run-id"] ?? createRunId(),
+        signingKeyPath: options["--signing-key"],
+      });
+      const outputPath = path.resolve(options["--output"]);
+      await mkdir(path.dirname(outputPath), { recursive: true });
+      const archive = await packCap({
+        directory: path.join(temporary, "artifact"),
+        outputPath,
+      });
+      console.log(`Compilation CAP: ${archive.path}`);
+      console.log(`Artifact Digest: ${built.artifactDigest}`);
+      return;
+    } finally {
+      await rm(temporary, { recursive: true, force: true });
+    }
+  }
+  if (subcommand === "pack") {
+    const options = parseOptions(rest, {
+      "--dir": { type: "string", required: true },
+      "--output": { type: "string", required: true },
+    });
+    const source = path.resolve(options["--dir"]);
+    const destination = path.resolve(options["--output"]);
+    const archive = await packCap({ directory: source, outputPath: destination });
+    console.log(`CAP file: ${archive.path}`);
+    console.log(`Archive SHA-256: ${archive.sha256}`);
+    console.log(`Artifact Digest: ${archive.artifactDigest}`);
+    return;
+  }
+  if (subcommand !== "verify") {
+    throw new CiteArkError("Usage: citeark cap import-paper2agent|create-compilation|pack|verify ...");
+  }
+  const options = parseOptions(rest, {
+    "--dir": { type: "string" },
+    "--file": { type: "string" },
+  });
+  if (Boolean(options["--dir"]) === Boolean(options["--file"])) {
+    throw new CiteArkError("cap verify requires exactly one of --dir or --file");
+  }
+  const report = options["--file"]
+    ? await verifyCapArchive(path.resolve(options["--file"]))
+    : await verifyCapDirectory(path.resolve(options["--dir"]));
+  if (!report.valid) throw new CiteArkError(`CAP validation failed: \n- ${report.issues.join("\n- ")}`, { exitCode: 2 });
+  console.log("CAP: valid");
+  console.log(`Protocol: ${report.protocolVersion}`);
+  console.log(`Artifact Digest: ${report.artifactDigest}`);
+  console.log(`Profiles: ${report.manifest.profiles.join(", ")}`);
+  console.log(`Valid signatures: ${report.attestations.filter((item) => item.signatureValid && item.subjectValid).length}`);
+  if (report.archive) console.log(`Archive SHA-256: ${report.archive.sha256}`);
+}
+
+function parsersCommand() {
+  for (const parser of listEvidenceParsers()) console.log(`${parser.id}@${parser.version}`);
+}
+
+async function autoDlCommand(argv) {
+  const [subcommand, ...rest] = argv;
+  if (!new Set([
+    "list",
+    "images",
+    "status",
+    "start",
+    "stop",
+    "release",
+    "bootstrap",
+    "save-image",
+  ]).has(subcommand)) {
+    throw new CiteArkError(
+      "Usage: citeark autodl list|images|status|start|stop|release|bootstrap|save-image [--instance <uuid>] [--token-env AUTODL_API_TOKEN]",
+    );
+  }
+  const needsInstance = !new Set(["list", "images"]).has(subcommand);
+  const options = parseOptions(rest, {
+    "--instance": { type: "string", required: needsInstance },
+    "--token-env": { type: "string", default: "AUTODL_API_TOKEN" },
+    "--token-stdin": { type: "boolean", default: false },
+    "--confirm": { type: "string" },
+    "--image-name": { type: "string" },
+    "--save-as": { type: "string" },
+  });
+  const token = options["--token-stdin"]
+    ? await readSecretFromStdin()
+    : process.env[options["--token-env"]];
+  if (!token) {
+    throw new CiteArkError(
+      options["--token-stdin"]
+        ? "No AutoDL token received on stdin"
+        : `Environment variable ${options["--token-env"]} is not set`,
+    );
+  }
+  const client = new AutoDlProClient({ token });
+  const instanceUuid = options["--instance"];
+  if (subcommand === "list") {
+    const result = await client.listInstances();
+    const instances = Array.isArray(result?.list) ? result.list : [];
+    console.log(JSON.stringify(instances.map((instance) => ({
+      uuid: instance.uuid,
+      name: instance.name,
+      status: instance.status,
+      region: instance.region_name ?? instance.region_sign,
+      gpuSpecUuid: instance.gpu_spec_uuid,
+      gpuCount: instance.req_gpu_amount,
+    })), null, 2));
+    return;
+  }
+  if (subcommand === "images") {
+    const result = await client.listPrivateImages();
+    const images = Array.isArray(result?.list) ? result.list : [];
+    console.log(JSON.stringify(images.map((image) => ({
+      imageUuid: image.image_uuid,
+      name: image.name,
+      status: image.status,
+      imageSize: image.image_size,
+      createdAt: image.create_at,
+    })), null, 2));
+    return;
+  }
+  if (subcommand === "status") {
+    console.log(await client.getStatus(instanceUuid));
+    return;
+  }
+  if (subcommand === "start") {
+    await client.powerOn(instanceUuid, { startCommand: "sleep infinity" });
+    console.log(`AutoDL instance start requested: ${instanceUuid}`);
+    return;
+  }
+  if (subcommand === "stop") {
+    await client.powerOff(instanceUuid);
+    console.log(`AutoDL instance stop requested: ${instanceUuid}`);
+    return;
+  }
+  if (subcommand === "bootstrap") {
+    const connection = parseAutoDlSshConnection(
+      await client.getInstance(instanceUuid),
+    );
+    const ssh = new AutoDlSshClient(connection);
+    try {
+      await ssh.connect();
+      await Promise.all([
+        ssh.putFile(
+          path.join(PACKAGE_ROOT, "runtime", "bootstrap-autodl-runtime.sh"),
+          "/root/citeark-bootstrap-runtime.sh",
+        ),
+        ssh.putFile(
+          path.join(PACKAGE_ROOT, "docker", "claude-code", "codex-pro-relay.mjs"),
+          "/root/codex-pro-relay.mjs",
+        ),
+        ssh.putFile(
+          path.join(PACKAGE_ROOT, "runtime", "requirements-baseline.txt"),
+          "/root/citeark-requirements-baseline.txt",
+        ),
+        ssh.putFile(
+          path.join(PACKAGE_ROOT, "runtime", "create-runtime-venv.sh"),
+          "/root/citeark-create-runtime-venv.sh",
+        ),
+      ]);
+      const result = await ssh.exec(
+        "chmod 0700 /root/citeark-bootstrap-runtime.sh && /root/citeark-bootstrap-runtime.sh",
+        {
+          onStdout: (text) => process.stdout.write(text),
+          onStderr: (text) => process.stderr.write(text),
+        },
+      );
+      if (result.code !== 0) {
+        throw new CiteArkError(`AutoDL runtime initialization failed (exit code ${result.code})`);
+      }
+    } finally {
+      ssh.close();
+    }
+    if (options["--save-as"]) {
+      await ensureAutoDlInstanceStopped(client, instanceUuid);
+      const saved = await client.saveInstanceImage(instanceUuid, options["--save-as"]);
+      console.log(`AutoDL private image save submitted: ${saved?.image_uuid ?? "waiting for AutoDL image ID"}`);
+    } else {
+      console.log("AutoDL runtime ready. Save a private image or run again with --save-as.");
+    }
+    return;
+  }
+  if (subcommand === "save-image") {
+    if (!options["--image-name"]) {
+      throw new CiteArkError("save-image requires --image-name");
+    }
+    await ensureAutoDlInstanceStopped(client, instanceUuid);
+    const saved = await client.saveInstanceImage(instanceUuid, options["--image-name"]);
+    console.log(`AutoDL private image save submitted: ${saved?.image_uuid ?? "waiting for AutoDL image ID"}`);
+    return;
+  }
+  if (options["--confirm"] !== instanceUuid) {
+    throw new CiteArkError("Releasing an instance deletes its system disk. Pass the full instance UUID with --confirm.");
+  }
+  const status = String(await client.getStatus(instanceUuid)).toLowerCase();
+  if (!new Set(["stopped", "shutdown", "shutoff"]).has(status)) {
+    await client.powerOff(instanceUuid);
+    await client.waitForStatus(instanceUuid, ["stopped", "shutdown", "shutoff"]);
+  }
+  await client.release(instanceUuid);
+  console.log(`AutoDL instance released: ${instanceUuid}`);
+}
+
+async function ensureAutoDlInstanceStopped(client, instanceUuid) {
+  const status = String(await client.getStatus(instanceUuid)).trim().toLowerCase();
+  if (new Set(["stopped", "shutdown", "shutoff"]).has(status)) return;
+  await client.powerOff(instanceUuid);
+  await client.waitForStatus(instanceUuid, ["stopped", "shutdown", "shutoff"]);
+}
+
+async function readSecretFromStdin() {
+  const chunks = [];
+  let bytes = 0;
+  for await (const chunk of process.stdin) {
+    bytes += chunk.length;
+    if (bytes > 16 * 1024) throw new CiteArkError("The credential on stdin exceeds the size limit");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks).toString("utf8").trim();
+}
+
+async function doctorCommand(argv) {
+  const options = parseOptions(argv, {
+    "--image": {
+      type: "string",
+      default: "citeark-agent/runtime:cpu",
+    },
+    "--agent": { type: "string", default: "opencode" },
+  });
+  if (!new Set(["claude-code", "codex", "opencode"]).has(options["--agent"])) {
+    throw new CiteArkError("--agent must be claude-code, codex, or opencode");
+  }
+  const report = await dockerDoctor(options["--image"], options["--agent"]);
+  console.log(`Docker client: ${report.client ?? "unavailable"}`);
+  console.log(`Docker server: ${report.server ?? "unavailable"}`);
+  console.log(`Runtime image: ${report.image ?? "unavailable"}`);
+  console.log(`Agent runtime: ${options["--agent"]}`);
+  console.log(`Agent CLI: ${report.runtime ?? "unavailable"}`);
+  if (report.issues.length > 0) {
+    throw new CiteArkError(`Runtime not ready: \n- ${report.issues.join("\n- ")}`);
+  }
+  console.log("CiteArk Agent runtime: ready");
+}
+
+async function dashboardCommand(argv) {
+  const options = parseOptions(argv, {
+    "--pipelines-dir": { type: "string", default: ".citeark/pipelines" },
+    "--host": { type: "string", default: "127.0.0.1" },
+    "--port": { type: "string", default: "4310" },
+  });
+  const port = Number(options["--port"]);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    throw new CiteArkError("--port must be an integer from 0 to 65535");
+  }
+  const dashboard = await startDashboardServer({
+    pipelinesDirectory: options["--pipelines-dir"],
+    host: options["--host"],
+    port,
+  });
+  console.log("CiteArk Agent dashboard started");
+  console.log(`URL: ${dashboard.url}`);
+  console.log(`Pipeline directory: ${dashboard.pipelinesDirectory}`);
+  console.log("Press Ctrl+C to stop");
+}
+
+async function initCommand(argv) {
+  const options = parseOptions(argv, {
+    "--dir": { type: "string", default: "citeark-agent-task" },
+  });
+  const destination = path.resolve(options["--dir"]);
+  await mkdir(destination, { recursive: true });
+  await cp(
+    path.join(PACKAGE_ROOT, "examples", "toy-evaluation", "task.json"),
+    path.join(destination, "task.json"),
+  );
+  await cp(
+    path.join(PACKAGE_ROOT, "examples", "toy-evaluation", "paper.md"),
+    path.join(destination, "paper.md"),
+  );
+  await cp(
+    path.join(PACKAGE_ROOT, "examples", "toy-evaluation", "repository"),
+    path.join(destination, "repository"),
+    { recursive: true },
+  );
+  console.log(`Example task created: ${destination}`);
+  console.log(
+    `Next: citeark run --task ${shellQuote(path.join(destination, "task.json"))} --agent opencode --api-base-url https://api.deepseek.com --model '<model-id>' --dry-run`,
+  );
+}
+
+function parseOptions(argv, definitions) {
+  const output = {};
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (definition.default !== undefined) output[name] = definition.default;
+  }
+  for (let index = 0; index < argv.length; index += 1) {
+    const name = argv[index];
+    const definition = definitions[name];
+    if (!definition) throw new CiteArkError(`Unknown option: ${name}`);
+    if (definition.type === "boolean") {
+      output[name] = true;
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("--")) {
+      throw new CiteArkError(`Missing value for ${name}`);
+    }
+    output[name] = value;
+    index += 1;
+  }
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (definition.required && output[name] === undefined) {
+      throw new CiteArkError(`Missing required option: ${name}`);
+    }
+  }
+  return output;
+}
+
+function agentEntryOptions() {
+  return {
+    "--agent": { type: "string", required: true },
+    "--api-base-url": { type: "string", required: true },
+    "--api-key": { type: "string" },
+    "--api-key-env": { type: "string" },
+    "--model": { type: "string", required: true },
+    "--subagent-model": { type: "string" },
+    "--effort": { type: "string" }, "--model-budget": { type: "string" },
+  };
+}
+
+function agentRuntimeOptions(options, dryRun, { allowGcpSecret = false } = {}) {
+  const runtime = options["--agent"];
+  if (!new Set(["claude-code", "codex", "opencode"]).has(runtime)) {
+    throw new CiteArkError("--agent must be claude-code, codex, or opencode");
+  }
+  if (options["--api-key"] && options["--api-key-env"]) {
+    throw new CiteArkError("Provide either --api-key or --api-key-env");
+  }
+  const environmentName = options["--api-key-env"];
+  const apiKey = options["--api-key"] ?? (environmentName ? process.env[environmentName] : null);
+  const hasGcpSecret = Boolean(options["--gcp-provider-secret"] ?? process.env.CITEARK_GCP_PROVIDER_SECRET);
+  if (!dryRun && !apiKey && !(allowGcpSecret && hasGcpSecret)) {
+    throw new CiteArkError(
+      environmentName
+        ? `Environment variable ${environmentName} is not set`
+        : "Provide --api-key, --api-key-env, or --gcp-provider-secret for GCP Batch.",
+    );
+  }
+  return {
+    runtime,
+    apiBaseUrl: options["--api-base-url"],
+    apiKey,
+    apiKeySource: apiKey
+      ? (environmentName ? `env:${environmentName}` : "parameter")
+      : "gcp-secret-manager",
+    model: options["--model"],
+    subagentModel: options["--subagent-model"],
+    effort: options["--effort"], maxBudgetUsd: options["--model-budget"] ? Number(options["--model-budget"]) : undefined,
+  };
+}
+
+function gcpEntryOptions() {
+  return {
+    "--gcp-project": { type: "string" },
+    "--gcp-region": { type: "string" },
+    "--gcp-staging-bucket": { type: "string" },
+    "--gcp-asset-cache-bucket": { type: "string" },
+    "--gcp-asset-restore-checkpoint-prefix": { type: "string" },
+    "--gcp-asset-restore-checkpoint-bucket": { type: "string" },
+    "--gcp-service-account": { type: "string" },
+    "--gcp-provider-secret": { type: "string" },
+    "--gcp-machine-type": { type: "string" },
+    "--gcp-provisioning-model": { type: "string" },
+    "--gcp-boot-disk-gb": { type: "string" },
+    "--gcp-wait-timeout-minutes": { type: "string" },
+    "--gcp-critical-checkpoint-seconds": { type: "string" },
+    "--gcp-full-checkpoint-seconds": { type: "string" },
+    "--gcp-checkpoint-retention": { type: "string" },
+    "--gcp-result-stability-seconds": { type: "string" },
+    "--gcp-disable-checkpoints": { type: "boolean", default: false },
+    "--gcp-keep-job": { type: "boolean", default: false },
+    "--gcp-keep-staging": { type: "boolean", default: false },
+  };
+}
+
+function autoDlEntryOptions() {
+  return {
+    "--autodl-token-env": { type: "string", default: "AUTODL_API_TOKEN" },
+    "--allow-remote-model-key": { type: "boolean", default: false },
+    "--autodl-image-uuid": { type: "string" },
+    "--autodl-gpu-spec-uuid": { type: "string" },
+    "--autodl-data-centers": { type: "string" },
+    "--autodl-max-hourly-cny": { type: "string" },
+    "--autodl-expand-system-disk-gb": { type: "string" },
+    "--autodl-keep-instance": { type: "boolean", default: false },
+    "--autodl-keep-failed-instance": { type: "boolean", default: false },
+    "--autodl-release-on-failure": { type: "boolean", default: false },
+  };
+}
+
+function executorOptions(options) {
+  const autoDlTokenEnvironment = options["--autodl-token-env"];
+  return {
+    gcpBatch: {
+      projectId: options["--gcp-project"],
+      region: options["--gcp-region"],
+      stagingBucket: options["--gcp-staging-bucket"],
+      assetCacheBucket: options["--gcp-asset-cache-bucket"],
+      assetPreparationRestoreCheckpointPrefix:
+        options["--gcp-asset-restore-checkpoint-prefix"],
+      assetPreparationRestoreCheckpointBucket:
+        options["--gcp-asset-restore-checkpoint-bucket"],
+      serviceAccount: options["--gcp-service-account"],
+      providerSecret: options["--gcp-provider-secret"],
+      machineType: options["--gcp-machine-type"],
+      provisioningModel: options["--gcp-provisioning-model"],
+      bootDiskGb: options["--gcp-boot-disk-gb"],
+      waitTimeoutMinutes: options["--gcp-wait-timeout-minutes"],
+      checkpointEnabled: options["--gcp-disable-checkpoints"] ? false : undefined,
+      criticalCheckpointIntervalSeconds: options["--gcp-critical-checkpoint-seconds"],
+      fullCheckpointIntervalSeconds: options["--gcp-full-checkpoint-seconds"],
+      checkpointRetention: options["--gcp-checkpoint-retention"],
+      keepJob: options["--gcp-keep-job"],
+      keepStaging: options["--gcp-keep-staging"],
+    },
+    autoDl: {
+      allowRemoteModelKey: options["--allow-remote-model-key"],
+      apiToken: autoDlTokenEnvironment
+        ? process.env[autoDlTokenEnvironment]
+        : undefined,
+      imageUuid: options["--autodl-image-uuid"],
+      gpuSpecUuid: options["--autodl-gpu-spec-uuid"],
+      dataCenterList: options["--autodl-data-centers"]
+        ?.split(",")
+        .map((item) => item.trim())
+        .filter(Boolean),
+      maxHourlyCny: options["--autodl-max-hourly-cny"],
+      expandSystemDiskGb: options["--autodl-expand-system-disk-gb"],
+      providerSecret: options["--gcp-provider-secret"],
+      keepInstance: options["--autodl-keep-instance"],
+      keepFailedInstance: options["--autodl-keep-failed-instance"]
+        ? true
+        : options["--autodl-release-on-failure"]
+          ? false
+          : undefined,
+    },
+  };
+}
+
+function printHelp() {
+  console.log(`CiteArk Agent ${VERSION}
+
+Independent research, experiment execution, and signed evidence.
+
+Start and continue
+  citeark                         Open the interactive research workspace
+  citeark start <paper-id>         Start from a CiteArk paper
+  citeark start --paper <path>     Start from a paper file or URL
+  citeark start --cap <file>       Use a CAP artifact as research input
+  citeark start --resume --work-dir <directory>
+  citeark view <directory>         Browse a saved conversation without running it
+
+Profiles and sessions
+  citeark model add|list|use|remove|check <name>
+  citeark compute add|list|use|remove|check <name>
+  citeark session list
+  citeark session attach|status|pause|resume|cancel <directory>
+  citeark session note <directory> --message <text>
+  citeark session fetch <remote-directory> --compute <name> --output <path>
+
+Research options
+  --goal <text>                   Set your research question
+  --repository <path-or-url>       Include source code
+  --guide <file>                  Include research instructions
+  --compute <name>                Select a saved local, SSH or catalog profile
+  --background                    Start a detached research worker
+  --compute-catalog <file>        Use your local or remote compute configuration
+  --plan-only                     Save a plan without running experiments
+  --experiments <id,id>            Select experiments
+  --plain                         Use line-oriented terminal output
+  --non-interactive               Run with explicit options, without prompts
+  --dry-run                       Prepare inputs without models or compute
+
+Model options
+  --model-profile <name>           Select a saved model configuration
+  --assessment-profile <name>      Use a separate model for scientific assessment
+  --change-model                  Record an explicit model change on resume
+  --effort <level>                 low, medium, high, xhigh or max
+  --model-budget <usd>             Runtime model budget (not a total cost cap)
+  --agent <runtime>               opencode, codex, or claude-code
+  --api-base-url <url>             Model endpoint
+  --model <name>                   Model name
+  --api-key-env <name>             Environment variable containing the API key
+
+Artifacts and tools
+  citeark publish --cap <file> [--plan <file>]
+  citeark cap verify --file <file>
+  citeark graph --cap <file> --operation subgraph
+  citeark paper setup --python python3.12
+  citeark paper parse --input paper.pdf --output ./paper-reading
+  citeark setup [--gpu]
+  citeark doctor
+  citeark deploy --replay <paper-id>
+
+Advanced commands
+  compile · run · pipeline · research · contract · compute · assets
+  evidence · handoff · parsers · dashboard · autodl · init
+
+Terminal controls
+  PgUp/PgDn or mouse wheel        Browse the full conversation
+  End                             Follow new output
+  Ctrl+O                          Expand or collapse long tool output
+  /pause /resume /cancel          Control the attached research worker
+  Enter                           Queue an instruction for the next invocation
+  Ctrl+C                          Detach from the research worker
+
+Documentation: https://citeark.co/docs/local-reproduction`);
+}
+
+export { parseOptions, agentEntryOptions, gcpEntryOptions, autoDlEntryOptions, agentRuntimeOptions, executorOptions };