Files

T

ducoterra 3bacbff874 fix(phased-execution): resume failed session on retry, surface errors, thinking/compaction indicators

- retries now resume the failed executor's session (pre/post session
  tracking replaces the broken mtime-vs-ref check)
- report recovery from the session file when the JSON stream loses its
  tail (child signaled mid-flush)
- progress.mjs: thinking indicators (◐ thinking… / ◑ thought for Ns),
  compaction (⧉ …) and provider auto-retry lines; trims trailing
  whitespace so no blank lines after LLM text; exits 1 on truncated
  stream, model error, or missing final text (pi --mode json always
  exits 0 even on errors)
- explicit ✗ ERROR lines + exit codes: 0 ok, 1 phase failed, 130/143
  interrupted (INT/TERM traps; post-pipeline check covers the case
  where bash suppresses the INT trap after a job dies from SIGINT)
- PIPESTATUS captured in a single statement (any following command
  resets it)
- skills dir: .gitignore README.md so pi's skill scanner (which honors
  .gitignore) stops warning 'description is required'

2026-08-21 11:00:21 -04:00

4.2 KiB

Raw Blame History

name, description

name	description
phased-execution	Runs the .agent/phases/ phased-execution pipeline (ported from opencode's next-phase/auto-phase commands). Use when the user asks to run the next phase, run all phases, run the phase pipeline, or check pipeline status. Each phase executes in a separate pi subprocess so this chat's context stays small.

Phased Execution

Phase state lives in files, not chat:

.agent/PLAN.md — master plan; LOCKED DECISIONS are binding
.agent/phases/todo/NN_name.md — pending phases (alphanumerical sort = execution order)
.agent/phases/complete/ — finished phases
.agent/reports/ — per-phase executor reports, stderr, and validation logs
.agent/validate.sh — the pass/fail gate for every phase

The scripts run each phase in a separate pi process (fresh context) with bounded fixer retries. A phase only moves to complete/ after the child exits 0, the child's stream ends with a clean final report, and .agent/validate.sh passes. This chat only dispatches and relays results — do not implement phase code yourself; that is what the subprocess is for.

Live display

While a phase runs, scripts/progress.mjs relays the child's JSON stream to the terminal: tool calls, assistant text, ◐ thinking… / ◑ thought for Ns indicators, yellow ⧉ compacting context lines (these can take minutes — not a hang), and provider auto-retry notices. If the child dies mid-flush and the stream loses the final message, the report is recovered from the child's session file (.agent/phase-sessions/), so a completed phase is never lost to a truncated stream.

Commands

(Resolve scripts/ against this skill's directory.)

Run the next phase, or a specific one:

bash scripts/run-phase.sh            # first pending phase
bash scripts/run-phase.sh 03_api.md  # specific phase (warns if out of order)

Run the whole pipeline — every pending phase, in order, stopping at the first phase that fails after all retries:

bash scripts/auto-phase.sh

Re-running auto-phase.sh after a failure continues where it stopped.

After a run

Exit codes: 0 = success (or nothing to run), 1 = phase failed after all attempts / no pending phases error, 130/143 = interrupted (Ctrl+C / SIGTERM). Failures always print a ✗ ERROR: line with the last error output — if the script's output looks like it ended abruptly, re-run it; the failed executor's session is resumed automatically (retries continue the child's own session, keeping its work).

Relay to the user: the phase name, its executor report (printed at the end of the script output), and the validation outcome. On failure, point the user at .agent/reports/<phase>.a*.{md,err,validate} — the script also prints a ready to run pi --session … -c “…” command to continue the failed session manually.

Configuration (environment variables)

Var	Default	Meaning
`MAX_FIX_ATTEMPTS`	`3`	Fixer retries per phase
`PHASE_MODEL`	session default	`--model` for child executors (e.g. `anthropic/claude-sonnet-4-5`)
`PHASE_THINKING`	session default	`--thinking` level for child executors
`PHASE_COMMIT`	`0`	`1` = `git commit --no-gpg-sign` after each passing phase
`PI_TRUST`	`0`	`1` = pass `--approve` (load project `.pi/` settings/skills into children)
`FRESH_FIX`	`0`	`1` = fixer retries start fresh instead of resuming the failed session
`QUIET`	`0`	`1` = suppress live progress display (reports are still written)

Setup notes

First run creates .agent/validate.sh from assets/validate.sh if missing. It must be adapted to the project's real checks — it is the authoritative quality gate.
Phase files are created by the /to-phase, /audit-create, /new-project, and /new-python-* prompt templates.
Child executor sessions are kept in .agent/phase-sessions/; add it to .gitignore if the project is versioned.
If you keep non-skill markdown (e.g. a README.md) in a skills directory (like ~/.pi/agent/skills/), pi warns “description is required” for it. Add a .gitignore in that directory listing the file — pi's skill scanner honors .gitignore, so the file is skipped.

4.2 KiB Raw Blame History