worktree-controller 1.32.11__tar.gz → 1.32.13__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.11 → worktree_controller-1.32.13}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/README.md +4 -4
  3. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/operations.md +21 -0
  4. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/reference.md +52 -0
  5. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/roadmap.md +6 -0
  6. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/pyproject.toml +1 -1
  7. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/pyproject.toml.orig +1 -1
  8. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/__init__.py +1 -1
  9. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_evidence.py +30 -1
  10. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/cli.py +1 -0
  11. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/delivered_closeout.py +5 -2
  12. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/preserved_cleanup.py +5 -3
  13. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/store.py +103 -2
  14. {worktree_controller-1.32.11 → worktree_controller-1.32.13/src/worktree_controller}/tool_cli_contract.json +2 -1
  15. {worktree_controller-1.32.11/src/worktree_controller → worktree_controller-1.32.13}/tool_cli_contract.json +2 -1
  16. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/LICENSE +0 -0
  17. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/architecture.md +0 -0
  18. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/client-integration.md +0 -0
  19. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/daily-workflow.md +0 -0
  20. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/first-change.md +0 -0
  21. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/getting-started.md +0 -0
  22. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/integration-boundaries.md +0 -0
  23. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/publishing.md +0 -0
  24. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/docs/scope.md +0 -0
  25. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/examples/change_task.py +0 -0
  26. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/examples/client_continuation.py +0 -0
  27. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/examples/quickstart.py +0 -0
  28. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/activation_layout.py +0 -0
  29. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/branch_retirement.py +0 -0
  30. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/canonical_refresh.py +0 -0
  31. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/canonical_transition.py +0 -0
  32. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_attempts.py +0 -0
  33. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/cleanup_recovery.py +0 -0
  34. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/controller.py +0 -0
  35. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/convergence.py +0 -0
  36. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/disposable.py +0 -0
  37. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/environment.py +0 -0
  38. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/frozen_recovery.py +0 -0
  39. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/git_backend.py +0 -0
  40. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/governance.py +0 -0
  41. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/hardlinks.py +0 -0
  42. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/integration_cleanup.py +0 -0
  43. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/integration_conflict.py +0 -0
  44. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/integration_retry.py +0 -0
  45. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/keyed_document_scope.py +0 -0
  46. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle.py +0 -0
  47. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle_history.py +0 -0
  48. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/lifecycle_observation.py +0 -0
  49. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/metadata_codec.py +0 -0
  50. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/metadata_relocation.py +0 -0
  51. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/models.py +0 -0
  52. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/mount_diagnostics.py +0 -0
  53. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  54. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/namespace_migration.py +0 -0
  55. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/native_session_recovery.py +0 -0
  56. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/owner_actions.py +0 -0
  57. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/policy.py +0 -0
  58. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/preservation.py +0 -0
  59. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/publication_execution.py +0 -0
  60. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/reconciler.py +0 -0
  61. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/record_updates.py +0 -0
  62. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/recovery_guidance.py +0 -0
  63. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/registration_backfill.py +0 -0
  64. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/registration_prune.py +0 -0
  65. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/release_intents.py +0 -0
  66. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/rendering.py +0 -0
  67. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/resource_admission.py +0 -0
  68. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/retirement_adapters.py +0 -0
  69. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/retirement_execution.py +0 -0
  70. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/semantics.py +0 -0
  71. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/session.py +0 -0
  72. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/session_admission.py +0 -0
  73. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/source_cleanup.py +0 -0
  74. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/source_preservation.py +0 -0
  75. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/source_recovery.py +0 -0
  76. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/task_workflow.py +0 -0
  77. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/transaction_scope.py +0 -0
  78. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/src/worktree_controller/writer_lease.py +0 -0
  79. {worktree_controller-1.32.11 → worktree_controller-1.32.13}/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.11
3
+ Version: 1.32.13
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.11 · Linux · Python 3.12 · Apache-2.0**
26
+ **Current release: 1.32.13 · 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.11
35
+ python -m pip install worktree-controller==1.32.13
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.11 uses CLI contract **61** and storage layout **5**.
44
+ Software version 1.32.13 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.11
53
+ git checkout v1.32.13
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.11 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.32.13 · 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.11
18
+ python -m pip install worktree-controller==1.32.13
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.11 uses CLI contract **61** and storage layout **5**.
27
+ Software version 1.32.13 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.11
36
+ git checkout v1.32.13
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
@@ -7,6 +7,58 @@ 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
+
44
+ ## No-change preservation history reads (1.32.13)
45
+
46
+ Terminal no-change checks now use the same lock-scoped allocation filter as preserved
47
+ cleanup. This includes the check for cleanup completed before the original no-change
48
+ transition: it previously decoded unrelated completion documents again in each nested
49
+ verification. Relevant documents are still read and checked on every lookup. Only unrelated
50
+ allocation scopes with unchanged file identities may be reused, never a receipt verdict;
51
+ the map expires at the end of the outermost flock. A new authority lock reads those bytes again.
52
+
53
+ An isolated preservation plan for five files totaling 27,479 bytes, with eight unrelated
54
+ 2 MiB completion documents, reduced unrelated full-document reads from 64 to 16
55
+ (approximately 128 MiB to 32 MiB decoded). Both authority observations, the source scan,
56
+ original completion proof and existing refusal conditions remain mandatory. The fixture
57
+ also included 16 MiB of ignored files outside the selected source. This addresses repeated
58
+ history decoding; the first scan, preservation-tree verification, Git observation and
59
+ retirement authority scans retain their existing costs. It establishes no site latency
60
+ bound and does not identify the cause of a historical timeout.
61
+
10
62
  ## Optional integrations and dependencies
