docs(queen): design for self-healing recoverable blockers

[gHashTag]

What

Adds trios/agent-server/docs/queen-self-heal.md — a design for making the Queen resolve the recoverable blockers she currently parks for a human, per the owner's ask ("королева сама чинит все блокеры").

Grounding

Written from live dispatch/review logs on the production trios-agent-server (2026-09-27) and a read of the engine sources (QueenReviewDecision.swift, QueenBoundaryPaths.swift, queen-tick.ts, QueenSpecQuality.swift). Over ~15 min the swarm was healthy — accept×5 / send×5 / wait / escalate×3 / empty×2 — but the escalate/empty/loop cases each needed a person.

Five recoverable blocker classes → bounded self-heal

1. Out-of-boundary work (#4871/#4872/#4874) → auto-widen the boundary to the repeatedly-needed paths, capped, collision-checked, audited.
2. Empty diff (#4869/#4870) → retry once on the next ranked model, bounded by the candidate list.
3. Transient reviewer timeout (#4871, "nothing was spent") → re-run the review once (idempotent).
4. Missing acceptance criteria → derive them from the issue's own scenarios/boundary, marked Queen-derived; never invent an issue or a boundary.
5. Retry-ceiling holds the issue forever (t27#4886 ← feat(claw-app): restyle the MCP page and calm the audit page's live signals browseros-ai/BrowserOS#2164, re-filed by hand) → reset the retry budget once when the brief has changed.

Invariant: no correctness gate is weakened — work that fails its criteria is still sent back/escalated, an empty diff never becomes an accept. Each heal ships with a gate-preservation control test.

Why draft / not implemented

This is design only. It's a trios/agent-server engine change (roadmap stage 2) that must be built and tested where the engine's bun deps and a Postgres are available — it cannot be validated from a read-only session. Opened as a draft for a maintainer to implement and validate.

🤖 Generated with Claude Code

https://claude.ai/code/session_01FJktaYxNrfAUdxSwdQw3gV

---

Generated by Claude Code

[gHashTag]

The one red check here is cla (Contributor License Agreement) on the commit. That's a repository-policy gate, not a defect in this diff — and it's not something I can clear: signing a CLA is the author/owner's action. The commit is authored as the repo owner (raoffonom@icloud.com) via the GitHub App, so this likely just needs the owner to accept the CLA (or a maintainer to whitelist the app commit).

This is a draft, docs-only PR — one new file, trios/agent-server/docs/queen-self-heal.md, a design write-up. Nothing to build or test. I'm not driving it to green (the CLA is yours to clear); it's parked for a maintainer to review the design and implement it where the engine builds.

---

Generated by Claude Code

[gHashTag]

Closing this — the design overclaims. After building the engine locally (bun install, bun test green) and reading queen-tick.ts / queen-reviewer.ts, most of what this doc proposes already exists on this branch:

• Empty attempt → free_attempts + FREE_ATTEMPT_CEILING: an empty attempt is released and, after a bounded count, escalates. (my "heal feat(providers): add Moonshot API compatibility + fix Z.AI endpoint #2" — already there)
• Spent retry ceiling → ceiling_releases + MAX_CEILING_RELEASES = 1: "the bee gets maximumSendBacks attempts, then an hour, then one more" — a spent ceiling IS handed back to the swarm once. t27#4886's "keeps its issue for good" describes older behavior. (my "heal feat(trios): Queen supervisor - delegation, observability, skills, replay #5" — already there)
• Transient reviewer failure → isTransientReviewerError + sawTransient: "a transient refusal tries the next lane too" and does not markReviewerLaneFailed. (my "heal feat(zai): switch z.ai to OpenAI-compatible coding endpoint #3" — already there)

So the escalate verdicts observed in the live logs are the engine correctly escalating after bounded automatic retries — the intended design, not a missing self-heal. The one thing genuinely absent (auto-widening a boundary) is deliberate: widening is the collision the boundary prevents. Writing missing acceptance criteria automatically is likewise a faith-acceptance the engine deliberately refuses.

My mistake was designing from log symptoms before reading the retry/ceiling machinery. Closing rather than leaving a design that misrepresents the engine. No code was pushed.

---

Generated by Claude Code

[github-actions]

⚠️ No test results were produced

View workflow run