worktree-controller 1.34.2__tar.gz → 1.36.0__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 (85) hide show
  1. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/PKG-INFO +16 -10
  2. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/README.md +10 -7
  3. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/build-resources.md +29 -0
  4. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/operations.md +40 -2
  5. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/reference.md +8 -0
  6. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/examples/change_task.py +2 -2
  7. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/examples/client_continuation.py +3 -3
  8. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/examples/quickstart.py +2 -2
  9. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/pyproject.toml +8 -3
  10. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/pyproject.toml.orig +8 -3
  11. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/__init__.py +1 -1
  12. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/activation_layout.py +2 -0
  13. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/branch_retirement.py +96 -42
  14. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/build_preservation.py +39 -4
  15. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/build_resources.py +21 -0
  16. worktree_controller-1.36.0/src/worktree_controller/canonical_refresh.py +281 -0
  17. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/canonical_transition.py +60 -12
  18. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/cli.py +74 -11
  19. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/controller.py +32 -8
  20. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/convergence.py +101 -28
  21. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/delivered_closeout.py +18 -2
  22. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/disposable.py +254 -98
  23. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/environment.py +66 -3
  24. worktree_controller-1.36.0/src/worktree_controller/frontier.py +344 -0
  25. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/git_backend.py +149 -20
  26. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/governance.py +10 -5
  27. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/hardlinks.py +25 -4
  28. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/keyed_document_scope.py +44 -39
  29. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/lifecycle.py +811 -370
  30. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/metadata_codec.py +24 -19
  31. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/models.py +15 -1
  32. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/multiple_cleanup_recovery.py +7 -2
  33. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/namespace_migration.py +21 -10
  34. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/native_session_recovery.py +7 -1
  35. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/policy.py +114 -27
  36. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/preservation.py +246 -151
  37. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/preserved_cleanup.py +42 -7
  38. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/publication_execution.py +84 -40
  39. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/reconciler.py +9 -5
  40. worktree_controller-1.36.0/src/worktree_controller/recovery_guidance.py +244 -0
  41. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/registration_backfill.py +6 -3
  42. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/registration_prune.py +3 -11
  43. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/rendering.py +12 -0
  44. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/resource_admission.py +133 -21
  45. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/semantics.py +2 -1
  46. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/session.py +12 -4
  47. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/session_admission.py +2 -0
  48. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/source_cleanup.py +26 -23
  49. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/source_preservation.py +34 -10
  50. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/source_recovery.py +24 -2
  51. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/store.py +212 -129
  52. {worktree_controller-1.34.2 → worktree_controller-1.36.0/src/worktree_controller}/tool_cli_contract.json +49 -10
  53. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/transaction_scope.py +73 -24
  54. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/writer_lease.py +124 -32
  55. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/writer_session.py +133 -11
  56. {worktree_controller-1.34.2/src/worktree_controller → worktree_controller-1.36.0}/tool_cli_contract.json +49 -10
  57. worktree_controller-1.34.2/src/worktree_controller/canonical_refresh.py +0 -150
  58. worktree_controller-1.34.2/src/worktree_controller/recovery_guidance.py +0 -212
  59. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/LICENSE +0 -0
  60. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/architecture.md +0 -0
  61. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/client-integration.md +0 -0
  62. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/daily-workflow.md +0 -0
  63. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/first-change.md +0 -0
  64. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/getting-started.md +0 -0
  65. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/integration-boundaries.md +0 -0
  66. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/publishing.md +0 -0
  67. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/roadmap.md +0 -0
  68. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/docs/scope.md +0 -0
  69. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/cleanup_attempts.py +0 -0
  70. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/cleanup_evidence.py +0 -0
  71. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/cleanup_recovery.py +0 -0
  72. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/frozen_recovery.py +0 -0
  73. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/integration_cleanup.py +0 -0
  74. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/integration_conflict.py +0 -0
  75. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/integration_retry.py +0 -0
  76. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/lifecycle_history.py +0 -0
  77. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/lifecycle_observation.py +0 -0
  78. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/metadata_relocation.py +0 -0
  79. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/mount_diagnostics.py +0 -0
  80. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/owner_actions.py +0 -0
  81. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/record_updates.py +0 -0
  82. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/release_intents.py +0 -0
  83. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/retirement_adapters.py +0 -0
  84. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/retirement_execution.py +0 -0
  85. {worktree_controller-1.34.2 → worktree_controller-1.36.0}/src/worktree_controller/task_workflow.py +0 -0
@@ -1,18 +1,21 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: worktree-controller
3
- Version: 1.34.2
3
+ Version: 1.36.0
4
4
  Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
7
7
  Classifier: Operating System :: POSIX :: Linux
8
8
  Classifier: Programming Language :: Python :: 3.12