11
63
 
12
64
  The core control plane has a single runtime dependency (`websockets>=15,<16`) and works standalone
@@ -20,6 +20,12 @@ the shared repository lock, then retain it through semantic, transaction and ret
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.11"
7
+ version = "1.32.13"
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.11"
7
+ version = "1.32.13"
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.11"
3
+ __version__ = "1.32.13"
@@ -9,7 +9,7 @@ from typing import Any
9
9
  from . import hardlinks
10
10
  from . import preservation as p
11
11
  from .models import ControllerError
12
- from .store import now_iso
12
+ from .store import MetadataStore, now_iso
13
13
 
14
14
  MAX_EVIDENCE_BYTES = 64 * 1024 * 1024
15
15
 
@@ -33,6 +33,35 @@ def read_document(directory: p._Directory, name: str) -> tuple[dict[str, Any], s
33
33
  return value, hashlib.sha256(raw).hexdigest()
34
34
 
35
35
 
36
+ def completion_for_allocation(
37
+ store: MetadataStore, path: Path, allocation: str,
38
+ ) -> tuple[dict[str, Any], str] | None:
39
+ """Reuse only unrelated scope, never a receipt or a validation verdict.
40
+
41
+ Cleanup rechecks its plan between actions. Large unrelated completions need
42
+ not be decoded on each check while the same repository flock is held. Pin
43
+ and recheck their complete inode identity even on a negative scope hit;
44
+ relevant bytes and every preservation generation still receive full checks.
45
+ """
46
+ with p._absolute_directory(path.parent) as chain:
47
+ directory = chain[-1]
48
+ identity = p._identity(os.stat(path.name, dir_fd=directory.fd, follow_symlinks=False))
49
+ scopes = store._completion_scopes
50
+ previous = None if scopes is None else scopes.get(path)
51
+ if previous is not None and previous[0] == tuple(identity) and previous[1] != allocation:
52
+ with p._regular_fd(directory.fd, path.name, identity):
53
+ return None
54
+ receipt, raw_sha = read_document(directory, path.name)
55
+ if scopes is not None:
56
+ scope = receipt.get("plan", {}).get("allocation_id")
57
+ # Allocation IDs are canonical UUIDs. Unknown larger/nonstring values
58
+ # cannot match one; do not retain arbitrary payloads in this small map.
59
+ scopes[path] = (
60
+ tuple(identity), scope if isinstance(scope, str) and len(scope) == 36 else None
61
+ )
62
+ return receipt, raw_sha
63
+
64
+
36
65
  def write(directory: Path, name: str, value: dict[str, Any]) -> dict[str, str]:
37
66
  with p._absolute_directory(directory, create=True) as chain:
38
67
  digest = p._write_once(chain[-1], name, value)
@@ -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,
@@ -137,10 +137,13 @@ def _legacy_no_change(store: MetadataStore, item: WorktreeGitState, record: Meta
137
137
 
138
138
 
139
139
  def _has_pre_completion_cleanup(store: MetadataStore, record: MetadataRecord) -> bool:
140
- from .cleanup_evidence import read
140
+ from .cleanup_evidence import completion_for_allocation
141
141
 
142
142
  for path in sorted(store.completion_receipts_dir.glob("*.json")):
143
- value, _ = read(path)
143
+ entry = completion_for_allocation(store, path, record.allocation_id)
144
+ if entry is None:
145
+ continue
146
+ value, _ = entry
144
147
  plan = value.get("plan", {})
145
148
  if plan.get("allocation_id") == record.allocation_id and plan.get("terminal_evidence") is None:
146
149
  return True
@@ -10,7 +10,7 @@ from pathlib import Path
10
10
  from typing import Any
11
11
 
12
12
  from . import preservation as p
13
- from .cleanup_evidence import read_document
13
+ from .cleanup_evidence import completion_for_allocation, 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
@@ -615,8 +615,10 @@ def cleanup_receipts(
615
615
  if _preservation_source_relative(plan, item.path) in original_completed
616
616
  )
617
617
  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)
618
+ completion_entry = completion_for_allocation(store, path, record.allocation_id)
619
+ if completion_entry is None:
620
+ continue
621
+ receipt, raw_sha = completion_entry
620
622
  plan = receipt.get("plan", {})
621
623
  if plan.get("allocation_id") != record.allocation_id:
622
624
  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.11",
1074
+ "tool_version": "1.32.13",
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",
@@ -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.11",
1074
+ "tool_version": "1.32.13",
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",