Connect product workflows, board delivery and retained recovery

.gitignore

@@ -9,7 +9,7 @@ __pycache__/
 .pytest_cache/
 .ruff_cache/
 .mypy_cache/
-node_modules/
+node_modules
 dist/
 build/
 site/

compose.object-storage.local.yaml

@@ -0,0 +1,28 @@
+# Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0
+# Local emulation only. Supply an already installed image pinned by digest.
+name: forge-object-storage-local
+services:
+  minio:
+    image: ${FORGE_MINIO_IMAGE:?Set an installed MinIO image pinned by sha256 digest}
+    command: ["server", "/data", "--console-address", ":9001"]
+    ports:
+      - "127.0.0.1:9000:9000"
+      - "127.0.0.1:9001:9001"
+    environment:
+      MINIO_ROOT_USER_FILE: /run/secrets/minio_user
+      MINIO_ROOT_PASSWORD_FILE: /run/secrets/minio_password
+    secrets: [minio_user, minio_password]
+    volumes:
+      - objects:/data
+    read_only: true
+    tmpfs: [/tmp]
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    restart: "no"
+secrets:
+  minio_user:
+    file: ${FORGE_MINIO_USER_FILE:?Set a private local MinIO administrator identity file}
+  minio_password:
+    file: ${FORGE_MINIO_PASSWORD_FILE:?Set a private local MinIO administrator credential file}
+volumes:
+  objects:

docs/agent-integrations.md

@@ -317,9 +317,36 @@ 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.
 
+## Request independent fresh verification
+
+Linked verification is a separate operation for the exact configured checks of an accepted implementation. Read its candidate first. It binds the current operator, source, runtime, runner, inputs and command count. Reading a candidate grants no execution authority.
+
+| Operation | Python SDK | Factory MCP |
+| --- | --- | --- |
+| Review current scope | `linked_verification_candidate(run_id)` | `get_linked_verification_candidate` |
+| Submit explicit consent once | `request_linked_verification(run_id, request)` | `request_linked_verification` |
+| Read the same operation | `linked_verification_status(run_id, request_id)` | `get_linked_verification_status` |
+
+Python and MCP accept the native `LinkedVerificationInputV1` body: `version: 1`, the retained lowercase hexadecimal `request_id`, the reviewed `candidate_digest` and all three acknowledgments set to `true`. The CLI requires each acknowledgment explicitly and never prompts for implicit consent:
+
+```sh
+forge linked-verifications candidate RUN_ID
+forge linked-verifications request RUN_ID \
+  --request-id REQUEST_ID \
+  --candidate-digest REVIEWED_CANDIDATE_DIGEST \
+  --acknowledge-all-fresh-checks \
+  --acknowledge-no-coding-or-repair \
+  --acknowledge-original-history-and-budget-preserved
+forge linked-verifications status RUN_ID REQUEST_ID
+```
+
+Save the request ID, complete candidate and exact consent before the POST. These adapters submit once. A timeout, refusal or stale candidate never triggers another POST, a replacement identity or a budget reset. After uncertain delivery, read status for the original request. A missing receipt leaves the outcome unknown.
+
+The initial worker path requires a configured, qualified host runner. Unsupported transports refuse without fallback. The worker owns execution of the frozen commands and the independent operation ledger. This consent grants no coding or repair and preserves the original implementation history and budget. `queued` and `executing` are progress states; `failed` or `needs_reconciliation` do not establish successful checks. Only `completed` includes the typed parent-verification settlement. Git delivery keeps its own policy and consent gates.
+
 ## 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 172 operator tools to that coding process.
+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 202 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:
 

docs/agent-tools.md

@@ -33,6 +33,10 @@ Firefly Agentic registers the tools allowed by the run's frozen role configurati
 
 Use the [tool prerequisites guide](tooling-prerequisites.md) to check every phase and provider before enabling a capability. Commands, browsers, internet search and external MCP are optional configured capabilities; the initial implementation role grants the six confined source tools.
 
