piocloop 0.1.0__tar.gz

piocloop-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # required for OIDC trusted publisher
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

piocloop-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+wheels/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Editable install artifacts
+*.pth
+
+# Distribution / packaging
+MANIFEST
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project-specific
+*.log
+.pi/

piocloop-0.1.0/ANALYSIS.md

@@ -0,0 +1,155 @@
+# pyocloop — code analysis
+
+Analysis of `../pyocloop` @ `57d000d` (v0.3.1), focused on why the loop sometimes
+hangs. Findings are marked **CONFIRMED** (verified against a live `opencode`
+1.18.7 server or by unambiguous code reading) or **PLAUSIBLE**.
+
+---
+
+## The hang: three independent mechanisms, all reachable
+
+The loop's blocking point is `tui.py:446`:
+
+```python
+while not self._idle_event.is_set():
+    try:
+        await asyncio.wait_for(self._idle_event.wait(), timeout=IDLE_POLL_INTERVAL)
+    except asyncio.TimeoutError:
+        session = await self._client.get_session(self._current_session_id)
+        if session.get("idle", False):      # <-- never true
+            self._idle_event.set()
+```
+
+This `while` has **no exit other than `_idle_event` being set**. There is no
+iteration deadline, no max-retry, no bail-out. So any failure to observe the
+idle signal is an unrecoverable hang, not a slow iteration. Three separate
+things can cause that.
+
+### H1 — The polling fallback is a no-op **CONFIRMED**
+
+`git log` shows commit `02e9008 fix(tui): add session-idle polling fallback`,
+added precisely to rescue a missed `session.idle`. It cannot work: the OpenCode
+session object has **no `idle` field**. Live response from `POST /session`:
+
+```json
+{"id":"ses_055ec9c8effeOIYm5v2tGw2MEo","slug":"sunny-forest","projectID":"global",
+ "directory":"/tmp","path":"tmp","cost":0,"tokens":{...},"title":"New session - ...",
+ "version":"1.18.7","time":{"created":1785264825201,"updated":1785264825201}}
+```
+
+`session.get("idle", False)` is therefore **always `False`**. The fallback polls
+every 30s forever and never fires. The intended safety net does not exist.
+
+### H2 — The OpenCode server can deadlock on its own stdout **CONFIRMED (mechanism)**
+
+`opencode_server.py` spawns the server with `stdout=PIPE, stderr=STDOUT`, then
+reads the pipe *only* until the "listening" banner:
+
+```python
+async for raw in self._proc.stdout:
+    if "opencode server listening" in line:
+        return m.group(1)          # <-- loop exits; nothing ever reads again
+```
+
+After that, **nothing drains the pipe for the rest of the run**. asyncio buffers
+into a `StreamReader`, but its flow control calls `pause_reading()` at the 64 KiB
+high-water mark; the OS pipe (another ~64 KiB) then fills, and the server
+**blocks in `write()` and stops serving**. The client sees no further SSE events
+→ H1 → permanent hang.
+
+This matches the reported symptom precisely: works fine, then hangs
+*sometimes*, after an unpredictable amount of work. It is output-volume
+dependent, so a chatty local-LLM provider (extra warnings, retries, token
+diagnostics on stderr — which is merged into the same pipe) reaches the
+threshold much faster than a quiet cloud provider. **This is the most likely
+cause of the hangs you observed, and it is a pyocloop bug, not an LLM problem.**
+
+### H3 — SSE reconnect drops events permanently **CONFIRMED**
+
+`subscribe_events` reconnects with backoff up to 30 s, but OpenCode's `/event`
+stream has no replay and the client sends no `Last-Event-ID`. **Every event
+emitted during the gap is lost forever.** If the lost event is `session.idle`,
+the iteration hangs (H1 again). A clean disconnect sets `backoff = 5.0`, so
+there is always at least a 5 s blind window per reconnect.
+
+### Why the existing escape hatch doesn't help
+
+`_reload_plan` (line 322) can set `_idle_event`, but only when
+`is_plan_complete()` — i.e. only on the very last iteration. A stall on
+iteration 3 of 20 is never rescued.
+
+---
+
+## Other defects
+
+### D1 — "Retry" is dead **CONFIRMED**
+
+Every error path in `_worker_loop` does `post_message(_LoopError(...)); return` —
+the worker exits. `action_retry` only repaints the header to `READY`, and
+`action_start_loop` then sets `_start_event`, which **no one is awaiting**. After
+any loop error, `R` then `S` leaves the app looking ready but permanently dead.
+Restarting the process is the only recovery.
+
+### D2 — A stale idle event ends the wrong iteration **CONFIRMED**
+
+`on__session_idle` accepts the event when the session ID is *empty*:
+
+```python
+if not msg.session_id or msg.session_id == self._current_session_id:
+```
+
+`_idle_event.clear()` happens at line 420, *before* the prompt is sent. A late
+`session.idle` from iteration N-1 arriving in that window terminates iteration N
+instantly → the loop spins, creating sessions that do no work. The server is
+also shared and unauthenticated on a fixed port, so another client's events can
+land here too.
+
+### D3 — Errors don't stop the loop **CONFIRMED**
+
+`on__session_error` sets `_state = STATE_ERROR` *and* sets `_idle_event`, so the
+loop immediately starts the next iteration while the header reads `ERROR`. With
+a persistently failing provider this becomes an unbounded hot loop hammering the
+LLM. There is no error-streak circuit breaker.
+
+### D4 — No progress-stall detection **CONFIRMED**
+
+If the model does not tick a checkbox (very common with smaller local models),
+the loop re-runs the identical task forever. Nothing compares plan progress
+across iterations. Externally this is indistinguishable from a hang.
+
+### D5 — Fixed port 4096 **CONFIRMED**
+
+No fallback and no port-in-use detection; a second instance or a stale server
+kills startup. Should use port 0 / auto-select.
+
+### D6 — Pause is confusing **CONFIRMED (UX)**
+
+`Space` during `RUNNING` only sets a flag checked *after* the current iteration
+completes. `PAUSING` can persist for many minutes with no indication that the
+pause is pending rather than stuck.
+
+### D7 — Minor
+
+- `on__session_created` resets `_total_tokens`, so the `tok:` field is
+  per-iteration despite being named total, and it fires for *any* session
+  created on the shared server.
+- `parse_model_string("foo")` yields `providerID: ""` — likely rejected upstream.
+- `_log_fh` is only closed in `_do_quit`; an exception path leaks it.
+- Dead imports (`os`, `sys`, `signal` partially) in `opencode_client.py` /
+  `opencode_server.py`.
+- Blocked tasks count against `percent_complete` forever, so the bar never
+  reaches 100% on a plan with blocked items.
+
+---
+
+## Verdict
+
+Your instinct that the local LLM was to blame is understandable, but the
+evidence points at pyocloop. **H2 (undrained stdout pipe) and H1 (a fallback
+that can never fire) together produce exactly "it works, then it silently stops
+forever"**, and the loop has no deadline that would ever break out. A stuck
+local LLM would have produced the same visible symptom *only* because pyocloop
+has no timeout to distinguish the two — which is itself the deeper flaw.
+
+**Design lesson carried into piocloop: every wait gets a deadline, every pipe
+gets a drainer, and lack of progress is a first-class detected state.**

