# Changelog

## 0.5.3 — 2026-08-03

- Add hybrid `DIRECT`/`PLAN`/`EXECUTION-CONTRACT` routing: clear tasks proceed directly, ambiguous tasks retain advisor plans, approved plans stay authoritative, and materialized skills run actor-first with bounded review.
- Add opt-in `actor-first-reviewed`: one failure rescue, private ordered final review, one persisted correction, fail-closed withholding, and `/pi-moa retry-review`; `brain-once` with `finalGate:false` remains the default.
- Bundle actor-aware DeepSeek V4/GLM guidance, schema-shaped argument repair, exact-write and safety guards, recovery hints, and conditional `apply_patch` registration without overriding Pi's built-ins.
- Stream each Advisor's transient, secret-redacted reasoning tail and partial Markdown while retaining bounded final-response cards outside model context.
- Compared with 0.5.2, replace unanimous parallel final approval with ordered availability fallback, strengthen approved-plan and materialized-skill handling, and preserve the configured effective actor in status and response metadata.
- Document source-patch-free Serena and FFF integration through `PI_SERENA_REMIND_ON_FIRST_MISS=1` and `PI_FFF_MODE=override`; external tool definitions continue to pass through unchanged.

## 0.5.3-brain-on-demand — 2026-07-28

- Make `actor-first-reviewed` the built-in and shipped-example default: the actor begins immediately, successful tool batches stay actor-only, and no initial planning advisor runs.
- Add one provider-owned read-only rescue after the first failed current-turn tool batch. The rescue is consumed even when unavailable; later failures do not create a controller loop.
- Privately buffer terminal candidates and require a JSON final verdict with per-requirement `PASS | FAIL | MISSING` checks and evidence. Configured advisors run as ordered availability fallbacks under one shared deadline; the first valid verdict is authoritative.
- Permit one evidence-backed actor correction and one re-review. Persist the immutable turn envelope, rescue/correction count, guidance, candidate digest, and bounded sanitized pending-review packet across tool calls, reloads, and branch restoration; a second `REVISE` withholds.
- Fix no-user continuation identity: never infer a user turn from assistant/tool/custom messages, reuse restored active-turn state, reject stale results, and make zero model calls when no real/restored turn exists.
- Add `/pi-moa retry-review` and the TUI retry action. Unavailable/malformed final review keeps the candidate local and retries only that same final packet—never actor execution or planning first.
- Add `advisorWorkflow: "actor-first-reviewed" | "brain-once"`, workflow-aware status/settings, mandatory `finalGate:true` validation for actor-first, and safe legacy migration: files without the field load as brain-once and preserve the old missing-gate behavior until saved.
- Keep brain-once parallel planning, raw advisor plans, failure checkpoints, and optional final gate selectable. Both workflows share ordered structured final-review semantics and correction persistence.
- Extend safe diagnostics and benchmark aggregation with workflow, rescue/final stages, review attempt, correction count, fallback order/selection, verdict, digests, and withheld status. No dependency or model-slot topology changed.

## 0.5.2 — 2026-07-26

- Mark `Fusion Fast` as the stable, recommended daily preset and `Fusion` as improving while its two-advisor quality, latency, and token tradeoff continues to be tuned.
- Keep final-gated tool turns private by releasing only actor `toolCall` blocks, stripping nested thinking/prose, and removing MoA wrappers and provider labels from actor execution and correction guidance.
- Accept a valid trailing `REVISE` block after final-review preamble text and pass only that block to the actor. `APPROVE` remains exact, unanimous, and fail-closed.
- Restore nested DeepSeek tool routing under Fusion Fast without modifying external extensions: use Serena first for semantic code work and direct `bash` first for explicit run/build/lint tasks, while leaving discovery prompts unaffected.
- Validate the routing change in 48 matched runs: Fusion first-tool correctness improved from 21/24 to 24/24, required sequences from 21/24 to 23/24, corrected completion from 20/24 to 24/24, blank finals from four to zero, Serena-first from 0/3 to 3/3, and bash-first from 2/3 to 3/3.

## 0.5.1 — 2026-07-26

