# Pi Harness

Use `templates/harnesses/pi/binding.json.template` and `templates/harnesses/pi/adapter.json.template` when creating or converting a Pi-bound loop. The latter becomes generated `runtime/adapter.json` and is removed when converting back to Codex.

The bundled extension exposes `dirtyloops_runtime` and `dirtyloops_child`. Its baseline uses vanilla Pi `AgentSession` primitives with explicit working directory, model and reasoning selection, parent-linked persistent sessions when required, lifecycle completion delivery, steering, cancellation, and a bounded active-child limit. Optional plugins are accelerators, not requirements.

The runtime manifest captures one canonical hash over the loaded Pi runtime closure at module evaluation and reports the current Pi session id as `coordinator_id`. Do not recompute loaded identity from changed files. After a material operation, call `dirtyloops_runtime action=activate doc_root=<absolute-loop-doc-root>` from a different Pi session. `/reload` retains the session id and is intentionally insufficient. Launch only the exact vanilla probe returned; its ordinary completion acknowledgement makes activation ready.

Terminal results enter one durable completion channel. A visible completion includes a handle, nonce, and owning loop; call `dirtyloops_child` with `action=ack`, that handle, that nonce, and the exact absolute loop `doc_root` as soon as the parent receives it. Emission is not acknowledgement. The adapter retries an unacknowledged emission with a bounded activation budget, reconstructs pending delivery and loop ownership from parent session entries after resume, and blocks another launch until the terminal result is acknowledged.

Normal completion is callback-driven and never uses `status`, sleep, or wait polling. `dirtyloops_child action=recover` and legacy `action=status` are reason-required recovery operations. `missed-heartbeat` eligibility comes from adapter-observed `AgentSession` activity and a minimum silence window, `delivery-recovery` forces a reasoned re-emission of an unacknowledged completion, and `operator-request` preserves explicit intervention. Every attempt is durably recorded and accepted attempts are rate-limited.

Degraded delivery requires coordinator renewal before another ordinary launch. Before forced re-emission, the adapter records non-rewindable degradation in `runtime/activation.json`; session-tree navigation cannot erase the blocker. At a safe boundary, call `dirtyloops_runtime action=renew` with the phase Beads issue, repo-relative turn doc, PR state, expected branch, and recovery handle. The adapter verifies the checkout, snapshots the exact degraded handle set, atomically moves activation back to `required`, and records the ownership handoff. A different Pi session completes the ordinary activation probe and acknowledgement to take ownership; interrupted renewal closeout is idempotently reconciled before ordinary launch. Context-pressure renewal may use `ctx.getContextUsage()` evidence at an adaptive safe boundary; the contract sets no fixed coordinator lifetime, context threshold, model, or topology.

Enable an optional backend only after an exact supported protocol handshake. Missing, incompatible, or partial plugin behavior leaves that backend unavailable and falls back to vanilla Pi when the baseline satisfies the mission. The current backend is Nicobailon's `pi-subagents`, certified through its RPC v1 `ping`, `spawn`, `status`, and `stop` contract. It is available only for explicitly requested read-only evidence scouts using the packaged `dirtyloops.scout` agent; that profile exposes only `read`, `grep`, `find`, and `ls`. Completion follows the returned `status.json` lifecycle with a filesystem watcher, not terminal scraping or active polling. Durable sessions, broad review, and write ownership stay on vanilla Pi. Dynamic workflow orchestration does not own Beads, phase advancement, implementation integration, review closeout, or CI state.

Prepare and verify attached symbolic branches before mutation. Do not use child isolation modes that auto-commit or repair checkout placement inside the child.

Completion criterion: the binding validates, the active runtime identifies as Pi, and vanilla Pi can satisfy the required capabilities without optional plugins.