piocloop-0.1.0/DESIGN.md

@@ -0,0 +1,221 @@
+# piocloop — design
+
+A port of [pyocloop](../pyocloop) that drives the **PI coding agent**
+(`@earendil-works/pi-coding-agent`, `pi` on PATH) instead of OpenCode.
+
+Same product: a Textual TUI that repeatedly asks a coding agent to execute the
+next task from `PLAN.md`, until the agent writes `<plan-complete>`.
+Different — and much simpler — transport.
+
+---
+
+## 1. Why the PI port is structurally more reliable
+
+pyocloop talks to an HTTP server over a network socket plus a lossy SSE stream.
+PI offers **`--mode rpc`: newline-delimited JSON over the subprocess's own
+stdin/stdout**. That deletes entire classes of the bugs found in `ANALYSIS.md`:
+
+| pyocloop failure | piocloop |
+|---|---|
+| SSE reconnect gap loses `session.idle` (H3) | No socket. A pipe cannot silently drop a record; if it closes, the process died and we *know*. |
+| Fixed port 4096 collisions (D5) | No port at all. |
+| Ambiguous / cross-session idle events (D2) | One process, one conversation; `agent_settled` is unambiguous. |
+| Polling fallback against a non-existent field (H1) | `get_state` returns a real `isStreaming` flag — a fallback that actually works. |
+| Undrained stdout deadlocks the server (H2) | Still a live hazard — **must be designed against explicitly** (§4.1). |
+
+Verified live against `pi` 0.82.1 (`--mode rpc --no-session -nt`), the event
+sequence for one prompt is:
+
+```
+response(prompt, success=true)
+agent_start → turn_start → message_start → message_end → … → turn_end
+agent_end
+agent_settled          ← the correct "iteration is over" signal
+```
+
+**Use `agent_settled`, not `agent_end`.** Per the protocol docs, `agent_end` is
+one low-level run and "may still be followed by retry, compaction, or queued
+continuations"; `agent_settled` fires only once nothing more will happen
+automatically. Treating `agent_end` as done would cut iterations short mid-retry.
+
+---
+
+## 2. Architecture
+
+```
+cli.py        typer entry point (piloop run / bootstrap)
+tui.py        Textual app: header, activity log, state machine, loop worker
+pi_client.py  spawns & owns `pi --mode rpc`; JSONL framing; request/response
+              correlation; event fan-out; extension-UI auto-responder
+pi_events.py  event → internal Message mapping (the _dispatch_sse equivalent)
+plan_parser.py  UNCHANGED — port verbatim from pyocloop
+```
+
+`plan_parser.py` is agent-agnostic and correct; copy it as-is (plus tests, which
+pyocloop lacks). `tui.py`'s widget/state-machine layer ports over largely intact.
+`opencode_server.py` + `opencode_client.py` are **replaced wholesale** by
+`pi_client.py`.
+
+### Process model
+
+One long-lived `pi --mode rpc` process for the whole run; per iteration send
+`{"type":"new_session"}` to get a fresh context. This is much cheaper than
+respawning (PI's startup does model-catalog and extension loading — the smoke
+test showed several hundred ms and 5 extension callbacks). The supervisor may
+still kill and respawn the process as the escalation step of the watchdog (§4.2),
+so respawn must be supported anyway.
+
+### Session-per-iteration rationale
+
+Same as pyocloop: each iteration starts from a clean context so the agent
+re-reads `PLAN.md` rather than trusting stale in-context state. `--session-dir`
+is passed through so sessions remain inspectable/resumable after a run.
+
+---
+
+## 3. Command / event mapping
+
+| Need | RPC |
+|---|---|
+| new iteration | `{"type":"new_session"}` |
+| send loop prompt | `{"id":"…","type":"prompt","message":"…"}` |
+| iteration finished | event `agent_settled` |
+| cancel current work | `{"type":"abort"}` |
+| liveness / stuck check | `{"type":"get_state"}` → `data.isStreaming` |
+| model at startup | CLI `--model provider/id`, or `{"type":"set_model",…}` |
+| token/cost display | `turn_end` / `message_end` message objects |
+| activity log | `tool_execution_start`, `message_update` text deltas |
+| plan-file edit detection | `tool_execution_end` where the edited path == plan file |
+
+Note `file.edited` has no direct PI equivalent — piocloop watches
+`tool_execution_end` for edit/write tool calls, and in any case already re-reads
+`PLAN.md` on a 4 s timer.
+
+### CLI surface
+
+```
+piloop run [OPTIONS]
+  -m, --model TEXT        provider/id, e.g. zai/glm-5.2   (pass through to pi)
+      --thinking TEXT     off|minimal|low|medium|high|xhigh|max
+      --prompt PATH       loop prompt      [default: .loop-prompt.md]
+      --plan PATH         plan file        [default: PLAN.md]
+  -r, --run               start immediately
+      --max-iterations N  hard stop        [default: 100]
+      --iteration-timeout S  per-iteration deadline [default: 1800]
+      --session-dir PATH  pass through to pi
+      --tools / --exclude-tools TEXT  pass through
+      --dialog-policy TEXT  cancel|allow|deny   [default: cancel]   (§4.3)
+      --verbose, --log PATH, --debug
+```
+
+`-p/--port` is **dropped** (no server). pyocloop's `-a/--agent` has no PI
+equivalent — PI has no named-agent concept; the nearest equivalents are
+`--append-system-prompt` and `--skill`, so expose those instead rather than
+faking `--agent`.
+
+---
+
+## 4. The three things that must not be repeated
+
+Every hang in `ANALYSIS.md` traces to a wait with no deadline or a pipe with no
+reader. These are the load-bearing requirements of the port.
+
+### 4.1 Drain every pipe, always
+
+`pi`'s stdout is the protocol, so it is read continuously by construction —
+but **stderr must get its own concurrent drain task**. pyocloop's H2 deadlock
+came from exactly this. Never merge stderr into the protocol stream (it would
+corrupt JSONL framing); read it separately into the log ring buffer.
+
+**Framing rule from the spec:** split on `\n` only, stripping an optional
+trailing `\r`. Do *not* use a generic line reader — Python's `for line in
+stream` splits only on `\n` for text streams and is fine, but note the docs
+explicitly call out Node's `readline` as non-compliant because it also breaks on
+`U+2028`/`U+2029`, which are legal inside JSON strings. Use
+`asyncio.StreamReader.readuntil(b"\n")` on the **binary** stream and decode
+after splitting, so multi-byte and separator characters can never desync frames.
+Raise `readuntil`'s limit well above the default 64 KiB — `message_update`
+events embed the full partial message and routinely exceed it.
+
+### 4.2 Every wait has a deadline, and a defined escalation
+
+Replace pyocloop's unbounded `while not self._idle_event.is_set()` with a
+three-stage watchdog:
+
+1. **Soft poll** — every 30 s of silence, send `get_state`. If
+   `isStreaming` is `false` and no `agent_settled` arrived, the settle signal was
+   missed: treat as settled. *(This is the fallback pyocloop intended; unlike
+   `session.idle`, `isStreaming` genuinely exists.)*
+2. **Iteration deadline** — at `--iteration-timeout` (default 30 min), send
+   `abort`, log it, and wait a short grace period for settle.
+3. **Process wedge** — if abort doesn't settle within ~30 s, or the pipe hits
+   EOF, or `get_state` stops responding: kill the process group, respawn, and
+   resume the loop at the next iteration. Count consecutive respawns; stop after
+   3 with a clear error.
+
+Combined with `--max-iterations`, **no code path can wait forever**.
+
+### 4.3 Answer extension UI dialogs — or the loop will hang
+
+This is a genuine new hazard and the single most important protocol detail for
+an *unattended* harness. Extensions can call `ctx.ui.select()` / `confirm()` /
+`input()` / `editor()`, which emit `extension_ui_request` on stdout and
+**block the agent until the client sends a matching `extension_ui_response` on
+stdin**. Only dialogs carrying a `timeout` field auto-resolve; the rest wait
+indefinitely. A TUI harness that ignores them reproduces pyocloop's hang with a
+new cause.
+
+The smoke test on this machine already emitted five `extension_ui_request`s per
+prompt (`setStatus` from the `openrouter`, `zai-usage` and `mcp` extensions).
+Those are fire-and-forget — but the same channel carries blocking dialogs, and
+this user has six extension packages installed.
+
+**Requirement:** `pi_client.py` MUST implement the responder:
+
+- fire-and-forget (`setStatus`, `notify`, `setWidget`, `setTitle`,
+  `set_editor_text`) → render into the header/activity log, send nothing;
+- blocking (`select`, `confirm`, `input`, `editor`) → reply immediately per
+  `--dialog-policy`, default `cancel`
+  (`{"type":"extension_ui_response","id":…,"cancelled":true}`), and log it
+  prominently so a silently-declined permission prompt is visible.
+
+Status text arrives with ANSI SGR escapes embedded (observed:
+`Z.ai:…`), so strip or translate them before writing to
+the Textual log.
+
+### 4.4 Progress stalls are a state, not a hang
+
+Carried over from D4: track `PlanProgress.completed` across iterations. If it
+does not increase for N consecutive iterations (default 3), enter a distinct
+`STALLED` state, pause the loop, and say so. This is the difference between "the
+model is looping on a task it can't finish" and "the harness is broken" — a
+distinction pyocloop cannot make.
+
+### 4.5 Recoverable errors must actually recover
+
+Fix D1/D3 structurally: `_worker_loop` never `return`s on error. It catches,
+increments an error streak, applies backoff, and continues; only
+`--max-iterations`, a completed plan, an error streak of 3, or an explicit stop
+ends the worker. `Retry` re-arms a *live* worker rather than pretending to
+restart a dead one.
+
+---
+
+## 5. Deliberate non-goals for v0.1
+
+- No PI *SDK* embedding (`AgentSession`) — that is Node-only; the subprocess RPC
+  boundary is the whole point of a Python harness.
+- No multi-agent / parallel task execution.
+- No resume-mid-plan-from-session — `PLAN.md` is already the durable state.
+
+---
+
+## 6. Risks
+
+| Risk | Mitigation |
+|---|---|
+| Blocking extension dialog stalls unattended runs | §4.3 auto-responder, default `cancel` |
+| PI RPC protocol churn (0.82.x, pre-1.0) | Isolate all protocol knowledge in `pi_client.py`; pin a tested `pi` version range and assert it at startup |
+| `message_update` flood (one event per token) overwhelms the TUI | Coalesce text deltas; render at most ~10 Hz; never log deltas individually |
+| Local/small models never tick checkboxes | §4.4 stall detection makes it visible instead of silent |
+| Project-trust prompts skipped in non-interactive mode change tool availability | Document `--approve`/`-a`; surface the effective trust state at startup |

piocloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ronan Barzic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

piocloop-0.1.0/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.5
+Name: piocloop
+Version: 0.1.0
+Summary: TUI loop harness that orchestrates the PI coding agent to execute tasks from a PLAN.md file iteratively
+Project-URL: Homepage, https://github.com/rbarzic/piocloop
+Project-URL: Repository, https://github.com/rbarzic/piocloop
+Project-URL: Issues, https://github.com/rbarzic/piocloop/issues
+Author-email: Ronan Barzic <rbarzic@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,automation,pi,pi-coding-agent,textual,tui
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: textual>=0.80
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# piocloop
+
+A Python TUI that orchestrates the [PI coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent)
+to execute tasks from a `PLAN.md` file iteratively, one session at a time.
+
+piocloop is a port of [pyocloop](https://github.com/rbarzic/pyocloop) — same
+concept, but it drives `pi --mode rpc` over stdin/stdout JSONL instead of an
+OpenCode HTTP server plus SSE stream. That change, plus a real watchdog, fixes
+the hangs documented in [`ANALYSIS.md`](ANALYSIS.md).
+
+## How it works
+
+1. piocloop starts a `pi --mode rpc` subprocess
+2. On each iteration it starts a fresh session, sends your loop prompt (with the
+   plan file path injected), and waits for `agent_settled`
+3. PI reads the plan, executes the next task, marks it `[x]`, and appends
+   `<plan-complete>` when everything is done
+4. The TUI shows live progress: task counter, progress bar, current task, token
+   count, cost, and elapsed/average time per iteration
+5. The loop stops when PI writes `<plan-complete>` — or when the watchdog, an
+   error streak, a stall, or `--max-iterations` intervenes
+
+## Requirements
+
+- Python 3.11+
+- `pi` on your PATH, configured with a provider (developed against pi 0.82.1)
+
+```bash
+npm install -g @earendil-works/pi-coding-agent
+```
+
+## Installation
+
+```bash
+git clone https://github.com/rbarzic/piocloop
+cd piocloop
+pip install .
+```
+
+## Usage
+
+```bash
+piloop doctor                    # check pi is installed and reachable
+piloop bootstrap .               # create starter PLAN.md and .loop-prompt.md
+piloop run --model zai/glm-5.2
+```
+
+### Using an OpenRouter model
+
+Set your OpenRouter API key, then prefix the OpenRouter model ID with
+`openrouter/`. For example, Kimi K3 is `moonshotai/kimi-k3` on OpenRouter:
+
+```bash
+export OPENROUTER_API_KEY="your-openrouter-api-key"
+piloop run --model openrouter/moonshotai/kimi-k3
+```
+
+You can check that PI's model catalog contains it with:
+
+```bash
+pi --list-models openrouter | grep kimi-k3
+```
+
+### `piloop run`
+
+| Option | Default | Meaning |
+|---|---|---|
+| `-m, --model` | pi's default | Model pattern or `provider/id` |
+| `--thinking` | pi's default | `off\|minimal\|low\|medium\|high\|xhigh\|max` |
+| `--plan` | `PLAN.md` | Plan file |
+| `--prompt` | `.loop-prompt.md` | Loop prompt file |
+| `-r, --run` | off | Start iterating immediately |
+| `--max-iterations` | 100 | Hard stop |
+| `--iteration-timeout` | 1800 | Seconds before an iteration is aborted |
+| `--max-stalls` | 3 | Stop after N iterations with no plan progress (0 disables) |
+| `--dialog-policy` | `cancel` | How to answer blocking extension dialogs |
+| `--session-dir`, `--no-session` | — | Passed through to pi |
+| `--tools`, `--exclude-tools` | — | Passed through to pi |
+| `--append-system-prompt`, `--skill` | — | Passed through to pi (repeatable) |
+| `--approve / --no-approve` | pi's default | Project-local file trust |
+| `--verbose`, `--log`, `--debug` | — | Diagnostics |
+
+Keys: `S` start · `Space` pause · `A` abort current iteration · `R` retry ·
+`Q` quit.
+
+## Plan format
+
+```markdown
+- [ ] a task to do
+- [x] a completed task
+- [MANUAL] something a human must do — never attempted, excluded from progress
+- [BLOCKED: reason] something the agent could not finish
+```
+
+The run ends when the agent appends, at the start of a line:
+
+```
+<plan-complete>summary of what was done</plan-complete>
+```
+
+## Agent skill (optional)
+
+`skills/piocloop-setup/` is an [Agent Skills](https://agentskills.io/specification)
+package you can copy into your own agent so it can set up piocloop runs for you —
+turning "for each of these 40 items, do X" into a correctly formatted `PLAN.md`
+and `.loop-prompt.md`. It is not loaded automatically; install it only if you
+want it:
+
+```bash
+cp -r skills/piocloop-setup ~/.pi/agent/skills/     # PI
+cp -r skills/piocloop-setup ~/.claude/skills/       # Claude Code
+```
+
+See [`skills/README.md`](skills/README.md) for other harnesses and for pointing
+`pi` at this checkout without copying.
+
+## Differences from pyocloop
+
+| | pyocloop | piocloop |
+|---|---|---|
+| Agent | OpenCode | PI |
+| Transport | HTTP + SSE on port 4096 | stdin/stdout JSONL |
+| "Iteration done" signal | `session.idle` SSE event | `agent_settled` RPC event |
+| Idle fallback | polled a field that does not exist | polls `get_state().isStreaming` |
+| Iteration timeout | none | `--iteration-timeout`, then abort, then respawn |
+| Iteration cap | none | `--max-iterations` |
+| Progress stalls | undetected | `STALLED` state |
+| Repeated errors | looped forever | error-streak circuit breaker |
+| Blocking agent dialogs | n/a | auto-answered (`--dialog-policy`) |
+| Tests | none | 119 |
+
+`-a/--agent` and `-p/--port` are gone: PI has no named-agent concept (use
+`--append-system-prompt` / `--skill`) and no server to bind.
+
+## Why the rewrite is more reliable
+
+[`ANALYSIS.md`](ANALYSIS.md) documents the pyocloop defects that motivated this
+port — verified against a live OpenCode server, not inferred. The two that
+caused silent hangs:
+
+* the server's stdout pipe was never drained after startup, so the OS pipe
+  eventually filled and the server blocked in `write()` and stopped serving;
+* the loop's idle wait had no deadline, and its polling fallback tested a
+  `session.idle` field that OpenCode does not return — so a single missed SSE
+  event hung the run forever.
+
+piocloop's design rules ([`DESIGN.md`](DESIGN.md) §4) are the direct response:
+**every pipe gets a drainer, every wait gets a deadline, and lack of progress is
+a first-class state.** The test suite mutation-checks the first two — removing
+either fix makes the corresponding regression test hang.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e ".[dev]"
+.venv/bin/python -m pytest tests/ -q
+```
+
+Tests run against `tests/fake_pi.py`, a stub agent — no network, no API key and
+no LLM required.
+
+## License
+
+MIT