9
- Requires-Dist: websockets>=15,<16
10
- Requires-Python: >=3.12, <3.13
9
+ Classifier: Programming Language :: Python :: 3.13
10
+ Classifier: Programming Language :: Python :: 3.14
11
+ Requires-Dist: websockets>=15,<16 ; extra == 'native-session'
12
+ Requires-Python: >=3.12, <3.15
11
13
  Project-URL: Homepage, https://github.com/xuanheng-tech/worktree-controller
12
14
  Project-URL: Documentation, https://github.com/xuanheng-tech/worktree-controller/blob/main/README.md
13
15
  Project-URL: Repository, https://github.com/xuanheng-tech/worktree-controller
14
16
  Project-URL: Issues, https://github.com/xuanheng-tech/worktree-controller/issues
15
17
  Project-URL: Changelog, https://github.com/xuanheng-tech/worktree-controller/blob/main/CHANGELOG.md
18
+ Provides-Extra: native-session
16
19
  Description-Content-Type: text/markdown
17
20
 
18
21
  # Worktree Controller
@@ -23,25 +26,26 @@ It checks repository policy before allocating a worktree, grants writing authori
23
26
  process, and records handoff, integration, recovery and release evidence. Git remains the source
24
27
  of truth for files, branches, commits and registered worktrees.
25
28
 
26
- **Current release: 1.32.18 · Linux · Python 3.12 · Apache-2.0**
29
+ **Current release: 1.36.0 · Linux · Python 3.12–3.14 · Apache-2.0**
27
30
 
28
31
  ## Install
29
32
 
30
33
  Use a virtual environment in a new directory:
31
34
 
32
35
  ```bash
33
- python3.12 -m venv .venv
36
+ python3 -m venv .venv
34
37
  . .venv/bin/activate
35
- python -m pip install worktree-controller==1.32.18
38
+ python -m pip install worktree-controller==1.36.0
36
39
  worktree-controller --version
37
40
  worktree-controller capabilities --json
38
41
  ```
39
42
 
40
- WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
41
- supported by this release. Its one runtime dependency is `websockets>=15,<16`.
43
+ WC requires Git and readable Linux `/proc` on Python 3.12–3.14. Core commands have zero required
44
+ third-party runtime dependencies; install `worktree-controller[native-session]==1.36.0` only when
45
+ using optional WebSocket-backed native session recovery (`websockets>=15,<16`).
42
46
  On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
43
47
  distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
44
- Software version 1.32.18 uses CLI contract **61** and storage layout **5**.
48
+ Software version 1.36.0 uses CLI contract **62** and storage layout **5**.
45
49
 
46
50
  ## Try it in a disposable repository
47
51
 
@@ -50,7 +54,7 @@ With the environment above active:
50
54
  ```bash
51
55
  git clone https://github.com/xuanheng-tech/worktree-controller.git wc
52
56
  cd wc
53
- git checkout v1.32.18
57
+ git checkout v1.36.0
54
58
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
55
59
  ```
56
60
 
@@ -79,6 +83,8 @@ Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease
79
83
  For client developers, the [AI client integration guide](docs/client-integration.md) describes the
80
84
  public identity and closeout contract, with an offline example that continues the same unfinished
81
85
  task from two independent client processes while preserving its files and checkpoint.
86
+ Thin CLI and Claude Code hook shims are bundled in `scripts/controller-consumer` and installed or
87
+ verified via `scripts/install-controller-consumers` (`--dry-run` / `--check`).
82
88
 
83
89
  ## Use WC in a real project
84
90
 
@@ -6,25 +6,26 @@ 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.18 · Linux · Python 3.12 · Apache-2.0**
9
+ **Current release: 1.36.0 · Linux · Python 3.12–3.14 · Apache-2.0**
10
10
 
11
11
  ## Install
12
12
 
13
13
  Use a virtual environment in a new directory:
14
14
 
15
15
  ```bash
16
- python3.12 -m venv .venv
16
+ python3 -m venv .venv
17
17
  . .venv/bin/activate
18
- python -m pip install worktree-controller==1.32.18
18
+ python -m pip install worktree-controller==1.36.0
19
19
  worktree-controller --version
20
20
  worktree-controller capabilities --json
21
21
  ```
22
22
 
23
- WC requires Git and readable Linux `/proc`. Other operating systems and Python versions are not
24
- supported by this release. Its one runtime dependency is `websockets>=15,<16`.
23
+ WC requires Git and readable Linux `/proc` on Python 3.12–3.14. Core commands have zero required
24
+ third-party runtime dependencies; install `worktree-controller[native-session]==1.36.0` only when
25
+ using optional WebSocket-backed native session recovery (`websockets>=15,<16`).
25
26
  On Ubuntu, if creating the environment reports that `ensurepip` is unavailable, install the
26
27
  distribution's `python3.12-venv` package first (for example, `sudo apt install python3.12-venv`).
