worktree-controller 1.32.10__tar.gz → 1.32.12__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/README.md +4 -4
  3. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/operations.md +39 -0
  4. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/reference.md +42 -0
  5. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/roadmap.md +7 -1
  6. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/pyproject.toml +1 -1
  7. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/pyproject.toml.orig +1 -1
  8. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/__init__.py +1 -1
  9. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/cli.py +1 -0
  10. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/lifecycle.py +12 -1
  11. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/preserved_cleanup.py +34 -2
  12. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/store.py +103 -2
  13. {worktree_controller-1.32.10 → worktree_controller-1.32.12/src/worktree_controller}/tool_cli_contract.json +2 -1
  14. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/transaction_scope.py +58 -0
  15. {worktree_controller-1.32.10/src/worktree_controller → worktree_controller-1.32.12}/tool_cli_contract.json +2 -1
  16. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/LICENSE +0 -0
  17. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/architecture.md +0 -0
  18. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/client-integration.md +0 -0
  19. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/daily-workflow.md +0 -0
  20. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/first-change.md +0 -0
  21. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/getting-started.md +0 -0
  22. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/integration-boundaries.md +0 -0
  23. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/publishing.md +0 -0
  24. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/docs/scope.md +0 -0
  25. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/examples/change_task.py +0 -0
  26. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/examples/client_continuation.py +0 -0
  27. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/examples/quickstart.py +0 -0
  28. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/activation_layout.py +0 -0
  29. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/branch_retirement.py +0 -0
  30. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/canonical_refresh.py +0 -0
  31. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/canonical_transition.py +0 -0
  32. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/cleanup_attempts.py +0 -0
  33. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/cleanup_evidence.py +0 -0
  34. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/cleanup_recovery.py +0 -0
  35. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/controller.py +0 -0
  36. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/convergence.py +0 -0
  37. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/delivered_closeout.py +0 -0
  38. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/disposable.py +0 -0
  39. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/environment.py +0 -0
  40. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/frozen_recovery.py +0 -0
  41. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/git_backend.py +0 -0
  42. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/governance.py +0 -0
  43. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/hardlinks.py +0 -0
  44. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/integration_cleanup.py +0 -0
  45. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/integration_conflict.py +0 -0
  46. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/integration_retry.py +0 -0
  47. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/keyed_document_scope.py +0 -0
  48. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/lifecycle_history.py +0 -0
  49. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/lifecycle_observation.py +0 -0
  50. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/metadata_codec.py +0 -0
  51. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/metadata_relocation.py +0 -0
  52. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/models.py +0 -0
  53. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/mount_diagnostics.py +0 -0
  54. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  55. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/namespace_migration.py +0 -0
  56. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/native_session_recovery.py +0 -0
  57. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/owner_actions.py +0 -0
  58. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/policy.py +0 -0
  59. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/preservation.py +0 -0
  60. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/publication_execution.py +0 -0
  61. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/reconciler.py +0 -0
  62. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/record_updates.py +0 -0
  63. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/recovery_guidance.py +0 -0
  64. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/registration_backfill.py +0 -0
  65. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/registration_prune.py +0 -0
  66. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/release_intents.py +0 -0
  67. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/rendering.py +0 -0
  68. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/resource_admission.py +0 -0
  69. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/retirement_adapters.py +0 -0
  70. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/retirement_execution.py +0 -0
  71. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/semantics.py +0 -0
  72. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/session.py +0 -0
  73. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/session_admission.py +0 -0
  74. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/source_cleanup.py +0 -0
  75. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/source_preservation.py +0 -0
  76. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/source_recovery.py +0 -0
  77. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/task_workflow.py +0 -0
  78. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/writer_lease.py +0 -0
  79. {worktree_controller-1.32.10 → worktree_controller-1.32.12}/src/worktree_controller/writer_session.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: worktree-controller
3
- Version: 1.32.10
3
+ Version: 1.32.12
4
4
  Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -23,7 +23,7 @@ It checks repository policy before allocating a worktree, grants writing authori
23
23
  process, and records handoff, integration, recovery and release evidence. Git remains the source
24
24
  of truth for files, branches, commits and registered worktrees.
25
25
 
26
- **Current release: 1.32.10 · Linux · Python 3.12 · Apache-2.0**
26
+ **Current release: 1.32.12 · Linux · Python 3.12 · Apache-2.0**
27
27
 
