Release 0.2.28: bounded final recovery allowance and fenced SCM writes

CHANGELOG.md

@@ -2,6 +2,15 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
+## 0.2.28 — 2026-10-20
+
+- Let a current native factory administrator reserve one final fifth dispatch after a known, drained fourth official-CLI failure, with a sealed allowance and admission in the existing WAL transaction.
+- Bind the reservation to the reviewed current executable, source, original operator and current execution authority. Consume it at reservation, including a lost response or an attempt that never starts; refuse a sixth dispatch.
+- Keep legacy four-attempt recovery and worker-feedback contracts unchanged. Add a separate native allowance-bound feedback variant and typed SDK admission and readback methods.
+- Guide administrator review through failed attempt, mitigation and final confirmation. Retain the exact browser request before its single POST and recover an existing receipt after local storage is lost.
+- Recheck acquired execution ownership after source-control token preparation and the final authority callback, preventing a stopped or disconnected owner from posting feedback.
+- Refresh the controlled desktop/mobile walkthrough captures and document the difference between an administrator's mitigation attestation, process evidence and actual product verification.
+
 ## 0.2.27 — 2026-10-20
 
 - Preserve an inherited ignored `SIGXFSZ` for trusted Codex and Claude CLI launches under a finite POSIX file-size limit, allowing an oversized write to return `EFBIG` while retaining the kernel limit.

README.md

