Release Forge 0.2.43 with durable checkpoint continuation

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
+## 0.2.43 — 2026-10-24
+
+- Allocate command ordinals durably across service instances and restored graphs. Preserve exact explicit replay, unknown-effect holds and run-lifetime command budgets.
+- Restore fully completed command history through canonical native WAL and consume receipts. Keep changed source, authority, runtime contracts and interrupted effects blocked.
+- Compress accumulated native checkpoint history losslessly within an explicit 8 MiB raw bound while preserving the 192 KiB snapshot and 256 KiB WAL limits. Scan decoded records against current credential custody, including generic journal reads.
+- Stage complete branding files with a compact manifest, send the composed brief once, and retain the nine granted static checkpoint tools and exact frozen wireframe descriptors.
+- Preserve verified GitHub delivery links and bind finite maintenance communication to the exact new native creation receipt. Lifecycle notices and owner answers grant no resume or new execution authority.
+- Stream checkpoint identity from tracked Git source, including ignored tracked assets, and nonignored untracked source. Generated ignored dependencies no longer turn a host checkpoint into a transport-archive failure; runner archive transfer remains separately guarded.
+- Page source listing and text search explicitly, classify binary source, and hash every eligible file completely for manifests without the old 2,000-path or 1 MiB manifest cutoff.
+- Bind the V12 source profile to an explicit 35-module admission closure and 22 loader inputs with fresh same-source native/SQL measurements, retaining all seven historical profiles. Studio remains on its unchanged 0.2.42 assets and captures; see the [release notes](docs/release-notes.md#0243) for verification boundaries.
+
 ## 0.2.42 — 2026-10-24
 
 - Complete an uncertain remote Git checkpoint only through a new finite native request, preserving the original unknown request, retained review body, current permissions and exact branch checks.

docs/agent-tools.md

@@ -9,10 +9,10 @@ Firefly Agentic registers the tools allowed by the run's frozen role configurati
 
 | Tool | Scope and evidence |
 | --- | --- |
-| `list_files` | Up to 2,000 component source paths; skips dependency trees, credentials and symlinks. |
+| `list_files` | Versioned pages of component source paths, with a source-view digest and continuation cursor. A page is never the whole project unless its scope is complete. |
 | `read_file` | Bounded UTF-8 source with its SHA256 hash. |
 | `write_file` | Complete bounded source content in a relative component path. |
-| `search_text` | Literal text search with line numbers, file hashes and an explicit truncation flag. |
+| `search_text` | Complete selected text search with finite result pages, full-file hashes, explicit snippet truncation and binary/UTF-8 classification. |
 | `edit_lines` | Inclusive line replacement requiring the current file hash, rechecked on the open write descriptor. |
 | `git_diff` | A bounded component diff with external drivers, text conversion, filesystem monitors and hooks disabled. |
 | `execute_command` | Bounded argv execution through the frozen host or Docker policy. |
@@ -36,6 +36,20 @@ The table is a conditional native registry, not a promise that every provider re
 
 The separately qualified source-only Codex route has a different, measured contract: governed source list/read/search and source edits within its exact admitted workspace, plus only the utilities explicitly recorded in its supported profile. It does not inherit `execute_command`, browser tools, internet search or `read_run_evidence` from the ordinary native registry. The current binary, model metadata, package policy and runtime must match that qualified profile before dispatch. A configured provider, an available capability, a qualified source-only profile and a completed invocation are separate states; check the [tool prerequisites](tooling-prerequisites.md) and [source-only recovery requirements](recovery.md) for the applicable route. Owner guidance does not modify a call already in flight or become delivery authority for a sealed source-only invocation.
 
+## Continue through a large source tree
+
+The native `list_files` tool returns a version-one page with `files`, `view_sha256`, `next_cursor` and `complete`. Start without a cursor. If `complete` is false, send the returned cursor with the same prefix and page size. Keep going until the final page. The default page size is 100; up to 1,000 paths can be requested in one response. The admitted byte window can shorten a page further. These are response windows, not project file-count limits.
+
+Firefly Agentic uses `path_prefix`; the source-only CLI reader uses its existing `path` argument as the prefix. Both accept an optional `cursor`. The CLI also accepts `page_size` and requires a new unique `request_id` for each page. Reusing an ID reads its exact stored result; changing that ID's cursor or arguments is refused. Old requests without paging arguments remain valid and receive an explicit first page. Internal Python callers of `WorkspaceTools.list_files()` receive the complete eligible path list.
+
+A cursor binds the repository/component, prefix or search query, response options and complete filename/metadata view. A changed view is refused: start a new listing instead of combining pages from different source states. Cursor contents are navigation data, not execution or permission grants.
+
+Git workspaces select tracked files, including tracked files covered by ignore rules, plus nonignored untracked files. Ignored installed dependencies are not treated as product source. Selected private paths, unsafe links, aliases and conflicts refuse; they are not silently counted as inspected. Standalone non-Git callers keep confined source traversal. Present but malformed Git metadata never triggers a filesystem fallback.
+
+`search_text` applies the prefix before scanning and can find text in files larger than the ordinary whole-file read window. Its pages retain the full-file SHA256 and report `snippet_truncated` separately from result-page continuation. Binary and invalid-UTF8 files are counted explicitly; unreadable or changed source refuses the operation. `complete` means the selected text-search page sequence has reached its end, not that binary content was searched as text.
+
+Before and after a native command, the internal manifest streams all selected file bytes, including large and binary files, without using a reader page or a fixed aggregate byte cutoff. Source identity is rechecked before returning. This complete accounting does not remove the separate role, command, provider or host budgets. It also does not expand the existing whole-file write/edit window; large-file editing needs its own supported interface.
+
 ## Observe a Python workload
 
 Grant both `profile_python` and `execute_command` to the implementation role before creating the run. The repository runner must use an immutable Docker image, archive workspace transfer and network `none`, without a pool binding. Its image must already contain `python3` and the workload's dependencies. Host, bind-mount, network-enabled and pool profiles do not receive this optional tool. Readiness checks runner availability; the invocation still determines whether the image has a working Python interpreter. The default six source grants are unchanged.

docs/architecture.md

@@ -516,7 +516,9 @@ flowchart LR
 
 <p class="forge-flow-caption" id="original-result-flow-guide">Save the original checkpoint and intent before submitting to Bridge. If the result is uncertain, retain its identity, read or check the original result, then review one continuation. Continuing commits the one-use consume receipt before native parsing, followed by implementation and verification. On a narrow screen, scroll horizontally or focus the diagram and use the arrow keys.</p>
 
-The restore ticket binds the original checkpoint, intent and selected result record. The execution owner repeats authority, source, configuration and deadline checks before restoring native Agentic history with `prompt=None`. The selected response is consumed once before the SDK parser receives it. A failure after that commit cannot authorize replay. A later repair keeps its own task identity; its mutable task key cannot replace the original implementation receipt. Owner recovery retains a committed consume boundary and holds unfinished tickets for reconciliation. See the [operator recovery journey](recovery.md#review-a-held-result-in-studio) for supported file tools and current limits.
+The restore ticket binds the original checkpoint, intent and selected result record. The execution owner repeats authority, source, configuration and deadline checks before restoring native Agentic history with `prompt=None`. The selected response is consumed once before the SDK parser receives it. A failure after that commit cannot authorize replay. A later repair keeps its own task identity; its mutable task key cannot replace the original implementation receipt. Owner recovery retains a committed consume boundary and holds unfinished tickets for reconciliation. Static command, knowledge and evidence tools retain explicit grants. Command-enabled restoration verifies bounded native WAL against canonical, fully completed durable command records. Prior effects must precede the selected checkpoint; later command creation must follow the matching restore consume. Unknown, interrupted, orphaned or altered effects refuse. Fresh commands use the next durable ordinal and preserve lifetime budgets. The checkpoint runtime contract binds the restore implementation, preventing an older contract from silently gaining this behavior. See the [operator recovery journey](recovery.md#review-a-held-result-in-studio) for supported tools and current limits.
+
+Boundary snapshots retain lossless canonical native history within an explicit 8 MiB raw bound. New records above 64 KiB use zlib/base64 within the existing 192 KiB snapshot and 256 KiB WAL limits. Canonical envelope/base64, raw SHA-256, size, end-of-stream and trailing-data checks precede restoration. Current credential admission scans decoded records at capture, consume, restore and generic journal read without exposing raw history in returned WAL or logs. Generic journal reads suspend ambient unit bindings and inspect one bounded record at a time under current reader/configuration guards. Source admission V11 adds the decoder to its explicit 34-module closure; the checkpoint runtime contract binds custody producer and consumer.
 
 `BridgeProvider.execute()` creates a separate pending-request set for each invocation. Agentic task-graph children inherit that shared object through a context variable. Each completion tracks its own attempt before transport and clears it after a validated response, an exhausted stream or a known quota/pause response. Completing one request cannot clear another pending request. If the task graph unwraps a cancellation exception, the outer provider checks its own set before returning cancellation to the Engine. Both context tokens are reset when their scopes end. The Engine then records an unresolved submission against the original journal intent before finishing local cancellation. Regression controls cover the real `FireflyAgent` path, concurrent invocations on a shared provider, successive completions and restart through the native Store.
 
@@ -590,6 +592,10 @@ Source: [`api.py`](https://github.com/fireflyframework/firefly-forge/blob/main/s
 
 ## Agent roles, native tools and cited context
 
+Product branding enters implementation through a compact file manifest. Engine validates the frozen kit's digest and admits the complete assets against current credentials, then materializes them under `docs/brand/<digest>/` inside the selected component. Each manifest entry carries the component-relative path, UTF-8 byte count and SHA-256. Complete tokens, logos, styles and font-license text stay available through the governed file tools. Existing conflicting content refuses materialization; the file writer also checks the empty-file hash before creating a missing asset. Cancellation, ownership and current project authority are checked around effects.
+
+The manifest passes through the existing brand-instruction template. The complete assembled development brief appears once in the native user prompt; backend/frontend instructions, tool rules and frozen QA descriptors remain separate instructions. Embedded SVG and font CSS therefore stay in source files, while requirements and knowledge remain complete in the brief. This changes context representation without increasing checkpoint limits or silently cutting content. Engine and runtime changes require a newly measured source capability profile before native admission.
+
 <details class="forge-gallery" markdown="1">
 <summary>Inspect instructions, tool authority and knowledge scope</summary>