27
- Software version 1.32.18 uses CLI contract **61** and storage layout **5**.
28
+ Software version 1.36.0 uses CLI contract **62** and storage layout **5**.
28
29
 
29
30
  ## Try it in a disposable repository
30
31
 
@@ -33,7 +34,7 @@ With the environment above active:
33
34
  ```bash
34
35
  git clone https://github.com/xuanheng-tech/worktree-controller.git wc
35
36
  cd wc
36
- git checkout v1.32.18
37
+ git checkout v1.36.0
37
38
  python examples/quickstart.py --workspace "$HOME/wc-first-run"
38
39
  ```
39
40
 
@@ -62,6 +63,8 @@ Finalizer handoff. These CLI 61 entrypoints retain the existing ownership, lease
62
63
  For client developers, the [AI client integration guide](docs/client-integration.md) describes the
63
64
  public identity and closeout contract, with an offline example that continues the same unfinished
64
65
  task from two independent client processes while preserving its files and checkpoint.
66
+ Thin CLI and Claude Code hook shims are bundled in `scripts/controller-consumer` and installed or
67
+ verified via `scripts/install-controller-consumers` (`--dry-run` / `--check`).
65
68
 
66
69
  ## Use WC in a real project
67
70
 
@@ -123,8 +123,37 @@ cross-call verdict cache or validation exemption is introduced. Older runtimes
123
123
  can read the history event but cannot classify these outputs; they continue to
124
124
  refuse unknown ignored content. Do not alternate runtimes during cleanup.
125
125
 
126
+ With `rebuilt_preservation_lineage_version=1`, an older generation may belong to a
127
+ source rebuilt during a formally reopened development cycle, including explicit
128
+ park/resume transitions before the next handoff. The original owner, allocation,
129
+ ancestor commits and every source ancestor must match; the rebuilt directory must
130
+ be a distinct node. Both the old immutable copy and a fresh preservation at the
131
+ current registration CAS are required. `BUILD_PRESERVATION_BASELINE_REQUIRED`
132
+ blocks cleanup while allowing the existing preservation plan/copy flow to save the
133
+ selected registered output. It grants copy authority only, never deletion authority.
134
+ After every affected output has its fresh copy, use normal typed cleanup and its
135
+ exact plan ID. Only that cleanup's real completed action proofs cover the absent
136
+ new sources. Old generations remain unchanged; no historical deletion is inferred.
137
+
126
138
  ## Retention preview
127
139
 
140
+ With `registered_build_absence_version=1`, an output already registered as
141
+ `owner-rebuildable-no-evidence` may be absent before cleanup starts. Its absence
142
+ does not need a fabricated cleanup receipt or a copy of a directory that no longer
143
+ exists. The original registration must still match owner, HEAD, CAS, committed
144
+ build inputs and every surviving ancestor. Historical preservation copies and
145
+ their lineage are verified and retained unchanged. Unregistered missing sources
146
+ keep the existing completion-evidence requirement.
147
+
148
+ The ordinary release dry-run reports `registered_build_absences` with state
149
+ `ABSENT_AT_OBSERVATION` and attribution `NOT_ESTABLISHED_BY_OBSERVATION`. Successful
150
+ release retains those observations in the allocation history, including after
151
+ interrupted-release recovery. This records present state, not who removed the
152
+ output. Typed cleanup pins any initial absence separately from its action list;
153
+ absence arising during an action cannot replace real action/recovery evidence.
154
+ No unknown file, failed transaction, writer, runtime, ref or publication check is
155
+ relaxed. Existing outputs retain their normal cleanup and preservation requirements.
156
+
128
157
  `retention_release_preflight_version=1` changes the preview meaning:
129
158
  `WOULD_RELEASE` requires the exact release dry-run to succeed at observation time.
130
159
  Its decision is attached as `release_preflight`. `CLOSEOUT_REQUIRED` means a park,
@@ -94,6 +94,42 @@ Advance an idle ACTIVE canonical with `canonical-refresh`. A canonical frozen in
94
94
  including one already on main/master, uses `canonical-transition` with exact owner, record CAS,
95
95
  frozen HEAD, observed local main and published remote main identities.
96
96
 