28
28
  ## Install
29
29
 
@@ -32,7 +32,7 @@ Use a virtual environment in a new directory:
32
32
  ```bash
33
33
  python3.12 -m venv .venv
34
34
  . .venv/bin/activate
35
- python -m pip install worktree-controller==1.32.10
35
+ python -m pip install worktree-controller==1.32.12
36
36
  worktree-controller --version
37
37
  worktree-controller capabilities --json
38
38
  ```
@@ -41,7 +41,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
41
41
  supported by this release. Its one runtime dependency is `websockets>=15,<16`.
42
42
  On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
43
43
  distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
44
- Software version 1.32.10 uses CLI contract **61** and storage layout **5**.
44
+ Software version 1.32.12 uses CLI contract **61** and storage layout **5**.
45
45
 
46
46
  ## Try it in a disposable repository
47
47
 
@@ -50,7 +50,7 @@ With the environment above active:
50
50
  ```bash
51
51
  git clone https://github.com/xuanheng-tech/worktree-controller.git wc
52
52
  cd wc
53
- git checkout v1.32.10
53
+ git checkout v1.32.12
54
54
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
55
55
  ```
56
56
 
@@ -6,7 +6,7 @@ It checks repository policy before allocating a worktree, grants writing authori
6
6
  process, and records handoff, integration, recovery and release evidence. Git remains the source
7
7
  of truth for files, branches, commits and registered worktrees.
8
8
 
9
- **Current release: 1.32.10 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.32.12 · Linux · Python 3.12 · Apache-2.0**
10
10
 
11
11
  ## Install
12
12
 
@@ -15,7 +15,7 @@ Use a virtual environment in a new directory:
15
15
  ```bash
16
16
  python3.12 -m venv .venv
17
17
  . .venv/bin/activate
18
- python -m pip install worktree-controller==1.32.10
18
+ python -m pip install worktree-controller==1.32.12
19
19
  worktree-controller --version
20
20
  worktree-controller capabilities --json
21
21
  ```
@@ -24,7 +24,7 @@ WC requires Git and readable Linux `/proc`. Other operating systems and Python v
24
24
  supported by this release. Its one runtime dependency is `websockets>=15,<16`.
25
25
  On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
26
26
  distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
27
- Software version 1.32.10 uses CLI contract **61** and storage layout **5**.
27
+ Software version 1.32.12 uses CLI contract **61** and storage layout **5**.
28
28
 
29
29
  ## Try it in a disposable repository
30
30
 
@@ -33,7 +33,7 @@ With the environment above active:
33
33
  ```bash
34
34
  git clone https://github.com/xuanheng-tech/worktree-controller.git wc
35
35
  cd wc
36
- git checkout v1.32.10
36
+ git checkout v1.32.12
37
37
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
38
38
  ```
39
39
 
@@ -7,6 +7,27 @@ the [getting started guide](getting-started.md) provides an isolated first run.
7
7
  Client implementers can follow the [AI client integration guide](client-integration.md) and its
8
8
  offline cross-client continuation example.
9
9
 
10
+ ## Repository lock availability
11
+
12
+ Capability `repository_lock_admission_version` 1 adds an entry gate for cooperating runtimes.
13
+ A writer that has entered the gate waits for current readers without admitting later readers
14
+ ahead of it. The existing `repo.lock` still excludes every metadata mutation, including calls
15
+ from older runtimes. Diagnostics retain their coherent snapshot through all checks.
16
+
17
+ Typed cleanup keeps a separate active marker while holding its shared repository lock, so
18
+ ordinary history queries remain available even when a metadata writer is waiting. Doctor
19
+ continues to wait for cleanup's filesystem/journal gate. A cleanup waiting to start does not
20
+ grant this read bypass. The entry gate and active marker use existing directories and kernel
21
+ flocks, introduce no persistent record, and disappear automatically when their process exits.
22
+
23
+ This is not a strict FIFO or a wait-time guarantee. A long existing check or cleanup can still
24
+ delay writers. Older calls do not join the new entry ordering or active marker; mixed-runtime
25
+ operation preserves exclusion but cannot promise the same read availability and ordering.
26
+ Let those owners finish normally, retain their original request and evidence, then reobserve.
27
+ Do not terminate another owner, remove locks, change authority or extend consumer timeouts to
28
+ declare recovery. A completed candidate release can precede its source releases: inspect every
29
+ `source_release_trigger.outcomes` entry and the original receipt query.
30
+
10
31
  ## Start or resume development
