Add GPU device selection, upgrade harnesses, and standardize task docs

.agents/skills/create-searchswe-task/references/task-authoring.md

@@ -113,6 +113,17 @@ above; do not copy its task-specific values.
 When measuring improvement against a supplied starting system/model, document
 that baseline and the comparison criterion.
 
+Use the task title as the README's level-one heading, followed by these
+level-two headings in order: `Task Metadata`, `Change Log`,
+`Difficulty Explanation`, `Verification Explanation`, and `References`.
+Metadata covers identity, authors, inputs, metric and resource budgets.
+Explain engineering difficulty with any measured evidence, and document scoring,
+limits, setup and validation under verification; use level-three headings as needed.
+List the papers, datasets or methods actually referenced by the task, or `None`.
+New tasks start at `1.0.0` with a dated `Added initial task` changelog entry.
+Keep the README and `task.version` aligned as the task evolves; retain original
+versions and fingerprints in historical validation reports.
+
 Search-SWE release packages use a separate verifier:
 
 ```toml
@@ -160,6 +171,13 @@ CPU Compose files must not contain an NVIDIA reservation. Keep the image,
 shared image, stop and ask the maintainer before introducing a third base image.
 Treat `docker/README.md` as the source of truth if published versions change.
 
+For a local GPU trial, use the shared launcher's optional
+`--gpu-device <host-index-or-UUID>`. It carries one resolved UUID into both
+phases using per-run Compose copies. Keep the package's default `count: 1`
+requests and document any task-specific GPU capacity requirement in its README.
+Install the target checkout's pinned coding-agent CLIs in the agent Dockerfile;
+the current versions are defined in `scripts/harness_versions.py`.
+
 Pin task-specific package and system dependencies. Do not use `latest`, clone a
 moving branch during a build, copy a host virtual environment, or depend on a
 developer's local image/cache. The Docker build context is its containing

.agents/skills/create-searchswe-task/references/validation.md

@@ -101,7 +101,10 @@ GPU images target linux/amd64 with CUDA 13.0 userspace. GPU execution requires
 a compatible NVIDIA host driver and Container Toolkit. With the documented
 Harbor 0.22.0 Docker backend, `gpus = 1` alone fails preflight. The repository
 launcher passes `--override-gpus 0`, while **both Compose overlays still request
-the real GPU**. For direct Harbor runs on that backend use the same override;
+the real GPU**. Add `--gpu-device <host-index-or-UUID>` to the shared launcher
+for explicit selection in both phases. Check the resulting container device
+requests and the per-phase configuration under the trial's `gpu/` directory.
+For direct Harbor runs on that backend use the same override;
 do not falsify task metadata to work around it. Recheck this behavior if Harbor
 changes. CPU tasks do not need the override or NVIDIA reservation.
 

.agents/skills/create-searchswe-task/scripts/scaffold_task.py

@@ -4,6 +4,7 @@
 from __future__ import annotations
 
 import argparse
+from datetime import date
 import json
 from pathlib import Path
 import re
@@ -74,11 +75,35 @@ def files_for(task_name: str, hardware: str) -> dict[str, str]:
             f"""
             # {task_name}
 
-            **Task:** `{task_name}`
+            ## Task Metadata
 
-            Replace this scaffold text with an author-facing overview of the
-            objective, dataset/model provenance and license, metric, resource
-            needs, and local validation procedure.
+            | Field | Value |
+            | --- | --- |
+            | Task | `{task_name}` |
+            | Version | 1.0.0 |
+            | Hardware | {hardware.upper()} |
+
+            Describe the objective, authors, inputs, metric and resource budgets
+            consistently with task.toml. Link dataset/model provenance and licenses.
+
+            ## Change Log
+
+            | Date | Version | Description |
+            | --- | --- | --- |
+            | {date.today().isoformat()} | 1.0.0 | Added initial task |
+
+            ## Difficulty Explanation
+
+            Explain the engineering challenges and any measured difficulty evidence.
+
+            ## Verification Explanation
+
+            Describe the submission interface, scoring, limits, credential setup
+            and local validation commands. Record actual model-trial feedback.
+
+            ## References
+
+            None.
             """
         ),
         "assets.json": json.dumps(
@@ -147,7 +172,7 @@ def files_for(task_name: str, hardware: str) -> dict[str, str]:
 
             [task]
             name = "search-swe/{task_name}"
-            version = "0.1.0"
+            version = "1.0.0"
             description = "Replace with the task's observable objective."
             authors = [{{ name = "Search-SWE" }}]
             keywords = ["information-retrieval", "search"]

.agents/skills/maintain-searchswe-task/references/task-audit.md

@@ -10,6 +10,7 @@ workflow/tool modifications need independent scrutiny, not implicit acceptance.
 | Repository precedent | For each new task, the contributor names one or two closest reviewed `tasks/` packages already merged into the base branch or states that none is close, and explains matching dimensions, structural reuse and intentional differences. Independently inspect the closest analogue by objective, grading/judge shape, resources, hardware and data/artifact layout. Current contracts and validators override legacy examples. Reject unexplained copying of task-specific IDs/authors, datasets or HF pins, thresholds/baselines, allowlists, budgets, licenses/provenance or hidden evaluation design. Merely existing on main is not proof that a pattern remains valid. |
 | Instructions | Compare `raw-instruction.md` with the final `instruction.md`: the agent-facing version starts from a concrete work need and preserves the goal, starting state, input/output schema and paths, executable interface, artifacts, thresholds and constraints. Both match every graded requirement. No secret-only correctness requirement or hidden solution hints. |
 | Objective/resources | Clear goal, starting state and measured outcomes. Supply a meaningful baseline when grading improvement. CPU default, GPU only for execution. Both Dockerfiles, both Compose reservations and `gpus` agree. Visible tools/API/model docs match injected resources and budgets. Pin dependencies/images; inspect build contexts. |
+| Task README | One task title followed by `Task Metadata`, `Change Log`, `Difficulty Explanation`, `Verification Explanation`, and `References`. Current version matches `task.toml`; new tasks start at `1.0.0` with a dated `Added initial task` entry. Difficulty and validation claims match evidence. References identify existing paper/data/method sources, or `None`. Historical trial versions and fingerprints remain accurate. |
 | Solvability | Real known-good submission through the same separate verifier/artifact-transfer interface, expected vs observed reward and an authorized coding-agent trial. A scaffold's always-zero test, empty manifest, dry-run or static pass is not a working benchmark. No public author-only solution without approval. |
 | Model feedback | Trajectory, score and judge health inspected; task-setting changes explained, or a reason recorded for retaining the setting. Substantive task/scoring changes have relevant checks and a new model trial within the authorized budget, tied to the final evaluated revision. Missing evidence remains explicit; a valid low score alone is not a reason to weaken the task. |
 | Grader isolation | Separate verifier; hidden tests/labels/references absent from agent mounts/images. Submitted code actually runs unprivileged with timeout, restricted environment, no grader/reward writes or judge keys. Root in a separate container can still tamper with grading. Reward initializes to zero, numeric finite [0,1], failures propagate, cleanup/logs work. |
@@ -61,6 +62,9 @@ trusted temporary base `main` service/image, then build both contexts only when
 authorized. Run known-good and negative verifier cases in disposable environments.
 For the documented Harbor 0.22.0 GPU backend, the launcher uses `--override-gpus 0`
 while **both** Compose overlays still request the GPU; recheck on version changes.
+For explicit selection, use `--gpu-device <host-index-or-UUID>` with the trusted
+launcher. Verify that the generated phase configurations expose the same UUID
+and retain task mounts and network controls; package defaults use `count: 1`.
 The launcher does not support `--agent oracle`; a known-good implementation must
 be tested separately through the real verifier, in an author-only copy.
 

.env.example

@@ -15,7 +15,7 @@ AGENT_MODEL=
 DEEPSEEK_API_KEY=
 ZAI_API_KEY=
 
-# Optional Pi default: off, minimal, low, medium, high, or xhigh.
+# Optional Pi default: off, minimal, low, medium, high, xhigh, or max.
 PI_THINKING=
 
 # Codex agent only: fill both endpoint fields when using --agent codex.

README.md

@@ -171,7 +171,7 @@ it.
 
 #### Claude Code and the official Anthropic API
 
-Claude Code 2.1.283 is preinstalled in every task image. Set an Anthropic model
+Claude Code 2.1.309 is preinstalled in every task image. Set an Anthropic model
 available to your API account and the dedicated coding-agent key:
 
 ```dotenv
