Prepare 0.2.45: preserve authority across durable recovery

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 <!-- Copyright 2026 Firefly Software Foundation. SPDX-License-Identifier: Apache-2.0 -->
 
+## 0.2.45 — 2026-10-25
+
+- Page project and campaign data without a fixed project-count ceiling, retain revision-bound references, and configure finite campaign execution windows with durable usage accounting.
+- Stream credential fingerprint preparation and checkpoint source admission outside database writer units while retaining current credential, source and ownership checks.
+- Ground AI-written status in current verification facts, recorded reasons and next factory actions. Preserve historical checks as historical context and keep pending factory work separate from questions requiring a person.
+- Accept normal and blocked worker outcomes through atomic native completion custody, including restored checkpoints. Keep QA and Git delivery behind the exact accepted outcome and current authority.
+- Add explicit administrator acknowledgement of an unknown command for one separately bound verification continuation and its following coding/QA/Git lineage. Preserve the unknown row, spent ordinals, frozen command and repair budgets, and repeated current-actor checks.
+- Bind retained source-catalog manifests to their immutable hash and stable identity across checks. For file ctime-only changes, stream a bounded rehash against the original payload SHA-256 without refreshing its baseline. Preserve other identity fields and full metadata checks during reads.
+- Add explicit native checkpoint-mode adoption for an eligible older Bridge continuation that stopped before model dispatch. Retain the original provider revision, unfinished intents, source, unknown outcomes and spent budgets while admitting only stronger result-recovery and checkpoint settings.
+- Follow validated test and maintenance descendants when selecting current issue status, retaining the root conversation receipt and asking for clarification when current leaves are ambiguous.
+- Include the audited credential-scanner dependency closure in fixed workspace exports, preserve later native receipts after an accepted worker outcome, and withhold malformed historical verification requests from public facts.
+- Preserve the originally selected model profile for same-provider Bridge verification continuations and admit only a separately reviewed correction for an eligible retained selection failure before model dispatch. Keep the original configuration, claims, unknown outcomes and spent budgets intact.
+- Record restart recovery against the current intent or explicit readmission claim. Repair a missing annotation for an already held task without rewriting its state or replaying work. Refuse unresolved Bridge results before reading provider configuration.
+- Require fresh source-profile measurements and preserve every historical profile literal. Keep Studio 0.2.45 assets unchanged. Controlled native, SQL, host and visual evidence remains separate from completed CRM delivery or live-provider acceptance.
+
 ## 0.2.44 — 2026-10-25
 
 - Store equal native history arrays once in the version-3 lossless checkpoint codec, then reconstruct and hash the complete canonical record before restoration. Preserve version-1 raw and version-2 compressed snapshot readability and original encoded identities.

docs/agent-lifecycle.md

@@ -87,7 +87,7 @@ The lifecycle projection reports execution bindings and knowledge availability.
 
 An implementation worker can return a typed `verification` request when it needs results from the run's approved checks. With a frozen automatic-verification grant, forge runs all explicit `run.commands` through the authorized runner, records their native intents and outcomes, and supplies factory feedback. Request names and question text do not select commands or grant access. Product choices, credentials and approvals still require a person.
 
