pi-harness

pi-harness is the research and build area for Pi, Earendil's minimal, extensible agent harness (github.com/earendil-works/pi). It began on 2026-10-11 by asking whether owning a harness fixes the costliest failures in this machine's Claude Code, Kimi and OpenCode history. Those were false completion claims, agents that stop before the goal, and destructive actions.

It now ships pi-task. A Pi worker does one task in a fresh Incus container. Its result comes back only if a judge, in another fresh container, finds that the brief's checks hold, no gaming rule fired, and every hidden check passed. An accepted result arrives as a branch, pi/<task>, and is never merged automatically.

Status

Location: ~/workspace/pi-harness. It is its own git repository (branch master, created 2026-10-16) with no remote: commit, never push.
Deployed: pi-task at /opt/pi-worker, release 238d899 (2026-10-17), driving image pi-worker-1.1.0 (fingerprint cc669a3e) in Incus project pi-workers. On PATH as ~/bin/pi-task.
Claude Code skill: pi-worker (~/.claude/skills/pi-worker/SKILL.md), installed from the release.
Worker models: deepseek/deepseek-v4-pro (the default) or any OpenRouter model as openrouter/VENDOR/MODEL.
Verification (2026-10-17):
- pi-goal: 76 tests pass.
- Boundary tests: 19/19 on image cc669a3e.
- pi-task verify: passes.
- End to end: one OpenRouter run (qwen/qwen3-coder) and one DeepSeek run, both accepted in about 19 s.
Pi on the host: 1.1.0 from the official pi.dev installer, in managed mode (~/.pi/agent). artifacts/pi-install/verify.sh refuses unless the pi on PATH is that install.
Current focus:
- More trials on real tasks.
- The open design question of a worker that can read the gaming rules (Blockers).

What it is made of

Part	Path	What it does
pi-goal	`artifacts/pi-goal/`	A Pi extension. The worker can finish only when the brief's DONE WHEN holds. Pi runs VERIFY itself, `goal.pl` (SWI-Prolog) decides, and the gaming checks (`ast_facts.py` and `gaming.pl`) block changes that pass the checks without doing the task
pi-guard	`artifacts/pi-guard/`	A Pi extension that blocks destructive and convention-breaking bash. It is the first line of defence, not the boundary
pi-worker	`artifacts/pi-worker/`	The pinned image build, `worker.py` (one task: bundle in, worker, bundle out, judge, accept or reject), `pi_task.py` (the deployed CLI), `install.sh`, the boundary tests and the Claude Code skill
pi-rpc	`artifacts/pi-rpc/`	A Python RPC client for Pi, plus the probes that answered the hands-on research questions
pi-install	`artifacts/pi-install/`	The record of the host Pi install, and its refusing verifier
history-mining	`artifacts/history-mining/`	Scripts that mined the agent history behind the requirements
notes	`notes/`	The research notes. Start at `notes/00-index.md`

Key Pages

Architecture: the run pipeline, the goal gate, the gaming checks, hidden checks, the image and the deployment.
Decisions: the rulings of 2026-10-16 and the design decisions measurements forced.
Blockers: what is open, and what was found and fixed.
Runbooks: delegating, judging, rebuilding the image, deploying, refusals.

Quick Commands

# Use it
pi-task verify                                   # VERIFIED or REFUSED; on a refusal, stop
pi-task check-brief BRIEF --hidden HIDDEN        # parse a brief the way the judge will
pi-task run   --repo REPO --brief BRIEF --hidden HIDDEN [--model openrouter/qwen/qwen3-coder]
pi-task judge --repo REPO --brief BRIEF --base START_COMMIT --ref BRANCH --hidden HIDDEN
# exit status: 0 accepted or done, 1 rejected or not done, 2 refused

# Develop it (in ~/workspace/pi-harness)
PI_GOAL_PYTHON=~/.local/bin/python3.14t node --test artifacts/pi-goal/goal.test.ts
node --test artifacts/pi-guard/rules.test.ts
artifacts/pi-worker/build-image.sh --rebuild
python3.14t artifacts/pi-worker/boundary_tests.py <scratch dir>
artifacts/pi-worker/install.sh <commit>
artifacts/pi-install/verify.sh

Links (repo documents, not wiki pages)

notes/00-index.md: the index of every research note.
notes/history-pain/00-summary.md: the ranked pain in the agent history that set the requirements.
notes/13-hands-on-results.md: measured answers to the open questions (skills, MCP, CLAUDE.md, RPC, sessions, telemetry, the guard).
notes/14-plan-goal-and-worker.md: the plan, and the rulings of 2026-10-16.
notes/15-goal-and-worker-results.md: everything built and measured, including the red-team rounds.
artifacts/pi-worker/skill/SKILL.md: the manual, covering the brief format, hidden checks and how to read a verdict.