Add consented GitHub clarification continuation and Claude activity in 0.2.26

CHANGELOG.md

@@ -2,7 +2,23 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
-## 0.2.24 — Unreleased
+## 0.2.26 — Unreleased
+
+- Present bounded Claude text, tool requests and reported results without treating provider messages as command receipts or final QA.
+- Keep unsupported structured output behind an explicit verified-content reader, with honest archive-limit and omitted-block messages.
+- Configure separate GitHub polling continuation consent through Mapping, Scope and Review, preserving the original request through uncertain saves and exact receipt recovery.
+- Recheck current polling account, application and native authority after credential waits before clarification continuation and feedback.
+- Preserve all existing MCP wire contracts while adding four polling-continuation tools, for 162 tools and 258 versioned prompt resources.
+
+## 0.2.25 — 2026-10-20
+
+- Retain complete sanitized coding-provider events within explicit archive limits, with atomic storage and integrity-checked, currently authorized reads through HTTP, SDK, CLI and MCP.
+- Present recognized provider commands and outcomes in Studio, with a separate on-demand full-content reader and current desktop/mobile walkthroughs.
+- Distinguish recovery attempts in source-control milestone feedback while preserving historical delivery identities and unresolved-write holds.
+- Recheck the exact polled GitHub comment and its author's current repository access after preparing the issue token, before posting feedback.
+- Let interrupted execution tasks finish cancellation cleanup when several consumers detect a lost lease or the shutdown deadline expires; retain the storage fence until effects drain.
+
+## 0.2.24 — 2026-10-20
 
 - Bind an explicitly adopted current CLI executable to one failed-run recovery task while preserving its original model, timeout, permissions, budgets and snapshot.
 - Refuse changed or inaccessible executable metadata before continuation, and recheck the admitted entrypoint before process creation and result acceptance.

Dockerfile

@@ -4,6 +4,8 @@ WORKDIR /build/studio
 COPY studio/package*.json ./
 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
 RUN npm run build
 
 FROM python:3.13-slim-trixie

README.md

@@ -37,6 +37,8 @@ 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.
+
 ## 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).
@@ -53,9 +55,9 @@ A factory administrator can review source-control delegation under **Project acc
 
 SDK, CLI and MCP clients can inspect those original-command candidates through the same authenticated read. Inspection never creates a continuation request or dispatches work. API-only installations report local admission and execution separately in health and metrics; accepting a request does not establish that a remote worker is ready.
 
