@citeark/agent 0.3.20

package/src/compute/autodl-pro-staging.mjs

@@ -0,0 +1,117 @@
+import path from "node:path";
+
+import { GoogleAccessTokenProvider } from "../gcp/auth.mjs";
+import { GcpIamCredentialsSigner, createGcsV4SignedReadUrl } from "../gcp/signed-url.mjs";
+import { GcsStagingClient } from "../gcp/storage.mjs";
+
+export function createAutoDlGcsStageTransfer({ config, clients = {} } = {}) {
+  if (!config?.stagingBucket || !config?.stageSigningServiceAccount) return null;
+  if (clients.stageTransfer) return clients.stageTransfer;
+  const auth = clients.stageAuth ?? new GoogleAccessTokenProvider(clients.stageAuthOptions);
+  return new AutoDlGcsStageTransfer({
+    bucket: config.stagingBucket,
+    serviceAccount: config.stageSigningServiceAccount,
+    expiresSeconds: config.stageSignedUrlExpiresSeconds,
+    storage: clients.stageStorage ?? new GcsStagingClient({
+      auth,
+      ...clients.stageStorageOptions,
+    }),
+    signer: clients.stageSigner ?? new GcpIamCredentialsSigner({
+      auth,
+      ...clients.stageSignerOptions,
+    }),
+  });
+}
+
+export class AutoDlGcsStageTransfer {
+  constructor({
+    bucket,
+    serviceAccount,
+    expiresSeconds = 30 * 60,
+    storage,
+    signer,
+    now = () => new Date(),
+  } = {}) {
+    this.bucket = required(bucket, "bucket");
+    this.serviceAccount = required(serviceAccount, "serviceAccount");
+    this.expiresSeconds = positiveInteger(expiresSeconds, "expiresSeconds");
+    this.storage = requiredClient(storage, "storage", ["uploadFile", "deleteObject"]);
+    this.signer = requiredClient(signer, "signer", ["signBlob"]);
+    this.now = now;
+  }
+
+  async publish({ runId, attempt, filePath, digest, byteSize }) {
+    const normalizedDigest = String(digest ?? "").toLowerCase();
+    if (!/^[a-f0-9]{64}$/.test(normalizedDigest)) {
+      throw new TypeError("AutoDL GCS 暂存包 SHA-256 无效");
+    }
+    const size = positiveInteger(byteSize, "byteSize");
+    const object = [
+      "autodl-stage",
+      safeIdentifier(runId),
+      `attempt-${positiveInteger(attempt, "attempt")}`,
+      `${normalizedDigest}.tar.gz`,
+    ].join("/");
+    await this.storage.uploadFile({
+      bucket: this.bucket,
+      object,
+      filePath: path.resolve(filePath),
+      contentType: "application/gzip",
+    });
+    try {
+      const url = await createGcsV4SignedReadUrl({
+        bucket: this.bucket,
+        object,
+        serviceAccount: this.serviceAccount,
+        signer: this.signer,
+        expiresSeconds: this.expiresSeconds,
+        now: this.now(),
+      });
+      return {
+        mode: "gcs-signed-url",
+        bucket: this.bucket,
+        object,
+        url,
+        digest: normalizedDigest,
+        byteSize: size,
+        remove: async () => await this.storage.deleteObject({
+          bucket: this.bucket,
+          object,
+        }),
+      };
+    } catch (error) {
+      await this.storage.deleteObject({ bucket: this.bucket, object }).catch(() => undefined);
+      throw error;
+    }
+  }
+}
+
+function safeIdentifier(value) {
+  return String(value ?? "run")
+    .toLowerCase()
+    .replaceAll(/[^a-z0-9-]/g, "-")
+    .replaceAll(/^-+|-+$/g, "")
+    .slice(0, 80) || "run";
+}
+
+function required(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new TypeError(`AutoDL GCS 暂存缺少 ${field}`);
+  }
+  return value.trim();
+}
+
+function requiredClient(value, field, methods) {
+  if (!value || methods.some((method) => typeof value[method] !== "function")) {
+    throw new TypeError(`AutoDL GCS 暂存 ${field} 实现无效`);
+  }
+  return value;
+}
+
+function positiveInteger(value, field) {
+  const numeric = Number(value);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new TypeError(`AutoDL GCS 暂存 ${field} 必须是正整数`);
+  }
+  return numeric;
+}

