worktree-controller 1.32.5__tar.gz → 1.32.7__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.5 → worktree_controller-1.32.7}/PKG-INFO +5 -5
  2. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/README.md +4 -4
  3. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/architecture.md +5 -0
  4. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/operations.md +28 -0
  5. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/roadmap.md +21 -10
  6. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/pyproject.toml +1 -1
  7. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/pyproject.toml.orig +1 -1
  8. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/__init__.py +1 -1
  9. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/controller.py +38 -21
  10. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/integration_conflict.py +3 -3
  11. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/lifecycle.py +1 -13
  12. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/publication_execution.py +3 -2
  13. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/semantics.py +13 -0
  14. {worktree_controller-1.32.5 → worktree_controller-1.32.7/src/worktree_controller}/tool_cli_contract.json +1 -1
  15. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/writer_lease.py +3 -1
  16. {worktree_controller-1.32.5/src/worktree_controller → worktree_controller-1.32.7}/tool_cli_contract.json +1 -1
  17. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/LICENSE +0 -0
  18. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/client-integration.md +0 -0
  19. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/daily-workflow.md +0 -0
  20. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/first-change.md +0 -0
  21. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/getting-started.md +0 -0
  22. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/integration-boundaries.md +0 -0
  23. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/publishing.md +0 -0
  24. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/reference.md +0 -0
  25. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/docs/scope.md +0 -0
  26. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/examples/change_task.py +0 -0
  27. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/examples/client_continuation.py +0 -0
  28. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/examples/quickstart.py +0 -0
  29. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/activation_layout.py +0 -0
  30. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/branch_retirement.py +0 -0
  31. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/canonical_refresh.py +0 -0
  32. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/canonical_transition.py +0 -0
  33. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/cleanup_attempts.py +0 -0
  34. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/cleanup_evidence.py +0 -0
  35. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/cleanup_recovery.py +0 -0
  36. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/cli.py +0 -0
  37. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/convergence.py +0 -0
  38. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/delivered_closeout.py +0 -0
  39. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/disposable.py +0 -0
  40. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/environment.py +0 -0
  41. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/frozen_recovery.py +0 -0
  42. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/git_backend.py +0 -0
  43. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/governance.py +0 -0
  44. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/hardlinks.py +0 -0
  45. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/integration_cleanup.py +0 -0
  46. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/integration_retry.py +0 -0
  47. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/keyed_document_scope.py +0 -0
  48. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/lifecycle_history.py +0 -0
  49. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/lifecycle_observation.py +0 -0
  50. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/metadata_codec.py +0 -0
  51. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/metadata_relocation.py +0 -0
  52. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/models.py +0 -0
  53. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/mount_diagnostics.py +0 -0
  54. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  55. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/namespace_migration.py +0 -0
  56. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/native_session_recovery.py +0 -0
  57. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/owner_actions.py +0 -0
  58. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/policy.py +0 -0
  59. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/preservation.py +0 -0
  60. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/preserved_cleanup.py +0 -0
  61. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/reconciler.py +0 -0
  62. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/record_updates.py +0 -0
  63. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/recovery_guidance.py +0 -0
  64. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/registration_backfill.py +0 -0
  65. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/registration_prune.py +0 -0
  66. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/release_intents.py +0 -0
  67. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/rendering.py +0 -0
  68. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/resource_admission.py +0 -0
  69. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/retirement_adapters.py +0 -0
  70. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/retirement_execution.py +0 -0
  71. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/session.py +0 -0
  72. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/session_admission.py +0 -0
  73. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/source_cleanup.py +0 -0
  74. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/source_preservation.py +0 -0
  75. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/source_recovery.py +0 -0
  76. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/store.py +0 -0
  77. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/task_workflow.py +0 -0
  78. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/src/worktree_controller/transaction_scope.py +0 -0
  79. {worktree_controller-1.32.5 → worktree_controller-1.32.7}/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.5