-For a local factory without an incoming webhook route, an administrator can enable [GitHub App issue polling](docs/scm.md#use-github-issue-comments-from-a-local-factory). Complete the baseline and separate account consent before posting a new status or answer comment. The mapped user's current permissions still apply, recorded answers retain their provenance, and answering leaves the existing run paused. Product edits and continuation use their separate signed-ingress grants; polling does not create projects or provide full GitFlow.
+For a local factory without an incoming webhook route, an administrator can enable [GitHub App issue polling](docs/scm.md#use-github-issue-comments-from-a-local-factory). Complete the baseline and separate account consent before posting a new status or answer comment. The mapped user's current permissions still apply, recorded answers retain their provenance, and answering leaves the existing run paused. For an answered clarification, a separate polling continuation consent lets the mapped person request continuation of that same run. Review its account, components and acknowledgment under **Project access**, then use the exact continuation cut in a new GitHub comment. See the [continuation walkthrough](docs/console-tour.md#review-github-continuation-consent). Polling does not create projects or provide full GitFlow.
 
-For a new product, a separately consented signed GitHub conversation can use `/forge intake` to register its first project and functional definition. This requires current native administrator authority and the repository's explicit intake consent. Registration does not start implementation. Follow [repository intake](docs/repository-workflow.md#register-a-first-product-from-github) for the contract; local issue polling remains limited to status and answers on existing runs.
+For a new product, a separately consented signed GitHub conversation can use `/forge intake` to register its first project and functional definition. This requires current native administrator authority and the repository's explicit intake consent. Registration does not start implementation. Follow [repository intake](docs/repository-workflow.md#register-a-first-product-from-github) for the contract; local issue polling supports status, answers and separately consented clarification continuation on existing runs.
 
 Use the [run evidence reader](docs/run-evidence.md) to inspect or export a consistent cut of activity, tasks, WAL and tool results. A separately granted implementation agent can read bounded evidence from its own run. Reading evidence never replays a command or clears an unresolved outcome. Optional [Bridge original-request recovery](docs/bridge.md) also retains the first submission and its pending or terminal observations; it keeps the graph-continuation hold until a supported checkpoint exists.
 

docs/agent-integrations.md

@@ -36,6 +36,12 @@ forge run --repository REPOSITORY_ID --project PROJECT_ID --component stock \
 
 A standalone frontend can select `--backend none`. Explicit stack choices must match a configured component. `--roles-file role-selection.json` applies validated role overrides; a run retains the resulting snapshot.
 
+## Continue an answered clarification through local GitHub polling
+
+`ForgeClient.configure_scm_polling_resume_grant`, `scm_polling_resume_grant` and `current_scm_polling_resume_grant` save or read the separate version 3 transport-bound consent. `review_scm_polling_resume(project_id, repository_id, binding_request_id, run_id)` reads the current answered-clarification cut without dispatching it. MCP exposes `configure_scm_polling_resume_grant`, `get_scm_polling_resume_grant`, `get_current_scm_polling_resume_grant` and `review_scm_polling_resume` with the same strict request contract.
+
+Use `forge project scm-polling-resume-grants configure|get|current|review` for those explicit operations. Retain the caller request identity before a single consent POST and read the exact original request after a lost response. Existing status/answer or signed-ingress consent never becomes polling-resume authority. These clients cannot fabricate a signed event, post a GitHub command, change a provider or increase a run budget. Follow the [polling clarification continuation](scm.md#continue-an-answered-clarification-through-polling) guide to review and send a separate repository comment.
+
 ## Delegate repository accounts
 
 SCM delegation connects a recorded provider account to an existing Forge user for explicit project components and actions. It does not create a user, grant project membership or turn a webhook sender into a personal login. The mapped user must remain enabled and retain the required project permission.
@@ -385,3 +391,26 @@ A mapped SCM account needs separate administrator consent to change an existing
 Use `forge project scm-product-change-grants configure PROJECT REPOSITORY consent.json` for one reviewed write. The document is the strict `SCMProductChangeGrantInputV1` body described in [SCM product changes](scm.md#change-an-existing-functional-product). Retain its original request ID before sending it. After an uncertain response or conflict, use `get PROJECT REPOSITORY REQUEST` under the same CLI group. `current PROJECT REPOSITORY BINDING_REQUEST` reads the current consent for that mapping; it does not resolve a different original request.
 
 The signed `/forge product_change` command still arrives through verified provider ingress. These clients do not fabricate its signature, infer an actor or send a product edit on behalf of the provider. Read the original result with `forge project scm-product-changes get PROJECT REPOSITORY CHANGE_REQUEST`. A missing receipt does not authorize a resend or replacement identity. Its recorded product revision may differ from the current product.
+
+
+## Read complete retained provider activity
+
+New provider stdout and stderr observations retain a bounded visible preview and, when the native JSON shape is recognized, a version 1 typed `activity_summary`. Codex summaries preserve the command, known exit code and output preview even when the original JSON exceeds the timeline's display budget. Claude summaries describe assistant text, requested tools, reported tool results and final provider reports. Plain logs remain escaped text. Unsupported or malformed structured previews get a generic card with an explicit content reader. Provider output remains untrusted observed data.
+
+Claude recognition follows its documented [CLI stream-json output](https://code.claude.com/docs/en/headless#stream-responses) and [complete content-block messages](https://code.claude.com/docs/en/agent-sdk/streaming-output#message-flow). The optional `provider: claude` summary field names this recognized format; it is not authenticated provider attribution. `tool_name` belongs only to an observed tool request. `tool_outcome` records `reported_result` or `reported_error`, without inferring a process exit code from `is_error`. A `result` message is a provider report, including when its subtype is `success`.
+
+For a mixed message, `content_blocks` contains at most four typed text/tool observations with 128-byte previews, and `omitted_blocks` counts blocks not displayed. Recognition is bounded to messages with at most 64 blocks; unsupported shapes use the generic display. Single-block previews retain their existing 768-byte limit. Tool input objects and attachments are not serialized into the summary. The original sanitized message, descriptor version, hash and archive limits stay unchanged. No cross-event tool correlation or factory verification is inferred from these fields.
+
+Each new observation has an `activity_content` descriptor bound to its run, event, stage, UTF-8 size and sanitized-message SHA256. `available` means the sanitized message was retained atomically with its index in PostgreSQL. The limits are 4 MiB per message, 64 MiB and 4,096 retained messages per run. `budget_exceeded` explicitly means complete content was not retained. Older events keep their historical text and have no invented content descriptor or backfill. The hash identifies sanitized retained bytes, not the provider's original wire output or an immutable execution receipt.
+
+Read an available descriptor through the same current authority as the run:
+
+```sh
+forge evidence activity RUN_ID EVENT_ID --expected-descriptor DESCRIPTOR_SHA256 --chunk 0
+```
+
+The equivalent SDK call is `client.run_activity_content(run_id, event_id, {"expected_descriptor": digest, "chunk": 0})`; MCP exposes `get_run_activity_content`. HTTP uses `GET /api/v1/runs/{run_id}/activity/{event_id}/content?expected_descriptor=SHA256&chunk=0`. Responses contain version 1, the descriptor digest, chunk ordinal and byte offset, total byte count, sanitized-message digest, `data_base64` and `next_chunk`. Each chunk is at most 16 KiB; follow the returned ordinal through `null`, concatenate decoded bytes, and verify the complete size and SHA256 before treating the message as complete. UTF-8 characters can span chunks. Clients do not retry effects or persist authentication in content files.
+
+Every chunk read validates the whole retained payload, current repository and frozen project scope, current reader identity, and credential admission again immediately before returning. A late registered credential anywhere in the message withholds every chunk, including when it crosses a chunk boundary. Changed descriptors, missing or corrupt content, exceeded budgets or changed scope return explicit unavailable responses; they never return a partial success. Reads are private and not cacheable.
+
+Run-evidence pages and ZIP exports keep their existing 1 MiB record/page and 16 MiB snapshot limits. They include only the small observed activity index and bound descriptors, never the BYTEA payload. New manifests mark activity content as excluded with bound references. Historical exports without new descriptors retain their prior format. The UI labels previews separately from complete content and verifies the full digest before offering complete content for copying.

docs/architecture.md

@@ -45,6 +45,54 @@ Flycanon's server runs in a separate environment, with its own migration and ing
 
 Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/api.py) (`FactoryConfiguration`, `create_runtime`, `create_application`), [`worker_runtime.py`](https://github.com/fireflyframework/firefly-forge/blob/main/src/firefly_forge/worker_runtime.py) (`WorkerSupervision`).
 
+### Observed provider activity
+
+`activity_models.py` projects known Codex JSON into small typed summaries; `activity_claude.py` recognizes Claude stream-json content blocks and result messages. Both describe observed output. A requested tool, reported tool result and final provider report remain distinct from the factory's WAL receipts and verification. Claude format recognition supplies no authenticated provider attribution, cross-event tool correlation or inferred exit code.
+
+`Store.event()` retains the sanitized message separately from that bounded projection. Studio renders supported summaries, leaves plain logs readable and offers an explicit verified reader for complete content. Unsupported structured previews receive a generic card. The optional Claude summary fields preserve the existing descriptor version and byte/hash binding; the archive writer, current-authority checks, credential fences and D04 export limits are shared. See [the activity contract](agent-integrations.md#read-complete-retained-provider-activity) and [the operator walkthrough](run-evidence.md#read-complete-provider-activity).
+
+### GitHub polling clarification continuation
+
+`SCMPollResumeGrantInputV3` separates REST-polling continuation consent from status/answer bindings and signed-delivery grants. `SCMPollResumeAuthority` owns current binding, project and native-user checks, immutable consent receipts and bounded history. Its registered pyfly controller, `ForgeClient`, CLI and four MCP tools share the same typed contract. Studio's Mapping, Scope and Review wizard retains one input before submission and reads its exact receipt after an uncertain response.
+
+A new `/forge resume` comment carries the existing version 2 continuation input under the distinct `github_rest_poll_v1` grant. `SCMPollResumeAuthority`, extending `SCMResumeAuthority`, rechecks the current account and application outside the database transaction, then native authority and the original clarification cut under the retained locks. Credential admission waits trigger fresh remote and local checks before action and feedback. An unknown intent remains held; queuing the original run records neither provider execution nor final product acceptance.
+
+<div class="forge-flow forge-flow--dependencies" role="region" aria-label="GitHub polling continuation boundaries" tabindex="0" markdown="1">
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+    A[Review account and scope] --> B[Retain consent receipt]
+    B --> C[Read clarification cut]
+```
+
+</div>
+
+Consent prepares the boundary. A new comment requests the actual continuation:
+
+<div class="forge-flow forge-flow--dependencies" role="region" aria-label="GitHub polling continuation admission" tabindex="0" markdown="1">
+
+```mermaid
+---
+config:
+  flowchart:
+    wrappingWidth: 96
+---
+flowchart LR
+    D[New resume comment] --> E[Recheck remote and native authority]
+    E --> F[Retain continuation receipt]
+    F --> G[Queue original run]
+    E -->|Unknown or revoked| H[Hold or refuse]
+```
+
+</div>
+
+See [polling admission and limits](scm.md#continue-an-answered-clarification-through-polling), the [operator walkthrough](console-tour.md#review-github-continuation-consent) and the native implementation in `scm_poll_resume.py`, `scm_resume_service.py` and `scm_resume_cut.py`.
+
 ### Connection OAuth and resource custody
 
 `FactoryConfiguration` registers `OAuthProviderPolicies`, `ConnectionOAuth`, `OAuthResources` and the external MCP registry as separate native beans. Policy admission fixes the issuer, endpoints, resource and scope. The connection service binds client registration and browser attempts to the current actor and immutable revision; it uses public pyfly OAuth client and PKCE APIs. PostgreSQL stores encrypted credentials, grant families, effects and append-only events.
@@ -332,7 +380,7 @@ Built-in model instructions are versioned YAML resources loaded and rendered by
 | Native browser QA | Fresh Docker context, declared local origin and bounded actions | Layout diagnostics and screenshots require actual visual/interaction review. |
 | Native PHP diagnostics | Explicit `profile_php` plus command grant, frozen Docker/archive/network-`none` runner | Runtime metrics or preinstalled Xdebug observations retain command receipts; they do not authorize or approve work. |
 | Internet search | Explicit Brave or Tavily selection, retained credential revision and domain restrictions | Bounded cited results are untrusted references; no key goes to the model. |
-| Factory MCP | 157 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. |
+| Factory MCP | 162 authenticated operator tools in `mcp_server.py` | These API tools are distinct from a coding model's workspace tools. |
 
 Flycanon retrieves `forge-<repository_id>` project context and shared framework references. Required retrieval failure prevents coding continuation. The retained citations/context digest support recovery. A ProductProject does not automatically create an aggregated memory workspace across its repositories.