package/src/compute/campaign.mjs

@@ -0,0 +1,110 @@
+import { resolveComputeRequirement } from "./requirements.mjs";
+import { measurementHardwareConstraint } from "./measurement-hardware.mjs";
+import { executionTimeoutCapMinutes } from "../contracts/execution-timeouts.mjs";
+import { CiteArkError, sha256Value } from "../util.mjs";
+import { sharedWorkloads, workloadMinutes } from "./shared-workloads.mjs";
+
+// Keep an existing campaign intact across publication retries. When migrating
+// an older per-experiment job, completed targets must not train again.
+export function campaignExecutionTargets(targets, previousUnits = [], completedTargets = []) {
+  const key = t => `${t.experimentId}:${t.claimId}`;
+  const previous = previousUnits.find(unit => unit.id?.startsWith("campaign:"));
+  if (previous) {
+    const admitted = new Set(targets.map(key));
+    const removed = previous.targets.filter(t => !admitted.has(key(t)));
+    // Workers before the target-binding fix persisted contextual
+    // claim/experiment associations without any verifiable measurement as
+    // campaign members. They never had a valid contract to execute. Permit a
+    // one-way migration that only drops those empty legacy members; a real
+    // measured target changing still invalidates the immutable campaign.
+    if (removed.some(t => Array.isArray(t.measurementIds) && t.measurementIds.length)) {
+      throw new CiteArkError("恢复任务的整组实验范围已改变");
+    }
+    const retainedTargets = previous.targets.filter(t => admitted.has(key(t)));
+    const retained = new Set(retainedTargets.map(key));
+    const done = new Set(completedTargets.map(key));
+    if (targets.some(t => !retained.has(key(t)) && !done.has(key(t)))) throw new CiteArkError("不能在恢复运行中加入新的实验");
+    return retainedTargets;
+  }
+  const done = new Set(completedTargets.map(key));
+  return targets.filter(t => !done.has(key(t)));
+}
+
+/** One selected set is one persistent execution, with claim-specific outputs. */
+export function reproductionCampaign(research, targets) {
+  if (!targets.length) return null;
+  const unique = [...new Map(targets.map(t => [`${t.experimentId}:${t.claimId}`, t])).values()]
+    .sort((a, b) => `${a.experimentId}:${a.claimId}`.localeCompare(`${b.experimentId}:${b.claimId}`));
+  const ids = [...new Set(unique.map(t => t.experimentId))];
+  const experiments = ids.map(id => {
+    const experiment = research.experiments.find(e => e.id === id);
+    if (!experiment) throw new CiteArkError(`找不到所选实验：${id}`);
+    return experiment;
+  });
+  for (const target of unique) {
+    if (!experiments.find(e => e.id === target.experimentId).claimIds.includes(target.claimId)) {
+      throw new CiteArkError(`实验 ${target.experimentId} 未绑定结论 ${target.claimId}`);
+    }
+  }
+  // A run has one immutable source snapshot. Do not quietly substitute another
+  // repository or split the user's selection into separately billed machines.
+  if (new Set(experiments.map(e => sha256Value(e.repository))).size !== 1) {
+    throw new CiteArkError("所选实验的固定源码不同，需先统一工作区源码计划，不能静默拆成多台机器执行");
+  }
+  const requirements = experiments.map(resolveComputeRequirement);
+  const gpu = requirements.some(r => r.accelerator === "required" || r.accelerator === "optional");
+  const hardware = experiments.map(measurementHardwareConstraint);
+  const typeSets = hardware.map(h => h.requiredGpuTypes).filter(types => types.length);
+  const requiredGpuTypes = typeSets.length ? typeSets[0].filter(type => typeSets.every(set =>
+    set.some(t => t.toLowerCase() === type.toLowerCase()))) : [];
+  if (typeSets.length && !requiredGpuTypes.length) {
+    throw new CiteArkError("所选实验要求不同的固定 GPU 型号，单台机器无法满足全部科学条件");
+  }
+  const accelerator = gpu ? "gpu" : "cpu";
+  const estimate = campaignWorkEstimate(experiments, accelerator);
+  const maximum = key => Math.max(...requirements.map(r => r[key] ?? 0));
+  const timeoutMinutes = Math.min(executionTimeoutCapMinutes("faithful"), experiments.reduce(
+    (sum, e) => sum + (e.environment?.timeoutMinutes ?? 720), 0));
+  const first = experiments[0];
+  const compute = {
+    accelerator: gpu ? "required" : "none", cpuCores: maximum("cpuCores"),
+    memoryGb: maximum("memoryGb"), gpuCount: gpu ? Math.max(1, maximum("gpuCount"),
+      ...hardware.map(h => h.requiredGpuCount ?? 0)) : 0,
+    ...(gpu ? { minVramGb: Math.max(maximum("minVramGb"), ...hardware.map(h => h.requiredVramGb ?? 0)) || undefined } : {}),
+    cpuFallbackAllowed: !gpu, preemptionSafe: requirements.every(r => r.preemptionSafe),
+    estimatedDurationMinutes: { [accelerator]: estimate.durationMinutes },
+    rationale: estimate.basis === "shared_workloads"
+      ? "One machine; identical declared workloads counted once, without assuming parallel speedup."
+      : "Joint runtime is unknown until the Agent plans shared work; independent experiment durations are not added into a campaign quote.",
+  };
+  const experiment = {
+    ...first, compute,
+    environment: { ...first.environment, timeoutMinutes },
+    protocol: { executionMode: "agent_planned", objective: "Complete all selected experiments in one persistent workspace.",
+      entrypoint: "Agent organizes the selected scientific work, shared training and measurement.",
+      requiredCommandFragments: [],
+      ...(gpu ? { benchmark: { device: "gpu", ...(requiredGpuTypes.length ? { requiredGpuTypes } : {}),
+        ...(compute.gpuCount ? { requiredGpuCount: compute.gpuCount } : {}),
+        ...(compute.minVramGb ? { requiredVramGb: compute.minVramGb } : {}) } } : {}),
+    },
+  };
+  return { id: `campaign:${sha256Value(unique.map(t => [t.claimId, t.experimentId])).slice(0, 20)}`,
+    experimentId: first.id, experimentIds: ids, claimIds: [...new Set(unique.map(t => t.claimId))],
+    measurementIds: [...new Set(unique.flatMap(t => t.measurementIds ?? []))], targets: unique,
+    sharedAcrossClaims: new Set(unique.map(t => t.claimId)).size > 1, experiments, experiment,
+    estimate, timeoutMinutes };
+}
+
+// Optional planner-declared work items describe *computation*, not new scientific
+// experiments or a DAG. Same ID is reusable only with the exact same definition.
+export function campaignWorkEstimate(experiments, accelerator) {
+  if (experiments.length === 1 && !experiments[0].compute?.workloads?.length) {
+    const r = resolveComputeRequirement(experiments[0]);
+    return { basis: "single_experiment", durationMinutes: r.estimatedDurationMinutes[accelerator] ?? null };
+  }
+  if (!experiments.every(e => e.compute?.workloads?.length)) return { basis: "unknown", durationMinutes: null };
+  const work = sharedWorkloads(experiments);
+  const durations = work.map(item => workloadMinutes(item, accelerator));
+  return { basis: "shared_workloads", workloadCount: work.length,
+    durationMinutes: durations.every(n => Number.isFinite(n) && n >= 0) ? durations.reduce((a, b) => a + b, 0) : null };
+}

