---

name: prepare-paper-recovery-env description: "Inspect, prepare, and document an isolated runtime environment for Paper2Skills recovery experiments, including package probes, model/cache checks, GPU status, bounded benchmark acquisition, and a runtime handoff for recover-paper-result." metadata: disco-role: meta

Prepare Paper Recovery Env

Use this skill after create-paper-module-skill validation and before recover-paper-result whenever recovery needs models, packages, datasets, GPUs, API keys, benchmark code, or any nontrivial runtime setup. It adapts the environment-inspection discipline from repo-skill creation to Paper2Skills recovery, where the goal is an auditable recovery runtime rather than a public repo skill.

All artifacts must be in English.

Purpose

Create a current-attempt runtime handoff that tells recover-paper-result exactly what is usable, what was prepared, what failed, and what fallback is allowed. This is an active environment-preparation stage, not a passive inventory. Missing packages, datasets, model caches, or benchmark files are setup tasks to attempt within the user's constraints before they become blockers. Do not spend recovery time guessing package state, performing broad filesystem scans, or mutating shared environments without permission.

Inputs

• attempt_dir containing run_manifest.json.
• module_plan.json and generated skills root.
• Runtime constraints from the user or run prompt:
  • preferred model id/path and fallback model id/path
  • GPU ids or CPU-only permission
  • network permissions and setup commands
  • package mutation rules
  • isolated environment prefix, if the user wants one
  • benchmark/dataset URLs or local paths
  • whether reduced training is allowed

Outputs

Write these files under the attempt directory:

environment/
  runtime_handoff.json
  logs/
    package_probe.json
    gpu_probe.json
    model_cache_probe.json
    benchmark_probe.json
    command_log.json

Also update run_manifest.json.stages.prepare_environment to complete or blocked. Recovery validation treats a missing or still-pending prepare stage as a contract failure.

Workflow

1. Read run_manifest.json and runtime constraints. If constraints are missing, infer only low-risk defaults and record them.
2. Run bounded probes before any installation or download:
   • Python executable and version.
   • Import availability for packages required by the recovery target.
   • GPU visibility with nvidia-smi if available.
   • Model cache roots from user-supplied paths, $HF_HOME, $TRANSFORMERS_CACHE, ~/.cache/huggingface, and the workspace only.
   • Benchmark or dataset source availability.
3. Do not scan broad roots such as /share/project recursively. Search only explicit allowlists, known cache roots, and the workspace with timeouts.
4. If packages are missing:
   • Prefer an existing compatible environment supplied by the user.
   • If mutation is allowed, create or use an isolated environment. Prefer conda when available and fall back to venv, mirroring prepare-repo-skill-env.
   • Use the same default location policy as prepare-repo-skill-env: when the user does not provide a prefix, put recovery environments under $DISCO_CODING_AGENT_DIR/envs/; if that variable is unset, use ~/.disco/agent/envs/. Name the environment paper-recovery-<run_name>. Do not install into conda base, a shared conda env, or the active environment unless the user explicitly authorized that exact mutation. If runtime constraints say isolated env only, use this private environment even when the active Python already has the requested imports.
   • Install the smallest missing package set needed by the selected recovery target. For import/package name mismatches, pass explicit specs such as --pip-package sklearn=scikit-learn.
   • Put timeouts around installs. Record command, elapsed time, stdout/stderr tail, exit code, and whether environment was modified.
   • If installs stall or fail, try the user-provided network/VPN setup, a safe pip index/mirror, or a narrower package set when appropriate. Only then record a blocker, with the failed command and the next concrete fix.
5. If benchmark/data acquisition is needed:
   • Try the requested fresh source with a timeout.
   • Treat a timed-out or partial checkout as unusable until it validates as a real worktree and the requested resource files exist. A directory containing only .git is not a usable benchmark source.
   • If fresh acquisition fails, reuse a local immutable checkout only when allowed or when the run prompt permits it. Record the fresh-fetch blocker, reused path, commit/version, exact files used, and copy/snapshot concrete resource files into the current attempt.
   • Prefer resource files that can ground an actual example: task JSON/PDDL/TWL2/problem files, environment config, split manifests, prompts, expert plans, or benchmark metadata. For ALFWorld-style reduced recovery, prefer concrete task/game/config resources when available; if only README/API files are available, record why and require the generated data item to identify which fields came from those files.
   • If the paper needs a public dataset such as AIME2024 and no local path is supplied, attempt bounded acquisition from the user-supplied URL or a direct public source when source acquisition permits network access. A missing local dataset is not a blocker until bounded download or an explicit user question has been attempted and logged.