+Run, component and maintenance definitions retain the full declared verification list without a fixed command-count ceiling. Configured-check requests select an index from that list; the executor checks both its existence and the operator's granted scope. For example, a product with 51 checks can select check 50 using its zero-based index, when its configured execution allowance leaves enough capacity for that call and final verification.
+
+The selected runner's execution allowance still governs actual calls. Grant admission reserves capacity for independent final verification, and a restart preserves calls already spent. Increasing a definition's size does not change a retained run's commands, grants or counters. Command validation and any explicitly selected work deadlines continue to apply.
+
 Native tool arguments reject known configured credentials before file writes or external requests. Text returned by every native tool is redacted against the shared server credential registry before the model receives it. This checks known values and their configured representations; it does not discover every possible secret in a repository.
 
 Paths cannot traverse outside the component. Source read and write operations reject symlinks, hardlinks, Git metadata and credential filenames. Git diff reads only the component's admitted source paths and does not update the index. It includes tracked changes and nonignored untracked source files, representing new files as added-file patches without staging them. The response covers at most 100 paths and 128,000 characters, with explicit truncation; it is not a complete project diff when truncated. A rejected line edit requires reading the new file before retrying.

docs/api.md

@@ -15,6 +15,67 @@ Request and response bodies use JSON unless a route downloads an artifact or
 file. Project permissions apply to the authenticated identity. The actual
 running application's OpenAPI document is the authoritative schema.
 