package/src/compute/catalog.mjs

@@ -0,0 +1,123 @@
+import { readJson } from "../util.mjs";
+
+export const DEFAULT_COMPUTE_CATALOG = Object.freeze({
+  schemaVersion: "0.1",
+  profiles: [
+    {
+      id: "local-docker-cpu",
+      label: "Local Docker CPU",
+      executor: "local-docker",
+      accelerator: "cpu",
+      cpuCores: 8,
+      memoryGb: 32,
+      hourlyUsd: 0,
+      available: true,
+    },
+  ],
+});
+
+export const DEFAULT_COMPUTE_POLICY = Object.freeze({
+  schemaVersion: "0.1",
+  allowCpuFallback: true,
+  maxEstimatedComputeUsd: null,
+  maxNonResumableSpotDurationMinutes: 30,
+  allowedExecutors: null,
+  allowedProfileIds: null,
+});
+
+export async function loadComputeCatalog(target) {
+  const catalog = target ? await readJson(target) : structuredClone(DEFAULT_COMPUTE_CATALOG);
+  validateComputeCatalog(catalog);
+  return catalog;
+}
+
+export async function loadComputePolicy(target) {
+  const policy = target ? await readJson(target) : structuredClone(DEFAULT_COMPUTE_POLICY);
+  validateComputePolicy(policy);
+  return { ...structuredClone(DEFAULT_COMPUTE_POLICY), ...policy };
+}
+
+export function validateComputeCatalog(catalog) {
+  const issues = [];
+  if (catalog?.schemaVersion !== "0.1") issues.push("catalog.schemaVersion 必须是 0.1");
+  if (!Array.isArray(catalog?.profiles) || catalog.profiles.length === 0) issues.push("catalog.profiles 必须是非空数组");
+  const ids = new Set();
+  for (const [index, profile] of (catalog?.profiles ?? []).entries()) {
+    const label = `catalog.profiles[${index}]`;
+    if (typeof profile?.id !== "string" || !profile.id) issues.push(`${label}.id 必须是非空字符串`);
+    if (ids.has(profile?.id)) issues.push(`计算资源 profile id 重复：${profile.id}`);
+    ids.add(profile?.id);
+    if (typeof profile?.executor !== "string" || !profile.executor) issues.push(`${label}.executor 必须是非空字符串`);
+    if (profile?.executorConfig !== undefined && (!profile.executorConfig || typeof profile.executorConfig !== "object" || Array.isArray(profile.executorConfig))) {
+      issues.push(`${label}.executorConfig 必须是对象`);
+    }
+    if (
+      profile?.executor === "gcp-batch"
+      && !nonEmptyString(profile?.executorConfig?.machineType)
+      && !nonEmptyString(profile?.executorConfig?.instanceTemplate)
+    ) {
+      issues.push(`${label}.executorConfig 至少需要 machineType 或 instanceTemplate`);
+    }
+    if (profile?.executor === "autodl-pro" && (typeof profile?.executorConfig?.gpuSpecUuid !== "string" || !profile.executorConfig.gpuSpecUuid)) {
+      issues.push(`${label}.executorConfig.gpuSpecUuid 是 autodl-pro 的必需字段`);
+    }
+    if (profile?.executorConfig?.provisioningModel && !new Set(["STANDARD", "SPOT", "FLEX_START"]).has(profile.executorConfig.provisioningModel)) {
+      issues.push(`${label}.executorConfig.provisioningModel 必须是 STANDARD、SPOT 或 FLEX_START`);
+    }
+    if (!new Set(["cpu", "gpu"]).has(profile?.accelerator)) issues.push(`${label}.accelerator 必须是 cpu 或 gpu`);
+    for (const field of ["cpuCores", "memoryGb"]) {
+      if (!isFinitePositive(profile?.[field])) issues.push(`${label}.${field} 必须大于 0`);
+    }
+    if (profile?.hourlyUsd !== null && profile?.hourlyUsd !== undefined && !isFiniteNonNegative(profile.hourlyUsd)) {
+      issues.push(`${label}.hourlyUsd 必须是非负数或 null`);
+    }
+    if (profile?.hourlyCny !== null && profile?.hourlyCny !== undefined && !isFiniteNonNegative(profile.hourlyCny)) {
+      issues.push(`${label}.hourlyCny 必须是非负数或 null`);
+    }
+    if (profile?.accelerator === "gpu") {
+      if (!isFinitePositive(profile?.gpu?.count)) issues.push(`${label}.gpu.count 必须大于 0`);
+      if (!isFinitePositive(profile?.gpu?.vramGb)) issues.push(`${label}.gpu.vramGb 必须大于 0`);
+    }
+  }
+  if (issues.length) throw new TypeError(`计算资源目录校验失败：\n- ${issues.join("\n- ")}`);
+  return catalog;
+}
+
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+export function validateComputePolicy(policy) {
+  const issues = [];
+  if (policy?.schemaVersion !== "0.1") issues.push("policy.schemaVersion 必须是 0.1");
+  if (policy?.allowCpuFallback !== undefined && typeof policy.allowCpuFallback !== "boolean") issues.push("policy.allowCpuFallback 必须是布尔值");
+  if (policy?.maxEstimatedComputeUsd !== null && policy?.maxEstimatedComputeUsd !== undefined && !isFiniteNonNegative(policy.maxEstimatedComputeUsd)) {
+    issues.push("policy.maxEstimatedComputeUsd 必须是非负数或 null");
+  }
+  if (
+    policy?.maxNonResumableSpotDurationMinutes !== null
+    && policy?.maxNonResumableSpotDurationMinutes !== undefined
+    && !isFinitePositive(policy.maxNonResumableSpotDurationMinutes)
+  ) {
+    issues.push("policy.maxNonResumableSpotDurationMinutes 必须是正数或 null");
+  }
+  for (const field of ["allowedExecutors", "allowedProfileIds"]) {
+    if (policy?.[field] !== null && policy?.[field] !== undefined && (!Array.isArray(policy[field]) || policy[field].some((item) => typeof item !== "string" || !item))) {
+      issues.push(`policy.${field} 必须是字符串数组或 null`);
+    }
+  }
+  if (policy.allowedGpuTypes !== undefined && (!Array.isArray(policy.allowedGpuTypes)
+    || policy.allowedGpuTypes.some((type) => typeof type !== "string" || !type))) issues.push("allowedGpuTypes 必须是型号列表");
+  if (policy.maximumGpuCount !== undefined && (!Number.isInteger(policy.maximumGpuCount)
+    || policy.maximumGpuCount < 1)) issues.push("maximumGpuCount 必须是正整数");
+  if (issues.length) throw new TypeError(`计算策略校验失败：\n- ${issues.join("\n- ")}`);
+  return policy;
+}
+
+function isFinitePositive(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+
+function isFiniteNonNegative(value) {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}

package/src/compute/checkpoint-protocol.mjs

@@ -0,0 +1,154 @@
+const DEFAULT_CRITICAL_INTERVAL_SECONDS = 20;
+const DEFAULT_FULL_INTERVAL_SECONDS = 300;
+const DEFAULT_RETENTION = 3;
+
+export const GCP_BATCH_RETRYABLE_INFRASTRUCTURE_EXIT_CODES = Object.freeze([
+  50001, // Spot VM preemption
+  50002, // VM reporting timeout
+  50003, // VM rebooted during execution
+  50004, // VM and task became unresponsive
+  50006, // VM recreated during execution
+]);
+
+const GCP_BATCH_RUNTIME_TIMEOUT_EXIT_CODE = 50005;
+
+export function resolveCheckpointPolicy({ options = {}, profile = {} } = {}) {
+  const enabled = booleanValue(
+    options.checkpointEnabled ?? profile.checkpointEnabled,
+    true,
+  );
+  const criticalIntervalSeconds = positiveInteger(
+    options.criticalCheckpointIntervalSeconds ?? profile.criticalCheckpointIntervalSeconds,
+    DEFAULT_CRITICAL_INTERVAL_SECONDS,
+  );
+  const fullIntervalSeconds = positiveInteger(
+    options.fullCheckpointIntervalSeconds ?? profile.fullCheckpointIntervalSeconds,
+    DEFAULT_FULL_INTERVAL_SECONDS,
+  );
+  if (fullIntervalSeconds < criticalIntervalSeconds) {
+    throw new TypeError("GCP 完整检查点间隔不能短于关键检查点间隔");
+  }
+  return {
+    schemaVersion: "0.1",
+    enabled,
+    criticalIntervalSeconds,
+    fullIntervalSeconds,
+    retention: positiveInteger(
+      options.checkpointRetention ?? profile.checkpointRetention,
+      DEFAULT_RETENTION,
+    ),
+    restoreOnInfrastructureRetry: true,
+    reuseCompletedResult: true,
+  };
+}
+
+export function checkpointObjectPrefix(stagingPrefix, attempt) {
+  const normalized = String(stagingPrefix ?? "citeark-run")
+    .replaceAll(/[^a-zA-Z0-9_.-]/g, "-");
+  return `${normalized}-checkpoint-a${Number(attempt)}`;
+}
+
+export function checkpointStatusObject(prefix) {
+  return `${prefix}-status.json`;
+}
+
+export function infrastructureResumePrompt(bundle) {
+  return [
+    `Run ID: ${bundle.runId}`,
+    "The previous cloud worker was interrupted by infrastructure, not by a scientific or protocol decision.",
+    "CiteArk restored the most recent durable checkpoint, including the Agent session, execution trace, workspace, and any evidence already produced.",
+    "Continue the same task from that checkpoint. Inspect existing files first and do not repeat completed downloads, installations, experiments, or repairs unless their outputs are missing or corrupt.",
+    "When task.json enables workspacePlan, restore the current research-plan.json and progress.md, not the initial interpretation. Check prior process identity, live state, logs and outputs before starting any replacement. Continue within the runner's remaining cumulative budget.",
+    "If /job/output/result.json and all evidence it references are already complete, verify them and finish immediately without rerunning the experiment.",
+    ...coordinatorRecoveryGuidance(bundle),
+  ].join("\n");
+}
+
+export function targetRecoveryPrompt(bundle) {
+  return [
+    `Run ID: ${bundle.runId}`,
+    "This is a new operational attempt for the same immutable reproduction target.",
+    "CiteArk restored the previous Agent workspace, task environment, acquired assets, caches, audit trace, and evidence so the repair can continue instead of restarting.",
+    "Inspect the preserved failure, acquisition manifest, installed dependency state, and existing files before acting. Keep valid completed work and apply a materially different repair for the recorded blocker.",
+    "Do not reuse a failed result.json as success. When workspacePlan is enabled, continue the preserved editable plan with source-grounded revisions; otherwise preserve the original contract. Replace the result only when actual evidence justifies it, within the remaining runner budget.",
+    ...coordinatorRecoveryGuidance(bundle),
+  ].join("\n");
+}
+
+function coordinatorRecoveryGuidance(bundle) {
+  const notes = bundle.state?.recoveryGuidance;
+  if (!Array.isArray(notes)) return [];
+  const lines = notes.filter((note) => typeof note === "string" && note.trim());
+  return lines.length
+    ? ["Coordinator observations from the preserved failure (verify against the restored files; the scientific contract remains unchanged):", ...lines]
+    : [];
+}
+
+export function summarizeInfrastructureAttempt(job) {
+  const starts = [];
+  const seen = new Set();
+  const failures = [];
+  for (const [index, event] of (job?.status?.statusEvents ?? []).entries()) {
+    const description = String(event?.description ?? "");
+    const isStart = /\bcontainer\b.*\bstarted\b/i.test(description)
+      || (event?.type === "RUNNING_EVENT" && description.length === 0);
+    const eventTime = String(event?.eventTime ?? "");
+    const identity = eventTime
+      ? `${eventTime}|${description}`
+      : `without-time-${index}`;
+    if (seen.has(identity)) continue;
+    seen.add(identity);
+    if (isStart) {
+      starts.push(event);
+      continue;
+    }
+    const exitCode = batchExitCode(description);
+    if (exitCode !== null) {
+      failures.push({
+        exitCode,
+        eventTime: eventTime || null,
+        description: description || null,
+        category: exitCode === GCP_BATCH_RUNTIME_TIMEOUT_EXIT_CODE
+          ? "timeout"
+          : GCP_BATCH_RETRYABLE_INFRASTRUCTURE_EXIT_CODES.includes(exitCode)
+            ? "infrastructure"
+            : "execution",
+        retryable: GCP_BATCH_RETRYABLE_INFRASTRUCTURE_EXIT_CODES.includes(exitCode),
+      });
+    }
+  }
+  const executionAttempt = Math.max(1, starts.length || 1);
+  const resumedInfrastructureAttempts = Math.min(
+    Math.max(0, executionAttempt - 1),
+    failures.filter((failure) => failure.retryable).length,
+  );
+  const infrastructureAttempt = 1 + resumedInfrastructureAttempts;
+  return {
+    executionAttempt,
+    infrastructureAttempt,
+    resumeCount: resumedInfrastructureAttempts,
+    interruptionCount: resumedInfrastructureAttempts,
+    latestFailure: failures.at(-1) ?? null,
+  };
+}
+
+function batchExitCode(description) {
+  const matched = String(description ?? "").match(/\bexit code\s+(-?\d+)\b/i);
+  if (!matched) return null;
+  const exitCode = Number(matched[1]);
+  return Number.isInteger(exitCode) ? exitCode : null;
+}
+
+function booleanValue(value, fallback) {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value !== "boolean") throw new TypeError("GCP checkpointEnabled 必须是布尔值");
+  return value;
+}
+
+function positiveInteger(value, fallback) {
+  const numeric = value === undefined || value === null ? fallback : Number(value);
+  if (!Number.isInteger(numeric) || numeric <= 0) {
+    throw new TypeError("GCP 检查点参数必须是正整数");
+  }
+  return numeric;
+}

