@citeark/agent 0.3.20

package/src/compute/gcp-checkpoint-worker.mjs

@@ -0,0 +1,1633 @@
+import { freshCodexInvocation } from "../runtime/codex.mjs";
+import { shellQuote } from "../util.mjs";
+
+export const WORKSPACE_CHECKPOINT_CAPTURE_PYTHON = String.raw`
+import hashlib
+import json
+import os
+import pathlib
+import shutil
+import stat
+import subprocess
+
+root = pathlib.Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+repository = root / "workspace" / "repository"
+execution = root / "execution"
+destination = execution / "workspace-checkpoint"
+temporary = execution / (".workspace-checkpoint-" + str(os.getpid()))
+git = ["git", "-c", "safe.directory=" + str(repository)]
+maximum_file_bytes = 8 * 1024 * 1024
+maximum_total_bytes = 64 * 1024 * 1024
+excluded_directories = {".git", ".cache", ".mypy_cache", ".pytest_cache", ".venv", "__pycache__", "node_modules"}
+
+def sha256_file(target):
+    digest = hashlib.sha256()
+    with target.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def safe_relative(value):
+    candidate = pathlib.PurePosixPath(value)
+    return (
+        bool(value)
+        and not candidate.is_absolute()
+        and ".." not in candidate.parts
+        and "\\" not in value
+    )
+
+shutil.rmtree(temporary, ignore_errors=True)
+temporary.mkdir(parents=True)
+(temporary / "untracked").mkdir()
+manifest = {"schemaVersion": "0.1", "retained": [], "excluded": []}
+
+inside = subprocess.run(
+    [*git, "rev-parse", "--is-inside-work-tree"],
+    cwd=repository,
+    stdout=subprocess.PIPE,
+    stderr=subprocess.DEVNULL,
+    text=True,
+)
+git_backed = inside.returncode == 0 and inside.stdout.strip() == "true"
+manifest["mode"] = "git-diff" if git_backed else "runner-snapshot-diff"
+candidate_paths = []
+if git_backed:
+    with (temporary / "repository.patch").open("wb") as target:
+        diff = subprocess.run(
+            [*git, "diff", "--binary", "--no-ext-diff", "HEAD", "--", "."],
+            cwd=repository,
+            stdout=target,
+            stderr=subprocess.PIPE,
+        )
+    if diff.returncode != 0:
+        raise SystemExit("failed to capture workspace patch")
+    untracked = subprocess.run(
+        [*git, "ls-files", "--others", "--exclude-standard", "-z"],
+        cwd=repository,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+    if untracked.returncode != 0:
+        raise SystemExit("failed to list untracked workspace files")
+    candidate_paths = [
+        raw.decode("utf-8", errors="strict")
+        for raw in untracked.stdout.split(b"\0")
+        if raw
+    ]
+else:
+    (temporary / "repository.patch").write_bytes(b"")
+    before_path = execution / "workspace-before.json"
+    if not before_path.is_file():
+        raise SystemExit("runner snapshot checkpoint requires workspace-before.json")
+    before = json.loads(before_path.read_text(encoding="utf-8"))
+    before_files = {
+        item.get("path"): item
+        for item in before.get("entries", [])
+        if isinstance(item, dict) and item.get("type") == "file" and isinstance(item.get("path"), str)
+    }
+    current_paths = set()
+    for source in repository.rglob("*"):
+        relative = source.relative_to(repository).as_posix()
+        candidate = pathlib.PurePosixPath(relative)
+        if any(part in excluded_directories for part in candidate.parts):
+            continue
+        if source.is_symlink() or not source.is_file():
+            continue
+        current_paths.add(relative)
+        previous = before_files.get(relative)
+        size = source.stat().st_size
+        if previous and previous.get("size") == size and previous.get("sha256") == sha256_file(source):
+            continue
+        candidate_paths.append(relative)
+    manifest["deleted"] = sorted(set(before_files) - current_paths)
+
+if (temporary / "repository.patch").stat().st_size > maximum_total_bytes:
+    raise SystemExit("workspace patch exceeds checkpoint boundary")
+
+retained_bytes = 0
+for relative in candidate_paths:
+    candidate = pathlib.PurePosixPath(relative)
+    if not safe_relative(relative) or any(part in excluded_directories for part in candidate.parts):
+        manifest["excluded"].append({"path": relative, "reason": "unsafe-or-rebuildable"})
+        continue
+    if candidate.name == ".env" or candidate.name.startswith(".env."):
+        manifest["excluded"].append({"path": relative, "reason": "secret-shaped"})
+        continue
+    source = repository.joinpath(*candidate.parts)
+    if source.is_symlink() or not source.is_file():
+        manifest["excluded"].append({"path": relative, "reason": "not-regular-file"})
+        continue
+    size = source.stat().st_size
+    if size > maximum_file_bytes or retained_bytes + size > maximum_total_bytes:
+        manifest["excluded"].append({"path": relative, "reason": "rebuildable-size-boundary", "size": size})
+        continue
+    target = temporary / "untracked" / pathlib.Path(*candidate.parts)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(source, target)
+    mode = stat.S_IMODE(source.stat().st_mode)
+    os.chmod(target, mode)
+    digest = sha256_file(target)
+    manifest["retained"].append({"path": relative, "size": size, "sha256": digest, "mode": mode})
+    retained_bytes += size
+
+manifest["patchBytes"] = (temporary / "repository.patch").stat().st_size
+manifest["retainedBytes"] = retained_bytes
+(temporary / "manifest.json").write_text(json.dumps(manifest, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+shutil.rmtree(destination, ignore_errors=True)
+temporary.replace(destination)
+`;
+
+export const WORKSPACE_CHECKPOINT_RESTORE_PYTHON = String.raw`
+import hashlib
+import json
+import os
+import pathlib
+import shutil
+import subprocess
+
+root = pathlib.Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+repository = root / "workspace" / "repository"
+checkpoint = root / "execution" / "workspace-checkpoint"
+manifest_path = checkpoint / "manifest.json"
+patch_path = checkpoint / "repository.patch"
+git = ["git", "-c", "safe.directory=" + str(repository)]
+
+def sha256_file(target):
+    digest = hashlib.sha256()
+    with target.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def safe_relative(value):
+    candidate = pathlib.PurePosixPath(value)
+    return (
+        bool(value)
+        and not candidate.is_absolute()
+        and ".." not in candidate.parts
+        and "\\" not in value
+    )
+
+if not manifest_path.is_file() or not patch_path.is_file():
+    raise SystemExit("workspace checkpoint is incomplete")
+manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+mode = manifest.get("mode", "git-diff")
+if mode == "git-diff" and patch_path.stat().st_size:
+    applied = subprocess.run(
+        [*git, "apply", "--binary", "--whitespace=nowarn", str(patch_path)],
+        cwd=repository,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.PIPE,
+    )
+    if applied.returncode != 0:
+        raise SystemExit("failed to restore workspace patch")
+elif mode == "runner-snapshot-diff":
+    for relative in manifest.get("deleted", []):
+        if not isinstance(relative, str) or not safe_relative(relative):
+            raise SystemExit("unsafe deleted workspace checkpoint path")
+        candidate = pathlib.PurePosixPath(relative)
+        target = repository.joinpath(*candidate.parts)
+        current = repository
+        for part in candidate.parts[:-1]:
+            current = current / part
+            if current.exists() and current.is_symlink():
+                raise SystemExit("workspace checkpoint deletion crosses a symbolic link")
+        if target.is_file() and not target.is_symlink():
+            target.unlink()
+elif mode != "git-diff":
+    raise SystemExit("unknown workspace checkpoint mode")
+
+for item in manifest.get("retained", []):
+    relative = item.get("path")
+    if not isinstance(relative, str) or not safe_relative(relative):
+        raise SystemExit("unsafe untracked workspace checkpoint path")
+    candidate = pathlib.PurePosixPath(relative)
+    source = checkpoint / "untracked" / pathlib.Path(*candidate.parts)
+    if source.is_symlink() or not source.is_file():
+        raise SystemExit("missing untracked workspace checkpoint file")
+    if source.stat().st_size != item.get("size") or sha256_file(source) != item.get("sha256"):
+        raise SystemExit("untracked workspace checkpoint identity mismatch")
+    target = repository.joinpath(*candidate.parts)
+    current = repository
+    for part in candidate.parts[:-1]:
+        current = current / part
+        if current.exists() and current.is_symlink():
+            raise SystemExit("workspace checkpoint destination crosses a symbolic link")
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists() and target.is_symlink():
+        raise SystemExit("workspace checkpoint destination is a symbolic link")
+    shutil.copyfile(source, target)
+    os.chmod(target, int(item.get("mode", 0o644)) & 0o777)
+`;
+
+const WORKSPACE_AUDIT_PYTHON = String.raw`
+import datetime
+import hashlib
+import json
+import os
+import pathlib
+import subprocess
+
+root = pathlib.Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+repository = root / "workspace" / "repository"
+execution = root / "execution"
+before_path = execution / "workspace-before.json"
+excluded = {".git", ".cache", ".mypy_cache", ".pytest_cache", ".venv", "__pycache__", "node_modules"}
+
+def sha256_file(target):
+    digest = hashlib.sha256()
+    with target.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+def scan(directory, relative=""):
+    entries = []
+    for child in sorted(directory.iterdir(), key=lambda item: item.name):
+        child_relative = pathlib.PurePosixPath(relative, child.name).as_posix()
+        if child.is_symlink():
+            entries.append({"path": child_relative, "type": "symlink", "target": os.readlink(child)})
+        elif child.is_dir():
+            if child.name not in excluded:
+                entries.extend(scan(child, child_relative))
+        elif child.is_file():
+            stat = child.stat()
+            entries.append({
+                "path": child_relative,
+                "type": "file",
+                "size": stat.st_size,
+                "sha256": sha256_file(child),
+            })
+    return entries
+
+if not repository.is_dir() or not before_path.is_file():
+    raise SystemExit("workspace audit requires repository and workspace-before.json")
+
+with before_path.open("r", encoding="utf-8") as source:
+    before = json.load(source)
+after = {
+    "generatedAt": datetime.datetime.now(datetime.timezone.utc).isoformat().replace("+00:00", "Z"),
+    "excludedDirectories": sorted(excluded),
+    "entries": scan(repository),
+}
+before_by_path = {entry["path"]: entry for entry in before.get("entries", [])}
+after_by_path = {entry["path"]: entry for entry in after["entries"]}
+changes = {
+    "added": [entry for path, entry in after_by_path.items() if path not in before_by_path],
+    "modified": [
+        {"path": path, "before": before_by_path[path], "after": entry}
+        for path, entry in after_by_path.items()
+        if path in before_by_path and before_by_path[path] != entry
+    ],
+    "deleted": [entry for path, entry in before_by_path.items() if path not in after_by_path],
+}
+for filename, value in (("workspace-after.json", after), ("workspace-changes.json", changes)):
+    temporary = execution / (filename + ".tmp")
+    with temporary.open("w", encoding="utf-8") as target:
+        json.dump(value, target, ensure_ascii=False, indent=2)
+        target.write("\n")
+    temporary.replace(execution / filename)
+
+patch_path = execution / "repository.patch"
+untracked_path = execution / "untracked-files.txt"
+inside = subprocess.run(
+    ["git", "rev-parse", "--is-inside-work-tree"],
+    cwd=repository,
+    stdout=subprocess.PIPE,
+    stderr=subprocess.DEVNULL,
+    text=True,
+)
+if inside.returncode == 0 and inside.stdout.strip() == "true":
+    with patch_path.open("wb") as target:
+        diff = subprocess.run(
+            ["git", "diff", "--binary", "--no-ext-diff", "HEAD"],
+            cwd=repository,
+            stdout=target,
+            stderr=subprocess.PIPE,
+        )
+    if diff.returncode != 0:
+        raise SystemExit("failed to capture repository patch")
+    untracked = subprocess.run(
+        ["git", "ls-files", "--others", "--exclude-standard"],
+        cwd=repository,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+    )
+    if untracked.returncode != 0:
+        raise SystemExit("failed to capture untracked file list")
+    untracked_path.write_text(untracked.stdout, encoding="utf-8")
+else:
+    patch_path.write_text("", encoding="utf-8")
+    untracked_path.write_text("", encoding="utf-8")
+
+if patch_path.stat().st_size > 64 * 1024 * 1024:
+    raise SystemExit("repository patch exceeds the 64 MiB publication boundary")
+`;
+
+export const PUBLICATION_EXPORT_PYTHON = String.raw`
+import hashlib
+import json
+import os
+import pathlib
+import shutil
+import tarfile
+
+root = pathlib.Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+destination = pathlib.Path(os.environ.get("CITEARK_RESULT_ARCHIVE", "/tmp/citeark-result.tar.gz")).resolve()
+completion_relative = os.environ.get("CITEARK_COMPLETION_RELATIVE", "output/result.json")
+maximum_bytes = int(os.environ.get("CITEARK_RESULT_MAX_BYTES", str(512 * 1024 * 1024)))
+inline_evidence_maximum_bytes = int(
+    os.environ.get("CITEARK_INLINE_EVIDENCE_MAX_BYTES", str(64 * 1024 * 1024))
+)
+external_object_prefix = os.environ.get("CITEARK_EXTERNAL_OBJECT_PREFIX", "").strip()
+
+def safe_relative(value):
+    candidate = pathlib.PurePosixPath(str(value))
+    return (
+        bool(str(value))
+        and not candidate.is_absolute()
+        and ".." not in candidate.parts
+        and "\\" not in str(value)
+    )
+
+def resolve_regular(relative):
+    if not safe_relative(relative):
+        raise SystemExit("unsafe publication path: " + str(relative))
+    source = root / pathlib.PurePosixPath(relative)
+    if source.is_symlink():
+        raise SystemExit("publication path cannot be a symbolic link: " + str(relative))
+    target = source.resolve()
+    if root not in target.parents or not target.is_file():
+        raise SystemExit("publication path is not a regular file: " + str(relative))
+    return target
+
+def sha256_file(target):
+    digest = hashlib.sha256()
+    with target.open("rb") as source:
+        while True:
+            chunk = source.read(1024 * 1024)
+            if not chunk:
+                break
+            digest.update(chunk)
+    return digest.hexdigest()
+
+execution = root / "execution"
+manifest_path = execution / "result-export.json"
+previous_manifest = None
+if manifest_path.is_file():
+    try:
+        previous_manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except Exception:
+        previous_manifest = None
+manifest_path.unlink(missing_ok=True)
+paths = set()
+if execution.is_dir():
+    for target in execution.rglob("*"):
+        if target.is_file() and not target.is_symlink():
+            relative = target.relative_to(root).as_posix()
+            if relative != "execution/.publication-reserve":
+                paths.add(relative)
+
+paths.add(completion_relative)
+completion = resolve_regular(completion_relative)
+declared_relatives = set()
+if completion_relative == "output/result.json":
+    try:
+        result = json.loads(completion.read_text(encoding="utf-8"))
+    except Exception as error:
+        raise SystemExit("cannot read output/result.json for evidence export: " + str(error))
+    original_result_bytes = completion.read_bytes()
+    # Workspace summaries do not duplicate the plan's parser-input manifest.
+    # Collect existing inputs here before leaving the scientific machine.
+    task_file = root / "input" / "task.json"
+    task = json.loads(task_file.read_text(encoding="utf-8")) if task_file.is_file() else {}
+    if task.get("workspacePlan", {}).get("version") == 2 and result.get("schemaVersion") == "2.0":
+        plan_file = root / "output" / "research-plan.json"
+        try:
+            plan = json.loads(plan_file.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            plan = {}
+        for measurement in plan.get("measurements", []):
+            parser_path = measurement.get("parser", {}).get("evidencePath", "")
+            relative = "output/" + str(parser_path)
+            if not isinstance(parser_path, str) or not safe_relative(parser_path):
+                raise SystemExit("unsafe parser publication path: " + relative)
+            if (root / relative).is_file():
+                resolve_regular(relative)
+                declared_relatives.add(relative)
+    retained_outputs = []
+    retention_excluded = []
+    retention_excluded_paths = set()
+    for item in result.get("outputs", []):
+        if not isinstance(item, dict) or item.get("kind") not in ("model", "checkpoint", "dataset"):
+            retained_outputs.append(item)
+            continue
+        relative = "output/" + str(item.get("path", ""))
+        source = resolve_regular(relative)
+        retention_excluded_paths.add(item.get("path"))
+        retention_excluded.append({
+            "id": item.get("id"),
+            "kind": item.get("kind"),
+            "role": item.get("role"),
+            "path": item.get("path"),
+            "description": item.get("description"),
+            "size": source.stat().st_size,
+            "sha256": sha256_file(source),
+            "retention": "withheld-model-bytes",
+        })
+    if retention_excluded:
+        result["outputs"] = retained_outputs
+        result["evidence"] = [
+            item for item in result.get("evidence", [])
+            if not isinstance(item, dict) or item.get("path") not in retention_excluded_paths
+        ]
+        retention_record = {
+            "schemaVersion": "0.1",
+            "policy": "withhold-model-and-checkpoint-bytes",
+            "excluded": retention_excluded,
+        }
+        retention_evidence_relative = "evidence/citeark-publication-retention.json"
+        retention_evidence = root / "output" / pathlib.PurePosixPath(retention_evidence_relative)
+        retention_evidence.parent.mkdir(parents=True, exist_ok=True)
+        retention_evidence.write_text(
+            json.dumps(retention_record, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        result["evidence"].append({
+            "path": retention_evidence_relative,
+            "description": (
+                "CiteArk retention audit for model and checkpoint outputs whose bytes "
+                "were intentionally excluded from persistent storage"
+            ),
+        })
+        limitation = (
+            "Model and checkpoint bytes were intentionally excluded by the CiteArk "
+            "retention policy; evaluation evidence and content identities remain in retention audit evidence."
+        )
+        limitations = result.get("limitations")
+        if not isinstance(limitations, list):
+            limitations = []
+        if limitation not in limitations:
+            limitations.append(limitation)
+        result["limitations"] = limitations
+        completion.write_text(
+            json.dumps(result, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        retention_path = execution / "publication-retention.json"
+        retention_path.write_text(
+            json.dumps(retention_record, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        paths.add("execution/publication-retention.json")
+    # Output references are also declared evidence. Preserve their real bytes
+    # before the coordinator validates the result envelope.
+    evidence = result.get("evidence", [])
+    declared_evidence_paths = {item.get("path") for item in evidence if isinstance(item, dict)}
+    linked_evidence_added = []
+    for item in result.get("outputs", []):
+        if not isinstance(item, dict):
+            continue
+        for related in item.get("relatedEvidencePaths", []):
+            if not isinstance(related, str) or related in declared_evidence_paths:
+                continue
+            if related in retention_excluded_paths:
+                continue
+            resolve_regular("output/" + related)
+            evidence.append({"path": related, "description": "Existing evidence referenced by output " + str(item.get("id", "unknown"))})
+            declared_evidence_paths.add(related)
+            linked_evidence_added.append(related)
+    if linked_evidence_added:
+        original_path = execution / "result-envelope-original.json"
+        if not original_path.exists():
+            original_path.write_bytes(original_result_bytes)
+        paths.add("execution/result-envelope-original.json")
+        result["evidence"] = evidence
+        completion.write_text(json.dumps(result, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        audit_path = execution / "result-envelope-normalization.json"
+        audit_path.write_text(json.dumps({"kind": "citeark.result-envelope-normalization", "addedReferencedEvidence": linked_evidence_added}) + "\n", encoding="utf-8")
+        paths.add("execution/result-envelope-normalization.json")
+    for collection in ("evidence", "outputs"):
+        for item in result.get(collection, []):
+            if not isinstance(item, dict) or not isinstance(item.get("path"), str):
+                continue
+            relative = "output/" + item["path"]
+            if not safe_relative(relative):
+                raise SystemExit("unsafe declared publication path: " + relative)
+            declared_relatives.add(relative)
+
+# Raw scientific tables and histories are evidence even when the Agent only
+# declares their aggregate. Do not lose them when the scientific VM is removed.
+raw_suffixes = {".json", ".jsonl", ".ndjson", ".csv", ".tsv", ".txt", ".log", ".parquet", ".arrow"}
+output_root = root / "output"
+withheld_paths = {item.get("path") for item in result.get("outputs", [])
+                  if isinstance(item, dict) and item.get("kind") in ("model", "checkpoint", "dataset")} if completion_relative == "output/result.json" else set()
+if completion_relative == "output/result.json":
+    withheld_paths.update(retention_excluded_paths)
+    for target in output_root.rglob("*"):
+        if not target.is_file() or target.is_symlink() or target.suffix.lower() not in raw_suffixes:
+            continue
+        relative_output = target.relative_to(output_root).as_posix()
+        if relative_output in withheld_paths or any(part.startswith(".env") or part.lower() in ("auth.json", "credentials.json", "secrets.json") for part in target.relative_to(output_root).parts):
+            continue
+        relative = target.relative_to(root).as_posix()
+        resolve_regular(relative)
+        declared_relatives.add(relative)
+
+for optional in ("output/environment.txt", "output/packaging-recovery.txt", "output/experiment-records.jsonl", "output/cpu-preparation.json",
+                 "output/research-plan.json", "output/progress.md", "output/rejected-research-plan.json"):
+    target = root / optional
+    if target.is_file() and not target.is_symlink():
+        paths.add(optional)
+
+# The working plan drives downstream parsing, even if the Agent forgot to list
+# it as evidence. Export it and its revisions independently of result.evidence.
+task_path = root / "input" / "task.json"
+if task_path.is_file():
+    task = json.loads(task_path.read_text(encoding="utf-8"))
+    if isinstance(task.get("workspacePlan"), dict) and task["workspacePlan"].get("version") in (1, 2):
+        resolve_regular("output/research-plan.json")
+        paths.add("output/research-plan.json")
+plan_history = root / "output" / "plan-history"
+if plan_history.is_dir() and not plan_history.is_symlink():
+    for revision in plan_history.glob("*.json"):
+        if revision.is_file() and not revision.is_symlink():
+            paths.add(revision.relative_to(root).as_posix())
+phase_history = root / "output" / "phase-history"
+if phase_history.is_dir() and not phase_history.is_symlink():
+    for receipt in phase_history.glob("*.json"):
+        resolve_regular(receipt.relative_to(root).as_posix())
+        paths.add(receipt.relative_to(root).as_posix())
+experiment_logs = root / "output" / "experiment-logs"
+if experiment_logs.is_dir() and not experiment_logs.is_symlink():
+    for log in experiment_logs.iterdir():
+        if log.name.endswith((".stdout.log", ".stderr.log")) and log.is_file() and not log.is_symlink():
+            relative = log.relative_to(root).as_posix()
+            resolve_regular(relative)
+            paths.add(relative)
+
+previous_external = {}
+if isinstance(previous_manifest, dict):
+    for descriptor in previous_manifest.get("externalObjects", []):
+        if not isinstance(descriptor, dict):
+            continue
+        relative = descriptor.get("path")
+        object_name = descriptor.get("object")
+        digest = descriptor.get("sha256")
+        size = descriptor.get("size")
+        if (
+            isinstance(relative, str)
+            and safe_relative(relative)
+            and isinstance(object_name, str)
+            and pathlib.PurePosixPath(object_name).name == object_name
+            and isinstance(digest, str)
+            and len(digest) == 64
+            and all(character in "0123456789abcdef" for character in digest)
+            and isinstance(size, int)
+            and size > 0
+        ):
+            previous_external[relative] = descriptor
+
+external = []
+inline_used = sum(resolve_regular(relative).stat().st_size for relative in paths)
+for relative in sorted(declared_relatives):
+    source = root / pathlib.PurePosixPath(relative)
+    if source.is_file() and not source.is_symlink():
+        size = source.stat().st_size
+        if relative in paths:
+            continue
+        if size <= inline_evidence_maximum_bytes and inline_used + size <= maximum_bytes:
+            paths.add(relative)
+            inline_used += size
+            continue
+        if not external_object_prefix:
+            raise SystemExit("large declared output requires CITEARK_EXTERNAL_OBJECT_PREFIX: " + relative)
+        digest = sha256_file(source)
+        external_target = pathlib.Path(external_object_prefix + "-" + digest + ".blob")
+        external_target.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source, external_target)
+        external.append({
+            "path": relative,
+            "size": size,
+            "sha256": digest,
+            "transport": "gcs-external",
+            "object": external_target.name,
+        })
+        continue
+    reusable = previous_external.get(relative)
+    if reusable is None:
+        raise SystemExit("publication path is not a regular file: " + relative)
+    external.append(reusable)
+
+descriptors = []
+total = 0
+for relative in sorted(paths):
+    target = resolve_regular(relative)
+    size = target.stat().st_size
+    total += size
+    if total > maximum_bytes:
+        raise SystemExit(
+            "publication result exceeds the configured byte boundary; large non-model outputs must use content-addressed object storage"
+        )
+    descriptors.append({
+        "path": relative,
+        "size": size,
+        "sha256": sha256_file(target),
+        "transport": "inline",
+    })
+
+manifest_path.write_text(
+    json.dumps({
+        "schemaVersion": "0.1",
+        "kind": "citeark.publication-result-export",
+        "contentPolicy": "scientific-tables-histories-declared-outputs-and-runner-audit",
+        "workspaceIncluded": False,
+        "runtimeHomeIncluded": False,
+        "byteSize": total,
+        "externalByteSize": sum(item["size"] for item in external),
+        "files": descriptors,
+        "externalObjects": external,
+    }, ensure_ascii=False, indent=2) + "\n",
+    encoding="utf-8",
+)
+paths.add("execution/result-export.json")
+
+destination.parent.mkdir(parents=True, exist_ok=True)
+with tarfile.open(destination, "w:gz", dereference=False) as archive:
+    for relative in sorted(paths):
+        archive.add(resolve_regular(relative), arcname=relative, recursive=False)
+`;
+
+// Keep the primary attempt diagnosis when exporting its diagnostic bundle also
+// fails. A missing research.json after a stalled Agent is a secondary failure.
+export const PUBLICATION_FAILURE_JQ = `
+. + {exitCode:$exitCode, publicationExitCode:$exitCode,
+     publicationFailureStage:$publicationFailureStage, finishedAt:$finishedAt}
+  + (if (.agentExitCode // 0) != 0 then {}
+     elif $storageExhausted == 1 then
+       {retryable:true, failureCategory:"infrastructure",
+        failureStage:$publicationFailureStage, failureCode:"infrastructure.storage_exhausted"}
+     else {retryable:false, failureCategory:"publication", failureStage:$publicationFailureStage}
+     end)
+`;
+
+export const PUBLICATION_FAILURE_EXPORT_PYTHON = String.raw`
+import io
+import json
+import os
+import pathlib
+import tarfile
+
+root = pathlib.Path(os.environ.get("CITEARK_JOB_ROOT", "/job")).resolve()
+destination = pathlib.Path(os.environ.get("CITEARK_RESULT_ARCHIVE", "/tmp/citeark-result.tar.gz")).resolve()
+candidates = [
+    "output/result.json",
+    "output/research-plan.json",
+    "output/progress.md",
+    "execution/trace.jsonl",
+    "execution/runner-events.jsonl",
+    "execution/claude-stderr.log",
+    "execution/provider-pro-relay.log",
+    "execution/network-router.log",
+    "execution/liguse-tunnel.log",
+    "execution/network-preflight.json",
+    "execution/runner-boundary.json",
+    "execution/runtime-budget.json",
+    "execution/agent-stalled.json",
+    "execution/paper-budget-exhausted.json",
+    "execution/publication-stderr.log",
+    "execution/checkpoint.log",
+    "execution/disk-usage.jsonl",
+    "execution/result-ready.json",
+]
+execution = root / "execution"
+if execution.is_dir():
+    candidates.extend(
+        target.relative_to(root).as_posix()
+        for target in execution.glob("remote-attempt-*.json")
+        if target.is_file() and not target.is_symlink()
+    )
+
+maximum_file_bytes = int(os.environ.get("CITEARK_FAILURE_FILE_MAX_BYTES", str(8 * 1024 * 1024)))
+maximum_total_bytes = int(os.environ.get("CITEARK_FAILURE_TOTAL_MAX_BYTES", str(64 * 1024 * 1024)))
+destination.parent.mkdir(parents=True, exist_ok=True)
+destination.unlink(missing_ok=True)
+retained = []
+retained_bytes = 0
+with tarfile.open(destination, "w:gz", dereference=False) as archive:
+    for relative in candidates:
+        target = (root / relative).resolve()
+        if root in target.parents and target.is_file() and not target.is_symlink():
+            remaining = maximum_total_bytes - retained_bytes
+            if remaining <= 0:
+                break
+            size = target.stat().st_size
+            keep = min(size, maximum_file_bytes, remaining)
+            with target.open("rb") as source:
+                if size > keep:
+                    source.seek(size - keep)
+                payload = source.read(keep)
+            info = tarfile.TarInfo(relative + (".tail" if size > keep else ""))
+            info.size = len(payload)
+            info.mode = 0o600
+            archive.addfile(info, io.BytesIO(payload))
+            retained_bytes += len(payload)
+            retained.append({"path": relative, "sourceBytes": size, "retainedBytes": len(payload), "truncated": size > keep})
+    manifest = json.dumps({
+        "schemaVersion": "0.1",
+        "kind": "citeark.bounded-publication-failure-export",
+        "maximumFileBytes": maximum_file_bytes,
+        "maximumTotalBytes": maximum_total_bytes,
+        "retainedBytes": retained_bytes,
+        "files": retained,
+    }, ensure_ascii=False, indent=2).encode("utf-8") + b"\n"
+    info = tarfile.TarInfo("execution/failure-export.json")
+    info.size = len(manifest)
+    info.mode = 0o600
+    archive.addfile(info, io.BytesIO(manifest))
+`;
+
+export function buildCheckpointedWorkerScript({
+  runId = "unknown-run",
+  executor = "gcp-batch",
+  initialInvocation,
+  resumeInvocation,
+  attempt,
+  stagePath,
+  resultPath,
+  liveTracePath,
+  streamTrace = false,
+  checkpointPrefixPath,
+  checkpointStatusPath,
+  externalObjectPrefixPath = `${resultPath}.object`,
+  restoreCheckpointPrefixPath = checkpointPrefixPath,
+  checkpointPolicy,
+  runtimeBudgetSeconds = 0,
+  completionRelativePath = "output/result.json",
+  completionHasEvidence = true,
+  completionValidatorRelativePath = null,
+  completionSuccessJq = '.execution.status == "succeeded"',
+  preserveRebuildableCache = false,
+  finalCheckpointKind = "critical",
+  finalCheckpointReason = "publication-ready",
+  allowCpuHandoff = false,
+  providerRelay = false,
+  providerRelayPath = "/opt/citeark/codex-pro-relay.mjs",
+  agentStallTimeoutSeconds = 0,
+  restoreCheckpointOnStart = false,
+  reuseCompletedResultOnRestore = true,
+}) {
+  const initialPromptPath = `/tmp/citeark-active-prompts/attempt-${attempt}.txt`;
+  const resumePromptPath = `/tmp/citeark-active-prompts/attempt-${attempt}-resume.txt`;
+  const initialCommand = commandLine(initialInvocation, initialPromptPath);
+  const resumeCommand = commandLine(resumeInvocation, resumePromptPath);
+  const freshCodexCommand = commandLine(freshCodexInvocation(initialInvocation), initialPromptPath);
+  const enabled = checkpointPolicy.enabled ? "1" : "0";
+  const packageCacheRoot = executor === "autodl-pro"
+    ? "/opt/citeark/cache"
+    : "/job/runtime-cache";
+  const agentEnvironment = [
+    ...(providerRelay ? ["OPENAI_API_KEY=citeark-local-relay", "CITEARK_API_KEY=citeark-local-relay"] : []),
+    "HOME=/job/runtime-home",
+    "PATH=/job/runtime-venv/bin:/opt/citeark/venv/bin:/opt/citeark/cargo/bin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    "VIRTUAL_ENV=/job/runtime-venv",
+    "UV_PROJECT_ENVIRONMENT=/job/runtime-venv",
+    "UV_CONFIG_FILE=/dev/null",
+    'PIP_INDEX_URL="$PYTHON_PACKAGE_INDEX"',
+    'UV_INDEX="$PYTHON_PACKAGE_INDEX"',
+    "UV_INDEX_STRATEGY=first-index",
+    "PIP_DEFAULT_TIMEOUT=120",
+    "PIP_RETRIES=8",
+    "UV_HTTP_TIMEOUT=120",
+    "UV_HTTP_RETRIES=8",
+    'HF_ENDPOINT="$HUGGINGFACE_ENDPOINT"',
+    "HF_HUB_ETAG_TIMEOUT=30",
+    "HF_HUB_DOWNLOAD_TIMEOUT=120",
+    "UV_PYTHON_INSTALL_DIR=/job/runtime-cache/uv-python",
+    `UV_CACHE_DIR=${packageCacheRoot}/uv`,
+    `PIP_CACHE_DIR=${packageCacheRoot}/pip`,
+    `CARGO_HOME=${packageCacheRoot}/cargo`,
+    "CARGO_NET_GIT_FETCH_WITH_CLI=true",
+    "XDG_CACHE_HOME=/job/runtime-cache/xdg",
+    "HF_HOME=/job/runtime-cache/huggingface",
+    "TORCH_HOME=/job/runtime-cache/torch",
+  ].join(" ");
+  return [
+    "set -Eeuo pipefail",
+    "JOB_ROOT=/job",
+    `RUN_ID=${shellQuote(runId)}`,
+    `STAGE=${shellQuote(stagePath)}`,
+    `RESULT=${shellQuote(resultPath)}`,
+    `CHECKPOINT_PREFIX=${shellQuote(checkpointPrefixPath)}`,
+    `CHECKPOINT_STATUS=${shellQuote(checkpointStatusPath)}`,
+    `EXTERNAL_OBJECT_PREFIX=${shellQuote(externalObjectPrefixPath)}`,
+    `RESTORE_CHECKPOINT_PREFIX=${shellQuote(restoreCheckpointPrefixPath)}`,
+    `CHECKPOINT_ENABLED=${enabled}`,
+    `CHECKPOINT_CRITICAL_INTERVAL=${checkpointPolicy.criticalIntervalSeconds}`,
+    `CHECKPOINT_FULL_INTERVAL=${checkpointPolicy.fullIntervalSeconds}`,
+    `CHECKPOINT_RETENTION=${checkpointPolicy.retention}`,
+    `TOTAL_RUNTIME_BUDGET_SECONDS=${Math.max(0, Math.floor(Number(runtimeBudgetSeconds) || 0))}`,
+    `RESTORE_CHECKPOINT_ON_START=${restoreCheckpointOnStart ? "1" : "0"}`,
+    `REUSE_COMPLETED_RESULT_ON_RESTORE=${reuseCompletedResultOnRestore ? "1" : "0"}`,
+    "RESULT_READY=/job/execution/result-ready.json",
+    "INVALIDATED_RESULT_SHA256=",
+    `COMPLETION=${shellQuote(`/job/${completionRelativePath}`)}`,
+    `COMPLETION_RELATIVE=${shellQuote(completionRelativePath)}`,
+    `COMPLETION_HAS_EVIDENCE=${completionHasEvidence ? "1" : "0"}`,
+    `COMPLETION_VALIDATOR=${shellQuote(completionValidatorRelativePath ? `/job/${completionValidatorRelativePath}` : "")}`,
+    `COMPLETION_SUCCESS_JQ=${shellQuote(completionSuccessJq)}`,
+    `PRESERVE_REBUILDABLE_CACHE=${preserveRebuildableCache ? "1" : "0"}`,
+    `FINAL_CHECKPOINT_KIND=${shellQuote(finalCheckpointKind)}`,
+    `FINAL_CHECKPOINT_REASON=${shellQuote(finalCheckpointReason)}`,
+    `ALLOW_CPU_HANDOFF=${allowCpuHandoff ? "1" : "0"}`,
+    `PROVIDER_RELAY=${providerRelay ? "1" : "0"}`,
+    `PROVIDER_RELAY_PATH=${shellQuote(providerRelayPath)}`,
+    `AGENT_STALL_TIMEOUT_SECONDS=${Math.max(0, Math.floor(Number(agentStallTimeoutSeconds) || 0))}`,
+    "INFRASTRUCTURE_RETRY=${BATCH_TASK_RETRY_ATTEMPT:-0}",
+    "CHECKPOINT_STOP=/tmp/citeark-checkpoint-stop",
+    "CHECKPOINT_LOCK=/tmp/citeark-checkpoint-lock",
+    "AGENT_PID_FILE=/tmp/citeark-agent.pid",
+    "AGENT_STALL_STATE=/job/execution/agent-stalled.json",
+    "AGENT_PID=",
+    "AGENT_STALLED=0",
+    "AGENT_TIMED_OUT=0",
+    "AGENT_RUN_USER=",
+    "RUNTIME_VIRTUAL_ENV=/job/runtime-venv",
+    "SUPERVISOR_PYTHON=/opt/citeark/venv/bin/python",
+    "PYTHON_PACKAGE_INDEX=",
+    "HUGGINGFACE_ENDPOINT=",
+    "RUNTIME_BUDGET_STATE=/job/execution/runtime-budget.json",
+    "PUBLICATION_RESERVE=/job/execution/.publication-reserve",
+    "RUNTIME_BUDGET_BASE_SECONDS=0",
+    "RUNTIME_BUDGET_SEGMENT_STARTED_EPOCH=0",
+    "PROVIDER_RELAY_PID=",
+    shellFunctions(executor),
+    "mkdir -p \"$JOB_ROOT\"",
+    "cp \"$STAGE\" /tmp/citeark-stage.tar.gz",
+    "tar -xzf /tmp/citeark-stage.tar.gz -C \"$JOB_ROOT\"",
+    "mkdir -p /job/output /job/execution /job/runtime-home/codex /job/assets /job/runtime-cache/cargo /job/runtime-cache/uv /job/runtime-cache/uv-python /job/runtime-cache/pip /job/runtime-cache/xdg /job/runtime-cache/huggingface /job/runtime-cache/torch",
+    "fallocate -l 128M \"$PUBLICATION_RESERVE\" 2>/dev/null || dd if=/dev/zero of=\"$PUBLICATION_RESERVE\" bs=1M count=128 status=none",
+    // Checkpoints contain the previous phase's execution/prompts. Keep this
+    // coordinator's invocation outside /job before restoring that history.
+    "# BEGIN current invocation prompts",
+    "mkdir -p /tmp/citeark-active-prompts",
+    `cp /job/execution/prompts/attempt-${attempt}.txt ${initialPromptPath}`,
+    `cp /job/execution/prompts/attempt-${attempt}-resume.txt ${resumePromptPath}`,
+    "# END current invocation prompts",
+    "if [ -f /job/input/runner-codex-capacity-retry.mjs ]; then cp /job/input/runner-codex-capacity-retry.mjs /tmp/citeark-codex-capacity-retry.mjs; fi",
+    "initialize_scientific_runtime",
+    "cp /job/input/runner-codex-account.mjs /tmp/citeark-codex-account.mjs",
+    "trap 'node /tmp/citeark-codex-account.mjs close' EXIT",
+    "hydrate_provider_secret",
+    "if [ -f /job/input/runner-paper-budget.json ]; then chown root:root /job/input/runner-paper-budget.json; chmod 0600 /job/input/runner-paper-budget.json; fi",
+    "if [ \"$PROVIDER_RELAY\" = 1 ]; then start_provider_relay; fi",
+    "RESTORED_CHECKPOINT=0",
+    "if [ \"$CHECKPOINT_ENABLED\" = 1 ] && { [ \"$INFRASTRUCTURE_RETRY\" -gt 0 ] || [ \"$RESTORE_CHECKPOINT_ON_START\" = 1 ]; }; then restore_checkpoints; fi",
+    `if [ -s "$AGENT_STALL_STATE" ]; then mv "$AGENT_STALL_STATE" "/job/execution/agent-stalled-before-a${attempt}-r$INFRASTRUCTURE_RETRY.json"; fi`,
+    "initialize_runtime_budget",
+    "if [ \"$RESTORED_CHECKPOINT\" = 1 ] && [ \"$REUSE_COMPLETED_RESULT_ON_RESTORE\" != 1 ]; then",
+    "  if [ -s \"$COMPLETION\" ]; then INVALIDATED_RESULT_SHA256=\"$(sha256sum \"$COMPLETION\" | cut -d' ' -f1)\"; fi",
+    "  if [ -n \"$INVALIDATED_RESULT_SHA256\" ]; then mkdir -p /job/output/phase-history; cp \"$COMPLETION\" \"/job/output/phase-history/$INVALIDATED_RESULT_SHA256.json\"; fi",
+    "  rm -f \"$RESULT_READY\"",
+    "  printf '{\"type\":\"citeark.completed_result_invalidated\",\"reason\":\"semantic-validation-retry\",\"timestamp\":\"%s\"}\\n' \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> /job/execution/trace.jsonl",
+    "fi",
+    "configure_runner_boundary",
+    "BUDGET_WATCH_PID=",
+    "rm -f /job/execution/paper-budget-exhausted.json",
+    "if [ \"${CITEARK_PAPER_BUDGET_REQUIRED:-0}\" = 1 ]; then",
+
+    "  ( while true; do if [ -s /job/execution/paper-budget-exhausted.json ]; then pkill -TERM -u node || true; sleep 15; pkill -KILL -u node || true; break; fi; sleep 2; done ) &",
+    "  BUDGET_WATCH_PID=$!",
+    "fi",
+    "if ! ensure_disk_headroom 20 pre-agent; then",
+    `  jq -nc --argjson attempt ${attempt} --argjson infrastructureRetry "$INFRASTRUCTURE_RETRY" --arg finishedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{attempt:$attempt,exitCode:75,agentExitCode:0,infrastructureRetry:$infrastructureRetry,restoredCheckpoint:false,timedOut:false,retryable:true,failureCategory:"infrastructure",failureStage:"setup",failureCode:"infrastructure.storage_headroom_insufficient",finishedAt:$finishedAt}' > /job/execution/remote-attempt-${attempt}.json`,
+    "  release_rebuildable_runtime_cache",
+    "  rm -f \"$PUBLICATION_RESERVE\" /tmp/citeark-result.tar.gz",
+    `  CITEARK_JOB_ROOT=/job CITEARK_RESULT_ARCHIVE=/tmp/citeark-result.tar.gz "$SUPERVISOR_PYTHON" -c ${shellQuote(PUBLICATION_FAILURE_EXPORT_PYTHON)}`,
+    "  cp /tmp/citeark-result.tar.gz \"$RESULT\"",
+    "  sync",
+    "  exit 0",
+    "fi",
+    `printf '{"type":"citeark.attempt_started","attempt":${attempt},"executor":${JSON.stringify(executor)},"infrastructureRetry":%s,"restoredCheckpoint":%s,"timestamp":"%s"}\\n' "$INFRASTRUCTURE_RETRY" "$RESTORED_CHECKPOINT" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl`,
+    "rm -f \"$CHECKPOINT_STOP\" \"$AGENT_PID_FILE\" \"$AGENT_STALL_STATE\"",
+    "checkpoint_loop & CHECKPOINT_PID=$!",
+    "trap 'handle_termination' TERM INT",
+    "set +e",
+    "if [ \"$RESTORED_CHECKPOINT\" = 1 ] && [ \"$REUSE_COMPLETED_RESULT_ON_RESTORE\" = 1 ] && result_ready_matches; then",
+    "  printf '{\"type\":\"citeark.completed_result_reused\",\"infrastructureRetry\":%s,\"timestamp\":\"%s\"}\\n' \"$INFRASTRUCTURE_RETRY\" \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> /job/execution/trace.jsonl",
+    "  AGENT_EXIT=0",
+    "else",
+    "  rm -f \"$RESULT_READY\"",
+    "  if [ \"$RESTORED_CHECKPOINT\" = 1 ]; then AGENT_COMMAND=" + shellQuote(resumeCommand) + "; else AGENT_COMMAND=" + shellQuote(initialCommand) + "; fi",
+    "  if [ -n \"${CITEARK_CODEX_ACCOUNT_ID:-}\" ] && ! find /job/runtime-home/codex/sessions -name '*.jsonl' -print -quit 2>/dev/null | grep -q .; then AGENT_COMMAND=" + shellQuote(freshCodexCommand) + "; fi",
+    "  cd /job/workspace/repository",
+    "  REMAINING_RUNTIME_SECONDS=\"$(remaining_runtime_budget_seconds)\"",
+    "  if [ \"$TOTAL_RUNTIME_BUDGET_SECONDS\" -gt 0 ] && [ \"$REMAINING_RUNTIME_SECONDS\" -le 0 ]; then",
+    "    AGENT_EXIT=124",
+    "    AGENT_TIMED_OUT=1",
+    "    printf '{\"type\":\"citeark.runtime_budget_exhausted\",\"runtimeBudgetSeconds\":%s,\"timestamp\":\"%s\"}\\n' \"$TOTAL_RUNTIME_BUDGET_SECONDS\" \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\" >> /job/execution/trace.jsonl",
+    "  else",
+    `  RUNNER_EVENT_ID="$RUN_ID:${attempt}:$INFRASTRUCTURE_RETRY"`,
+    "  RUNNER_STARTED_AT=\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"",
+    `  jq -nc --arg eventId "$RUNNER_EVENT_ID" --arg runId "$RUN_ID" --argjson attempt ${attempt} --arg executor ${shellQuote(executor)} --arg command "$AGENT_COMMAND" --arg startedAt "$RUNNER_STARTED_AT" --arg captureBoundary "$RUNNER_CAPTURE_BOUNDARY" '{schemaVersion:"0.1",type:"runner.process_started",$eventId,$runId,$attempt,$executor,command:"/bin/bash",args:["-lc",$command],workingDirectory:"/job/workspace/repository",$captureBoundary,$startedAt}' >> /job/execution/runner-events.jsonl`,
+    "  if [ -n \"$AGENT_RUN_USER\" ]; then",
+    `    if [ "$TOTAL_RUNTIME_BUDGET_SECONDS" -gt 0 ]; then timeout --signal=TERM --kill-after=15s "\${REMAINING_RUNTIME_SECONDS}s" runuser -u "$AGENT_RUN_USER" -- env ${agentEnvironment} /bin/bash -lc "exec $AGENT_COMMAND" >> /job/execution/trace.jsonl 2>> /job/execution/claude-stderr.log & else runuser -u "$AGENT_RUN_USER" -- env ${agentEnvironment} /bin/bash -lc "exec $AGENT_COMMAND" >> /job/execution/trace.jsonl 2>> /job/execution/claude-stderr.log & fi`,
+    "  else",
+    "    if [ \"$TOTAL_RUNTIME_BUDGET_SECONDS\" -gt 0 ]; then timeout --signal=TERM --kill-after=15s \"${REMAINING_RUNTIME_SECONDS}s\" /bin/bash -lc \"exec $AGENT_COMMAND\" >> /job/execution/trace.jsonl 2>> /job/execution/claude-stderr.log & else /bin/bash -lc \"exec $AGENT_COMMAND\" >> /job/execution/trace.jsonl 2>> /job/execution/claude-stderr.log & fi",
+    "  fi",
+    "  AGENT_PID=$!",
+    "  printf '%s\\n' \"$AGENT_PID\" > \"$AGENT_PID_FILE\"",
+    ...(streamTrace ? ['  tail -c +1 --pid="$AGENT_PID" -f /job/execution/trace.jsonl &', '  LIVE_TRACE_PID=$!'] : []),
+    ...(liveTracePath ? [
+      `  (while kill -0 "$AGENT_PID" 2>/dev/null; do cp /job/execution/trace.jsonl ${shellQuote(liveTracePath)} 2>/dev/null || true; sleep 2; done) &`,
+      '  LIVE_TRACE_PID=$!',
+    ] : []),
+    "  wait \"$AGENT_PID\"",
+    "  AGENT_EXIT=$?",
+    ...(streamTrace ? ['  wait "$LIVE_TRACE_PID" || true'] : []),
+    ...(liveTracePath ? ['  kill "$LIVE_TRACE_PID" 2>/dev/null || true', `  cp /job/execution/trace.jsonl ${shellQuote(liveTracePath)} 2>/dev/null || true`] : []),
+    "  if [ -s \"$AGENT_STALL_STATE\" ]; then AGENT_STALLED=1; AGENT_TIMED_OUT=1; AGENT_EXIT=124; fi",
+    "  if [ \"$AGENT_EXIT\" -eq 124 ]; then AGENT_TIMED_OUT=1; fi",
+    "  RUNNER_FINISHED_AT=\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\"",
+    `  jq -nc --arg eventId "$RUNNER_EVENT_ID" --arg runId "$RUN_ID" --argjson attempt ${attempt} --arg executor ${shellQuote(executor)} --argjson exitCode "$AGENT_EXIT" --argjson timedOut "$AGENT_TIMED_OUT" --arg startedAt "$RUNNER_STARTED_AT" --arg finishedAt "$RUNNER_FINISHED_AT" '{schemaVersion:"0.1",type:"runner.process_finished",$eventId,$runId,$attempt,$executor,$exitCode,signal:null,$timedOut,$startedAt,$finishedAt}' >> /job/execution/runner-events.jsonl`,
+    "  rm -f \"$AGENT_PID_FILE\"",
+    "  AGENT_PID=",
+    "  fi",
+    "fi",
+    "set -e",
+    "touch \"$CHECKPOINT_STOP\"",
+    "if [ -n \"${CHECKPOINT_PID:-}\" ]; then wait \"$CHECKPOINT_PID\" || true; fi",
+    "stop_provider_relay",
+    "if [ -n \"${BUDGET_WATCH_PID:-}\" ]; then kill \"$BUDGET_WATCH_PID\" 2>/dev/null || true; fi",
+    "write_runtime_budget || true",
+    "if [ \"$AGENT_EXIT\" -eq 0 ] && [ -n \"$COMPLETION_VALIDATOR\" ]; then",
+    "  if ! \"$SUPERVISOR_PYTHON\" \"$COMPLETION_VALIDATOR\" /job/input/asset-preparation-plan.json \"$COMPLETION\" >> /job/execution/completion-validation.log 2>&1; then AGENT_EXIT=65; fi",
+    "fi",
+    "if [ \"$AGENT_EXIT\" -eq 0 ]; then mark_result_ready agent-completed || true; fi",
+    "RECOVERY_NEEDED=0",
+    "if [ \"$ALLOW_CPU_HANDOFF\" = 1 ] && jq -e '.schemaVersion == \"2.0\" and .status == \"handoff\" and .nextPhase == \"cpu\"' \"$COMPLETION\" >/dev/null 2>&1; then FINAL_CHECKPOINT_KIND=full; FINAL_CHECKPOINT_REASON=research-handoff; PRESERVE_REBUILDABLE_CACHE=1; fi",
+    "if [ \"$AGENT_EXIT\" -ne 0 ] || [ ! -s \"$COMPLETION\" ]; then RECOVERY_NEEDED=1; elif ! jq -e \"$COMPLETION_SUCCESS_JQ\" \"$COMPLETION\" >/dev/null 2>&1; then RECOVERY_NEEDED=1; fi",
+    "if [ \"$CHECKPOINT_ENABLED\" = 1 ] && [ \"$RECOVERY_NEEDED\" = 1 ]; then checkpoint_state full target-recovery || true; fi",
+    "if [ \"$CHECKPOINT_ENABLED\" = 1 ] && [ \"$RECOVERY_NEEDED\" = 0 ] && [ \"$PRESERVE_REBUILDABLE_CACHE\" = 1 ]; then checkpoint_state \"$FINAL_CHECKPOINT_KIND\" \"$FINAL_CHECKPOINT_REASON\" || true; fi",
+    `jq -nc --argjson attempt ${attempt} --argjson exitCode "$AGENT_EXIT" --argjson infrastructureRetry "$INFRASTRUCTURE_RETRY" --argjson restoredCheckpoint "$RESTORED_CHECKPOINT" --argjson timedOut "$AGENT_TIMED_OUT" --argjson agentStalled "$AGENT_STALLED" --argjson runtimeBudgetSeconds "$TOTAL_RUNTIME_BUDGET_SECONDS" --argjson consumedRuntimeSeconds "$(runtime_budget_consumed_seconds)" --arg finishedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" '{attempt:$attempt,exitCode:$exitCode,agentExitCode:$exitCode,infrastructureRetry:$infrastructureRetry,restoredCheckpoint:$restoredCheckpoint,timedOut:$timedOut,agentStalled:$agentStalled,runtimeBudgetSeconds:$runtimeBudgetSeconds,consumedRuntimeSeconds:$consumedRuntimeSeconds,finishedAt:$finishedAt} + (if $agentStalled == 1 then {failureCategory:"timeout",failureStage:"provider",failureCode:"agent.effective_progress_stalled",retryable:false} elif $timedOut == 1 then {failureCategory:"timeout",failureStage:"execution",failureCode:"execution.runtime_budget_exhausted",retryable:false} else {} end)' > /job/execution/remote-attempt-${attempt}.json`,
+    `printf '{"type":"citeark.attempt_finished","attempt":${attempt},"executor":${JSON.stringify(executor)},"exitCode":%s,"infrastructureRetry":%s,"timestamp":"%s"}\\n' "$AGENT_EXIT" "$INFRASTRUCTURE_RETRY" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl`,
+    "if [ \"$PRESERVE_REBUILDABLE_CACHE\" != 1 ]; then release_rebuildable_runtime_cache; fi",
+    "PUBLICATION_STAGE=workspace-audit",
+    "PUBLICATION_EXIT=0",
+    ": > /job/execution/publication-stderr.log",
+    "if ! ensure_disk_headroom 1 pre-publication; then PUBLICATION_STAGE=storage-headroom; PUBLICATION_EXIT=75; printf '%s\\n' 'No space left on device: publication headroom below 1 GiB' >> /job/execution/publication-stderr.log; fi",
+    `if [ "$PUBLICATION_EXIT" -eq 0 ]; then CITEARK_JOB_ROOT=/job "$SUPERVISOR_PYTHON" -c ${shellQuote(WORKSPACE_AUDIT_PYTHON)} 2>> /job/execution/publication-stderr.log || PUBLICATION_EXIT=$?; fi`,
+    "if [ \"$PUBLICATION_EXIT\" -eq 0 ]; then",
+    "  PUBLICATION_STAGE=result-export",
+    `  CITEARK_JOB_ROOT=/job CITEARK_RESULT_ARCHIVE=/tmp/citeark-result.tar.gz CITEARK_COMPLETION_RELATIVE="$COMPLETION_RELATIVE" CITEARK_EXTERNAL_OBJECT_PREFIX="$EXTERNAL_OBJECT_PREFIX" "$SUPERVISOR_PYTHON" -c ${shellQuote(PUBLICATION_EXPORT_PYTHON)} 2>> /job/execution/publication-stderr.log || PUBLICATION_EXIT=$?`,
+    "fi",
+    "if [ \"$PUBLICATION_EXIT\" -ne 0 ]; then",
+    "  STORAGE_EXHAUSTED=0",
+    "  if grep -Eqi 'No space left on device|ENOSPC|storage headroom' /job/execution/publication-stderr.log; then STORAGE_EXHAUSTED=1; fi",
+    `  jq --argjson exitCode "$PUBLICATION_EXIT" --argjson storageExhausted "$STORAGE_EXHAUSTED" --arg publicationFailureStage "$PUBLICATION_STAGE" --arg finishedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" ${shellQuote(PUBLICATION_FAILURE_JQ)} /job/execution/remote-attempt-${attempt}.json > /job/execution/remote-attempt-${attempt}.json.tmp`,
+    `  mv /job/execution/remote-attempt-${attempt}.json.tmp /job/execution/remote-attempt-${attempt}.json`,
+    "  rm -f /tmp/citeark-result.tar.gz \"$PUBLICATION_RESERVE\"",
+    "  if [ \"$PRESERVE_REBUILDABLE_CACHE\" != 1 ]; then release_rebuildable_runtime_cache; fi",
+    `  CITEARK_JOB_ROOT=/job CITEARK_RESULT_ARCHIVE=/tmp/citeark-result.tar.gz "$SUPERVISOR_PYTHON" -c ${shellQuote(PUBLICATION_FAILURE_EXPORT_PYTHON)}`,
+    "  cp /tmp/citeark-result.tar.gz \"$RESULT\"",
+    "  sync",
+    "  exit 0",
+    "fi",
+    "rm -f \"$PUBLICATION_RESERVE\"",
+    "if [ \"$CHECKPOINT_ENABLED\" = 1 ] && [ \"$PRESERVE_REBUILDABLE_CACHE\" != 1 ]; then checkpoint_state \"$FINAL_CHECKPOINT_KIND\" \"$FINAL_CHECKPOINT_REASON\" || true; fi",
+    "cp /tmp/citeark-result.tar.gz \"$RESULT\"",
+    "sync",
+    "exit 0",
+  ].join("\n");
+}
+
+function commandLine(invocation, promptPath) {
+  const args = Array.isArray(invocation?.args) ? [...invocation.args] : [];
+  const command = invocation.command === "codex" && invocation.capacityRecovery
+    ? ["node", "/tmp/citeark-codex-capacity-retry.mjs", String(invocation.capacityRecovery.retryDelayMs), String(invocation.capacityRecovery.maxRetries)]
+    : [invocation.command];
+  if (typeof invocation?.promptArgument === "string") {
+    if (args.at(-1) !== invocation.promptArgument) {
+      throw new TypeError("Agent invocation 的 promptArgument 必须是最后一个命令参数");
+    }
+    args.pop();
+    const prefix = [...command, ...args].map(shellQuote).join(" ");
+    return `${prefix} "$(cat ${shellQuote(promptPath)})"`;
+  }
+  return [...command, ...args].map(shellQuote).join(" ");
+}
+
+function shellFunctions(executor) {
+  const unavailableBoundary = `${executor}-supervisor-unavailable`;
+  const separateUidBoundary = `${executor}-supervisor-separate-uid`;
+  return `
+initialize_scientific_runtime() {
+  if [ ! -x /opt/citeark/create-runtime-venv.sh ] || [ ! -x "$SUPERVISOR_PYTHON" ]; then
+    printf '%s\n' "CiteArk 科学运行基线不完整，拒绝启动 Agent" >&2
+    return 70
+  fi
+  PYTHON_PACKAGE_INDEX="\${CITEARK_PYTHON_PACKAGE_INDEX:-\${PIP_INDEX_URL:-https://pypi.org/simple}}"
+  HUGGINGFACE_ENDPOINT="\${CITEARK_HUGGINGFACE_ENDPOINT:-\${HF_ENDPOINT:-https://huggingface.co}}"
+  /opt/citeark/create-runtime-venv.sh "$RUNTIME_VIRTUAL_ENV"
+  export VIRTUAL_ENV="$RUNTIME_VIRTUAL_ENV"
+  export UV_PROJECT_ENVIRONMENT="$RUNTIME_VIRTUAL_ENV"
+  export PATH="$RUNTIME_VIRTUAL_ENV/bin:/opt/citeark/venv/bin:/opt/citeark/cargo/bin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
+  export PIP_INDEX_URL="$PYTHON_PACKAGE_INDEX"
+  export UV_INDEX="$PYTHON_PACKAGE_INDEX"
+  export UV_INDEX_STRATEGY=first-index
+  export HF_ENDPOINT="$HUGGINGFACE_ENDPOINT"
+  "$RUNTIME_VIRTUAL_ENV/bin/python" - <<'PY'
+import numpy
+import scipy
+import torch
+
+assert torch.version.cuda == "12.8", torch.version.cuda
+print("CiteArk scientific task environment: ready")
+PY
+}
+
+configure_runner_boundary() {
+  mkdir -p /job/execution
+  if [ "$(id -u)" != 0 ] || ! id node >/dev/null 2>&1 || ! command -v runuser >/dev/null 2>&1; then
+    jq -nc --arg captureBoundary ${shellQuote(unavailableBoundary)} '{schemaVersion:"0.1",$captureBoundary,agentCanWriteAuditDirectory:true}' > /job/execution/runner-boundary.json
+    printf '%s\n' ${shellQuote(`${executor} runner 无法建立独立 UID 审计边界，拒绝启动 Agent`)} >&2
+    return 1
+  fi
+  chmod 0711 /job
+  chown -R node:node /job/workspace /job/output /job/runtime-home /job/assets /job/runtime-cache /job/runtime-venv
+  chown root:node /job/execution
+  chmod 0710 /job/execution
+  if ! runuser -u node -- env HOME=/job/runtime-home UV_CONFIG_FILE=/dev/null /bin/bash -lc 'mkdir -p "$HOME/.local/share/opencode" && test -w "$HOME/.local/share/opencode" && test -w /job/assets && test -w /job/runtime-cache && test -w /job/runtime-venv && test -w /job/runtime-venv/lib/python3.12/site-packages'; then
+    printf '%s\n' ${shellQuote(`${executor} runner 的低权限 Agent 无法访问可写运行目录，拒绝启动`)} >&2
+    return 1
+  fi
+  AGENT_RUN_USER=node
+  RUNNER_CAPTURE_BOUNDARY=${shellQuote(separateUidBoundary)}
+  jq -nc --arg captureBoundary "$RUNNER_CAPTURE_BOUNDARY" --arg agentUser "\${AGENT_RUN_USER:-$(id -un)}" \\
+    --arg separateUidBoundary ${shellQuote(separateUidBoundary)} \\
+    '{schemaVersion:"0.1",$captureBoundary,$agentUser,runnerUser:(env.USER // "root"),agentCanWriteAuditDirectory:($captureBoundary != $separateUidBoundary)}' \\
+    > /job/execution/runner-boundary.json
+}
+
+record_disk_usage() {
+  local stage="$1" available_kb used_kb total_kb
+  read -r total_kb used_kb available_kb < <(df -Pk /job | awk 'NR==2 {print $2, $3, $4}')
+  jq -nc \
+    --arg stage "$stage" \
+    --arg recordedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --argjson totalBytes "$((total_kb * 1024))" \
+    --argjson usedBytes "$((used_kb * 1024))" \
+    --argjson availableBytes "$((available_kb * 1024))" \
+    '{schemaVersion:"0.1",$stage,$recordedAt,$totalBytes,$usedBytes,$availableBytes}' \
+    >> /job/execution/disk-usage.jsonl
+  printf '%s\n' "$available_kb"
+}
+
+ensure_disk_headroom() {
+  local minimum_gib="$1" stage="$2" available_kb
+  available_kb="$(record_disk_usage "$stage")"
+  [ "$available_kb" -ge "$((minimum_gib * 1024 * 1024))" ]
+}
+
+release_rebuildable_runtime_cache() {
+  set +e
+  find /job/runtime-cache /job/assets -mindepth 1 -maxdepth 1 -exec rm -rf -- {} + 2>/dev/null
+  rm -rf /job/runtime-venv /job/workspace/venv /job/workspace/runtime-venv \
+    /job/workspace/repository/.venv /job/workspace/repository/venv \
+    /job/runtime-home/.cache /job/runtime-home/.npm \
+    /job/runtime-home/.local/share/uv /job/runtime-home/.local/share/pnpm \
+    /job/runtime-home/.bun/install/cache /job/runtime-home/.config/opencode/node_modules
+  record_disk_usage post-cache-release >/dev/null 2>&1 || true
+  set -e
+}
+
+hydrate_provider_secret() {
+  if [ -n "\${CITEARK_CODEX_ACCOUNT_ID:-}" ]; then
+    unset OPENAI_API_KEY OPENAI_BASE_URL
+    node /tmp/citeark-codex-account.mjs open
+    return $?
+  fi
+  local credential_name="\${CITEARK_PROVIDER_SECRET_ENV_NAME:-}"
+  local secret_resource="\${CITEARK_PROVIDER_SECRET_RESOURCE:-}"
+  local credential_url="\${CITEARK_PROVIDER_CREDENTIAL_URL:-}"
+  local credential_token="\${CITEARK_PROVIDER_CREDENTIAL_TOKEN:-}"
+  local access_token encoded secret_value
+  if [ -z "$credential_name" ]; then
+    printf '%s\n' "运行时密钥环境变量名缺失" >&2
+    return 1
+  fi
+  case "$credential_name" in
+    ANTHROPIC_API_KEY|OPENAI_API_KEY|DEEPSEEK_API_KEY|CITEARK_API_KEY) ;;
+    *) printf '%s\n' "运行时密钥环境变量名无效" >&2; return 1 ;;
+  esac
+  if [ -n "$(printenv "$credential_name" 2>/dev/null)" ]; then
+    return 0
+  fi
+  if [ -n "$credential_url" ] || [ -n "$credential_token" ]; then
+    if [ -z "$credential_url" ] || [ -z "$credential_token" ]; then
+      printf '%s\n' "BYOK 凭据代理配置不完整" >&2
+      return 1
+    fi
+    encoded="$(curl --fail --silent --show-error \\
+      -H "Authorization: Bearer $credential_token" \\
+      -H 'Accept: application/json' \\
+      "$credential_url" \\
+      | jq -er '.data')"
+  elif [ -z "$secret_resource" ]; then
+    printf '%s\n' "GCP Batch 运行时密钥引用不完整" >&2
+    return 1
+  else
+    access_token="$(curl --fail --silent --show-error \\
+      -H 'Metadata-Flavor: Google' \\
+      'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token' \\
+      | jq -er '.access_token')"
+    encoded="$(curl --fail --silent --show-error \\
+      -H "Authorization: Bearer $access_token" \\
+      -H 'Content-Type: application/json' \\
+      "https://secretmanager.googleapis.com/v1/$secret_resource:access" \\
+      | jq -er '.payload.data')"
+  fi
+  secret_value="$(printf '%s' "$encoded" | base64 -d)"
+  if [ -z "$secret_value" ]; then
+    printf '%s\n' "GCP Batch 运行时密钥为空" >&2
+    return 1
+  fi
+  export "$credential_name=$secret_value"
+  unset access_token encoded secret_value credential_token credential_url
+  unset CITEARK_PROVIDER_CREDENTIAL_TOKEN CITEARK_PROVIDER_CREDENTIAL_URL
+}
+
+start_provider_relay() {
+  local count=0
+  node --use-env-proxy "$PROVIDER_RELAY_PATH" >> /job/execution/provider-pro-relay.log 2>&1 &
+  PROVIDER_RELAY_PID=$!
+  while [ "$count" -lt 50 ]; do
+    if curl --fail --silent --show-error "http://127.0.0.1:\${CITEARK_CODEX_RELAY_PORT:-4317}/health" >/dev/null 2>&1; then
+      return 0
+    fi
+    kill -0 "$PROVIDER_RELAY_PID" 2>/dev/null || break
+    sleep 0.1
+    count=$((count + 1))
+  done
+  printf '%s\n' "Provider Pro relay 启动失败" >&2
+  return 1
+}
+
+stop_provider_relay() {
+  if [ -n "\${PROVIDER_RELAY_PID:-}" ] && kill -0 "$PROVIDER_RELAY_PID" 2>/dev/null; then
+    kill -TERM "$PROVIDER_RELAY_PID" 2>/dev/null || true
+    wait "$PROVIDER_RELAY_PID" 2>/dev/null || true
+  fi
+  PROVIDER_RELAY_PID=
+}
+
+runtime_budget_consumed_seconds() {
+  local now elapsed consumed
+  if [ "$TOTAL_RUNTIME_BUDGET_SECONDS" -le 0 ]; then
+    printf '0\n'
+    return 0
+  fi
+  now="$(date +%s)"
+  elapsed=$((now - RUNTIME_BUDGET_SEGMENT_STARTED_EPOCH))
+  [ "$elapsed" -ge 0 ] || elapsed=0
+  consumed=$((RUNTIME_BUDGET_BASE_SECONDS + elapsed))
+  if [ "$consumed" -gt "$TOTAL_RUNTIME_BUDGET_SECONDS" ]; then consumed="$TOTAL_RUNTIME_BUDGET_SECONDS"; fi
+  printf '%s\n' "$consumed"
+}
+
+write_runtime_budget() {
+  local consumed temporary
+  [ "$TOTAL_RUNTIME_BUDGET_SECONDS" -gt 0 ] || return 0
+  consumed="$(runtime_budget_consumed_seconds)"
+  temporary="\${RUNTIME_BUDGET_STATE}.tmp"
+  jq -nc \
+    --argjson totalRuntimeBudgetSeconds "$TOTAL_RUNTIME_BUDGET_SECONDS" \
+    --argjson consumedRuntimeSeconds "$consumed" \
+    --arg updatedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    '{schemaVersion:"0.1",$totalRuntimeBudgetSeconds,$consumedRuntimeSeconds,$updatedAt}' \
+    > "$temporary"
+  mv "$temporary" "$RUNTIME_BUDGET_STATE"
+}
+
+initialize_runtime_budget() {
+  local restored=0
+  if [ "$TOTAL_RUNTIME_BUDGET_SECONDS" -le 0 ]; then return 0; fi
+  if [ -s "$RUNTIME_BUDGET_STATE" ]; then
+    restored="$(jq -r '.consumedRuntimeSeconds // 0' "$RUNTIME_BUDGET_STATE" 2>/dev/null || printf '0')"
+  fi
+  case "$restored" in ''|*[!0-9]*) restored=0 ;; esac
+  if [ "$restored" -gt "$TOTAL_RUNTIME_BUDGET_SECONDS" ]; then restored="$TOTAL_RUNTIME_BUDGET_SECONDS"; fi
+  RUNTIME_BUDGET_BASE_SECONDS="$restored"
+  RUNTIME_BUDGET_SEGMENT_STARTED_EPOCH="$(date +%s)"
+  write_runtime_budget
+}
+
+remaining_runtime_budget_seconds() {
+  local consumed remaining
+  if [ "$TOTAL_RUNTIME_BUDGET_SECONDS" -le 0 ]; then
+    printf '0\n'
+    return 0
+  fi
+  consumed="$(runtime_budget_consumed_seconds)"
+  remaining=$((TOTAL_RUNTIME_BUDGET_SECONDS - consumed))
+  [ "$remaining" -ge 0 ] || remaining=0
+  printf '%s\n' "$remaining"
+}
+
+latest_checkpoint() {
+  local kind="$1"
+  ls -1t "\${RESTORE_CHECKPOINT_PREFIX}-\${kind}-"*.tar.gz 2>/dev/null | head -n 1 || true
+}
+
+restore_checkpoints() {
+  local full critical full_mtime=0 critical_mtime=0
+  full="$(latest_checkpoint full)"
+  critical="$(latest_checkpoint critical)"
+  if [ -n "$full" ]; then
+    verify_checkpoint_archive "$full"
+    tar -xzf "$full" -C /job
+    full_mtime="$(stat -c %Y "$full" 2>/dev/null || echo 0)"
+    RESTORED_CHECKPOINT=1
+  fi
+  if [ -n "$critical" ]; then
+    critical_mtime="$(stat -c %Y "$critical" 2>/dev/null || echo 0)"
+    if [ "$critical_mtime" -ge "$full_mtime" ]; then
+      verify_checkpoint_archive "$critical"
+      tar -xzf "$critical" -C /job
+      RESTORED_CHECKPOINT=1
+    fi
+  fi
+  if [ "$RESTORED_CHECKPOINT" = 1 ]; then
+    if [ -d /job/execution/workspace-checkpoint ]; then restore_workspace_checkpoint; fi
+    mkdir -p /job/execution
+    printf '{"type":"citeark.checkpoint_restored","infrastructureRetry":%s,"full":"%s","critical":"%s","timestamp":"%s"}\n' \
+      "$INFRASTRUCTURE_RETRY" "$(basename "\${full:-}")" "$(basename "\${critical:-}")" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl
+  fi
+}
+
+verify_checkpoint_archive() {
+  local archive="$1" status="\${RESTORE_CHECKPOINT_PREFIX}-status.json"
+  local object expected actual cache_required=0
+  case "$RESTORE_CHECKPOINT_PREFIX" in *citeark-asset-cache-manifest-*) cache_required=1 ;; esac
+  if [ ! -s "$status" ]; then
+    if [ "$cache_required" = 1 ]; then
+      printf '%s\n' "资产缓存缺少检查点状态文件" >&2
+      return 1
+    fi
+    return 0
+  fi
+  object="$(jq -r '.object // empty' "$status" 2>/dev/null || true)"
+  if [ "$object" != "$(basename "$archive")" ]; then
+    if [ "$cache_required" = 1 ]; then
+      printf '%s\n' "资产缓存状态没有绑定待恢复检查点" >&2
+      return 1
+    fi
+    return 0
+  fi
+  expected="$(jq -r '.sha256 // empty' "$status" 2>/dev/null || true)"
+  case "$expected" in sha256:[0-9a-f][0-9a-f]*) ;; *)
+    if [ "$cache_required" = 1 ]; then
+      printf '%s\n' "资产缓存检查点缺少 SHA-256" >&2
+      return 1
+    fi
+    return 0
+  esac
+  actual="sha256:$(sha256sum "$archive" | cut -d' ' -f1)"
+  if [ "$actual" != "$expected" ]; then
+    printf '%s\n' "检查点 SHA-256 不匹配，拒绝恢复" >&2
+    return 1
+  fi
+}
+
+capture_workspace_checkpoint() {
+  CITEARK_JOB_ROOT=/job "$SUPERVISOR_PYTHON" -c ${shellQuote(WORKSPACE_CHECKPOINT_CAPTURE_PYTHON)}
+}
+
+restore_workspace_checkpoint() {
+  CITEARK_JOB_ROOT=/job "$SUPERVISOR_PYTHON" -c ${shellQuote(WORKSPACE_CHECKPOINT_RESTORE_PYTHON)}
+}
+
+flush_checkpoint_object() {
+  local path="$1" expected_bytes="\${2:-}" actual_bytes
+  if ! sync -f "$path" 2>> /job/execution/checkpoint.log; then
+    sync 2>> /job/execution/checkpoint.log || return 1
+  fi
+  if [ ! -s "$path" ]; then
+    printf '%s\n' "检查点对象落盘后为空：$path" >> /job/execution/checkpoint.log
+    return 1
+  fi
+  actual_bytes="$(stat -c %s "$path" 2>/dev/null || true)"
+  if [ -n "$expected_bytes" ] && [ "$actual_bytes" != "$expected_bytes" ]; then
+    printf '%s\n' "检查点对象落盘后大小不一致：$path expected=$expected_bytes actual=$actual_bytes" >> /job/execution/checkpoint.log
+    return 1
+  fi
+}
+
+checkpoint_state() {
+  local kind="$1" reason="\${2:-periodic}" sequence temporary target status_tmp status_bytes bytes created archive_sha256 paths=()
+  local trace_tail trace_digest retention_excludes last_effective_epoch last_effective_at
+  [ "$CHECKPOINT_ENABLED" = 1 ] || return 0
+  mkdir "$CHECKPOINT_LOCK" 2>/dev/null || return 0
+  write_runtime_budget || true
+  if ! node /tmp/citeark-codex-account.mjs save; then rmdir "$CHECKPOINT_LOCK"; return 1; fi
+  if ! capture_workspace_checkpoint 2>> /job/execution/checkpoint.log; then
+    rmdir "$CHECKPOINT_LOCK" 2>/dev/null || true
+    return 1
+  fi
+  sequence="$(date -u +%Y%m%dT%H%M%S)-$(date +%N)-r\${INFRASTRUCTURE_RETRY}"
+  temporary="/tmp/citeark-checkpoint-\${kind}-\${sequence}.tar.gz"
+  retention_excludes="/tmp/citeark-checkpoint-excludes-\${sequence}.txt"
+  target="\${CHECKPOINT_PREFIX}-\${kind}-\${sequence}.tar.gz"
+  : > "$retention_excludes"
+  cat >> "$retention_excludes" <<'CHECKPOINT_EXCLUDES'
+runtime-home/codex/auth.json
+runtime-home/.cache
+runtime-home/.npm
+runtime-home/.local/share/uv
+runtime-home/.local/share/pnpm
+runtime-home/.bun/install/cache
+runtime-home/.config/opencode/node_modules
+runtime-home/.local/share/opencode/log
+runtime-home/.local/share/opencode/snapshot
+runtime-home/.local/share/opencode/repos
+execution/.publication-reserve
+output/.env*
+output/*/.env*
+output/auth.json
+output/*/auth.json
+output/credentials.json
+output/*/credentials.json
+output/secrets.json
+output/*/secrets.json
+workspace/repository/.git
+workspace/repository/*/.git
+workspace/repository/.cache
+workspace/repository/*/.cache
+workspace/repository/.mypy_cache
+workspace/repository/*/.mypy_cache
+workspace/repository/.pytest_cache
+workspace/repository/*/.pytest_cache
+workspace/repository/.venv
+workspace/repository/*/.venv
+workspace/repository/__pycache__
+workspace/repository/*/__pycache__
+workspace/repository/node_modules
+workspace/repository/*/node_modules
+workspace/repository/.env
+workspace/repository/.env.*
+workspace/repository/*/.env
+workspace/repository/*/.env.*
+CHECKPOINT_EXCLUDES
+  if [ -s "$COMPLETION" ] && jq -e . "$COMPLETION" >/dev/null 2>&1; then
+    while IFS= read -r relative; do
+      case "$relative" in
+        ""|/*|../*|*/../*|*/..) continue ;;
+      esac
+      printf 'output/%s\n' "$relative" >> "$retention_excludes"
+    done < <(jq -r '.outputs[]? | select(.kind == "model" or .kind == "checkpoint" or .kind == "dataset") | .path // empty' "$COMPLETION")
+  fi
+  if [ "$reason" != asset-preparation ]; then
+    [ -d /job/execution ] && paths+=(execution)
+    [ -d /job/runtime-home ] && paths+=(runtime-home)
+  fi
+  # Preserve the full scientific output tree, including raw histories.
+  [ -d /job/output ] && paths+=(output)
+  if [ "$reason" = target-recovery ] || [ "$reason" = asset-preparation ] || [ "$PRESERVE_REBUILDABLE_CACHE" = 1 ]; then
+    [ -d /job/assets ] && paths+=(assets)
+    [ -d /job/runtime-cache ] && paths+=(runtime-cache)
+    [ -d /job/runtime-venv ] && paths+=(runtime-venv)
+  fi
+  if [ "\${#paths[@]}" -eq 0 ]; then rm -f "$retention_excludes"; rmdir "$CHECKPOINT_LOCK"; return 0; fi
+  if tar --ignore-failed-read --warning=no-file-changed --exclude-from="$retention_excludes" -I 'gzip -1' -cf "$temporary" -C /job "\${paths[@]}" 2>> /job/execution/checkpoint.log; then
+    bytes="$(stat -c %s "$temporary")"
+    cp "$temporary" "$target"
+    if ! flush_checkpoint_object "$target" "$bytes"; then
+      rm -f "$target" "$temporary" "$retention_excludes"
+      rmdir "$CHECKPOINT_LOCK" 2>/dev/null || true
+      return 1
+    fi
+    archive_sha256="sha256:$(sha256sum "$temporary" | cut -d' ' -f1)"
+    created="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+    status_tmp="/tmp/citeark-checkpoint-status-\${sequence}.json"
+    trace_tail="$(grep -v '"type":"citeark.checkpoint_saved"' /job/execution/trace.jsonl 2>/dev/null \
+      | tail -n 80 \
+      | jq -Rsc '
+        def clean($n):
+          if type == "string" then
+            gsub("sk-[A-Za-z0-9_-]{12,}"; "<redacted-secret>")
+            | if length > $n then .[0:($n - 1)] + "…" else . end
+          else null end;
+        def compact: with_entries(select(.value != null));
+        [
+          splits("\\n")
+          | fromjson?
+          | select(type == "object")
+          | {
+              type,
+              timestamp: (.timestamp | clean(64)),
+              recorded_at: (.recorded_at | clean(64)),
+              created_at: (.created_at | clean(64)),
+              attempt,
+              executor: (.executor | clean(64)),
+              infrastructureRetry,
+              restoredCheckpoint,
+              kind: (.kind | clean(48)),
+              reason: (.reason | clean(120)),
+              sequence: (.sequence | clean(120)),
+              bytes,
+              exitCode,
+              exit_code,
+              timed_out,
+              resultSha256: (.resultSha256 | clean(80)),
+              signal: (.signal | clean(32)),
+              thread_id: (.thread_id | clean(120)),
+              turn_id: (.turn_id | clean(120)),
+              is_error,
+              tool_name: (.tool_name | clean(80)),
+              elapsed_time_seconds,
+              item: (
+                if (.item | type) == "object" then
+                  {
+                    id: (.item.id | clean(120)),
+                    type: (.item.type | clean(80)),
+                    status: (.item.status | clean(48)),
+                    exit_code: .item.exit_code,
+                    command: (.item.command | clean(300)),
+                    text: (.item.text | clean(500))
+                  } | compact
+                else null end
+              )
+            } | compact
+        ] | .[-24:]' 2>/dev/null \
+      || printf '[]')"
+    trace_digest="$(printf '%s' "$trace_tail" | sha256sum | cut -d' ' -f1)"
+    last_effective_epoch="$(agent_last_effective_activity_epoch)"
+    last_effective_at=""
+    if [ "$last_effective_epoch" -gt 0 ]; then
+      last_effective_at="$(date -u -d "@$last_effective_epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+    fi
+    jq -nc \
+      --arg sequence "$sequence" \
+      --arg kind "$kind" \
+      --arg reason "$reason" \
+      --arg object "$(basename "$target")" \
+      --arg createdAt "$created" \
+      --argjson bytes "$bytes" \
+      --arg sha256 "$archive_sha256" \
+      --argjson infrastructureRetry "$INFRASTRUCTURE_RETRY" \
+      --arg traceDigest "$trace_digest" \
+      --argjson traceTail "$trace_tail" \
+      --arg lastEffectiveAt "$last_effective_at" \
+      '{schemaVersion:"0.1",$sequence,$kind,$reason,$object,$createdAt,$bytes,$sha256,$infrastructureRetry,activity:({traceDigest:$traceDigest,traceTail:$traceTail,observedAt:$createdAt} + (if $lastEffectiveAt == "" then {} else {lastEffectiveAt:$lastEffectiveAt} end))}' \
+      > "$status_tmp"
+    status_bytes="$(stat -c %s "$status_tmp")"
+    cp "$status_tmp" "$CHECKPOINT_STATUS"
+    if ! flush_checkpoint_object "$CHECKPOINT_STATUS" "$status_bytes" || ! jq -e . "$CHECKPOINT_STATUS" >/dev/null 2>&1; then
+      printf '%s\n' "检查点状态文件未可靠落盘，拒绝发布检查点：$CHECKPOINT_STATUS" >> /job/execution/checkpoint.log
+      rm -f "$CHECKPOINT_STATUS" "$status_tmp" "$target" "$temporary" "$retention_excludes"
+      rmdir "$CHECKPOINT_LOCK" 2>/dev/null || true
+      return 1
+    fi
+    printf '{"type":"citeark.checkpoint_saved","kind":"%s","reason":"%s","sequence":"%s","bytes":%s,"timestamp":"%s"}\n' \
+      "$kind" "$reason" "$sequence" "$bytes" "$created" >> /job/execution/trace.jsonl
+    ls -1t "\${CHECKPOINT_PREFIX}-\${kind}-"*.tar.gz 2>/dev/null | tail -n +$((CHECKPOINT_RETENTION + 1)) | while IFS= read -r old; do rm -f "$old"; done
+    rm -f "$status_tmp"
+  fi
+  rm -f "$temporary" "$retention_excludes"
+  rmdir "$CHECKPOINT_LOCK" 2>/dev/null || true
+}
+
+checkpoint_signature() {
+  find /job/execution /job/runtime-home /job/workspace/repository /job/output/evidence /job/output/logs \
+    \\( -path '*/.git' -o -path '*/.cache' -o -path '*/.mypy_cache' -o -path '*/.pytest_cache' \
+       -o -path '*/.venv' -o -path '*/__pycache__' -o -path '*/node_modules' \
+       -o -path '/job/runtime-home/.npm' -o -path '/job/runtime-home/.local/share/uv' \
+       -o -path '/job/runtime-home/.local/share/pnpm' -o -path '/job/runtime-home/.bun/install/cache' \
+       -o -path '/job/runtime-home/.config/opencode/node_modules' \
+       -o -path '/job/runtime-home/.local/share/opencode/log' \
+       -o -path '/job/runtime-home/.local/share/opencode/snapshot' \
+       -o -path '/job/runtime-home/.local/share/opencode/repos' \\) -prune \
+    -o -type f ! -name '.env' ! -name '.env.*' \
+       ! -path '/job/execution/trace.jsonl' ! -path '/job/execution/checkpoint.log' \
+       ! -path '/job/execution/runtime-budget.json' \
+       ! -path '/job/execution/.publication-reserve' \
+       ! -path '/job/execution/workspace-checkpoint/*' -printf '%T@:%s:%p\n' 2>/dev/null \
+    | sort | tail -n 32 | sha256sum | cut -d' ' -f1
+  if [ -f /job/execution/trace.jsonl ]; then
+    grep -v '"type":"citeark.checkpoint_saved"' /job/execution/trace.jsonl 2>/dev/null \
+      | tail -n 80 | sha256sum | cut -d' ' -f1
+  fi
+  if [ -f "$COMPLETION" ]; then stat -c '%Y:%s' "$COMPLETION"; fi
+}
+
+agent_last_effective_activity_epoch() {
+  local value
+  value="$(grep -v -E '"type":"citeark\.(checkpoint_saved|agent_stalled)"' /job/execution/trace.jsonl 2>/dev/null \
+    | tail -n 1 \
+    | jq -r '.timestamp // .recorded_at // .recordedAt // .created_at // .createdAt // empty' 2>/dev/null \
+    || true)"
+  case "$value" in
+    ""|null) printf '0\n' ;;
+    *[!0-9]*) date -u -d "$value" +%s 2>/dev/null || printf '0\n' ;;
+    *)
+      if [ "\${#value}" -ge 13 ]; then printf '%s\n' "$((value / 1000))"; else printf '%s\n' "$value"; fi
+      ;;
+  esac
+}
+
+mark_result_ready() {
+  local reason="\${1:-agent-completed}" evidence digest ready_tmp
+  [ "$AGENT_EXIT" -eq 0 ] && [ -s "$COMPLETION" ] || return 1
+  jq -e . "$COMPLETION" >/dev/null 2>&1 || return 1
+  if [ "$COMPLETION_HAS_EVIDENCE" = 1 ]; then
+    while IFS= read -r evidence; do
+      case "$evidence" in
+        ""|/*|../*|*/../*|*/..) return 1 ;;
+      esac
+      [ -f "/job/output/$evidence" ] || return 1
+    done < <(jq -r '.evidence[]?.path // empty' "$COMPLETION")
+  fi
+  digest="$(sha256sum "$COMPLETION" | cut -d' ' -f1)"
+  ready_tmp="/tmp/citeark-result-ready.json"
+  printf '{"schemaVersion":"0.1","resultSha256":"%s","reason":"%s","createdAt":"%s","infrastructureRetry":%s}\n' \
+    "$digest" "$reason" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$INFRASTRUCTURE_RETRY" > "$ready_tmp"
+  cp "$ready_tmp" "$RESULT_READY"
+  printf '{"type":"citeark.result_ready","reason":"%s","resultSha256":"%s","timestamp":"%s"}\n' \
+    "$reason" "$digest" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl
+  rm -f "$ready_tmp"
+}
+
+result_ready_matches() {
+  local expected observed
+  [ -s "$RESULT_READY" ] && [ -s "$COMPLETION" ] || return 1
+  expected="$(jq -r 'select(.reason == "agent-completed") | .resultSha256 // empty' "$RESULT_READY" 2>/dev/null)"
+  observed="$(sha256sum "$COMPLETION" | cut -d' ' -f1)"
+  [ -n "$expected" ] && [ "$expected" = "$observed" ]
+}
+
+checkpoint_loop() {
+  local last_full now signature last_signature=""
+  local agent_pid="" last_effective_epoch=0 idle_seconds=0 last_effective_at=""
+  last_full="$(date +%s)"
+  checkpoint_state critical worker-started || true
+  while [ ! -e "$CHECKPOINT_STOP" ]; do
+    sleep "$CHECKPOINT_CRITICAL_INTERVAL" & wait $! || true
+    [ -e "$CHECKPOINT_STOP" ] && break
+    signature="$(checkpoint_signature)"
+    if [ "$signature" != "$last_signature" ]; then
+      checkpoint_state critical changed || true
+      last_signature="$signature"
+    fi
+    # An environment checkpoint can take minutes. If the Agent finished while
+    # it was being written, let the parent validate and publish the final one.
+    [ -e "$CHECKPOINT_STOP" ] && break
+    now="$(date +%s)"
+    if [ "$AGENT_STALL_TIMEOUT_SECONDS" -gt 0 ] && [ ! -s "$AGENT_STALL_STATE" ]; then
+      agent_pid="$(cat "$AGENT_PID_FILE" 2>/dev/null || true)"
+      last_effective_epoch="$(agent_last_effective_activity_epoch)"
+      if [ -n "$agent_pid" ] && kill -0 "$agent_pid" 2>/dev/null && [ "$last_effective_epoch" -gt 0 ]; then
+        idle_seconds=$((now - last_effective_epoch))
+        if [ "$idle_seconds" -ge "$AGENT_STALL_TIMEOUT_SECONDS" ]; then
+          last_effective_at="$(date -u -d "@$last_effective_epoch" +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || true)"
+          jq -nc \
+            --arg detectedAt "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+            --arg lastEffectiveAt "$last_effective_at" \
+            --argjson idleSeconds "$idle_seconds" \
+            --argjson timeoutSeconds "$AGENT_STALL_TIMEOUT_SECONDS" \
+            '{schemaVersion:"0.1",reason:"effective-progress-stalled",$detectedAt,$lastEffectiveAt,$idleSeconds,$timeoutSeconds}' \
+            > "$AGENT_STALL_STATE"
+          printf '{"type":"citeark.agent_stalled","reason":"effective-progress-stalled","idleSeconds":%s,"timeoutSeconds":%s,"lastEffectiveAt":"%s","timestamp":"%s"}\n' \
+            "$idle_seconds" "$AGENT_STALL_TIMEOUT_SECONDS" "$last_effective_at" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl
+          checkpoint_state critical agent-stalled || true
+          kill -TERM "$agent_pid" 2>/dev/null || true
+        fi
+      fi
+    fi
+    [ -e "$CHECKPOINT_STOP" ] && break
+    if [ $((now - last_full)) -ge "$CHECKPOINT_FULL_INTERVAL" ]; then
+      checkpoint_state full periodic || true
+      last_full="$now"
+    fi
+  done
+}
+
+handle_termination() {
+  set +e
+  printf '{"type":"citeark.infrastructure_interruption","signal":"TERM","infrastructureRetry":%s,"timestamp":"%s"}\n' \
+    "$INFRASTRUCTURE_RETRY" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" >> /job/execution/trace.jsonl
+  checkpoint_state critical signal || true
+  if [ -n "\${AGENT_PID:-}" ]; then kill -TERM "$AGENT_PID" 2>/dev/null || true; fi
+  stop_provider_relay
+  exit 143
+}`;
+}