worktree-controller 1.32.2__tar.gz → 1.32.4__tar.gz

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.32.2
+Version: 1.32.4
 Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -114,3 +114,13 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)
 
 Licensed under the [Apache License 2.0](https://github.com/xuanheng-tech/worktree-controller/blob/main/LICENSE).
+
+With `terminal_preserved_cleanup_version` 1, published integrations and completed
+no-change feature/audit tasks may use the existing preservation and `resource-clean --typed`
+flow. Require one exact remote-verified, lease-cleared publication or one verified original
+no-change completion. Every removed tree needs immutable preservation coverage.
+Plans pin the current verified proof baseline; cleanup and release recheck it without
+rewriting history, reopening lifecycle or relaxing owner/HEAD/CAS, runtime, lease, retained-ref
+and transaction guards. A newly observed legacy digest is not historical hash evidence.
+New-format no-change completions may clean afterward only when their frozen prior cleanup
+set is empty; existing pre-completion proofs retain their original CAS.

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/README.md

@@ -97,3 +97,13 @@ a successful process exit alone does not prove that all worktrees are settled.
 - [Report a security issue](https://github.com/xuanheng-tech/worktree-controller/blob/main/SECURITY.md)
 
 Licensed under the [Apache License 2.0](https://github.com/xuanheng-tech/worktree-controller/blob/main/LICENSE).
+
+With `terminal_preserved_cleanup_version` 1, published integrations and completed
+no-change feature/audit tasks may use the existing preservation and `resource-clean --typed`
+flow. Require one exact remote-verified, lease-cleared publication or one verified original
+no-change completion. Every removed tree needs immutable preservation coverage.
+Plans pin the current verified proof baseline; cleanup and release recheck it without
+rewriting history, reopening lifecycle or relaxing owner/HEAD/CAS, runtime, lease, retained-ref
+and transaction guards. A newly observed legacy digest is not historical hash evidence.
+New-format no-change completions may clean afterward only when their frozen prior cleanup
+set is empty; existing pre-completion proofs retain their original CAS.

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/docs/architecture.md

@@ -12,6 +12,7 @@ development and recovery paths; exact public interfaces live in the [contract](.
 | Git observations and mutations | `git_backend.py` | Git owns registrations, refs, paths, HEAD and cleanliness |
 | State and durable evidence | `models.py`, `store.py`, `metadata_codec.py`, `record_updates.py` | Validate stored identities; serialize mutations under the repository lock; record updates bump their version, and both update helpers append history |
 | Shared identity and semantic checks | `semantics.py` | Consume the caller's snapshot, including effective intent state and terminal reconciliation; do not acquire authority or write metadata |
+| Release-intent queries | `release_intents.py` | Select from the caller's snapshot and calculate renewal backoff using its supplied time; no metadata writes or fresh observation |
 | Budget admission | `resource_admission.py` | Preserve durable request identity and host reservations across retries |
 | Writer entitlement | `writer_lease.py`, `writer_session.py`, `governance.py` | Bind the real process identity and exact operation/target |
 | Lifecycle orchestration | `lifecycle.py` and focused recovery modules | Compose existing guards and append durable transition evidence |
@@ -76,3 +77,9 @@ Further lifecycle extraction should follow one cohesive transition at a time, ke
 scope and immutable evidence together. Avoid moving mutation helpers that depend on lifecycle's
 clock, transaction state or caller-specific guards merely to reduce a line count. Public CLI,
 capability and storage changes require their own version and compatibility review.
+
+Release-intent selection and renewal backoff share a pure query module. Lifecycle keeps the
+mutation helpers, clock, lock scope, cancellation and history append unchanged. Convergence
+uses the same query directly; lifecycle retains its existing internal aliases. A changed HEAD
+or record version still renews immediately, and repeated unchanged expiries retain the existing
+one-day backoff cap. This extraction changes no CLI, capability or storage contract.

worktree_controller-1.32.4/docs/integration-boundaries.md

@@ -0,0 +1,68 @@
+# Consumer and protocol boundaries
+
+Inventory verified on 2026-10-23 against WC 1.32.3 (CLI 61, storage 5) and GF 1.9.7.
+This is a source inventory, not an observation of every installed host or external user.
+The public [CLI contract](../tool_cli_contract.json) remains authoritative.
+[Scope](scope.md) records the conservative decision to keep existing commands supported.
+
+## Existing delivery protocols
+
+| Flow | Producer authority | Consumer responsibility | Required evidence and refusal |
+| --- | --- | --- | --- |
+| Integration publication | WC `integration-publication-session/v1`; repository lock spans verify, authorize, push observation and completion | GF publishes the exact authorized candidate with a non-force push and independently observes the remote | Repository/allocation, lease/run, candidate, expected main, record version and validation identity must match. Missing capability, drift or incomplete completion blocks. After uncertain transport, inspect remote facts and re-enter the same identity. |
+| Branch retirement | WC `branch-retirement-execution/v1` and `retirement-execution-result/v1` | GF performs only the plan-authorized exact-OID ref operation | The public plan, verify, authorize and complete results bind the operation and ancestry proof. Missing refs alone do not establish a completed retirement; retain recovery identity. |
+| Sensitive source review | GF owns its review-file schema | Treat the four WC linkage fields as opaque identities | No derivation of private authority digests or parsing WC metadata to construct authority. |
+| Review evidence | SR owns `snapshot-runner read`, evidence-read schema 1 and stored-era validation | GF's explicit initial-publish mode consumes public fields | Unknown schema, partial output, gaps or identity mismatch blocks; GF does not parse SR storage or hard-code its security epoch. |
+| Deployment health | The published toolchain catalog, currently owned by GF | `tool-skill-sync doctor` verifies installed capabilities and the frozen runtime contract | Explicit CLI/storage allowlists and required capability versions all apply. Source availability or equal CLI numbers alone do not prove compatibility. |
+
+These protocols already exist. The next step is preserving and testing them, not designing a
+replacement message bus or accepting unknown versions. Protocol/capability versioning does not
+relax the deployment catalog's explicit CLI/storage compatibility checks.
+
+GF is independently usable for its core Git operations. WC/SR adapters run only when their
+corresponding operation is requested. GF's
+[adapter inventory and regression matrix](https://github.com/xuanheng-tech/git-finalizer/blob/828c35a3bc3d60c5ef25f1fb5221a086e749c0b5/docs/integration-boundaries.md)
+is the consumer-owned authority. WC owns lifecycle; a GF execution receipt still needs the
+formal `lease-complete` flow before lifecycle completion.
+
+Two bounded legacy couplings remain: GF checks WC namespace directory **existence** to report
+a migration blocker, and recognizes exact public contract descriptions in its scanner. Neither
+is general private-state parsing. Replace the existence probe only after a producer-owned
+public unmanaged/legacy/migrated verdict exists and all negative controls pass. Keep the narrow
+scanner recognition until an agreed producer/consumer contract change replaces it; never widen
+the scanner or silently fall back to private files.
+
+## Host consumers
+
+A fresh inspection of AW's current controller client confirms the following source call paths:
+
+| Surface | Evidence classification | Ownership decision |
+| --- | --- | --- |
+| `host-execution`, `execution-admit/cancel`, `admission-queue` | Direct calls | WC governs admission and resource claims; AW keeps business scheduling and host policy. |
+| `session-admit` | Direct `_invoke` call after capability negotiation | Supported. The earlier audit's absence claim is obsolete. |
+| `session-bind` | Argument tuple passed through `_run`, rather than a literal `_invoke` call | Supported. An `_invoke`-only search misses this consumer. |
+| `binding-add/remove/transfer` | Transfer is direct; add/remove are dynamically composed by a bounded helper | Supported; explicit client/session identity and existing lease checks remain required. |
+| `lifecycle-events`, `lifecycle-event-ack` | Direct calls | WC owns event identity; AW acknowledges after its own durable update. |
+| `reconcile-session` | No direct external AW CLI call found in this inspection; WC's shipped session-end adapter calls the lifecycle function | Supported. No proof of exclusive use or safe deprecation. |
+
+Also observed: plan/acquire/resume/status/capabilities, writer lease acquire/release and write
+guard; integration queue/refresh/validate, publication lease acquire/complete, reconciliation,
+release-intent and lifecycle-history. Static literals are evidence of a call path, not runtime
+frequency or a complete list of dynamically constructed commands.
+
+No AW identity default, resource limit, QP policy or business approval changes in this inventory.
+Any future host-policy relocation needs consumer-owned changes, staged compatibility, migration
+and rollback. Recovery commands remain supported until all consumers have an evidence-backed
+migration and a published deprecation window.
+
+## Regression and change gates
+
+- WC: public CLI/API contract tests plus the affected lifecycle/recovery suites, and the complete
+  integration gate for shared changes. A pure helper extraction preserves clocks, locks, request
+  identity, immutable history, refusal codes, retry timing and aliases.
+- GF: its existing boundary tests, public-protocol negative controls and required real WC/SR
+  release gate. A consumer stub is not a substitute for real producer acceptance.
+- Host: installed capability checks and the consumer's existing acceptance command before
+  activation. Source inspection is not installed-runtime or live-business acceptance.
+- Preserve old receipts and explicit version allowlists. Do not count an expected nonzero refusal
+  as functional success, and do not infer business completion from a clean checkout.

worktree_controller-1.32.4/docs/roadmap.md

@@ -0,0 +1,46 @@
+# Maintenance roadmap
+
+Execution baseline: 2026-10-23. This is the WC portion of the approved four-tool maintenance
+direction. Each stage needs its own tested deliverable; later ideas are not current behavior.
+
+## Current baseline
+
+WC 1.32.4 retains CLI contract 61 and storage layout 5. The scope and architecture documents
+are already on main. Two previous extractions reduced private cross-module imports from 93 to
+82; this batch moves pure release-intent selection/backoff queries into one module, reducing
+the baseline to 80. It retains lifecycle mutation helpers, clocks and internal aliases.
+
+GF 1.9.7 already consumes SR's public read API and WC's versioned publication/retirement
+protocols. CL 1.3.10 and SR 2.5.12 already use main on both hosting platforms. These completed
+items are not prerequisites still waiting to happen.
+
+[Consumer boundaries](integration-boundaries.md) correct the earlier AW session-call inventory.
+Remaining evidence gaps are external consumer usage, installed-host behavior beyond the existing
+acceptance gates, and historical temporary-file impact. No historical evidence is cleaned up.
+
+## Sequence and acceptance
+
+| Stage | Deliverable | Exit evidence | Stop or rollback boundary |
+| --- | --- | --- | --- |
+| Now: boundaries | Current protocol and consumer inventory, including legacy adapters | Named owner per interface, source references, explicit unknowns; no changes to supported commands | Conflicting evidence keeps the interface supported |
+| Now: WC structure | One cohesive pure release-intent query extraction | Full integration gate; existing renewal/cancellation/recovery behavior; CLI 61/storage 5 unchanged | Revert the isolated extraction if behavior differs |
+| Pilot: shared quality checks | Local release-tools candidate and CL integration packet with a full commit pin | Workflow lint, CL local quality check, then all supported Python versions on real hosted CI after publication | Restore the pinned original CL workflow; PyPI/Gitea flows remain owned by consumers |
+| Next 2–6 weeks | Further WC extraction only where a shared responsibility is clear; measure maintenance burden and failures | One behavior-preserving batch at a time, consumer gates, shrinking private-import baseline | Keep injected clocks, transaction and crash hooks with their owner until an explicit migration is tested |
+| Following 6–12 weeks | Evaluate moving manifests, compatibility catalog and shared Skills from GF to a dedicated toolchain owner | Full ownership inventory, staged installer/migration, exactly one active writer, historical pin and rollback tests | No second simultaneous Skill authority; no ownership switch on file-copy evidence |
+| Following 3–6 months | Evaluate a staged GF Python core migration | Characterization of exit/status/ref effects, isolated old/new comparisons, interruption recovery and real consumer gates | No dual production writes; preserve scanner refusals and existing installation until replacement passes |
+
+The time ranges express ordering, not release deadlines. Batch internal maintenance with a
+planned software release instead of increasing the CLI contract for every refactor. A public
+behavior change still requires explicit contract/capability review and compatibility updates.
+
+## Shared workflow pilot boundary
+
+Start with CL and retain its Python matrix and `just check`; only after hosted equivalence is
+proved adopt SR with its additional package check. Pin all workflow dependencies to reviewed
+commits. Keep upload jobs and their Trusted Publisher/environment in each repository's top-level
+release workflow. First publication of a new public repository requires its own authorization.
+
+Do not introduce a shared runtime Python dependency into CL/SR, merge the tools, relax SR's
+Python floor, move host-specific defaults without migration, or replace existing WC/GF protocols.
+GitHub-first release consolidation and a future toolchain repository remain design decisions,
+not permission to disable existing Gitea delivery or platform controls.

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/docs/scope.md

@@ -4,16 +4,18 @@ This document records which parts of the public CLI are generic worktree governa
 exist mainly for one consumer. It is an inventory plus proposed boundaries; nothing here changes
 behavior, and every "proposed" line needs an owner decision before code moves.
 
-Snapshot: CLI contract 61, 81 commands, 65 `*_version` capability keys. The public contract
-counts were rechecked on 2026-10-23; consumer mappings below are the cloud audit
-reported in the maintainer handoff, not a runtime trace or proof of exclusive use.
+Snapshot: WC 1.32.3, CLI contract 61, 81 commands, 66 `*_version` capability keys. The public contract
+counts were rechecked on 2026-10-23. Host call paths were rechecked against current
+consumer source; this remains static evidence, not a runtime trace or proof of exclusive use.
+See [consumer boundaries](integration-boundaries.md) for the updated protocol inventory.
 
 ## How the inventory was made
 
 - **Agent Workspace (AW):** every `_invoke(...)` call in AW's controller client
-  (`backend/src/agent_workspace/infrastructure/worktree_controller.py`) plus its session-retirement
-  and external-execution modules. This was an exact static match in that audit, not a guarantee
-  that dynamic or other consumers do not exist.
+  (`backend/src/agent_workspace/infrastructure/worktree_controller.py`), plus argument tuples
+  passed through `_run`, bounded dynamic binding helpers, session-retirement and external-execution
+  modules. The earlier `_invoke`-only inventory missed `session-bind`. This is not proof that
+  dynamic or other consumers do not exist.
 - **Git Finalizer (GF):** word match over `git-finalize*` and `tooling/*.py`. Common words
   (`review`, `task`, `release`, `resume`, `status`, `doctor`) can be false positives; the
   retirement and publication entries are confirmed by GF's adapter code.
@@ -34,7 +36,8 @@ Checkout budget, ownership and safe release for any person or agent sharing a re
 
 `branch-retirement-plan`, `-verify`, `-authorize`, `-complete`, `-record`, `-status`,
 `-executions`, and `publication-execution-session`. These are the public protocols GF consumes
-through capabilities; they should evolve by capability version, not by CLI contract number.
+through versioned capabilities and protocols. This does not relax explicit CLI/storage version
+allowlists in the deployment catalog or permit unknown versions. See [boundaries](integration-boundaries.md).
 
 ## 3. Host-runtime integration (used by AW today)
 
@@ -45,7 +48,8 @@ through capabilities; they should evolve by capability version, not by CLI contr
 | `admission-queue` | yes | Periodic queue reconciliation |
 | `binding-add`, `binding-remove`, `binding-transfer` | yes | Runtime bindings owned by a host |
 | `lifecycle-events`, `lifecycle-event-ack` | yes | Event feed with consumer acknowledgement |
-| `session-admit`, `session-bind`, `reconcile-session` | not found in AW's client | Need an owner answer: other host, legacy, or removable |
+| `session-admit`, `session-bind` | yes, confirmed in current source | Capability-negotiated direct/tuple call paths; retain support |
+| `reconcile-session` | no direct external AW CLI call found | WC session-end calls its lifecycle function; other external consumers remain unverified |
 
 **Proposed:** keep these in WC only if they are documented as a generic *host runtime protocol*
 (any host, explicit `--client-id`, no AW-specific defaults or wording). Otherwise move the
@@ -61,7 +65,8 @@ and binding records.
 `reconcile-writers`, `acquire-across`, `acquire-when-free`, `canonical-refresh`,
 `canonical-transition`, `namespace-migration-plan`, `-verify`, `-receipts`, `namespace-migrate`.
 
-Most of these have no consumer in AW or GF and appear only in reference docs, or not at all.
+A static AW/GF inventory cannot establish usage by operators, other hosts or indirect adapters.
+These commands remain supported; lack of a literal call is not deprecation evidence.
 
 **Proposed:** classify each as *supported*, *operator-only* or *deprecated* in the CLI contract,
 publish a deprecation window for the last group, and stop adding a new top-level command per
@@ -70,7 +75,8 @@ recovery case — prefer one `recover` entry with typed subcases.
 ## Open questions for the owner
 
 1. Is `host-execution` meant for hosts other than AW? If not, should its policy move to AW?
-2. Who uses `session-admit`, `session-bind` and `reconcile-session`?
+2. Which additional consumers use the session interfaces? AW use of `session-admit` and
+   `session-bind` is confirmed; direct external `reconcile-session` usage remains unverified.
 3. Which section-4 commands may be deprecated, and on what timeline?
 
 ## Current compatibility decision

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.32.2"
+version = "1.32.4"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.32.2"
+version = "1.32.4"
 description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
 readme = "README.md"
 requires-python = ">=3.12,<3.13"

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/__init__.py

@@ -1,3 +1,3 @@
 """Worktree lifecycle controller."""
 
-__version__ = "1.32.2"
+__version__ = "1.32.4"

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/cli.py

@@ -1047,6 +1047,7 @@ def _main(argv: list[str] | None) -> int:
                 "preservation_supersession_version": 1,
                 "retained_typed_cleanup_version": 1,
                 "aborted_integration_preserved_cleanup_version": 1,
+                "terminal_preserved_cleanup_version": 1,
                 "preservation_leaf_version": 1,
                 "integration_publication_execution_version": 1,
                 "integration_retry_version": 1,

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/convergence.py

@@ -316,11 +316,11 @@ def _require_intent_renewal_due(
     stays blocked. The same rule as stale-intent renewal applies: a changed record or
     HEAD, or a first expiry, proceeds at once.
     """
-    from .lifecycle import _release_intents_for_allocation, _renewal_due
+    from .release_intents import release_intent_renewal_due, release_intents_for_allocation
 
     canonical = inventory(repository_path)
     snapshot = MetadataStore(canonical.common_dir).load()
-    intents = _release_intents_for_allocation(snapshot, record.allocation_id)
+    intents = release_intents_for_allocation(snapshot, record.allocation_id)
     if any(intent.status in {"PENDING", "BLOCKED_RETRYABLE"} for intent in intents):
         return  # create_release_intent reuses the live intent
     stale = [intent for intent in intents if intent.status == "STALE"]
@@ -329,7 +329,7 @@ def _require_intent_renewal_due(
     # The backoff runs from the most recent time an intent of this allocation went stale.
     latest = max(stale, key=lambda intent: (intent.updated_at, intent.created_at, intent.intent_id))
     ttl = load_policy(canonical.canonical_path).release_intent_ttl_seconds
-    if not _renewal_due(snapshot, latest, record, item.head, datetime.now(UTC), ttl):
+    if not release_intent_renewal_due(snapshot, latest, record, item.head, datetime.now(UTC), ttl):
         raise ControllerError(
             "RENEWAL_BACKOFF",
             f"unchanged handoff release intent is backing off after {latest.blocker or 'expiry'}",

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/delivered_closeout.py

@@ -136,8 +136,119 @@ def _legacy_no_change(store: MetadataStore, item: WorktreeGitState, record: Meta
     return original
 
 
+def _has_pre_completion_cleanup(store: MetadataStore, record: MetadataRecord) -> bool:
+    from .cleanup_evidence import read
+
+    for path in sorted(store.completion_receipts_dir.glob("*.json")):
+        value, _ = read(path)
+        plan = value.get("plan", {})
+        if plan.get("allocation_id") == record.allocation_id and plan.get("terminal_evidence") is None:
+            return True
+    return False
+
+
+def terminal_cleanup_evidence(store: MetadataStore, snapshot: MetadataSnapshot,
+                              item: WorktreeGitState, record: MetadataRecord) -> dict[str, Any]:
+    """Pin existing terminal proof without reopening a frozen allocation.
+
+    Legacy no-change receipts acquire a verified baseline now, never a claim of
+    historical digest observation. New completions can clean at their terminal
+    CAS only when they froze an empty prior cleanup set.
+    """
+    from .cleanup_evidence import read
+    from .semantics import publication_receipt_lease_released
+
+    def invalid():
+        return ControllerError("TERMINAL_CLEANUP_EVIDENCE_INVALID",
+                               "exact lease-cleared publication or no-change completion required")
+
+    try:
+        if record.lifecycle == "PUBLISHED" and record.role == "integration":
+            matches = [receipt for receipt in snapshot.publication_receipts.values()
+                       if receipt.allocation_id == record.allocation_id]
+            if len(matches) != 1:
+                raise invalid()
+            receipt = matches[0]
+            if (receipt.repository_id != snapshot.repository_id
+                    or receipt.status not in {"REMOTE_VERIFIED", "RELEASED"}
+                    or not receipt.remote_verified_at
+                    or not publication_receipt_lease_released(snapshot, receipt)
+                    or receipt.candidate_oid != item.head
+                    or receipt.finalizer_record_id != record.finalizer_record_id
+                    or not receipt.validation_evidence_id):
+                raise invalid()
+            intents = [intent for intent in snapshot.integration_intents.values()
+                       if intent.allocation_id == record.allocation_id]
+            if receipt.intent_id is not None or intents:
+                if len(intents) != 1:
+                    raise invalid()
+                intent = intents[0]
+                if (receipt.intent_id != intent.intent_id
+                        or intent.allocation_id != record.allocation_id
+                        or intent.publication_identity != receipt.receipt_id
+                        or intent.candidate_oid != item.head
+                        or intent.validation_evidence_id != receipt.validation_evidence_id):
+                    raise invalid()
+            from .store import publication_receipt_to_dict
+
+            receipt_path = store.publication_receipts_dir / f"{receipt.receipt_id}.json"
+            receipt_value, receipt_digest = read(receipt_path)
+            if receipt_value != publication_receipt_to_dict(receipt):
+                raise invalid()
+            # The producer receipt is immutable; later closeout has separate evidence.
+            return {"contract": "terminal-preserved-cleanup/v1", "kind": "publication",
+                    "receipt_id": receipt.receipt_id,
+                    "receipt_ref": {"path": str(receipt_path), "sha256": receipt_digest},
+                    "repository_id": receipt.repository_id,
+                    "allocation_id": receipt.allocation_id, "intent_id": receipt.intent_id,
+                    "candidate_oid": receipt.candidate_oid,
+                    "finalizer_record_id": receipt.finalizer_record_id,
+                    "validation_evidence_id": receipt.validation_evidence_id,
+                    "remote_verified_at": receipt.remote_verified_at}
+        if (record.lifecycle != "NO_CHANGE_COMPLETED" or record.role not in {"feature", "audit"}
+                or not record.history):
+            raise invalid()
+        completion_ref = record.history[-1].get("no_change_completion_ref")
+        if completion_ref:
+            receipt = _completion_document(store, completion_ref)
+            original = record_from_dict(receipt["before_record"])
+            event = record.history[-1]
+            if (receipt.get("contract") != NO_CHANGE_CONTRACT
+                    or receipt.get("kind") != "no_change_completion"
+                    or receipt.get("preservation_cleanup_receipts") != []
+                    or _no_change_transition(original, event) != record
+                    or {key: value for key, value in event.items() if key != "no_change_completion_ref"}
+                    != receipt["completion_event"]):
+                raise invalid()
+            _no_change_identity(receipt, original, item, snapshot.repository_id)
+            if not (_no_change_time(original.last_reviewed_at)
+                    <= _no_change_time(receipt["completed_at"]) <= _no_change_time(event["at"])):
+                raise invalid()
+            if _has_pre_completion_cleanup(store, record):
+                raise invalid()
+            return {"contract": "terminal-preserved-cleanup/v1", "kind": "no_change",
+                    "completion_ref": completion_ref}
+        matches = []
+        for path in sorted(store.completion_receipts_dir.glob("*.json")):
+            value, digest = read(path)
+            if (value.get("kind") == "no_change_completion"
+                    and value.get("allocation_id") == record.allocation_id):
+                matches.append({"receipt_id": path.stem, "path": str(path), "sha256": digest})
+        if len(matches) != 1:
+            raise invalid()
+        ref = matches[0]
+        _legacy_no_change(store, item, record, snapshot.repository_id, ref)
+        return {"contract": "terminal-preserved-cleanup/v1", "kind": "legacy_no_change",
+                "completion_ref": ref}
+    except (OSError, KeyError, TypeError, ValueError, IndexError, ControllerError) as exc:
+        raise invalid() from exc
+
+
 def verify_no_change_cleanup(store: MetadataStore, item: WorktreeGitState,
-                             record: MetadataRecord, repository_id: str | None) -> list[dict[str, str]]:
+                             record: MetadataRecord, repository_id: str | None, *,
+                             cleanup_recovery: dict[str, Any] | None = None,
+                             cleanup_transaction_id: str | None = None,
+                             allow_pending_typed_no_action: bool = False) -> list[dict[str, str]]:
     """Bridge only frozen normal transitions; cleanup keeps its original exact CAS."""
     from .preserved_cleanup import cleanup_receipts
 
@@ -157,6 +268,14 @@ def verify_no_change_cleanup(store: MetadataStore, item: WorktreeGitState,
                     <= _no_change_time(receipt["completed_at"]) <= _no_change_time(event["at"])):
                 raise _no_change_fail("completion timestamp differs from its transition")
             refs = receipt["preservation_cleanup_receipts"]
+            if refs == [] and not _has_pre_completion_cleanup(store, record):
+                terminal_cleanup_evidence(store, store._load_unlocked(), item, record)
+                return cleanup_receipts(
+                    store, item, record, repository_id, cleanup_recovery=cleanup_recovery,
+                    cleanup_transaction_id=cleanup_transaction_id,
+                    allow_pending_typed_no_action=allow_pending_typed_no_action,
+                    include_no_action_refs=True,
+                )
         elif receipt.get("kind") == "no_change_cleanup_recovery":
             plan = receipt["plan"]
             legacy = record_from_dict(plan["record"])

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/lifecycle.py

@@ -79,6 +79,9 @@ from .preserved_cleanup import CONTRACT as PRESERVED_CLEANUP_CONTRACT
 from .preserved_cleanup import coverage, delete_preserved_state
 from .record_updates import updated_intent as _updated_intent
 from .record_updates import updated_record as _updated_record
+from .release_intents import RENEWAL_BACKOFF_CAP_SECONDS as RENEWAL_BACKOFF_CAP_SECONDS
+from .release_intents import release_intent_renewal_due as _renewal_due
+from .release_intents import release_intents_for_allocation as _release_intents_for_allocation
 from .semantics import assert_record_version as _cas
 from .semantics import (
     attribution_base,
@@ -95,6 +98,7 @@ from .semantics import (
 from .semantics import effective_intent_state as _effective_intent_state
 from .semantics import integration_reconciliation as _integration_reconciliation
 from .semantics import managed_record as _managed_record
+from .semantics import publication_receipt_lease_released as _publication_receipt_lease_released
 from .semantics import record_for as _record_for
 from .store import (
     INTEGRATION_INTENT_CONTRACT_VERSION,
@@ -348,54 +352,6 @@ def _updated_release_intent(intent: ReleaseIntent, event: str, **changes: Any) -
     return release_intent_from_dict(payload)
 
 
-RENEWAL_BACKOFF_CAP_SECONDS = 24 * 3600
-
-
-def _renewal_due(
-    snapshot: MetadataSnapshot,
-    previous: ReleaseIntent,
-    record: MetadataRecord,
-    head: str,
-    now: datetime,
-    ttl_seconds: int,
-) -> bool:
-    """Whether a stale release intent should be renewed on this pass.
-
-    The first expiry, or a changed record or HEAD, is renewed at once. Each further
-    stale intent of an unchanged identity failed the same way, so the next renewal
-    waits the TTL doubled per repeat, capped at a day. Renewal stays eventual (a stuck
-    checkout is still retried) while one blocked allocation no longer adds an intent
-    on every reconciliation pass.
-    """
-    if (previous.expected_record_version, previous.expected_head) != (record.record_version, head):
-        return True
-    streak = sum(
-        1
-        for intent in _release_intents_for_allocation(snapshot, record.allocation_id)
-        if intent.status == "STALE"
-        and (intent.expected_record_version, intent.expected_head) == (record.record_version, head)
-    )
-    if streak <= 1:
-        return True
-    delay = min(ttl_seconds * 2 ** (streak - 2), RENEWAL_BACKOFF_CAP_SECONDS)
-    return (now - datetime.fromisoformat(previous.updated_at)).total_seconds() >= delay
-
-
-def _release_intents_for_allocation(
-    snapshot: MetadataSnapshot, allocation_id: str
-) -> tuple[ReleaseIntent, ...]:
-    return tuple(
-        sorted(
-            (
-                intent
-                for intent in snapshot.release_intents.values()
-                if intent.allocation_id == allocation_id
-            ),
-            key=lambda intent: (intent.created_at, intent.intent_id),
-        )
-    )
-
-
 def _cancel_release_intents(
     store: MetadataStore,
     snapshot: MetadataSnapshot,
@@ -4760,6 +4716,7 @@ def _typed_cleanup_plan_locked(
     blockers: list[dict[str, str]] = []
     aborted_integration = record.role == "integration" and record.lifecycle == "INTEGRATION_ABORTED"
     integration_abort_evidence = None
+    terminal_evidence = None
     preserved_evidence = None
     preserved_evidences: list[dict[str, Any]] = []
     multiple = bool(additional_preservation_receipts or additional_preservation_receipt_sha256)
@@ -4907,6 +4864,12 @@ def _typed_cleanup_plan_locked(
             from .integration_cleanup import abort_evidence
 
             integration_abort_evidence = abort_evidence(store, snapshot, item, record)
+        elif ((record.lifecycle == "PUBLISHED" and record.role == "integration")
+              or (record.lifecycle == "NO_CHANGE_COMPLETED" and not archived_no_commit
+                  and record.history)):
+            from .delivered_closeout import terminal_cleanup_evidence
+
+            terminal_evidence = terminal_cleanup_evidence(store, snapshot, item, record)
         elif (record.lifecycle != "HANDOFF_READY" and not archived_no_commit and not retained_cleanup) or record.role not in {
             "feature",
             "audit",
@@ -4963,13 +4926,13 @@ def _typed_cleanup_plan_locked(
         runtime_evidence["scan_error"] = {"code": exc.code, "message": str(exc)}
         blockers.append({"code": exc.code, "message": str(exc)})
     for resource in resources:
-        if aborted_integration and resource["cleanup_action"] == "remove-tree":
+        if (aborted_integration or terminal_evidence is not None) and resource["cleanup_action"] == "remove-tree":
             # This additional lifecycle has no project-name/path allowlist. Even
             # otherwise recognized build output requires an exact preserved copy.
             resource.update(
                 classification="blocked", cleanup_action="none",
-                blocker="INTEGRATION_PRESERVATION_REQUIRED",
-                reason="aborted integration cleanup requires exact preservation for every tree",
+                blocker="INTEGRATION_PRESERVATION_REQUIRED" if aborted_integration else "TERMINAL_PRESERVATION_REQUIRED",
+                reason="terminal integration/no-change cleanup requires exact preservation for every tree",
             )
         if resource["blocker"]:
             blockers.append(
@@ -5039,6 +5002,8 @@ def _typed_cleanup_plan_locked(
         identity["preservation_evidence"] = preserved_evidence
     if multiple:
         identity["preservation_evidences"] = preserved_evidences
+    if terminal_evidence is not None:
+        identity["terminal_evidence"] = terminal_evidence
     if integration_abort_evidence is not None:
         identity["integration_abort_evidence"] = integration_abort_evidence
     if recovery is not None:
@@ -6215,32 +6180,6 @@ def _reconciliation_for_publication_receipt(
     return matches[0] if matches else None
 
 
-def _lease_release_reconciliation_for_publication_receipt(
-    snapshot: MetadataSnapshot, receipt_id: str
-) -> ReconciliationReceipt | None:
-    matches = [
-        receipt
-        for receipt in snapshot.reconciliation_receipts.values()
-        if receipt.source_receipt_id == receipt_id
-        and receipt.result == "LEASE_RELEASE_ACKNOWLEDGED"
-    ]
-    if len(matches) > 1:
-        raise ControllerError(
-            "RECONCILIATION_DRIFT", "publication receipt has multiple lease reconciliations"
-        )
-    return matches[0] if matches else None
-
-
-def _publication_receipt_lease_released(
-    snapshot: MetadataSnapshot, receipt: PublicationReceipt
-) -> bool:
-    return bool(
-        receipt.lease_released_at is not None
-        or _lease_release_reconciliation_for_publication_receipt(snapshot, receipt.receipt_id)
-        is not None
-    )
-
-
 def _publication_receipt_effectively_released(
     snapshot: MetadataSnapshot, receipt: PublicationReceipt
 ) -> bool:
@@ -7518,7 +7457,11 @@ def _validate_release_core(
     elif record.lifecycle == "NO_CHANGE_COMPLETED" and record.history[-1].get("no_change_completion_ref"):
         from .delivered_closeout import verify_no_change_cleanup
 
-        cleanup_refs = verify_no_change_cleanup(store, item, record, snapshot.repository_id)
+        cleanup_refs = verify_no_change_cleanup(
+            store, item, record, snapshot.repository_id, cleanup_recovery=cleanup_recovery,
+            cleanup_transaction_id=cleanup_transaction_id,
+            allow_pending_typed_no_action=allow_pending_typed_no_action,
+        )
     else:
         cleanup_refs = cleanup_receipts(
             store, item, record, snapshot.repository_id,

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/preserved_cleanup.py

@@ -640,6 +640,11 @@ def cleanup_receipts(
             plan = receipt.get("plan", {})
             if plan.get("allocation_id") != record.allocation_id:
                 continue
+            if plan.get("terminal_evidence") is not None:
+                from .delivered_closeout import terminal_cleanup_evidence
+
+                if terminal_cleanup_evidence(store, store._load_unlocked(), item, record) != plan["terminal_evidence"]:
+                    raise _blocked("terminal completion evidence changed after cleanup")
             if plan.get("integration_abort_evidence") is not None:
                 from .integration_cleanup import abort_evidence
 

worktree_controller-1.32.4/src/worktree_controller/release_intents.py

@@ -0,0 +1,57 @@
+"""Pure queries over the caller's release-intent snapshot.
+
+Callers retain ownership of clocks, locks and all release-intent mutations.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+from .models import MetadataRecord, MetadataSnapshot, ReleaseIntent
+
+RENEWAL_BACKOFF_CAP_SECONDS = 24 * 3600
+
+
+def release_intent_renewal_due(
+    snapshot: MetadataSnapshot,
+    previous: ReleaseIntent,
+    record: MetadataRecord,
+    head: str,
+    now: datetime,
+    ttl_seconds: int,
+) -> bool:
+    """Whether a stale release intent should be renewed on this pass.
+
+    The first expiry, or a changed record or HEAD, is renewed at once. Each further
+    stale intent of an unchanged identity failed the same way, so the next renewal
+    waits the TTL doubled per repeat, capped at a day. Renewal stays eventual (a stuck
+    checkout is still retried) while one blocked allocation no longer adds an intent
+    on every reconciliation pass.
+    """
+    if (previous.expected_record_version, previous.expected_head) != (record.record_version, head):
+        return True
+    streak = sum(
+        1
+        for intent in release_intents_for_allocation(snapshot, record.allocation_id)
+        if intent.status == "STALE"
+        and (intent.expected_record_version, intent.expected_head) == (record.record_version, head)
+    )
+    if streak <= 1:
+        return True
+    delay = min(ttl_seconds * 2 ** (streak - 2), RENEWAL_BACKOFF_CAP_SECONDS)
+    return (now - datetime.fromisoformat(previous.updated_at)).total_seconds() >= delay
+
+
+def release_intents_for_allocation(
+    snapshot: MetadataSnapshot, allocation_id: str
+) -> tuple[ReleaseIntent, ...]:
+    return tuple(
+        sorted(
+            (
+                intent
+                for intent in snapshot.release_intents.values()
+                if intent.allocation_id == allocation_id
+            ),
+            key=lambda intent: (intent.created_at, intent.intent_id),
+        )
+    )

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/semantics.py

@@ -20,6 +20,8 @@ from .models import (
     IntegrationReconciliationReceipt,
     MetadataRecord,
     MetadataSnapshot,
+    PublicationReceipt,
+    ReconciliationReceipt,
     RepositoryInventory,
     WorktreeGitState,
     WorktreePolicy,
@@ -29,6 +31,32 @@ from .policy import load_policy
 EVIDENCE_LIFECYCLES = frozenset({"HANDOFF_READY", "PRESERVED", "INTEGRATING", "PUBLISHED"})
 
 
+def _lease_release_reconciliation_for_publication_receipt(
+    snapshot: MetadataSnapshot, receipt_id: str
+) -> ReconciliationReceipt | None:
+    matches = [
+        receipt
+        for receipt in snapshot.reconciliation_receipts.values()
+        if receipt.source_receipt_id == receipt_id
+        and receipt.result == "LEASE_RELEASE_ACKNOWLEDGED"
+    ]
+    if len(matches) > 1:
+        raise ControllerError(
+            "RECONCILIATION_DRIFT", "publication receipt has multiple lease reconciliations"
+        )
+    return matches[0] if matches else None
+
+
+def publication_receipt_lease_released(
+    snapshot: MetadataSnapshot, receipt: PublicationReceipt
+) -> bool:
+    return bool(
+        receipt.lease_released_at is not None
+        or _lease_release_reconciliation_for_publication_receipt(snapshot, receipt.receipt_id)
+        is not None
+    )
+
+
 def record_for(item: WorktreeGitState, snapshot: MetadataSnapshot) -> MetadataRecord | None:
     allocation_id = snapshot.bindings.get(item.key)
     if allocation_id is None:

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/src/worktree_controller/tool_cli_contract.json

@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.32.2",
+  "tool_version": "1.32.4",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,
@@ -1512,6 +1512,14 @@
     "single_input_compatibility": "existing single receipt contract, plan and receipt shape remain unchanged",
     "storage_layout_version": 4
   },
+  "terminal_preserved_cleanup_version": 1,
+  "terminal_preserved_cleanup_contract": {
+    "contract": "terminal-preserved-cleanup/v1",
+    "eligible": "PUBLISHED integration with one matching remote-verified publication and cleared publication lease; NO_CHANGE_COMPLETED feature/audit with one verified original completion transition and receipt",
+    "coverage": "every removed tree requires an exact immutable preservation generation; existing owner, HEAD, CAS, retained-ref, binding, runtime, writer and transaction guards remain mandatory",
+    "evidence": "plan pins raw producer publication bytes or exact completion reference; legacy completion establishes a newly verified raw baseline; cleanup and release reverify it without rewriting historical evidence or reopening lifecycle",
+    "new_no_change": "new-format completions with an empty frozen prior cleanup set may clean at the exact terminal CAS; nonempty prior proof sets retain their original pre-completion CAS"
+  },
   "retained_typed_cleanup_version": 1,
   "aborted_integration_preserved_cleanup_version": 1,
   "aborted_integration_preserved_cleanup_contract": {

{worktree_controller-1.32.2 → worktree_controller-1.32.4}/tool_cli_contract.json

@@ -1071,7 +1071,7 @@
   "session_launcher_entrypoint": "worktree-session",
   "session_entrypoint": "worktree-session-end",
   "tool_name": "worktree-controller",
-  "tool_version": "1.32.2",
+  "tool_version": "1.32.4",
   "delivered_closeout_version": 1,
   "retained_archive_version": 1,
   "retention_convergence_version": 2,
@@ -1512,6 +1512,14 @@
     "single_input_compatibility": "existing single receipt contract, plan and receipt shape remain unchanged",
     "storage_layout_version": 4
   },
+  "terminal_preserved_cleanup_version": 1,
+  "terminal_preserved_cleanup_contract": {
+    "contract": "terminal-preserved-cleanup/v1",
+    "eligible": "PUBLISHED integration with one matching remote-verified publication and cleared publication lease; NO_CHANGE_COMPLETED feature/audit with one verified original completion transition and receipt",
+    "coverage": "every removed tree requires an exact immutable preservation generation; existing owner, HEAD, CAS, retained-ref, binding, runtime, writer and transaction guards remain mandatory",
+    "evidence": "plan pins raw producer publication bytes or exact completion reference; legacy completion establishes a newly verified raw baseline; cleanup and release reverify it without rewriting historical evidence or reopening lifecycle",
+    "new_no_change": "new-format completions with an empty frozen prior cleanup set may clean at the exact terminal CAS; nonempty prior proof sets retain their original pre-completion CAS"
+  },
   "retained_typed_cleanup_version": 1,
   "aborted_integration_preserved_cleanup_version": 1,
   "aborted_integration_preserved_cleanup_contract": {