97
+ If a tracked local edit has already reached published main byte for byte, capability
98
+ `canonical_published_reconciliation_version=1` supports an explicit safe reconciliation:
99
+
100
+ ```text
101
+ worktree-controller canonical-refresh --repo <canonical-repo> --dry-run --json \
102
+ --reconcile-published-path AGENTS.md --expected-target <full-published-main-oid>
103
+ ```
104
+
105
+ Review the returned blob/mode identities, then repeat without `--dry-run`. Repeat
106
+ the path option for every selected file. This stages only exact published content
107
+ before the guarded fast-forward; it never resets, stashes or overwrites local edits.
108
+ Unselected changes, untracked files, symlinks, content filters, independent index
109
+ content and a changed remote target remain blocked. If interrupted after staging,
110
+ the identical request accepts those exact target blobs and can resume. Ordinary
111
+ canonical refresh still requires cleanliness and its authority and content-use guards.
112
+
113
+ Version 2 also accepts selected bytes that match one common baseline on the
114
+ fetched main's first-parent history between canonical HEAD and the target.
115
+ The preview names `reconciliation_baseline`. Controller stages those exact bytes,
116
+ fast-forwards through that published baseline, then fast-forwards to the expected
117
+ latest target. The original content remains in published Git history. A later
118
+ published edit is therefore applied by ordinary Git fast-forward, not discarded
119
+ or reverted to make local bytes match. An interruption after the intermediate
120
+ fast-forward resumes from that clean baseline. Independent edits, mixed snapshots
121
+ without a common matching baseline and changed expected targets remain refused.
122
+
123
+ With `canonical_refresh_scope_version=1`, a process whose references are only the
124
+ canonical root directory or shared Git metadata is an observer, not a content
125
+ occupant. Fast-forward preserves those nodes; there is no reason to stop a shared
126
+ service or shell just to clear its cwd. References inside checkout content, writer
127
+ leases, external runtime bindings and conflicting transactions still block. Git
128
+ continues to enforce its index/ref locks. The decision reports
129
+ `non_content_process_count`; it does not attest production activation. A runtime
130
+ that consumes mutable canonical source must register that runtime binding rather
131
+ than relying on cwd as a substitute. Worktree removal keeps its stricter guards.
132
+
97
133
  A frozen source cannot accept feature writes. Same-session continuation requires a compatible
98
134
  consumer to send `--access read|exec|write` and the actual write target. Continuing feature work on
99
135
  the source uses the supported reopen flow; handing off does not end the whole business task.
@@ -399,8 +435,10 @@ installed runtimes available for verification and rollback.
399
435
  The gate requires a root release whose runtime, packaging, maintenance scripts and complete Skill
400
436
  payload exactly equal the original frozen predecessor. Both public baseline and target must have
401
437
  live matching stable release tags. The target must descend from that baseline and preserve storage,
402
- metadata and writer-lease formats and installed Skill bytes. This entry cannot combine namespace,
403
- policy, Skill or cleanup migrations. Existing resource, metadata and consumer gates still run.
438
+ metadata and installed Skill bytes. Writer-lease format must also remain unchanged, except for the
439
+ backward-readable schema 2 to 3 upgrade; every other lease-format migration remains refused. This
440
+ entry cannot combine namespace, policy, Skill or cleanup migrations. Existing resource, metadata and
441
+ consumer gates still run.
404
442
  Live compatible writer sessions may continue; incompatible, stale or incomplete evidence is not
405
443
  made eligible by this procedure.
406
444
 
@@ -1707,6 +1707,14 @@ replace the former executable contracts; branch retirement publishes contract
1707
1707
  `branch-retirement/v5` with execution authorization `branch-retirement-execution/v1` on plan schema 1. The package exposes `worktree-controller`,
1708
1708
  `worktree-session`, and `worktree-session-end` only. Historical releases remain unchanged.
1709
1709
 
1710
+ From 1.34.4, writer lease schema 3 records the holder's original process group ID.
1711
+ This preserves liveness evidence when a non-leader holder exits and is reaped while
1712
+ another group member survives. Schema 2 leases remain readable and upgrade through
1713
+ same-holder renewal; if such a holder has exited, its unknown original group fails
1714
+ closed with `HOLDER_PROCESS_GROUP_UNKNOWN` rather than assuming PGID equals PID.
1715
+ The process group is occupancy evidence, not part of holder equality or the
1716
+ session-closeout identity digest. CLI 61 and storage layout 5 remain unchanged.
1717
+
1710
1718
  ### Governed deployment and rollback
1711
1719
 
1712
1720
  An archived Codex thread can leave a stale agent binding on a shared, still-live
@@ -42,8 +42,8 @@ def main():
42
42
  parser.error("--resume needs this demo's existing workspace and handoff.json")
43
43
  elif workspace.exists() or workspace.is_symlink() or not workspace.parent.is_dir():
44
44
  parser.error("--workspace must be a new path under an existing directory")
45
- if sys.platform != "linux" or sys.version_info[:2] != (3, 12):
46
- parser.error("the demo requires Linux and Python 3.12")
45
+ if sys.platform != "linux" or not ((3, 12) <= sys.version_info[:2] < (3, 15)):
46
+ parser.error("the demo requires Linux and Python 3.12-3.14")
47
47
  controller = Path(sys.executable).with_name("worktree-controller")
48
48
  if not controller.is_file():
49
49
  found = shutil.which("worktree-controller")
@@ -32,8 +32,8 @@ def main():
32
32
  parser.error("workspace must not be a symlink")
