Show Codex MCP activity and distinguish retained verification

CHANGELOG.md

@@ -2,6 +2,24 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
+## 0.2.30 — 2026-10-20
+
+- Present bounded Codex MCP server, tool, reported status and text output in Studio without treating provider reports as native runner receipts or product QA.
+- Name the known configured-check tool clearly and keep its exact identity under a disclosure. Retain exact bounded identities for other tools.
+- Preserve existing archive limits, integrity checks and explicit full-event reads; unsupported structured results remain available only through the retained event.
+- Label retained previous-attempt verification before its totals in recovery feedback. Keep current-attempt checks distinct without changing delivery identities or replay rules.
+- Refresh the controlled desktop/mobile walkthroughs and document the distinction between actual finite-client messages, presentation fixtures and product acceptance.
+
+## 0.2.29 — 2026-10-20
+
+- Let an administrator grant selected retained checks to one future official-CLI recovery through a separate scoped MCP channel, with explicit limits and current source, actor and execution authority checks.
+- Run check requests through the native runner and WAL using only a configured command index and retained request identity. Preserve known readback, unknown-effect holds and independent final verification capacity.
+- Bind the grant to the final recovery request before reservation. Keep the original four-attempt contract, one-use fifth allowance, runner budgets and historical snapshots unchanged.
+- Guide Studio administrators through check review, explicit grant, mitigation and final reservation. Retain exact request bodies before each single POST; hold uncertain responses, revoked access and missing browser records for authorized readback.
+- Add strict SDK and CLI grant, current-status, exact-receipt and revocation operations. Keep the 162 operator MCP tools separate from the one-tool coding channel and add two native Agentic prompt resources.
+- Select asyncio explicitly for the API server and refuse a known uvloop host with a finite file-size limit before trusted CLI dispatch intent or launch. Preserve the kernel limit and all spent task and reservation history.
+- Refresh the controlled desktop/mobile walkthroughs for 0.2.29, including the four-step grant journey. These fixtures and protocol tests do not establish live official-CLI tool use or generated-product acceptance.
+
 ## 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.

Dockerfile

@@ -6,6 +6,7 @@ RUN npm ci
 COPY studio/ ./
 COPY tests/fixtures/activity-archive-contract-v1.json /build/tests/fixtures/activity-archive-contract-v1.json
 COPY tests/fixtures/activity-claude-contract-v1.json /build/tests/fixtures/activity-claude-contract-v1.json
+COPY tests/fixtures/activity-codex-mcp-v1.json /build/tests/fixtures/activity-codex-mcp-v1.json
 RUN npm run build
 
 FROM python:3.13-slim-trixie

README.md

@@ -37,18 +37,20 @@ A passing run records its verified source and local checkpoint. Publication rech
 
 Review an [incremental product change](docs/product-lifecycle.md) against its saved revision before adding a feature or integration. Studio retains the original save request and any later draft separately when the outcome is uncertain. Journey references show linked behavior and acceptance criteria; review them against the product's intended experience before implementation.
 
-Read the run's [retained evidence](docs/run-evidence.md) to distinguish coding-provider activity from final factory verification. Studio distinguishes Codex command results from Claude tool requests, reported results and provider messages. Complete sanitized event content is available on demand within archive limits; provider reports remain separate from factory verification. SDK, CLI and MCP readers use the same current permissions and exact content descriptor.
+Read the run's [retained evidence](docs/run-evidence.md) to distinguish coding-provider activity from final factory verification. Studio distinguishes Codex command results and reported MCP activity from Claude tool requests, reported results and provider messages. Known configured-check calls use a human title with their exact tool identity available separately. Complete sanitized event content is available on demand within archive limits; provider reports remain separate from factory verification. SDK, CLI and MCP readers use the same current permissions and exact content descriptor.
 
 ## Choose how the factory executes work
 
 The default combined service admits and executes work. A split installation separates API replicas from headless workers: one execution leader runs the jobs while other workers wait as standbys. Processes share the PostgreSQL ledger and retained private storage. Standbys provide takeover; they do not add a distributed pool of active workers. See [runtime roles](docs/runtime-roles.md) and [factory infrastructure](docs/factory-infrastructure.md).
 
 Choose and verify the execution environment before admitting a run. Git workspaces protect the consumer checkout; host commands still run with the worker's operating-system identity. Project users require isolated execution, while host coding and host verification require current administrator authority. [Runner configuration](docs/sandbox.md) and [security](docs/security.md) describe the enforced boundaries.
 