11
32
 
12
33
  For everyday feature/audit work, the [task entrypoints](daily-workflow.md) resolve the original
@@ -290,6 +311,24 @@ belongs to the delegated reconciler. Dirty or active work stays with its owner;
290
311
  and immutable receipts are not disposable checkout payloads. For an interrupted release, use
291
312
  `release-recovery-inspect` and replay its exact published recovery arguments.
292
313
 
314
+ From 1.32.11, an already removed feature/audit checkout at `RELEASED_RECORDED` may finish
315
+ its original receipt with its own retained `METADATA_WRITTEN` acquire journal present. The
316
+ original plan and both journal identities must agree with the acquired/released history,
317
+ exact +1 record CAS, retained HEAD and absent checkout, binding and writer lease. Other
318
+ transactions, changed requests and earlier incomplete phases remain blocked. The acquire
319
+ journal is preserved and stays nonterminal until the immutable release receipt is complete.
320
+ This recovery completes evidence only; it does not grant owner authority or business acceptance.
321
+
322
+ If that exact pending release blocks a normal runtime rollout, first deliver and verify the
323
+ repair through source review, tests and normal publication, then stage the exact published
324
+ release through `controller-activate stage`. Its versioned `bin/worktree-controller` is the
325
+ ordinary public CLI: an independently authorized operator may invoke only the original
326
+ `release-recovery-inspect` / returned `release` request with that pinned installed binary.
327
+ Check the public version, staged source manifest and published commit first. No candidate
328
+ activation, active-pin edit, journal edit or rollout exception is involved. Require complete
329
+ exact receipt history, then rerun normal activation with the full governed repository set.
330
+
331
+
293
332
  `reconcile release-plans` keeps plans referenced by durable release receipts. They remain part
294
333
  of closed lifecycle and branch-retirement evidence after the checkout is gone. It retires only
295
334
  unreferenced leftover plans for already released allocations with durable release evidence.
@@ -7,6 +7,40 @@ For a first run, use the [getting started guide](getting-started.md). This refer
7
7
  the detailed contracts, historical compatibility notes and benchmark evidence previously in the README.
8
8
  The [CLI contract](../tool_cli_contract.json) is authoritative for exact interfaces.
9
9
 
10
+ ## Repository lock admission (1.32.12)
11
+
12
+ `repository_lock_admission_version: 1` retains CLI contract 61 and storage layout 5. All new
13
+ entrants take an exclusive flock on the existing metadata-root directory before acquiring
14
+ `repo.lock`, then release that entry gate once admitted. A writer waiting for current readers
15
+ therefore excludes later cooperating readers. A shared read already held by the same PID and
16
+ thread can nest across `MetadataStore` instances without waiting behind its own writer.
17
+
18
+ Typed cleanup still serializes on the transactions directory and holds `repo.lock` shared.
19
+ After admission, it holds a flock on the existing cleanup-actions directory until its final
20
+ scan or failure receipt completes. Readers that find the entry gate occupied can confirm that
21
+ active marker and take their compatible shared `repo.lock`; filesystem/journal diagnostics
22
+ retain their separate cleanup-observation gate. The marker is not release or write authority.
23
+ These locks use the same Linux directory-flock support as the existing cleanup gate.
24
+ Lock diagnostics should include `repository.metadata_path` itself, `repo.lock`,
25
+ `transactions` and `cleanup-actions`; new waiters can be at the entry directory before
26
+ reaching `repo.lock`.
27
+
28
+ The admission gate does not provide strict global FIFO or a finite latency bound. Old code
29
+ continues to obey `repo.lock` but ignores the new entry gate and active marker. Its exclusion
30
+ is preserved; mixed-runtime ordering and history availability can remain limited until those
31
+ calls finish. No lease, receipt, metadata migration, new database or service is introduced.
32
+
33
+ Repeated cleanup checks retain only the allocation scope of unrelated completion documents
34
+ inside the current thread's outermost repository flock, including fresh `MetadataStore`
35
+ instances used by one diagnostic. Each reuse pins and rechecks the regular file and
36
+ ancestor identities, including inode, size, mtime and ctime. Replacement, in-place mutation,
37
+ ownership/type change or symlink substitution forces a fresh read or refusal. Relevant
38
+ documents always receive full byte/hash, plan, action and generation verification; this is
39
+ neither a cached verdict nor a source-tree cache. The scope map clears when the outer flock
40
+ exits. An isolated six-check fixture with sixteen 1 MiB unrelated receipts reduced full document
41
+ reads from 96 to 16 with equal results; this does not establish a production latency bound or
42
+ explain every historical long-held lock.
43
+
10
44
  ## Optional integrations and dependencies