3
+ Version: 1.32.7
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.5 · Linux · Python 3.12 · Apache-2.0**
26
+ **Current release: 1.32.7 · 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.5
35
+ python -m pip install worktree-controller==1.32.7
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.5 uses CLI contract **61** and storage layout **5**.
44
+ Software version 1.32.7 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.5
53
+ git checkout v1.32.7
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.5 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.32.7 · 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.5
18
+ python -m pip install worktree-controller==1.32.7
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.5 uses CLI contract **61** and storage layout **5**.
27
+ Software version 1.32.7 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.5
36
+ git checkout v1.32.7
37
37
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
38
38
  ```
39
39
 
@@ -87,3 +87,8 @@ one-day backoff cap. This extraction changes no CLI, capability or storage contr
87
87
  Scope digest and overlap queries live in `semantics` alongside scope normalization. Integration
88
88
  retry calls these shared pure helpers directly; lifecycle retains compatibility aliases. Their
89
89
  serialization, empty-scope interpretation and parent/child path rules remain unchanged.
90
+
91
+ Allocation-to-intent lookup also lives in `semantics`. It reads only the caller's snapshot,
92
+ returns the original unique intent or no match, and refuses multiple intents bound to one
93
+ allocation as `INVALID_METADATA`. Publication execution and conflict resolution use this shared
94
+ query directly; lifecycle keeps its existing alias, lock scope and transition guards.
@@ -29,6 +29,19 @@ uses the public Snapshot Runner package. Context Loader and `tool-skill-sync` ar
29
29
  4. Register rebuildable environments while ACTIVE. Run focused tests, the required project gate,
30
30
  and Snapshot review before Git Finalizer commits or publishes the task branch.
31
31
 
32
+ ## Concurrent diagnostic reads
33
+
34
+ `doctor` refreshes Git inventory after acquiring the repository's shared lock and retains that
35
+ lock through metadata, semantic, transaction and retirement diagnostics. Normal Controller
36
+ mutations wait until those reads finish, so a guarded release cannot remove an inspected checkout
37
+ halfway through its scope or ancestry checks. This lock coordinates Controller operations; direct
38
+ Git changes and external processes still have their own observation boundaries.
39
+
40
+ A genuinely unavailable commit still refuses through the existing API/CLI contract. Keep the
41
+ original exit code and request, and compare the exact repository and checkout used by the failed
42
+ Git command before concluding that an object was lost. Repeating a diagnostic does not recover a
43
+ lifecycle, replace frozen source evidence or settle another owner's outstanding authorization.
44
+
32
45
  ## Handoff and integrate
33
46
 
34
47
  Publish the source branch, hand off its exact commit and scope, then enqueue one integration intent.
@@ -83,6 +96,21 @@ original invocation and current observations; do not automatically apply the mai
83
96
  to an unrelated identity change. An unchanged clean PREPARING candidate can be observed again with
84
97
  its exact original claim without allocating another checkout.
85
98
 
99
+ ## Finished commands and runtime reconciliation
100
+
101
+ A command exit releases its writer entitlement; runtime occupancy remains until ordinary
102
+ reconciliation proves it clear. `RUNTIME_OCCUPIED` means positive holder, group or path-use
103
+ evidence. `RUNTIME_SCAN_UNCERTAIN` means visibility or identity evidence is incomplete. Both
104
+ retain the binding and execution reservation; neither proves task completion or permits cleanup.
105
+
106
+ After resolving the reported uncertainty or waiting for the actual workload to finish, rerun
107
+ `admission-queue --repo <canonical-repo> --apply --json` with the original request intact.
108
+ Inspect its per-request outcomes: exit 0 reports a successful queue observation even when a row
109
+ still has a blocker. Direct `binding-remove` returns exit 2 on either refusal. Once clear,
110
+ ordinary reconciliation removes the binding and releases the execution budget; commits and local
111
+ files remain in their checkout. Do not remove bindings manually, loosen guards or treat a retry
112
+ count as proof that the runtime must already be clear.
113
+
86
114
  ## Recovery guidance and session closeout
87
115
 
88
116
  When `capabilities --json` advertises `recovery_guidance_version` 1, inspect one checkout:
@@ -1,14 +1,22 @@
1
1
  # Maintenance roadmap
2
2
 
3
- Execution baseline: 2026-10-23. This is the WC portion of the approved four-tool maintenance
3
+ Execution baseline: 2026-10-24. This is the WC portion of the approved four-tool maintenance
4
4
  direction. Each stage needs its own tested deliverable; later ideas are not current behavior.
5
5
 
6
6
  ## Current baseline
7
7
 
8
- WC 1.32.5 retains CLI contract 61 and storage layout 5. The scope and architecture documents
9
- are already on main. Previous extractions reduced private cross-module imports from 93 to
10
- 82 and then 80. This batch moves pure scope hashing/overlap queries into `semantics`, reducing
11
- the baseline to 78. It retains lifecycle mutation helpers, clocks and internal aliases.
8
+ WC 1.32.6 completed the runtime-visibility fix and the previously planned allocation-to-intent
9
+ query extraction. Private cross-module imports remain at 76. Software version 1.32.7 retains
10
+ CLI contract 61, the existing capability versions and storage layout 5, and serializes doctor
11
+ snapshot reads with normal Controller mutations. Diagnostics refresh Git inventory after taking
12
+ the shared repository lock, then retain it through semantic, transaction and retirement checks.
13
+ The regression uses a real guarded release and verifies the retained commit and branch; a truly
14
+ missing commit still refuses through both the API and CLI.
15
+
16
+ The original intermittent commit-resolution report did not retain enough per-command evidence
17
+ to establish its exact cause. The isolated concurrency defect is reproducible; that does not
18
+ prove the historical report had the same cause. Site-specific owner actions remain separate
19
+ from WC repairs and package deployment.
12
20
 
13
21
  GF 1.9.8 already consumes SR's public read API and WC's versioned publication/retirement
14
22
  protocols. CL 1.3.10 and SR 2.5.12 already use main on both hosting platforms. These completed
@@ -23,7 +31,8 @@ acceptance gates, and historical temporary-file impact. No historical evidence i
23
31
  | Stage | Deliverable | Exit evidence | Stop or rollback boundary |
24
32
  | --- | --- | --- | --- |
25
33
  | 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 |
26
- | 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 |
34
+ | WC structure: delivered | Pure release-intent, scope and allocation-to-intent queries | Existing behavior retained; private-import baseline 76; CLI 61/storage 5 unchanged | Preserve clocks, mutation and crash-hook ownership |
35
+ | Now: diagnostic stability | One coherent doctor snapshot across guarded lifecycle changes | Real concurrent release, fresh inventory and negative API/CLI controls; full integration gate | Retain missing-commit and ownership refusals; preserve original incident uncertainty |
27
36
  | Shared quality checks: delivered | CL/SR adopt release-tools with a reviewed full commit pin | Both hosted parallel pilots and final three-version checks passed; SR retains its package check | Restore the pinned original consumer workflow; PyPI/Gitea flows remain owned by consumers |
28
37
  | 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 |
29
38
  | 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 |
@@ -45,7 +54,9 @@ Python floor, move host-specific defaults without migration, or replace existing
45
54
  GitHub-first release consolidation and a future toolchain repository remain design decisions,
46
55
  not permission to disable existing Gitea delivery or platform controls.
47
56
 
48
- This maintenance batch moves pure scope hashing and overlap queries to `semantics`, lowering
49
- the private-import baseline from 80 to 78. Publication metadata readback now shares a bounded
50
- visibility window; exact bytes, identities, failed-command outcomes and same-bundle recovery stay
51
- mandatory. CL/SR shared quality checks have passed their hosted parallel and final matrices.
57
+ The allocation-to-intent maintenance task and the 1.32.6 delivery are complete. Use the real
58
+ diagnostic-stability maintenance task to observe checkpoint pause, fresh-executor resume,
59
+ Finalizer handoff, integration and release; preserve pending results instead of interpreting
60
+ an advisory success as completion. The released publication visibility window keeps exact bytes,
61
+ identities, failed-command outcomes and same-bundle recovery mandatory. CL/SR shared quality checks
62
+ have passed their hosted parallel and final matrices.
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.32.5"
7
+ version = "1.32.7"
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.5"
7
+ version = "1.32.7"
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.5"
3
+ __version__ = "1.32.7"
@@ -5,6 +5,7 @@ from __future__ import annotations
5
5
  import os
6
6
  import stat
7
7
  from collections import defaultdict
8
+ from contextlib import ExitStack
8
9
  from datetime import datetime
9
10
  from pathlib import Path
10
11
  from typing import Any
@@ -1603,27 +1604,43 @@ def doctor(repository_path: Path, *, namespace_pid: int | None = None) -> dict[s
1603
1604
 
1604
1605
  policy = default_policy(repository.canonical_path)
1605
1606
  store = MetadataStore(repository.common_dir)
1606
- try:
1607
- snapshot = store.load()
1608
- except ControllerError as exc:
1609
- error = _environment_first(exc, diagnosis)
1610
- result["repository"] = {
1611
- "canonical_path": str(repository.canonical_path),
1612
- "common_dir": str(repository.common_dir),
1613
- "worktree_count": len(repository.worktrees),
1614
- "normal_limit": policy.normal_limit,
1615
- "hard_limit": policy.hard_limit,
1616
- "metadata_path": str(store.root),
1617
- }
1618
- result["errors"].append({"code": error.code, "message": str(error)})
1619
- result["decision"] = {
1620
- "code": "FAIL",
1621
- "reason": "repository environment or controller metadata is unavailable",
1622
- "primary_diagnosis": _primary_diagnosis(
1623
- diagnosis, result["warnings"] + result["errors"], failed=True
1624
- ),
1625
- }
1626
- return result
1607
+ with ExitStack() as stack:
1608
+ try:
1609
+ # Release/refresh must not invalidate Git paths while the snapshot's
1610
+ # semantic and transaction evidence is still being read.
1611
+ stack.enter_context(store.lock(exclusive=False))
1612
+ repository = inventory(repository_path)
1613
+ snapshot = store.load()
1614
+ except ControllerError as exc:
1615
+ error = _environment_first(exc, diagnosis)
1616
+ result["repository"] = {
1617
+ "canonical_path": str(repository.canonical_path),
1618
+ "common_dir": str(repository.common_dir),
1619
+ "worktree_count": len(repository.worktrees),
1620
+ "normal_limit": policy.normal_limit,
1621
+ "hard_limit": policy.hard_limit,
1622
+ "metadata_path": str(store.root),
1623
+ }
1624
+ result["errors"].append({"code": error.code, "message": str(error)})
1625
+ result["decision"] = {
1626
+ "code": "FAIL",
1627
+ "reason": "repository environment or controller metadata is unavailable",
1628
+ "primary_diagnosis": _primary_diagnosis(
1629
+ diagnosis, result["warnings"] + result["errors"], failed=True
1630
+ ),
1631
+ }
1632
+ return result
1633
+ return _doctor_snapshot(result, repository, policy, store, snapshot)
1634
+
1635
+
1636
+ def _doctor_snapshot(
1637
+ result: dict[str, Any],
1638
+ repository: RepositoryInventory,
1639
+ policy: WorktreePolicy,
1640
+ store: MetadataStore,
1641
+ snapshot: MetadataSnapshot,
1642
+ ) -> dict[str, Any]:
1643
+ diagnosis = result["environment_diagnosis"]
1627
1644
  warnings = _metadata_warnings(repository, policy, snapshot)
1628
1645
  result["repository"] = _repository_payload(repository, policy, snapshot)
1629
1646
  result["worktrees"] = _observed_worktrees(
@@ -9,7 +9,7 @@ from typing import Any
9
9
  from .git_backend import commits_with_parents, inventory
10
10
  from .integration_retry import _sources
11
11
  from .models import ControllerError
12
- from .semantics import integration_candidate_issues
12
+ from .semantics import integration_candidate_issues, intent_for_allocation
13
13
  from .store import MetadataStore
14
14
 
15
15
 
@@ -23,7 +23,7 @@ def resolve_integration(
23
23
  finalizer_record_id: str,
24
24
  ) -> dict[str, Any]:
25
25
  from .controller import status
26
- from .lifecycle import _intent_for_allocation, _intent_payload
26
+ from .lifecycle import _intent_payload
27
27
  from .record_updates import updated_intent, updated_record
28
28
  from .semantics import assert_record_version as _cas
29
29
  from .semantics import managed_record as _managed_record
@@ -40,7 +40,7 @@ def resolve_integration(
40
40
  snapshot = store._load_unlocked()
41
41
  item, record = _managed_record(repository, snapshot, target)
42
42
  _cas(record, expected_record_version)
43
- intent = _intent_for_allocation(snapshot, record.allocation_id)
43
+ intent = intent_for_allocation(snapshot, record.allocation_id)
44
44
  if record.owner != owner:
45
45
  raise ControllerError("OWNER_MISMATCH", "resolution owner does not match")
46
46
  if (
@@ -97,6 +97,7 @@ from .semantics import (
97
97
  )
98
98
  from .semantics import effective_intent_state as _effective_intent_state
99
99
  from .semantics import integration_reconciliation as _integration_reconciliation
100
+ from .semantics import intent_for_allocation as _intent_for_allocation
100
101
  from .semantics import managed_record as _managed_record
101
102
  from .semantics import publication_receipt_lease_released as _publication_receipt_lease_released
102
103
  from .semantics import record_for as _record_for
@@ -355,19 +356,6 @@ def _cancel_release_intents(
355
356
  )
356
357
 
357
358
 
358
- def _intent_for_allocation(
359
- snapshot: MetadataSnapshot, allocation_id: str
360
- ) -> IntegrationIntent | None:
361
- matches = [
362
- intent
363
- for intent in snapshot.integration_intents.values()
364
- if intent.allocation_id == allocation_id
365
- ]
366
- if len(matches) > 1:
367
- raise ControllerError("INVALID_METADATA", "multiple intents bind one allocation")
368
- return matches[0] if matches else None
369
-
370
-
371
359
  def _duration_ms(start: str, end: str) -> int:
372
360
  return max(
373
361
  0,
@@ -21,9 +21,10 @@ from pathlib import Path
21
21
  from typing import Any, TextIO
22
22
 
23
23
  from .git_backend import _git, inventory, is_ancestor, validate_branch_name
24
- from .lifecycle import _intent_for_allocation, _validate_prepared_publication_receipt
24
+ from .lifecycle import _validate_prepared_publication_receipt
25
25
  from .models import ControllerError
26
26
  from .policy import load_policy
27
+ from .semantics import intent_for_allocation
27
28
  from .semantics import managed_record as _managed_record
28
29
  from .store import MetadataStore, now_iso
29
30
 
@@ -163,7 +164,7 @@ class PublicationSession:
163
164
  raise ControllerError(
164
165
  "PUBLICATION_EVIDENCE_MISMATCH", "leased candidate evidence differs"
165
166
  )
166
- intent = _intent_for_allocation(snapshot, record.allocation_id)
167
+ intent = intent_for_allocation(snapshot, record.allocation_id)
167
168
  if intent is None or (
168
169
  intent.state != "PUBLISHING"
169
170
  or intent.publication_identity != lease.lease_id
@@ -99,6 +99,19 @@ def assert_record_version(
99
99
  )
100
100
 
101
101
 
102
+ def intent_for_allocation(
103
+ snapshot: MetadataSnapshot, allocation_id: str
104
+ ) -> IntegrationIntent | None:
105
+ matches = [
106
+ intent
107
+ for intent in snapshot.integration_intents.values()
108
+ if intent.allocation_id == allocation_id
109
+ ]
110
+ if len(matches) > 1:
111
+ raise ControllerError("INVALID_METADATA", "multiple intents bind one allocation")
112
+ return matches[0] if matches else None
113
+
114
+
102
115
  def integration_intent_abandoned(intent: IntegrationIntent) -> bool:
103
116
  """Recognize the explicit terminal event without forgiving unexplained drift."""
104
117
  return (
@@ -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.5",
1074
+ "tool_version": "1.32.7",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,
@@ -92,8 +92,10 @@ def assert_runtime_clear(target: Path, holders: tuple[WriterHolder, ...]) -> Non
92
92
  if (not holders or process is None or any(holder.boot_id != boot_id()
93
93
  or process.start_ticks >= holder.start_ticks for holder in holders)):
94
94
  observed.append(reference)
95
- if observed or any(evidence[key] for key in ("managed_references", "managed_visibility_uncertainties", "scan_uncertainties")):
95
+ if observed or evidence["managed_references"]:
96
96
  raise ControllerError("RUNTIME_OCCUPIED", "runtime remains until managed and observed use is clear")
97
+ if evidence["managed_visibility_uncertainties"] or evidence["scan_uncertainties"]:
98
+ raise ControllerError("RUNTIME_SCAN_UNCERTAIN", "runtime visibility remains uncertain")
97
99
 
98
100
 
99
101
  def foreign_runtime_bindings(record: MetadataRecord, holder: WriterHolder, lease_id: str | None) -> tuple[str, ...]:
@@ -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.5",
1074
+ "tool_version": "1.32.7",
1075
1075
  "delivered_closeout_version": 1,
1076
1076
  "retained_archive_version": 1,
1077
1077
  "retention_convergence_version": 2,