diff --git a/.claude/harness-candidates.md b/.claude/harness-candidates.md
index e067e9ad..c734c88a 100644
--- a/.claude/harness-candidates.md
+++ b/.claude/harness-candidates.md
@@ -455,3 +455,12 @@ with the two `action.yml` items above — one considered change to the action's
   `final_status`, which does not exist in `run.json` and would have made a new
   assertion dead on arrival. Guard: assert the key set that non-Python consumers
   depend on, mirroring how CE030 pins doc/schema parity.
+
+- [ ] A `_*TurnState` (agent turn-state) attribute that is written but never read
+  outside its own assignment — CE037-class dead accumulator. Surfaced during the
+  Pi harness port: `_PiTurnState.turns_finished` was copied from OpenCode's
+  `steps_finished` (which drives that agent's `finished_without_tokens` guard) but
+  Pi deliberately dropped that guard, leaving the counter dead. Fixed by hand this
+  run. Guard would need cross-method dataflow over each `Agent`-subclass turn-state
+  class (write sites vs read sites), which the AST-only CExxx runner can't express
+  in ~30 min — deferred. Caught in: Pi harness Phase 2 quality review.
diff --git a/.github/pages-stub/index.html b/.github/pages-stub/index.html
index 4d3677df..39deba00 100644
--- a/.github/pages-stub/index.html
+++ b/.github/pages-stub/index.html
@@ -12,7 +12,7 @@
     -->
     <meta
       name="description"
-      content="Coder Eval is Playwright for coding agents: an open-source, agent-agnostic framework for evaluating and benchmarking AI coding agents and their skills — sandboxed runs of Claude Code, Codex, Antigravity (Gemini), or OpenCode against declarative YAML tasks, with weighted scoring and CI gates. Documentation: coder-eval.com/docs"
+      content="Coder Eval is Playwright for coding agents: an open-source, agent-agnostic framework for evaluating and benchmarking AI coding agents and their skills — sandboxed runs of Claude Code, Codex, Antigravity (Gemini), OpenCode, or Pi against declarative YAML tasks, with weighted scoring and CI gates. Documentation: coder-eval.com/docs"
     />
 
     <!--
@@ -227,7 +227,7 @@ <h1 class="sr-only">Coder Eval</h1>
       <p class="lead">
         <strong>Playwright for coding agents.</strong> An open-source, agent-agnostic framework for
         evaluating and benchmarking AI coding agents and their skills: it runs a real agent — Claude
-        Code, Codex, Antigravity (Gemini), or OpenCode — in a sandbox against declarative YAML
+        Code, Codex, Antigravity (Gemini), OpenCode, or Pi — in a sandbox against declarative YAML
         tasks, then scores the files and commands the agent actually produced.
       </p>
       <p class="notice">
diff --git a/CLAUDE.md b/CLAUDE.md
index 1e988f96..9311bb6b 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -144,7 +144,7 @@ action.yml                         # Published composite GitHub Action (coder-ev
 - **Sub-agent token accounting**: There is NO separate per-sub-agent field. Every sub-agent generation is captured as a `parent_tool_use_id`-tagged `AssistantMessage` in the turn transcript, so per-sub-agent usage is derived by grouping those messages on that id (the evalboard's `aggregateSubAgentUsage` does exactly this). Claude bubbles its sub-agent's intermediate generations into the parent stream natively, and the **terminal** generation (delivered as the Agent tool result, never streamed) is synthesized into one via `_synthesize_subagent_terminal_message` from `tool_use_result.usage`. Codex reconstructs all child generations from the child rollout (`_recover_subagent_tool_calls`). The turn total already includes sub-agent cost — Claude via the SDK's cumulative `model_usage`; Codex via `_fold_subagent_tokens`, which folds the child messages (their real per-generation tokens) into the parent total. `CommandTelemetry.result_summary` is stored **untruncated** (no 200-char cap) so sub-agent returns are preserved whole. Set `CODER_EVAL_RAW_SDK_LOG=1` to dump every raw SDK event to the task log for inspection.
 - **Reconciliation message (stream self-reconciles to the turn total)**: The per-message stream consistently under-reports the authoritative turn total — a fixed prompt slice (~512 input tokens on Claude) is billed on no SDK-emitted message, and sub-agent input/cache only partially bubbles up. So `EventCollector.build_turn_record` appends one synthetic `ReconciliationMessage` (`role="reconciliation"`, in the `TranscriptMessage` union) per turn, carrying the per-bucket residual = `token_usage` − Σ(assistant message buckets). The invariant: **summing the four token buckets across `TurnRecord.messages` (assistant + reconciliation) equals `token_usage` exactly**, for both Claude and Codex (Codex's stream is already complete after `_recover_subagent_tool_calls`, so its residual is usually 0 and no entry is emitted). This is what lets the evalboard SUM the message stream as the source of truth instead of reading a separate aggregate ("agent tokens"): `selectTokenTotals` returns the stream sum whenever a reconciliation entry is present, and the timeline renders it as its own row. It is agent-agnostic (booked at the single `EventCollector` seam), carries no cost (cost stays on `token_usage`), and is excluded from generation/turn counts and the cost simulator. The LiteLLM open-weight actual-cost join (`litellm_cost.apply_actual_cost`) deliberately writes cost at the TURN level only (`token_usage.total_cost_usd` = the real OpenRouter bill) plus the per-call `TurnRecord.provider_call_costs` audit record; it does NOT touch the message token buckets, so `EventCollector` stays the single writer and this invariant holds on every backend. The Python `token_usage`/`total_token_usage` aggregate is unchanged and still authoritative for budget/judges/reports.
 - **Reference solutions are directory-only, and shielded (partially) from the agent**: `task.reference` is a single required `directory:` (relative to the task YAML) — the inline `code:` / single-file `file:` forms are gone, because a directory is the only shape that can be permission-gated as a unit; a `model_validator(mode="before")` gives the removed forms a migration error. The orchestrator stages a **per-run private copy** (`orchestration/evaluation.py::stage_reference_dir`, symlinks stripped) into a tempdir, removed in `_cleanup` via `path_utils.rmtree_restrictive` (keyed on `_reference_staging_root`, recorded BEFORE the copy so a failed copy still cleans up; `rmtree(ignore_errors=True)` silently declines on a tree left at 000) and deliberately never preserved into `run_dir/artifacts`. That copy is held at mode `000` for the whole of every `agent.communicate` call via **`Sandbox.set_permissions`**, the driver-aware wrapper over `fs_permissions.py::set_permissions`. Windows **stack**: exiting restores the *enclosing* window's mode, only the outermost exit restores the pre-window mode — that is what makes a mid-turn re-grant (`mode=READ_ONLY_MODE`) expressible, and it covers two windows at the same mode so no refcount is needed. The window is enforced **only inside a docker container** (`Sandbox.enforces_permission_windows`) and is a no-op on the host, where the agent shares our uid. **That gate keys on the `CODER_EVAL_IN_CONTAINER` env var, NOT `sandbox.driver`** — `run_task_internal_command` rewrites `driver: docker` → `tempdir` before building the in-container Orchestrator, so a driver-based gate would silently disable the anti-cheat on exactly the path that needs it (regression-guarded by `TestSandboxDriverGate`); `resolve_reference_dir` gates its `/work/references` branch on the same var for the same reason. The task directory is **not** shielded (`:ro` mount → EROFS, and the same YAML is readable at `/work/input`). Criteria address reference files with the `$REFERENCE_DIR` token (same resolver as `$TASK_DIR`) and the `REFERENCE_DIR` env var for `run_command`; `reference_comparison` names one file via `reference_file`. Docker mounts a throwaway **read-write** copy at `/work/references` (a `:ro` mount cannot be chmod'd — EROFS), masks the in-task-dir original with an empty tmpfs, and drops `DAC_OVERRIDE`/`DAC_READ_SEARCH`. `FOWNER`/`CHOWN` are deliberately **NOT** dropped: the in-container orchestrator that applies the window is the same root process with the same caps, so dropping `FOWNER` breaks *the harness's own* chmod wherever the bind mount preserves a non-root owner (native Linux — verified: `chmod: Operation not permitted`), i.e. exactly where the drop would otherwise bite. A window that cannot be applied is now a hard error, not a warning: `Sandbox.set_permissions` passes `strict=True` whenever it enforces, so an unprotected run fails instead of producing a normal-looking score. **KNOWN GAP — this is defense-in-depth, not a boundary**: (a) `chmod(2)` is gated on owner-or-`CAP_FOWNER` and the container runs as root owning the copy, so a deliberate `chmod 755 /work/references` restores access; (b) the window spans `agent.communicate` only, and nothing reaps agent child processes at turn end, so a backgrounded read loop succeeds once the window closes. The **write** half of (b) is closed — `path_utils.digest_tree` hashes the tree at staging and `Orchestrator._verify_reference_integrity` re-checks before grading, raising `ReferenceTamperedError` (→ `FinalStatus.ERROR`) on a mismatch so an agent cannot overwrite the reference to drive `reference_comparison` to 1.0. Passive reads are blocked; an adversarial agent is not. Full containment requires running the agent as a non-root uid AND holding the window for the agent's whole lifetime — follow-up. `tasks/anti_cheat_reference` probes the passive-read half.
-- **Harness run-limit parity**: a shared `BaseAgentConfig` field must mean the same thing on every backend, so a divergence is either fixed or documented — never silent. **`run_limits.max_turns` on Codex/Antigravity counts VISIBLE turns** (resolved tool calls, read live off the shared `EventCollector.visible_turn_count`, the same list `TurnRecord.commands` holds) because one `communicate()` is a single SDK turn on both, so a native counter would clamp at 1; claude-code keeps its native SDK cap, whose unit (an agent-loop turn) absorbs arbitrarily many parallel calls — the same number is NOT the same budget across harnesses. OpenCode likewise keeps a native unit — the CLI streams a real multi-step loop per `communicate()` (`step_start`/`step_finish`), so `max_turns: N` allows N complete steps and cuts cleanly when step N+1 begins. The cap is enforced on the same loop boundary as the cooperative early stop and finalizes cleanly as `max_turns_exhausted` (no crash, no retry); on Antigravity that boundary lives in `_drain()`, so the background-work poll loop honors it too. Known unfixed divergences: `permission_mode` on Codex and Antigravity (both run unconfined — the sandbox driver is the isolation boundary), `disallowed_tools` on Codex (forwarded, not SDK-enforced), `allowed_tools`/`disallowed_tools` on Antigravity (not read at all), `turn_timeout` on Antigravity (bounded by an earlier internal poll deadline at 80% of it), `allowed_tools`/`disallowed_tools`/`system_prompt` on OpenCode (no CLI knob; warned at `start()`, not enforced), and **`agent.plugins[].path` depth** — claude-code REQUIRES a plugin root holding `skills/` and silently loads NOTHING from a bare skills directory, while Codex and Antigravity scan both depths and accept either. That is the costly direction: the wrong depth produces no error, every positive row of an activation suite scores 0, and the suite reports recall 0.0, which reads exactly like a skill that never triggers. Held to the plugin-root shape (for `SKILL_SOURCE_PATH` only) by lint rule CE045. `plugins` on OpenCode is **honored for skills**: each local plugin root is mapped to the `skills` dir its `.claude-plugin/plugin.json` declares (default `<root>/skills`, never the root itself — `skills.paths` is scanned recursively and a plugin root can hold a self-referential symlink) and injected via `OPENCODE_CONFIG_CONTENT`, which `--pure` does not suppress; a plugin's agents/hooks/commands/MCP servers are still dropped. Full table + rationale: docs/agents/HARNESS_PARITY.md.
+- **Harness run-limit parity**: a shared `BaseAgentConfig` field must mean the same thing on every backend, so a divergence is either fixed or documented — never silent. **`run_limits.max_turns` on Codex/Antigravity counts VISIBLE turns** (resolved tool calls, read live off the shared `EventCollector.visible_turn_count`, the same list `TurnRecord.commands` holds) because one `communicate()` is a single SDK turn on both, so a native counter would clamp at 1; claude-code keeps its native SDK cap, whose unit (an agent-loop turn) absorbs arbitrarily many parallel calls — the same number is NOT the same budget across harnesses. OpenCode likewise keeps a native unit — the CLI streams a real multi-step loop per `communicate()` (`step_start`/`step_finish`), so `max_turns: N` allows N complete steps and cuts cleanly when step N+1 begins. **Pi** is the same shape — the CLI (`pi -p --mode json`) streams a real multi-step loop per `communicate()` (`turn_start`/`turn_end`), so `max_turns: N` counts native `turn_start` steps; Pi retries transient/provider errors INTERNALLY (`agent_end.willRetry`), and the reducer finalizes once at `agent_settled`/EOF (not the first `agent_end`), folding the retry cycles into one turn. The cap is enforced on the same loop boundary as the cooperative early stop and finalizes cleanly as `max_turns_exhausted` (no crash, no retry); on Antigravity that boundary lives in `_drain()`, so the background-work poll loop honors it too. Known unfixed divergences: `permission_mode` on Codex, Antigravity, and Pi (all run unconfined — the sandbox driver is the isolation boundary), `disallowed_tools` on Codex (forwarded, not SDK-enforced), `allowed_tools`/`disallowed_tools` on Antigravity (not read at all), `turn_timeout` on Antigravity (bounded by an earlier internal poll deadline at 80% of it), `allowed_tools`/`disallowed_tools`/`system_prompt` on OpenCode (no CLI knob; warned at `start()`, not enforced), `allowed_tools`/`disallowed_tools` on Pi (its built-in tool names are lowercase — `bash`/`read`/… — and cannot map to the Claude-namespaced config default, so forwarding them would strip the agent of ALL tools; warned+ignored like the three agents above) — Pi DOES enforce `system_prompt` (`--append-system-prompt`, a small win over OpenCode) and DOES honor `plugins` for skills (each resolved skills dir → a `--skill <dir>` arg via the shared `_plugin_skill_dirs` resolver, recorded as `pi_skill_paths`, so it CAN run activation suites) but does NOT read `system_prompt_file`, and **`agent.plugins[].path` depth** — claude-code REQUIRES a plugin root holding `skills/` and silently loads NOTHING from a bare skills directory, while Codex and Antigravity scan both depths and accept either. That is the costly direction: the wrong depth produces no error, every positive row of an activation suite scores 0, and the suite reports recall 0.0, which reads exactly like a skill that never triggers. Held to the plugin-root shape (for `SKILL_SOURCE_PATH` only) by lint rule CE045. `plugins` on OpenCode is **honored for skills**: each local plugin root is mapped to the `skills` dir its `.claude-plugin/plugin.json` declares (default `<root>/skills`, never the root itself — `skills.paths` is scanned recursively and a plugin root can hold a self-referential symlink) and injected via `OPENCODE_CONFIG_CONTENT`, which `--pure` does not suppress; a plugin's agents/hooks/commands/MCP servers are still dropped. Full table + rationale: docs/agents/HARNESS_PARITY.md.
 - **sandbox isolation**: Tasks that don't need MCP servers should set `setting_sources: []` in their `agent:` block to isolate the sandbox from the host project's CLAUDE.md and settings. Without this, the host project's CLAUDE.md (often 20 KB+) is injected into every API call, inflating cache-creation tokens and cost significantly.
 - **Run-time caps (non-criterion enforcement)**: `TaskDefinition.run_limits` (`RunLimits` model) is the single namespace for all *task-level* run-time caps — `max_turns` / `task_timeout` / `turn_timeout` (structural) and `max_input_tokens` / `max_output_tokens` / `max_total_tokens` / `max_usd` (cumulative budget). Token/USD breaches abort with `FinalStatus.TOKEN_BUDGET_EXCEEDED` or `COST_BUDGET_EXCEEDED` (both `category == "failed"`). Structural caps are set from the CLI via `-D run_limits.max_turns=…` / `-D run_limits.task_timeout=…` / `-D run_limits.turn_timeout=…` (field-merged into `run_limits`); budget caps via `-D run_limits.max_usd=…` etc. or YAML. Layered config uses field-merge — a variant block overrides individual keys without replacing the task's block. The one *per-criterion* cap, `stop_early.decide_within`, deliberately lives on `LiveSuccessCriterion` instead (see below) — the watcher must attribute a decision-step timeout to a specific criterion, which `RunLimits` (task-scoped, criterion-agnostic) cannot express.
 - **Early stop on criterion (opt-in, per-criterion arming)**: a `stop_early:` block (`StopEarlyPolicy`) on a criterion ends a single-shot run early once the run's **armed** criteria decide the outcome, so a raised `max_turns` isn't wasted on the smoke flavor. The block's PRESENCE is the arming and alone activates the watcher — there is **no run-level master switch**: `run_limits.stop_early: false` is the run-level KILL SWITCH that force-disarms every block (the one-line experiment-variant/`-D` override for an authoritative full run), and `run_limits.stop_early: true` (the removed master arm) is a hard `EarlyStopConfigError` at resolution. The block exists on `LiveSuccessCriterion` only (currently `skill_triggered`, `command_executed` — so arming an unobservable criterion is unrepresentable, a pydantic extra-forbid error). Arming carries one implicit trigger (a native live-fail may fail-stop the run); its keys refine it: `on_pass: stop` (pass-stop the moment the criterion live-passes; default `continue` just latches) and `decide_within: N` (still undecided after N tool-call steps latches an **effective fail**, fed through the same fail-stop rule, reported as `decision_budget_exceeded` — an ordinary weighted fail, NOT a gate-bypassing force-fail; cumulative across retry attempts of the same turn). A trigger whose polarity the instance can't decide (per the abstract, checker-independent `live_decidable_polarities()`, a pure function of the criterion's own fields, paired with the checker's `live_verdict` override by lint rule CE025, a registry-based whole-tree check) is **inert by design** — one dataset-fanned YAML line serves both positive rows (pass/timeout live) and distractor rows (fail live). Verdicts **latch**: once a criterion decides, its `live_verdict` is never polled again. Stop rule is weighted, not strict-boolean: `run_limits.stop_early_gate_threshold` (default `1.0`, reproducing strict-AND behavior exactly) is the minimum weighted score (`Σ weight·score / Σ weight` over the armed subset) required to pass; a fail-stop fires once the armed set's **ceiling** (best case for everything still undecided) can no longer reach the threshold — so a low-weight fail or timeout that can't doom the gate is absorbed and the run continues — and is **deferred while any pass-capable armed criterion is undecided** (a distractor misfire never truncates a positive row's recall signal); a pass-stop fires once the `on_pass: stop` subset's **floor** (worst case) already meets the threshold, and is symmetrically **deferred while any pass-capable armed criterion outside the `on_pass: stop` subset is undecided** (so an early pass never freezes a sibling `on_pass: continue` criterion's signal out of the trajectory). A fail-stop is therefore verdict-preserving; a pass-stop can miss a *later* distractor misfire, so authoritative P/R/F1 comes from a kill-switched (`stop_early: false`) run. Driven by `orchestration/early_stop.py::EarlyStopWatcher` (built when `early_stop_active(task)`: ≥1 armed criterion, kill switch not thrown) through the agent's cooperative `should_stop` seam (tool-call granularity, no SIGKILL); live verdicts only *trigger* the stop — the standard `check_all_async` on the frozen trajectory is authoritative. Gating is **FIRED-ONLY**: a run the watcher actually cut gates on the **armed subset** via the weighted `EvaluationResult.armed_criteria_passed`; a run that completes naturally — armed or not — gates strict-AND via `all_criteria_passed`, so adding a block never changes the verdict of a run it didn't cut. Note the gate keys on the watcher having FIRED (`result.early_stop is not None`), not on confirmed truncation — an agent that ignores `should_stop`, or a stop firing on the final message, still gates armed-only. Every resolution-time guardrail violation is a hard error at resolution (plan *and* run); the one load-time case — a `stop_early:` block on a non-live criterion — is a pydantic schema error at task load, which the run surface reports as a skipped task like any other malformed task. A runtime verdict bug **fails open** to a full run. Surfaces: `EarlyStopInfo` (incl. `gate_threshold` at stop time), report notes/badges, `stopped_early` run.json rows, `EarlyStopped`/`EarlyStopReason` telemetry dims. Worked rationale: docs/TASK_DEFINITION_GUIDE.md § `stop_early`. No blocks anywhere ⇒ behavior byte-for-byte unchanged.
diff --git a/README.md b/README.md
index 0f8d63f1..e0b78755 100644
--- a/README.md
+++ b/README.md
@@ -17,14 +17,14 @@
 open-source, **agent-agnostic** framework for **evaluating and benchmarking AI coding
 agents and their skills** — built for benchmark authors, CLI builders, and skill
 builders — with sandboxing, reproducibility, and data-driven analysis. It runs a real
-agent — **Claude Code**, **OpenAI Codex**, **Google Antigravity (Gemini)**, or
-**OpenCode** — in a sandbox against declarative YAML tasks, then scores the files and
+agent — **Claude Code**, **OpenAI Codex**, **Google Antigravity (Gemini)**,
+**OpenCode**, or **Pi** — in a sandbox against declarative YAML tasks, then scores the files and
 commands it actually produced. Changing harness is one field (`agent.type`); the
 tasks, criteria, scoring, telemetry, and reports stay the same.
 
 Reach for it when you want to **benchmark agents on your own domain tasks**,
 **test whether a skill triggers** in the agent you ship for, **A/B-test Claude Code
-vs. Codex vs. Gemini vs. OpenCode** (or model vs. model, prompt vs. prompt), or
+vs. Codex vs. Gemini vs. OpenCode vs. Pi** (or model vs. model, prompt vs. prompt), or
 **gate CI on coding-agent quality**. It is **not a fixed leaderboard**: unlike
 SWE-bench or SkillsBench, which rank models on a shared task set, you bring the tasks
 and you bring the scoring — weighted 0.0–1.0 criteria, a `skill_triggered` activation
@@ -40,7 +40,7 @@ care about. See [How it compares](https://coder-eval.com/docs/comparison).
 - **Sandboxed execution** in isolated environments with resource limits
 - **Weighted, continuous scoring** (0.0–1.0) with fractional credit and thresholds
 - **Many criterion types** — from file checks to code similarity and LLM-graded rubrics
-- **Agent-agnostic by design** — Claude Code, OpenAI Codex, Antigravity (Gemini), and OpenCode today; add your own harness through the plugin SPI
+- **Agent-agnostic by design** — Claude Code, OpenAI Codex, Antigravity (Gemini), OpenCode, and Pi today; add your own harness through the plugin SPI
 - **Experiment layer** — A/B agent configs (models, tools, prompts) side-by-side
 - **Full telemetry** — every tool call, token counts, and cost, with real-time streaming
 
@@ -62,7 +62,7 @@ care about. See [How it compares](https://coder-eval.com/docs/comparison).
 ## What you can do with it
 
 - **Benchmark coding agents** — score an agent across a suite of tasks with weighted scoring and pass/fail thresholds
-- **Compare models & configs** — A/B-test Claude vs. Codex vs. Gemini vs. OpenCode, model vs. model, tool-on vs. tool-off, prompt vs. prompt
+- **Compare models & configs** — A/B-test Claude vs. Codex vs. Gemini vs. OpenCode vs. Pi, model vs. model, tool-on vs. tool-off, prompt vs. prompt
 - **Evaluate skills** — verify an agent actually engages a target skill (`skill_triggered`) and score skill-driven suites (SkillsBench-style), on whichever harness your users run
 - **Keep skills up to date in CI** — re-validate your skills on every change or on a schedule; catch silent regressions when models, prompts, or the skills themselves drift
 - **Gate CI on agent quality** — run the suite in GitHub Actions and fail the build on regressions
@@ -252,6 +252,7 @@ The step's exit code is coder-eval's own: non-zero on any failed task.
 | [Codex](docs/agents/CODEX.md) | Running the OpenAI Codex agent |
 | [Antigravity (Gemini)](docs/agents/ANTIGRAVITY.md) | Running the Google Antigravity / Gemini agent |
 | [OpenCode](docs/agents/OPENCODE.md) | Running the OpenCode agent on open-weight models |
+| [Pi](docs/agents/PI.md) | Running the Pi agent on open-weight models |
 | [Run-Limit Parity](docs/agents/HARNESS_PARITY.md) | What each run_limits field means on every harness |
 | [A/B Experiments](docs/AB_EXPERIMENTS.md) | Compare models / tools / prompts across the same tasks |
 | [Bring Your Own Dataset](docs/DATASETS.md) | Fan a single task out over a dataset |
diff --git a/docker/Dockerfile b/docker/Dockerfile
index d9cdd586..99467fac 100644
--- a/docker/Dockerfile
+++ b/docker/Dockerfile
@@ -36,6 +36,12 @@ RUN curl -fsSL https://deb.nodesource.com/setup_22.x | bash - \
     && rm -rf /var/lib/apt/lists/* \
     && npm install -g @anthropic-ai/claude-code@${CLAUDE_CODE_VERSION}
 
+# Pi Node CLI, pinned — same rationale as the Claude Code pin above (the agent
+# binary is a dominant non-model driver of results; @latest would freeze
+# nondeterministically under layer caching). Node 22 + npm are already present.
+ARG PI_VERSION=0.84.4
+RUN npm install -g @earendil-works/pi-coding-agent@${PI_VERSION}
+
 # uv: matches host sandbox.py's `uv venv` + `uv pip install` fast path
 RUN curl -LsSf https://astral.sh/uv/install.sh | env UV_INSTALL_DIR=/usr/local/bin sh
 
@@ -58,12 +64,16 @@ COPY experiments/default.yaml ./experiments/default.yaml
 # come from public PyPI, so this needs no private-index credentials. The RUN
 # below always passes `--extra codex --extra antigravity --extra litellm`.
 #
-# NOT every built-in agent ships here: `opencode` is registered unconditionally
-# but its CLI is a Node package (`npm install -g opencode-ai`), absent from this
-# image, and no OpenCode credentials are in SandboxConfig.env_passthrough -- so
-# `--driver docker` does not support it. Adding it means a pinned version that
-# travels with the release tag (as CLAUDE_CODE_VERSION does) plus an
-# env_passthrough block; see docs/agents/OPENCODE.md "Running in Docker".
+# `pi` IS baked above (pinned PI_VERSION) and its OPENROUTER_API_KEY provider
+# credential is in DockerDriverConfig.env_passthrough, so `--driver docker --type pi`
+# is supported. NOT every built-in agent ships here, though: `opencode` is
+# registered unconditionally but its CLI is a Node package
+# (`npm install -g opencode-ai`), absent from this image -- so `--driver docker`
+# does not support it. (OPENROUTER_API_KEY IS now in env_passthrough, added for Pi,
+# so an OpenCode env-auth run would authenticate once the CLI is baked; the CLI is
+# the remaining blocker.) Adding it means a pinned version that travels with the release
+# tag (as CLAUDE_CODE_VERSION / PI_VERSION do) plus an env_passthrough block; see
+# docs/agents/OPENCODE.md "Running in Docker".
 #
 # CODER_EVAL_UV_EXTRAS carries ADDITIONAL opt-in extras on top of those; it
 # defaults to none. `make docker-image-full` passes `--extra uipath`, which
diff --git a/docs/DOCKER_ISOLATION.md b/docs/DOCKER_ISOLATION.md
index 6018f418..14850092 100644
--- a/docs/DOCKER_ISOLATION.md
+++ b/docs/DOCKER_ISOLATION.md
@@ -15,7 +15,7 @@ Set `sandbox.driver: docker` on a task (or pass `--driver docker` on the CLI —
 a thin alias for `-D sandbox.driver=docker`) when you want:
 
 - **Isolation from the host filesystem/network** — agent-generated code can't reach files outside the sandbox.
-- **A pinned toolchain** — the image bakes in Python 3.13, Node 22 LTS, `@anthropic-ai/claude-code`, `uv`, and the matching `coder_eval` version, so results don't drift with host upgrades.
+- **A pinned toolchain** — the image bakes in Python 3.13, Node 22 LTS, `@anthropic-ai/claude-code`, the `pi` CLI (`@earendil-works/pi-coding-agent`), the codex/antigravity/litellm agent SDKs, `uv`, and the matching `coder_eval` version, so results don't drift with host upgrades.
 
 Aggregation (P/R/F1, suite thresholds, reports) always stays on the host. Each container is a sealed "run one task → emit one `task.json`" worker.
 
diff --git a/docs/EXTENDING.md b/docs/EXTENDING.md
index 3befae19..401380d9 100644
--- a/docs/EXTENDING.md
+++ b/docs/EXTENDING.md
@@ -285,8 +285,8 @@ The base package ships **no** plugin rates; only the built-in table.
 ## See also
 
 - [Claude Code](agents/CLAUDE_CODE.md) · [Codex](agents/CODEX.md) ·
-  [Antigravity](agents/ANTIGRAVITY.md) · [OpenCode](agents/OPENCODE.md) — the
-  built-in agents, each registered via this same SPI
+  [Antigravity](agents/ANTIGRAVITY.md) · [OpenCode](agents/OPENCODE.md) ·
+  [Pi](agents/PI.md) — the built-in agents, each registered via this same SPI
 - [Task Definition Guide](TASK_DEFINITION_GUIDE.md) — the criterion catalogue
 - [CLAUDE.md](https://github.com/UiPath/coder_eval/blob/main/CLAUDE.md) — architecture
   and extension points in depth
diff --git a/docs/USER_GUIDE.md b/docs/USER_GUIDE.md
index 1676690d..33e15620 100644
--- a/docs/USER_GUIDE.md
+++ b/docs/USER_GUIDE.md
@@ -39,7 +39,7 @@ coder-eval run tasks/hello_date.yaml --stream full  # live LLM output
 | `-D path=value` / `--set` | Override any resolved task-config field (`agent`/`run_limits`/`sandbox` roots), e.g. `-D run_limits.max_turns=30 -D agent.permission_mode=plan -D agent.sdk_options.effort=high`. Repeatable; schema-validated. This is the way to set permission mode, turn/timeout limits, token/USD budget caps, tools, plugins, and SDK options. |
 | `--model, -m` | Shorthand alias for `-D agent.model=…` (e.g., `claude-sonnet-5`) |
 | `--driver` | Shorthand alias for `-D sandbox.driver=…` (`tempdir` or `docker`) |
-| `--type, -T` | Override agent type for all tasks (`claude-code`, `codex`, `antigravity`, `opencode`, or a plugin kind). |
+| `--type, -T` | Override agent type for all tasks (`claude-code`, `codex`, `antigravity`, `opencode`, `pi`, or a plugin kind). |
 | `--repeats` | Run each `(task, variant)` N times (≥1); overrides experiment/variant `repeats:`. See [Replicates](#replicates). |
 | `--resume` | Resume an interrupted run: skip tasks already finalized in `--run-dir` and run the rest, folding prior results into `run.json`. Requires `--run-dir`. A task with *any* final status (incl. FAILED/ERROR) counts as finalized, so resume does **not** retry failures — delete a task's `task.json` to force a re-run. A config mismatch is warned, not refused. |
 | `--sample N` | For dataset-backed tasks, run a fixed-seed random N-row sample (reproducible; cheap smoke test). See [Bring Your Own Dataset](DATASETS.md). |
diff --git a/docs/agents/HARNESS_PARITY.md b/docs/agents/HARNESS_PARITY.md
index 8053c47b..7da24b4e 100644
--- a/docs/agents/HARNESS_PARITY.md
+++ b/docs/agents/HARNESS_PARITY.md
@@ -10,12 +10,12 @@ This page is the contract for what each run limit means per harness, plus the sh
 
 ## The table
 
-| Limit | claude-code | codex | antigravity | opencode |
-|---|---|---|---|---|
-| `run_limits.max_turns` | native SDK cap (agent-loop turns) | visible-turn cap (resolved tool calls) | visible-turn cap (resolved tool calls) | native step cap (the CLI's own agent-loop steps) |
-| `run_limits.turn_timeout` | watchdog, SIGKILL on the CLI subprocess | watchdog + cooperative interrupt | watchdog, plus an earlier internal poll deadline at 80% of it (see below) | deadline enforced in-loop and on the final reap; SIGTERM→SIGKILL on the CLI's whole process group |
-| `run_limits.task_timeout` | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic |
-| `run_limits.stop_early` | cooperative `should_stop` | cooperative `should_stop` | cooperative `should_stop` | cooperative `should_stop` (event granularity) |
+| Limit | claude-code | codex | antigravity | opencode | pi |
+|---|---|---|---|---|---|
+| `run_limits.max_turns` | native SDK cap (agent-loop turns) | visible-turn cap (resolved tool calls) | visible-turn cap (resolved tool calls) | native step cap (the CLI's own agent-loop steps) | native turn cap (the CLI's own `turn_start` agent-loop steps) |
+| `run_limits.turn_timeout` | watchdog, SIGKILL on the CLI subprocess | watchdog + cooperative interrupt | watchdog, plus an earlier internal poll deadline at 80% of it (see below) | deadline enforced in-loop and on the final reap; SIGTERM→SIGKILL on the CLI's whole process group | deadline enforced in-loop and on the final reap; SIGTERM→SIGKILL on the CLI's whole process group |
+| `run_limits.task_timeout` | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic | orchestrator-level, agent-agnostic |
+| `run_limits.stop_early` | cooperative `should_stop` | cooperative `should_stop` | cooperative `should_stop` | cooperative `should_stop` (event granularity) | cooperative `should_stop` (event granularity — Pi streams incrementally) |
 
 ## `max_turns` counts visible turns on Codex and Antigravity
 
@@ -50,6 +50,14 @@ when step N+1 begins, with the completed steps' tokens intact. A step is one
 assistant generation and may carry several tool calls — so, as with claude-code,
 the same number is a looser tool-call budget than on the visible-turn backends.
 
+**Pi keeps a native unit too — its `turn_start` agent-loop steps.** Like OpenCode,
+`pi -p --mode json` runs a real multi-step agent loop per invocation and streams it
+(`turn_start` / `turn_end`), so `max_turns: N` allows N complete turns and cuts the
+run when turn N+1 begins, with the completed turns' tokens intact. Pi streams
+incrementally, so the cut genuinely stops spend mid-run. A Pi turn is one assistant
+generation and may carry several tool calls — the same looser budget as claude-code
+and OpenCode.
+
 **So holding `max_turns` constant across harnesses does not hold the budget
 constant.** If you are A/B-ing across backends and the cap is close to binding, that
 is the number to distrust.
@@ -116,10 +124,10 @@ whose cap fires should not look like a task whose harness hung.
 Not a run limit, but the same promise: one task file, three harnesses, same meaning.
 This field breaks it silently.
 
-| | claude-code | codex | antigravity |
-|---|---|---|---|
-| `<path>/skills/<name>/SKILL.md` (plugin root) | **required** | accepted | accepted |
-| `<path>/<name>/SKILL.md` (bare skills dir) | **loads nothing** | accepted | accepted |
+| | claude-code | codex | antigravity | pi |
+|---|---|---|---|---|
+| `<path>/skills/<name>/SKILL.md` (plugin root) | **required** | accepted | accepted | accepted |
+| `<path>/<name>/SKILL.md` (bare skills dir) | **loads nothing** | accepted | accepted | **loads, but undetected** † |
 
 claude-code hands the value to the SDK as a *plugin directory*, and a plugin's skills
 live at `<plugin>/skills/<name>/SKILL.md`. Point it at the directory that directly
@@ -127,6 +135,15 @@ parents the skill directories and no skill loads. Codex
 (`codex_agent._setup_skills`) and Antigravity (`antigravity_agent._resolve_skills_paths`)
 both scan **both** layouts and take whichever actually holds a `<skill>/SKILL.md`.
 
+† Pi uses the shared `_plugin_skill_dirs` resolver, whose bare-dir fallback resolves a
+bare skills directory to itself and passes it as `--skill <dir>`, so the skill *does*
+load and the agent can use it. But `skill_triggered` detects engagement by matching a
+`skills/<name>/` segment in the read path (`_SKILL_PATH_RE`), which a bare dir lacks — so
+an **activation suite** on a bare dir still scores recall 0 even though the skill ran.
+Net effect for activation suites is therefore the same silent-0 as claude-code, via a
+different mechanism; use the plugin-root shape (lint rule CE045 holds `SKILL_SOURCE_PATH`
+to it for exactly this reason).
+
 So `.claude/skills` works on two backends out of three and fails on the third — and
 fails without an error. The agent simply is not offered the skill, every positive row
 of an activation suite scores 0, and the suite reports recall 0.0. That is
@@ -165,15 +182,45 @@ plugin-root shape by lint rule CE045. The rule keys on that variable name only;
 one, feeds `experiments/plugin-comparison.yaml`, whose default agent is claude-code,
 so the same requirement applies there and is unlinted.
 
+**OpenCode and Pi both honor the *skills* half of a plugin.** OpenCode maps each
+local plugin root to its `skills.paths`; Pi maps each to a `--skill <dir>` argument —
+both via the same `_plugin_skill_dirs` resolver — so both **can** run activation
+suites. A plugin's non-skill assets (agents/hooks/commands/MCP servers) are dropped on
+both. See [OpenCode](OPENCODE.md) and [Pi § plugins](PI.md#known-limitations).
+
+## Pi enforces `system_prompt` but not the tool allowlists
+
+- **`system_prompt` is ENFORCED** (`--append-system-prompt`, semantics `append`) — a
+  small win over OpenCode, which drops it.
+- **`allowed_tools` / `disallowed_tools` are NOT enforced.** Pi's built-in tools are
+  lowercase (`bash`/`read`/`write`/`edit`/`grep`/`find`/`ls`), but the shared config
+  default (`experiments/default.yaml`) sets Claude-namespaced names
+  (`Bash`/`Read`/`Write`/…). Forwarding those to `--tools` would allowlist tools that
+  do not exist in Pi and strip the agent of ALL tools — so, like OpenCode (drops them),
+  Codex (forwards `disallowed_tools` without SDK enforcement), and Antigravity (does not
+  read them), Pi ignores them and runs with its full native toolset. A task that needs a
+  restricted Pi toolset would have to name Pi's lowercase tools — a documented follow-up.
+- **`permission_mode` is NOT enforced** — Pi headless print mode auto-runs tools and
+  exposes only project-file trust (`--approve` / `--no-approve`), no tool-approval
+  mode; the sandbox driver is the isolation boundary (same as Codex/Antigravity).
+- **`system_prompt_file` is NOT read** (use inline `system_prompt`), matching
+  Codex/Antigravity.
+- **Built-in auto-retry.** Pi retries a transient/provider error *internally* (another
+  `agent_start` cycle in the same invocation, flagged `willRetry: true`), which the
+  harness folds into one turn. The internal retry is bounded by
+  `turn_timeout` / `task_timeout`.
+
+Full detail: [Pi](PI.md).
+
 ## Reproducing
 
 `tasks/run_limits/` holds one fixture per limit: `max_turns_cap.yaml` asks for more
 sequential work than its cap allows, and `turn_timeout.yaml` runs a command that
 outlives its watchdog. Run either with `--type claude-code` / `--type codex` /
-`--type antigravity` / `--type opencode` to check a backend against the contract
-above.
+`--type antigravity` / `--type opencode` / `--type pi` to check a backend against the
+contract above.
 
 ## Related
 
-- [Claude Code](CLAUDE_CODE.md) · [Codex](CODEX.md) · [Antigravity](ANTIGRAVITY.md) · [OpenCode](OPENCODE.md)
+- [Claude Code](CLAUDE_CODE.md) · [Codex](CODEX.md) · [Antigravity](ANTIGRAVITY.md) · [OpenCode](OPENCODE.md) · [Pi](PI.md)
 - [Task Definition Guide](../TASK_DEFINITION_GUIDE.md) — the full `run_limits` schema
diff --git a/docs/agents/OPENCODE.md b/docs/agents/OPENCODE.md
index 31921b3d..09327d30 100644
--- a/docs/agents/OPENCODE.md
+++ b/docs/agents/OPENCODE.md
@@ -295,17 +295,18 @@ Two things are missing, both deliberate rather than overlooked:
   pinned version that travels with the coder_eval release tag the way
   `CLAUDE_CODE_VERSION` does — a release-process decision, not a one-line edit.
   (Node 22 is already present in the image, so the change itself is small.)
-- **No credentials would reach it.** The docker driver forwards host environment
-  variables through an explicit allowlist (`SandboxConfig.env_passthrough`),
-  which carries per-harness blocks for Codex and Antigravity but none for
-  OpenCode — so `OPENROUTER_API_KEY` and friends are not passed through, and
-  `opencode auth login`'s credential file is not mounted. Even a custom image
-  with the CLI baked in would authenticate against nothing.
-
-Until both land, run OpenCode tasks under `tempdir` (the default) on a host that
-has the CLI and its provider credentials. If you need container isolation now,
-build your own image from `docker/Dockerfile` with the `npm install -g` line
-added and pass the credentials via `sandbox.env_passthrough_extra`.
+- **Env auth partly reaches it; file auth does not.** `OPENROUTER_API_KEY` **is**
+  now in the default allowlist (`DockerDriverConfig.env_passthrough` — added for
+  Pi), so a custom image with the OpenCode CLI baked in *would* authenticate
+  against an OpenRouter model. But `opencode auth login`'s credential file is not
+  mounted, so any provider OpenCode authenticates via that file (not env) still
+  reaches nothing.
+
+Until the CLI is baked in, run OpenCode tasks under `tempdir` (the default) on a
+host that has the CLI and its provider credentials. If you need container
+isolation now, build your own image from `docker/Dockerfile` with the
+`npm install -g` line added; `OPENROUTER_API_KEY` already forwards by default, and
+any other provider credential can be added via `sandbox.env_passthrough_extra`.
 
 ## Known limitations
 
@@ -324,10 +325,10 @@ added and pass the credentials via `sandbox.env_passthrough_extra`.
   visible-turn unit Codex/Antigravity use — see
   [Run-Limit Parity](HARNESS_PARITY.md) before holding `max_turns` constant
   across harnesses.
-- **The `docker` sandbox driver is unsupported.** The CLI is not in the image and
-  no OpenCode credentials are in the `env_passthrough` allowlist — see
-  [Running in Docker](#running-in-docker) for the workaround and what it would
-  take to close.
+- **The `docker` sandbox driver is unsupported.** The CLI is not in the image
+  (`OPENROUTER_API_KEY` is now forwarded by default, added for Pi, but the OpenCode
+  CLI itself is still absent) — see [Running in Docker](#running-in-docker) for the
+  workaround and what it would take to close.
 - **No sub-agent attribution.** OpenCode's CLI stream does not expose nested agent
   generations, so per-sub-agent token grouping (available for Claude and Codex) is
   not derivable.
diff --git a/docs/agents/PI.md b/docs/agents/PI.md
new file mode 100644
index 00000000..eb515197
--- /dev/null
+++ b/docs/agents/PI.md
@@ -0,0 +1,272 @@
+---
+description: >-
+  Run Pi, the pi Node coding agent, as the agent under evaluation in Coder
+  Eval — installation, provider authentication, model selection, the enforced
+  and divergent config fields, and how its event stream maps to sandboxed,
+  weighted scoring.
+---
+
+# Running Pi in Coder Eval
+
+## Overview
+
+[Pi](https://pi.dev/) is a Node terminal coding agent (the `pi` CLI). Coder Eval
+drives it in **JSON print mode**:
+
+```bash
+pi -p --mode json --no-context-files --no-approve \
+   --session-dir <dir> --session-id <id> --model <provider/id> -- "<prompt>"
+```
+
+`--mode json` streams **newline-delimited JSON events** on stdout, one event per
+line. `PiAgent` reduces that stream into the standardized event protocol
+(`AgentStart` / `TurnStart` / `ToolStart` / `ToolEnd` / `TurnEnd` / `AgentEnd`)
+and lets `EventCollector` build the `TurnRecord`, exactly like every other
+harness.
+
+Because Pi is model-agnostic, this is a cheap way to evaluate a broad set of
+open-weight models (Kimi, DeepSeek, GLM, …) through a single agent. Pi **enforces
+`system_prompt`** (via `--append-system-prompt`) — a small win over OpenCode. It
+does **not** enforce `allowed_tools` / `disallowed_tools`: the shared config
+default uses Claude-namespaced tool names (`Bash`/`Read`/`Write`/…) that do not
+match Pi's lowercase built-ins (`bash`/`read`/`write`/…), so forwarding them would
+leave the agent with no tools at all. Like OpenCode / Codex / Antigravity, Pi
+therefore runs with its full native toolset and warns that these fields are
+unenforced.
+
+## Setup
+
+### 1. Install the Pi CLI
+
+Pi is a **Node** CLI, not a Python package:
+
+```bash
+npm install -g @earendil-works/pi-coding-agent
+pi --version
+```
+
+The `coder-eval[pi]` extra exists for symmetry with the other harnesses and
+carries **no Python dependencies** — the agent shells out to the binary above and
+imports no third-party package:
+
+```bash
+uv sync --extra pi   # documents the opt-in; installs no extra packages
+```
+
+If the binary is missing, the task fails at `start()` with an actionable error
+naming the install command, rather than failing obscurely mid-run.
+
+### 2. Authentication
+
+Pi addresses a model as `provider/id` and reads the provider key from the
+environment, which Coder Eval forwards into the subprocess (it also picks up keys
+from `.env`, since `config.py` calls `load_dotenv(override=True)`):
+
+```bash
+export OPENROUTER_API_KEY="sk-or-..."   # OpenRouter (any model)
+```
+
+## Usage
+
+### Command line
+
+```bash
+uv run coder-eval run tasks/pi_smoke_test.yaml
+uv run coder-eval run tasks/my_task.yaml -D agent.type=pi -D agent.model=openrouter/moonshotai/kimi-k3
+```
+
+### Task definition (YAML)
+
+```yaml
+agent:
+  type: "pi"
+  # provider-prefixed model id; no separate --provider needed.
+  model: "openrouter/moonshotai/kimi-k3"
+  permission_mode: "acceptEdits"
+  thinking_level: "medium"   # optional: reasoning effort (see below)
+```
+
+### Model selection
+
+`agent.model` is passed through verbatim to `--model`, so it must be Pi's
+provider-prefixed `provider/id` form. The provider prefix decides which
+credential is used:
+
+| `agent.model` | Provider | Credential |
+|---|---|---|
+| `openrouter/moonshotai/kimi-k3` | OpenRouter | `OPENROUTER_API_KEY` |
+
+Pi speaks OpenRouter natively, so it does **not** need the LiteLLM proxy — that
+shim exists to translate Anthropic ↔ OpenAI for the Claude Code SDK.
+
+> On some OpenRouter accounts a model is blocked by an account **guardrail**
+> (`404 "model blocked by guardrail"`). That is an account setting, not a Coder
+> Eval problem — adjust it at
+> [openrouter.ai/settings/privacy](https://openrouter.ai/settings/privacy), or
+> pick another model. `openrouter/moonshotai/kimi-k3` runs cleanly on the dev
+> account and is the smoke task's default.
+
+### `thinking_level`
+
+Pi's reasoning effort, forwarded as `--thinking`. Accepts the seven-value set
+`off` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max` (a strict
+superset of the Antigravity `thinking_level`), defaulting to `medium`.
+
+### Enforced config fields
+
+Pi forwards these config knobs to real CLI flags:
+
+| Field | Pi flag |
+|---|---|
+| `system_prompt` | `--append-system-prompt <text>` (appended, semantics `append`) |
+| `thinking_level` | `--thinking <level>` |
+| `model` | `--model <provider/id>` |
+
+### Unenforced config fields
+
+`allowed_tools` / `disallowed_tools` are **not** forwarded. The shared config
+default (`experiments/default.yaml`) sets Claude-namespaced tool names
+(`Bash`/`Read`/`Write`/`Edit`/`Glob`/`Grep`/`Skill`), but Pi's built-in tools are
+lowercase and differently named (`bash`/`read`/`write`/`edit`/`grep`/`find`/`ls`).
+Passing the PascalCase names to `--tools` would allowlist tools that do not exist
+in Pi, leaving the agent with **zero** tools. So — like OpenCode, Codex, and
+Antigravity — Pi ignores these fields, runs with its full native toolset, and
+warns at `start()` that they are unenforced. `permission_mode` and
+`system_prompt_file` are unenforced too (see below); `plugins` **is** honored for
+its skills half (each resolved skills dir → a `--skill <dir>` arg).
+
+## Permissions
+
+Pi headless print mode auto-runs tools; it exposes only project-file trust
+(`--approve` / `--no-approve`), not a tool-approval mode. Coder Eval always
+passes `--no-approve` so the run never blocks. **`permission_mode` is therefore
+not enforced** — the sandbox driver is the isolation boundary (the same posture
+as Codex and Antigravity). `start()` logs a warning naming `permission_mode`
+(and any other unenforced field it saw) so a task never silently believes it was
+constrained.
+
+## Multi-turn and simulation
+
+A standard task reaches its solution inside a **single** `communicate()` call —
+Pi runs its own multi-step agent loop there (verified: a write+read task ran
+three internal `turn_start` steps, all tools executed). A simulation / dialog
+task calls `communicate()` once per user turn and relies on the agent remembering
+prior turns, so `PiAgent` reuses a per-agent `--session-dir` + stable
+`--session-id` on **every** invocation: the first call creates the session, later
+calls resume it. The session tempdir lives outside the sandbox working dir and
+the staged reference dir, so it never pollutes graded files or trips
+reference-integrity, and it is removed in `stop()`. `pi_session_id` is recorded
+per task under `environment_info`.
+
+## Telemetry
+
+Mapping from the CLI's event vocabulary onto `TurnRecord`:
+
+| Pi event | Becomes |
+|---|---|
+| `turn_start` | `TurnStartEvent` (one inner turn; the unit `max_turns` counts) |
+| `message_update` (`text_delta`) | `TextChunkEvent` + `agent_output` |
+| `tool_execution_start` | `ToolStartEvent` |
+| `tool_execution_end` | `ToolEndEvent` |
+| `turn_end` | `TurnEndEvent` + per-turn tokens/cost, one `AssistantMessage` |
+| `agent_settled` (or stdout EOF) | the single terminal `AgentEndEvent` |
+
+Token buckets come from `turn_end.message.usage`, read **once per turn** and
+**summed** across turns (per-generation, not cumulative). Pi's `input` is already
+the fresh input slice, so it maps straight to `uncached_input_tokens`; `cacheRead`
+and `cacheWrite` map to the cache buckets. `reasoning` tokens fold into
+`output_tokens` (they bill at the output rate) while remaining visible as
+`reasoning_tokens` per message. This keeps the reconciliation invariant exact:
+summing the four buckets across `TurnRecord.messages` equals `token_usage`.
+
+Real per-call cost rides on `turn_end.message.usage.cost.total` and lands on
+`token_usage.total_cost_usd`, so runs are costed from the provider's own
+accounting rather than the static rate card. No `pricing.py` entry is needed for
+a Pi model; the rate card (`calculate_cost` over the captured buckets) is only a
+fallback for a stream that omits cost entirely. A genuinely free model still
+resolves to $0.
+
+Tool names and argument keys are normalized to the canonical (Claude) vocabulary
+on capture — `write` → `Write`, `read` → `Read`, `bash` → `Bash`, and a
+`Read`/`Write`/`Edit` call's `path` argument → `file_path` — so one
+`command_executed` criterion scores identically whether the run used Claude,
+Codex, OpenCode or Pi. An unmapped tool keeps its own name.
+
+### Auto-retry
+
+Pi retries a transient/provider error **internally**: it emits another
+`agent_start` / `turn_*` / `agent_end` cycle in the same invocation, marking the
+first `agent_end` with `willRetry: true`. `PiAgent` treats `agent_end` as
+non-terminal and finalizes exactly once at `agent_settled` (or stdout EOF), so a
+retried invocation still produces a single `AgentEndEvent` with the cycles' usage
+merged. The internal retry is bounded by `turn_timeout` / `task_timeout`.
+
+### Drift is crashed, not scored
+
+A turn whose CLI exits cleanly but which captured **no recognized events** (an
+upgrade renamed the vocabulary) is failed rather than reported as a clean empty
+success — the error names the unrecognized event types it saw. Intentional cuts
+(`should_stop`, `max_turns`) are exempt.
+
+> **Zero-usage turn.** A provider that reports no usage yields an all-zero
+> `token_usage`. Pi does **not** hard-fail such a turn (its multi-provider surface
+> makes a blanket fail brittle); the turn is scored and a warning is logged. If
+> you need strict token accounting, prefer a provider whose stream reports usage.
+
+## Running in Docker
+
+Pi **is supported under `--driver docker`.** The pinned Pi CLI is baked into
+`docker/Dockerfile` (`ARG PI_VERSION`, alongside the claude-code CLI), and
+`OPENROUTER_API_KEY` is forwarded into the container by the docker driver's
+default `env_passthrough` allowlist — so `--driver docker --type pi` runs
+end-to-end with no per-task `env_passthrough_extra`:
+
+```bash
+export OPENROUTER_API_KEY="sk-or-..."
+uv run coder-eval run tasks/pi_smoke_test.yaml --driver docker
+```
+
+**Docker is the recommended driver for untrusted / adversarial Pi runs.** Pi's
+`permission_mode` is unenforced — headless print mode auto-runs tools — so the
+**container is the confinement boundary**. Under `tempdir` there is no such
+boundary; the agent runs with the host's own permissions. Prefer `--driver
+docker` whenever the task prompt or workspace is not fully trusted.
+
+## Known limitations
+
+- **`permission_mode` is not enforced.** Pi headless print mode auto-runs tools;
+  the sandbox driver is the isolation boundary (same as Codex/Antigravity).
+- **`plugins` skills are injected via `--skill`.** Each `type: local` plugin root
+  is resolved to its skills dir (`<root>/skills`, holding `<name>/SKILL.md`) and
+  passed to the CLI as a `--skill <dir>` argument — the same `_plugin_skill_dirs`
+  resolver OpenCode uses — and recorded as `pi_skill_paths` in `environment_info`.
+  Pi therefore **can run activation suites**: `skill_triggered` detects Pi's
+  engagement agent-agnostically (the agent `read`s the full `SKILL.md`, a
+  `read`→`Read` call whose `path` matches `skills/<name>/`). Use the **plugin-root
+  shape** (`<path>/skills/<name>/SKILL.md`) for activation suites: a bare skills dir
+  still *loads* (the resolver's fallback passes it as `--skill <dir>`), but the read
+  path then lacks the `skills/<name>/` segment `skill_triggered` matches on, so the
+  suite scores recall 0 even though the skill ran — see
+  [Harness Parity § plugin-path depth](HARNESS_PARITY.md). A plugin's non-skill
+  assets (agents/hooks/commands/MCP) are not wired.
+- **`system_prompt_file` is not read.** Use `system_prompt` (inline) instead — it
+  is enforced via `--append-system-prompt`. `system_prompt_file` is warned about
+  at `start()` (matching Codex/Antigravity, which also do not read the file form).
+- **`max_turns` counts Pi's native agent-loop turns.** One `turn_start` = one
+  agent-loop step; `max_turns: N` allows N complete turns, then the run finalizes
+  cleanly as `max_turns_exhausted`. See
+  [Run-Limit Parity](HARNESS_PARITY.md) before holding `max_turns` constant across
+  harnesses.
+- **No sub-agent attribution.** Pi's CLI stream does not expose nested agent
+  generations, so per-sub-agent token grouping (available for Claude and Codex) is
+  not derivable.
+- **Cooperative stop is at event granularity.** `should_stop` is polled between
+  events and honored by terminating the CLI, so `stop_early` works, but the cut
+  lands on an event boundary rather than mid-tool. Pi streams incrementally, so
+  this genuinely cuts spend mid-run.
+
+## References
+
+- [Pi](https://pi.dev/)
+- [Extending Coder Eval](../EXTENDING.md) — the agent plugin SPI
+- [Task Definition Guide](../TASK_DEFINITION_GUIDE.md)
diff --git a/docs/comparison.md b/docs/comparison.md
index 745e7109..c3f624d2 100644
--- a/docs/comparison.md
+++ b/docs/comparison.md
@@ -9,8 +9,8 @@ description: >-
 # How Coder Eval compares
 
 **Coder Eval** is an agent-agnostic framework for evaluating AI coding agents and
-their skills. It runs a real agent (Claude Code, OpenAI Codex, Antigravity/Gemini, or
-OpenCode — one `agent.type` field apart) in a sandbox against declarative YAML
+their skills. It runs a real agent (Claude Code, OpenAI Codex, Antigravity/Gemini,
+OpenCode, or Pi — one `agent.type` field apart) in a sandbox against declarative YAML
 tasks and scores the files and commands it produces on a weighted 0.0–1.0 scale,
 with cost/token telemetry, an A/B experiment layer, skill-activation checks, and CI
 pass/fail gates.
@@ -25,7 +25,7 @@ in its own documentation; see [Sources](#sources).
 | --- | --- | --- | --- | --- | --- | --- |
 | **What it grades** | Files + commands the agent produced | Whether a patch passes the repo's tests | Skill value on a fixed task set | Agent task success in sandboxes | Model text output | Whatever you wire up |
 | **Task source** | Your own (YAML) | Fixed benchmark (+ collection script) | Fixed (87 tasks / 8 domains) | Your own (framework) + Terminal-Bench 2.0 | Your own (YAML/JSON) + registry | Manual |
-| **Runs a real agent + tools** | ✅ Claude Code, Codex, Antigravity (Gemini), OpenCode | Runs your patch/scaffold | ✅ multi-harness | ✅ Claude Code, OpenHands, Codex | ❌ grades model output | ❌ |
+| **Runs a real agent + tools** | ✅ Claude Code, Codex, Antigravity (Gemini), OpenCode, Pi | Runs your patch/scaffold | ✅ multi-harness | ✅ Claude Code, OpenHands, Codex | ❌ grades model output | ❌ |
 | **Sandboxed & reproducible** | ✅ tempdir / Docker | ✅ Docker | ✅ deterministic verifiers | ✅ Docker + cloud (Daytona/Modal) | — (grades text) | ❌ |
 | **Scoring** | Weighted 0.0–1.0 + thresholds | Pass/fail (tests) | Pass/fail (verifiers) | Task-level | Match / model-graded | ❌ |
 | **A/B experiments (model / tool / prompt)** | ✅ built-in | ❌ | Skills on/off only | — | Compare model versions | ❌ |
@@ -123,7 +123,7 @@ focus on tasks and criteria rather than harness infrastructure.
 
 - Benchmarking coding agents on your own domain tasks instead of a fixed leaderboard.
 - Evaluating how well agents use a CLI or a skill (Claude Code skills included).
-- A/B-testing agents, models, tools, or prompts on the same tasks (Claude Code vs. Codex vs. Antigravity/Gemini vs. OpenCode).
+- A/B-testing agents, models, tools, or prompts on the same tasks (Claude Code vs. Codex vs. Antigravity/Gemini vs. OpenCode vs. Pi).
 - Detecting skill regressions when a model or prompt changes.
 - Gating CI on coding-agent quality.
 - Producing reproducible, sandboxed runs scored per file and per command, with a dashboard for review.
diff --git a/docs/index.md b/docs/index.md
index 7db93bb1..d3fc34ae 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,7 +4,7 @@ description: >-
   Coder Eval is Playwright for coding agents: an open-source, agent-agnostic
   framework to evaluate, benchmark, and A/B-test AI coding agents and their skills
   in a sandbox — declarative YAML tasks, weighted scoring, cost/token telemetry, and
-  CI gates for Claude Code, Codex, Antigravity (Gemini), and OpenCode.
+  CI gates for Claude Code, Codex, Antigravity (Gemini), OpenCode, and Pi.
 ---
 
 # Evaluate AI coding agents and their skills — Coder Eval
@@ -13,7 +13,7 @@ description: >-
 open-source, **agent-agnostic** framework for **evaluating AI coding agents and their
 skills** — built for benchmark authors, CLI builders, and skill builders — with
 sandboxing, reproducibility, and data-driven analysis. It runs a real agent —
-**Claude Code**, **OpenAI Codex**, **Google Antigravity (Gemini)**, or **OpenCode** —
+**Claude Code**, **OpenAI Codex**, **Google Antigravity (Gemini)**, **OpenCode**, or **Pi** —
 against declarative YAML tasks in a sandbox. Changing harness is one field
 (`agent.type`); the tasks, criteria, scoring, telemetry, and reports stay the same.
 It is **not a fixed leaderboard**: you bring the tasks and you bring the scoring.
@@ -33,14 +33,14 @@ coding-agent quality?"* — this is the framework for that.
 - **Sandboxed execution** in isolated environments with resource limits
 - **Weighted, continuous scoring** (0.0–1.0) with fractional credit and thresholds
 - **Many criterion types** — from file checks to code similarity and LLM-graded rubrics
-- **Agent-agnostic by design** — Claude Code, OpenAI Codex, Antigravity (Gemini), and OpenCode today; add your own harness through the plugin SPI
+- **Agent-agnostic by design** — Claude Code, OpenAI Codex, Antigravity (Gemini), OpenCode, and Pi today; add your own harness through the plugin SPI
 - **Experiment layer** — A/B agent configs (models, tools, prompts) side-by-side
 - **Full telemetry** — every tool call, token counts, and cost, with real-time streaming
 
 ## Use cases
 
 - **Benchmark coding agents** — score an agent across a suite of tasks with weighted pass/fail thresholds
-- **Compare models & configs** — A/B-test Claude Code vs. Codex vs. Gemini vs. OpenCode, model vs. model, tool-on vs. tool-off, prompt vs. prompt
+- **Compare models & configs** — A/B-test Claude Code vs. Codex vs. Gemini vs. OpenCode vs. Pi, model vs. model, tool-on vs. tool-off, prompt vs. prompt
 - **Test whether a skill triggers** — verify an agent actually engages a target
   skill (`skill_triggered`) and score skill-driven suites (SkillsBench-style), on
   whichever harness your users run
@@ -86,6 +86,7 @@ New here? Start with **[Tutorial 01 — Your First Evaluation](tutorials/01-firs
 | [Codex](agents/CODEX.md) | Running the OpenAI Codex agent |
 | [Antigravity (Gemini)](agents/ANTIGRAVITY.md) | Running the Google Antigravity / Gemini agent |
 | [OpenCode](agents/OPENCODE.md) | Running the OpenCode agent on open-weight models |
+| [Pi](agents/PI.md) | Running the Pi agent on open-weight models |
 | [Run-Limit Parity](agents/HARNESS_PARITY.md) | What each run_limits field means on every harness |
 | [A/B Experiments](AB_EXPERIMENTS.md) | Compare models / tools / prompts across the same tasks |
 | [Bring Your Own Dataset](DATASETS.md) | Fan a single task out over a dataset |
diff --git a/docs/llms.txt b/docs/llms.txt
index baec1eac..9a8adaa6 100644
--- a/docs/llms.txt
+++ b/docs/llms.txt
@@ -4,7 +4,7 @@
 > for evaluating, benchmarking, and A/B-testing AI coding agents and their skills
 > (including Claude Code skills) in a sandbox. It uses declarative YAML tasks with
 > weighted, continuous scoring (0.0–1.0), runs real agents (Claude Code, OpenAI
-> Codex, Google Antigravity/Gemini, OpenCode) with full tool use — switching harness
+> Codex, Google Antigravity/Gemini, OpenCode, Pi) with full tool use — switching harness
 > is one field, `agent.type` — captures per-tool cost/token telemetry, and provides
 > CI-ready pass/fail gates. It is not a fixed benchmark or leaderboard: you bring the
 > tasks and the scoring, and it can verify whether a skill actually triggers.
@@ -31,6 +31,7 @@ and A/B plumbing.
 - [Codex](https://coder-eval.com/docs/agents/codex): Running the OpenAI Codex agent
 - [Antigravity (Gemini)](https://coder-eval.com/docs/agents/antigravity): Running the Google Antigravity / Gemini agent
 - [OpenCode](https://coder-eval.com/docs/agents/opencode): Running the OpenCode agent on open-weight models
+- [Pi](https://coder-eval.com/docs/agents/pi): Running the Pi agent on open-weight models
 - [Run-Limit Parity](https://coder-eval.com/docs/agents/harness-parity): What each run_limits field means on every harness
 - [A/B Experiments](https://coder-eval.com/docs/ab-experiments): Compare models / tools / prompts across the same tasks
 - [Bring Your Own Dataset](https://coder-eval.com/docs/datasets): Fan a single task out over a dataset
diff --git a/docs/tutorials/06-use-docker-isolation.md b/docs/tutorials/06-use-docker-isolation.md
index 2e6b4d25..7e3631d1 100644
--- a/docs/tutorials/06-use-docker-isolation.md
+++ b/docs/tutorials/06-use-docker-isolation.md
@@ -19,8 +19,8 @@ For the complete reference, see [Docker Isolation](../DOCKER_ISOLATION.md).
 - **Isolation** — agent-generated code can't touch files or the network outside
   the sandbox.
 - **Reproducibility** — the image bakes in Python 3.13, Node 22 LTS, the Claude
-  CLI, `uv`, and the matching `coder_eval` version, so results don't drift with
-  host upgrades.
+  and Pi CLIs, the codex/antigravity/litellm agent SDKs, `uv`, and the matching
+  `coder_eval` version, so results don't drift with host upgrades.
 
 Aggregation (scores, reports, evalboard) still happens on the host — each
 container is a sealed "run one task → emit one `task.json`" worker.
diff --git a/evalboard/app/_components/__tests__/harness-badge.test.tsx b/evalboard/app/_components/__tests__/harness-badge.test.tsx
index 32b384c8..f4953575 100644
--- a/evalboard/app/_components/__tests__/harness-badge.test.tsx
+++ b/evalboard/app/_components/__tests__/harness-badge.test.tsx
@@ -18,6 +18,12 @@ describe("harnessShortLabel", () => {
         expect(harnessShortLabel("delegate-sdk")).toBe("Delegate");
     });
 
+    test("the Pi harness reads as Pi", () => {
+        // `agent.type` is "pi" (AgentKind.PI) in run.json; the badge shows the
+        // Pi mark and the short label "Pi".
+        expect(harnessShortLabel("pi")).toBe("Pi");
+    });
+
     test("an unknown harness falls back to its id rather than a wrong name", () => {
         expect(harnessShortLabel("some-new-agent")).toBe("some-new-agent");
     });
@@ -29,6 +35,11 @@ describe("HarnessBadge", () => {
         expect(screen.getByAltText("Delegate · UiPath")).toBeInTheDocument();
     });
 
+    test("renders the Pi vendor mark with pi.dev in the alt text", () => {
+        render(<HarnessBadge harness="pi" />);
+        expect(screen.getByAltText("Pi · pi.dev")).toBeInTheDocument();
+    });
+
     test("renders the id as text when there is no logo for it", () => {
         // Better a raw id than another vendor's mark on someone else's run.
         render(<HarnessBadge harness="some-new-agent" />);
diff --git a/evalboard/app/_components/harness-badge.tsx b/evalboard/app/_components/harness-badge.tsx
index 02a7bbaa..4c788e32 100644
--- a/evalboard/app/_components/harness-badge.tsx
+++ b/evalboard/app/_components/harness-badge.tsx
@@ -17,6 +17,7 @@ const HARNESS_LOGO: Record<string, { src: string; label: string; short: string }
         short: "Claude Code",
     },
     codex: { src: "/harness/codex.png", label: "Codex · OpenAI", short: "Codex" },
+    pi: { src: "/harness/pi.png", label: "Pi · pi.dev", short: "Pi" },
     antigravity: {
         src: "/harness/antigravity.png",
         label: "Antigravity · Google Gemini",
diff --git a/evalboard/app/runs/[id]/[...task]/_sections.tsx b/evalboard/app/runs/[id]/[...task]/_sections.tsx
index 617da165..f52ff560 100644
--- a/evalboard/app/runs/[id]/[...task]/_sections.tsx
+++ b/evalboard/app/runs/[id]/[...task]/_sections.tsx
@@ -279,7 +279,7 @@ const MSG_GRID =
 // figure, not the SDK's cumulative per-turn cost). Token-column copy is shared
 // via TOKEN_COLUMN_HELP so the timeline and the run grid stay consistent.
 const MESSAGE_COST_HELP =
-    "Per-message cost: this message's recorded tokens priced at list rates — the cost of this single API call. The SDK reports only a cumulative per-turn figure, so these need not sum exactly to the task's total cost (the authoritative SDK number) shown above. Blank when the model is unpriced or no per-message tokens were recorded.";
+    "Per-message cost: this message's recorded tokens priced at list rates — the cost of this single API call. The SDK reports only a cumulative per-turn figure, so these need not sum exactly to the task's total cost (the authoritative SDK number) shown above. For a harness that reports a real per-turn cost on an unpriced model (e.g. Pi on an open-weight model), the turn's real cost is instead apportioned across its rows by token share, so those rows DO sum to the turn total. Blank only when neither a list price nor a real turn cost is available, or no per-message tokens were recorded.";
 
 function messageKind(blockTypes: MessageEvent["blockTypes"]): string {
     const set = new Set(blockTypes);
diff --git a/evalboard/lib/__tests__/parseMessages.test.ts b/evalboard/lib/__tests__/parseMessages.test.ts
index ba21f4f7..e1e034bd 100644
--- a/evalboard/lib/__tests__/parseMessages.test.ts
+++ b/evalboard/lib/__tests__/parseMessages.test.ts
@@ -861,3 +861,90 @@ describe("parseMessages — reconciliation entry", () => {
         expect(recon.costUsd).toBeNull();
     });
 });
+
+describe("parseMessages — open-weight cost apportionment", () => {
+    // An assistant message carrying token buckets + a model, on a turn that
+    // reports a real per-turn total_cost_usd. Mirrors the Pi harness shape:
+    // real stream cost at the turn, models absent from the rate card.
+    function tokMsg(
+        model: string,
+        input: number,
+        output: number,
+        // Distinct started_at + message_id so separate generations are NOT
+        // collapsed into one emission row by the same-emission heuristic.
+        startSec = 0,
+        messageId?: string,
+    ) {
+        const ss = String(startSec).padStart(2, "0");
+        return {
+            role: "assistant",
+            started_at: `2026-01-01T00:00:${ss}.000Z`,
+            completed_at: `2026-01-01T00:00:${ss}.500Z`,
+            generation_duration_ms: 500,
+            content_blocks: [{ block_type: "text" as const, text: "x" }],
+            input_tokens: input,
+            output_tokens: output,
+            model,
+            message_id: messageId ?? `m-${startSec}`,
+        };
+    }
+
+    test("unpriced model + real turn cost: rows are filled and sum EXACTLY to the total", () => {
+        const turns: TurnEntry[] = [
+            {
+                model_used: "openrouter/unpriced-xyz",
+                token_usage: { total_cost_usd: 0.009 },
+                messages: [
+                    tokMsg("openrouter/unpriced-xyz", 300, 100, 0), // weight 400
+                    tokMsg("openrouter/unpriced-xyz", 100, 0, 2), //   weight 100
+                ],
+            },
+        ];
+        const rows = parseMessages(turns);
+        expect(rows).toHaveLength(2);
+        for (const r of rows) expect(r.costUsd).not.toBeNull();
+        const sum = rows.reduce((a, r) => a + (r.costUsd ?? 0), 0);
+        expect(sum).toBeCloseTo(0.009, 10); // exact to the cent and far beyond
+        // Apportioned by token share: first row 400/500, second 100/500.
+        expect(rows[0].costUsd).toBeCloseTo(0.009 * (400 / 500), 10);
+    });
+
+    test("provider_call_costs present (LiteLLM/OpenCode): NOT apportioned — cost lives in the ProviderCall table", () => {
+        const turns: TurnEntry[] = [
+            {
+                model_used: "openrouter/unpriced-xyz",
+                token_usage: { total_cost_usd: 0.009 },
+                // The open-weight actual-cost join already booked this turn's real
+                // cost per-call; apportioning the turn total onto message rows too
+                // would surface the same money twice.
+                provider_call_costs: [{ cost_usd: 0.009, input_tokens: 300, output_tokens: 100 }],
+                messages: [tokMsg("openrouter/unpriced-xyz", 300, 100, 0)],
+            },
+        ];
+        // Unpriced model + a per-call audit → the row stays blank, NOT apportioned.
+        expect(parseMessages(turns)[0].costUsd).toBeNull();
+    });
+
+    test("unpriced model + NO turn cost: rows stay blank (—), not a misleading $0", () => {
+        const turns: TurnEntry[] = [
+            {
+                model_used: "openrouter/unpriced-xyz",
+                messages: [tokMsg("openrouter/unpriced-xyz", 300, 100)],
+            },
+        ];
+        expect(parseMessages(turns)[0].costUsd).toBeNull();
+    });
+
+    test("priced model is left on the rate card (apportionment never overrides)", () => {
+        const turns: TurnEntry[] = [
+            {
+                model_used: "gpt-5.6-terra",
+                token_usage: { total_cost_usd: 999 }, // absurd; must NOT leak into rows
+                messages: [tokMsg("gpt-5.6-terra", 1_000_000, 1_000_000)],
+            },
+        ];
+        const r = parseMessages(turns)[0];
+        // Rate card: 1M input @ $2 + 1M output @ $12 = $14, not the bogus 999.
+        expect(r.costUsd).toBeCloseTo(14, 6);
+    });
+});
diff --git a/evalboard/lib/runs.ts b/evalboard/lib/runs.ts
index 010a38b2..b78038bc 100644
--- a/evalboard/lib/runs.ts
+++ b/evalboard/lib/runs.ts
@@ -1609,6 +1609,9 @@ export function parseMessages(turns: TurnEntry[]): MessageEvent[] {
     const out: MessageEvent[] = [];
     let order = 0;
     for (const turn of turns) {
+        // Index in `out` where this turn's rows begin, so the open-weight
+        // cost-apportionment pass below can address exactly this turn's rows.
+        const turnStart = out.length;
         // Resolve tool_use_id -> CommandEntry per iteration (the id is locally
         // unique). Used to pull execution time + result preview onto tool_use
         // blocks.
@@ -1998,6 +2001,59 @@ export function parseMessages(turns: TurnEntry[]): MessageEvent[] {
                 note: typeof msg.note === "string" ? msg.note : null,
             });
         }
+
+        // Open-weight cost apportionment. A CLI harness that owns its provider
+        // (Pi and friends) reports a REAL per-turn `total_cost_usd` from its
+        // stream but runs models absent from the rate card, so `messageCostUsd`
+        // priced every row null and the Cost column dashes out even though the
+        // turn has a real bill. When the rate card priced NOTHING for this turn
+        // yet the backend reported a real total, distribute that total across
+        // this turn's rows in proportion to their tokens. The column then shows
+        // numbers that sum EXACTLY to the turn total (last row absorbs the
+        // rounding residual), and so to the task total. Priced harnesses
+        // (Claude / Codex / Bedrock) already have per-row figures and are left
+        // untouched — this only fills the gap, never overrides. Display-only:
+        // the authoritative task total still reads the backend aggregate, not a
+        // sum of these costUsd, so there is no double-count.
+        // EXCLUDED: turns carrying a `provider_call_costs` audit (the LiteLLM route
+        // + OpenCode's open-weight join) book the real per-call cost in the separate
+        // ProviderCall table by design. Apportioning the turn total onto message
+        // rows too would surface the SAME money twice — once per-row here, once
+        // itemised there — reversing the documented "actual cost is no longer
+        // distributed onto transcript messages" decision for every historical
+        // LiteLLM/OpenCode run. Only a stream-native total with NO per-call audit
+        // (Pi and friends) is apportioned.
+        const turnRows = out.slice(turnStart);
+        const realCost = turn.token_usage?.total_cost_usd;
+        const anyPriced = turnRows.some((r) => r.costUsd != null);
+        const hasPerCallActuals = (turn.provider_call_costs?.length ?? 0) > 0;
+        if (
+            !anyPriced &&
+            !hasPerCallActuals &&
+            typeof realCost === "number" &&
+            realCost > 0 &&
+            turnRows.length > 0
+        ) {
+            const weight = (r: MessageEvent) =>
+                (r.inputTokens ?? 0) +
+                (r.outputTokens ?? 0) +
+                (r.cacheWriteTokens ?? 0) +
+                (r.cacheReadTokens ?? 0);
+            const totalWeight = turnRows.reduce((a, r) => a + weight(r), 0);
+            if (totalWeight > 0) {
+                let allocated = 0;
+                turnRows.forEach((r, i) => {
+                    if (i === turnRows.length - 1) {
+                        // Last row takes the residual so the column sums exactly.
+                        r.costUsd = realCost - allocated;
+                    } else {
+                        const share = (realCost * weight(r)) / totalWeight;
+                        r.costUsd = share;
+                        allocated += share;
+                    }
+                });
+            }
+        }
     }
     return out;
 }
diff --git a/evalboard/public/harness/pi.png b/evalboard/public/harness/pi.png
new file mode 100644
index 00000000..fe35b182
Binary files /dev/null and b/evalboard/public/harness/pi.png differ
diff --git a/experiments/default.yaml b/experiments/default.yaml
index ebf627b5..b9469a4b 100644
--- a/experiments/default.yaml
+++ b/experiments/default.yaml
@@ -39,7 +39,8 @@ defaults:
     # count_cached_input: false
 
   agent:
-    # Agent type (currently only "claude-code" is supported)
+    # Agent type. Built-in kinds: claude-code, codex, antigravity, opencode, pi,
+    # none (plus any plugin-registered kind). claude-code is the run-wide default.
     type: claude-code
 
     # Permission mode for agent actions:
diff --git a/mkdocs.yml b/mkdocs.yml
index ebd33b6d..d01681d1 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -2,7 +2,7 @@ site_name: Coder Eval
 site_description: >-
   Evaluate and benchmark AI coding agents and their skills — a sandboxed,
   agent-agnostic framework with declarative YAML eval suites for Claude Code,
-  Codex, Antigravity (Gemini) and OpenCode, A/B experiments, weighted scoring,
+  Codex, Antigravity (Gemini), OpenCode and Pi, A/B experiments, weighted scoring,
   and CI gates.
 site_url: https://coder-eval.com/docs/
 repo_url: https://github.com/UiPath/coder_eval
@@ -85,6 +85,7 @@ extra:
     agents/CODEX.md: "Running the OpenAI Codex agent"
     agents/ANTIGRAVITY.md: "Running the Google Antigravity / Gemini agent"
     agents/OPENCODE.md: "Running the OpenCode agent on open-weight models"
+    agents/PI.md: "Running the Pi agent on open-weight models"
     agents/HARNESS_PARITY.md: "What each run_limits field means on every harness"
     AB_EXPERIMENTS.md: "Compare models / tools / prompts across the same tasks"
     DATASETS.md: "Fan a single task out over a dataset"
@@ -115,6 +116,7 @@ nav:
       - Codex: agents/CODEX.md
       - Antigravity (Gemini): agents/ANTIGRAVITY.md
       - OpenCode: agents/OPENCODE.md
+      - Pi: agents/PI.md
       - Run-Limit Parity: agents/HARNESS_PARITY.md
   - Advanced:
       - A/B Experiments: AB_EXPERIMENTS.md
diff --git a/pyproject.toml b/pyproject.toml
index ac13f968..dfa53aed 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,7 +1,7 @@
 [project]
 name = "coder-eval"
 version = "0.11.7"
-description = "Evaluate, benchmark, and A/B-test AI coding agents (Claude Code, Codex, Gemini/Antigravity, OpenCode) with sandboxed, reproducible YAML task suites."
+description = "Evaluate, benchmark, and A/B-test AI coding agents (Claude Code, Codex, Gemini/Antigravity, OpenCode, Pi) with sandboxed, reproducible YAML task suites."
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.13"
@@ -9,7 +9,7 @@ authors = [{ name = "UiPath", email = "coder-eval@uipath.com" }]
 keywords = [
     "ai", "llm", "agent", "coding-agent", "evaluation", "eval", "evals",
     "benchmark", "swe-bench", "claude", "claude-code", "codex", "anthropic",
-    "gemini", "antigravity", "opencode", "sandbox", "code-generation", "agent-evaluation",
+    "gemini", "antigravity", "opencode", "pi", "sandbox", "code-generation", "agent-evaluation",
     "llm-evaluation", "llm-eval", "ai-evaluation", "skills-evaluation",
     "claude-skills", "claude-code-skills", "agent-skills", "skillsbench",
     "agent-testing", "llmops",
@@ -147,6 +147,19 @@ antigravity = [
 # fail at start() with a clear hint pointing back here.
 # See docs/agents/OPENCODE.md.
 opencode = []
+# Optional extra that enables Pi agent support.
+#
+# Deliberately EMPTY, exactly like `opencode` above. Pi ships as a Node CLI
+# (`npm install -g @earendil-works/pi-coding-agent`), and PiAgent drives that
+# binary over a subprocess reading `pi -p --mode json` — it imports no
+# third-party Python package. The extra exists to keep the opt-in surface
+# uniform across harnesses and to give the `npm install` prerequisite a single
+# home in the packaging metadata. On `--driver docker` the pinned Pi CLI is baked
+# into docker/Dockerfile (like claude-code), so no host install is needed there;
+# on `tempdir`/host the `npm install` prerequisite above still applies. Without
+# the CLI on PATH the framework still installs and runs; Pi tasks fail at start()
+# with a clear hint pointing here. See docs/agents/PI.md.
+pi = []
 
 [project.scripts]
 coder-eval = "coder_eval.cli:app"
diff --git a/src/coder_eval/agents/__init__.py b/src/coder_eval/agents/__init__.py
index 0bbf0dde..c56ecf39 100644
--- a/src/coder_eval/agents/__init__.py
+++ b/src/coder_eval/agents/__init__.py
@@ -6,12 +6,13 @@
 from coder_eval.agents.codex_agent import CodexAgent
 from coder_eval.agents.noop_agent import NoOpAgent
 from coder_eval.agents.opencode_agent import OpenCodeAgent
+from coder_eval.agents.pi_agent import PiAgent
 from coder_eval.agents.registry import AgentRegistry, create_agent
 from coder_eval.models import AgentKind
 
 
 def register_builtins(registry: type[AgentRegistry]) -> None:
-    """Register the built-in agents (Claude/Codex/Antigravity/OpenCode/NoOp) onto ``registry``.
+    """Register the built-in agents (Claude/Codex/Antigravity/OpenCode/Pi/NoOp) onto ``registry``.
 
     This is the target of coder-eval's own ``coder_eval.plugins`` entry point, so
     the built-in agents travel the identical discovery path as any third-party
@@ -21,7 +22,7 @@ def register_builtins(registry: type[AgentRegistry]) -> None:
     """
     # Reference the imported classes so the registration side effect is explicit
     # and a future refactor that drops the top-level imports fails loudly here.
-    _ = (ClaudeCodeAgent, CodexAgent, AntigravityAgent, OpenCodeAgent, NoOpAgent)
+    _ = (ClaudeCodeAgent, CodexAgent, AntigravityAgent, OpenCodeAgent, PiAgent, NoOpAgent)
     # Rot-protection: the decorators fire on import, but assert the built-ins are
     # actually registered so a future lazy-import refactor (which would leave the
     # import-cached modules' decorators un-run) fails loudly instead of silently
@@ -31,6 +32,7 @@ def register_builtins(registry: type[AgentRegistry]) -> None:
         AgentKind.CODEX,
         AgentKind.ANTIGRAVITY,
         AgentKind.OPENCODE,
+        AgentKind.PI,
         AgentKind.NONE,
     ):
         if registry.get(kind) is None:
@@ -44,6 +46,7 @@ def register_builtins(registry: type[AgentRegistry]) -> None:
     "CodexAgent",
     "NoOpAgent",
     "OpenCodeAgent",
+    "PiAgent",
     "create_agent",
     "register_builtins",
 ]
diff --git a/src/coder_eval/agents/_skills.py b/src/coder_eval/agents/_skills.py
new file mode 100644
index 00000000..60bdb11b
--- /dev/null
+++ b/src/coder_eval/agents/_skills.py
@@ -0,0 +1,113 @@
+"""Shared ``agent.plugins`` -> skills-directory resolver for CLI harnesses.
+
+Both OpenCode (maps each skills dir into ``skills.paths`` in
+``OPENCODE_CONFIG_CONTENT``) and Pi (passes each as a ``--skill <dir>`` argument)
+honor only the *skills* half of a Claude plugin. This module holds that one
+resolver so neither agent has to reach into the other's private module for it
+(the alternative — ``pi_agent`` importing ``opencode_agent._plugin_skill_dirs`` —
+coupled the two harnesses through an implementation-private symbol).
+
+Only the skills half of a plugin is honored. A plugin's agents, hooks, commands
+and MCP servers have no CLI equivalent and are dropped by both harnesses.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from coder_eval.utils import expand_env_vars
+
+
+logger = logging.getLogger(__name__)
+
+_PLUGIN_MANIFEST_RELPATH = (".claude-plugin", "plugin.json")
+_DEFAULT_PLUGIN_SKILLS_SUBDIR = "skills"
+_SKILL_FILE = "SKILL.md"
+
+
+def _manifest_skill_dirs(root: Path) -> list[Path]:
+    """Skill directories a Claude-plugin root declares, in manifest order.
+
+    Reads the ``skills`` field of ``<root>/.claude-plugin/plugin.json`` (a string
+    or a list of strings, each relative to the root) and falls back to the
+    convention default ``<root>/skills`` when the manifest is absent, unreadable,
+    or declares none. Honoring the manifest rather than hardcoding ``skills/``
+    keeps a plugin that relocates its skills working on both harnesses.
+    """
+    manifest = root.joinpath(*_PLUGIN_MANIFEST_RELPATH)
+    declared: list[str] = []
+    if manifest.is_file():
+        try:
+            data: Any = json.loads(manifest.read_text(encoding="utf-8"))
+        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
+            data = None
+        if isinstance(data, dict):
+            value = data.get("skills")
+            if isinstance(value, str):
+                declared = [value]
+            elif isinstance(value, list):
+                declared = [entry for entry in value if isinstance(entry, str)]
+    if not declared:
+        declared = [_DEFAULT_PLUGIN_SKILLS_SUBDIR]
+    return [(root / relative).resolve() for relative in declared]
+
+
+def _plugin_skill_dirs(
+    plugins: Sequence[Mapping[str, Any]] | None,
+    log: logging.Logger | logging.LoggerAdapter[Any] = logger,
+    harness: str = "opencode",
+) -> list[str]:
+    """Resolve ``plugins:`` entries to skill-directory paths for a CLI harness.
+
+    Returns the skills-parent directories (each holding ``<name>/SKILL.md``) that
+    a ``type: local`` plugin root declares. Shared by OpenCode (``skills.paths``
+    in ``OPENCODE_CONFIG_CONTENT``) and Pi (a ``--skill <dir>`` argument each);
+    ``harness`` only labels the diagnostics. Every way this can come up empty is
+    logged rather than passed over: a plugin whose skills never reach the agent
+    still *looks* like a normal run, which is precisely the failure this closes.
+    """
+    resolved: list[str] = []
+    for plugin in plugins or []:
+        if not isinstance(plugin, Mapping) or plugin.get("type") != "local":
+            log.warning(f"{harness}: ignoring non-local plugin entry %r — only `type: local` maps to skills.", plugin)
+            continue
+        path_str = plugin.get("path")
+        if not path_str:
+            continue
+        expanded = expand_env_vars(str(path_str))
+        root = Path(expanded).resolve()
+        if not root.is_dir():
+            hint = "env var likely unset" if "$" in expanded else "path does not exist"
+            log.warning(
+                f"{harness}: plugin skills path did not resolve: %r -> %r (%s); no skills injected from it",
+                path_str,
+                expanded,
+                hint,
+            )
+            continue
+        candidates = [directory for directory in _manifest_skill_dirs(root) if directory.is_dir()]
+        # A path that is ALREADY a bare skills directory (<root>/<name>/SKILL.md)
+        # has no `skills/` subdir, so use it as-is. Deliberately not a fallback for
+        # a root that HAS one: `skills.paths` is scanned recursively and a repo
+        # root can contain self-referential symlinks (UiPath/skills has
+        # `plugins/uipath -> ..`), which resolves skills through an arbitrary path
+        # and silently drops duplicate names.
+        if not candidates:
+            candidates = [root]
+        for directory in candidates:
+            if next(directory.glob(f"*/{_SKILL_FILE}"), None) is None:
+                log.warning(
+                    f"{harness}: no <name>/%s directly under %s (from plugin %r) — the CLI still scans it "
+                    + "recursively, but check the plugin path points at a skills root",
+                    _SKILL_FILE,
+                    directory,
+                    path_str,
+                )
+            as_text = str(directory)
+            if as_text not in resolved:
+                resolved.append(as_text)
+    return resolved
diff --git a/src/coder_eval/agents/opencode_agent.py b/src/coder_eval/agents/opencode_agent.py
index d0e4c908..076a8bf4 100644
--- a/src/coder_eval/agents/opencode_agent.py
+++ b/src/coder_eval/agents/opencode_agent.py
@@ -38,9 +38,8 @@
 import shutil
 import signal
 import time
-from collections.abc import Callable, Mapping, Sequence
+from collections.abc import Callable
 from datetime import datetime
-from pathlib import Path
 from typing import Any, ClassVar, Literal, NoReturn
 
 from coder_eval.agent import Agent
@@ -77,8 +76,8 @@
     TurnEndStatus,
     TurnStartEvent,
 )
-from coder_eval.utils import expand_env_vars
 
+from ._skills import _plugin_skill_dirs
 from .registry import AgentRegistry
 
 
@@ -222,9 +221,6 @@
 # Only the skills half of a plugin is honored. A Claude plugin's agents, hooks,
 # commands and MCP servers have no OpenCode equivalent and are still dropped.
 _CONFIG_CONTENT_ENV = "OPENCODE_CONFIG_CONTENT"
-_PLUGIN_MANIFEST_RELPATH = (".claude-plugin", "plugin.json")
-_DEFAULT_PLUGIN_SKILLS_SUBDIR = "skills"
-_SKILL_FILE = "SKILL.md"
 
 # ToolEndStatus -> CommandTelemetry.result_status (the persisted tri-state).
 _RESULT_STATUS: dict[ToolEndStatus, Literal["success", "error", "unknown"]] = {
@@ -276,86 +272,6 @@ def _canonical_params(tool_name: str, params: dict[str, Any]) -> dict[str, Any]:
     return {rename.get(key, key): value for key, value in params.items()}
 
 
-def _manifest_skill_dirs(root: Path) -> list[Path]:
-    """Skill directories a Claude-plugin root declares, in manifest order.
-
-    Reads the ``skills`` field of ``<root>/.claude-plugin/plugin.json`` (a string
-    or a list of strings, each relative to the root) and falls back to the
-    convention default ``<root>/skills`` when the manifest is absent, unreadable,
-    or declares none. Honoring the manifest rather than hardcoding ``skills/``
-    keeps a plugin that relocates its skills working on both harnesses.
-    """
-    manifest = root.joinpath(*_PLUGIN_MANIFEST_RELPATH)
-    declared: list[str] = []
-    if manifest.is_file():
-        try:
-            data: Any = json.loads(manifest.read_text(encoding="utf-8"))
-        except (OSError, UnicodeDecodeError, json.JSONDecodeError):
-            data = None
-        if isinstance(data, dict):
-            value = data.get("skills")
-            if isinstance(value, str):
-                declared = [value]
-            elif isinstance(value, list):
-                declared = [entry for entry in value if isinstance(entry, str)]
-    if not declared:
-        declared = [_DEFAULT_PLUGIN_SKILLS_SUBDIR]
-    return [(root / relative).resolve() for relative in declared]
-
-
-def _plugin_skill_dirs(
-    plugins: Sequence[Mapping[str, Any]] | None,
-    log: logging.Logger | logging.LoggerAdapter[Any] = logger,
-) -> list[str]:
-    """Resolve ``plugins:`` entries to OpenCode ``skills.paths`` directories.
-
-    Every way this can come up empty is logged rather than passed over: a plugin
-    whose skills never reach the agent still *looks* like a normal run, which is
-    precisely the failure this function exists to close.
-    """
-    resolved: list[str] = []
-    for plugin in plugins or []:
-        if not isinstance(plugin, Mapping) or plugin.get("type") != "local":
-            log.warning("opencode: ignoring non-local plugin entry %r — only `type: local` maps to skills.", plugin)
-            continue
-        path_str = plugin.get("path")
-        if not path_str:
-            continue
-        expanded = expand_env_vars(str(path_str))
-        root = Path(expanded).resolve()
-        if not root.is_dir():
-            hint = "env var likely unset" if "$" in expanded else "path does not exist"
-            log.warning(
-                "opencode: plugin skills path did not resolve: %r -> %r (%s); no skills injected from it",
-                path_str,
-                expanded,
-                hint,
-            )
-            continue
-        candidates = [directory for directory in _manifest_skill_dirs(root) if directory.is_dir()]
-        # A path that is ALREADY a bare skills directory (<root>/<name>/SKILL.md)
-        # has no `skills/` subdir, so use it as-is. Deliberately not a fallback for
-        # a root that HAS one: `skills.paths` is scanned recursively and a repo
-        # root can contain self-referential symlinks (UiPath/skills has
-        # `plugins/uipath -> ..`), which resolves skills through an arbitrary path
-        # and silently drops duplicate names.
-        if not candidates:
-            candidates = [root]
-        for directory in candidates:
-            if next(directory.glob(f"*/{_SKILL_FILE}"), None) is None:
-                log.warning(
-                    "opencode: no <name>/%s directly under %s (from plugin %r) — the CLI still scans it "
-                    + "recursively, but check the plugin path points at a skills root",
-                    _SKILL_FILE,
-                    directory,
-                    path_str,
-                )
-            as_text = str(directory)
-            if as_text not in resolved:
-                resolved.append(as_text)
-    return resolved
-
-
 class _OpenCodeTurnState:
     """Per-``communicate()`` accumulator: events in, finalization payload out.
 
diff --git a/src/coder_eval/agents/pi_agent.py b/src/coder_eval/agents/pi_agent.py
new file mode 100644
index 00000000..0b50dd4b
--- /dev/null
+++ b/src/coder_eval/agents/pi_agent.py
@@ -0,0 +1,1243 @@
+"""Pi agent implementation (the ``pi`` Node coding agent — https://pi.dev/).
+
+Drives the ``pi`` CLI in JSON print mode::
+
+    pi -p --mode json --no-context-files --no-approve \
+        --session-dir <D> --session-id <ID> [--model provider/id] \
+        [--thinking L] [--append-system-prompt S] -- <prompt>
+
+which streams **newline-delimited JSON events** on stdout. Each line is one
+event; this module reduces that stream into the standardized coder_eval event
+protocol (``AgentStart`` / ``TurnStart`` / ``ToolStart`` / ``ToolEnd`` /
+``TurnEnd`` / ``AgentEnd``) and lets :class:`EventCollector` build the
+``TurnRecord`` — so no telemetry is assembled by hand here. The design mirrors
+:mod:`coder_eval.agents.opencode_agent` almost verbatim; the differences are
+noted inline.
+
+Event grammar (captured from ``pi`` 0.84.4)
+-------------------------------------------
+- ``{"type": "session", ...}`` — always line 1 (cwd/id/version).
+- ``{"type": "agent_start"}`` — bare; **can appear more than once** per
+  invocation (Pi auto-retries a transient/provider error internally).
+- ``{"type": "turn_start"}`` — bare; one per agent-loop step. This is the unit
+  ``max_turns`` counts.
+- ``{"type": "message_update", "assistantMessageEvent": {...}}`` — streaming
+  deltas (text/thinking/toolcall). Text deltas drive ``TextChunkEvent``.
+- ``{"type": "message_end", "message": {...}}`` — a complete message. Ignored
+  for token accounting: ``turn_end`` echoes the same assistant usage once per
+  step, and reading both would double-count.
+- ``{"type": "tool_execution_start", "toolCallId": ..., "toolName": ...,
+  "args": {...}}`` / ``{"type": "tool_execution_end", "toolCallId": ...,
+  "result": ..., "isError": ...}``.
+- ``{"type": "turn_end", "message": {...assistant...}, "toolResults": [...]}``
+  — ``message.usage`` is that step's OWN usage (per-generation), summed across
+  steps for the turn total.
+- ``{"type": "agent_end", "messages": [...], "willRetry": <bool>}`` —
+  ``willRetry: true`` means another retry cycle follows in the SAME invocation.
+- ``{"type": "agent_settled"}`` — the true terminal event (after all retries);
+  emit the single ``AgentEndEvent`` here / at EOF, NOT on the first
+  ``agent_end``.
+
+Token semantics
+---------------
+Per-generation, **SUM** (identical to OpenCode; NOT cumulative). Each
+``turn_end.message.usage`` carries ``{input, output, cacheRead, cacheWrite,
+[reasoning], totalTokens, cost:{...,total}}`` for that step, where
+``totalTokens == input + output + cacheRead + cacheWrite``. Unlike OpenCode,
+Pi's ``input`` IS the fresh slice already (no flat/nested arbitration needed),
+so it maps straight to ``uncached_input_tokens``. ``reasoning`` bills at the
+output rate. ``cost.total`` per step is summed into
+``token_usage.total_cost_usd`` (the rate card is only a fallback when the
+stream omits cost).
+
+Session continuity
+------------------
+A per-agent ``--session-dir`` + stable ``--session-id`` are assigned in
+``start()`` and replayed on every ``communicate()`` — create-if-missing on the
+first call, resume after — which is what makes multi-turn (dialog-mode)
+evaluation work across separate CLI invocations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import json
+import logging
+import os
+import re
+import shutil
+import signal
+import tempfile
+import time
+from collections.abc import Callable
+from datetime import datetime
+from typing import Any, ClassVar, Literal, NoReturn
+from uuid import uuid4
+
+from coder_eval.agent import Agent
+from coder_eval.agents._skills import _plugin_skill_dirs  # shared plugin->skills resolver
+from coder_eval.errors import AgentCrashError, TurnTimeoutError
+from coder_eval.isolation.docker_runner import STDOUT_LINE_LIMIT_BYTES
+from coder_eval.models import (
+    AgentKind,
+    AgentState,
+    ApiRoute,
+    AssistantMessage,
+    CommandTelemetry,
+    ContentBlock,
+    PiAgentConfig,
+    ResultSummary,
+    SystemPromptSemantics,
+    TokenUsage,
+    TranscriptMessage,
+    TurnRecord,
+)
+from coder_eval.pricing import calculate_cost
+from coder_eval.streaming.callbacks import StreamCallback, safe_emit
+from coder_eval.streaming.collector import EventCollector
+from coder_eval.streaming.events import (
+    AgentEndEvent,
+    AgentEndStatus,
+    AgentStartEvent,
+    StreamEvent,
+    TextChunkEvent,
+    ToolEndEvent,
+    ToolEndStatus,
+    ToolStartEvent,
+    TurnEndEvent,
+    TurnEndStatus,
+    TurnStartEvent,
+)
+
+from .registry import AgentRegistry
+
+
+logger = logging.getLogger(__name__)
+
+# Grace period between SIGTERM and SIGKILL when tearing down the CLI subprocess.
+# Doubles as the post-EOF exit grace in _settle_turn when no turn deadline is
+# configured. Re-declared here at the same value as OpenCode's rather than shared:
+# the full nd-JSON-CLI driver hoist that would unify the two harnesses' teardown
+# constants and reducers is a tracked follow-up; the shared plugin->skills resolver
+# already lives in `agents/_skills.py`. STDOUT_LINE_LIMIT_BYTES, which IS canonical,
+# is imported above.
+_TERM_GRACE_SECONDS = 5.0
+
+# SIGKILL does not exist on Windows (where the process-group sweep is a no-op
+# anyway); resolve it dynamically so the module imports and typechecks on every
+# platform, falling back to SIGTERM for the direct-pid kill_sync path.
+_SIGKILL: signal.Signals = getattr(signal, "SIGKILL", signal.SIGTERM)
+
+# How long to keep draining stdout/stderr after the CLI process has been reaped.
+# A print-mode CLI may leave an inherited pipe open, so every post-exit read
+# must be bounded.
+_DRAIN_SECONDS = 2.0
+
+# How many distinct unrecognized event-type strings to retain for the crash
+# message when the vocabulary check fails (diagnosis, not an exhaustive list).
+_MAX_UNRECOGNIZED_TYPES = 8
+
+# pi's native tool names -> the canonical (Claude) vocabulary every criterion is
+# written against. Mirrors opencode_agent._TOOL_NAME_MAP: without it a
+# `command_executed` with `tool_name: Bash` matches nothing on a Pi run. Unknown
+# tools pass through unchanged.
+_TOOL_NAME_MAP: dict[str, str] = {
+    "bash": "Bash",
+    "read": "Read",
+    "write": "Write",
+    "edit": "Edit",
+    "patch": "Edit",
+    "multiedit": "Edit",
+    # Pi's search tool is `find` (glob-by-pattern), NOT `glob` — mapping it to the
+    # canonical `Glob` keeps command_executed / commands_efficiency criteria
+    # comparable across harnesses. There is no `glob` tool in Pi's built-in set.
+    "find": "Glob",
+    "grep": "Grep",
+    "list": "LS",
+    "ls": "LS",
+    "webfetch": "WebFetch",
+    "todowrite": "TodoWrite",
+    "todoread": "TodoRead",
+    "task": "Agent",
+}
+
+# pi per-tool INPUT-arg key -> canonical (Claude) key. Mirrors
+# opencode_agent._OPENCODE_ARG_RENAME. The spike's write/read tools used `path`,
+# so map it to `file_path` for Read/Write/Edit (the search tools keep `path`,
+# which is already Claude's key). Keyed by the canonical tool name (post
+# _TOOL_NAME_MAP); unlisted keys pass through.
+_PI_ARG_RENAME: dict[str, dict[str, str]] = {
+    "Read": {"path": "file_path"},
+    "Write": {"path": "file_path"},
+    "Edit": {
+        "path": "file_path",
+        "oldString": "old_string",
+        "newString": "new_string",
+        "replaceAll": "replace_all",
+    },
+}
+
+# Config fields the Pi CLI has no equivalent knob for (v1), OR that cannot be
+# safely forwarded. `experiments/default.yaml` sets `permission_mode` and
+# `allowed_tools` on every task, so warn once at start() rather than let a task
+# believe it constrained the agent. NOTE `system_prompt` IS supported (mapped to
+# --append-system-prompt) and `plugins` IS supported (each resolved skills dir is
+# mapped to a `--skill <dir>` argument), so neither is here.
+_UNSUPPORTED_CONFIG_FIELDS: tuple[str, ...] = (
+    "permission_mode",
+    "system_prompt_file",
+    # Pi's built-in tool names are lowercase (bash/read/write/edit/grep/find/ls)
+    # and do not match the Claude-namespaced default (Bash/Read/Write/...), so
+    # forwarding them to --tools would allowlist nonexistent tools and strip the
+    # agent of ALL tools. Ignored like OpenCode/Codex/Antigravity do.
+    "allowed_tools",
+    "disallowed_tools",
+)
+
+# The full recognized Pi vocabulary (from `pi` 0.84.4). A clean exit that
+# recognized NOTHING from this set is vocabulary drift and is crashed rather than
+# scored as a silent empty success (see _settle_turn).
+_RECOGNIZED_EVENTS = frozenset(
+    {
+        "session",
+        "agent_start",
+        "turn_start",
+        "message_start",
+        "message_update",
+        "message_end",
+        "tool_execution_start",
+        "tool_execution_end",
+        "turn_end",
+        "agent_end",
+        "agent_settled",
+    }
+)
+
+# ToolEndStatus -> CommandTelemetry.result_status (the persisted tri-state).
+_RESULT_STATUS: dict[ToolEndStatus, Literal["success", "error", "unknown"]] = {
+    ToolEndStatus.OK: "success",
+    ToolEndStatus.ERROR: "error",
+    ToolEndStatus.PERMISSION_DENIED: "error",
+    ToolEndStatus.UNRESOLVED: "unknown",
+}
+
+
+def _canonical_params(tool_name: str, params: dict[str, Any]) -> dict[str, Any]:
+    """Rename a tool call's argument keys to the canonical cross-agent vocabulary.
+
+    Order is preserved and unlisted keys pass through untouched.
+    """
+    rename = _PI_ARG_RENAME.get(tool_name)
+    if not rename:
+        return params
+    return {rename.get(key, key): value for key, value in params.items()}
+
+
+def _result_text(result: Any) -> str | None:
+    """Best-effort flatten of a Pi ``tool_execution_end.result`` to text.
+
+    Pi results are ``{"content": [{"type": "text", "text": "..."}, ...]}`` (spike
+    verified). Fall back to the string form for any other shape so a summary is
+    never silently dropped.
+    """
+    if isinstance(result, dict):
+        content = result.get("content")
+        if isinstance(content, list):
+            parts = [str(item.get("text", "")) for item in content if isinstance(item, dict)]
+            joined = "".join(parts)
+            if joined:
+                return joined
+    if result is None:
+        return None
+    return str(result)
+
+
+class _PiTurnState:
+    """Per-``communicate()`` accumulator: events in, finalization payload out.
+
+    Owns everything the terminal ``AgentEndEvent`` must carry (transcript
+    messages, summed usage, text output) plus the open-tool bookkeeping needed
+    to force-close orphans when a turn dies mid-flight.
+    """
+
+    def __init__(self, *, task_id: str, iteration: int, user_input: str, model: str | None) -> None:
+        self.task_id = task_id
+        self.iteration = iteration
+        self.user_input = user_input
+        self.model = model
+
+        self.started_at = time.monotonic()
+        self.thread_id: str | None = None
+
+        # Cumulative turn totals (summed across every inner step).
+        self.usage = TokenUsage()
+        self.cost_usd: float = 0.0
+        self.saw_cost = False
+
+        self.messages: list[TranscriptMessage] = []
+        self.text_parts: list[str] = []
+
+        # Pi `turn_start` events counted; this is what max_turns caps.
+        self.turn_count = 0
+        self.turn_id: str = ""
+        # True between a step's `turn_start` and its `turn_end`. `finalize` needs
+        # it to close a TurnStartEvent the stream never got to close.
+        self.turn_open = False
+        self.turn_started_at: datetime | None = None
+        self.turn_text_parts: list[str] = []
+        self.turn_tool_ids: list[str] = []
+
+        # toolCallId -> telemetry for tools awaiting a result.
+        self.open_tools: dict[str, CommandTelemetry] = {}
+        self.sequence = 0
+        self.stop_reason: str | None = None
+        self.error_message: str | None = None
+        self.max_turns_exhausted = False
+        # Guards the one-terminal-event rule; see finalize().
+        self.finalized = False
+        # Count of events matched against the recognized Pi vocabulary (drift check),
+        # plus a bounded sample of the types that did NOT match — so the drift crash
+        # message can name what it actually saw.
+        self.recognized_events = 0
+        self.unrecognized_types: set[str] = set()
+        # Warn-once guard for token-accounting drift. The event-vocabulary check
+        # catches renamed EVENT types, but not a renamed/absent `usage` field or a
+        # bucket whose type changed — those silently coerce to 0 (see `_as_int`) and
+        # would zero out the run's tokens/cost, blinding max_total_tokens / max_usd
+        # gates. Mirrors OpenCode's `_warn_token_shape` (its escape hatch shipped
+        # with this warning; Pi's earlier cut kept the hatch but dropped the warn).
+        self.warned_token_shape = False
+
+        self._emit: Callable[[StreamEvent], None] = lambda _e: None
+
+    def bind(self, emit: Callable[[StreamEvent], None]) -> None:
+        self._emit = emit
+
+    def emit(self, event: StreamEvent) -> None:
+        self._emit(event)
+
+    @property
+    def agent_output(self) -> str:
+        return "".join(self.text_parts)
+
+    # --- event handlers ----------------------------------------------------
+
+    def on_turn_start(self) -> None:
+        # A prior step's `turn_start` with no `turn_end` — a generation aborted
+        # mid-turn (the defining willRetry case: a provider error before the
+        # assistant message completed). Close its dangling TurnStartEvent before
+        # opening the next, or the stream carries N starts and N-1 ends, breaking
+        # the one-pair-per-inner-turn contract renderers depend on. `finalize`
+        # closes only the LAST open turn, so it cannot cover this.
+        if self.turn_open:
+            self.turn_open = False
+            self.emit(
+                TurnEndEvent(
+                    task_id=self.task_id,
+                    thread_id=self.thread_id,
+                    turn_id=self.turn_id,
+                    status=TurnEndStatus.CRASHED,
+                    tokens=None,
+                )
+            )
+        self.turn_count += 1
+        self.turn_open = True
+        self.turn_id = f"turn_{self.turn_count}"
+        self.turn_started_at = datetime.now()
+        self.turn_text_parts = []
+        self.turn_tool_ids = []
+        self.emit(
+            TurnStartEvent(
+                task_id=self.task_id,
+                thread_id=self.thread_id,
+                turn_id=self.turn_id,
+                model=self.model,
+            )
+        )
+
+    def on_message_update(self, obj: dict[str, Any]) -> None:
+        """Stream a ``text_delta`` as a ``TextChunkEvent`` (thinking/toolcall ignored)."""
+        event = obj.get("assistantMessageEvent")
+        if not isinstance(event, dict) or event.get("type") != "text_delta":
+            return
+        delta = event.get("delta")
+        if not isinstance(delta, str) or not delta:
+            return
+        self.text_parts.append(delta)
+        self.turn_text_parts.append(delta)
+        self.emit(TextChunkEvent(task_id=self.task_id, thread_id=self.thread_id, turn_id=self.turn_id, text=delta))
+
+    def on_tool_execution_start(self, obj: dict[str, Any]) -> None:
+        call_id = str(obj.get("toolCallId") or f"call_{self.sequence + 1}")
+        if call_id in self.open_tools:
+            return
+        self.sequence += 1
+        raw_tool = str(obj.get("toolName") or "unknown")
+        tool_name = _TOOL_NAME_MAP.get(raw_tool.lower(), raw_tool)
+        args = obj.get("args")
+        params = args if isinstance(args, dict) else {}
+        started = datetime.now()
+        telemetry = CommandTelemetry(
+            tool_name=tool_name,
+            tool_id=call_id,
+            assistant_turn_index=self.turn_count,
+            timestamp=started,
+            execution_started_at=started,
+            parameters=_canonical_params(tool_name, params),
+            sequence_number=self.sequence,
+        )
+        self.open_tools[call_id] = telemetry
+        self.turn_tool_ids.append(call_id)
+        self.emit(ToolStartEvent(task_id=self.task_id, thread_id=self.thread_id, turn_id=self.turn_id, tool=telemetry))
+
+    def on_tool_execution_end(self, obj: dict[str, Any]) -> None:
+        call_id = str(obj.get("toolCallId") or "")
+        summary = _result_text(obj.get("result"))
+        is_error = bool(obj.get("isError"))
+        if is_error:
+            message = summary or "tool failed"
+            # Best-effort: Pi does not tag permission denials distinctly, so infer
+            # from the result text. The persisted tri-state folds both to "error"
+            # (see _RESULT_STATUS), so a misclassified legit "permission denied" in
+            # output is cosmetic. Mirrors opencode_agent.
+            denied = "permission" in message.lower() or "denied" in message.lower()
+            status = ToolEndStatus.PERMISSION_DENIED if denied else ToolEndStatus.ERROR
+        else:
+            message = None
+            status = ToolEndStatus.OK
+        self._close_tool(call_id, status=status, summary=summary, error=message)
+
+    def _close_tool(
+        self,
+        call_id: str,
+        *,
+        status: ToolEndStatus,
+        summary: str | None,
+        error: str | None,
+    ) -> None:
+        telemetry = self.open_tools.pop(call_id, None)
+        if telemetry is None:
+            # A result with no matching call (shouldn't happen, but never drop it).
+            self.sequence += 1
+            telemetry = CommandTelemetry(
+                tool_name="unknown",
+                tool_id=call_id,
+                assistant_turn_index=self.turn_count,
+                timestamp=datetime.now(),
+                sequence_number=self.sequence,
+            )
+        completed = datetime.now()
+        telemetry.execution_completed_at = completed
+        if telemetry.execution_started_at is not None:
+            telemetry.duration_ms = (completed - telemetry.execution_started_at).total_seconds() * 1000
+        telemetry.result_status = _RESULT_STATUS[status]
+        # Stored untruncated by design (sub-agent returns must survive whole).
+        telemetry.result_summary = summary
+        telemetry.error_message = error
+        self.emit(
+            ToolEndEvent(
+                task_id=self.task_id,
+                thread_id=self.thread_id,
+                turn_id=self.turn_id,
+                tool=telemetry,
+                status=status,
+            )
+        )
+
+    def _warn_token_shape(self, message: str, *args: Any) -> None:
+        """Log a token-accounting anomaly at most once per turn (not once per bucket/step)."""
+        if self.warned_token_shape:
+            return
+        self.warned_token_shape = True
+        logger.warning("pi: unexpected token accounting — " + message, *args)
+
+    def _as_int(self, value: Any) -> int:
+        """Coerce one stream-supplied token count; count a non-number as 0.
+
+        A bare ``int()`` would raise on a non-numeric value, which
+        ``communicate``'s ``except Exception`` turns into an ``AgentCrashError``
+        (categorized ``AGENT_CRASH``, ``max_retries=2``), burning three attempts
+        on one mistyped bucket. A bool is never a token count (``int(True) == 1``).
+
+        ``None`` is a legitimately-absent bucket (silent). Any OTHER unparseable
+        value is a schema drift and warns once — otherwise a changed bucket type
+        would silently zero the turn's tokens and cost.
+        """
+        if value is None:
+            return 0
+        if isinstance(value, bool) or not isinstance(value, int | float | str):
+            self._warn_token_shape("token count had unexpected type %s (%r); counted as 0", type(value).__name__, value)
+            return 0
+        try:
+            return int(value)
+        except (TypeError, ValueError):
+            self._warn_token_shape("token count %r was not parseable as an int; counted as 0", value)
+            return 0
+
+    def on_turn_end(self, obj: dict[str, Any]) -> None:
+        """Accumulate this step's usage and append its assistant message.
+
+        Usage is read from ``turn_end`` ONCE per step (not from every
+        ``message_end``, which echoes the same numbers) so the turn total is the
+        sum of the per-generation slices.
+        """
+        self.turn_open = False
+        message = obj.get("message")
+        message = message if isinstance(message, dict) else {}
+        raw_usage = message.get("usage")
+        if not isinstance(raw_usage, dict) or not raw_usage:
+            # A completed step that booked no usage object at all — a renamed or
+            # absent `usage` (which the event-vocabulary check cannot see). Its
+            # tokens/cost silently resolve to 0; say so once.
+            self._warn_token_shape("turn_end carried no usage object; this step's tokens/cost counted as 0")
+        usage = raw_usage if isinstance(raw_usage, dict) else {}
+
+        step_in = self._as_int(usage.get("input"))
+        raw_out = self._as_int(usage.get("output"))
+        step_reasoning = self._as_int(usage.get("reasoning"))
+        step_cw = self._as_int(usage.get("cacheWrite"))
+        step_cr = self._as_int(usage.get("cacheRead"))
+        # Reasoning bills at the output rate but is reported apart from `output`;
+        # fold it into the turn total (the per-message record keeps it separately).
+        step_out = raw_out + step_reasoning
+
+        # A turn_end that DID carry a usage object but whose every bucket resolves
+        # to 0 is the drift shape the whole-object check above cannot see: keys
+        # renamed by a CLI upgrade each coerce to 0 (see `_as_int`), tokens and cost
+        # silently vanish, and `max_usd` / `max_total_tokens` can never trip. Warn
+        # once (score, don't crash — the documented Pi policy). OpenCode guards the
+        # same gap with `steps_finished > 0 and usage.is_empty()`.
+        if raw_usage and step_in == raw_out == step_reasoning == step_cw == step_cr == 0:
+            self._warn_token_shape("turn_end usage object had all-zero token buckets; this step booked 0 tokens/cost")
+
+        self.usage = TokenUsage(
+            uncached_input_tokens=self.usage.uncached_input_tokens + step_in,
+            output_tokens=self.usage.output_tokens + step_out,
+            cache_creation_input_tokens=self.usage.cache_creation_input_tokens + step_cw,
+            cache_read_input_tokens=self.usage.cache_read_input_tokens + step_cr,
+        )
+        # Cross-check the stream's OWN `totalTokens` against the buckets we summed.
+        # Pi's invariant is totalTokens == input + output + cacheRead + cacheWrite
+        # (reasoning is billed at the output rate but excluded from this field, so
+        # compare against raw_out, not step_out). A mismatch means a bucket was
+        # renamed or its meaning moved under a CLI upgrade — exactly the drift the
+        # per-bucket `_as_int` coercion would otherwise absorb silently, blinding
+        # max_total_tokens / max_usd. Warn once, mirroring OpenCode's `tokens.total`
+        # guard; only when the field is actually present (older streams omit it).
+        reported_total = usage.get("totalTokens")
+        # Accept int OR float (a `123.0`-shaped total is itself a plausible drift and
+        # _as_int accepts floats for the buckets); the numeric compare below is
+        # exact for whole values (123.0 == 123).
+        if isinstance(reported_total, int | float) and not isinstance(reported_total, bool):
+            expected_total = step_in + raw_out + step_cw + step_cr
+            if reported_total != expected_total:
+                self._warn_token_shape(
+                    "turn_end totalTokens=%d does not reconcile with input+output+cacheRead+cacheWrite=%d — "
+                    + "a bucket may have been renamed or its meaning moved; re-check docs/agents/PI.md before "
+                    + "trusting cost",
+                    reported_total,
+                    expected_total,
+                )
+        cost = usage.get("cost")
+        if isinstance(cost, dict):
+            total = cost.get("total")
+            if isinstance(total, int | float) and not isinstance(total, bool):
+                self.cost_usd += float(total)
+                self.saw_cost = True
+
+        finish = message.get("stopReason")
+        if isinstance(finish, str) and finish:
+            self.stop_reason = finish
+        # Capture a terminal provider error so a `pi -p` that exits 0 after
+        # exhausting retries still surfaces WHY (finalize reads error_message into
+        # result_summary.result). Reset on a non-error turn so an intermediate
+        # retry error that a later cycle recovered from never leaks into the result.
+        if finish == "error":
+            err = message.get("errorMessage")
+            self.error_message = err if isinstance(err, str) and err else "pi reported stopReason=error"
+        else:
+            self.error_message = None
+
+        started = self.turn_started_at or datetime.now()
+        completed = datetime.now()
+        blocks: list[ContentBlock] = []
+        turn_text = "".join(self.turn_text_parts)
+        if turn_text:
+            blocks.append(ContentBlock(block_type="text", sequence=0, text=turn_text))
+        for i, tool_id in enumerate(self.turn_tool_ids, start=len(blocks)):
+            blocks.append(ContentBlock(block_type="tool_use", sequence=i, tool_use_id=tool_id))
+
+        self.messages.append(
+            AssistantMessage(
+                started_at=started,
+                completed_at=completed,
+                generation_duration_ms=(completed - started).total_seconds() * 1000,
+                content_blocks=blocks,
+                tool_use_ids=list(self.turn_tool_ids),
+                input_tokens=step_in,
+                output_tokens=step_out,
+                cache_creation_tokens=step_cw,
+                cache_read_tokens=step_cr,
+                reasoning_tokens=step_reasoning,
+                stop_reason=finish if isinstance(finish, str) else None,
+                model=self.model,
+                message_id=str(message.get("responseId") or "") or None,
+            )
+        )
+        self.emit(
+            TurnEndEvent(
+                task_id=self.task_id,
+                thread_id=self.thread_id,
+                turn_id=self.turn_id,
+                status=TurnEndStatus.COMPLETED,
+                tokens=TokenUsage(
+                    uncached_input_tokens=step_in,
+                    output_tokens=step_out,
+                    cache_creation_input_tokens=step_cw,
+                    cache_read_input_tokens=step_cr,
+                ),
+            )
+        )
+
+    def _rate_card_cost(self) -> float | None:
+        if not self.model or self.usage.is_empty():
+            return None
+        return calculate_cost(
+            self.model,
+            uncached_input_tokens=self.usage.uncached_input_tokens,
+            output_tokens=self.usage.output_tokens,
+            cache_creation_tokens=self.usage.cache_creation_input_tokens,
+            cache_read_tokens=self.usage.cache_read_input_tokens,
+        )
+
+    def _resolve_cost(self) -> float | None:
+        """Decide the turn's cost: the stream's own accounting vs the rate card.
+
+        Pi reports a real per-call ``cost.total`` (spike-verified), which wins for
+        any nonzero total. Two conservative fallbacks to the rate card:
+        - the stream reported no cost field at all (``saw_cost`` False), or
+        - it reported a cost field but the turn total came out exactly ``$0`` on a
+          model the rate card DOES price. A true $0 (free/promo response) and a
+          provider whose cost field is present-but-always-zero are indistinguishable
+          from the stream alone, so we prefer the rate card: understating cost would
+          silently defeat ``max_usd`` budget gates, which is the worse failure. A
+          genuinely free model (no rate-card entry) still resolves to the stream's 0.
+        """
+        rate = self._rate_card_cost()
+        if not self.saw_cost:
+            return rate
+        if self.cost_usd == 0.0 and rate:
+            logger.debug(
+                "pi: the stream reported $0 for a turn the rate card prices at $%.6f; using the rate card "
+                + "so the run total is not understated.",
+                rate,
+            )
+            return rate
+        return self.cost_usd
+
+    def close_open_tools(self) -> None:
+        """Force-close every tool still awaiting a result (crash/timeout orphans)."""
+        for call_id in list(self.open_tools):
+            self._close_tool(call_id, status=ToolEndStatus.UNRESOLVED, summary=None, error="no result observed")
+
+    def finalize(
+        self,
+        status: AgentEndStatus,
+        *,
+        crashed: bool = False,
+        crash_reason: str | None = None,
+    ) -> None:
+        """Close orphaned tools and emit the terminal ``AgentEndEvent`` (idempotent)."""
+        if self.finalized:
+            return
+        self.finalized = True
+        self.close_open_tools()
+        usage = self.usage
+        cost = self._resolve_cost()
+        if cost is not None:
+            usage = usage.model_copy(update={"total_cost_usd": cost})
+        # A turn still open here never received its `turn_end` — close its
+        # TurnStartEvent or the one-pair-per-inner-turn contract breaks.
+        if self.turn_open:
+            self.turn_open = False
+            self.emit(
+                TurnEndEvent(
+                    task_id=self.task_id,
+                    thread_id=self.thread_id,
+                    turn_id=self.turn_id,
+                    status=TurnEndStatus(status.value),
+                    tokens=None,
+                )
+            )
+        self.emit(
+            AgentEndEvent(
+                task_id=self.task_id,
+                thread_id=self.thread_id,
+                status=status,
+                usage=usage,
+                iteration=self.iteration,
+                user_input=self.user_input,
+                agent_output=self.agent_output,
+                model_used=self.model,
+                assistant_turn_count=self.turn_count,
+                messages=list(self.messages),
+                num_turns=self.turn_count,
+                max_turns_exhausted=self.max_turns_exhausted,
+                result_summary=ResultSummary(
+                    is_error=crashed,
+                    subtype=status.value,
+                    stop_reason=self.stop_reason,
+                    result=crash_reason or self.error_message,
+                ),
+                crashed=crashed,
+                crash_reason=crash_reason,
+                duration_seconds=time.monotonic() - self.started_at,
+            )
+        )
+
+
+@AgentRegistry.register(AgentKind.PI, PiAgentConfig)
+class PiAgent(Agent[PiAgentConfig]):
+    """Runs the ``pi`` CLI as a subprocess, one invocation per turn."""
+
+    # `should_stop` is polled at every event boundary — i.e. tool-call
+    # granularity — and honored by terminating the CLI subprocess cleanly.
+    supports_cooperative_stop: ClassVar[bool] = True
+
+    # Pi maps `system_prompt` to `--append-system-prompt`, so it appends to (does
+    # not replace) the CLI's default prompt. Declared explicitly (mirrors Codex /
+    # Antigravity, NOT OpenCode's `"unknown"`).
+    system_prompt_semantics: ClassVar[SystemPromptSemantics] = "append"
+
+    def __init__(
+        self,
+        config: PiAgentConfig,
+        route: ApiRoute | None = None,
+        *,
+        task_id: str = "unknown",
+    ) -> None:
+        """Every parameter the agent factory can pass is DECLARED, not absorbed.
+
+        ``create_agent`` calls ``agent_class(config, route=route, **kwargs)``
+        through a ``cast(Any, ...)``, so a ``**_`` sink would mean nothing checks
+        the kwargs at runtime either — a mis-gated kwarg must be loud here rather
+        than silently dropped.
+
+        ``route`` is accepted for factory parity and deliberately unused: the CLI
+        owns its own provider configuration. ``task_id`` only labels the emitted
+        event stream.
+        """
+        self.config = config
+        self.route = route
+        self.task_id = task_id
+        self.working_directory: str | None = None
+        self._env_path_prepend: list[str] = []
+        self._plugin_tools_dir: str | None = None
+        # Skills-parent dirs resolved from `agent.plugins`, passed to `pi --skill`
+        # (Pi discovers `<name>/SKILL.md` recursively). Assigned in start().
+        self._skill_dirs: list[str] = []
+        # Per-agent session, reused across communicate() calls for multi-turn /
+        # simulation continuity (assigned in start(), removed in stop() — NOT in
+        # kill(), which the orchestrator's mid-turn backstop calls; dropping the
+        # dir there would break resume across a retried turn. _cleanup always
+        # calls stop() after any kill(), so the tempdir is still reclaimed).
+        self._session_id: str | None = None
+        self._session_dir: str | None = None
+        self._process: asyncio.subprocess.Process | None = None
+        # Process-group ids of every invocation this agent spawned, swept on
+        # kill()/kill_sync()/stop().
+        self._spawned_pgids: list[int] = []
+        self._state = AgentState.WORKING
+
+    # --- lifecycle ---------------------------------------------------------
+
+    async def start(
+        self,
+        working_directory: str,
+        *,
+        env_path_prepend: list[str] | None = None,
+        plugin_tools_dir: str | None = None,
+    ) -> None:
+        if shutil.which("pi") is None:
+            raise RuntimeError(
+                "The 'pi' CLI was not found on PATH."
+                + " Install it with `npm install -g @earendil-works/pi-coding-agent` (see https://pi.dev/)."
+            )
+        ignored = [f for f in _UNSUPPORTED_CONFIG_FIELDS if getattr(self.config, f, None)]
+        if ignored:
+            logger.warning(
+                "pi: %s set but NOT enforced — the CLI has no equivalent knob in JSON print mode, so the run is "
+                + "unconstrained by them; do not rely on them as a boundary (see docs/agents/PI.md).",
+                ", ".join(ignored),
+            )
+        # Resolve `agent.plugins` -> skills dirs and load them via `pi --skill`.
+        # Loudly logs when plugins were declared but nothing resolved (the run
+        # would otherwise measure the model WITHOUT the skill under test).
+        self._skill_dirs = _plugin_skill_dirs(self.config.plugins, log=logger, harness="pi")
+        if self._skill_dirs:
+            logger.info("pi: loading %d skill dir(s) via --skill: %s", len(self._skill_dirs), self._skill_dirs)
+        elif self.config.plugins:
+            logger.warning(
+                "pi: %d plugin(s) declared but 0 skill dir(s) resolved — the agent will run WITHOUT them "
+                + "(see docs/agents/PI.md).",
+                len(self.config.plugins),
+            )
+        self.working_directory = working_directory
+        self._env_path_prepend = list(env_path_prepend or [])
+        self._plugin_tools_dir = plugin_tools_dir
+        # A stable pre-assigned id (create-if-missing on turn 1, resume after).
+        # The tempdir lives OUTSIDE the sandbox working dir and staged reference
+        # dir, so it never pollutes graded files or trips reference-integrity.
+        # Drop any session dir from a prior start() first so re-starting the same
+        # agent instance cannot leak a tempdir.
+        self._cleanup_session_dir()
+        # Sanitize task_id before it reaches pi's `--session-id`: dataset-row tasks
+        # have path-shaped ids ("suite/row_3", set in task_loader) and pi derives
+        # its session file from the id under `--session-dir`, so a raw '/' would
+        # resolve to a non-existent subdir and fail the row before any work. Keep
+        # only the safe id charset (mirrors sandbox.py's flatten, but stricter).
+        safe_task_id = re.sub(r"[^A-Za-z0-9._-]", "_", self.task_id)
+        self._session_id = f"coder-eval-{safe_task_id}-{uuid4().hex[:8]}"
+        self._session_dir = tempfile.mkdtemp(prefix="pi-session-")
+        self._state = AgentState.WORKING
+
+    async def stop(self) -> None:
+        await self.kill()
+        self._cleanup_session_dir()
+        self._mark_stopped()
+
+    def _cleanup_session_dir(self) -> None:
+        if self._session_dir is not None:
+            shutil.rmtree(self._session_dir, ignore_errors=True)
+            self._session_dir = None
+
+    async def kill(self) -> None:
+        proc = self._process
+        if proc is not None and proc.returncode is None:
+            with contextlib.suppress(ProcessLookupError):
+                proc.terminate()
+            with contextlib.suppress(TimeoutError, asyncio.TimeoutError):
+                await asyncio.wait_for(proc.wait(), timeout=_TERM_GRACE_SECONDS)
+            if proc.returncode is None:
+                with contextlib.suppress(ProcessLookupError):
+                    proc.kill()
+        self._sweep_process_groups()
+
+    def kill_sync(self) -> None:
+        """SIGKILL the in-flight CLI and its process group (watchdog thread; must not await)."""
+        proc = self._process
+        if proc is not None and proc.returncode is None:
+            with contextlib.suppress(ProcessLookupError, PermissionError):
+                os.kill(proc.pid, _SIGKILL)
+        self._sweep_process_groups()
+
+    def _sweep_process_groups(self) -> None:
+        """SIGKILL every process group this agent spawned (POSIX only).
+
+        Each invocation runs in its own session (``start_new_session``), so its
+        pgid is the CLI's pid and the group contains ONLY what that invocation
+        spawned — a lingering child included, a shared daemon we did not start
+        excluded.
+        """
+        if os.name != "posix":
+            return
+        for pgid in self._spawned_pgids:
+            with contextlib.suppress(ProcessLookupError, PermissionError, OSError):
+                os.killpg(pgid, _SIGKILL)
+        self._spawned_pgids.clear()
+
+    def get_environment_info(self) -> dict[str, Any]:
+        # Spread the base first so the `system_prompt_semantics` run marker is
+        # always present (CE046).
+        info: dict[str, Any] = {
+            **super().get_environment_info(),
+            "pi_model": self.config.model,
+            "pi_thinking_level": self.config.thinking_level,
+        }
+        if self._session_id:
+            info["pi_session_id"] = self._session_id
+        if self._skill_dirs:
+            # Recorded per task so a run's report can confirm the skills under test
+            # actually reached the agent.
+            info["pi_skill_paths"] = list(self._skill_dirs)
+        return info
+
+    # --- command construction ---------------------------------------------
+
+    def _build_argv(self, user_input: str) -> list[str]:
+        # -p exits after the run; --no-context-files + --no-approve isolate the
+        # sandbox from host AGENTS.md/CLAUDE.md and project-local trust (analogue
+        # of OpenCode --pure / Claude setting_sources: []). --session-dir +
+        # --session-id give cross-communicate() continuity (simulation mode) —
+        # reused every call, created on turn 1, resumed after. NOT --no-session
+        # (that would defeat continuity). All spike-verified. No --dir flag: the
+        # working dir is set via the subprocess `cwd`.
+        assert self._session_dir is not None and self._session_id is not None
+        argv = [
+            "pi",
+            "-p",
+            "--mode",
+            "json",
+            "--no-context-files",
+            "--no-approve",
+            "--session-dir",
+            self._session_dir,
+            "--session-id",
+            self._session_id,
+        ]
+        if self.config.model:
+            argv += ["--model", self.config.model]  # provider-prefixed form
+        if self.config.thinking_level:
+            argv += ["--thinking", self.config.thinking_level]
+        for skill_dir in self._skill_dirs:
+            # Additive skill load (from agent.plugins). Pi lists each skill's
+            # name+description in the system prompt and the agent `read`s the full
+            # SKILL.md on demand — the OpenCode/Codex `plugins` mechanism, Pi-native.
+            argv += ["--skill", skill_dir]
+        # allowed_tools / disallowed_tools are NOT forwarded. The shared config
+        # default (experiments/default.yaml) sets Claude-namespaced tool names
+        # (Bash/Read/Write/Edit/Glob/Grep/Skill), but Pi's built-in tools are
+        # lowercase and differently named (bash/read/write/edit/grep/find/ls).
+        # Passing the PascalCase names to `--tools` allowlists tools that do not
+        # exist in Pi, leaving the agent with ZERO tools ("I don't have tool
+        # access"). So, like OpenCode/Codex/Antigravity, these fields are treated
+        # as unenforced (see _UNSUPPORTED_CONFIG_FIELDS) and Pi runs with its full
+        # native toolset. Warned at start().
+        if self.config.system_prompt:
+            argv += ["--append-system-prompt", self.config.system_prompt]
+        # user_input is a distinct argv element after `--` (never shell-interpolated).
+        argv += ["--", user_input]
+        return argv
+
+    def _build_env(self) -> dict[str, str]:
+        """The CLI's full environment: the host's, plus the sandbox's contributions.
+
+        The PATH prepend is the mock-shadowing contract (``Agent.start``): the
+        sandbox's mock CLI directories must resolve BEFORE the real binaries.
+        ``PLUGIN_TOOLS_DIR`` is advisory and never overrides an inherited value.
+        Returns the WHOLE environment (seeded from ``os.environ``) so the CLI
+        keeps the host's provider credentials (``OPENROUTER_API_KEY``, ...).
+        """
+        env = dict(os.environ)
+        if self._env_path_prepend:
+            env["PATH"] = os.pathsep.join([*self._env_path_prepend, env.get("PATH", "")])
+        if self._plugin_tools_dir and "PLUGIN_TOOLS_DIR" not in env:
+            env["PLUGIN_TOOLS_DIR"] = self._plugin_tools_dir
+        return env
+
+    # --- the turn ----------------------------------------------------------
+
+    async def communicate(
+        self,
+        user_input: str,
+        *,
+        stream_callback: StreamCallback | None = None,
+        timeout: float | None = None,
+        max_turns: int | None = None,
+        should_stop: Callable[[], bool] | None = None,
+    ) -> TurnRecord:
+        if self.working_directory is None:
+            raise RuntimeError("PiAgent.start() must be called before communicate()")
+
+        self._begin_turn()
+        collector = EventCollector()
+
+        def emit(event: StreamEvent) -> None:
+            collector.on_event(event)
+            if stream_callback is not None:
+                safe_emit(stream_callback, event)
+
+        state = _PiTurnState(
+            task_id=self.task_id,
+            iteration=self._iteration,
+            user_input=user_input,
+            model=self.config.model,
+        )
+        state.bind(emit)
+
+        emit(
+            AgentStartEvent(
+                task_id=self.task_id,
+                prompt=user_input,
+                iteration=self._iteration,
+                model=self.config.model,
+            )
+        )
+
+        deadline = None if timeout is None else time.monotonic() + timeout
+        stopped_early = False
+        stderr_drain: asyncio.Future[bytes] | None = None
+        # Bound OUTSIDE the try so the teardown in `finally` can tell "never
+        # spawned" from "spawned and possibly still running".
+        proc: asyncio.subprocess.Process | None = None
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                *self._build_argv(user_input),
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                cwd=self.working_directory,
+                env=self._build_env(),
+                # A single nd-JSON event can carry a whole tool result, which blows
+                # past StreamReader's default 64 KiB line cap and would raise
+                # ValueError mid-stream, killing the read loop.
+                limit=STDOUT_LINE_LIMIT_BYTES,
+                # Own session/process group, so teardown can killpg any lingering
+                # child without touching anything this invocation didn't spawn.
+                start_new_session=os.name == "posix",
+            )
+            self._process = proc
+            if os.name == "posix":
+                self._spawned_pgids.append(proc.pid)
+            assert proc.stdout is not None
+
+            # Drain stderr CONCURRENTLY: a child that fills the ~64 KiB stderr pipe
+            # blocks on write, stops emitting stdout, and never exits — hanging the
+            # turn to its deadline. It gets its own reader so the nd-JSON on stdout
+            # stays clean.
+            if proc.stderr is not None:
+                stderr_drain = asyncio.ensure_future(proc.stderr.read())
+
+            # A print-mode CLI may leave an inherited pipe open, so readline() can
+            # block on an EOF that never comes. Race each read against process
+            # exit; once the process is gone a bounded drain collects the tail.
+            exit_waiter = asyncio.ensure_future(proc.wait())
+            read_task: asyncio.Future[bytes] | None = None
+            try:
+                while True:
+                    remaining = None if deadline is None else deadline - time.monotonic()
+                    if remaining is not None and remaining <= 0:
+                        await self._timeout_turn(state, collector, timeout or 0.0)
+
+                    if read_task is None:
+                        read_task = asyncio.ensure_future(proc.stdout.readline())
+                    done, _pending = await asyncio.wait(
+                        {read_task, exit_waiter},
+                        timeout=remaining,
+                        return_when=asyncio.FIRST_COMPLETED,
+                    )
+                    if not done:
+                        await self._timeout_turn(state, collector, timeout or 0.0)
+                    if not read_task.done():
+                        try:
+                            await asyncio.wait_for(asyncio.shield(read_task), _DRAIN_SECONDS)
+                        except TimeoutError:
+                            break
+                    line = read_task.result()
+                    read_task = None
+                    if not line:
+                        break
+
+                    self._handle_line(line, state)
+
+                    if max_turns is not None and state.turn_count > max_turns:
+                        state.max_turns_exhausted = True
+                        await self.kill()
+                        break
+                    if should_stop is not None and should_stop():
+                        stopped_early = True
+                        await self.kill()
+                        break
+            finally:
+                if read_task is not None:
+                    read_task.cancel()
+                exit_waiter.cancel()
+
+            status = await self._settle_turn(
+                proc,
+                state,
+                collector,
+                stderr_drain,
+                stopped_early=stopped_early,
+                deadline=deadline,
+                timeout=timeout,
+            )
+            state.finalize(status)
+            # Build BEFORE marking the turn clean: a failure in the reduction is a
+            # failed turn, and `_end_turn_ok` would clear the rollback flag that
+            # `discard_pending_turn` needs.
+            record = collector.build_turn_record()
+            self._end_turn_ok()
+            return record
+
+        except (AgentCrashError, TurnTimeoutError):
+            # Already funneled through finalize by _crash_turn / _timeout_turn.
+            raise
+        except asyncio.CancelledError:
+            self._finalize_external_cancel(state.finalize)
+            self._capture_partial_turn(collector)
+            raise
+        except Exception as e:
+            # A spawn failure (OSError), a StreamReader ValueError past `limit`, a
+            # malformed-payload error in a handler, a pydantic error assembling
+            # telemetry. Funnel to the pending-turn contract like the siblings.
+            self._crash_turn(state, collector, f"Pi turn failed: {e!s}", cause=e)
+            raise  # unreachable (_crash_turn is NoReturn) — makes the no-fall-through explicit
+        finally:
+            if stderr_drain is not None:
+                stderr_drain.cancel()
+            self._reap_orphaned_cli(proc)
+            self._process = None
+
+    def _reap_orphaned_cli(self, proc: asyncio.subprocess.Process | None) -> None:
+        """Kill a CLI still running as the turn unwinds. No-op otherwise.
+
+        The ``except Exception`` crash and an external cancellation both reach the
+        ``finally`` with the child possibly alive — neither passes through the
+        graceful ``kill()``. Abandoning it is not merely a leak: ``AgentCrashError``
+        is retried, so attempt 2 would spawn a SECOND ``pi`` editing the very files
+        the criteria are about to score. Synchronous (no await) so it survives a
+        ``CancelledError`` in flight. ``proc`` is ``None`` when the spawn failed.
+        """
+        if proc is None or proc.returncode is not None:
+            return
+        with contextlib.suppress(ProcessLookupError, PermissionError):
+            proc.kill()
+        self._sweep_process_groups()
+
+    async def _settle_turn(
+        self,
+        proc: asyncio.subprocess.Process,
+        state: _PiTurnState,
+        collector: EventCollector,
+        stderr_drain: asyncio.Future[bytes] | None,
+        *,
+        stopped_early: bool,
+        deadline: float | None,
+        timeout: float | None,
+    ) -> AgentEndStatus:
+        """Reap the CLI once the read loop is done and decide the turn's end status.
+
+        Raises ``AgentCrashError`` (via :meth:`_crash_turn`) when the process died
+        with neither an intentional stop nor a recognized event stream. Raises
+        ``TurnTimeoutError`` when the deadline elapses while waiting for the exit.
+        """
+        remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+        try:
+            await asyncio.wait_for(proc.wait(), timeout=_TERM_GRACE_SECONDS if remaining is None else remaining)
+        except TimeoutError:
+            if remaining is not None:
+                await self._timeout_turn(state, collector, timeout or 0.0)
+            await self.kill()
+            self._crash_turn(
+                state,
+                collector,
+                f"Pi closed its event stream but did not exit within {_TERM_GRACE_SECONDS:.0f}s",
+            )
+        stderr_bytes = b""
+        if stderr_drain is not None:
+            with contextlib.suppress(TimeoutError):
+                stderr_bytes = await asyncio.wait_for(asyncio.shield(stderr_drain), timeout=_DRAIN_SECONDS)
+
+        # A terminal provider error (stopReason=error that survived pi's internal
+        # retries) is infrastructure failure, not an agent failure. `pi -p` exits 0
+        # after exhausting retries, so without this the turn books as a clean
+        # COMPLETED (FinalStatus.FAILURE, category "failed") — silently depressing
+        # the measured pass rate. Crashing routes it through _communicate_with_retry
+        # and, if unrecovered, to FinalStatus.ERROR (category "error", excluded from
+        # outcomes). Mirrors opencode_agent._settle_turn.
+        #
+        # Gated on intentional cuts like the two crash arms below: `error_message`
+        # is set at an error `turn_end` and cleared only by a LATER non-error
+        # `turn_end`, but a `max_turns` / `should_stop` cut can fire at the next
+        # `turn_start` (before that clearing `turn_end` ever arrives), leaving a
+        # stale error from a turn pi was still retrying. Without the guard that
+        # clean, budget-exhausted cut would crash + burn retries, contradicting the
+        # documented "finalizes cleanly as max_turns_exhausted, no crash" contract.
+        if state.error_message is not None and not stopped_early and not state.max_turns_exhausted:
+            self._crash_turn(state, collector, f"Pi error: {state.error_message}")
+
+        # A non-zero exit with no intentional cut means the turn died.
+        if proc.returncode not in (0, None) and not stopped_early and not state.max_turns_exhausted:
+            detail = stderr_bytes.decode("utf-8", "replace").strip() or f"exit code {proc.returncode}"
+            self._crash_turn(state, collector, f"Pi exited non-zero: {detail}")
+
+        # A clean exit that recognized NO events is vocabulary drift — the CLI's
+        # schema moved, and scoring a silent empty success would be indistinguishable
+        # from a real pass in every aggregate. Intentional cuts are exempt (a stop
+        # can land before the first event).
+        if not stopped_early and not state.max_turns_exhausted and state.recognized_events == 0:
+            seen = ", ".join(sorted(state.unrecognized_types)) or "none (stdout carried no JSON events)"
+            self._crash_turn(
+                state,
+                collector,
+                "Pi exited cleanly but the turn captured no recognized events. Unrecognized event types seen: "
+                + f"{seen}. The CLI's event schema may have changed — see docs/agents/PI.md before trusting any "
+                + "run from this CLI version.",
+            )
+
+        if stopped_early:
+            return AgentEndStatus.STOPPED_EARLY
+        if state.max_turns_exhausted:
+            return AgentEndStatus.MAX_TURNS_EXHAUSTED
+        return AgentEndStatus.COMPLETED
+
+    def _crash_turn(
+        self,
+        state: _PiTurnState,
+        collector: EventCollector,
+        message: str,
+        *,
+        cause: BaseException | None = None,
+    ) -> NoReturn:
+        """Park the crashed partial record and raise ``AgentCrashError``."""
+        state.close_open_tools()
+        try:
+            self._finalize_and_raise_crash(state.finalize, message, cause=cause)
+        finally:
+            self._capture_partial_turn(collector)
+
+    async def _timeout_turn(
+        self,
+        state: _PiTurnState,
+        collector: EventCollector,
+        timeout: float,
+    ) -> NoReturn:
+        """Kill the CLI, park the crashed partial record, raise ``TurnTimeoutError``."""
+        await self.kill()
+        state.close_open_tools()
+        try:
+            self._finalize_and_raise_timeout(state.finalize, timeout)
+        finally:
+            self._capture_partial_turn(collector)
+
+    def _handle_line(self, line: bytes, state: _PiTurnState) -> None:
+        """Parse one nd-JSON line and dispatch it. Never raises on bad input.
+
+        Pi may emit multiple ``agent_start``/``turn_*``/``agent_end`` cycles in one
+        invocation (auto-retry). ``agent_end`` is NOT terminal — only
+        ``agent_settled`` / stdout EOF is — so it is recognized and otherwise
+        ignored, and the read loop keeps going.
+        """
+        raw = line.decode("utf-8", "replace").strip()
+        if not raw:
+            return
+        try:
+            obj = json.loads(raw)
+        except json.JSONDecodeError:
+            logger.debug("pi: skipping non-JSON stdout line: %s", raw[:200])
+            return
+        if not isinstance(obj, dict):
+            return
+
+        event_type = str(obj.get("type") or "")
+        # `session` is line 1 (cwd/id); `message_start`/`message_end`/`agent_end`/
+        # `agent_settled` carry no state we accumulate (usage is read from
+        # `turn_end`, not the echoing `message_end`). All are recognized vocabulary.
+        if event_type in _RECOGNIZED_EVENTS:
+            state.recognized_events += 1
+        elif len(state.unrecognized_types) < _MAX_UNRECOGNIZED_TYPES:
+            state.unrecognized_types.add(event_type or "<missing type>")
+
+        if event_type == "turn_start":
+            state.on_turn_start()
+        elif event_type == "message_update":
+            state.on_message_update(obj)
+        elif event_type == "tool_execution_start":
+            state.on_tool_execution_start(obj)
+        elif event_type == "tool_execution_end":
+            state.on_tool_execution_end(obj)
+        elif event_type == "turn_end":
+            state.on_turn_end(obj)
+        else:
+            logger.debug("pi: unhandled event type %r", event_type)
diff --git a/src/coder_eval/models/__init__.py b/src/coder_eval/models/__init__.py
index 97d4f64c..e9eab8bc 100644
--- a/src/coder_eval/models/__init__.py
+++ b/src/coder_eval/models/__init__.py
@@ -14,6 +14,7 @@
     LocalPluginConfig,
     NoneAgentConfig,
     OpenCodeAgentConfig,
+    PiAgentConfig,
     ResolvedAgentConfig,
     SystemPromptMode,
     SystemPromptSemantics,
@@ -227,6 +228,7 @@
     "LocalPluginConfig",
     "NoneAgentConfig",
     "OpenCodeAgentConfig",
+    "PiAgentConfig",
     "ResolvedAgentConfig",
     "SystemPromptMode",
     "SystemPromptSemantics",
diff --git a/src/coder_eval/models/agent_config.py b/src/coder_eval/models/agent_config.py
index a22756f7..1c79337f 100644
--- a/src/coder_eval/models/agent_config.py
+++ b/src/coder_eval/models/agent_config.py
@@ -381,6 +381,55 @@ class OpenCodeAgentConfig(BaseAgentConfig):
     )
 
 
+# Pi's ``--thinking`` reasoning-effort set. A STRICT SUPERSET of ThinkingLevel
+# (adds ``off``/``xhigh``/``max``), so Pi gets its own literal rather than reusing
+# the 4-value one — reuse would forbid valid Pi levels. Spike-confirmed against
+# ``pi --help`` on Pi 0.84.4.
+type PiThinkingLevel = Literal["off", "minimal", "low", "medium", "high", "xhigh", "max"]
+
+
+class PiAgentConfig(BaseAgentConfig):
+    """Pi agent configuration (the ``pi`` Node coding agent — https://pi.dev/).
+
+    Drives the ``pi`` CLI in JSON print mode
+    (``pi -p --mode json``), which streams newline-delimited JSON events on
+    stdout. ``model`` is Pi's provider-prefixed ``provider/model`` form (e.g.
+    ``openrouter/moonshotai/kimi-k3``) and is passed through verbatim via
+    ``--model`` (no separate ``--provider`` needed).
+
+    Session continuity (multi-turn / simulation)
+    --------------------------------------------
+    Each ``communicate()`` is one ``pi`` subprocess. A standard task reaches its
+    solution inside a single ``communicate()`` (Pi runs its own multi-step agent
+    loop). A simulation/dialog task calls ``communicate()`` once per user turn and
+    relies on the agent remembering prior turns — so ``PiAgent`` reuses a per-agent
+    ``--session-dir`` + stable ``--session-id`` on every invocation (create-if-missing
+    on turn 1, resume after), mirroring OpenCode's ``--session`` continuity.
+
+    Enforced vs unenforced fields
+    -----------------------------
+    ``system_prompt`` → ``--append-system-prompt`` IS enforced (a small capability
+    win over OpenCode). ``allowed_tools`` / ``disallowed_tools`` are NOT forwarded:
+    the shared config default sets Claude-namespaced tool names
+    (``Bash``/``Read``/…) that do not exist in Pi's lowercase toolset
+    (``bash``/``read``/…), so forwarding them to ``--tools`` would allowlist
+    nonexistent tools and strip the agent of ALL tools — like OpenCode/Codex/
+    Antigravity, Pi ignores them and runs with its full native toolset.
+    ``permission_mode`` is NOT enforced (Pi headless print mode auto-runs tools;
+    the sandbox driver is the isolation boundary) and ``system_prompt_file`` is NOT
+    read — both warned about at ``start()``. ``plugins`` skills ARE injected (each
+    resolved skills dir → a ``--skill <dir>`` arg, recorded as ``pi_skill_paths`` in
+    ``environment_info``), so Pi can run activation suites. See ``docs/agents/PI.md``.
+    """
+
+    type: Literal[AgentKind.PI]  # type: ignore[assignment]
+
+    thinking_level: PiThinkingLevel = Field(
+        default="medium",
+        description="Pi reasoning effort passed as --thinking (off/minimal/low/medium/high/xhigh/max).",
+    )
+
+
 class NoneAgentConfig(BaseAgentConfig):
     """No-op ("agentless") agent configuration.
 
@@ -405,7 +454,12 @@ class NoneAgentConfig(BaseAgentConfig):
 # Only includes the concrete subclasses (not BaseAgentConfig) since the discriminator
 # must be a Literal type. BaseAgentConfig is returned by parse_agent_config when type=None.
 type AgentConfig = Annotated[
-    ClaudeCodeAgentConfig | CodexAgentConfig | AntigravityAgentConfig | OpenCodeAgentConfig | NoneAgentConfig,
+    ClaudeCodeAgentConfig
+    | CodexAgentConfig
+    | AntigravityAgentConfig
+    | OpenCodeAgentConfig
+    | PiAgentConfig
+    | NoneAgentConfig,
     Field(discriminator="type"),
 ]
 
diff --git a/src/coder_eval/models/enums.py b/src/coder_eval/models/enums.py
index 0cba3650..10ed5c20 100644
--- a/src/coder_eval/models/enums.py
+++ b/src/coder_eval/models/enums.py
@@ -109,6 +109,7 @@ class AgentKind(StrEnum):
     CODEX = "codex"
     ANTIGRAVITY = "antigravity"
     OPENCODE = "opencode"
+    PI = "pi"
     NONE = "none"  # Agentless / system task — no coding agent runs; success criteria do all the work.
     UNKNOWN = "unknown"  # Used when agent type cannot be determined (e.g., task loading failure)
 
diff --git a/src/coder_eval/models/sandbox.py b/src/coder_eval/models/sandbox.py
index d2083d09..94108c47 100644
--- a/src/coder_eval/models/sandbox.py
+++ b/src/coder_eval/models/sandbox.py
@@ -256,6 +256,11 @@ class DockerDriverConfig(BaseModel):
             # selects the Gemini model when agent.model is unset.
             "GEMINI_API_KEY",
             "ANTIGRAVITY_MODEL",
+            # Pi agent provider credential — Pi addresses models as `provider/id`
+            # and reads OpenRouter's key from the env. The baked pi CLI + this
+            # passthrough make `--driver docker --type pi` work; without it the
+            # in-container pi has no credential and every turn fails auth.
+            "OPENROUTER_API_KEY",
             # User HOME used to keep ~/.claude resolution symmetric with the host.
             # See docs/DOCKER_ISOLATION.md "HOME is forwarded by default" for the
             # contract. tl;dr: Path.home() inside the container returns the
diff --git a/tasks/pi_smoke_test.yaml b/tasks/pi_smoke_test.yaml
new file mode 100644
index 00000000..f35084de
--- /dev/null
+++ b/tasks/pi_smoke_test.yaml
@@ -0,0 +1,38 @@
+task_id: "pi_smoke_test"
+description: "Smoke-test the Pi agent harness: create and run a small Python script."
+initial_prompt: "Create a Python file named app.py in the current working directory that prints 'Hello, Pi!' on one line, and today's date in YYYY-MM-DD format on the next line. Use the datetime module. Then run the script with: python app.py"
+# No `smoke-pass`: that tag routes a task into the CI E2E bucket, which runs on
+# Bedrock runners with no `pi` CLI and no OpenRouter credentials. Run this task
+# locally (or in a job that installs both) instead —
+# `npm install -g @earendil-works/pi-coding-agent`, then export OPENROUTER_API_KEY.
+tags: [smoke, basic, pure-python, pi]
+
+run_limits:
+  expected_turns: 5
+  # The CLI drives a full agent loop per invocation; give it room but keep the
+  # smoke bounded so a hung provider fails fast instead of stalling a suite.
+  task_timeout: 600
+
+agent:
+  type: "pi"
+  # Pi addresses models as provider/model and speaks OpenRouter natively
+  # (authenticated by OPENROUTER_API_KEY), so it needs no LiteLLM proxy. Real
+  # per-call cost lands on the turn: Pi reports `cost` on every turn_end event
+  # and the harness folds it into token_usage.total_cost_usd (falling back to the
+  # rate card only when the stream omits it). Spike-verified working model;
+  # swappable to any Pi-addressable provider/id.
+  model: "openrouter/moonshotai/kimi-k3"
+  permission_mode: "acceptEdits"
+
+success_criteria:
+  - type: "file_exists"
+    path: "app.py"
+    description: "The file app.py must be created."
+  - type: "file_contains"
+    path: "app.py"
+    includes: ["Hello, Pi!", "datetime"]
+    description: "The script must contain the required string and import."
+  - type: "run_command"
+    command: "python app.py"
+    timeout: 10
+    description: "The script must execute successfully."
diff --git a/tests/fixtures/pi_happy_stream.jsonl b/tests/fixtures/pi_happy_stream.jsonl
new file mode 100644
index 00000000..2891a4a0
--- /dev/null
+++ b/tests/fixtures/pi_happy_stream.jsonl
@@ -0,0 +1,45 @@
+{"type":"session","version":3,"id":"01a06be7-fbbf-7641-9680-be47d4693f73","timestamp":"2026-09-04T10:12:40.511Z","cwd":"/work"}
+{"type":"agent_start"}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"user","content":[{"type":"text","text":"Create a file named hello.txt containing exactly the word hi using the write tool. Then read it back with the read tool and state the contents."}],"timestamp":1788516760585}}
+{"type":"message_end","message":{"role":"user","content":[{"type":"text","text":"Create a file named hello.txt containing exactly the word hi using the write tool. Then read it back with the read tool and state the contents."}],"timestamp":1788516760585}}
+{"type":"message_start","message":{"role":"assistant","content":[],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"pending","timestamp":1788516760616}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"thinking_start","contentIndex":0}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"thinking_delta","contentIndex":0,"delta":"Write"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"thinking_delta","contentIndex":0,"delta":" file then"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"thinking_delta","contentIndex":0,"delta":" read."}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_start","contentIndex":1,"id":"write:0","toolName":"write"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_delta","contentIndex":1,"delta":""}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_delta","contentIndex":1,"delta":"{\"path\": \"hello.txt\", \"content\": \"hi\"}"}}
+{"type":"message_update","usage":{"input":406,"output":69,"cacheRead":1024,"cacheWrite":0,"reasoning":8,"totalTokens":1499,"cost":{"input":0.0010352999999999998,"output":0.00087975,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002177194}},"assistantMessageEvent":{"type":"thinking_end","contentIndex":0,"content":"Write file then read."}}
+{"type":"message_update","usage":{"input":406,"output":69,"cacheRead":1024,"cacheWrite":0,"reasoning":8,"totalTokens":1499,"cost":{"input":0.0010352999999999998,"output":0.00087975,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002177194}},"assistantMessageEvent":{"type":"toolcall_end","contentIndex":1,"toolCall":{"type":"toolCall","id":"write:0","name":"write","arguments":{"path":"hello.txt","content":"hi"}}}}
+{"type":"message_end","message":{"role":"assistant","content":[{"type":"thinking","thinking":"Write file then read.","thinkingSignature":"[{\"type\":\"reasoning.text\",\"text\":\"Write file then read.\",\"format\":\"unknown\",\"index\":0}]"},{"type":"toolCall","id":"write:0","name":"write","arguments":{"path":"hello.txt","content":"hi"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":406,"output":69,"cacheRead":1024,"cacheWrite":0,"reasoning":8,"totalTokens":1499,"cost":{"input":0.0010352999999999998,"output":0.00087975,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002177194}},"stopReason":"toolUse","timestamp":1788516760616,"responseId":"gen-1788516760-h7AqlA8rocYqvzr5bE9l","rawStopReason":"tool_calls"}}
+{"type":"tool_execution_start","toolCallId":"write:0","toolName":"write","args":{"path":"hello.txt","content":"hi"}}
+{"type":"tool_execution_end","toolCallId":"write:0","toolName":"write","result":{"content":[{"type":"text","text":"Successfully wrote 2 bytes to hello.txt"}]},"isError":false}
+{"type":"message_start","message":{"role":"toolResult","toolCallId":"write:0","toolName":"write","content":[{"type":"text","text":"Successfully wrote 2 bytes to hello.txt"}],"isError":false,"timestamp":1788516762541}}
+{"type":"message_end","message":{"role":"toolResult","toolCallId":"write:0","toolName":"write","content":[{"type":"text","text":"Successfully wrote 2 bytes to hello.txt"}],"isError":false,"timestamp":1788516762541}}
+{"type":"turn_end","message":{"role":"assistant","content":[{"type":"thinking","thinking":"Write file then read.","thinkingSignature":"[{\"type\":\"reasoning.text\",\"text\":\"Write file then read.\",\"format\":\"unknown\",\"index\":0}]"},{"type":"toolCall","id":"write:0","name":"write","arguments":{"path":"hello.txt","content":"hi"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":406,"output":69,"cacheRead":1024,"cacheWrite":0,"reasoning":8,"totalTokens":1499,"cost":{"input":0.0010352999999999998,"output":0.00087975,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002177194}},"stopReason":"toolUse","timestamp":1788516760616,"responseId":"gen-1788516760-h7AqlA8rocYqvzr5bE9l","rawStopReason":"tool_calls"},"toolResults":[{"role":"toolResult","toolCallId":"write:0","toolName":"write","content":[{"type":"text","text":"Successfully wrote 2 bytes to hello.txt"}],"isError":false,"timestamp":1788516762541}]}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"pending","timestamp":1788516762544}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_start","contentIndex":0,"id":"read:1","toolName":"read"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_delta","contentIndex":0,"delta":""}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"toolcall_delta","contentIndex":0,"delta":"{\"path\": \"hello.txt\"}"}}
+{"type":"message_update","usage":{"input":512,"output":49,"cacheRead":1024,"cacheWrite":0,"reasoning":3,"totalTokens":1585,"cost":{"input":0.0013055999999999999,"output":0.00062475,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002192494}},"assistantMessageEvent":{"type":"toolcall_end","contentIndex":0,"toolCall":{"type":"toolCall","id":"read:1","name":"read","arguments":{"path":"hello.txt"}}}}
+{"type":"message_end","message":{"role":"assistant","content":[{"type":"toolCall","id":"read:1","name":"read","arguments":{"path":"hello.txt"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":512,"output":49,"cacheRead":1024,"cacheWrite":0,"reasoning":3,"totalTokens":1585,"cost":{"input":0.0013055999999999999,"output":0.00062475,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002192494}},"stopReason":"toolUse","timestamp":1788516762544,"responseId":"gen-1788516762-S6qNOttzQjEAZuTdBsee","rawStopReason":"tool_calls"}}
+{"type":"tool_execution_start","toolCallId":"read:1","toolName":"read","args":{"path":"hello.txt"}}
+{"type":"tool_execution_end","toolCallId":"read:1","toolName":"read","result":{"content":[{"type":"text","text":"hi"}]},"isError":false}
+{"type":"message_start","message":{"role":"toolResult","toolCallId":"read:1","toolName":"read","content":[{"type":"text","text":"hi"}],"isError":false,"timestamp":1788516764037}}
+{"type":"message_end","message":{"role":"toolResult","toolCallId":"read:1","toolName":"read","content":[{"type":"text","text":"hi"}],"isError":false,"timestamp":1788516764037}}
+{"type":"turn_end","message":{"role":"assistant","content":[{"type":"toolCall","id":"read:1","name":"read","arguments":{"path":"hello.txt"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":512,"output":49,"cacheRead":1024,"cacheWrite":0,"reasoning":3,"totalTokens":1585,"cost":{"input":0.0013055999999999999,"output":0.00062475,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002192494}},"stopReason":"toolUse","timestamp":1788516762544,"responseId":"gen-1788516762-S6qNOttzQjEAZuTdBsee","rawStopReason":"tool_calls"},"toolResults":[{"role":"toolResult","toolCallId":"read:1","toolName":"read","content":[{"type":"text","text":"hi"}],"isError":false,"timestamp":1788516764037}]}
+{"type":"turn_start"}
+{"type":"message_start","message":{"role":"assistant","content":[],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"stopReason":"pending","timestamp":1788516764038}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_start","contentIndex":0}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":"Created"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" `hello.txt` and"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":" read it back. Contents"}}
+{"type":"message_update","usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"total":0}},"assistantMessageEvent":{"type":"text_delta","contentIndex":0,"delta":": **hi**"}}
+{"type":"message_update","usage":{"input":79,"output":28,"cacheRead":1536,"cacheWrite":0,"reasoning":3,"totalTokens":1643,"cost":{"input":0.00020145,"output":0.000357,"cacheRead":0.00039321600000000005,"cacheWrite":0,"total":0.0009516660000000001}},"assistantMessageEvent":{"type":"text_end","contentIndex":0,"content":"Created `hello.txt` and read it back. Contents: **hi**"}}
+{"type":"message_end","message":{"role":"assistant","content":[{"type":"text","text":"Created `hello.txt` and read it back. Contents: **hi**"}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":79,"output":28,"cacheRead":1536,"cacheWrite":0,"reasoning":3,"totalTokens":1643,"cost":{"input":0.00020145,"output":0.000357,"cacheRead":0.00039321600000000005,"cacheWrite":0,"total":0.0009516660000000001}},"stopReason":"stop","timestamp":1788516764038,"responseId":"gen-1788516764-PDS1DE9HRseKaqHTeGIx","rawStopReason":"stop"}}
+{"type":"turn_end","message":{"role":"assistant","content":[{"type":"text","text":"Created `hello.txt` and read it back. Contents: **hi**"}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":79,"output":28,"cacheRead":1536,"cacheWrite":0,"reasoning":3,"totalTokens":1643,"cost":{"input":0.00020145,"output":0.000357,"cacheRead":0.00039321600000000005,"cacheWrite":0,"total":0.0009516660000000001}},"stopReason":"stop","timestamp":1788516764038,"responseId":"gen-1788516764-PDS1DE9HRseKaqHTeGIx","rawStopReason":"stop"},"toolResults":[]}
+{"type":"agent_end","messages":[{"role":"user","content":[{"type":"text","text":"Create a file named hello.txt containing exactly the word hi using the write tool. Then read it back with the read tool and state the contents."}],"timestamp":1788516760585},{"role":"assistant","content":[{"type":"thinking","thinking":"Write file then read.","thinkingSignature":"[{\"type\":\"reasoning.text\",\"text\":\"Write file then read.\",\"format\":\"unknown\",\"index\":0}]"},{"type":"toolCall","id":"write:0","name":"write","arguments":{"path":"hello.txt","content":"hi"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":406,"output":69,"cacheRead":1024,"cacheWrite":0,"reasoning":8,"totalTokens":1499,"cost":{"input":0.0010352999999999998,"output":0.00087975,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002177194}},"stopReason":"toolUse","timestamp":1788516760616,"responseId":"gen-1788516760-h7AqlA8rocYqvzr5bE9l","rawStopReason":"tool_calls"},{"role":"toolResult","toolCallId":"write:0","toolName":"write","content":[{"type":"text","text":"Successfully wrote 2 bytes to hello.txt"}],"isError":false,"timestamp":1788516762541},{"role":"assistant","content":[{"type":"toolCall","id":"read:1","name":"read","arguments":{"path":"hello.txt"}}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":512,"output":49,"cacheRead":1024,"cacheWrite":0,"reasoning":3,"totalTokens":1585,"cost":{"input":0.0013055999999999999,"output":0.00062475,"cacheRead":0.000262144,"cacheWrite":0,"total":0.002192494}},"stopReason":"toolUse","timestamp":1788516762544,"responseId":"gen-1788516762-S6qNOttzQjEAZuTdBsee","rawStopReason":"tool_calls"},{"role":"toolResult","toolCallId":"read:1","toolName":"read","content":[{"type":"text","text":"hi"}],"isError":false,"timestamp":1788516764037},{"role":"assistant","content":[{"type":"text","text":"Created `hello.txt` and read it back. Contents: **hi**"}],"api":"openai-completions","provider":"openrouter","model":"moonshotai/kimi-k3","usage":{"input":79,"output":28,"cacheRead":1536,"cacheWrite":0,"reasoning":3,"totalTokens":1643,"cost":{"input":0.00020145,"output":0.000357,"cacheRead":0.00039321600000000005,"cacheWrite":0,"total":0.0009516660000000001}},"stopReason":"stop","timestamp":1788516764038,"responseId":"gen-1788516764-PDS1DE9HRseKaqHTeGIx","rawStopReason":"stop"}],"willRetry":false}
+{"type":"agent_settled"}
diff --git a/tests/lint/agent_roster_parity.py b/tests/lint/agent_roster_parity.py
index 873f7c4f..4dba2ac6 100644
--- a/tests/lint/agent_roster_parity.py
+++ b/tests/lint/agent_roster_parity.py
@@ -45,15 +45,21 @@
 # How each built-in agent is spelled in prose. Keyed by the `AgentKind` VALUE so a
 # new built-in fails `test_every_builtin_kind_has_display_names` until its prose
 # name is declared here — the enum stays the trigger, this table is only the
-# spelling. Matching is case-insensitive and substring-based, so "Codex" also
-# covers "OpenAI Codex" and `coder-eval[codex]`.
+# spelling. Matching is case-insensitive and WORD-BOUNDARY anchored (see
+# `missing_agents_in`), so a short name like "Pi" matches the standalone word but
+# NOT "anthropic" / "ci-pipeline" / "copies"; "Codex" still covers "OpenAI Codex"
+# and the bracketed `coder-eval[codex]`.
 AGENT_DISPLAY_NAMES: dict[str, tuple[str, ...]] = {
-    "claude-code": ("Claude Code",),
+    # The hyphenated `claude-code` spelling is listed alongside the prose form so
+    # the word-boundary matcher accepts the packaging-metadata keyword too
+    # (`\bClaude Code\b` would not match the hyphenated form).
+    "claude-code": ("Claude Code", "claude-code"),
     "codex": ("Codex",),
     # Google's harness is named on some surfaces by its model ("Gemini"), which is
     # an acceptable spelling of the same row.
     "antigravity": ("Antigravity", "Gemini"),
     "opencode": ("OpenCode",),
+    "pi": ("Pi",),
 }
 
 
@@ -94,11 +100,12 @@ def roster_kinds() -> list[str]:
 
 def missing_agents_in(text: str, kinds: list[str] | None = None) -> list[str]:
     """Roster kinds that ``text`` names by none of their accepted spellings."""
-    haystack = text.lower()
     return [
         kind
         for kind in (kinds if kinds is not None else roster_kinds())
-        if not any(name.lower() in haystack for name in AGENT_DISPLAY_NAMES.get(kind, (kind,)))
+        if not any(
+            re.search(rf"\b{re.escape(name)}\b", text, re.IGNORECASE) for name in AGENT_DISPLAY_NAMES.get(kind, (kind,))
+        )
     ]
 
 
diff --git a/tests/test_custom_lint.py b/tests/test_custom_lint.py
index adfbd60c..e5a12bfb 100644
--- a/tests/test_custom_lint.py
+++ b/tests/test_custom_lint.py
@@ -3647,13 +3647,27 @@ def test_catches_the_opencode_regression(self):
         # The exact historical gap: a surface listing three of the four harnesses.
         from tests.lint.agent_roster_parity import missing_agents_in
 
-        three_of_four = "runs Claude Code, Codex, or Antigravity (Gemini) in a sandbox"
+        three_of_four = "runs Claude Code, Codex, Antigravity (Gemini), or Pi in a sandbox"
         assert missing_agents_in(three_of_four) == ["opencode"]
 
     def test_model_name_counts_as_naming_the_antigravity_row(self):
         from tests.lint.agent_roster_parity import missing_agents_in
 
-        assert missing_agents_in("Claude Code, Codex, Gemini, and OpenCode") == []
+        assert missing_agents_in("Claude Code, Codex, Gemini, OpenCode, and Pi") == []
+
+    def test_short_name_is_not_satisfied_by_a_substring(self):
+        # The matcher is word-boundary anchored, so the 2-char "Pi" row is NOT
+        # satisfied by an incidental bigram in unrelated prose — the exact
+        # false-negative that let a stale roster ship undetected for Pi.
+        from tests.lint.agent_roster_parity import missing_agents_in
+
+        for decoy in ("anthropic models", "see the ci-pipeline.md guide", "the harness copies files"):
+            assert missing_agents_in(decoy, kinds=["pi"]) == ["pi"]
+        # A standalone mention (any surrounding punctuation) DOES satisfy it.
+        assert missing_agents_in("runs Pi in a sandbox", kinds=["pi"]) == []
+        assert missing_agents_in("… OpenCode, or Pi —", kinds=["pi"]) == []
+        # The hyphenated packaging spelling satisfies the claude-code row.
+        assert missing_agents_in("coder-eval[claude-code]", kinds=["claude-code"]) == []
 
     def test_extractors_narrow_to_the_marketing_region(self, tmp_path: Path):
         from tests.lint.agent_roster_parity import _mkdocs_site_description, _pyproject_marketing_text
diff --git a/tests/test_docker_wildcard_env.py b/tests/test_docker_wildcard_env.py
index 0c61775f..803ce2ec 100644
--- a/tests/test_docker_wildcard_env.py
+++ b/tests/test_docker_wildcard_env.py
@@ -44,3 +44,10 @@ def test_env_passthrough_extra_list_persists(self):
         extras = ["TOKEN_A", "TOKEN_B", "TOKEN_C"]
         cfg = DockerDriverConfig(env_passthrough_extra=extras)
         assert cfg.env_passthrough_extra == extras
+
+    def test_openrouter_api_key_in_default_allowlist(self):
+        """Pi's provider credential ships in the default env_passthrough so a
+        `--driver docker --type pi` run authenticates without a per-task
+        env_passthrough_extra. Read the default off the model so the assertion
+        survives future additions to the allowlist."""
+        assert "OPENROUTER_API_KEY" in DockerDriverConfig().env_passthrough
diff --git a/tests/test_image_from_dockerfiles.py b/tests/test_image_from_dockerfiles.py
index 5ab57d9a..2400aa39 100644
--- a/tests/test_image_from_dockerfiles.py
+++ b/tests/test_image_from_dockerfiles.py
@@ -507,3 +507,34 @@ def _pin(df: Path) -> str | None:
         f"CLAUDE_CODE_VERSION drift: docker/Dockerfile pins {fw!r} but docker/Dockerfile.runtime pins {kit!r} — "
         "inject and rebase tasks would run different Claude Code versions."
     )
+
+
+def test_pi_cli_baked_and_pinned() -> None:
+    """docker/Dockerfile must ship a PINNED Pi CLI, and its install line must
+    reference the ARG (not a hardcoded literal) so a bump is one edit and the
+    pin can't drift from the install. Mirrors the claude-code pinned-CLI guard
+    above — Pi's presence is a positive, mechanically-checkable invariant
+    (`--driver docker --type pi` depends on it). Fails on @latest or removal.
+    Scope: main docker/Dockerfile only — Dockerfile.runtime deliberately does
+    NOT bake Pi (inject-mode is out of scope), so it is not asserted here."""
+    df_text = (Path(__file__).resolve().parents[1] / "docker" / "Dockerfile").read_text(encoding="utf-8")
+
+    pin: str | None = None
+    for ln in df_text.splitlines():
+        m = re.match(r"\s*ARG PI_VERSION=(\S+)", ln)
+        if m:
+            pin = m.group(1)
+            break
+    assert pin, "ARG PI_VERSION=<version> missing from docker/Dockerfile — the Pi CLI is not pinned."
+    assert pin.lower() != "latest", (
+        f"PI_VERSION is pinned to {pin!r} — the Pi CLI must be an exact version, not `latest`, so layer "
+        "caching cannot freeze it nondeterministically across rebuilds."
+    )
+
+    assert re.search(
+        r"npm install -g @earendil-works/pi-coding-agent@\$\{PI_VERSION\}",
+        df_text,
+    ), (
+        "docker/Dockerfile must `npm install -g @earendil-works/pi-coding-agent@${PI_VERSION}` — the install "
+        "must reference the PI_VERSION ARG so the pin and the install cannot drift."
+    )
diff --git a/tests/test_pi_agent.py b/tests/test_pi_agent.py
new file mode 100644
index 00000000..f0c305fe
--- /dev/null
+++ b/tests/test_pi_agent.py
@@ -0,0 +1,1195 @@
+"""Tests for the Pi agent harness.
+
+The CLI is never invoked: ``asyncio.create_subprocess_exec`` is patched with a
+fake process that replays a newline-delimited JSON event stream, so the whole
+reduction path (nd-JSON -> standardized events -> ``TurnRecord``) is exercised
+offline and without credentials.
+
+The happy fixture (``tests/fixtures/pi_happy_stream.jsonl``) is a BYTE-REAL
+capture from ``pi -p --mode json`` 0.84.4 (write hello.txt + read it back, 3
+agent-loop turns). The expected token/cost totals below are derived from that
+fixture's per-``turn_end`` usages, summed — not free-standing magic numbers.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import signal
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from coder_eval.agents.pi_agent import PiAgent, _PiTurnState, _result_text
+from coder_eval.errors import AgentCrashError, TurnTimeoutError
+from coder_eval.models import AgentKind, AssistantMessage, PiAgentConfig
+from coder_eval.pricing import calculate_cost
+from coder_eval.streaming.events import (
+    AgentEndEvent,
+    AgentEndStatus,
+    AgentStartEvent,
+    ToolEndEvent,
+    ToolEndStatus,
+    ToolStartEvent,
+    TurnEndEvent,
+    TurnEndStatus,
+    TurnStartEvent,
+)
+
+
+_FIXTURE = Path(__file__).parent / "fixtures" / "pi_happy_stream.jsonl"
+HAPPY_STREAM = _FIXTURE.read_text(encoding="utf-8").splitlines()
+
+# Derived from the fixture's three `turn_end` usages (per-generation, summed):
+#   input   406 + 512 + 79   = 997
+#   output  (69+8)+(49+3)+(28+3) = 160   (reasoning folds into the output rate)
+#   cacheRead 1024 + 1024 + 1536 = 3584
+#   cost.total 0.002177194 + 0.002192494 + 0.000951666 = 0.005321354
+EXPECTED_INPUT = 997
+EXPECTED_OUTPUT = 160
+EXPECTED_CACHE_READ = 3584
+EXPECTED_COST = 0.005321354
+
+
+def _turn_start() -> str:
+    return json.dumps({"type": "turn_start"})
+
+
+def _turn_end(*, inp: int, out: int, cache_read: int = 0, cache_write: int = 0, reasoning: int = 0, cost: float = 0.0):
+    """A `turn_end` event carrying that step's own (per-generation) usage."""
+    usage: dict[str, Any] = {
+        "input": inp,
+        "output": out,
+        "cacheRead": cache_read,
+        "cacheWrite": cache_write,
+        "reasoning": reasoning,
+        "totalTokens": inp + out + cache_read + cache_write,
+        "cost": {"total": cost},
+    }
+    return json.dumps(
+        {"type": "turn_end", "message": {"role": "assistant", "usage": usage, "stopReason": "stop"}, "toolResults": []}
+    )
+
+
+def _tool_start(call_id: str, name: str, args: dict[str, Any]) -> str:
+    return json.dumps({"type": "tool_execution_start", "toolCallId": call_id, "toolName": name, "args": args})
+
+
+def _tool_end(call_id: str, name: str, text: str, *, is_error: bool = False) -> str:
+    return json.dumps(
+        {
+            "type": "tool_execution_end",
+            "toolCallId": call_id,
+            "toolName": name,
+            "result": {"content": [{"type": "text", "text": text}]},
+            "isError": is_error,
+        }
+    )
+
+
+class _FakeProcess:
+    def __init__(self, lines: list[str], returncode: int = 0, stderr: bytes = b"") -> None:
+        self._lines = [f"{line}\n".encode() for line in lines]
+        self.returncode: int | None = None
+        self._final_returncode = returncode
+        self._stderr = stderr
+        self.pid = 4242
+        self.terminated = False
+        self.killed = False
+        self.stdout = self
+
+    async def readline(self) -> bytes:
+        if self._lines:
+            return self._lines.pop(0)
+        self.returncode = self._final_returncode
+        return b""
+
+    async def read(self) -> bytes:
+        return self._stderr
+
+    async def wait(self) -> int:
+        self.returncode = self._final_returncode
+        return self.returncode
+
+    def terminate(self) -> None:
+        self.terminated = True
+        self.returncode = self._final_returncode
+
+    def kill(self) -> None:
+        self.killed = True
+        self.returncode = self._final_returncode
+
+
+class _RunningProcess(_FakeProcess):
+    """A process that stays alive until it is explicitly terminated or killed."""
+
+    def __init__(self, lines: list[str], **kwargs: Any) -> None:
+        super().__init__(lines, **kwargs)
+        self._exited = asyncio.Event()
+
+    async def wait(self) -> int:
+        await self._exited.wait()
+        self.returncode = self._final_returncode
+        return self.returncode
+
+    def terminate(self) -> None:
+        self.terminated = True
+        self._exited.set()
+
+    def kill(self) -> None:
+        self.killed = True
+        self._exited.set()
+
+
+class _ExplodingRunningProcess(_RunningProcess):
+    """Raises from ``readline`` mid-stream AND stays alive, like the real CLI.
+
+    ``_ExplodingProcess`` inherits the plain fake's ``wait()``, which reports an
+    exit code the instant it is awaited — so it can never model the case that
+    matters for teardown: the read loop dying while the CLI is still streaming.
+    """
+
+    async def readline(self) -> bytes:
+        if self._lines:
+            return self._lines.pop(0)
+        raise ValueError("Separator is not found, and chunk exceed the limit")
+
+
+@pytest.fixture
+def patch_exec(monkeypatch: pytest.MonkeyPatch):
+    """Patch subprocess spawn; return a dict capturing the argv used."""
+    captured: dict[str, Any] = {"killpg": []}
+
+    def _install(proc: _FakeProcess) -> dict[str, Any]:
+        async def fake_exec(*argv: str, **kwargs: Any) -> _FakeProcess:
+            captured["argv"] = list(argv)
+            captured["kwargs"] = kwargs
+            proc.stderr = proc  # type: ignore[assignment]
+            return proc
+
+        monkeypatch.setattr(asyncio, "create_subprocess_exec", fake_exec)
+        monkeypatch.setattr("shutil.which", lambda _name: "/usr/local/bin/pi")
+        monkeypatch.setattr(os, "killpg", lambda pgid, sig: captured["killpg"].append((pgid, sig)), raising=False)
+        return captured
+
+    return _install
+
+
+async def _run(agent: PiAgent, tmp_path: Any, prompt: str = "do the thing", **kwargs: Any):
+    await agent.start(str(tmp_path))
+    return await agent.communicate(prompt, **kwargs)
+
+
+def _agent(**overrides: Any) -> PiAgent:
+    config = PiAgentConfig(type="pi", **{"model": "openrouter/moonshotai/kimi-k3", **overrides})
+    return PiAgent(config, task_id="t1")
+
+
+class _EventRecorder:
+    def __init__(self) -> None:
+        self.events: list[Any] = []
+
+    def on_event(self, event: Any) -> None:
+        self.events.append(event)
+
+
+class TestHappyPath:
+    async def test_builds_turn_record(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+
+        assert record.crashed is False
+        # 3 turn_start steps in the fixture (write, read, summarize).
+        assert record.assistant_turn_count == 3
+        assert record.model_used == "openrouter/moonshotai/kimi-k3"
+        assert "hi" in record.agent_output
+
+    async def test_token_buckets_sum_across_turns(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+
+        usage = record.token_usage
+        assert usage is not None
+        assert usage.uncached_input_tokens == EXPECTED_INPUT
+        assert usage.output_tokens == EXPECTED_OUTPUT
+        assert usage.cache_read_input_tokens == EXPECTED_CACHE_READ
+        assert usage.cache_creation_input_tokens == 0
+        assert usage.total_cost_usd == pytest.approx(EXPECTED_COST)
+
+    async def test_reconciliation_invariant(self, patch_exec, tmp_path):
+        """Summing the four buckets across messages must equal token_usage exactly."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+
+        usage = record.token_usage
+        assert usage is not None
+        assert sum(m.input_tokens for m in record.messages) == usage.uncached_input_tokens
+        assert sum(m.output_tokens for m in record.messages) == usage.output_tokens
+        assert sum(m.cache_read_tokens for m in record.messages) == usage.cache_read_input_tokens
+
+    async def test_tool_calls_captured(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+
+        # write + read, normalized to the canonical vocabulary.
+        assert [c.tool_name for c in record.commands] == ["Write", "Read"]
+        write = record.commands[0]
+        assert write.tool_id == "write:0"
+        assert write.result_status == "success"
+        # `path` renamed to Claude's `file_path`.
+        assert write.parameters == {"file_path": "hello.txt", "content": "hi"}
+        assert write.result_summary == "Successfully wrote 2 bytes to hello.txt"
+
+    async def test_messages_attributed_to_turns(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+
+        assistants = [m for m in record.messages if isinstance(m, AssistantMessage)]
+        assert len(assistants) == 3
+        assert assistants[0].tool_use_ids == ["write:0"]
+        assert assistants[1].tool_use_ids == ["read:1"]
+        assert assistants[2].tool_use_ids == []  # final summary turn
+
+    async def test_event_order_is_balanced(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        recorder = _EventRecorder()
+        await _run(_agent(), tmp_path, stream_callback=recorder)
+
+        seen = recorder.events
+        assert len([e for e in seen if isinstance(e, AgentStartEvent)]) == 1
+        assert len([e for e in seen if isinstance(e, AgentEndEvent)]) == 1
+        starts = len([e for e in seen if isinstance(e, TurnStartEvent)])
+        ends = len([e for e in seen if isinstance(e, TurnEndEvent)])
+        assert starts == ends == 3
+        tstarts = len([e for e in seen if isinstance(e, ToolStartEvent)])
+        tends = len([e for e in seen if isinstance(e, ToolEndEvent)])
+        assert tstarts == tends == 2
+
+
+class TestResultTextFlatten:
+    def test_flattens_content_list(self):
+        assert _result_text({"content": [{"type": "text", "text": "a"}, {"type": "text", "text": "b"}]}) == "ab"
+
+    def test_none_stays_none(self):
+        assert _result_text(None) is None
+
+    def test_other_shapes_stringify(self):
+        assert _result_text(42) == "42"
+
+
+class TestToolNormalization:
+    async def test_bash_maps_to_canonical(self, patch_exec, tmp_path):
+        stream = [
+            _turn_start(),
+            _tool_start("bash:0", "bash", {"command": "pytest -q"}),
+            _tool_end("bash:0", "bash", "ok"),
+            _turn_end(inp=10, out=5),
+            json.dumps({"type": "agent_settled"}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.commands[0].tool_name == "Bash"
+        assert record.commands[0].parameters == {"command": "pytest -q"}
+
+    async def test_find_maps_to_glob(self, patch_exec, tmp_path):
+        # Pi's search-by-pattern tool is `find` (not `glob`); it must normalize to
+        # the canonical `Glob` so command_executed / commands_efficiency criteria
+        # written against `Glob` score on a Pi run that searched.
+        stream = [
+            _turn_start(),
+            _tool_start("f:0", "find", {"pattern": "**/*.py"}),
+            _tool_end("f:0", "find", "ok"),
+            _turn_end(inp=10, out=5),
+            json.dumps({"type": "agent_settled"}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.commands[0].tool_name == "Glob"
+
+    async def test_unknown_tool_passes_through(self, patch_exec, tmp_path):
+        stream = [
+            _turn_start(),
+            _tool_start("x:0", "some_new_tool", {"whatever": 1}),
+            _tool_end("x:0", "some_new_tool", "ok"),
+            _turn_end(inp=10, out=5),
+        ]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.commands[0].tool_name == "some_new_tool"
+        assert record.commands[0].parameters == {"whatever": 1}
+
+    async def test_edit_arg_keys_map_to_canonical(self, patch_exec, tmp_path):
+        stream = [
+            _turn_start(),
+            _tool_start("e:0", "edit", {"path": "a.py", "oldString": "a", "newString": "b", "replaceAll": True}),
+            _tool_end("e:0", "edit", "ok"),
+            _turn_end(inp=10, out=5),
+        ]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.commands[0].parameters == {
+            "file_path": "a.py",
+            "old_string": "a",
+            "new_string": "b",
+            "replace_all": True,
+        }
+
+
+class TestArgvConstruction:
+    async def test_base_flags_and_prompt(self, patch_exec, tmp_path):
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path)
+
+        argv = captured["argv"]
+        assert argv[:6] == ["pi", "-p", "--mode", "json", "--no-context-files", "--no-approve"]
+        assert argv[argv.index("--model") + 1] == "openrouter/moonshotai/kimi-k3"
+        assert argv[argv.index("--thinking") + 1] == "medium"
+        assert "--session-dir" in argv and "--session-id" in argv
+        assert "--no-session" not in argv
+        assert argv[-2] == "--"
+        assert argv[-1] == "do the thing"
+
+    async def test_tools_are_not_forwarded_but_system_prompt_is(self, patch_exec, tmp_path):
+        """allowed_tools/disallowed_tools are NOT forwarded: the shared config default
+        sets Claude-namespaced tool names (Bash/Read/...) that do not exist in Pi
+        (lowercase bash/read/...), so `--tools` would strip the agent of ALL tools.
+        Only `system_prompt` (a free-text string with no namespace) is forwarded."""
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(
+            _agent(allowed_tools=["Read", "Write"], disallowed_tools=["Bash"], system_prompt="be terse"),
+            tmp_path,
+        )
+        argv = captured["argv"]
+        assert "--tools" not in argv
+        assert "--exclude-tools" not in argv
+        assert argv[argv.index("--append-system-prompt") + 1] == "be terse"
+
+    async def test_user_input_is_a_post_dashdash_argv_element(self, patch_exec, tmp_path):
+        """Shell-safety: the prompt is never interpolated into a shell string."""
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path, prompt="rm -rf / ; echo $(whoami)")
+        argv = captured["argv"]
+        assert argv[-1] == "rm -rf / ; echo $(whoami)"
+        assert argv[argv.index("--") - 1] != "rm -rf / ; echo $(whoami)"
+
+    async def test_explicit_line_limit_is_passed(self, patch_exec, tmp_path):
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path)
+        assert captured["kwargs"]["limit"] > 64 * 1024
+
+
+class TestSessionContinuity:
+    async def test_successive_calls_reuse_the_same_session(self, patch_exec, tmp_path):
+        """Multi-turn / simulation stitching: both invocations carry the SAME id+dir."""
+        captured1 = patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        await _run(agent, tmp_path)
+        argv1 = captured1["argv"]
+        sid1 = argv1[argv1.index("--session-id") + 1]
+        sdir1 = argv1[argv1.index("--session-dir") + 1]
+
+        captured2 = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await agent.communicate("follow up")
+        argv2 = captured2["argv"]
+        assert argv2[argv2.index("--session-id") + 1] == sid1
+        assert argv2[argv2.index("--session-dir") + 1] == sdir1
+
+    async def test_start_creates_and_stop_removes_the_session_dir(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        await agent.start(str(tmp_path))
+        session_dir = agent._session_dir
+        assert session_dir is not None and Path(session_dir).is_dir()
+
+        await agent.stop()
+        assert not Path(session_dir).exists()
+        assert agent._session_dir is None
+
+    async def test_restart_does_not_leak_the_prior_session_dir(self, patch_exec, tmp_path):
+        """Re-starting the same agent instance must remove the previous tempdir."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        await agent.start(str(tmp_path))
+        first = agent._session_dir
+        assert first is not None and Path(first).is_dir()
+
+        await agent.start(str(tmp_path))
+        second = agent._session_dir
+        assert second is not None and second != first
+        assert not Path(first).exists()  # the first dir was cleaned up, not leaked
+        await agent.stop()
+
+
+class TestEnvironmentInfo:
+    def test_carries_semantics_and_pi_fields(self):
+        info = _agent(thinking_level="high").get_environment_info()
+        assert info["system_prompt_semantics"] == "append"
+        assert info["pi_model"] == "openrouter/moonshotai/kimi-k3"
+        assert info["pi_thinking_level"] == "high"
+
+    async def test_session_id_recorded_after_start(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        assert "pi_session_id" not in agent.get_environment_info()
+        await agent.start(str(tmp_path))
+        assert agent.get_environment_info()["pi_session_id"].startswith("coder-eval-t1-")
+
+    async def test_dataset_row_task_id_is_sanitized_in_session_id(self, patch_exec, tmp_path):
+        # Dataset-row tasks have path-shaped ids ("suite/row_1"); pi derives its
+        # session file from --session-id under --session-dir, so a raw '/' would
+        # resolve to a non-existent subdir and fail the row. The id must carry no
+        # path separator.
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        config = PiAgentConfig(type="pi", model="openrouter/moonshotai/kimi-k3")
+        agent = PiAgent(config, task_id="suite/row_1")
+        await _run(agent, tmp_path)
+        sid = captured["argv"][captured["argv"].index("--session-id") + 1]
+        assert "/" not in sid and "\\" not in sid
+        assert sid.startswith("coder-eval-suite_row_1-")
+
+
+class TestSandboxEnvironment:
+    async def test_prepends_mock_dirs_ahead_of_the_inherited_path(self, patch_exec, tmp_path, monkeypatch):
+        monkeypatch.setenv("PATH", "/parent/bin")
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        await agent.start(str(tmp_path), env_path_prepend=["/sandbox/mocks", "/sandbox/bins"])
+        await agent.communicate("do the thing")
+
+        assert captured["kwargs"]["env"]["PATH"] == os.pathsep.join(["/sandbox/mocks", "/sandbox/bins", "/parent/bin"])
+
+    async def test_host_environment_is_inherited_whole(self, patch_exec, tmp_path, monkeypatch):
+        monkeypatch.setenv("OPENROUTER_API_KEY", "sk-test")
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path)
+        assert captured["kwargs"]["env"]["OPENROUTER_API_KEY"] == "sk-test"
+
+
+class TestUnsupportedConfigIsAnnounced:
+    async def test_start_warns_about_unenforced_fields(self, patch_exec, tmp_path, caplog):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        with caplog.at_level("WARNING"):
+            await _agent(permission_mode="plan").start(str(tmp_path))
+        assert "permission_mode" in caplog.text
+        assert "NOT enforced" in caplog.text
+
+    async def test_plugins_that_do_not_resolve_warn_loudly(self, patch_exec, tmp_path, caplog):
+        """plugins IS supported now (-> --skill), but a path that resolves to no skills
+        must warn — else the run silently measures the model WITHOUT the skill."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        with caplog.at_level("WARNING"):
+            await _agent(plugins=[{"type": "local", "path": "/no/such/dir"}]).start(str(tmp_path))
+        assert "0 skill dir(s) resolved" in caplog.text or "did not resolve" in caplog.text
+        # plugins is no longer named in the "NOT enforced" warning.
+        assert "plugins" not in "".join(r.message for r in caplog.records if "NOT enforced" in r.message)
+
+    async def test_unenforced_fields_warn_but_system_prompt_does_not(self, patch_exec, tmp_path, caplog):
+        """allowed_tools/disallowed_tools are unenforced (Claude-namespaced default cannot
+        map to Pi's lowercase toolset) and MUST warn when set. `system_prompt` IS enforced
+        (--append-system-prompt) and must never appear in the unenforced-fields warning."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        with caplog.at_level("WARNING"):
+            await _agent(allowed_tools=["Read"], disallowed_tools=["Bash"], system_prompt="be terse").start(
+                str(tmp_path)
+            )
+        warning = "".join(r.message for r in caplog.records if "NOT enforced" in r.message)
+        assert "allowed_tools" in warning
+        assert "disallowed_tools" in warning
+        assert "system_prompt" not in warning  # the enforced field is never named
+
+
+class TestAutoRetry:
+    async def test_two_agent_cycles_reduce_to_one_agent_end(self, patch_exec, tmp_path):
+        """Pi retries a transient error internally: agent_end(willRetry:true) then a
+        clean second cycle then agent_settled. The reducer must finalize ONCE."""
+        stream = [
+            json.dumps({"type": "agent_start"}),
+            _turn_start(),
+            _turn_end(inp=100, out=10, cost=0.001),
+            json.dumps({"type": "agent_end", "messages": [], "willRetry": True}),
+            json.dumps({"type": "agent_start"}),
+            _turn_start(),
+            _tool_start("w:0", "write", {"path": "a.txt", "content": "x"}),
+            _tool_end("w:0", "write", "ok"),
+            _turn_end(inp=200, out=20, cost=0.002),
+            json.dumps({"type": "agent_end", "messages": [], "willRetry": False}),
+            json.dumps({"type": "agent_settled"}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        recorder = _EventRecorder()
+        record = await _run(_agent(), tmp_path, stream_callback=recorder)
+
+        assert record.crashed is False
+        assert len([e for e in recorder.events if isinstance(e, AgentEndEvent)]) == 1
+        # Both cycles' usage merged (SUM): input 100+200, output 10+20.
+        assert record.token_usage is not None
+        assert record.token_usage.uncached_input_tokens == 300
+        assert record.token_usage.output_tokens == 30
+        assert record.assistant_turn_count == 2
+
+
+class TestCooperativeStop:
+    def test_capability_flag_is_declared(self):
+        assert PiAgent.supports_cooperative_stop is True
+
+    async def test_should_stop_ends_turn_cleanly(self, patch_exec, tmp_path):
+        proc = _RunningProcess(HAPPY_STREAM)
+        patch_exec(proc)
+        record = await _run(_agent(), tmp_path, should_stop=lambda: True)
+
+        assert record.crashed is False
+        assert proc.terminated is True
+        # should_stop() is True from the first check, which lands after the first
+        # streamed line (the `session` header) and before any turn completes — so
+        # the cut is at turn 0, not merely "fewer than the full 3".
+        assert record.assistant_turn_count == 0
+
+    async def test_partial_record_is_returned_not_raised(self, patch_exec, tmp_path):
+        proc = _RunningProcess(HAPPY_STREAM)
+        patch_exec(proc)
+        record = await _run(_agent(), tmp_path, should_stop=lambda: True)
+        assert isinstance(record.assistant_turn_count, int)
+
+
+class TestMaxTurns:
+    async def test_max_turns_marks_exhausted(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path, max_turns=1)
+        assert record.max_turns_exhausted is True
+
+    async def test_a_cap_the_run_stays_under_is_not_exhausted(self, patch_exec, tmp_path):
+        """The fixture is exactly 3 turns, so max_turns=3 is the boundary."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path, max_turns=3)
+        assert record.max_turns_exhausted is False
+        assert record.assistant_turn_count == 3
+
+    async def test_the_deciding_turn_is_kept_whole(self, patch_exec, tmp_path):
+        """max_turns=1 cuts at the START of turn 2, so turn 1 survives complete."""
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path, max_turns=1)
+
+        assert record.max_turns_exhausted is True
+        assert len(record.commands) == 1  # turn 1's write
+        usage = record.token_usage
+        assert usage is not None
+        assert usage.uncached_input_tokens == 406  # turn 1's input exactly
+        assert usage.output_tokens == 77  # 69 + 8 reasoning
+
+    async def test_no_cap_is_uncapped(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        record = await _run(_agent(), tmp_path)
+        assert record.max_turns_exhausted is False
+        assert record.assistant_turn_count == 3
+
+
+class _HangingProcess(_FakeProcess):
+    def __init__(self, lines: list[str], **kwargs: Any) -> None:
+        super().__init__(lines, **kwargs)
+        self._exited = asyncio.Event()
+
+    async def readline(self) -> bytes:
+        if self._lines:
+            return self._lines.pop(0)
+        await self._exited.wait()
+        return b""
+
+    async def read(self) -> bytes:
+        await self._exited.wait()
+        return self._stderr
+
+    async def wait(self) -> int:
+        await self._exited.wait()
+        self.returncode = self._final_returncode
+        return self.returncode
+
+    def terminate(self) -> None:
+        self.terminated = True
+        self._exited.set()
+
+    def kill(self) -> None:
+        self.killed = True
+        self._exited.set()
+
+
+class TestTimeoutContract:
+    async def test_deadline_raises_turn_timeout_with_partial_parked(self, patch_exec, tmp_path):
+        proc = _HangingProcess([_turn_start()])
+        patch_exec(proc)
+        agent = _agent()
+        recorder = _EventRecorder()
+
+        with pytest.raises(TurnTimeoutError):
+            await _run(agent, tmp_path, timeout=0.2, stream_callback=recorder)
+
+        partial = agent.pending_turn
+        assert partial is not None
+        assert partial.crashed is True
+        assert proc.terminated is True
+        ends = [e for e in recorder.events if isinstance(e, AgentEndEvent)]
+        assert len(ends) == 1
+        assert ends[0].status is AgentEndStatus.TIMEOUT
+
+        await agent.discard_pending_turn()
+        assert agent._iteration == 0
+
+
+class _ExplodingProcess(_FakeProcess):
+    async def readline(self) -> bytes:
+        if self._lines:
+            return self._lines.pop(0)
+        raise ValueError("Separator is not found, and chunk exceed the limit")
+
+
+class TestFailurePaths:
+    async def test_nonzero_exit_crashes(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess([], returncode=1, stderr=b"boom: bad model"))
+        with pytest.raises(AgentCrashError, match="boom: bad model"):
+            await _run(_agent(), tmp_path)
+
+    async def test_empty_clean_exit_crashes_on_no_recognized_events(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess([], returncode=0))
+        with pytest.raises(AgentCrashError, match="no recognized events"):
+            await _run(_agent(), tmp_path)
+
+    async def test_drift_crash_names_the_unrecognized_types(self, patch_exec, tmp_path):
+        """A clean exit whose events are all unrecognized (schema drift) crashes and
+        names what it saw, for diagnosis."""
+        stream = [
+            json.dumps({"type": "some.new.event", "foo": 1}),
+            json.dumps({"type": "another.unknown", "bar": 2}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        with pytest.raises(AgentCrashError, match=r"another\.unknown, some\.new\.event") as exc:
+            await _run(_agent(), tmp_path)
+        assert "no recognized events" in str(exc.value)
+
+    async def test_stream_error_becomes_a_crash_with_partial_parked(self, patch_exec, tmp_path):
+        stream = [_turn_start(), _tool_start("w:0", "write", {"path": "a.txt", "content": "x"})]
+        patch_exec(_ExplodingProcess(stream))
+        agent = _agent()
+
+        with pytest.raises(AgentCrashError, match="Pi turn failed"):
+            await _run(agent, tmp_path)
+
+        partial = agent.pending_turn
+        assert partial is not None
+        assert partial.crashed is True
+        # The in-flight tool was force-closed rather than dropped.
+        assert [c.result_status for c in partial.commands] == ["unknown"]
+
+    async def test_spawn_failure_becomes_a_crash(self, monkeypatch, tmp_path):
+        async def boom(*_argv: str, **_kwargs: Any):
+            raise OSError("no fork for you")
+
+        monkeypatch.setattr(asyncio, "create_subprocess_exec", boom)
+        monkeypatch.setattr("shutil.which", lambda _name: "/usr/local/bin/pi")
+
+        with pytest.raises(AgentCrashError, match="no fork for you"):
+            await _run(_agent(), tmp_path)
+
+    async def test_malformed_line_is_skipped(self, patch_exec, tmp_path):
+        stream = ["not json at all", *HAPPY_STREAM]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.crashed is False
+        assert record.assistant_turn_count == 3
+
+    async def test_missing_cli_is_actionable(self, monkeypatch, tmp_path):
+        monkeypatch.setattr("shutil.which", lambda _name: None)
+        with pytest.raises(RuntimeError, match="@earendil-works/pi-coding-agent"):
+            await _agent().start(str(tmp_path))
+
+
+class TestUnexpectedErrorContract:
+    async def test_terminal_event_emitted_exactly_once_on_crash(self, patch_exec, tmp_path):
+        patch_exec(_ExplodingProcess([_turn_start()]))
+        recorder = _EventRecorder()
+
+        with pytest.raises(AgentCrashError):
+            await _run(_agent(), tmp_path, stream_callback=recorder)
+
+        ends = [e for e in recorder.events if isinstance(e, AgentEndEvent)]
+        assert len(ends) == 1
+        assert ends[0].crashed is True
+        assert ends[0].status is AgentEndStatus.CRASHED
+
+    async def test_iteration_rolls_back_after_the_crash(self, patch_exec, tmp_path):
+        patch_exec(_ExplodingProcess([]))
+        agent = _agent()
+
+        with pytest.raises(AgentCrashError):
+            await _run(agent, tmp_path)
+        assert agent._iteration == 1
+        await agent.discard_pending_turn()
+        assert agent._iteration == 0
+        assert agent.pending_turn is None
+
+
+class TestTurnEventsAreBalanced:
+    @staticmethod
+    def _pairs(recorder: _EventRecorder) -> tuple[int, int]:
+        starts = len([e for e in recorder.events if isinstance(e, TurnStartEvent)])
+        ends = len([e for e in recorder.events if isinstance(e, TurnEndEvent)])
+        return starts, ends
+
+    async def test_a_clean_turn_is_balanced(self, patch_exec, tmp_path):
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        recorder = _EventRecorder()
+        await _run(_agent(), tmp_path, stream_callback=recorder)
+        assert self._pairs(recorder) == (3, 3)
+
+    async def test_a_timeout_closes_the_open_turn(self, patch_exec, tmp_path):
+        proc = _HangingProcess([_turn_start()])
+        patch_exec(proc)
+        recorder = _EventRecorder()
+
+        with pytest.raises(TurnTimeoutError):
+            await _run(_agent(), tmp_path, timeout=0.2, stream_callback=recorder)
+
+        assert self._pairs(recorder) == (1, 1)
+        end = next(e for e in recorder.events if isinstance(e, TurnEndEvent))
+        assert end.status is TurnEndStatus.TIMEOUT
+
+
+class TestFactoryContract:
+    def test_route_accepted_positionally_and_by_keyword(self):
+        config = PiAgentConfig(type="pi", model="openrouter/moonshotai/kimi-k3")
+        assert PiAgent(config, route=None).route is None
+        assert PiAgent(config, None).route is None
+
+    def test_undeclared_kwarg_raises(self):
+        config = PiAgentConfig(type="pi", model="openrouter/moonshotai/kimi-k3")
+        assert PiAgent.supports_cost_log_tags is False
+        with pytest.raises(TypeError):
+            PiAgent(config, cost_log_tags={"x": "y"})  # type: ignore[call-arg]
+
+
+class TestRegistry:
+    def test_create_agent_returns_pi_agent(self):
+        from coder_eval.agents import AgentRegistry, create_agent, register_builtins
+
+        register_builtins(AgentRegistry)
+        agent = create_agent(AgentKind.PI, PiAgentConfig(type="pi"))
+        assert isinstance(agent, PiAgent)
+
+    def test_list_kinds_includes_pi(self):
+        from coder_eval.agents import AgentRegistry, register_builtins
+
+        register_builtins(AgentRegistry)
+        assert "pi" in AgentRegistry.list_kinds()
+
+    def test_parse_agent_config_dispatches_to_pi(self):
+        from coder_eval.models import parse_agent_config
+
+        cfg = parse_agent_config(type="pi", model="openrouter/moonshotai/kimi-k3")
+        assert isinstance(cfg, PiAgentConfig)
+        assert cfg.model == "openrouter/moonshotai/kimi-k3"
+
+
+@pytest.mark.skipif(os.name != "posix", reason="process-group teardown is POSIX-only by design")
+class TestProcessGroupTeardown:
+    async def test_spawn_uses_its_own_session(self, patch_exec, tmp_path):
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path)
+        assert captured["kwargs"]["start_new_session"] is (os.name == "posix")
+
+    async def test_stop_sweeps_the_spawned_group(self, patch_exec, tmp_path):
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        agent = _agent()
+        await _run(agent, tmp_path)
+        await agent.stop()
+        assert (4242, signal.SIGKILL) in captured["killpg"]
+
+    async def test_kill_sync_signals_pid_and_group(self, patch_exec, monkeypatch, tmp_path):
+        killed: list[tuple[int, int]] = []
+        monkeypatch.setattr(os, "kill", lambda pid, sig: killed.append((pid, sig)))
+        captured = patch_exec(_HangingProcess([]))
+        agent = _agent()
+        await agent.start(str(tmp_path))
+        proc = _HangingProcess([])
+        agent._process = proc  # type: ignore[assignment]
+        agent._spawned_pgids = [proc.pid]
+
+        agent.kill_sync()
+
+        assert (4242, signal.SIGKILL) in killed
+        assert (4242, signal.SIGKILL) in captured["killpg"]
+
+
+class TestToolFailureCapture:
+    async def test_tool_error_is_captured(self, patch_exec, tmp_path):
+        stream = [
+            _turn_start(),
+            _tool_start("b:0", "bash", {"command": "ls /root"}),
+            _tool_end("b:0", "bash", "boom: command exploded", is_error=True),
+            _turn_end(inp=10, out=5),
+        ]
+        patch_exec(_FakeProcess(stream))
+        recorder = _EventRecorder()
+        record = await _run(_agent(), tmp_path, stream_callback=recorder)
+
+        [cmd] = record.commands
+        assert cmd.result_status == "error"
+        assert cmd.error_message == "boom: command exploded"
+        [end] = [e for e in recorder.events if isinstance(e, ToolEndEvent)]
+        assert end.status is ToolEndStatus.ERROR
+
+    async def test_permission_denial_gets_its_own_status(self, patch_exec, tmp_path):
+        stream = [
+            _turn_start(),
+            _tool_start("b:0", "bash", {"command": "cat /etc/shadow"}),
+            _tool_end("b:0", "bash", "Permission denied by policy", is_error=True),
+            _turn_end(inp=10, out=5),
+        ]
+        patch_exec(_FakeProcess(stream))
+        recorder = _EventRecorder()
+        await _run(_agent(), tmp_path, stream_callback=recorder)
+        [end] = [e for e in recorder.events if isinstance(e, ToolEndEvent)]
+        assert end.status is ToolEndStatus.PERMISSION_DENIED
+
+    def test_orphan_result_is_never_dropped(self):
+        state = _PiTurnState(task_id="t", iteration=1, user_input="x", model=None)
+        events: list[Any] = []
+        state.bind(events.append)
+        state._close_tool("ghost", status=ToolEndStatus.UNRESOLVED, summary=None, error="no result observed")
+
+        [event] = events
+        assert isinstance(event, ToolEndEvent)
+        assert event.tool.tool_name == "unknown"
+        assert event.tool.result_status == "unknown"
+
+
+class TestZeroUsageTurn:
+    async def test_zero_usage_turn_is_scored_not_crashed(self, patch_exec, tmp_path):
+        """A provider reporting no usage yields an all-zero token_usage; Pi scores
+        it (no require_token_telemetry hard-fail) since its multi-provider surface
+        makes that brittle."""
+        stream = [
+            _turn_start(),
+            _turn_end(inp=0, out=0),
+            json.dumps({"type": "agent_settled"}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.crashed is False
+
+
+# --- review fixes: token-drift warn (#1), dangling-turn close (#2), error capture (#3) ---
+
+
+def _turn_end_error(msg: str = "404: blocked by guardrail") -> str:
+    """A `turn_end` whose provider errored (the willRetry / terminal-failure shape)."""
+    return json.dumps(
+        {
+            "type": "turn_end",
+            "message": {
+                "role": "assistant",
+                "usage": {"input": 5, "output": 2, "totalTokens": 7, "cost": {"total": 0.0}},
+                "stopReason": "error",
+                "errorMessage": msg,
+            },
+            "toolResults": [],
+        }
+    )
+
+
+class TestTurnLifecycleAndTokenTelemetry:
+    """Turn open/close balance, terminal-error surfacing, and the token-shape
+    guards that keep a CLI-schema drift from silently zeroing tokens/cost."""
+
+    async def test_dangling_turn_start_is_closed_on_next_turn_start(self, patch_exec, tmp_path):
+        """#2: a turn_start with no turn_end (a mid-turn retry abort) must be closed
+        when the next turn_start arrives, so TurnStart/TurnEnd stay balanced."""
+        stream = [
+            _turn_start(),  # turn 1 opens, then aborts mid-generation (no turn_end)
+            _turn_start(),  # turn 2 opens -> must close turn 1 first
+            _turn_end(inp=10, out=5),  # turn 2 ends cleanly
+            json.dumps({"type": "agent_settled"}),
+        ]
+        patch_exec(_FakeProcess(stream))
+        recorder = _EventRecorder()
+        await _run(_agent(), tmp_path, stream_callback=recorder)
+        starts = [e for e in recorder.events if isinstance(e, TurnStartEvent)]
+        ends = [e for e in recorder.events if isinstance(e, TurnEndEvent)]
+        assert len(starts) == len(ends) == 2  # balanced despite the aborted turn
+
+    async def test_terminal_error_crashes_the_turn(self, patch_exec, tmp_path):
+        """A terminal provider error (stopReason=error that survived pi's internal
+        retries) crashes the turn so it books as ERROR (retryable / excluded from
+        outcomes), not a clean COMPLETED FAILURE. Mirrors opencode_agent."""
+        stream = [_turn_start(), _turn_end_error("404: blocked by guardrail"), json.dumps({"type": "agent_settled"})]
+        patch_exec(_FakeProcess(stream))
+        agent = _agent()
+        with pytest.raises(AgentCrashError, match="blocked by guardrail"):
+            await _run(agent, tmp_path)
+        partial = agent.pending_turn
+        assert partial is not None
+        assert partial.crashed is True
+
+    async def test_max_turns_cut_after_an_error_turn_finalizes_cleanly(self, patch_exec, tmp_path):
+        """A max_turns cut landing right after an error turn_end (pi still retrying,
+        so error_message is set but not yet cleared) must finalize as
+        max_turns_exhausted — NOT crash on the stale error. Guards the documented
+        'no crash, no retry' contract; without the intentional-cut gate the error
+        arm would fire on a clean budget exhaustion."""
+        # turn 1 errors; turn 2's turn_start trips max_turns=1 before any clean
+        # turn_end can clear error_message.
+        stream = [_turn_start(), _turn_end_error("transient 429"), _turn_start(), _turn_end(inp=1, out=1)]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path, max_turns=1)
+        assert record.max_turns_exhausted is True
+        assert record.crashed is False
+
+    def test_error_message_resets_on_a_recovered_turn(self):
+        """#3: an intermediate error a later cycle recovers from must not leak into the result."""
+        state = _PiTurnState(task_id="t", iteration=1, user_input="x", model="m")
+        state.on_turn_end(json.loads(_turn_end_error("transient")))
+        assert state.error_message == "transient"
+        state.on_turn_end(json.loads(_turn_end(inp=5, out=2)))  # a later, successful turn
+        assert state.error_message is None
+
+    async def test_bad_token_bucket_warns_once(self, patch_exec, tmp_path, caplog):
+        """#1: a bucket whose type drifted (here a dict) coerces to 0 but warns, once."""
+        bad = json.dumps(
+            {
+                "type": "turn_end",
+                "message": {
+                    "role": "assistant",
+                    "usage": {"input": {"nested": 1}, "output": 2, "cost": {"total": 0.0}},
+                    "stopReason": "stop",
+                },
+                "toolResults": [],
+            }
+        )
+        stream = [_turn_start(), bad, _turn_start(), bad, json.dumps({"type": "agent_settled"})]
+        patch_exec(_FakeProcess(stream))
+        with caplog.at_level("WARNING"):
+            await _run(_agent(), tmp_path)
+        warns = [r for r in caplog.records if "unexpected token accounting" in r.getMessage()]
+        assert len(warns) == 1  # warn-once, not once per bucket/step
+
+    async def test_missing_usage_object_warns(self, patch_exec, tmp_path, caplog):
+        """#1: a completed turn_end with no `usage` object at all (a rename) warns."""
+        no_usage = json.dumps(
+            {"type": "turn_end", "message": {"role": "assistant", "stopReason": "stop"}, "toolResults": []}
+        )
+        stream = [_turn_start(), no_usage, json.dumps({"type": "agent_settled"})]
+        patch_exec(_FakeProcess(stream))
+        with caplog.at_level("WARNING"):
+            await _run(_agent(), tmp_path)
+        assert any("no usage object" in r.getMessage() for r in caplog.records)
+
+    async def test_all_zero_usage_object_warns(self, patch_exec, tmp_path, caplog):
+        """A turn_end that DID carry a usage object but whose every bucket is 0 (the
+        rename-each-key-to-0 drift shape) warns once — otherwise tokens and cost
+        silently vanish and max_usd / max_total_tokens go blind."""
+        zero = json.dumps(
+            {
+                "type": "turn_end",
+                "message": {
+                    "role": "assistant",
+                    "usage": {"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0},
+                    "stopReason": "stop",
+                },
+                "toolResults": [],
+            }
+        )
+        stream = [_turn_start(), zero, json.dumps({"type": "agent_settled"})]
+        patch_exec(_FakeProcess(stream))
+        with caplog.at_level("WARNING"):
+            record = await _run(_agent(), tmp_path)
+        assert record.crashed is False  # score, don't crash (documented Pi policy)
+        assert any("all-zero token buckets" in r.getMessage() for r in caplog.records)
+
+    async def test_total_tokens_mismatch_warns(self, patch_exec, tmp_path, caplog):
+        """The stream's own totalTokens must reconcile with input+output+cacheRead+
+        cacheWrite; a mismatch (a bucket renamed/moved under a CLI upgrade) warns
+        once instead of silently mis-booking tokens/cost."""
+        bad = json.dumps(
+            {
+                "type": "turn_end",
+                "message": {
+                    "role": "assistant",
+                    # buckets sum to 15, but the stream claims 999 — schema drift.
+                    "usage": {"input": 10, "output": 5, "cacheRead": 0, "cacheWrite": 0, "totalTokens": 999},
+                    "stopReason": "stop",
+                },
+                "toolResults": [],
+            }
+        )
+        stream = [_turn_start(), bad, json.dumps({"type": "agent_settled"})]
+        patch_exec(_FakeProcess(stream))
+        with caplog.at_level("WARNING"):
+            record = await _run(_agent(), tmp_path)
+        assert record.crashed is False
+        assert any("does not reconcile" in r.getMessage() for r in caplog.records)
+
+
+class TestSkillInjection:
+    """agent.plugins -> `pi --skill <dir>` (mirrors OpenCode/Codex plugin->skills)."""
+
+    def _plugin_root(self, tmp_path):
+        # A Claude-plugin root: <root>/skills/<name>/SKILL.md (manifest-default layout).
+        root = tmp_path / "plug"
+        skill = root / "skills" / "demo-skill"
+        skill.mkdir(parents=True)
+        (skill / "SKILL.md").write_text("---\nname: demo-skill\ndescription: demo\n---\n# Demo\n")
+        return root
+
+    async def test_resolved_plugin_emits_skill_arg(self, patch_exec, tmp_path):
+        root = self._plugin_root(tmp_path)
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(plugins=[{"type": "local", "path": str(root)}]), tmp_path)
+        argv = captured["argv"]
+        assert "--skill" in argv
+        # Points at the skills-PARENT dir (Pi discovers <name>/SKILL.md recursively).
+        assert argv[argv.index("--skill") + 1] == str((root / "skills").resolve())
+
+    async def test_no_plugins_means_no_skill_arg(self, patch_exec, tmp_path):
+        captured = patch_exec(_FakeProcess(HAPPY_STREAM))
+        await _run(_agent(), tmp_path)
+        assert "--skill" not in captured["argv"]
+
+    async def test_skill_paths_recorded_in_environment_info(self, patch_exec, tmp_path):
+        # Installs the shutil.which("pi") patch so start() doesn't require the real
+        # CLI on PATH (CI has no pi binary); we only assert on recorded skill paths.
+        patch_exec(_FakeProcess(HAPPY_STREAM))
+        root = self._plugin_root(tmp_path)
+        agent = _agent(plugins=[{"type": "local", "path": str(root)}])
+        await agent.start(str(tmp_path))
+        assert agent.get_environment_info()["pi_skill_paths"] == [str((root / "skills").resolve())]
+
+
+class TestTurnAlwaysReapsTheCli:
+    """No exit from ``communicate()`` may leave the CLI running. ``AgentCrashError``
+    is categorized AGENT_CRASH (max_retries=2) and the orchestrator's attempt-failure
+    hook only drains ``pending_turn`` — it never kills the agent. An abandoned CLI
+    therefore means attempt 2 spawns a SECOND ``pi`` editing the very files the
+    criteria are about to score. The graceful ``kill()`` covers the intentional cuts
+    and the timeout; these pin the two paths that reach ``finally`` with a live child.
+    """
+
+    async def test_read_loop_crash_kills_the_cli(self, patch_exec, tmp_path):
+        """``_crash_turn`` is synchronous and raises — nothing below it reaps."""
+        proc = _ExplodingRunningProcess([_turn_start()])
+        patch_exec(proc)
+        with pytest.raises(AgentCrashError, match="Pi turn failed"):
+            await _run(_agent(), tmp_path)
+        assert proc.killed is True
+
+    async def test_external_cancel_kills_the_cli(self, patch_exec, tmp_path):
+        """Teardown must survive a CancelledError in flight (no await), or the child
+        outlives an interrupted turn."""
+        proc = _HangingProcess([_turn_start()])
+        patch_exec(proc)
+        agent = _agent()
+        await agent.start(str(tmp_path))
+        task = asyncio.ensure_future(agent.communicate("do the thing"))
+        await asyncio.sleep(0.05)  # let it spawn and read the first event
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            _ = await task  # the await re-raises the cancellation; no value ever exists
+        assert proc.killed is True
+
+    async def test_a_clean_turn_kills_nothing(self, patch_exec, tmp_path):
+        """The happy path is unchanged: the CLI exited, so the reaper is a no-op."""
+        proc = _FakeProcess(HAPPY_STREAM)
+        captured = patch_exec(proc)
+        await _run(_agent(), tmp_path)
+        assert proc.killed is False
+        assert captured["killpg"] == []
+
+
+class TestExternalCancel:
+    async def test_cancel_parks_partial_and_reraises(self, patch_exec, tmp_path):
+        """The watchdog's CancelledError must not swallow captured telemetry: the
+        partial is parked, the terminal event says CRASHED, and the cancellation
+        still propagates."""
+        proc = _HangingProcess([_turn_start()])
+        patch_exec(proc)
+        agent = _agent()
+        await agent.start(str(tmp_path))
+        recorder = _EventRecorder()
+        task = asyncio.ensure_future(agent.communicate("do the thing", stream_callback=recorder))
+        await asyncio.sleep(0.05)
+        task.cancel()
+        with pytest.raises(asyncio.CancelledError):
+            _ = await task  # the await re-raises the cancellation; no value ever exists
+        partial = agent.pending_turn
+        assert partial is not None
+        assert partial.crashed is True
+        ends = [e for e in recorder.events if isinstance(e, AgentEndEvent)]
+        assert len(ends) == 1
+        assert ends[0].status is AgentEndStatus.CRASHED
+        assert ends[0].crash_reason == "turn cancelled"
+        assert proc.killed is True  # not abandoned mid-stream — see TestTurnAlwaysReapsTheCli
+
+
+def _turn_end_no_cost(*, inp: int, out: int) -> str:
+    """A `turn_end` whose usage object omits the `cost` key (provider/auth mode that
+    reports no cost) — so `_resolve_cost` must fall back to the rate card."""
+    return json.dumps(
+        {
+            "type": "turn_end",
+            "message": {
+                "role": "assistant",
+                "usage": {"input": inp, "output": out, "totalTokens": inp + out},
+                "stopReason": "stop",
+            },
+            "toolResults": [],
+        }
+    )
+
+
+class TestCostFallsBackToTheRateCard:
+    _SETTLED = json.dumps({"type": "agent_settled"})
+
+    async def test_stream_cost_wins_when_reported(self, patch_exec, tmp_path):
+        """The provider's own accounting beats a static headline rate."""
+        stream = [_turn_start(), _turn_end(inp=1000, out=500, cost=0.5), self._SETTLED]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        assert record.token_usage is not None
+        assert record.token_usage.total_cost_usd == pytest.approx(0.5)
+
+    async def test_missing_cost_is_priced_from_the_rate_card(self, patch_exec, tmp_path):
+        """No `cost` key at all — without the fallback the turn books tokens with no money."""
+        stream = [_turn_start(), _turn_end_no_cost(inp=1000, out=500), self._SETTLED]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(), tmp_path)
+        expected = calculate_cost("openrouter/moonshotai/kimi-k3", uncached_input_tokens=1000, output_tokens=500)
+        assert expected is not None and expected > 0
+        assert record.token_usage is not None
+        assert record.token_usage.total_cost_usd == pytest.approx(expected)
+
+    async def test_unpriced_model_reports_no_cost(self, patch_exec, tmp_path):
+        """`None` (not 0.0) so "unpriceable" stays distinct from "ran for free"."""
+        stream = [_turn_start(), _turn_end_no_cost(inp=10, out=5), self._SETTLED]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(model="nowhere/not-a-real-model"), tmp_path)
+        assert record.token_usage is not None
+        assert record.token_usage.total_cost_usd is None
+
+    async def test_zero_reported_cost_on_a_priced_model_uses_the_rate_card(self, patch_exec, tmp_path, caplog):
+        """A reported $0 on a model the rate card prices is a subscription/registry
+        gap, not a free run — latching on it would book real tokens with no money."""
+        stream = [_turn_start(), _turn_end(inp=1000, out=500, cost=0.0), self._SETTLED]
+        patch_exec(_FakeProcess(stream))
+        with caplog.at_level("DEBUG"):
+            record = await _run(_agent(), tmp_path)
+        expected = calculate_cost("openrouter/moonshotai/kimi-k3", uncached_input_tokens=1000, output_tokens=500)
+        assert expected is not None and expected > 0
+        assert record.token_usage is not None
+        assert record.token_usage.total_cost_usd == pytest.approx(expected)
+        assert "not understated" in caplog.text
+
+    async def test_zero_reported_cost_on_an_unpriced_model_stays_zero(self, patch_exec, tmp_path):
+        """With no rate to fall back to, the stream's 0 is the best information we have."""
+        stream = [_turn_start(), _turn_end(inp=10, out=5, cost=0.0), self._SETTLED]
+        patch_exec(_FakeProcess(stream))
+        record = await _run(_agent(model="nowhere/not-a-real-model"), tmp_path)
+        assert record.token_usage is not None
+        assert record.token_usage.total_cost_usd == 0.0
diff --git a/tests/test_pi_agent_config.py b/tests/test_pi_agent_config.py
new file mode 100644
index 00000000..db0cb1d0
--- /dev/null
+++ b/tests/test_pi_agent_config.py
@@ -0,0 +1,73 @@
+"""Phase 1: ``PiAgentConfig`` model + ``AgentKind.PI`` enum member.
+
+Registry-dispatch coverage (``parse_agent_config(type="pi")`` returning a
+``PiAgentConfig``) lives in ``tests/test_pi_agent.py`` — it needs Phase 2's
+registration. Here we exercise the model directly.
+"""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import ValidationError
+
+from coder_eval.models import AgentConfig, AgentKind, PiAgentConfig
+from coder_eval.models.agent_config import PiThinkingLevel
+
+
+def test_agentkind_pi_value():
+    assert AgentKind.PI == "pi"
+
+
+def test_importable_from_models():
+    # `from coder_eval.models import PiAgentConfig` must succeed (CE001).
+    assert PiAgentConfig.__name__ == "PiAgentConfig"
+
+
+def test_validates_and_defaults():
+    cfg = PiAgentConfig(type="pi")
+    assert cfg.type == AgentKind.PI
+    assert cfg.thinking_level == "medium"
+
+
+def test_round_trips_through_model_dump():
+    cfg = PiAgentConfig(type="pi", model="openrouter/moonshotai/kimi-k3", thinking_level="high")
+    restored = PiAgentConfig.model_validate(cfg.model_dump())
+    assert restored == cfg
+    assert restored.model == "openrouter/moonshotai/kimi-k3"
+    assert restored.thinking_level == "high"
+
+
+@pytest.mark.parametrize("level", ["off", "minimal", "low", "medium", "high", "xhigh", "max"])
+def test_all_seven_thinking_levels_validate(level):
+    assert PiAgentConfig(type="pi", thinking_level=level).thinking_level == level
+
+
+def test_thinking_level_literal_has_exactly_seven_values():
+    # PiThinkingLevel is a strict superset of the 4-value ThinkingLevel.
+    assert set(PiThinkingLevel.__value__.__args__) == {  # type: ignore[attr-defined]
+        "off",
+        "minimal",
+        "low",
+        "medium",
+        "high",
+        "xhigh",
+        "max",
+    }
+
+
+def test_invalid_thinking_level_rejected():
+    with pytest.raises(ValidationError):
+        PiAgentConfig(type="pi", thinking_level="ultra")  # type: ignore[arg-type]
+
+
+def test_unknown_extra_field_rejected():
+    with pytest.raises(ValidationError):
+        PiAgentConfig(type="pi", not_a_field=1)  # type: ignore[call-arg]
+
+
+def test_member_of_discriminated_union():
+    from pydantic import TypeAdapter
+
+    adapter = TypeAdapter(AgentConfig)
+    cfg = adapter.validate_python({"type": "pi", "model": "openrouter/moonshotai/kimi-k3"})
+    assert isinstance(cfg, PiAgentConfig)
diff --git a/tests/test_pi_smoke_task.py b/tests/test_pi_smoke_task.py
new file mode 100644
index 00000000..09bdebe3
--- /dev/null
+++ b/tests/test_pi_smoke_task.py
@@ -0,0 +1,38 @@
+"""Phase 3: the local Pi smoke task loads, resolves to PiAgentConfig, validates.
+
+The task is intentionally excluded from the CI E2E bucket (no ``smoke-pass``
+tag — the CI runners have no ``pi`` CLI and no OpenRouter credentials); it is a
+local smoke. This test only proves the YAML parses and resolves, offline.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from coder_eval.models import PiAgentConfig
+from coder_eval.orchestration.task_loader import load_task
+
+
+_TASK = Path("tasks/pi_smoke_test.yaml")
+
+
+def test_task_loads_and_resolves_to_pi_agent_config():
+    task, _raw = load_task(_TASK)
+    assert task.task_id == "pi_smoke_test"
+    assert isinstance(task.agent, PiAgentConfig)
+    assert task.agent.type == "pi"
+    assert task.agent.model == "openrouter/moonshotai/kimi-k3"
+
+
+def test_criteria_validate():
+    task, _raw = load_task(_TASK)
+    types = [c.type for c in task.success_criteria]
+    assert types == ["file_exists", "file_contains", "run_command"]
+
+
+def test_not_in_ci_e2e_bucket():
+    """No `smoke-pass` tag: the task must not route into the CI E2E bucket, which
+    has no `pi` CLI or OpenRouter credentials."""
+    task, _raw = load_task(_TASK)
+    assert "pi" in task.tags
+    assert "smoke-pass" not in task.tags
diff --git a/uv.lock b/uv.lock
index 28ced6d2..f684a026 100644
--- a/uv.lock
+++ b/uv.lock
@@ -564,7 +564,7 @@ requires-dist = [
     { name = "typer", specifier = ">=0.24.1" },
     { name = "uipath", marker = "extra == 'uipath'", specifier = ">=2.10.31" },
 ]
-provides-extras = ["dev", "uipath", "litellm", "codex", "antigravity", "opencode"]
+provides-extras = ["dev", "uipath", "litellm", "codex", "antigravity", "opencode", "pi"]
 
 [[package]]
 name = "colorama"