@@ -47,6 +47,8 @@ Choose and verify the execution environment before admitting a run. Git workspac
 
 On POSIX, trusted Codex and Claude launches preserve an inherited ignored `SIGXFSZ` when the parent has a finite file-size limit. The kernel limit remains enforced, and recovery still requires its existing process evidence and attempt budget. See [file-size failure recovery](docs/recovery.md#recover-a-known-failed-official-cli-attempt) for the launch conditions and qualification limits.
 
+After a known, drained fourth official-CLI failure, a native factory administrator can review [one final provider allowance](docs/recovery.md#review-the-final-allowance-in-studio) in the run's Plan tab. The wizard reviews the selected current CLI and source, records the administrator's mitigation attestation and reserves one fifth dispatch. The allowance is spent at reservation, even if its response is lost or dispatch never starts. Legacy recovery keeps its four-attempt limit; the final allowance cannot authorize a sixth dispatch or establish product QA.
+
 In Studio, a run's Plan tab can review an original queued command for explicit continuation after one controller replacement. The original Factory worker must still be waiting. The browser retains the request before submission and reads its exact receipt after a lost response. Follow the [continuation guide](docs/sandbox.md#continue-one-queued-command-after-a-controller-restart) for the admission and recovery limits.
 
 Open a paused run’s **Agent questions** tab to review the agent’s question and context. Choose a suggested answer or use the Markdown editor, review it, then send it under a retained response identity. Readback confirms the recorded answer after reload or a lost response; answering leaves the run paused until you resume it. Current project permissions and the authenticated replying user are checked separately from the recorded actor label. See [operator decisions](docs/agent-lifecycle.md#answer-an-agents-question).

docs/api.md

@@ -80,6 +80,22 @@ A native factory administrator can review `GET /runs/{id}/provider-recoveries/ca
 
 The strict body requires exactly one native process digest or explicit historical operator attestation. New-protocol unknown outcomes stay held. Current authority, source, provider and policy are checked again before launch, and all implementation intents count toward the four-dispatch limit. See [failed official CLI recovery](recovery.md#recover-a-known-failed-official-cli-attempt) for the proof fields, provenance and lost-response procedure. This change exposes HTTP endpoints only.
 
+### Final native recovery allowance
+
+The separate `/runs/{id}/provider-recoveries/allowances` surface reserves one fifth dispatch after a known native fourth-attempt failure. It requires a current native administrator with current execution authority. It accepts no historical process attestation or budget override.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/runs/{id}/provider-recoveries/allowances/candidate?agent=codex&adopt_current_executable=true` | Review the exact eligible failure and selected executable |
+| POST | `/runs/{id}/provider-recoveries/allowances` | Reserve and consume the one lifetime final allowance |
+| GET | `/runs/{id}/provider-recoveries/allowances/{request_id}` | Read the exact receipt as the original current operator |
+
+The strict POST body contains `request_id` (32 lowercase hexadecimal characters), `candidate_digest`, `native_process_digest`, `mitigation_evidence_digest` (each 64 lowercase hexadecimal characters), `agent` (`codex` or `claude`), `adopt_current_executable` (required literal `true`), and a nonblank `reason` of at most 2,000 characters. The mitigation digest is an administrator attestation, not server-generated QA evidence. HTTP201 retains a version-2 receipt with protocol `native-provider-recovery-allowance-v1`; the HTTP request does not execute inference.
+
+Same ID, body and current operator return the existing receipt. A stale candidate, different request, revoked authority or spent allowance refuses without another reservation. A missing response never renews eligibility. Legacy recovery routes retain their existing schemas and four-dispatch limit; reading a final allowance through the legacy receipt route returns HTTP409 identifying the new endpoint. See [the recovery procedure](recovery.md#reserve-one-final-native-provider-attempt) for launch checks, executable limits and lost-response handling.
+
+Fifth-attempt worker feedback uses `protocol: "native-provider-recovery-allowance-v1"`, literal `attempt: 5`, `role_id: "implementer"`, `task_id: "implement"`, `allowance_id` and `allowance_digest`, alongside the usual feedback fields. The native journal checks the actual consumed reservation and current authority before accepting it. Legacy `WorkerFeedback` remains limited to attempts 1–4.
+
 | Method | Path | Operation |
 | --- | --- | --- |
 | GET | `/health` | Inspect server health |

docs/architecture.md

@@ -254,6 +254,39 @@ An unknown remote publication, deployment or memory write cannot be generically
 
 Known official-CLI process failures have a separate same-run recovery admission. Its candidate binds current administrator authority, source, Git identity, provider settings and the original failed task. An optional executable adoption adds a server-derived file identity and SHA-256 to that cut. The admission, reservation and dispatch WAL retain the reviewed descriptor; each execution boundary rechecks it. The Engine builds a separate provider for that task with only the executable setting overlaid, so later normal repairs retain the original model configuration and CLI. See [updated CLI recovery](recovery.md#adopt-an-updated-cli-for-one-recovery) for the HTTP contract and installation limits.
 
+The final provider allowance is a separate administrator reservation after a known native fourth-attempt failure. Under the existing PostgreSQL identity, membership and run locks, it appends `provider_recovery_allowance`, its linked version-2 admission, the closed failure and one fifth implementation intent. The allowance is spent at reservation, including an unlaunched or failed dispatch. Candidate review binds the existing source/configuration cut and explicitly adopted CLI identity; no repair or verification grant is reset. The Engine and native feedback writer require the same sealed WAL link and current authority. The legacy recovery and worker-feedback contracts keep their four-attempt bound. See [the final allowance contract](api.md#final-native-recovery-allowance).
+
+<div class="forge-flow" role="region" aria-label="Final native provider allowance ordering" aria-describedby="final-allowance-flow-guide" tabindex="0" markdown="1">
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+  F["Fourth native<br/>process failure"] --> C["Administrator reviews<br/>exact candidate"]
+  C --> R["Atomic reservation<br/>and linked WAL"]
+```
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+  R["Reserved<br/>allowance"] --> G["Recheck authority,<br/>source and executable"]
+  G --> D["One fifth<br/>dispatch"]
+  D --> V["Independent<br/>verification"]
+  R --> H["Uncertain or refused:<br/>preserve reservation"]
+  D --> H
+```
+
+</div>
+
+<p class="forge-flow-caption" id="final-allowance-flow-guide">The first row commits the one-use reservation. The second follows execution under renewed checks; an uncertain or refused outcome keeps that reservation spent. Verification remains a separate stage. On a narrow screen, scroll horizontally or focus the diagram and use the arrow keys.</p>
+
 Bridge completion requests follow the same uncertainty rule. A transport failure, unusable completion or cancellation during an unfinished submission retains the original intent and workspace for reconciliation. Local cancellation stops scheduling but cannot establish the remote result. The hold survives cancelled, interrupted or failed run status; resume, handoff and replacement retry check it before dispatch. Recovery of the original Bridge job is not automated. See [provider failure handling](agents.md).
 
 Opt-in implementation checkpoints support explicit continuation at the original model boundary. The checkpoint and Bridge intent commit together before the completion POST. A bounded, read-only candidate projection verifies the retained journal, current authority and original ticket bindings before Studio offers a review. The projection makes no Bridge call and writes no ticket or consume receipt.