33
33
  if not args.resume and (workspace.exists() or not workspace.parent.is_dir()):
34
34
  parser.error("workspace must be a new path under an existing directory")
35
- if sys.platform != "linux" or sys.version_info[:2] != (3, 12):
36
- parser.error("the example requires Linux and Python 3.12")
35
+ if sys.platform != "linux" or not ((3, 12) <= sys.version_info[:2] < (3, 15)):
36
+ parser.error("the example requires Linux and Python 3.12-3.14")
37
37
  controller = Path(sys.executable).with_name("worktree-controller")
38
38
  if not controller.is_file():
39
39
  found = shutil.which("worktree-controller")
@@ -114,7 +114,7 @@ def main():
114
114
  return result
115
115
 
116
116
  capabilities = wc("capabilities")["decision"]
117
- require(capabilities.get("contract_version") == 61
117
+ require(capabilities.get("contract_version") == 62
118
118
  and capabilities.get("storage_layout_version") == 5,
119
119
  "unsupported CLI or storage contract; no repository operation was started")
120
120
  for capability in ("task_workflow_version", "session_closeout_expectations_version",
@@ -63,8 +63,8 @@ def main():
63
63
  workspace = args.workspace.absolute()
64
64
  if workspace.exists() or workspace.is_symlink() or not workspace.parent.is_dir():
65
65
  parser.error("--workspace must be a new path under an existing directory")
66
- if sys.platform != "linux" or sys.version_info[:2] != (3, 12):
67
- parser.error("the demo requires Linux and Python 3.12")
66
+ if sys.platform != "linux" or not ((3, 12) <= sys.version_info[:2] < (3, 15)):
67
+ parser.error("the demo requires Linux and Python 3.12-3.14")
68
68
  controller = Path(sys.executable).with_name("worktree-controller")
69
69
  if not controller.is_file():
70
70
  found = shutil.which("worktree-controller")
@@ -4,18 +4,23 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.34.2"
7
+ version = "1.36.0"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
- requires-python = ">=3.12,<3.13"
10
+ requires-python = ">=3.12,<3.15"
11
11
  license = "Apache-2.0"
12
12
  license-files = ["LICENSE"]
13
- dependencies = ["websockets>=15,<16"]
13
+ dependencies = []
14
14
  classifiers = [
15
15
  "Operating System :: POSIX :: Linux",
16
16
  "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Programming Language :: Python :: 3.14",
17
19
  ]
18
20
 
21
+ [project.optional-dependencies]
22
+ native-session = ["websockets>=15,<16"]
23
+
19
24
  [project.urls]
20
25
  Homepage = "https://github.com/xuanheng-tech/worktree-controller"
21
26
  Documentation = "https://github.com/xuanheng-tech/worktree-controller/blob/main/README.md"
@@ -4,18 +4,23 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.34.2"
7
+ version = "1.36.0"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
- requires-python = ">=3.12,<3.13"
10
+ requires-python = ">=3.12,<3.15"
11
11
  license = "Apache-2.0"
12
12
  license-files = ["LICENSE"]
13
- dependencies = ["websockets>=15,<16"]
13
+ dependencies = []
14
14
  classifiers = [
15
15
  "Operating System :: POSIX :: Linux",
16
16
  "Programming Language :: Python :: 3.12",
17
+ "Programming Language :: Python :: 3.13",
18
+ "Programming Language :: Python :: 3.14",
17
19
  ]
18
20
 
21
+ [project.optional-dependencies]
22
+ native-session = ["websockets>=15,<16"]
23
+
19
24
  [project.urls]
20
25
  Homepage = "https://github.com/xuanheng-tech/worktree-controller"
21
26
  Documentation = "https://github.com/xuanheng-tech/worktree-controller/blob/main/README.md"
@@ -1,3 +1,3 @@
1
1
  """Worktree lifecycle controller."""
2
2
 
3
- __version__ = "1.34.2"
3
+ __version__ = "1.36.0"
@@ -85,6 +85,7 @@ def _lease_bytes(raw: bytes, *, reverse: bool = False) -> bytes:
85
85
  writer_lease_from_dict(value)
86
86
  value["schema_version"] = 1
87
87
  value["holder"]["provider"] = value["holder"].pop("client_id")
88
+ value["holder"].pop("process_group_id", None)
88
89
  else:
89
90
  if (
90
91
  type(value.get("schema_version")) is not int
@@ -94,6 +95,7 @@ def _lease_bytes(raw: bytes, *, reverse: bool = False) -> bytes:
94
95
  raise LayoutError("previous writer lease does not match schema 1")
95
96
  value["schema_version"] = 2
96
97
  value["holder"]["client_id"] = value["holder"].pop("provider")
98
+ value["holder"].pop("process_group_id", None)
97
99
  writer_lease_from_dict(value)
98
100
  return (json.dumps(value, ensure_ascii=False, indent=2, sort_keys=True) + "\n").encode()
99
101
 
@@ -42,7 +42,7 @@ from .models import (
42
42
  )
43
43
  from .policy import load_policy
44
44
  from .resource_admission import canonical_holder_digest
45
- from .semantics import integration_intent_abandoned
45
+ from .semantics import effective_intent_state, integration_intent_abandoned
46
46
  from .store import MetadataStore, now_iso
47
47
  from .writer_lease import describe_holder, holder_is_live, resolve_holder
48
48
 
@@ -66,7 +66,6 @@ OPERATIONS = frozenset({"local", "remote"})
66
66
  REMOTE_PATTERN = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]{0,127}")
67
67
  PROTECTED_BRANCHES = frozenset({"main", "master", "trunk", "production"})
68
68
  SPECIAL_PREFIXES = ("rescue/", "archive/", "recovery/")
69
- TERMINAL_INTEGRATION_STATES = frozenset({"RELEASED"})
70
69
  TERMINAL_RELEASE_STATES = frozenset({"RELEASED", "CANCELLED"})
71
70
 
72
71
  # Only authority-bearing Controller state participates. Branch retirement plans and
@@ -746,8 +745,7 @@ def _evaluate(
746
745
  blockers.append("RELEASE_INTENT_UNRESOLVED")
747
746
  if any(
748
747
  (intent.allocation_id == resolved_allocation or resolved_allocation in intent.source_allocations)
749
- and intent.state not in TERMINAL_INTEGRATION_STATES
750
- and not integration_intent_abandoned(intent)
748
+ and effective_intent_state(snapshot, intent) not in {"RELEASED", "ABANDONED"}
751
749
  for intent in snapshot.integration_intents.values()
752
750
  ):
753
751
  blockers.append("INTEGRATION_INTENT_UNRESOLVED")
@@ -1146,10 +1144,7 @@ def outstanding_retirement_authorizations(
1146
1144
  for path in sorted(directory.glob("*.json")):
1147
1145
  if is_atomic_temp(path.name) or path.name.endswith("-abandoned.json"):
1148
1146
  continue
1149
- try:
1150
- value = dict(store._read_json(path))
1151
- except ControllerError:
1152
- continue
1147
+ value = dict(store._read_json(path))
1153
1148
  if value.get("contract") != execution.AUTHORIZATION_CONTRACT:
1154
1149
  continue
1155
1150
  if branch is not None and value.get("branch") != branch:
@@ -1245,13 +1240,34 @@ def authorize_branch_retirement(
1245
1240
  if operation == "local"
1246
1241
  else str(current["remote_tracking_ref"])
1247
1242
  )
1243
+ selector = holder or "self"
1244
+ if selector != "self" and not selector.startswith("ancestor:"):
1245
+ raise ControllerError(
1246
+ "INVALID_HOLDER",
1247
+ "a grant binds the calling process tree: use self or ancestor:<program>, never a "
1248
+ "detached pid that names somebody else's process",
1249
+ )
1250
+ resolved = (
1251
+ describe_holder(os.getpid(), client_id=client_id, session_id=session_id, run_id=run_id)
1252
+ if selector == "self"
1253
+ else resolve_holder(
1254
+ selector, client_id=client_id, session_id=session_id, run_id=run_id
1255
+ )
1256
+ )
1257
+ caller_holder_sha256 = canonical_holder_digest(asdict(resolved))
1248
1258
  live = [
1249
1259
  item
1250
1260
  for item in outstanding_retirement_authorizations(store, branch=str(current["branch"]))
1251
1261
  if item.get("operation") == operation
1252
1262
  ]
1253
1263
  replayed = next((item for item in live if item.get("request_id") == request_id), None)
1254
- if replayed is not None:
1264
+ if (
1265
+ replayed is not None
1266
+ and code == "RETIREMENT_EXECUTABLE"
1267
+ and replayed.get("plan_id") == plan_id
1268
+ and not grant_expired(replayed)
1269
+ and replayed.get("holder_sha256") == caller_holder_sha256
1270
+ ):
1255
1271
  return _payload(
1256
1272
  "branch-retirement-authorize",
1257
1273
  {
@@ -1259,6 +1275,7 @@ def authorize_branch_retirement(
1259
1275
  "idempotent": True,
1260
1276
  "plan_id": plan_id,
1261
1277
  "operation": operation,
1278
+ "authorization_id": replayed["authorization_id"],
1262
1279
  "authorization": replayed,
1263
1280
  "blockers": [],
1264
1281
  },
@@ -1288,21 +1305,6 @@ def authorize_branch_retirement(
1288
1305
  "outstanding_authorization_id": live[0]["authorization_id"],
1289
1306
  },
1290
1307
  )
1291
-
1292
- selector = holder or "self"
1293
- if selector != "self" and not selector.startswith("ancestor:"):
1294
- raise ControllerError(
1295
- "INVALID_HOLDER",
1296
- "a grant binds the calling process tree: use self or ancestor:<program>, never a "
1297
- "detached pid that names somebody else's process",
1298
- )
1299
- resolved = (
1300
- describe_holder(os.getpid(), client_id=client_id, session_id=session_id, run_id=run_id)
1301
- if selector == "self"
1302
- else resolve_holder(
1303
- selector, client_id=client_id, session_id=session_id, run_id=run_id
1304
- )
1305
- )
1306
1308
  issued_at = now_iso()
1307
1309
  expires_at = (
1308
1310
  datetime.fromisoformat(issued_at)
@@ -1409,10 +1411,41 @@ def complete_branch_retirement(
1409
1411
  repository = inventory(repository_path)
1410
1412
  store = MetadataStore(repository.common_dir)
1411
1413
  with store.lock(exclusive=True, create=False):
1414
+ if not re.fullmatch(r"[0-9a-f]{64}", authorization_id):
1415
+ raise ControllerError("INVALID_AUTHORIZATION_ID", "authorization id must be sha256")
1416
+ grant_exists = _authorization_path(store, authorization_id).is_file()
1417
+ grant: dict[str, Any] | None = None
1418
+ if grant_exists:
1419
+ grant = _load_authorization(store, authorization_id)
1420
+ if not hmac.compare_digest(str(grant["token"]), str(token)):
1421
+ raise ControllerError("AUTHORIZATION_TOKEN_MISMATCH", "execution token differs")
1422
+ for field in ("plan_id", "operation", "kind", "ref", "expected_oid", "expected_integrated_oid"):
1423
+ if result[field] != grant[field]:
1424
+ raise ControllerError(
1425
+ "EXECUTION_RESULT_MISMATCH", f"result {field} differs from the authorization"
1426
+ )
1427
+ if result["integrated_ref"] is not None and result["integrated_ref"] != grant["integrated_ref"]:
1428
+ raise ControllerError("EXECUTION_RESULT_MISMATCH", "result integrated_ref differs")
1412
1429
  settled = _receipt_by_authorization(store, authorization_id)
1413
1430
  if settled is not None:
1414
1431
  receipt, plan_id, operation = settled
1415
- if _authorization_path(store, authorization_id).is_file():
1432
+ if not grant_exists:
1433
+ if (
1434
+ result["plan_id"] != receipt.get("plan_id")
1435
+ or result["operation"] != receipt.get("operation")
1436
+ or result["expected_oid"] != receipt.get("expected_oid")
1437
+ or result["expected_integrated_oid"] != receipt.get("expected_integrated_oid")
1438
+ ):
1439
+ raise ControllerError(
1440
+ "EXECUTION_RESULT_MISMATCH", "result differs from settled retirement receipt"
1441
+ )
1442
+ recorded_token_hash = receipt.get("token_sha256")
1443
+ if recorded_token_hash is not None and not hmac.compare_digest(
1444
+ hashlib.sha256(str(token).encode("utf-8")).hexdigest(),
1445
+ str(recorded_token_hash),
1446
+ ):
1447
+ raise ControllerError("AUTHORIZATION_TOKEN_MISMATCH", "execution token differs")
1448
+ if grant_exists:
1416
1449
  # Crash between the receipt write and the grant close: the decision
1417
1450
  # is already recorded, so finishing the close needs no new one.
1418
1451
  _close_authorization(store, authorization_id)
@@ -1428,20 +1461,18 @@ def complete_branch_retirement(
1428
1461
  "provenance": receipt.get("provenance", RECEIPT_PROVENANCE_CLAIM),
1429
1462
  },
1430
1463
  )
1431
- grant = _load_authorization(store, authorization_id)
1432
- if not hmac.compare_digest(str(grant["token"]), str(token)):
1433
- raise ControllerError("AUTHORIZATION_TOKEN_MISMATCH", "execution token differs")
1434
- for field in ("plan_id", "operation", "kind", "ref", "expected_oid", "expected_integrated_oid"):
1435
- if result[field] != grant[field]:
1436
- raise ControllerError(
1437
- "EXECUTION_RESULT_MISMATCH", f"result {field} differs from the authorization"
1438
- )
1439
- if result["integrated_ref"] is not None and result["integrated_ref"] != grant["integrated_ref"]:
1440
- raise ControllerError("EXECUTION_RESULT_MISMATCH", "result integrated_ref differs")
1464
+ if grant is None:
1465
+ grant = _load_authorization(store, authorization_id)
1441
1466
  plan = _load_plan(store, str(grant["plan_id"]))
1442
1467
  authorization_id_value = str(grant["authorization_id"])
1443
1468
  receipt_path = _receipt_path(store, str(grant["plan_id"]), str(grant["operation"]))
1444
1469
  if receipt_path.is_file():
1470
+ existing_receipt = dict(store._read_json(receipt_path))
1471
+ if existing_receipt.get("authorization_id") != authorization_id_value:
1472
+ raise ControllerError(
1473
+ "EXECUTION_RESULT_MISMATCH",
1474
+ "existing completion receipt belongs to a different authorization",
1475
+ )
1445
1476
  # A receipt without a closed grant is a crash between the two writes;
1446
1477
  # finishing the close is the only safe repair and needs no new decision.
1447
1478
  _close_authorization(store, authorization_id_value)
@@ -1453,7 +1484,7 @@ def complete_branch_retirement(
1453
1484
  "authorization_id": authorization_id_value,
1454
1485
  "plan_id": grant["plan_id"],
1455
1486
  "operation": grant["operation"],
1456
- "receipt": dict(store._read_json(receipt_path)),
1487
+ "receipt": existing_receipt,
1457
1488
  "provenance": RECEIPT_PROVENANCE_AUTHORIZED,
1458
1489
  "grant_expired_at_settle": False,
1459
1490
  },
@@ -1499,7 +1530,13 @@ def complete_branch_retirement(
1499
1530
  _locked_store=store,
1500
1531
  )
1501
1532
  live_observation = _observation(repository, current)
1502
- blockers = _observation_delta(grant["observed"], live_observation, authorized_ref=str(grant["ref"]))
1533
+ blockers = _observation_delta(
1534
+ grant["observed"],
1535
+ live_observation,
1536
+ authorized_ref=str(grant["ref"]),
1537
+ canonical_path=repository.canonical_path,
1538
+ integrated_ref=str(grant.get("integrated_ref") or ""),
1539
+ )
1503
1540
  if str(current["controller_state_digest"]) != str(grant["controller_state_digest"]):
1504
1541
  blockers = sorted({*blockers, "PLAN_STATE_DRIFT"})
1505
1542
  if blockers:
@@ -1544,6 +1581,7 @@ def complete_branch_retirement(
1544
1581
  "observed_ref": grant["ref"],
1545
1582
  "observed_at_settle": target_before,
1546
1583
  "executor_name": result["executor"]["name"],
1584
+ "token_sha256": hashlib.sha256(str(grant["token"]).encode("utf-8")).hexdigest(),
1547
1585
  }
1548
1586
  store._atomic_json(receipt_path, receipt)
1549
1587
  _crash_point("retirement_receipt_written")
@@ -1570,21 +1608,27 @@ def _receipt_by_authorization(
1570
1608
  ) -> tuple[dict[str, Any], str, str] | None:
1571
1609
  """Find a settled retirement from its grant id, so replay answers after closure."""
1572
1610
 
1611
+ from .transaction_scope import is_atomic_temp
1612
+
1573
1613
  directory = store.branch_retirement_receipts_dir
1574
1614
  if not directory.is_dir():
1575
1615
  return None
1576
1616
  for receipt_file in sorted(directory.glob("*.json")):
1577
- try:
1578
- receipt = dict(store._read_json(receipt_file))
1579
- except ControllerError:
1617
+ if is_atomic_temp(receipt_file.name):
1580
1618
  continue
1619
+ receipt = dict(store._read_json(receipt_file))
1581
1620
  if receipt.get("authorization_id") == authorization_id:
1582
1621
  return receipt, str(receipt["plan_id"]), str(receipt["operation"])
1583
1622
  return None
1584
1623
 
1585
1624
 
1586
1625
  def _observation_delta(
1587
- bound: object, live: Mapping[str, Any], *, authorized_ref: str
1626
+ bound: object,
1627
+ live: Mapping[str, Any],
1628
+ *,
1629
+ authorized_ref: str,
1630
+ canonical_path: Path | None = None,
1631
+ integrated_ref: str | None = None,
1588
1632
  ) -> list[str]:
1589
1633
  """Blockers for the live Git facts the authorized deletion must not have touched.
1590
1634
 
@@ -1603,7 +1647,17 @@ def _observation_delta(
1603
1647
  for ref, oid in sorted(bound_refs.items()):
1604
1648
  if ref == authorized_ref:
1605
1649
  continue
1606
- if live_refs.get(ref) != oid:
1650
+ live_oid = live_refs.get(ref)
1651
+ if live_oid != oid:
1652
+ if (
1653
+ integrated_ref
1654
+ and ref == integrated_ref
1655
+ and canonical_path is not None
1656
+ and isinstance(oid, str)
1657
+ and isinstance(live_oid, str)
1658
+ and is_ancestor(canonical_path, oid, live_oid)
1659
+ ):
1660
+ continue
1607
1661
  blockers.append("OBSERVATION_REF_MOVED")
1608
1662
  if live.get("checked_out_paths"):
1609
1663
  blockers.append("OBSERVATION_CHECKOUT_APPEARED")