- Promote the Fusion Fast built-in acting model from MiMo V2.5 to DeepSeek V4 Flash, matching the shipped Fast example and verified live topology while preserving existing model-slot overrides.
- Evaluate every result in the latest actor tool-call batch before deciding whether to checkpoint, so a failed parallel call cannot be masked by a later successful sibling while a newer all-success batch still supersedes already reviewed failures.
- Make the opt-in final gate fail closed. Only unanimous valid `APPROVE` verdicts release a candidate; malformed or unavailable reviews and a second `REVISE` after the single correction withhold private candidates with stable errors.
- Strengthen generic planning and review evidence: map every explicit requirement to a finite criterion, verify unavailable current external facts before use, keep dependent operations sequential, and require redacted effective-state evidence for setup/deployment work instead of treating health as proof of unrelated controls.
- Document a live Fusion Fast validation that completed 9/9 representative Serena, FFF, Munin, Brave/pi-web, and RTK calls with one plan, the opt-in final review, and an observed RTK rewrite in the real tool event chain.
- Verify failure-checkpoint recovery on a local Crawl4AI 0.9.2 deployment: failed health evidence exposed its secure-by-default loopback binding, the corrected authenticated deployment passed direct health/PNG/PDF checks, and all seven pi-web tools passed afterward. This validates orchestration and external-tool integration; Pi MoA does not install or bundle those services.

- Add opt-in `advisorContextMode: "session"` so an initial plan advisor can use Pi's already compacted, sanitized prior session context for a follow-up after a completed task or when a user stops, switches to Fusion/Fusion Fast, and continues. The compatible default remains `turn`; failure checkpoints and final reviews stay turn-scoped.
- Derive the advisor input budget from the smallest configured advisor model's actual registry `contextWindow` using Pi's conservative chars/4 convention. Reserve the stage output/reasoning allowance, system prompt, up to eight bounded read-only tool results, tool schemas, and provider overhead. `maxAdvisorContextChars: 0` enables automatic budgeting; a positive value remains an optional smaller failsafe and never bypasses model capacity.
- Budget session context current-turn first and middle-truncate only remaining history when the computed safe budget is insufficient. Contexts continue excluding assistant draft prose, hidden thinking, image bytes, and normal tool arguments.
- Record model-window and reserved tokens, effective budget source/characters, configured/effective scope, and source/sent/truncated character counts in safe advisor diagnostics. Add Fusion/Fusion Fast context selectors and status output to `/pi-moa` without overwriting unrelated settings.
- Persist generated plans as Pi custom entries outside LLM context and restore them only for the exact user-turn key after reload/resume. Approved `pi-plan` handoffs execute directly without another planning-advisor call; failure checkpoints and the optional final review remain distinct.
- Run opt-in final-gate verdicts with `minimal` reasoning and at most 4096 output tokens while leaving plan/checkpoint reasoning, output budgets, recovery, and the 180-second deadline unchanged.
- Add deterministic regressions for full automatic session handoff, current-turn budget priority, explicit-cap safety, checkpoint/final isolation, history-sensitive cache keys, exact-turn plan restoration, approved-plan direct execution, and context diagnostics.
- Let `/pi-moa` set advisor reasoning independently for Fusion and Fusion Fast, restricted to `high` or `max`, and pair it with the preset token budget: Fusion 16k/32k and Fusion Fast 8k/16k per advisor. Existing configs default to `high`; bounded recovery remains `minimal`.
- Preserve each uncached advisor's labelled final response in the existing `pi-moa-advisor-activity` session card before the actor starts. This exposes visible advisory output—not provider-hidden chain-of-thought—without changing model calls, orchestration, actor context, usage, or diagnostics.
- Keep cards compact by default and show bounded multiline output when expanded. Persisted display copies strip terminal control characters and retain at most 20,000 Unicode code points per advisor without splitting surrogate pairs; authoritative actor guidance remains unchanged.
- Keep cache hits and successful actor-only continuations silent, and continue excluding advisor output from public actor messages, `pi-moa.advisor` diagnostics, credentials, raw provider errors, and tool arguments.
- Scope release CI to `npm audit --omit=peer`. Pi's core packages are unbundled host-provided peers, while official `@earendil-works/pi-coding-agent@0.82.0` still shrinkwraps `brace-expansion@5.0.7`; downstream overrides and lockfile-only edits do not replace the installed bytes. This removes a false `pi-moa` release blocker without claiming the [upstream advisory](https://github.com/advisories/GHSA-mh99-v99m-4gvg) is fixed; upstream tracking is [earendil-works/pi#7090](https://github.com/earendil-works/pi/issues/7090).
- Verify the final installation paths. A fresh Pi 0.82.0 managed install adds only `pi-moa`, auto-installs no Pi peers, reports zero vulnerabilities and no package warnings/deprecations, loads exactly Fusion/Fusion Fast, and `/pi-moa` status starts no model. A raw `npm install` outside Pi may auto-install the upstream peers and display their deprecation, install-script, and one-high-severity audit notices; an existing Pi-host audit has the same sole `brace-expansion` finding before and after adding `pi-moa`. An environment-dependent npm client update notice is not a `pi-moa` warning.
- Keep canonical `pi-plan` Plan Mode writes draft-only for `pi-moa`, then return a zero-token local completion after a successful `write_plan` so Pi settles and `pi-plan` can prefill `/plan-approve` before any further advisor or actor call. This prevents self-approval and premature implementation loops without modifying `pi-plan`.
- Preserve consequential-question handoffs through `ask_plan_question`: the actor retains the Plan Mode system/tool contract, waits for the user answer, then resumes planning and may write the draft. Deterministic regressions cover no early `write_plan`, approval, or implementation, and no follow-up inner model call while the question awaits its answer.

