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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: worktree-controller
-Version: 1.32.1
+Version: 1.32.4
 Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -23,7 +23,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 process, and records handoff, integration, recovery and release evidence. Git remains the source
 of truth for files, branches, commits and registered worktrees.
 
-**Current release: 1.32.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.2 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -32,7 +32,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.32.0
+python -m pip install worktree-controller==1.32.2
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -41,7 +41,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
 On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
 distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
-Software version 1.32.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.2 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -50,7 +50,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.32.0
+git checkout v1.32.2
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -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.1 → worktree_controller-1.32.4}/README.md

@@ -6,7 +6,7 @@ It checks repository policy before allocating a worktree, grants writing authori
 process, and records handoff, integration, recovery and release evidence. Git remains the source
 of truth for files, branches, commits and registered worktrees.
 
-**Current release: 1.32.0 · Linux · Python 3.12 · Apache-2.0**
+**Current release: 1.32.2 · Linux · Python 3.12 · Apache-2.0**
 
 ## Install
 
@@ -15,7 +15,7 @@ Use a virtual environment in a new directory:
 ```bash
 python3.12 -m venv .venv
 . .venv/bin/activate
-python -m pip install worktree-controller==1.32.0
+python -m pip install worktree-controller==1.32.2
 worktree-controller --version
 worktree-controller capabilities --json
 ```
@@ -24,7 +24,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
 supported by this release. Its one runtime dependency is `websockets>=15,<16`.
 On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
 distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
-Software version 1.32.0 uses CLI contract **61** and storage layout **5**.
+Software version 1.32.2 uses CLI contract **61** and storage layout **5**.
 
 ## Try it in a disposable repository
 
@@ -33,7 +33,7 @@ With the environment above active:
 ```bash
 git clone https://github.com/xuanheng-tech/worktree-controller.git wc
 cd wc
-git checkout v1.32.0
+git checkout v1.32.2
 python examples/quickstart.py --workspace "$HOME/wc-first-run"
 ```
 
@@ -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.1 → worktree_controller-1.32.4}/docs/architecture.md