-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.
+With the stdlib asyncio event loop on POSIX, trusted Codex and Claude launches preserve an inherited ignored `SIGXFSZ` when the parent has a finite file-size limit. `forge serve` selects this loop explicitly. External ASGI hosts must also use asyncio; a known uvloop host with a finite file-size limit is refused before the provider dispatch intent or child launch. The kernel limit and spent recovery history remain unchanged. 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.
 
+A recovery can also use [explicitly granted configured checks](docs/recovery.md#grant-configured-checks-for-the-final-recovery). Review the retained commands, runner and budget, grant access for one identified recovery, then reserve that final attempt separately. The scoped tool cannot submit arbitrary commands; successful interactive checks remain separate from independent final verification. SDK and CLI operators use the same grant and receipt contracts.
+
 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/agent-integrations.md

@@ -283,6 +283,24 @@ forge product apply-change REPOSITORY_ID change.json
 
 Python exposes `model_profiles`, `save_model_profile`, `test_model_profile`, `task_routing`, `save_task_routing`, `preview_product_change` and `apply_product_change`. Typed configuration methods can receive secrets from an application secret manager. The SDK filters profile responses and suppresses configuration errors that could reflect a submitted secret.
 
+## Grant check access to a coding recovery
+
+The scoped coding channel is separate from `forge mcp`. It lets an official Codex or Claude invocation request selected checks already retained by the run. The caller supplies a command index and request identity; the factory owns the actual command, runner, current authority and budget. It does not expose the operator token or the factory's 162 operator tools to that coding process.
+
+Use the native SDK methods `coding_check_candidate`, `grant_coding_checks`, `coding_check_receipt`, `coding_check_current` and `revoke_coding_checks`, or the matching CLI commands:
+
+```sh
+forge coding-check-grants candidate RUN_ID FUTURE_RECOVERY_REQUEST_ID --bind-port 0
+forge coding-check-grants grant RUN_ID reviewed-grant.json
+forge coding-check-grants get RUN_ID ORIGINAL_GRANT_REQUEST_ID
+forge coding-check-grants current RUN_ID
+forge coding-check-grants revoke RUN_ID reviewed-revocation.json
+```
+
+Prepare the JSON document from the reviewed candidate and [strict request fields](api.md#scoped-coding-check-grants). Keep its grant request ID and future recovery ID before the write. Each SDK or CLI operation makes one explicit request; an uncertain write requires reading its original receipt. A historical receipt does not establish current active status.
+
+After the grant is confirmed, read the final-allowance candidate again and explicitly reserve with the same future recovery request ID and `coding_check_grant_id`. Grant creation does not itself reserve a dispatch, and a refused linked flow cannot silently become CLI-only recovery. The [Studio journey](recovery.md#grant-configured-checks-for-the-final-recovery) illustrates these separate decisions with controlled fixtures. Native runner receipts and independent final verification determine the actual outcome.
+
 ## MCP
 
 Operators can inspect an uncertain learning invalidation through Python `learning_invalidation_receipt(record_id, request_id)`, `forge learning invalidation-receipt RECORD_ID --request-id REQUEST_ID`, or `get_learning_invalidation_receipt`. Each performs the same authorized GET for the exact committed request. The returned historical decision does not replace the current record state. A 404 remains unobserved evidence and never triggers a second write. Keep the original request identity and reason; see [invalidation receipts](learning.md#inspect-an-uncertain-invalidation).

docs/api.md

@@ -96,6 +96,42 @@ Same ID, body and current operator return the existing receipt. A stale candidat
 
 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.
 
+### Scoped coding-check grants
+
+These routes require a current native factory administrator and execution authority. They grant selected retained checks to one preallocated final recovery request; they do not reserve or execute the coding dispatch.
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/runs/{id}/coding-check-grants/candidate?recovery_request_id=ID&bind_port=0` | Review the retained commands, runner, source/authority cut and remaining budget |
+| POST | `/runs/{id}/coding-check-grants` | Record the explicit grant once |
+| GET | `/runs/{id}/coding-check-grants/{request_id}` | Read the original grant or revocation receipt |
+| GET | `/runs/{id}/coding-check-grants/current` | Inspect current grant identity, revision, status, receipt fingerprint and expiry |
+| POST | `/runs/{id}/coding-check-grants/revocations` | Revoke the exact current grant revision |
+
+The strict `CodingCheckGrantInput` rejects extra fields:
+
+| Field | Required review |
+| --- | --- |
+| `request_id` | Grant request identity: 32 lowercase hexadecimal characters |
+| `recovery_request_id` | Future final-allowance identity: 32 lowercase hexadecimal characters, retained before granting |
+| `candidate_digest` | The candidate's opaque 64-character SHA-256 fingerprint |
+| `expected_revision` | The candidate's nonnegative grant revision |
+| `command_indices` | One to twenty distinct configured indices, each 0–19 and present in the candidate |
+| `call_limit` | One to twenty invocations, no more than available interactive capacity; calls may repeat a selected index |
+| `valid_seconds` | Lifetime of 30–3600 seconds, also enforced during invocation |
+| `bind_port` | `0` by default for automatic loopback selection, or a fixed port from 1024–65535 |
+| `reason` | A nonblank explanation of at most 2,000 characters |
+
+The candidate separates `interactive_commands_remaining` from `independent_final_check_count`. Configured and policy checks together remain subject to the existing final-verification limit of 20. Grant creation cannot reset that limit or the frozen shared runner budget.
+
+The immutable grant receipt returns an opaque `receipt_digest`. Compare it with `/current`, along with grant ID, revision and expiry; do not recompute a native receipt hash from client-side JSON numbers. Only `active` current status can authorize the linked path. `none`, `revoked` and `expired` retain their distinct meanings, and an old receipt never overrides current permission or revocation checks.
+
+A revocation request requires its own `request_id`, the exact `grant_id`, current positive `expected_revision` and a `reason` of 1–2,000 characters. Read that original request ID after an uncertain response. The active grant and revocation records remain in the WAL; revocation cannot erase prior effects.
+
+After grant confirmation, refresh the final-allowance candidate and include `coding_check_grant_id` when reserving under the original `recovery_request_id`. Legacy CLI-only allowance bodies keep their existing wire shape. The scoped MCP tool accepts only `command_index` and its own 32-character request ID; it cannot choose a run, provider, directory, arguments, environment or timeout. See [the recovery procedure](recovery.md#grant-scoped-configured-checks-to-an-official-cli).
+
+## Factory endpoints
+
 | Method | Path | Operation |
 | --- | --- | --- |
 | GET | `/health` | Inspect server health |

docs/architecture.md

@@ -287,6 +287,42 @@ flowchart LR
 
 <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>
 
+### Scoped configured-check execution
+
+An official coding CLI can receive a separate, explicitly granted `run_configured_check(command_index, request_id)` tool for one final recovery. `CodingCheckGrants` binds the current administrator, future recovery identity, retained commands and runner, source/authority cut, call cap and expiry. Grant admission advances the WAL but consumes no provider dispatch. The final allowance must then name that grant and the same preallocated recovery request.
+
+The parent provider opens an invocation-scoped MCP endpoint on literal loopback. Its closure owns run, task, actor and lease identity; the model supplies only a retained command index and a request ID. `CodingCheckRuntime` checks current authority and budget around credential admission, resolves arguments internally, and calls the existing `SandboxExecutor`. Known results retain their observed source and receipt. A legitimate implementation edit can be checked again within the cap, while an unknown effect holds the invocation rather than allowing another identity to replay it.
+
+<div class="forge-flow" role="region" aria-label="Scoped configured-check grant and execution" aria-describedby="coding-check-flow-guide" tabindex="0" markdown="1">
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+  C["Review retained<br/>checks and limits"] --> G["Grant one future<br/>recovery request"]
+  G --> A["Reserve linked<br/>final attempt"]
+```
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+  L["Official<br/>coding CLI"] --> T["Scoped<br/>check tool"]
+  T --> W["Native runner<br/>receipt and WAL"]
+```
+
+</div>
+
+<p class="forge-flow-caption" id="coding-check-flow-guide">Review and grant before reserving the linked attempt. Each interactive call repeats current authority, source and budget checks; independent final verification follows separately. On a narrow screen, scroll horizontally or focus a diagram and use the arrow keys.</p>
+
+The coding channel is separate from the 162-tool operator MCP server. Its token is invocation-scoped, expires no later than the provider deadline, and is removed from streams and retained activity before storage. Accepted effects drain before teardown. Codex retains `workspace-write`; Claude uses an explicit private MCP configuration with strict server/tool selection. These adapters do not make general role-tool declarations enforceable inside an official CLI. A host runner retains service-account execution with timeout/output controls, without filesystem or network isolation. The grant changes no original snapshot, repair allowance or shared runner budget. See [the recovery journey](recovery.md#grant-configured-checks-for-the-final-recovery) and [native API contract](api.md#scoped-coding-check-grants).
+
 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.