nanoPyCodeAgent 0.7.0__tar.gz → 0.9.0__tar.gz

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/.agents/skills/release/scripts/verify-release.sh

@@ -8,8 +8,7 @@
 #
 # Usage: verify-release.sh <version|vVERSION>   e.g. verify-release.sh 0.1.1
 #
-# Smoke test runs the entry point with no args (currently side-effect-free).
-# If the entry point ever gains required args/interaction, adjust step 3.
+# Smoke test uses --version without a task and checks the installed version.
 set -euo pipefail
 
 PACKAGE="nanoPyCodeAgent"
@@ -63,11 +62,12 @@ printf 'OK: GitHub Release %s has wheel + sdist\n' "$tag"
 # --default-index (not --index): --index only *adds* an index, and uv's
 # first-index strategy would stop at a locally configured mirror that has the
 # package but not the new version yet. --refresh: uv's cached simple-index
-# metadata can be stale right after a publish. </dev/null: the entry point
-# reads stdin; EOF makes it exit immediately instead of hanging interactively.
+# metadata can be stale right after a publish. --version exits before task input
+# or credential validation; empty stdin without it is a command-line error.
 log "Smoke-testing uvx ${PACKAGE}@${version}"
 deadline=$(( $(date +%s) + POLL_TIMEOUT ))
-until uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" >/dev/null 2>&1 </dev/null; do
+until reported_version="$(uvx --refresh --default-index "$PYPI_INDEX" --from "${PACKAGE}@${version}" "$PACKAGE" --version 2>/dev/null </dev/null)" \
+  && [[ "$reported_version" == "${PACKAGE} ${version}" ]]; do
   (( $(date +%s) >= deadline )) && fail "uvx smoke test failed for ${PACKAGE}@${version} after ${POLL_TIMEOUT}s"
   printf 'uvx not ready (index propagation?); retrying in %ss...\n' "$POLL_INTERVAL"; sleep "$POLL_INTERVAL"
 done

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/.github/workflows/ci.yml

@@ -39,3 +39,21 @@ jobs:
         # --frozen installs exactly what uv.lock pins and fails if the lock has
         # drifted from pyproject.toml, so CI tests the declared dependencies.
         run: uv run --frozen pytest
+      - name: Test the httpx2 SDK transport
+        run: uv run --with anthropic==1.5.0 pytest
+
+  harbor:
+    name: Harbor workflow contracts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          python-version: "3.13"
+      - name: Test cache integrity, preflight, and verifier retries
+        run: >-
+          uv run --frozen --project benchmarks/harbor pytest
+          -c benchmarks/harbor/pyproject.toml benchmarks/harbor/tests

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/.gitignore

@@ -218,3 +218,6 @@ __marimo__/
 .streamlit/secrets.toml
 
 references/
+
+# Harbor benchmark results
+/jobs/

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/AGENTS.md

@@ -19,6 +19,24 @@ the matching one:
 
 See `docs/RELEASING.md` for the release process and prerequisites.
 