## 0.5.0 — 2026-07-24

- Recover advisor timeouts without extending the existing 180-second ceiling: reserve up to 30 seconds for one tools-off `minimal` finalization and salvage substantial streamed plan text when available. Deterministic tests cover the timeout path, partial-plan salvage, and fail-closed explicit cancellation.
- Recover zero-visible-text responses through the same bounded one-shot path instead of repeating the normal advisor call with tools and higher reasoning.
- Stop re-injecting failed advisor placeholders and degraded wording after actor work begins; retain usable plans and continue from current tool evidence.
- Add safe per-advisor diagnostics for provider/model, elapsed time, attempts, stop/failure reason, recovery outcome, timeout source, token usage, and redacted provider-error class without exposing raw errors or credentials.
- Validate the exact `openai-codex`, `opencode-go`, and `zai` routes in integration tests and a fresh live coding E2E. All three providers completed both plan and failure-checkpoint stages; the live run exercised real empty-response recovery for the OpenCode plan and Z.AI checkpoint and passed public/private verification.

## 0.4.6 — 2026-07-24

- Implement **brain once, hands many**: one retained advisor plan per user turn, direct actor continuation after successful tool results, and an advisor checkpoint only after the latest failed result. Missing in-memory state safely rebuilds the plan.
- Bound each advisor batch to 180 seconds (or a shorter inherited timeout), degrade timeouts to actor self-check guidance, and keep explicit cancellation fail-closed.
- Make plan advice concise and executable: cohesive batches, evidence-backed files/symbols, one important task-derived edge case, an exact completion check, and no repeated passing command.
- Ship `pi-moa-fast.example.json` as the controlled-test topology `openai-codex:gpt-5.4-mini` → `opencode-go:deepseek-v4-flash` with an 8000-token advisor cap; built-in defaults remain unchanged pending broader evidence.
- Reuse Pi's authenticated ZAI Coding Plan provider (`zai`) in `/pi-moa` and the existing `pi-plan` approved-file handoff; no duplicate provider or planner workflow is added.
- Remove the per-success controller-packet boundary from Fusion Fast. Checkpoint output cannot replace the retained plan or actor tool catalog, while config, workspace-path, and approved-plan validation remain strict.

## 0.4.5 — 2026-07-23

- Add `zai` (Z.AI) to the `/pi-moa` model picker so authenticated Z.AI models can be selected for any Fusion or Fusion Fast advisor or actor slot, alongside `opencode-go` and `openai-codex`.
- Extend the shared advisor edge-case checklist with async/background-task exception ownership: when generated code relies on background tasks, shared futures, or any deferred result a caller can abandon before completion, plan and checkpoint advisors now steer it to keep a strong reference and observe the outcome through a completion callback (e.g. Python `add_done_callback`) that retrieves the result or exception even when no waiter remains, targeting silently dropped failures such as Python's "Task exception was never retrieved". On the frozen `async_memo` fixture, Fusion Fast's clean-edge pass rate rose from 2/5 to 5/5 and a single run reached 6/6; the tradeoff is greater advisor focus, which raised median wall time (~+76%) and timeouts (1/5 to 2/5) on that fixture.