@@ -217,6 +217,17 @@ GPU, network-policy, and custom-provider options.
 
 </details>
 
+For a GPU task, add `--gpu-device 0` (host index or full GPU UUID) to select the
+same device for the agent and verifier. For example, after preparing its inputs
+and credentials:
+
+```bash
+bash scripts/run_task.sh --task code-embedding-finetuning --agent codex --gpu-device 0
+```
+
+Omit the option to use the default single-GPU allocation. See
+[GPU device selection](docs/evaluation.md#gpu-device-selection) for details.
+
 ## 📚 Documentation
 
 | Document | Contents |

README_zh.md

@@ -157,7 +157,7 @@ bash scripts/run_task.sh --task reasoning-query-rewriting --agent codex \
 
 #### Claude Code 和 Anthropic 官方 API
 
-所有任务镜像都预装 Claude Code 2.1.283。填写 API 账户可用的 Anthropic 模型
+所有任务镜像都预装 Claude Code 2.1.309。填写 API 账户可用的 Anthropic 模型
 和独立的编码智能体密钥：
 
 ```dotenv
@@ -201,6 +201,15 @@ bash scripts/run_task.sh --task reasoning-query-rewriting --agent claude-code --
 
 </details>
 
+GPU 任务可以增加 `--gpu-device 0`，使用宿主机编号或完整 GPU UUID，让 agent
+和 verifier 使用同一设备。例如，准备好该任务的数据和凭证后运行：
+
+```bash
+bash scripts/run_task.sh --task code-embedding-finetuning --agent codex --gpu-device 0
+```
+
+省略该参数时使用默认单卡分配。详见[GPU 设备选择](docs/evaluation.md#gpu-device-selection)。
+
 ## 📚 文档索引
 
 | 文档 | 内容 |

docs/contributing.md

@@ -28,6 +28,14 @@ prefix and `all` are reserved. Check `tasks/` on the current base and active PRs
 for name collisions. Set `task.name` to `search-swe/<task-name>`. A PR may contain
 multiple uniquely named tasks.
 
+Use the task title as the README's level-one heading and these level-two sections
+in order: `Task Metadata`, `Change Log`, `Difficulty Explanation`,
+`Verification Explanation`, and `References`. Include dated versions and concise
+changes in the changelog; new tasks start at `1.0.0` with `Added initial task`.
+Keep the current README version aligned with `task.toml`. Describe difficulty,
+scoring and runtime validation, and list existing paper/data/method references
+or `None`. Setup commands and detailed explanations can use level-three headings.
+
 Describe the task's goal, starting state and measured outcomes.
 CPU is the default; choose `--hardware gpu` for actual GPU execution. Repeat
 `--author` for coauthors. Use actual authors in `task.toml`, not only “Search-SWE”,
@@ -68,6 +76,9 @@ Use `--task <task-name>` for downloads and local trials. The downloader's
 `--task-path tasks/<task-name>` also accepts a canonical repository-relative
 path. Jobs default to `jobs/<task-name>`; alternate asset output roots contain
 `<task-name>/`. The launcher reads the package's local assets.
+For GPU trials, add `--gpu-device <host-index-or-UUID>` to select the same device
+for the agent and verifier. Choose an available GPU with the task's required
+capacity and a separate output directory for each simultaneous run.
 
 Follow the skill's [validation layers](../.agents/skills/create-searchswe-task/references/validation.md):
 Compose rendering, builds, verifier known-good and negative cases, and an

docs/evaluation.md

@@ -141,7 +141,7 @@ native provider configuration and ignores the direct mode's `AGENT_CODEX_CONFIG`
 
 ### Claude Code with the official Anthropic API
 
-Claude Code is pinned to version 2.1.283 and preinstalled in every task image.
+Claude Code is pinned to version 2.1.309 and preinstalled in every task image.
 Set a model available to your Anthropic API account and its dedicated
 coding-agent key:
 
@@ -160,7 +160,7 @@ bash scripts/run_task.sh \
   --dry-run
 ```
 
-Claude Code 2.1.283 accepts `low`, `medium`, `high`, `xhigh`, and `max` effort.
+Claude Code 2.1.309 accepts `low`, `medium`, `high`, `xhigh`, and `max` effort.
 Use `AGENT_REASONING_EFFORT` as a local default or `--reasoning-effort` for an
 explicit run. The launcher maps `AGENT_ANTHROPIC_API_KEY` to the agent-only
 `ANTHROPIC_API_KEY`, permits only `api.anthropic.com` during restricted Agent
@@ -174,7 +174,7 @@ enabled by adding host environment variables.
 
 ### Pi native providers
 
-Pi is pinned to version 0.87.1 by the launcher. It currently accepts these
+Pi is pinned to version 1.4.0 by the launcher. It currently accepts these
 verified provider/model combinations:
 
 | Model | Required variable |
@@ -198,7 +198,7 @@ bash scripts/run_task.sh \
 ```
 
 For Z.AI, set `ZAI_API_KEY` and use `zai/glm-5.3-flash`. The accepted thinking
-levels are `off`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Use
+levels are `off`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Use
 `PI_THINKING` as a local default or `--thinking` for an explicit run. Pi's
 native provider key does not replace verifier or task-resource credentials.
 
@@ -221,13 +221,18 @@ VERIFIER_OPENAI_BASE_URL=https://openrouter.ai/api/v1
 VERIFIER_OPENAI_API_KEY=YOUR_OPENROUTER_KEY
 ```
 
-The verifier images pin `harbor-rewardkit==0.2.0` with its Codex CLI 0.147.0
+The verifier images pin `harbor-rewardkit==0.2.0` with Codex CLI 0.164.0
 preloaded, and every RewardKit judge is fixed to `deepseek/deepseek-v4.1-flash`. `--model`
 changes the coding-agent model; it does not change this judge model. The
 trajectory-judge endpoint is `https://openrouter.ai/api/v1`, checked by
 the backend and permitted by the verifier allowlists. A relay on another hostname is rejected rather than
 silently broadening verifier egress.
 
+The task-local backend selects Codex `0.164.0` through RewardKit 0.2.0's
+versioned runtime/cache pin. The verifier image preinstalls that exact version
+for both root and task-specific audit users. This integration is checked against
+RewardKit 0.2.0; a RewardKit upgrade requires a fresh compatibility check.
+
 RewardKit 0.2.0 creates a fresh temporary `CODEX_HOME` for each agent judge, so
 setting only a host `CODEX_HOME` or `OPENAI_BASE_URL` does not configure that
 Codex process. Search-SWE therefore registers a `deepseek-codex` backend that
@@ -280,12 +285,42 @@ Tasks with `environment.gpus = 1` require one NVIDIA GPU. Their images use CUDA
 a compatible NVIDIA driver and Container Toolkit. Both task and verifier
 Compose overlays request the real GPU.
 
+### GPU device selection
+
+Add `--gpu-device` to the usual launcher command to select one host GPU by index
+or full UUID. The launcher resolves the device once and uses the same UUID for
+the agent and separate verifier:
+
+```bash
+nvidia-smi --query-gpu=index,uuid,name,memory.used --format=csv
+bash scripts/run_task.sh --task code-embedding-finetuning --agent codex \
+  --gpu-device 2 --output jobs/code-embedding-finetuning-gpu2
+```
+
+Choose an available device that meets the task's hardware requirements. Selection
+is explicit; coordinate concurrent users of the host. For simultaneous runs,
+select different GPUs and distinct output directories. Omit the option for the
+default single-GPU allocation. CPU tasks accept their usual commands.
+
+Each explicitly selected run stores its generated phase configurations under
+`gpu/` in the trial directory. The task files keep their default `count: 1`
+reservation; the generated copies replace it with one `device_ids` entry and
+retain the original mounts. Run from the local NVIDIA Docker host. Container
+CUDA device 0 refers to the single exposed device, regardless of its host index.
+`--dry-run` previews the selection without checking GPU availability.
+
+### Harbor integration
+
 Harbor 0.22.0's Docker backend rejects `gpus = 1` during its own preflight and
 does not translate that field into the Compose GPU request. The shared launcher
 therefore supplies `--override-gpus 0` automatically while leaving the truthful
 task metadata and Compose reservations intact. Direct Harbor invocations using
 `--env scripts.harbor_environments:PhaseScopedDocker` need the same override
 with that Harbor version. Recheck this workaround when upgrading Harbor.
+Direct Harbor calls can pass `--environment-kwarg gpu_device=GPU-<full-UUID>` to
+`scripts.harbor_environments:PhaseScopedDocker`. Its environment kwargs are
+retained when Harbor creates the separate verifier; extra agent-only Compose
+overlays are not a replacement for this shared selection.
 
 ## Runtime network enforcement
 

docs/network-policy.md

@@ -114,7 +114,7 @@ The launcher selects exactly one coding-model hostname: the hostname in `AGENT_O
 `api.anthropic.com` host for direct Claude Code. With `--openrouter`, Codex and
 Claude Code use `openrouter.ai`. The launcher passes the selected host through
 Harbor's `--allow-agent-host`, which augments only the `agent.run()` phase.
-Codex 0.157.1, Pi 0.87.1, and Claude Code 2.1.283 are preinstalled in every
+Codex 0.164.0, Pi 1.4.0, and Claude Code 2.1.309 are preinstalled in every
 agent image, so agent setup does not need package-registry or general internet
 access.
 
@@ -144,7 +144,7 @@ invoking Harbor directly on a non-public task, add the matching hostname:
 PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" harbor run --path tasks/TASK_NAME \
   --env scripts.harbor_environments:PhaseScopedDocker \
   --agent scripts.harbor_agents:PreinstalledCodex --model MODEL_ID \
-  --ak version=0.157.1 \
+  --ak version=0.164.0 \
   --allow-agent-host MODEL_API_HOST
 ```
 
@@ -156,7 +156,7 @@ PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" harbor run --path tasks/TASK_NAME \
   --env scripts.harbor_environments:PhaseScopedDocker \
   --agent scripts.harbor_agents:PreinstalledClaudeCode \
   --model ANTHROPIC_MODEL_ID \
-  --ak version=2.1.283 \
+  --ak version=2.1.309 \
   --ae 'ANTHROPIC_API_KEY=${AGENT_ANTHROPIC_API_KEY}' \
   --allow-agent-host api.anthropic.com
 ```

docs/quickstart.md

@@ -100,7 +100,7 @@ the run as successful.
 ## Next steps
 
 - Read the [full evaluation guide](evaluation.md) before selecting another task
-  or agent. It documents Codex, Pi, and the pinned Claude Code 2.1.283 launcher,
+  or agent. It documents Codex, Pi, and the pinned Claude Code 2.1.309 launcher,
   and explains how to read each task's own credential, hardware and network
   configuration.
 - Read the selected task's `README.md` and `instruction.md` for its resource