+## Benchmarks
+
+For new Harbor benchmark runs, use the standard workflow from the repository
+root: `uv run --project benchmarks/harbor python -m harbor_adapter run --config
+<config.json>`. See `benchmarks/harbor/README.md` for configuration, verified APT
+cache import, and the `--install-only` dependency preflight option.
+
+- Do not create per-job adapter copies or ad hoc bootstrap scripts. Add reusable
+  fixes and reviewed task-revision profiles to `benchmarks/harbor` with tests.
+- Preserve task images, package sources, and official test scripts. Cache hits
+  must match the current package index's filename, size, and SHA256 digest.
+- Run dependency preflight before model work when a task has a registered
+  profile. Record unsupported profiles explicitly; do not claim they passed.
+- Keep setup failures and verifier errors separate from scored failures. Only
+  verifier timeouts may retry, at most three total attempts using the same agent
+  output and the task's original per-attempt time limit.
+
+
 ## Language
 
 Write everything in **English** by default — source code (identifiers,
@@ -37,11 +55,15 @@ The **only** exception is documentation explicitly designated as Chinese:
 Everything outside that list — including code under `src/`, this file, and all
 other docs — is English.
 
+Do not label a document as `hand-written` unless its contents are actually
+authored and maintained by humans. For agent-authored source-of-truth documents,
+use wording such as `Chinese source` instead.
+
 ### Bilingual research notes
 
 Research notes are bilingual:
 
-- `docs/research/zh-CN/` contains the hand-written Chinese sources of truth.
+- `docs/research/zh-CN/` contains the Chinese sources of truth.
 - `docs/research/en/` contains English versions generated from the Chinese
   sources; regenerate the whole corresponding file instead of hand-editing it.
 
@@ -52,6 +74,28 @@ the English version is in sync, even when it has already been updated.
 
 ## Commits & PRs
 
+### Branch and pull request workflow
+
+All non-release changes MUST be made on a dedicated branch and merged into
+`main` through a GitHub pull request.
+
+- Before modifying repository files, agents MUST verify that the current branch
+  is not `main`. If it is `main`, create or switch to a dedicated branch first.
+- Agents MUST NOT commit directly to `main` or push non-release commits to
+  `origin/main`.
+- Open a pull request targeting `main`, and use the `land-pr` skill to merge it.
+  Do not merge without the skill's mandatory maintainer confirmation.
+- If work was accidentally started on `main`, move the changes to a dedicated
+  branch before committing or pushing them.
+
+The sole exception is the release workflow in `.agents/skills/release/SKILL.md`.
+Only when the maintainer explicitly requests a release may that skill commit and
+push its release-only changes directly to `main`, and only after its mandatory
+confirmation gate. Documentation, chores, hotfixes, and all other work still
+require a branch and pull request.
+
+### Commit and PR title format
+
 All agents working in this repo MUST follow
 [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
 for **commit messages** and **PR titles** (squash-merge often uses the PR

nanopycodeagent-0.9.0/CONTEXT.md

@@ -0,0 +1,65 @@
+# Code Agent Runtime
+
+This glossary defines the runtime artifacts produced and maintained by a code agent so that public output, diagnostics, evaluation data, and resumable state remain distinct.
+
+## Language
+
+**Agent Run**:
+A bounded execution that starts with an instruction and ends when the agent stops autonomous work.
+_Avoid_: Session, turn
+
+**Run Output**:
+The public result or event protocol that one agent run emits to its caller.
+_Avoid_: Trace, transcript
+
+**Run Result Object**:
+A single public object that summarizes how one Agent Run ended, including its final result and optional usage metadata.
+_Avoid_: Trajectory, session export
+
+**Public Event Stream**:
+A caller-facing Run Output that exposes a stable, selected sequence of Agent Run events as they occur.
+_Avoid_: Internal event bus, execution trace
+
+**Source Record**:
+An agent-specific record observed at a CLI, SDK, or protocol boundary and consumed by an adapter; it may already be a projection of the agent's internal state.
+_Avoid_: Native event, journal entry
+
+**Native Event**:
+An agent-independent runtime fact accepted by the core directly or normalized from a Source Record.
+_Avoid_: Source record, public event record, trajectory step
+
+**Journal Entry**:
+A Native Event together with the identity, ordering, and recording metadata required for durable history.
+_Avoid_: Persistence envelope, trajectory step
+
+**Event Journal**:
+A durable append-only sequence of Journal Entries for an Agent Run from which derived artifacts can be rebuilt.
+_Avoid_: Trajectory, session, public event stream
+
+**Partial Content**:
+An unfinished representation of a message, reasoning block, or tool input that is exposed before the logical content is complete.
+_Avoid_: Final message, completed event
+
+**Content Delta**:
+The incremental fragment or change relative to content already emitted for the same logical item.
+_Avoid_: Partial snapshot, final message
+
+**Terminal Event**:
+The final Public Event Stream record that explicitly states how an Agent Run ended.
+_Avoid_: EOF, last message
+
+**Execution Trace**:
+A diagnostic record of runtime activity retained to explain failures, timing, and internal behavior.
+_Avoid_: Run output, trajectory
+
+**Trajectory**:
+A task-scoped record of observations, actions, results, and outcome prepared for evaluation or offline analysis.
+_Avoid_: Execution trace, session, transcript
+
+**ATIF Trajectory**:
+A Trajectory represented by the Agent Trajectory Interchange Format and exposed as the runtime's public trajectory contract.
+_Avoid_: Event journal, native trajectory
+
+**Session**:
+Durable agent state that can span multiple runs and supports continuing or branching prior work.
+_Avoid_: Agent run, trajectory, transcript

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nanoPyCodeAgent
-Version: 0.7.0
+Version: 0.9.0
 Summary: A nano code agent built from scratch in pure Python.
 Project-URL: Homepage, https://github.com/minixalpha/nanoPyCodeAgent
 Project-URL: Repository, https://github.com/minixalpha/nanoPyCodeAgent
@@ -14,6 +14,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.13
 Requires-Dist: anthropic>=0.112.0
+Requires-Dist: httpx>=0.25.0
 Description-Content-Type: text/markdown
 
 # nanoPyCodeAgent
@@ -49,6 +50,20 @@ uv tool install nanoPyCodeAgent   # or: pipx install nanoPyCodeAgent
 nanoPyCodeAgent
 ```
 
+#### Run one task and exit
+
+Give it a task and it works through it on its own, with no prompt and nothing
+to confirm — the shape a script or a benchmark harness needs:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+The task runs in the current directory and the command exits when the run
+ends. See the [complete CLI reference](docs/user_docs/en/cli_reference.md) for
+all task input methods, options, exit statuses, trajectory output, and Event
+Journal behavior.
+
 #### Run a branch or tagged version
 
 Run an unreleased branch or a specific release tag straight from GitHub:
@@ -63,29 +78,11 @@ uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCode
 
 ### Configuration
 
-Credentials and the model come from two sources: **environment variables** and
-an optional user-level config file at `~/.nanoPyCodeAgent/settings.json`.
-Environment variables take precedence — the config file only fills in keys you
-have not set in the environment.
-
-The config file mirrors [Claude Code's settings](https://code.claude.com/docs/en/settings):
-put the values under an `env` object. Empty or whitespace-only values are ignored.
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "",
-    "ANTHROPIC_BASE_URL": "",
-    "ANTHROPIC_MODEL": ""
-  }
-}
-```
-
-| Variable | Required | Default | Description |
-| --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | Yes | — | Your Anthropic API key, or the key for a third-party / proxy service. |
-| `ANTHROPIC_BASE_URL` | No | `https://api.anthropic.com` | Point the SDK at a non-official / proxy endpoint. Leave it unset to use the official API — an empty value breaks requests. |
-| `ANTHROPIC_MODEL` | No | `claude-sonnet-4-6` | Override the model. An empty or whitespace-only value falls back to the default. |
+Set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` before running the agent.
+You can also configure the endpoint and model through environment variables or
+`~/.nanoPyCodeAgent/settings.json`. See the [configuration reference](docs/user_docs/en/configuration.md)
+for supported variables, defaults, file format, precedence, and empty-value
+handling.
 
 ### How to Update
 

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/README.md

@@ -31,6 +31,20 @@ uv tool install nanoPyCodeAgent   # or: pipx install nanoPyCodeAgent
 nanoPyCodeAgent
 ```
 
+#### Run one task and exit
+
+Give it a task and it works through it on its own, with no prompt and nothing
+to confirm — the shape a script or a benchmark harness needs:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+The task runs in the current directory and the command exits when the run
+ends. See the [complete CLI reference](docs/user_docs/en/cli_reference.md) for
+all task input methods, options, exit statuses, trajectory output, and Event
+Journal behavior.
+
 #### Run a branch or tagged version
 
 Run an unreleased branch or a specific release tag straight from GitHub:
@@ -45,29 +59,11 @@ uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCode
 
 ### Configuration
 
-Credentials and the model come from two sources: **environment variables** and
-an optional user-level config file at `~/.nanoPyCodeAgent/settings.json`.
-Environment variables take precedence — the config file only fills in keys you
-have not set in the environment.
-
-The config file mirrors [Claude Code's settings](https://code.claude.com/docs/en/settings):
-put the values under an `env` object. Empty or whitespace-only values are ignored.
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "",
-    "ANTHROPIC_BASE_URL": "",
-    "ANTHROPIC_MODEL": ""
-  }
-}
-```
-
-| Variable | Required | Default | Description |
-| --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | Yes | — | Your Anthropic API key, or the key for a third-party / proxy service. |
-| `ANTHROPIC_BASE_URL` | No | `https://api.anthropic.com` | Point the SDK at a non-official / proxy endpoint. Leave it unset to use the official API — an empty value breaks requests. |
-| `ANTHROPIC_MODEL` | No | `claude-sonnet-4-6` | Override the model. An empty or whitespace-only value falls back to the default. |
+Set `ANTHROPIC_API_KEY` or `ANTHROPIC_AUTH_TOKEN` before running the agent.
+You can also configure the endpoint and model through environment variables or
+`~/.nanoPyCodeAgent/settings.json`. See the [configuration reference](docs/user_docs/en/configuration.md)
+for supported variables, defaults, file format, precedence, and empty-value
+handling.
 
 ### How to Update
 

{nanopycodeagent-0.7.0 → nanopycodeagent-0.9.0}/README.zh-CN.md

@@ -31,6 +31,18 @@ uv tool install nanoPyCodeAgent   # 或: pipx install nanoPyCodeAgent
 nanoPyCodeAgent
 ```
 
+#### 一次性任务(非交互)
+
+给它一个任务,它会自己做完退出——不给提示符,也不会停下来等确认,这正是脚本或
+benchmark harness 需要的形态:
+
+```bash
+nanoPyCodeAgent -p "add a --version flag and run the tests"
+```
+
+任务在当前目录下执行,run 结束后命令随即退出。全部任务输入方式、选项、退出状态、
+trajectory 输出和 Event Journal 行为请参阅[完整 CLI 参考](docs/user_docs/zh-CN/cli_reference.md)。
+
 #### 运行某个分支或标签版本
 
 直接从 GitHub 运行未发布的分支,或某个具体的发布标签:
@@ -45,28 +57,9 @@ uvx --from "git+https://github.com/minixalpha/nanoPyCodeAgent@v0.1.0" nanoPyCode
 
 ### 配置
 
-凭据与模型有两种配置来源:**环境变量**,以及可选的用户级配置文件
-`~/.nanoPyCodeAgent/settings.json`。环境变量优先级更高——配置文件只用于填补你
-未在环境变量中设置的键。
-
-配置文件写法与 [Claude Code settings](https://code.claude.com/docs/en/settings)
-一致:把值放在 `env` 对象下。空值或纯空白会被忽略。
-
-```json
-{
-  "env": {
-    "ANTHROPIC_API_KEY": "",
-    "ANTHROPIC_BASE_URL": "",
-    "ANTHROPIC_MODEL": ""
-  }
-}
-```
-
-| 变量 | 是否必填 | 默认值 | 说明 |
-| --- | --- | --- | --- |
-| `ANTHROPIC_API_KEY` | 是 | 无 | 你的 Anthropic API key,或第三方/代理服务的 key。 |
-| `ANTHROPIC_BASE_URL` | 否 | `https://api.anthropic.com` | 将 SDK 指向非官方/代理 endpoint。使用官方 API 时保持不设置;留空值会导致请求失败。 |
-| `ANTHROPIC_MODEL` | 否 | `claude-sonnet-4-6` | 覆盖默认模型。空值或纯空白会回退到默认值。 |
+运行前请设置 `ANTHROPIC_API_KEY` 或 `ANTHROPIC_AUTH_TOKEN`。你也可以通过
+环境变量或 `~/.nanoPyCodeAgent/settings.json` 配置 endpoint 与模型。支持的变量、
+默认值、文件格式、优先级和空值处理请参阅[配置参考](docs/user_docs/zh-CN/configuration.md)。
 
 ### 如何更新
 

nanopycodeagent-0.9.0/benchmarks/harbor/README.md

@@ -0,0 +1,196 @@
+# Harbor adapter
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+This isolated workspace contains the nanoPyCodeAgent adapter for Terminal-Bench
+and other benchmarks run by Harbor. It is development infrastructure, not part
+of the end-user `nanoPyCodeAgent` package. Harbor is pinned to 0.21.0 in this
+workspace's lockfile.
+
+## Run a benchmark
+
+Set the connection credentials used by the CLI. For a third-party or proxy
+endpoint, configure the API key and base URL; select the model with Harbor's
+`--model` option shown below:
+
+```bash
+export ANTHROPIC_API_KEY="..."
+export ANTHROPIC_BASE_URL="https://gateway.example"
+```
+
+Run new benchmarks through the standard entry point, from the repository root:
+
+```bash
+uv run --project benchmarks/harbor python -m harbor_adapter run \
+  --config benchmarks/harbor/configs/qemu-alpine-ssh.json
+```
+
+This example pins the QEMU task revision and uses `deepseek/deepseek-flash`.
+Set the endpoint and credentials for that model, or copy the configuration and
+change `agents[].model_name`, task selection, and budgets for another run. These
+are ordinary Harbor JSON configurations; the entry point supplies the standard
+verifier and cache policy. It accepts the repository's `NanoPyCodeAgent` adapter
+with budget kwargs; credentials belong in the environment.
+
+The entry point builds the current working tree, including uncommitted changes,
+into a wheel and checks its Python sources against the recorded snapshot. It
+also snapshots the adapter, records source and wheel hashes, and uses that
+snapshot throughout the run. Inputs and logs live in `jobs/<job-name>-input/`;
+Harbor outputs remain in `jobs/<job-name>/`. Existing jobs are never overwritten.
+`summary.json` records scores, setup/preflight status, cache use, and verifier
+attempts. An infrastructure exception has no score; it is not converted to zero.
+The command exits nonzero for execution errors or incomplete results, while a
+completed score of zero is a valid benchmark result.
+
+Use `--job-name <unique-name>` for a readable run name. Add `--prepare-only` to
+build and record inputs without starting containers. Add `--install-only` to
+exercise dependency installation and preflight without calling the model or
+executing the official tests. A full run still performs setup and preflight in
+its own fresh container; an install-only check does not resume into model work.
+
+### Verified dependencies and preflight
+
+The standard adapter automatically uses `.cache/nanopy-harbor/`, shared across
+runs and ignored by Git. Override it with `NANOPY_HARBOR_CACHE` or the entry
+point's `--cache-dir`. On APT systems it refreshes the package index, resolves a
+SHA256 download plan, restores matching cached files, and downloads missing
+ones. Successful downloads are verified and saved before installation, so
+APT cleanup hooks cannot erase the shared copies. A different version or digest
+does not reuse an old cached file. Corrupt files fail setup before model work.
+Other package managers use Harbor's regular dependency installation.
+
+To import previously verified downloads once:
+
+```bash
+uv run --project benchmarks/harbor python -m harbor_adapter import-apt \
+  /path/to/bootstrap-cache/manifest.json
+```
+
+The manifest is a JSON array of objects with `url`, `filename`, `size`, and
+`sha256`, accompanied by `packages/<filename>` files. Import validates every
+file. At use time, the current APT index must independently match each entry.
+Copying the entire shared cache to another machine is also supported. A new
+machine with no matching cache still needs the original downloads to be
+available; this mechanism does not replace package sources or invent missing
+versions.
+
+Verifier dependency profiles are tied to reviewed task revisions in
+`src/harbor_adapter/bootstrap.py`. The current QEMU profile installs `sshpass`
+and warms the original verifier's uv 0.9.5, Python 3.13, pytest 8.4.1, and
+pytest-json-ctrf 0.3.5 dependencies using `pytest --version`. It runs no task
+assertions or solution code. Unknown QEMU revisions fail setup pending profile
+review; tasks without a profile explicitly report `not_configured`. Add a
+profile and regression tests when another task needs verifier preflight.
+
+Every installation writes `agent/bootstrap.json`, including partial progress
+on failure. Preflight failure stops the trial before any model call. The
+official verifier script remains unchanged and may still access the network
+when it runs; a successful preflight is not a guarantee against later outages.
+Full standard runs enable the timeout retry policy below by default, with zero
+whole-trial retries. CI checks these contracts without model calls or Docker.
+
+### Direct Harbor invocation
+
+For adapter development or comparison with published versions, the lower-level
+Harbor interface remains available. Pin the agent installed in the container:
+
+```bash
+uv run --project benchmarks/harbor harbor run \
+  --task terminal-bench/openssl-selfsigned-cert \
+  --agent harbor_adapter:NanoPyCodeAgent \
+  --agent-kwarg git_ref=<commit-sha> \
+  --model anthropic/claude-sonnet-4-6 \
+  --verifier harbor_adapter:RetryingVerifier \
+  --verifier-timeout-multiplier 4 \
+  --env docker \
+  --n-concurrent 1 \
+  --n-attempts 1
+```
+
+Use `--agent-kwarg version=<released-version>` instead of `git_ref` to install a
+published PyPI release. The two pins are mutually exclusive. If neither is
+provided, the adapter installs the latest published release. For reproducible
+benchmark results, always provide one of them. Prefer a full 40-character commit
+SHA for `git_ref`; Harbor may parse an unquoted abbreviated SHA such as `83e6271`
+as a number. To use an abbreviated revision, preserve its string type with
+`--agent-kwarg 'git_ref="83e6271"'`.
+
+The adapter sends the instruction through stdin, runs the agent in the task
+container's current directory, and saves combined stdout/stderr to
+`/logs/agent/nanopycodeagent.txt`. It uses the CLI's 50-turn default; override
+that with `--agent-kwarg max_turns=20`.
+
+Use `--agent-kwarg time_budget_seconds=N` to bound task work and remind the model
+to finalize before either time or replies run out. Choose a budget inside each
+task's native timeout, reserving at least 30 seconds for cost reconciliation
+plus trajectory writing and harness overhead. For example, the 3600-second
+targeted experiments use 3420 seconds; that value does not fit a 900-second task.
+No time budget is inferred automatically by the adapter.
+
+For the per-reply generation limit, pass `--agent-kwarg max_tokens=32768`.
+This becomes `--max-tokens 32768` in the container and overrides the forwarded
+`ANTHROPIC_MAX_TOKENS` environment variable. When omitted, the adapter sends no
+token flag, so the installed agent's environment/settings/default applies
+(32768 in the version introducing this option). Older releases require omitting
+the new option. The effective budget is recorded in the startup log and in
+`agent.extra.max_tokens` in the ATIF trajectory.
+
+The adapter also asks the agent to write an ATIF-v1.7 trajectory directly to
+`/logs/agent/trajectory.json`. Harbor collects that file as the trial's native
+ATIF output and backfills prompt, completion, cache-token, and cost totals into
+the agent result. Missing, invalid, or partial trajectories remain explicitly
+diagnosed; unknown usage or cost is not reported as zero.
+If any costs are estimated, `final_metrics.extra` records
+`cost_is_estimated: true` and the estimated portion in `estimated_cost_usd`.
+The adapter preserves both fields in the agent result's `metadata.trajectory`,
+including for partial totals. Estimates with a generation ID remain eligible
+for billing reconciliation; a successful lookup replaces the estimate.
+
+By default, the adapter strips the first provider prefix from `--model` and
+passes the result to nanoPyCodeAgent as `ANTHROPIC_MODEL`. Set
+`ANTHROPIC_MODEL` only when a custom endpoint requires an actual model name that
+differs from Harbor's `provider/model` identity; this explicit override takes
+precedence. Harbor-native provider credentials and configured base URLs are
+also normalized to the `ANTHROPIC_*` variables expected by nanoPyCodeAgent's
+SDK.
+
+## Retry verifier timeouts
+
+The example above uses `harbor_adapter:RetryingVerifier` for single-step Linux
+tasks. It runs the original test script up to **three times total**, retrying
+only when the script exceeds the task's native `[verifier].timeout_sec`. A
+900-second task therefore gets at most three 900-second attempts. A completed
+verification stops immediately, including a reward of zero. Script errors,
+missing or invalid rewards, and cancellation do not trigger another attempt.
+
+`--verifier-timeout-multiplier 4` gives Harbor's outer watchdog room for all
+three attempts plus test upload, process cleanup, and log collection. It does
+not extend each test-script attempt. Conflicting timeout overrides or caps
+that leave insufficient overall time are rejected. Use
+`--verifier-kwarg max_attempts=2` for two total attempts, or `max_attempts=1` for
+one; values above three are rejected.
+
+The runner reuses the same container, agent output, and dependency caches;
+the agent is run once. Test scripts must tolerate being rerun in that
+environment; verifier-side filesystem changes are not rolled back. Timed-out
+process groups and other members of their Linux session are killed before
+retrying. Each attempt's logs and any reward files are archived under
+`verifier/attempts/1/`, `2/`, and `3/`. The runner clears current verifier
+outputs before the next attempt, so a stale reward cannot determine its score.
+`verifier/retry-summary.json` records each attempt's status, duration, and exit
+code when available. Exhausting the attempts still produces Harbor's
+`VerifierTimeoutError`.
+
+This verifier requires `python3` and `bash` in the container, which the
+nanoPyCodeAgent adapter installs. These options apply to new runs; they cannot
+restore a deleted container or missing task outputs from an old trial.
+Harbor's ordinary `--max-retries` setting reruns the entire trial, including
+the agent, and is independent of these verifier attempts.
+
+## Test the adapter
+
+```bash
+uv run --project benchmarks/harbor pytest \
+  -c benchmarks/harbor/pyproject.toml \
+  benchmarks/harbor/tests
+```