package/src/compute/codex-account-lock.mjs

@@ -0,0 +1,111 @@
+import { CiteArkError } from "../util.mjs";
+
+const TERMINAL_BATCH_STATES = new Set(["SUCCEEDED", "FAILED", "CANCELLED"]);
+
+export function codexAccountLockObject(accountId) {
+  if (!/^[a-z0-9][a-z0-9-]{0,47}$/.test(accountId ?? "")) {
+    throw new TypeError("Codex 专用账号编号无效");
+  }
+  return `codex-accounts/${accountId}/active.json`;
+}
+
+export function codexAccountLockReference({ bucket, accountId, owner, jobName }) {
+  if (!accountId) return null;
+  return {
+    bucket,
+    object: codexAccountLockObject(accountId),
+    owner,
+    jobName,
+  };
+}
+
+export async function acquireCodexAccountLock({
+  storage,
+  batch,
+  bucket,
+  accountId,
+  owner,
+  jobName,
+  now = () => new Date(),
+}) {
+  if (!accountId) return null;
+  const object = codexAccountLockObject(accountId);
+  const value = {
+    schemaVersion: "0.2",
+    accountId,
+    owner,
+    jobName,
+    createdAt: now().toISOString(),
+  };
+  let created = await storage.createJsonObjectIfAbsent({ bucket, object, value });
+  if (created) return lockReference(value, bucket, object, created.generation);
+
+  let current = await storage.readJsonObjectVersion({ bucket, object, missing: null });
+  if (!current) {
+    created = await storage.createJsonObjectIfAbsent({ bucket, object, value });
+    if (created) return lockReference(value, bucket, object, created.generation);
+    current = await storage.readJsonObjectVersion({ bucket, object, missing: null });
+  }
+  if (current?.value?.owner === owner && current.value?.jobName === jobName) {
+    return lockReference(value, bucket, object, current.generation);
+  }
+
+  const incumbentJobName = typeof current?.value?.jobName === "string"
+    ? current.value.jobName
+    : null;
+  if (incumbentJobName && typeof batch?.findJob === "function") {
+    const incumbent = await batch.findJob(incumbentJobName).catch(() => undefined);
+    if (incumbent === null || TERMINAL_BATCH_STATES.has(incumbent?.status?.state)) {
+      await storage.deleteObject({
+        bucket,
+        object,
+        ifGenerationMatch: current.generation,
+      });
+      const replacement = await storage.createJsonObjectIfAbsent({ bucket, object, value });
+      if (replacement) {
+        return lockReference(value, bucket, object, replacement.generation);
+      }
+    }
+  }
+
+  throw new CiteArkError("Codex 订阅账号当前正被另一项活动任务使用，请等待该任务结束", {
+    retryable: true,
+    failureCode: "codex.account_busy",
+    failureCategory: "provider",
+    retryDisposition: "wait_for_account",
+    failureOwner: "platform",
+    recoveryAction: "等待同一订阅账号的活动 Batch 结束；平台不会为账号占用启动新的计算实例",
+  });
+}
+
+export async function releaseCodexAccountLock({ storage, lock }) {
+  if (!lock) return { released: false, reason: "not-configured" };
+  const current = await storage.readJsonObjectVersion({
+    bucket: lock.bucket,
+    object: lock.object,
+    missing: null,
+  });
+  if (!current) return { released: false, reason: "absent" };
+  if (
+    current.value?.owner !== lock.owner
+    || (lock.jobName && current.value?.jobName !== lock.jobName)
+  ) {
+    return { released: false, reason: "owner-mismatch" };
+  }
+  await storage.deleteObject({
+    bucket: lock.bucket,
+    object: lock.object,
+    ifGenerationMatch: current.generation,
+  });
+  return { released: true, reason: "released" };
+}
+
+function lockReference(value, bucket, object, generation) {
+  return {
+    bucket,
+    object,
+    owner: value.owner,
+    jobName: value.jobName,
+    generation: String(generation),
+  };
+}