## 0.4.4 — 2026-07-21

- Give plan and checkpoint advisors bounded workspace-scoped `read`, `grep`, `find`, and `ls` exploration, with traversal/symlink containment, aggregated usage, a highlighted live activity row, and a persistent tool-style session card.
- Raise the advisor output cap from 8k to 16k and retry one transient zero-output response before degrading.
- Treat existing detailed plans, including approved `pi-plan` files, as authoritative; advisors add mapped execution/TDD guidance instead of replacement plans, while implementation checkpoints remain active.
- Keep private checkpoint-format guidance out of actor narration while continuing the next unfinished plan item.

## 0.4.3 — 2026-07-20

- Add an interactive `/pi-moa` TUI menu for changing authenticated Fusion and Fusion Fast model slots while preserving direct status output in non-interactive modes.

## 0.4.2 — 2026-07-20

- Show uncached advisor plan/checkpoint activity in Pi's transient working row.

## 0.4.1 — 2026-07-20

- Document the 0.4.0 upgrade path and its provider-enforced plan/checkpoint behavior.

## 0.4.0 — 2026-07-20

- Replaced actor-initiated `pi_moa_review` with provider-enforced advisor execution before every actor request.
- Added an initial ordered-plan stage and automatic `PASS`/`REVISE` checkpoints after each changed Pi tool-result batch.
- Clarified malformed checkpoint verdicts as format failures so actors do not invent task defects or repeat passing checks.
- Cache identical plan/checkpoint contexts, charge only newly executed advisor usage, and expose safe stage/cache/degradation diagnostics.
- Removed the actor-facing advisor tool from runtime and benchmark tool allowlists.

## 0.3.2 — 2026-07-16

- Changed Fusion advisors from `openai-codex:gpt-5.6-sol` to `opencode-go:glm-5.2` and `opencode-go:kimi-k2.6` (2 advisors instead of 1).
- Changed Fusion Fast's actor from `opencode-go:deepseek-v4-flash` to `opencode-go:mimo-v2.5` after the operational pilot completed 3/3 trials and solved the task where Flash timed out.
- Removed the unpublished `/pi-moa:status` alias; use `/pi-moa`.
- Changed both presets from upfront advisor notes to actor-first execution with one Pi-native `pi_moa_review` call on the actor's first final candidate, followed by the actor's reviewed response.
- Bound review to one paid advisor batch per user turn, charge its usage once to the next actor message, and degrade to stable failure categories plus a self-check when advisors fail.

## 0.3.1 — 2026-07-14

- Preserve the last complete advisor batch when a refresh fails, while retaining the latest attempted fallback when no complete batch exists.
- Reject retired 0.2.9 fields and unknown config keys with value-free migration guidance. Current-shaped 0.3.0 configs remain accepted unchanged.
- Replace raw advisor failures with stable categories, structured diagnostics, and one visible degraded-run warning; cancellation still aborts before the actor.
- Restore `/pi-moa:status` as a deprecated alias and report each preset independently from `/pi-moa`.
- Require Node 22.19.0+, publish this changelog, and add reproducible source, tarball, and provenance release gates.

## 0.3.0 — 2026-07-13

- Simplified both presets to one tool-free advisor batch followed by one streamed acting-model call; removed draft, verifier/revision, and full-trace stages.
- Changed Fusion to `openai-codex:gpt-5.6-sol` advising `opencode-go:deepseek-v4-flash`; Fusion Fast uses `opencode-go:glm-5.2` with the same actor.
- Resolve each inner model's authentication through Pi and discard wrapper credentials before inner requests.
- Removed legacy verifier, trace, refresh-count, and advisor-context policy fields from the supported config shape.
- Added bounded per-turn advisor attempts, complete-batch caching, sanitized advisor context, and capability-v3 benchmark provenance.