@@ -10,8 +10,9 @@ development and recovery paths; exact public interfaces live in the [contract](.
 | --- | --- | --- |
 | CLI parsing and routing | `cli.py`, command modules | Dispatch explicit operations; do not duplicate authority decisions |
 | 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` | Validate stored identities; serialize mutations under the repository lock |
-| Shared identity and semantic checks | `semantics.py` | Consume the caller's snapshot; do not acquire authority or write metadata |
+| 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.4/docs/scope.md

@@ -0,0 +1,92 @@
+# Scope and consumer surface (draft for owner decision)
+
+This document records which parts of the public CLI are generic worktree governance and which
+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: 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 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.
+- **Docs/examples:** word match over `README.md`, `docs/`, `examples/` and the shipped Skill.
+
+## 1. Generic governance core (keep; any client)
+
+Checkout budget, ownership and safe release for any person or agent sharing a repository:
+
+`plan`, `status`, `doctor`, `capabilities`, `acquire`, `adopt`, `park`, `reopen`, `release`,
+`release-intent`, `quarantine`, `review`, `handoff`, `resume`, `task`, `complete-no-change`,
+`recovery-guide`, `lifecycle-history`, `write-guard`, `writer-lease-acquire`,
+`writer-lease-release`, `writer-session`, `lease-acquire`, `lease-complete`, `lease-abort`,
+`integration-enqueue`, `integration-claim`, `integration-validate`, `integration-queue`,
+`integration-refresh`, `reconcile`.
+
+## 2. Delivery-tool protocols (keep; versioned, consumed by GF)
+
+`branch-retirement-plan`, `-verify`, `-authorize`, `-complete`, `-record`, `-status`,
+`-executions`, and `publication-execution-session`. These are the public protocols GF consumes
+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)
+
+| Command | Used by AW | Note |
+| --- | --- | --- |
+| `host-execution` | yes | Budgets a host process with no repository writer lease; default `--client-id` is `agent-workspace` |
+| `execution-admit`, `execution-cancel` | yes | Durable admission of governed executions |
+| `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` | 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
+AW-specific policy (memory budgets, default identities) into AW and keep WC's part to admission
+and binding records.
+
+## 4. Recovery and maintenance tail
+
+`recover-handoff`, `recover-published`, `recovery-adopt`, `release-recovery-inspect`,
+`integration-abort`, `-abandon`, `-reopen`, `-resolve`, `-retry`, `-equivalent`,
+`-recovery-matrix`, `close-delivered`, `close-preserved`, `adopt-delivered`, `archive-retained`,
+`externalize`, `resource-register`, `resource-clean`, `resource-recover`, `gc-plan`, `gc-apply`,
+`reconcile-writers`, `acquire-across`, `acquire-when-free`, `canonical-refresh`,
+`canonical-transition`, `namespace-migration-plan`, `-verify`, `-receipts`, `namespace-migrate`.
+
+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
+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. 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
+
+Keep every existing command supported while these ownership questions are unresolved. Do not
+remove host commands, change default identities, relax recovery guards or deprecate commands
+from an absence of static matches. New hosts use explicit client/session identities and the
+versioned public contracts described in [client integration](client-integration.md). WC remains
+the lifecycle and policy authority; consumers retain their business and release approvals.
+
+Effective integration-state interpretation lives in `semantics.py`;
+record and intent updates live in `record_updates.py`. These moves preserve CLI contract 61 and
+storage layout 5. See [architecture](architecture.md) for module responsibilities.

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

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.32.1"
+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.1 → worktree_controller-1.32.4}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "worktree-controller"
-version = "1.32.1"
+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.1 → worktree_controller-1.32.4}/src/worktree_controller/__init__.py

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

{worktree_controller-1.32.1 → worktree_controller-1.32.4}/src/worktree_controller/canonical_transition.py

@@ -19,7 +19,6 @@ from .git_backend import (
     update_branch_ref,
     validate_branch_name,
 )
-from .lifecycle import _updated_record
 from .models import (
     ControllerError,
     MetadataRecord,
@@ -29,6 +28,7 @@ from .models import (
     WorktreePolicy,
 )
 from .policy import default_policy, load_policy, parse_policy
+from .record_updates import updated_record
 from .semantics import managed_record as _managed_record
 from .store import MetadataStore
 from .transaction_scope import conflicts
@@ -274,7 +274,7 @@ def transition_canonical(
             if not refresh_main and item.branch == expected_branch:
                 git_write(item.path, ("checkout", "--no-overwrite-ignore", expected_branch))
             raise
-        updated = _updated_record(
+        updated = updated_record(
             record,
             "CANONICAL_MAIN_REFRESHED" if refresh_main else "CANONICAL_TRANSITIONED",
             lifecycle="ACTIVE",

{worktree_controller-1.32.1 → 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.1 → worktree_controller-1.32.4}/src/worktree_controller/controller.py

@@ -33,9 +33,9 @@ from .mount_diagnostics import diagnose_mounts, mount_warnings
 from .policy import load_policy
 from .semantics import (
     EVIDENCE_LIFECYCLES,
+    effective_intent_state,
     evidence_head_issues,
     integration_candidate_issues,
-    integration_intent_abandoned,
     integration_queue_order,
     normalize_scope_paths,
     path_scope_issues,
@@ -248,22 +248,6 @@ def _intent_for_allocation(snapshot: MetadataSnapshot, allocation_id: str | None
     return matches[0] if matches else None
 
 
-def _effective_intent_state(snapshot: MetadataSnapshot, intent: Any) -> str:
-    reconciliations = [
-        receipt
-        for receipt in snapshot.integration_reconciliation_receipts.values()
-        if receipt.intent_id == intent.intent_id
-        and receipt.result == "STALE_INTENT_TERMINAL_ACKNOWLEDGED"
-    ]
-    if len(reconciliations) > 1:
-        raise ControllerError(
-            "INVALID_METADATA", "integration intent has multiple terminal reconciliations"
-        )
-    if reconciliations:
-        return reconciliations[0].effective_terminal_state
-    return "ABANDONED" if integration_intent_abandoned(intent) else intent.state
-
-
 def _integration_intent_order(intent: Any) -> tuple[int, int | str, str]:
     if intent.queue_sequence > 0:
         return (1, intent.queue_sequence, intent.intent_id)
@@ -400,7 +384,7 @@ def _repository_payload(
         (
             intent
             for intent in snapshot.integration_intents.values()
-            if _effective_intent_state(snapshot, intent) in {"QUEUED", "WAITING_SCOPE"}
+            if effective_intent_state(snapshot, intent) in {"QUEUED", "WAITING_SCOPE"}
         ),
         key=lambda value: integration_queue_order(snapshot, value),
     )
@@ -543,7 +527,7 @@ def _worktree_payload(
         "source_allocations": list(record.source_allocations) if record else [],
         "integration_intent_id": intent.intent_id if intent else None,
         "integration_intent_state": (
-            _effective_intent_state(snapshot, intent)
+            effective_intent_state(snapshot, intent)
             if intent is not None and snapshot is not None
             else None
         ),
@@ -1317,7 +1301,7 @@ def _semantic_warnings(
         "RELEASED": {"RELEASED"},
     }
     for intent in snapshot.integration_intents.values():
-        effective_state = _effective_intent_state(snapshot, intent)
+        effective_state = effective_intent_state(snapshot, intent)
         if effective_state in {"QUEUED", "WAITING_SCOPE", "ABANDONED"}:
             continue
         if unallocated_integration_conflict(intent):

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

@@ -199,13 +199,13 @@ def _is_candidate(record: MetadataRecord) -> bool:
 
 
 def _integration_bound(snapshot: MetadataSnapshot, record: MetadataRecord) -> bool:
-    from .lifecycle import _effective_intent_state
+    from .semantics import effective_intent_state
 
     return any(
         intent.allocation_id == record.allocation_id
         or record.allocation_id in intent.source_allocations
         for intent in snapshot.integration_intents.values()
-        if _effective_intent_state(snapshot, intent) not in TERMINAL_INTEGRATION_STATES
+        if effective_intent_state(snapshot, intent) not in TERMINAL_INTEGRATION_STATES
     ) or any(
         other.lifecycle != "RELEASED" and record.allocation_id in other.source_allocations
         for other in snapshot.records.values()
@@ -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'}",