worktree-controller 1.34.1__tar.gz → 1.34.4__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 (82) hide show
  1. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/PKG-INFO +1 -1
  2. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/operations.md +4 -2
  3. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/reference.md +8 -0
  4. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/pyproject.toml +1 -1
  5. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/pyproject.toml.orig +1 -1
  6. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/__init__.py +1 -1
  7. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/activation_layout.py +2 -0
  8. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/cli.py +14 -3
  9. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/convergence.py +69 -19
  10. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/lifecycle.py +180 -20
  11. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/metadata_codec.py +24 -19
  12. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/models.py +2 -1
  13. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/namespace_migration.py +9 -9
  14. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/record_updates.py +9 -1
  15. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/resource_admission.py +43 -9
  16. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/semantics.py +2 -1
  17. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/session.py +9 -4
  18. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/session_admission.py +2 -0
  19. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/tool_cli_contract.json +4 -3
  20. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/transaction_scope.py +30 -5
  21. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/writer_lease.py +57 -11
  22. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/tool_cli_contract.json +4 -3
  23. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/LICENSE +0 -0
  24. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/README.md +0 -0
  25. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/architecture.md +0 -0
  26. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/build-resources.md +0 -0
  27. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/client-integration.md +0 -0
  28. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/daily-workflow.md +0 -0
  29. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/first-change.md +0 -0
  30. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/getting-started.md +0 -0
  31. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/integration-boundaries.md +0 -0
  32. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/publishing.md +0 -0
  33. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/roadmap.md +0 -0
  34. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/docs/scope.md +0 -0
  35. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/examples/change_task.py +0 -0
  36. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/examples/client_continuation.py +0 -0
  37. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/examples/quickstart.py +0 -0
  38. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/branch_retirement.py +0 -0
  39. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/build_preservation.py +0 -0
  40. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/build_resources.py +0 -0
  41. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/canonical_refresh.py +0 -0
  42. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/canonical_transition.py +0 -0
  43. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/cleanup_attempts.py +0 -0
  44. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/cleanup_evidence.py +0 -0
  45. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/cleanup_recovery.py +0 -0
  46. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/controller.py +0 -0
  47. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/delivered_closeout.py +0 -0
  48. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/disposable.py +0 -0
  49. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/environment.py +0 -0
  50. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/frozen_recovery.py +0 -0
  51. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/git_backend.py +0 -0
  52. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/governance.py +0 -0
  53. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/hardlinks.py +0 -0
  54. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/integration_cleanup.py +0 -0
  55. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/integration_conflict.py +0 -0
  56. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/integration_retry.py +0 -0
  57. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/keyed_document_scope.py +0 -0
  58. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/lifecycle_history.py +0 -0
  59. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/lifecycle_observation.py +0 -0
  60. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/metadata_relocation.py +0 -0
  61. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/mount_diagnostics.py +0 -0
  62. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/multiple_cleanup_recovery.py +0 -0
  63. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/native_session_recovery.py +0 -0
  64. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/owner_actions.py +0 -0
  65. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/policy.py +0 -0
  66. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/preservation.py +0 -0
  67. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/preserved_cleanup.py +0 -0
  68. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/publication_execution.py +0 -0
  69. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/reconciler.py +0 -0
  70. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/recovery_guidance.py +0 -0
  71. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/registration_backfill.py +0 -0
  72. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/registration_prune.py +0 -0
  73. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/release_intents.py +0 -0
  74. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/rendering.py +0 -0
  75. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/retirement_adapters.py +0 -0
  76. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/retirement_execution.py +0 -0
  77. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/source_cleanup.py +0 -0
  78. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/source_preservation.py +0 -0
  79. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/source_recovery.py +0 -0
  80. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/store.py +0 -0
  81. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/src/worktree_controller/task_workflow.py +0 -0
  82. {worktree_controller-1.34.1 → worktree_controller-1.34.4}/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.34.1
3
+ Version: 1.34.4
4
4
  Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -399,8 +399,10 @@ installed runtimes available for verification and rollback.
399
399
  The gate requires a root release whose runtime, packaging, maintenance scripts and complete Skill
400
400
  payload exactly equal the original frozen predecessor. Both public baseline and target must have
401
401
  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.