+## Read recorded source
+
+In Studio, open a run from **Factory** and choose **Code**. Select a
+recorded branch and snapshot to browse its archived files. File windows are
+verified against the selected manifest and checksum before display. This view
+reads existing archives; it does not publish source, rescan credentials or run
+work. Current sign-in and project read permission remain required.
+
+These read-only endpoints require the current native identity and project read
+permission. Responses use `Cache-Control: private, no-store`. Snapshot IDs,
+catalog manifests and file indexes identify evidence; they do not grant access.
+
+| GET endpoint under `/api/v1/runs/{run_id}/source` | Result |
+| --- | --- |
+| `/revisions?after={snapshot_id}` | Up to 128 recorded snapshots and the next cursor; pending/failed publications remain explicit. |
+| `/revisions/{snapshot_id}/catalog?expected_manifest={sha256}&page=0` | An immutable source reference and a `SourceCatalogPageV1`. |
+| `/revisions/{snapshot_id}/files/{entry_index}?expected_manifest={sha256}&page=0&offset=0&limit=32768` | A verified byte window for an entry in that exact catalog page. |
+
+Catalog/file requests may include `request_id` for an existing Git delivery
+checkpoint. Its verified journal intent and receipt must retain a typed
+`expected_source_digest` equal to the catalog's complete source digest, as well
+as the same Git tree. A matching tree alone does not cover ignored public files.
+Older checkpoints without that exact proof remain unavailable through this
+selector; their source snapshot can still be read independently. File
+windows are at most 1 MiB and include exact byte offsets, a window SHA-256,
+Base64 content and optional UTF-8 text. `binary` describes the returned window,
+including a window that bisects a UTF-8 sequence; it does not guess a file type.
+
+The Python SDK exposes `run_source_revisions`, `run_source_catalog` and
+`run_source_file`. It validates response scope, indexes, extents and content
+hashes without retries. Unpublished snapshots have no content endpoint, and
+the server never substitutes a live workspace read. See
+[source storage and publication](architecture.md#read-recorded-source).
+
+### Rescan retained bytes after credential rotation
+
+A changed configured credential registry holds archived file reads until a
+current project owner or factory administrator explicitly scans the retained
+bytes. This uses existing native `members` authority; it does not grant execution
+or alter project permissions. A workspace is not required.
+
+| Endpoint under `/api/v1/runs/{run_id}/source/revisions/{snapshot_id}` | Purpose |
+| --- | --- |
+| `GET /credential-scan-candidate?expected_manifest={sha256}` | Review the current catalog and configured-credential fingerprint. Requires owner authority. |
+| `POST /credential-scans/{request_id}` | Submit one `SourceCredentialScanInputV1`, including both explicit retained-byte/no-source-change acknowledgments. |
+| `GET /credential-scans/{request_id}?expected_manifest={sha256}` | Read the exact pending or completed request without repeating a scan. Requires current source read access. |
+
+Keep the request identity, complete body and its canonical SHA-256 before the
+POST. After a lost reply, read that exact receipt. A pending request does not
+authorize content access and is never restarted automatically. A completed
+receipt records the unchanged snapshot, source digest, storage binding, actor,
+current credential fingerprint, file/byte counts and content-proof chain. The
+scanner verifies every retained chunk and file checksum before publication;
+it does not upload files, recreate a workspace or rewrite the archive.
+
+The SDK exposes `run_source_scan_candidate`, `run_source_rescan` and
+`run_source_scan_receipt`; readback requires `expected_request_sha256`.
+All responses are private and uncached. Current project access remains necessary
+after a successful scan. Personal API-token source routes remain unsupported
+until their separate observation allowlist is extended and tested.
+
 ## Observe the factory and manage personal tokens
 
 The [Factory dashboard](factory-dashboard.md#read-through-the-api) exposes read-only, paged project choices and factory, project or run observations. Its totals cover the selected scope independently of the page size. Current identity, exact cookie session when used and project access are checked again after the read snapshot.
@@ -214,6 +275,9 @@ After grant confirmation, refresh the final-allowance candidate and include `cod
 | GET | `/runs/{id}/checkpoint-continuations/requests/{request_id}/candidate` | Inspect a retained checkpoint and original ticket without admitting work |
 | POST | `/runs/{id}/checkpoint-continuations/requests/{request_id}/actions/{action_id}` | Save a reviewed finite continuation on the same execution request |
 | GET | `/runs/{id}/checkpoint-continuations/requests/{request_id}/status` | Read the saved checkpoint-continuation action and worker status |
+| GET | `/runs/{id}/worker-completion-settlements/candidate` | Review eligible known-worker V1 or consumed-terminal V2 custody without settling output |
+| POST | `/runs/{id}/worker-completion-settlements/{request_id}` | Submit exact V1 settlement or strict V2 local-postprocessing consent under one saved request identity |
+| GET | `/runs/{id}/worker-completion-settlements/{request_id}` | Read the same retained settlement/recovery receipt without dispatch or resubmission |
 | GET | `/runs/{id}/final-outcome-continuations/requests/{request_id}/candidate` | Review an already-consumed final result and current eligibility |
 | POST | `/runs/{id}/final-outcome-continuations/requests/{request_id}/actions/{action_id}` | Save one same-ticket final-result acceptance action |
 | GET | `/runs/{id}/final-outcome-continuations/requests/{request_id}/status` | Read final-result acceptance status without another submission |
@@ -247,6 +311,14 @@ The [original-result recovery guide](recovery.md#explicit-closed-text-implementa
 
 The [uncertain run-submission guide](recovery.md#settle-an-uncertain-run-submission) explains exact admission, cancellation and decision readback. The same enabled user can read or settle cancellation with current read access after signing in again. Replaying admission also requires the original authentication method and current execution authority.
 
+### Consumed-terminal recovery
+
+Consumed-terminal recovery uses the existing worker-completion endpoint family
+with a strict `version: 2` request; there is no query selector or new execution
+grant. The Python SDK, CLI and MCP provide explicit V2 candidate, request and
+status operations. See [the guided recovery flow](checkpoint-verification.md#recover-a-consumed-terminal-result-after-failure)
+for the five digest bindings, required acknowledgments and lost-response readback.
+
 ## Use explicit recovery from the Python SDK
 
 `ForgeClient` exposes the same original-request and checkpoint contracts. Retain