-New runs default to one verification continuation, with a strict configurable maximum of three. Each completed handoff permits one additional coding task, separately from the frozen repair budget and within the existing four-attempt ceiling. Earlier attempts and failed checks remain recorded. Current authority, source, policy and provider are checked again before effects and the next coding task. [Recovery](recovery.md#inspect-a-factory-verification-handoff) explains holds and explicit adoption for older runs.
+New runs default to one verification continuation. Operators configure a positive finite window; an explicit policy renewal and fresh adoption retain every spent handoff and command slot. Each completed handoff permits one additional coding task, separately from the frozen repair budget and within the existing four-attempt coding-stage ceiling. Earlier attempts and failed checks remain recorded. Current authority, source, policy and provider are checked again before effects and the next coding task. [Recovery](recovery.md#inspect-a-factory-verification-handoff) explains holds and explicit adoption for older runs.
 
 The run's verification panel shows command counts and `pending`, `running`, `completed` or `held` state. Completed means every configured command has a known result, including failures. Final acceptance still depends on the run's verification and delivery evidence. An uncertain effect stays held without automatic replay.
 

docs/api.md

@@ -18,11 +18,14 @@ running application's OpenAPI document is the authoritative schema.
 ## Automatic verification handoffs
 
 New runs freeze `settings.automatic_verification` from `GET /tools/policy`.
-The factory default is `{"enabled": true, "max_continuations": 1}`; the strict
-maximum is three. The existing administrator-only policy update accepts this
+The factory default is `{"enabled": true, "max_continuations": 1}`. The configured
+window must be a positive finite integer. The existing administrator-only policy update accepts this
 setting with the other tool settings. A frozen snapshot without this setting
 does not grant automatic execution.
 Older SDK/MCP policy writes that omit this setting preserve its current value.
+An explicit renewal changes the current policy and requires a new exact adoption;
+it retains every spent handoff and command slot. The separate four-attempt coding
+stage limit remains unchanged.
 
 A pending implementation request with typed `kind: "verification"` can ask
 Forge to run all explicit, frozen `run.commands` through `SandboxExecutor`.
@@ -74,6 +77,49 @@ The Python SDK exposes `verification_handoff_candidates`,
 perform one explicit request each and do not create IDs, apply a fallback or
 resume a run implicitly.
 
+### Unknown command acknowledgements
+
+The native operator routes are under
+`/runs/{run_id}/sandbox-executions/{execution_id}/unknown-command-acknowledgements`:
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/candidate?agent=agentic&adoption_request_id=...` | Review one unknown execution and one exact future verification adoption |
+| POST | `/{request_id}` | Append the reviewed version 1 acknowledgement once |
+| GET | `/{request_id}` | Read that exact immutable receipt with current permissions and credential admission |
+
+The strict `UnknownCommandAcknowledgementV1` input contains the candidate, policy,
+run, journal and execution digests, the exact `followup` object, and the server's
+observed `classification`. Every input must acknowledge no original replay and
+the bound verification and native continuation with literal `true` in
+`acknowledge_bound_verification_and_continuation`. For `start_unknown`, it must also
+acknowledge the unknown result and possible effects. For `closed_before_start`,
+it must instead acknowledge that the complete native WAL has no start intent;
+unknown-result acknowledgements do not apply. It accepts no claimed exit code,
+success result or arbitrary absence proof.
+This first contract covers native host executions under their original frozen
+sandbox policy. Docker and pool custody require separate supported recovery.
+
+The receipt leaves the original sandbox row, unknown start, consumed ordinal,
+held handoffs and all counters intact. It does not execute, adopt or resume.
+Only a later ordinary verification adoption using the bound request ID can admit
+the exact reviewed source, request, commands, policy, provider and new ordinals.
+Every handoff remains counted against the current finite policy. An exhausted
+window requires an explicit policy renewal and fresh review.
+Several eligible custody records require separate acknowledgements bound to the
+same future adoption. A receipt never waives unrelated or unreviewed executions.
+After every reviewed command has a known result (including known failures), only
+the completed handoff's factory response, native resume and continuation intent
+can carry the acknowledgement into coding, normal QA and Git. Existing frozen
+repair and provider grants remain required, with every spent counter retained.
+The acknowledging actor is checked again before dispatch and delivery. Original
+unknown outcomes remain unknown and are disclosed in publication communication.
+
+The Python SDK exposes `unknown_command_acknowledgement_candidate`,
+`acknowledge_unknown_command` and `unknown_command_acknowledgement`. After an
+uncertain POST, read the original request identity; do not choose a new identity
+or resend an unknown execution. See [operator recovery](recovery.md#acknowledge-an-unknown-command-for-follow-up-verification).
+
 ## Failed official-provider recovery
 
 A native factory administrator can review `GET /runs/{id}/provider-recoveries/candidate?agent=codex` or `claude`, explicitly POST the returned candidate digest under one caller-owned request ID to `/runs/{id}/provider-recoveries`, and read its exact receipt at `/runs/{id}/provider-recoveries/{request_id}`. Admission reserves one dispatch in the same run. It does not execute a model in the request or reset repair and verification budgets.