6. If model loading is requested:
   • First verify required packages and local/cache files.
   • If no local/cache hit exists, ask for or use explicit permission before downloading multi-GB models. Use a time budget and download into the attempt-scoped or DisCo-private cache, not a shared mutable cache unless the user requested it.
   • If loading is blocked, keep required-model success booleans false and write the exact blocker plus what was tried. A missing QwQ/Qwen cache is not a blocker until local cache probing and permitted bounded download or user clarification have happened.
7. If web search or API credentials are needed:
   • Check configured env vars or user-provided credential paths first.
   • Try an allowed keyless/public alternative when the method permits it.
   • If credentials are truly required and absent, ask the user for them or record the credential request as a pending user input. Do not present missing credentials as if the agent had exhausted setup work.
8. Write environment/runtime_handoff.json with a concise decision:
   • runtime_ready: true only when the requested runtime is genuinely ready.
   • reduced_recovery_recommended: true only when full runtime is blocked and the user permits reduced recovery.
   • blockers: exact actionable blockers.
   • allowed_sources_for_recovery: paths/URLs recover-paper-result may use.
   • environment_modified: whether any environment was changed.
9. Write environment/logs/command_log.json with every subprocess command executed by the environment probe, including GPU probes, benchmark clone attempts, version/commit checks, environment creation, installs, downloads, or killed commands. Commands that are only in terminal output are not auditable. If the probe is rerun, append to the existing command log instead of overwriting it.
10. Pass the handoff path to recover-paper-result. Recovery must include it in recovery/source_manifest.json.

Runtime Handoff Schema

{
  "schema_version": 1,
  "attempt_dir": "...",
  "python": {"executable": "...", "version": "..."},
  "packages": {"torch": false, "transformers": false},
  "environment": {
    "manager": "venv",
    "prefix": "~/.disco/agent/envs/paper-recovery-search_o1",
    "python": ".../bin/python",
    "setup": {"actions": [], "blockers": []}
  },
  "gpu": {"nvidia_smi_available": true, "visible_devices": []},
  "models": {
    "preferred": "Qwen/Qwen3-4B-Instruct-2507",
    "preferred_ready": false,
    "cache_hits": [],
    "blockers": []
  },
  "benchmarks": {
    "alfworld": {
      "fresh_attempted": true,
      "fresh_ok": false,
      "reused_local_source": "",
      "snapshot_dir": "",
      "resource_files": []
    }
  },
  "datasets": {},
  "runtime_ready": false,
  "reduced_recovery_recommended": true,
  "environment_modified": false,
  "allowed_sources_for_recovery": [],
  "blockers": []
}

Acceptance Criteria

• environment/runtime_handoff.json exists and is valid JSON.
• environment/logs/command_log.json exists, is valid JSON, and contains a commands list.
• run_manifest.json.stages.prepare_environment is complete when the requested runtime is ready, or blocked when exact blockers are recorded.
• If packages were missing and environment mutation was allowed, the command log shows an isolated environment creation/reuse and install attempts before the stage is marked blocked.
• If runtime constraints require isolated environments, the handoff's python.executable points to the private recovery environment Python, not the host/shared conda Python, unless private environment creation failed and the failure is logged as a blocker.
• Probes are bounded and logged.
• Shared environments are not mutated unless explicitly permitted.
• Any reused benchmark source has a current-attempt snapshot of concrete resource files.
• Partial clone directories are rejected unless they validate as complete worktrees containing the requested resource files.
• Repeated environment probes preserve earlier command-log entries.
• Full runtime booleans remain false unless the requested model/package stack is actually importable and ready.
• The handoff gives recover-paper-result enough information to choose between full recovery and an honest reduced fallback without repeating expensive discovery.

Script

Use scripts/probe_runtime.py for deterministic probes, bounded repair, and handoff generation. It can create/reuse an isolated conda env or venv at the DisCo-private default prefix, install explicitly requested missing packages, try bounded dataset/model downloads when flags permit them, inspect GPU/model cache hints, and validate benchmark source state. It must not perform unbounded downloads or broad scans.

Example for a Paper2Skills recovery that may need torch/transformers/vLLM/nltk, a QwQ/Qwen model, and a public benchmark:

python <skills_root>/prepare-paper-recovery-env/scripts/probe_runtime.py \
  --attempt-dir <attempt_dir> \
  --preferred-model Qwen/QwQ-32B \
  --package torch --package transformers --package vllm --package nltk \
  --env-manager auto \
  --pip-package torch \
  --pip-package transformers \
  --pip-package vllm \
  --pip-package nltk \
  --allow-env-mutation \
  --use-isolated-env \
  --attempt-model-download \
  --dataset-name AIME2024 \
  --dataset-url <direct-public-or-user-supplied-url> \
  --attempt-dataset-download \
  --network-timeout 300 \
  --install-timeout 900