11
45
 
12
46
  The core control plane has a single runtime dependency (`websockets>=15,<16`) and works standalone
@@ -957,6 +991,14 @@ keeps resolving after the move.
957
991
 
958
992
  ## Unified release plan and disposable resources
959
993
 
994
+ From 1.32.11, removed-release replay also admits its exact retained acquire predecessor
995
+ only for a feature/audit `RELEASED_RECORDED` release. Original plan/journal identity, acquired
996
+ and released history, +1 record CAS, retained HEAD, absence of checkout/binding/writer lease,
997
+ and all existing request/resource recovery guards remain mandatory. No journal is classified
998
+ terminal or changed by that admission; complete immutable release evidence is still required.
999
+ Other transactions and unsupported partial phases remain refused. This changes no command,
1000
+ option, capability, CLI contract or storage format.
1001
+
960
1002
  From 1.32.10, typed cleanup serializes on the existing transactions-directory inode while
961
1003
  holding `repo.lock` shared. This excludes normal metadata writers and older exclusive cleanup
962
1004
  implementations for the entire operation, while closed history readers retain their existing
@@ -13,13 +13,19 @@ retain their original owners. Release acceptance covers the exact installed cand
13
13
  1.32.7 upgrades and historical 1.30.4 restoration. Publication and local activation remain
14
14
  separate verified steps. The 1.32.9 patch skips unrelated live Git inventory for closed lifecycle selectors while
15
15
  retaining full locked metadata and immutable evidence validation. The 1.32.10 patch keeps closed history readable during typed cleanup while preserving writer,
16
- cleanup, diagnostic and activation serialization. Software version 1.32.10 retains
16
+ cleanup, diagnostic and activation serialization. Software version 1.32.11 retains
17
17
  CLI contract 61, the existing capability versions and storage layout 5, and serializes doctor
18
18
  snapshot reads with normal Controller mutations. Diagnostics refresh Git inventory after taking
19
19
  the shared repository lock, then retain it through semantic, transaction and retirement checks.
20
20
  The regression uses a real guarded release and verifies the retained commit and branch; a truly
21
21
  missing commit still refuses through both the API and CLI.
22
22
 
23
+ The 1.32.12 patch adds cooperating reader/writer entry ordering and an active-cleanup marker
24
+ on existing directories, while retaining CLI 61 / storage 5. Repeated cleanup checks reuse only
25
+ unchanged unrelated receipt scopes inside one flock. Late-reader bypass and repeated decoding
26
+ are independently reproduced; long-held checks, mixed old runtimes and exact site latency
27
+ remain separate observations, not a claim that every historical delay has been explained.
28
+
23
29
  The original intermittent commit-resolution report did not retain enough per-command evidence
24
30
  to establish its exact cause. The isolated concurrency defect is reproducible; that does not
25
31
  prove the historical report had the same cause. Site-specific owner actions remain separate
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.10"
7
+ version = "1.32.12"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.13"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.10"
7
+ version = "1.32.12"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.13"
@@ -1,3 +1,3 @@
1
1
  """Worktree lifecycle controller."""
2
2
 
3
- __version__ = "1.32.10"
3
+ __version__ = "1.32.12"
@@ -1039,6 +1039,7 @@ def _main(argv: list[str] | None) -> int:
1039
1039
  "canonical_transition_retirement_version": 1,
1040
1040
  "closed_lifecycle_query_version": 1,
1041
1041
  "source_release_summary_version": 1,
1042
+ "repository_lock_admission_version": 1,
1042
1043
  "tracked_source_progress_recovery_version": 1,
1043
1044
  "published_checkout_recovery_version": 1,
1044
1045
  "published_handoff_resource_registration_version": 1,