402
+ metadata and installed Skill bytes. Writer-lease format must also remain unchanged, except for the
403
+ backward-readable schema 2 to 3 upgrade; every other lease-format migration remains refused. This
404
+ entry cannot combine namespace, policy, Skill or cleanup migrations. Existing resource, metadata and
405
+ consumer gates still run.
404
406
  Live compatible writer sessions may continue; incompatible, stale or incomplete evidence is not
405
407
  made eligible by this procedure.
406
408
 
@@ -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
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.34.1"
7
+ version = "1.34.4"
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.34.1"
7
+ version = "1.34.4"
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.34.1"
3
+ __version__ = "1.34.4"
@@ -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
 
@@ -83,7 +83,12 @@ from .namespace_migration import (
83
83
  from .reconciler import reconcile_writers
84
84
  from .rendering import render
85
85
  from .retirement_execution import KIND_CAS_DELETE
86
- from .writer_lease import acquire_writer_lease, release_writer_lease, resolve_holder
86
+ from .writer_lease import (
87
+ HOLDER_RESOLVER_VERSION,
88
+ acquire_writer_lease,
89
+ release_writer_lease,
90
+ resolve_holder,
91
+ )
87
92
 
88
93
 
89
94
  def _common_parser() -> argparse.ArgumentParser:
@@ -896,6 +901,10 @@ def build_parser() -> argparse.ArgumentParser:
896
901
  reopen_parser.add_argument("--path", type=Path, required=True)
897
902
  reopen_parser.add_argument("--expected-record-version", type=int, required=True)
898
903
  reopen_parser.add_argument("--owner", required=True)
904
+ reopen_parser.add_argument(
905
+ "--drifted-head",
906
+ help="exact observed HEAD of a frozen checkout that gained commits after its handoff",
907
+ )
899
908
 
900
909
  for recovery_command in ("recover-handoff", "recover-published"):
901
910
  recovery_parser = commands.add_parser(
@@ -1065,6 +1074,7 @@ def _main(argv: list[str] | None) -> int:
1065
1074
  "retained_typed_cleanup_version": 1,
1066
1075
  "aborted_integration_preserved_cleanup_version": 2,
1067
1076
  "aborted_integration_branch_retirement_version": 1,
1077
+ "drifted_handoff_reopen_version": 1,
1068
1078
  "terminal_preserved_cleanup_version": 1,
1069
1079
  "preservation_leaf_version": 1,
1070
1080
  "integration_publication_execution_version": 1,
@@ -1074,7 +1084,7 @@ def _main(argv: list[str] | None) -> int:
1074
1084
  "capabilities_version": 1,
1075
1085
  "storage_layout_version": 5,
1076
1086
  "writer_session_version": 2,
1077
- "holder_resolver_version": 1,
1087
+ "holder_resolver_version": HOLDER_RESOLVER_VERSION,
1078
1088
  "host_managed_writer_session_version": HOST_MANAGED_WRITER_SESSION_VERSION,
1079
1089
  "resource_admission_version": 1,
1080
1090
  "acquire_no_effect_recovery_version": 1,
@@ -1105,7 +1115,7 @@ def _main(argv: list[str] | None) -> int:
1105
1115
  "typed_cleanup_no_action_receipt_version": 1,
1106
1116
  "typed_cleanup_verify_boundary_version": 1,
1107
1117
  "supported_writer_session_versions": [1, 2],
1108
- "writer_lease_schema_version": 2,
1118
+ "writer_lease_schema_version": 3,
1109
1119
  }
1110
1120
  elif parsed.command == "publication-execution-session":
1111
1121
  from .publication_execution import run_session
@@ -1831,6 +1841,7 @@ def _main(argv: list[str] | None) -> int:
1831
1841
  target=parsed.path,
1832
1842
  expected_record_version=parsed.expected_record_version,
1833
1843
  owner=parsed.owner,
1844
+ drifted_head=parsed.drifted_head,
1834
1845
  )
1835
1846
  elif parsed.command in {"binding-add", "binding-remove", "binding-transfer"}:
1836
1847
  payload = update_external_binding(
@@ -149,19 +149,36 @@ def busy_paths(targets: set[str]) -> set[str]:
149
149
  Same evidence as ``writer_lease.paths_in_use`` (cwd, open files, mappings), but a
150
150
  single scan serves every checkout instead of one full scan per checkout.
151
151
  """
152
+ if not targets:
153
+ return set()
152
154
 
153
155
  found: set[str] = set()
156
+ target_prefixes = tuple((t, t if t.endswith(os.sep) else t + os.sep) for t in targets)
157
+ try:
158
+ common_parent = os.path.commonpath(list(targets))
159
+ if not common_parent.endswith(os.sep):
160
+ common_prefix = common_parent + os.sep
161
+ else:
162
+ common_prefix = common_parent
163
+ except ValueError:
164
+ common_parent = None
165
+ common_prefix = None
166
+
154
167
  own = os.getpid()
155
168
  for entry in os.listdir("/proc"):
156
169
  if not entry.isdigit() or int(entry) == own:
157
170
  continue
158
171
  for candidate in _referenced_paths(int(entry)):
159
- current = candidate
160
- while current and current != os.sep:
161
- if current in targets:
162
- found.add(current)
172
+ if common_prefix is not None and not (
173
+ candidate == common_parent or candidate.startswith(common_prefix)
174
+ ):
175
+ continue
176
+ for target, prefix in target_prefixes:
177
+ if target not in found and (candidate == target or candidate.startswith(prefix)):
178
+ found.add(target)
163
179
  break
164
- current = os.path.dirname(current)
180
+ if len(found) == len(targets):
181
+ break
165
182
  return found
166
183
 
167
184
 
@@ -682,12 +699,31 @@ def _converge(
682
699
  "untracked": item.untracked,
683
700
  },
684
701
  owner_action=_dirty_owner_action(item, record),
685
- owner_action_request=owner_action(str(repository.canonical_path), {
686
- "path": str(item.path), "head": item.head, "branch": item.branch,
687
- **{key: getattr(record, key) for key in
688
- ("allocation_id", "task_key", "authority_key", "owner", "record_version")},
689
- }, reason="DIRTY_WORKTREE", required_actions=(
690
- "review_task_files", "finalize_or_checkpoint", "preserve_unknown_files", "park_or_handoff")),
702
+ owner_action_request=owner_action(
703
+ str(repository.canonical_path),
704
+ {
705
+ "path": str(item.path),
706
+ "head": item.head,
707
+ "branch": item.branch,
708
+ **{
709
+ key: getattr(record, key)
710
+ for key in (
711
+ "allocation_id",
712
+ "task_key",
713
+ "authority_key",
714
+ "owner",
715
+ "record_version",
716
+ )
717
+ },
718
+ },
719
+ reason="DIRTY_WORKTREE",
720
+ required_actions=(
721
+ "review_task_files",
722
+ "finalize_or_checkpoint",
723
+ "preserve_unknown_files",
724
+ "park_or_handoff",
725
+ ),
726
+ ),
691
727
  )
692
728
  continue
693
729
  if _integration_bound(snapshot, record):
@@ -724,22 +760,36 @@ def _converge(
724
760
  row.update(outcome=WAITING, reason="idle time is below the current threshold")
725
761
  continue
726
762
  if dry_run:
727
- if dormant or route not in {"release", "release-published-handoff", "release-retained-handoff"}:
728
- row.update(outcome=PREREQUISITE, reason=f"{route} must complete before exact release preflight")
763
+ if dormant or route not in {
764
+ "release",
765
+ "release-published-handoff",
766
+ "release-retained-handoff",
767
+ }:
768
+ row.update(
769
+ outcome=PREREQUISITE,
770
+ reason=f"{route} must complete before exact release preflight",
771
+ )
729
772
  continue
730
773
  try:
731
774
  checked = release(
732
- repository_path, target=Path(item.path),
733
- expected_record_version=record.record_version, owner_release=record.owner,
775
+ repository_path,
776
+ target=Path(item.path),
777
+ expected_record_version=record.record_version,
778
+ owner_release=record.owner,
734
779
  teardown_reproducible_venv=any(
735
- resource["state"] == "registered" for resource in record.disposable_resources
736
- ), dry_run=True,
780
+ resource["state"] == "registered"
781
+ for resource in record.disposable_resources
782
+ ),
783
+ dry_run=True,
737
784
  )
738
785
  except ControllerError as exc:
739
786
  row.update(outcome=BLOCKED, reason=str(exc), code=exc.code)
740
787
  continue
741
- row.update(outcome=PLANNED, reason="exact guarded release preflight passed",
742
- release_preflight=checked["decision"])
788
+ row.update(
789
+ outcome=PLANNED,
790
+ reason="exact guarded release preflight passed",
791
+ release_preflight=checked["decision"],
792
+ )
743
793
  continue
744
794
  try:
745
795
  current = record
@@ -421,8 +421,10 @@ def _transaction(
421
421
  expected_head: str | None,
422
422
  expected_record_version: int | None,
423
423
  created_at: str,
424
+ integration_intent_id: str | None = None,
425
+ integration_pending_merge: bool = False,
424
426
  ) -> dict[str, Any]:
425
- return {
427
+ payload: dict[str, Any] = {
426
428
  "schema_version": METADATA_SCHEMA_VERSION,
427
429
  "transaction_id": transaction_id,
428
430
  "repository_id": repository_id,
@@ -436,6 +438,11 @@ def _transaction(
436
438
  "created_at": created_at,
437
439
  "updated_at": now_iso(),
438
440
  }
441
+ if integration_intent_id is not None:
442
+ payload["integration_intent_id"] = integration_intent_id
443
+ if integration_pending_merge:
444
+ payload["integration_pending_merge"] = integration_pending_merge
445
+ return payload
439
446
 
440
447
 
441
448
  def _assert_all_adopted(repository: RepositoryInventory, snapshot: MetadataSnapshot) -> None:
@@ -1003,7 +1010,20 @@ def _reuse_integration_claim(
1003
1010
  raise ControllerError("INTEGRATION_INTENT_MISMATCH", "claim differs from its bound candidate")
1004
1011
  if item.detached or not item.clean or item.head != intent.candidate_oid:
1005
1012
  raise ControllerError("CANDIDATE_IDENTITY_MISMATCH", "claimed candidate changed")
1006
- issues = integration_candidate_issues(item, record, snapshot)
1013
+ event = intent.history[-1] if intent.history else {}
1014
+ pending_merge = (
1015
+ event.get("event") == "CANDIDATE_CLAIMED"
1016
+ and len(intent.source_handoffs) == 1
1017
+ and event.get("pending_merge_source") == intent.source_handoffs[0]
1018
+ and event.get("pending_merge_base") == intent.base_main_oid
1019
+ and intent.candidate_oid == intent.base_main_oid
1020
+ )
1021
+ issues = integration_candidate_issues(
1022
+ item,
1023
+ record,
1024
+ snapshot,
1025
+ pending_merge_source=intent.source_handoffs[0] if pending_merge else None,
1026
+ )
1007
1027
  if issues:
1008
1028
  raise ControllerError(issues[0]["code"], issues[0]["message"])
1009
1029
  if conflicts(store, allocation=record.allocation_id, target=item.path):
@@ -1011,11 +1031,124 @@ def _reuse_integration_claim(
1011
1031
  _sources(repository, snapshot, store, intent, require_idle=False)
1012
1032
  payload = status(repository_path)
1013
1033
  payload["command"] = "integration-claim"
1014
- payload["decision"] = {"code": "INTEGRATION_CANDIDATE_CLAIMED",
1015
- "reason": "existing unchanged preparing candidate retained", **_intent_payload(intent)}
1034
+ payload["decision"] = {
1035
+ "code": "INTEGRATION_CONFLICT_CLAIMED" if pending_merge else "INTEGRATION_CANDIDATE_CLAIMED",
1036
+ "reason": "existing unchanged preparing candidate retained",
1037
+ "pending_merge_source": intent.source_handoffs[0] if pending_merge else None,
1038
+ **_intent_payload(intent),
1039
+ }
1016
1040
  return payload
1017
1041
 
1018
1042
 
1043
+ def _resume_integration_acquire(
1044
+ repository_path: Path, *, intent_id: str, target: Path | None, branch: str | None
1045
+ ) -> None:
1046
+ repository = inventory(repository_path)
1047
+ store = MetadataStore(repository.common_dir)
1048
+ with store.lock(exclusive=True):
1049
+ repository = inventory(repository_path)
1050
+ snapshot = store._load_unlocked()
1051
+ intent = snapshot.integration_intents.get(intent_id)
1052
+ if intent is None or intent.state not in {"QUEUED", "PREPARING_INTEGRATION"}:
1053
+ return
1054
+ journals = []
1055
+ for path in sorted(store.transactions_dir.glob("*.json")):
1056
+ journal = dict(store._read_json(path))
1057
+ if (
1058
+ journal.get("command") == "acquire"
1059
+ and journal.get("integration_intent_id") == intent_id
1060
+ and journal.get("phase") in {"WORKTREE_ADDED", "METADATA_WRITTEN"}
1061
+ ):
1062
+ journals.append((path, journal))
1063
+ if not journals:
1064
+ return
1065
+ if len(journals) != 1:
1066
+ raise ControllerError(
1067
+ "INTEGRATION_INTENT_MISMATCH", "integration claim has ambiguous acquire journals"
1068
+ )
1069
+ path, journal = journals[0]
1070
+ expected_branch = branch or (
1071
+ f"integration/{intent.task_key}"
1072
+ + (f"-retry-{intent.attempt}" if intent.attempt > 1 else "")
1073
+ )
1074
+ allocation = journal.get("allocation_id")
1075
+ record = snapshot.records.get(allocation)
1076
+ items = [
1077
+ item for item in repository.worktrees
1078
+ if snapshot.bindings.get(item.key) == allocation
1079
+ ]
1080
+ if (
1081
+ journal.get("transaction_id") != path.stem
1082
+ or journal.get("repository_id") != snapshot.repository_id
1083
+ or not isinstance(allocation, str)
1084
+ or record is None
1085
+ or len(items) != 1
1086
+ or (target is not None and target.expanduser().absolute() != items[0].path)
1087
+ or journal.get("target_path") != str(items[0].path)
1088
+ or journal.get("branch") != expected_branch
1089
+ or items[0].branch != expected_branch
1090
+ or items[0].detached
1091
+ or not items[0].clean
1092
+ or items[0].head != journal.get("expected_head")
1093
+ or record.task_commit != journal.get("expected_head")
1094
+ or record.record_version != 1
1095
+ or (record.task_key, record.authority_key, record.module, record.owner)
1096
+ != (intent.task_key, intent.authority_key, intent.module, intent.owner)
1097
+ or record.role != "integration"
1098
+ or record.lifecycle != "ACTIVE"
1099
+ or record.source_allocations != intent.source_allocations
1100
+ or record.scope_paths != intent.scope_paths
1101
+ or type(journal.get("integration_pending_merge", False)) is not bool
1102
+ or (journal.get("integration_pending_merge") and len(intent.source_handoffs) != 1)
1103
+ ):
1104
+ raise ControllerError(
1105
+ "INTEGRATION_INTENT_MISMATCH", "interrupted integration acquire evidence changed"
1106
+ )
1107
+ if intent.state == "PREPARING_INTEGRATION" and (
1108
+ intent.allocation_id != allocation
1109
+ or intent.base_main_oid != record.base_commit
1110
+ or intent.candidate_oid != record.task_commit
1111
+ or intent.revision != 1
1112
+ ):
1113
+ raise ControllerError(
1114
+ "INTEGRATION_INTENT_MISMATCH", "claimed intent does not match its acquire journal"
1115
+ )
1116
+ if journal["phase"] == "METADATA_WRITTEN":
1117
+ if intent.state != "PREPARING_INTEGRATION":
1118
+ raise ControllerError(
1119
+ "INTEGRATION_INTENT_MISMATCH", "completed acquire has an unclaimed intent"
1120
+ )
1121
+ return
1122
+ if intent.state == "QUEUED":
1123
+ if intent.allocation_id is not None or snapshot.repository_id is None:
1124
+ raise ControllerError(
1125
+ "INTEGRATION_INTENT_MISMATCH", "queued intent already has an allocation"
1126
+ )
1127
+ intent = _updated_intent(
1128
+ intent,
1129
+ "CANDIDATE_CLAIMED",
1130
+ state="PREPARING_INTEGRATION",
1131
+ allocation_id=allocation,
1132
+ base_main_oid=record.base_commit,
1133
+ candidate_oid=record.task_commit,
1134
+ revision=1,
1135
+ claimed_at=now_iso(),
1136
+ blocked_reason=None,
1137
+ )
1138
+ if journal.get("integration_pending_merge"):
1139
+ event = {
1140
+ **intent.history[-1],
1141
+ "pending_merge_source": intent.source_handoffs[0],
1142
+ "pending_merge_base": record.task_commit,
1143
+ }
1144
+ intent = replace(intent, history=(*intent.history[:-1], event))
1145
+ store.replace_integration_intent(intent)
1146
+ _emit_lifecycle_event(store, snapshot.repository_id, intent, "PREPARE_SLOT_GRANTED")
1147
+ journal["phase"] = "METADATA_WRITTEN"
1148
+ journal["updated_at"] = now_iso()
1149
+ store.write_transaction(path.stem, journal)
1150
+
1151
+
1019
1152
  def claim_integration(
1020
1153
  repository_path: Path,
1021
1154
  *,
@@ -1032,6 +1165,14 @@ def claim_integration(
1032
1165
  snapshot = store.load()
1033
1166
  if intent_id is not None:
1034
1167
  requested = snapshot.integration_intents.get(intent_id)
1168
+ if requested is not None and requested.state in {"QUEUED", "PREPARING_INTEGRATION"}:
1169
+ if requested.owner != owner:
1170
+ raise ControllerError("OWNER_MISMATCH", "integration intent owner does not match")
1171
+ _resume_integration_acquire(
1172
+ repository_path, intent_id=intent_id, target=target, branch=branch
1173
+ )
1174
+ snapshot = store.load()
1175
+ requested = snapshot.integration_intents[intent_id]
1035
1176
  if requested is not None and requested.state == "PREPARING_INTEGRATION":
1036
1177
  return _reuse_integration_claim(repository_path, intent_id=intent_id, owner=owner,
1037
1178
  target=target, branch=branch)
@@ -1978,6 +2119,8 @@ def _acquire_once(
1978
2119
  expected_head=base_oid,
1979
2120
  expected_record_version=None,
1980
2121
  created_at=transaction_created,
2122
+ integration_intent_id=intent.intent_id if intent is not None else None,
2123
+ integration_pending_merge=pending_merge,
1981
2124
  )
1982
2125
  if resource_request is not None:
1983
2126
  AdmissionLedger().bind(resource_request, transaction_id=transaction_id,
@@ -3107,6 +3250,7 @@ def reopen(
3107
3250
  target: Path,
3108
3251
  expected_record_version: int,
3109
3252
  owner: str,
3253
+ drifted_head: str | None = None,
3110
3254
  ) -> dict[str, Any]:
3111
3255
  repository_initial = inventory(repository_path)
3112
3256
  store = MetadataStore(repository_initial.common_dir)
@@ -3139,19 +3283,33 @@ def reopen(
3139
3283
  raise ControllerError(
3140
3284
  "INTERRUPTED_TRANSACTION", "archive release transaction needs recovery"
3141
3285
  )
3142
- if not archived and (
3143
- record.handoff_commit is None
3144
- or record.task_commit is None
3145
- or record.finalizer_commit is None
3146
- or record.finalizer_record_id is None
3147
- or any(
3148
- identity != item.head
3149
- for identity in (
3150
- record.handoff_commit,
3151
- record.task_commit,
3152
- record.finalizer_commit,
3286
+ frozen_complete = (
3287
+ record.handoff_commit is not None
3288
+ and record.finalizer_record_id is not None
3289
+ and record.task_commit == record.handoff_commit
3290
+ and record.finalizer_commit == record.handoff_commit
3291
+ )
3292
+ drift_detail: dict[str, Any] | None = None
3293
+ if drifted_head is not None:
3294
+ # Commits made in a frozen checkout after its handoff: the owner names the
3295
+ # exact observed HEAD, which must strictly descend from the frozen identity.
3296
+ if archived or record.lifecycle != "HANDOFF_READY":
3297
+ raise ControllerError(
3298
+ "INVALID_LIFECYCLE", "drifted reopen requires a HANDOFF_READY allocation"
3153
3299
  )
3154
- )
3300
+ if (
3301
+ not frozen_complete
3302
+ or drifted_head != item.head
3303
+ or item.head == record.handoff_commit
3304
+ or not is_ancestor(repository.canonical_path, str(record.handoff_commit), item.head)
3305
+ ):
3306
+ raise ControllerError(
3307
+ "IDENTITY_MISMATCH",
3308
+ "drifted reopen requires the exact observed HEAD descending from the frozen handoff",
3309
+ )
3310
+ drift_detail = {"frozen_handoff_commit": record.handoff_commit, "observed_head": item.head}
3311
+ elif not archived and (
3312
+ not frozen_complete or record.handoff_commit != item.head
3155
3313
  ):
3156
3314
  raise ControllerError(
3157
3315
  "IDENTITY_MISMATCH", "reopen requires the exact frozen handoff identity"
@@ -3181,7 +3339,8 @@ def reopen(
3181
3339
  if archived
3182
3340
  else _updated_record(
3183
3341
  record,
3184
- "REOPENED",
3342
+ "REOPENED_AFTER_DRIFT" if drift_detail else "REOPENED",
3343
+ event_detail=drift_detail,
3185
3344
  lifecycle="ACTIVE",
3186
3345
  handoff_commit=None,
3187
3346
  finalizer_record_id=None,
@@ -8736,13 +8895,14 @@ def _recover_or_replay_removed_release(
8736
8895
  disposable_resources=tuple(resources),
8737
8896
  )
8738
8897
  store.replace_record(updated)
8739
- store.remove_binding(binding_keys[0])
8740
- store.remove_writer_lease(record.allocation_id)
8741
8898
  record = updated
8742
- elif record.record_version != plan.expected_record_version + 1 or binding_keys:
8899
+ elif record.record_version != plan.expected_record_version + 1 or len(binding_keys) > 1:
8743
8900
  raise ControllerError(
8744
8901
  "RELEASE_RECOVERY_MISMATCH", "released record does not match persisted plan"
8745
8902
  )
8903
+ for binding_key in binding_keys:
8904
+ store.remove_binding(binding_key)
8905
+ store.remove_writer_lease(record.allocation_id)
8746
8906
 
8747
8907
  transaction_id = str(transaction.get("transaction_id"))
8748
8908
  transaction["phase"] = "RELEASED_RECORDED"
@@ -1011,7 +1011,7 @@ def integration_reconciliation_receipt_to_dict(
1011
1011
  return asdict(receipt)
1012
1012
 
1013
1013
 
1014
- WRITER_LEASE_SCHEMA_VERSION = 2
1014
+ WRITER_LEASE_SCHEMA_VERSION = 3
1015
1015
  WRITER_RECEIPT_SCHEMA_VERSION = 1
1016
1016
 
1017
1017
 
@@ -1029,21 +1029,18 @@ def writer_lease_from_dict(data: Mapping[str, Any]) -> WriterLease:
1029
1029
  "expires_at",
1030
1030
  "record_version",
1031
1031
  }
1032
- if data.get("schema_version") != WRITER_LEASE_SCHEMA_VERSION or set(data) != expected:
1032
+ schema_version = data.get("schema_version")
1033
+ if schema_version not in {2, WRITER_LEASE_SCHEMA_VERSION} or set(data) != expected:
1033
1034
  raise ControllerError("INVALID_METADATA", "writer lease schema is invalid")
1034
1035
  lease_id = _optional_uuid(data.get("lease_id"), "lease_id")
1035
1036
  allocation_id = _optional_uuid(data.get("allocation_id"), "allocation_id")
1036
1037
  if lease_id is None or allocation_id is None:
1037
1038
  raise ControllerError("INVALID_METADATA", "writer lease identifiers are required")
1038
1039
  holder = data.get("holder")
1039
- if not isinstance(holder, Mapping) or set(holder) != {
1040
- "client_id",
1041
- "pid",
1042
- "boot_id",
1043
- "start_ticks",
1044
- "session_id",
1045
- "run_id",
1046
- }:
1040
+ holder_fields = {"client_id", "pid", "boot_id", "start_ticks", "session_id", "run_id"}
1041
+ if schema_version == WRITER_LEASE_SCHEMA_VERSION:
1042
+ holder_fields.add("process_group_id")
1043
+ if not isinstance(holder, Mapping) or set(holder) != holder_fields:
1047
1044
  raise ControllerError("INVALID_METADATA", "writer lease holder is invalid")
1048
1045
  session_id = holder.get("session_id")
1049
1046
  run_id = holder.get("run_id")
@@ -1053,7 +1050,7 @@ def writer_lease_from_dict(data: Mapping[str, Any]) -> WriterLease:
1053
1050
  raise ControllerError("INVALID_METADATA", "writer lease run is invalid")
1054
1051
  raw_expiry = data.get("expires_at")
1055
1052
  return WriterLease(
1056
- schema_version=WRITER_LEASE_SCHEMA_VERSION,
1053
+ schema_version=schema_version,
1057
1054
  lease_id=lease_id,
1058
1055
  repository_id=_nonempty_string(data.get("repository_id"), "repository_id"),
1059
1056
  allocation_id=allocation_id,
@@ -1066,6 +1063,11 @@ def writer_lease_from_dict(data: Mapping[str, Any]) -> WriterLease:
1066
1063
  start_ticks=_positive_int(holder.get("start_ticks"), "start_ticks"),
1067
1064
  session_id=session_id,
1068
1065
  run_id=run_id,
1066
+ process_group_id=(
1067
+ _positive_int(holder.get("process_group_id"), "process_group_id")
1068
+ if schema_version == WRITER_LEASE_SCHEMA_VERSION
1069
+ else None
1070
+ ),
1069
1071
  ),
1070
1072
  acquired_at=_validate_timestamp(data.get("acquired_at"), "acquired_at"),
1071
1073
  renewed_at=_validate_timestamp(data.get("renewed_at"), "renewed_at"),
@@ -1075,6 +1077,16 @@ def writer_lease_from_dict(data: Mapping[str, Any]) -> WriterLease:
1075
1077
 
1076
1078
 
1077
1079
  def writer_lease_to_dict(lease: WriterLease) -> dict[str, Any]:
1080
+ holder = {
1081
+ "client_id": lease.holder.client_id,
1082
+ "pid": lease.holder.pid,
1083
+ "boot_id": lease.holder.boot_id,
1084
+ "start_ticks": lease.holder.start_ticks,
1085
+ "session_id": lease.holder.session_id,
1086
+ "run_id": lease.holder.run_id,
1087
+ }
1088
+ if lease.schema_version == WRITER_LEASE_SCHEMA_VERSION:
1089
+ holder["process_group_id"] = lease.holder.process_group_id
1078
1090
  return {
1079
1091
  "schema_version": lease.schema_version,
1080
1092
  "lease_id": lease.lease_id,
@@ -1082,14 +1094,7 @@ def writer_lease_to_dict(lease: WriterLease) -> dict[str, Any]:
1082
1094
  "allocation_id": lease.allocation_id,
1083
1095
  "worktree_path": lease.worktree_path,
1084
1096
  "owner": lease.owner,
1085
- "holder": {
1086
- "client_id": lease.holder.client_id,
1087
- "pid": lease.holder.pid,
1088
- "boot_id": lease.holder.boot_id,
1089
- "start_ticks": lease.holder.start_ticks,
1090
- "session_id": lease.holder.session_id,
1091
- "run_id": lease.holder.run_id,
1092
- },
1097
+ "holder": holder,
1093
1098
  "acquired_at": lease.acquired_at,
1094
1099
  "renewed_at": lease.renewed_at,
1095
1100
  "expires_at": lease.expires_at,
@@ -2,7 +2,7 @@
2
2
 
3
3
  from __future__ import annotations
4
4
 
5
- from dataclasses import dataclass
5
+ from dataclasses import dataclass, field
6
6
  from pathlib import Path
7
7
  from typing import Any
8
8
 
@@ -381,6 +381,7 @@ class WriterHolder:
381
381
  start_ticks: int
382
382
  session_id: str | None
383
383
  run_id: str | None
384
+ process_group_id: int | None = field(default=None, compare=False)
384
385
 
385
386
 
386
387
  @dataclass(frozen=True)