@@ -7820,6 +7820,7 @@ def _release_transaction(
7820
7820
  *,
7821
7821
  target_path: str,
7822
7822
  allocation_id: str | None = None,
7823
+ removed_release_recovery: bool = False,
7823
7824
  ) -> dict[str, Any] | None:
7824
7825
  if not store.transactions_dir.exists():
7825
7826
  return None
@@ -7836,6 +7837,14 @@ def _release_transaction(
7836
7837
  and transaction.get("target_path") == target_path
7837
7838
  and (allocation_id is None or transaction.get("allocation_id") == allocation_id)
7838
7839
  ]
7840
+ if removed_release_recovery and len(matches) == 1 and len(transactions) == 2:
7841
+ from .transaction_scope import acquire_precedes_removed_release
7842
+
7843
+ other, = (row for row in transactions if row is not matches[0])
7844
+ if other.get("command") == "acquire" and acquire_precedes_removed_release(
7845
+ store, other["transaction_id"], matches[0]
7846
+ ):
7847
+ transactions = matches
7839
7848
  if len(matches) > 1 or len(matches) != len(transactions):
7840
7849
  raise ControllerError(
7841
7850
  "INTERRUPTED_TRANSACTION", "another controller transaction requires recovery"
@@ -8561,7 +8570,9 @@ def _recover_or_replay_removed_release(
8561
8570
  raise ControllerError(
8562
8571
  "BLOCK_DRIFT", "release target remains registered but is unavailable"
8563
8572
  )
8564
- transaction = _release_transaction(store, target_path=target_path)
8573
+ transaction = _release_transaction(
8574
+ store, target_path=target_path, removed_release_recovery=not dry_run,
8575
+ )
8565
8576
  if transaction is None:
8566
8577
  matches = [
8567
8578
  receipt
@@ -14,6 +14,7 @@ from .cleanup_evidence import read_document
14
14
  from .disposable import _delete_fd_tree, _fd_inventory, _unlink_leaf
15
15
  from .git_backend import head_paths, path_is_ignored, tracked_paths
16
16
  from .models import ControllerError, MetadataRecord
17
+ from .store import MetadataStore
17
18
 
18
19
  CONTRACT = "legacy-preserved-state-cleanup/v1"
19
20
 
@@ -22,6 +23,35 @@ def _blocked(message: str) -> ControllerError:
22
23
  return ControllerError("PRESERVATION_COVERAGE_INVALID", message)
23
24
 
24
25
 
26
+ def _completion_for_allocation(
27
+ store: MetadataStore, path: Path, allocation: str,
28
+ ) -> tuple[dict[str, Any], str] | None:
29
+ """Reuse only unrelated scope, never a receipt or a validation verdict.
30
+
31
+ Cleanup rechecks its plan between actions. Large unrelated completions need
32
+ not be decoded on each check while the same repository flock is held. Pin
33
+ and recheck their complete inode identity even on a negative scope hit;
34
+ relevant bytes and every preservation generation still receive full checks.
35
+ """
36
+ with p._absolute_directory(path.parent) as chain:
37
+ directory = chain[-1]
38
+ identity = p._identity(os.stat(path.name, dir_fd=directory.fd, follow_symlinks=False))
39
+ scopes = store._completion_scopes
40
+ previous = None if scopes is None else scopes.get(path)
41
+ if previous is not None and previous[0] == tuple(identity) and previous[1] != allocation:
42
+ with p._regular_fd(directory.fd, path.name, identity):
43
+ return None
44
+ receipt, raw_sha = read_document(directory, path.name)
45
+ if scopes is not None:
46
+ scope = receipt.get("plan", {}).get("allocation_id")
47
+ # Allocation IDs are canonical UUIDs. Unknown larger/nonstring values
48
+ # cannot match one; do not retain arbitrary payloads in this small map.
49
+ scopes[path] = (
50
+ tuple(identity), scope if isinstance(scope, str) and len(scope) == 36 else None
51
+ )
52
+ return receipt, raw_sha
53
+
54
+
25
55
  def coverage(
26
56
  receipt_path: Path,
27
57
  receipt_sha256: str,
@@ -615,8 +645,10 @@ def cleanup_receipts(
615
645
  if _preservation_source_relative(plan, item.path) in original_completed
616
646
  )
617
647
  for path in sorted(store.completion_receipts_dir.glob("*.json")):
618
- with p._absolute_directory(path.parent) as chain:
619
- receipt, raw_sha = read_document(chain[-1], path.name)
648
+ completion_entry = _completion_for_allocation(store, path, record.allocation_id)
649
+ if completion_entry is None:
650
+ continue
651
+ receipt, raw_sha = completion_entry
620
652
  plan = receipt.get("plan", {})
621
653
  if plan.get("allocation_id") != record.allocation_id:
622
654
  continue
@@ -9,6 +9,7 @@ import json
9
9
  import os
10
10
  import stat
11
11
  import tempfile
12
+ import threading
12
13
  import uuid
13
14
  from collections.abc import Callable, Iterator, Mapping
14
15
  from contextlib import contextmanager, suppress
@@ -118,6 +119,11 @@ _HISTORY_CACHE: dict[
118
119
  ] | None = None
119
120
  # CLI decoding retains its byte-reader error contract even without reuse.
120
121
  _BYTE_READS = False
122
+ # A nested read in the same thread is already admitted. Making it queue behind
123
+ # a writer that is waiting for its outer read would deadlock that writer.
124
+ _SHARED_LOCKS: dict[tuple[int, int, int, int], int] = {}
125
+ _CompletionScopes = dict[Path, tuple[tuple[int, ...], str | None]]
126
+ _LOCK_SCOPES: dict[tuple[int, int, int, int], tuple[int, _CompletionScopes]] = {}
121
127
 
122
128
 
123
129
  @contextmanager
@@ -246,11 +252,74 @@ class MetadataStore:
246
252
  self.lock_file = self.root / "repo.lock"
247
253
  self._flock_depth = 0
248
254
 
255
+ def _cleanup_active(self) -> bool:
256
+ """Only the active cleanup's directory flock admits bypassing the entry gate."""
257
+ try:
258
+ descriptor = os.open(
259
+ self.cleanup_actions_dir,
260
+ os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC,
261
+ )
262
+ except FileNotFoundError:
263
+ return False
264
+ try:
265
+ try:
266
+ fcntl.flock(descriptor, fcntl.LOCK_SH | fcntl.LOCK_NB)
267
+ except BlockingIOError:
268
+ return True
269
+ fcntl.flock(descriptor, fcntl.LOCK_UN)
270
+ return False
271
+ finally:
272
+ os.close(descriptor)
273
+
274
+ @contextmanager
275
+ def _entry_gate(self, key: tuple[int, int, int, int], *, exclusive: bool) -> Iterator[None]:
276
+ """Serialize entry, retaining repo.lock as the sole metadata mutation arbiter.
277
+
278
+ A writer keeps this gate while waiting for existing readers. Typed cleanup
279
+ has a distinct active marker: compatible history readers can still enter
280
+ during its long shared flock. Old runtimes keep their existing exclusion;
281
+ they do not participate in this new reader-admission ordering.
282
+ """
283
+ if not exclusive and _SHARED_LOCKS.get(key):
284
+ yield
285
+ return
286
+ descriptor = os.open(
287
+ self.root, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC
288
+ )
289
+ held = False
290
+ try:
291
+ try:
292
+ fcntl.flock(descriptor, fcntl.LOCK_EX | fcntl.LOCK_NB)
293
+ except BlockingIOError:
294
+ if not exclusive and self._cleanup_active():
295
+ yield
296
+ return
297
+ fcntl.flock(descriptor, fcntl.LOCK_EX)
298
+ held = True
299
+ yield
300
+ finally:
301
+ try:
302
+ if held:
303
+ fcntl.flock(descriptor, fcntl.LOCK_UN)
304
+ finally:
305
+ os.close(descriptor)
306
+
249
307
  @property
250
308
  def flock_held(self) -> bool:
251
309
  """True only while this process actually holds the repository flock."""
252
310
  return self._flock_depth > 0
253
311
 
312
+ @property
313
+ def _completion_scopes(self) -> _CompletionScopes | None:
314
+ """A fresh Store may share only this thread's actually held inode view."""
315
+ try:
316
+ opened = os.stat(self.lock_file, follow_symlinks=False)
317
+ except FileNotFoundError:
318
+ return None
319
+ key = (os.getpid(), threading.get_ident(), opened.st_dev, opened.st_ino)
320
+ view = _LOCK_SCOPES.get(key)
321
+ return None if view is None else view[1]
322
+
254
323
  @contextmanager
255
324
  def lock(self, *, exclusive: bool, create: bool = False) -> Iterator[None]:
256
325
  """Serialize repository access; writers fail closed on any lock anomaly.
@@ -327,18 +396,36 @@ class MetadataStore:
327
396
  if descriptor is None:
328
397
  yield
329
398
  return
399
+ opened = os.fstat(descriptor)
400
+ key = (os.getpid(), threading.get_ident(), opened.st_dev, opened.st_ino)
330
401
  held = False
331
402
  try:
332
403
  try:
333
- fcntl.flock(descriptor, fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
404
+ with self._entry_gate(key, exclusive=exclusive):
405
+ fcntl.flock(descriptor, fcntl.LOCK_EX if exclusive else fcntl.LOCK_SH)
334
406
  except OSError as exc:
335
407
  raise access_error(exc) from exc
336
408
  held = True
409
+ if not exclusive:
410
+ _SHARED_LOCKS[key] = _SHARED_LOCKS.get(key, 0) + 1
411
+ depth, scopes = _LOCK_SCOPES.get(key, (0, {}))
412
+ _LOCK_SCOPES[key] = (depth + 1, scopes)
337
413
  self._flock_depth += 1
338
414
  try:
339
415
  yield
340
416
  finally:
341
417
  self._flock_depth -= 1
418
+ depth, scopes = _LOCK_SCOPES[key]
419
+ if depth == 1:
420
+ scopes.clear()
421
+ del _LOCK_SCOPES[key]
422
+ else:
423
+ _LOCK_SCOPES[key] = (depth - 1, scopes)
424
+ if not exclusive:
425
+ if _SHARED_LOCKS[key] == 1:
426
+ del _SHARED_LOCKS[key]
427
+ else:
428
+ _SHARED_LOCKS[key] -= 1
342
429
  finally:
343
430
  try:
344
431
  if held:
@@ -406,16 +493,22 @@ class MetadataStore:
406
493
  no lock conversion or unlocked action boundary.
407
494
  """
408
495
  descriptor = None
496
+ active = None
409
497
  try:
410
498
  # Require the real mutation arbiter before initializing the existing
411
499
  # journal directory. Never bootstrap a missing repository lock here.
412
500
  try:
413
501
  with self.lock(exclusive=True):
414
502
  self.transactions_dir.mkdir(mode=0o700, exist_ok=True)
503
+ self.cleanup_actions_dir.mkdir(mode=0o700, exist_ok=True)
415
504
  descriptor = os.open(
416
505
  self.transactions_dir,
417
506
  os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC,
418
507
  )
508
+ active = os.open(
509
+ self.cleanup_actions_dir,
510
+ os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | os.O_CLOEXEC,
511
+ )
419
512
  fcntl.flock(descriptor, fcntl.LOCK_EX)
420
513
  except OSError as exc:
421
514
  raise ControllerError(
@@ -437,8 +530,16 @@ class MetadataStore:
437
530
  raise ControllerError(
438
531
  "RESOURCE_CLEANUP_LOCK_UNAVAILABLE", "cleanup journal directory changed"
439
532
  )
440
- yield
533
+ # Set the marker only after the cleanup actually holds its shared
534
+ # repo.lock; a cleanup waiting to enter grants no reader bypass.
535
+ fcntl.flock(active, fcntl.LOCK_EX)
536
+ try:
537
+ yield
538
+ finally:
539
+ fcntl.flock(active, fcntl.LOCK_UN)
441
540
  finally:
541
+ if active is not None:
542
+ os.close(active)
442
543
  if descriptor is not None:
443
544
  os.close(descriptor)
444
545
 
@@ -1071,7 +1071,7 @@
1071
1071
  "session_launcher_entrypoint": "worktree-session",
1072
1072
  "session_entrypoint": "worktree-session-end",
1073
1073
  "tool_name": "worktree-controller",
1074
- "tool_version": "1.32.10",
1074
+ "tool_version": "1.32.12",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,
@@ -1458,6 +1458,7 @@
1458
1458
  "storage_layout_version": 4
1459
1459
  },
1460
1460
  "source_release_summary_version": 1,
1461
+ "repository_lock_admission_version": 1,
1461
1462
  "source_release_summary_contract": {
1462
1463
  "version": 1,
1463
1464
  "field": "source_release_trigger.outcomes",
@@ -453,6 +453,64 @@ def _acquire_task_progress(store: MetadataStore, journal: dict, head: str) -> st
453
453
  return None
454
454
 
455
455
 
456
+ def acquire_precedes_removed_release(store: MetadataStore, transaction: str, release: dict) -> bool:
457
+ """Permit receipt recovery, never terminal classification, for this exact predecessor.
458
+
459
+ A retained acquire cannot become terminal until the release receipt exists. Only a
460
+ release already recorded at its exact +1 CAS may finish that receipt in its presence.
461
+ Both journals stay authoritative; ordinary mutations and rollout still see them pending.
462
+ """
463
+ _require_flock(store)
464
+ acquire = _journal_preconditions(
465
+ store, transaction, "acquire", frozenset({"METADATA_WRITTEN"})
466
+ )
467
+ if acquire is None or release.get("phase") != "RELEASED_RECORDED":
468
+ return False
469
+ identity = ("repository_id", "allocation_id", "target_path", "branch")
470
+ if any(acquire.get(key) != release.get(key) for key in identity):
471
+ return False
472
+ plan_id = release.get("release_plan_id")
473
+ if not isinstance(plan_id, str):
474
+ return False
475
+ snapshot = store._load_unlocked()
476
+ plan = snapshot.release_plans.get(plan_id)
477
+ record = snapshot.records.get(acquire["allocation_id"])
478
+ if plan is None or record is None or not record.history:
479
+ return False
480
+ if any(release.get(key) != getattr(plan, key) for key in (
481
+ *identity, "expected_head", "expected_record_version",
482
+ )):
483
+ return False
484
+ first, last = record.history[0], record.history[-1]
485
+ if (
486
+ record.role not in {"feature", "audit"}
487
+ or record.role != plan.role
488
+ or record.authority_key != plan.authority_key
489
+ or record.base_commit != acquire["expected_head"]
490
+ or record.task_commit != plan.expected_head
491
+ or record.lifecycle != "RELEASED"
492
+ or record.owner != "unassigned"
493
+ or record.record_version != plan.expected_record_version + 1
494
+ or first.get("event") != "ACQUIRED"
495
+ or first.get("from") is not None
496
+ or first.get("to") != "ACTIVE"
497
+ or first.get("at") != record.created_at
498
+ or last.get("event") not in {"RELEASED", "RELEASE_RECOVERED"}
499
+ or last.get("from") != plan.lifecycle
500
+ or last.get("to") != "RELEASED"
501
+ or _target_state(Path(plan.target_path)) != "absent"
502
+ or _worktree_registration(store.root.parents[1], Path(plan.target_path))[2] != "absent"
503
+ or _allocation_bound_anywhere(store, plan.allocation_id) != "unbound"
504
+ or (store.writer_leases_dir / f"{plan.allocation_id}.json").exists()
505
+ or _branch_ref_state(store.root.parents[1], f"refs/heads/{plan.branch}")
506
+ != (plan.expected_head, "resolved")
507
+ ):
508
+ return False
509
+ from .git_backend import is_ancestor
510
+
511
+ return is_ancestor(store.root.parents[1], acquire["expected_head"], plan.expected_head)
512
+
513
+
456
514
  def acquire_evidence_terminal(store: MetadataStore, transaction: str) -> str | None:
457
515
  """Close an interrupted acquire only on positive current-state proof.
458
516
 
@@ -1071,7 +1071,7 @@
1071
1071
  "session_launcher_entrypoint": "worktree-session",
1072
1072
  "session_entrypoint": "worktree-session-end",
1073
1073
  "tool_name": "worktree-controller",
1074
- "tool_version": "1.32.10",
1074
+ "tool_version": "1.32.12",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,
@@ -1458,6 +1458,7 @@
1458
1458
  "storage_layout_version": 4
1459
1459
  },
1460
1460
  "source_release_summary_version": 1,
1461
+ "repository_lock_admission_version": 1,
1461
1462
  "source_release_summary_contract": {
1462
1463
  "version": 1,
1463
1464
  "field": "source_release_trigger.outcomes",