worktree-controller 1.36.0__tar.gz → 1.36.1__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 (84) hide show
  1. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/PKG-INFO +1 -1
  2. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/pyproject.toml +1 -1
  3. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/pyproject.toml.orig +1 -1
  4. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/__init__.py +1 -1
  5. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/canonical_transition.py +2 -3
  6. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_attempts.py +2 -2
  7. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_recovery.py +8 -8
  8. worktree_controller-1.36.1/src/worktree_controller/cleanup_retention.py +475 -0
  9. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cli.py +48 -4
  10. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/controller.py +306 -17
  11. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/convergence.py +12 -0
  12. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/delivered_closeout.py +2 -2
  13. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/frozen_recovery.py +2 -3
  14. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/git_backend.py +21 -4
  15. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_conflict.py +2 -3
  16. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_retry.py +2 -3
  17. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle.py +117 -56
  18. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/multiple_cleanup_recovery.py +4 -4
  19. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/reconciler.py +2 -3
  20. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/recovery_guidance.py +1 -1
  21. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/registration_prune.py +2 -3
  22. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/session.py +1 -1
  23. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/store.py +3 -1
  24. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/task_workflow.py +1 -1
  25. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/tool_cli_contract.json +1 -1
  26. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/writer_lease.py +8 -4
  27. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/tool_cli_contract.json +1 -1
  28. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/LICENSE +0 -0
  29. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/README.md +0 -0
  30. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/architecture.md +0 -0
  31. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/build-resources.md +0 -0
  32. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/client-integration.md +0 -0
  33. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/daily-workflow.md +0 -0
  34. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/first-change.md +0 -0
  35. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/getting-started.md +0 -0
  36. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/integration-boundaries.md +0 -0
  37. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/operations.md +0 -0
  38. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/publishing.md +0 -0
  39. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/reference.md +0 -0
  40. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/roadmap.md +0 -0
  41. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/docs/scope.md +0 -0
  42. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/change_task.py +0 -0
  43. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/client_continuation.py +0 -0
  44. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/examples/quickstart.py +0 -0
  45. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/activation_layout.py +0 -0
  46. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/branch_retirement.py +0 -0
  47. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/build_preservation.py +0 -0
  48. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/build_resources.py +0 -0
  49. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/canonical_refresh.py +0 -0
  50. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/cleanup_evidence.py +0 -0
  51. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/disposable.py +0 -0
  52. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/environment.py +0 -0
  53. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/frontier.py +0 -0
  54. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/governance.py +0 -0
  55. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/hardlinks.py +0 -0
  56. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/integration_cleanup.py +0 -0
  57. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/keyed_document_scope.py +0 -0
  58. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle_history.py +0 -0
  59. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/lifecycle_observation.py +0 -0
  60. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/metadata_codec.py +0 -0
  61. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/metadata_relocation.py +0 -0
  62. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/models.py +0 -0
  63. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/mount_diagnostics.py +0 -0
  64. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/namespace_migration.py +0 -0
  65. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/native_session_recovery.py +0 -0
  66. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/owner_actions.py +0 -0
  67. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/policy.py +0 -0
  68. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/preservation.py +0 -0
  69. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/preserved_cleanup.py +0 -0
  70. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/publication_execution.py +0 -0
  71. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/record_updates.py +0 -0
  72. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/registration_backfill.py +0 -0
  73. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/release_intents.py +0 -0
  74. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/rendering.py +0 -0
  75. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/resource_admission.py +0 -0
  76. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/retirement_adapters.py +0 -0
  77. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/retirement_execution.py +0 -0
  78. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/semantics.py +0 -0
  79. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/session_admission.py +0 -0
  80. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_cleanup.py +0 -0
  81. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_preservation.py +0 -0
  82. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/source_recovery.py +0 -0
  83. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/src/worktree_controller/transaction_scope.py +0 -0
  84. {worktree_controller-1.36.0 → worktree_controller-1.36.1}/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.36.0
3
+ Version: 1.36.1
4
4
  Summary: Govern Git worktree budgets, authority, ownership, and lifecycle
5
5
  License-Expression: Apache-2.0
6
6
  License-File: LICENSE
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.36.0"
7
+ version = "1.36.1"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
@@ -4,7 +4,7 @@ build-backend = "uv_build"
4
4
 
5
5
  [project]
6
6
  name = "worktree-controller"
7
- version = "1.36.0"
7
+ version = "1.36.1"
8
8
  description = "Govern Git worktree budgets, authority, ownership, and lifecycle"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.12,<3.15"
@@ -1,3 +1,3 @@
1
1
  """Worktree lifecycle controller."""
2
2
 
3
- __version__ = "1.36.0"
3
+ __version__ = "1.36.1"
@@ -7,7 +7,7 @@ from dataclasses import replace
7
7
  from pathlib import Path
8
8
  from typing import Any
9
9
 
10
- from .controller import status
10
+ from .controller import compact_status
11
11
  from .git_backend import (
12
12
  _git,
13
13
  fetch_remote_branch,
@@ -354,8 +354,7 @@ def transition_canonical(
354
354
  }
355
355
  updated = replace(updated, history=(*updated.history[:-1], event))
356
356
  store.replace_record(updated)
357
- payload = status(repository_path)
358
- payload["command"] = "canonical-transition"
357
+ payload = compact_status(repository_path, command="canonical-transition", target=target)
359
358
  payload["decision"] = {
360
359
  "code": "CANONICAL_MAIN_REFRESHED" if refresh_main else "CANONICAL_TRANSITIONED",
361
360
  "allocation_id": updated.allocation_id,
@@ -202,14 +202,14 @@ def reconcile_typed_locked(repo: Path, store: MetadataStore, transaction: str, d
202
202
 
203
203
  def reconcile_typed(repo: Path, transaction: str, digest: str, *, dry_run: bool,
204
204
  expected_plan_id: str | None = None) -> dict:
205
- from .controller import status
205
+ from .controller import compact_status
206
206
  from .git_backend import inventory
207
207
 
208
208
  store = MetadataStore(inventory(repo).common_dir)
209
209
  with store.lock(exclusive=not dry_run):
210
210
  decision = reconcile_typed_locked(repo, store, transaction, digest, dry_run=dry_run,
211
211
  expected_plan_id=expected_plan_id)
212
- result = status(repo)
212
+ result = compact_status(repo, command="resource-recover")
213
213
  result.update(command="resource-recover", decision=decision)
214
214
  return result
215
215
 
@@ -348,7 +348,7 @@ def prepare(
348
348
  dry_run: bool,
349
349
  expected_plan_id: str | None = None,
350
350
  ) -> dict[str, Any]:
351
- from .controller import status
351
+ from .controller import compact_status
352
352
 
353
353
  store = MetadataStore(inventory(repo).common_dir)
354
354
  decision: dict[str, Any]
@@ -379,7 +379,7 @@ def prepare(
379
379
  }
380
380
  reference = e.write(directory, "record.json", document)
381
381
  decision.update(recovery_id=recovery_id, recovery_receipt=reference)
382
- result = status(repo)
382
+ result = compact_status(repo, command="resource-recover")
383
383
  result.update(command="resource-recover", decision=decision)
384
384
  return result
385
385
 
@@ -470,7 +470,7 @@ def rollout_check(
470
470
  repo: Path, *, receipt_path: Path | None = None, receipt_sha: str | None = None
471
471
  ) -> dict[str, Any]:
472
472
  """Read-only installation compatibility, never a transaction state transition."""
473
- from .controller import status
473
+ from .controller import compact_status
474
474
  from .transaction_scope import is_atomic_temp
475
475
 
476
476
  store = MetadataStore(inventory(repo).common_dir)
@@ -495,7 +495,7 @@ def rollout_check(
495
495
  "ROLLOUT_TRANSACTION_UNSUPPORTED", f"transaction recovery evidence is malformed: {exc}"
496
496
  )
497
497
  raise RolloutTransactionError(cause, path.stem, journal) from exc
498
- result = status(repo)
498
+ result = compact_status(repo, command="resource-recover")
499
499
  result.update(
500
500
  command="resource-recover",
501
501
  decision={
@@ -552,7 +552,7 @@ def reconcile_attempt(
552
552
  dry_run: bool,
553
553
  expected_plan_id: str | None = None,
554
554
  ) -> dict[str, Any]:
555
- from .controller import status
555
+ from .controller import compact_status
556
556
 
557
557
  store = MetadataStore(inventory(repo).common_dir)
558
558
  with store.lock(exclusive=not dry_run):
@@ -606,7 +606,7 @@ def reconcile_attempt(
606
606
  decision["reconciliation"] = e.write(
607
607
  path.parent, path.name, {**plan, "plan_id": plan_id, "timestamp": now_iso()}
608
608
  )
609
- result = status(repo)
609
+ result = compact_status(repo, command="resource-recover")
610
610
  result.update(command="resource-recover", decision=decision)
611
611
  return result
612
612
 
@@ -681,7 +681,7 @@ def _incomplete(
681
681
 
682
682
 
683
683
  def resume(repo: Path, *, recovery_path: Path, recovery_sha: str, dry_run: bool) -> dict[str, Any]:
684
- from .controller import status
684
+ from .controller import compact_status
685
685
  from .lifecycle import cleanup_typed_disposable
686
686
 
687
687
  store = MetadataStore(inventory(repo).common_dir)
@@ -806,7 +806,7 @@ def resume(repo: Path, *, recovery_path: Path, recovery_sha: str, dry_run: bool)
806
806
  )
807
807
  except Exception as exc:
808
808
  return _incomplete(repo, store, document, attempt_directory, attempt_id, underlying, exc)
809
- result = status(repo)
809
+ result = compact_status(repo, command="resource-recover")
810
810
  result.update(
811
811
  command="resource-recover",
812
812
  decision={
@@ -0,0 +1,475 @@
1
+ """Safe, fail-closed retention and pruning for terminal RELEASED cleanup evidence.
2
+
3
+ Typed and preserved disposable cleanups record pre/post hardlink topologies
4
+ (``cleanup-actions/<tx>/`` and ``completion-receipts/<tx>.json``) so an
5
+ interrupted cleanup can be verified and recovered. Once the owning allocation
6
+ has reached terminal ``RELEASED`` with an exact matching ``ReleaseReceipt``,
7
+ no live checkout or active lease/intent remains, and no retained transaction
8
+ journal or recovery record references that evidence, those multi-megabyte
9
+ topology artifacts are no longer required by any runtime or recovery path.
10
+
11
+ Pruning ALWAYS removes ``cleanup-actions/<id>/`` before removing
12
+ ``completion-receipts/<id>.json`` so ``cleanup_attempts.no_action_evidence``
13
+ never observes an unbound cleanup-actions directory.
14
+ """
15
+
16
+ from __future__ import annotations
17
+
18
+ import json
19
+ import os
20
+ import stat
21
+ import uuid
22
+ from contextlib import suppress
23
+ from dataclasses import dataclass
24
+ from datetime import UTC, datetime, timedelta
25
+ from pathlib import Path
26
+ from typing import Any
27
+
28
+ from .git_backend import inventory
29
+ from .models import ControllerError, MetadataSnapshot, RepositoryInventory
30
+ from .semantics import effective_intent_state
31
+ from .store import MetadataStore
32
+
33
+ PRUNABLE_CLEANUP_CONTRACTS = frozenset(
34
+ {
35
+ "typed-disposable-resource/v1",
36
+ "legacy-preserved-state-cleanup/v1",
37
+ "legacy-preserved-state-multiple-cleanup/v1",
38
+ }
39
+ )
40
+ TERMINAL_INTENT_STATES = frozenset({"RELEASED", "ABANDONED"})
41
+ DEFAULT_AUTO_KEEP_RECENT = 5
42
+ DEFAULT_AUTO_MAX_BYTES = 64 * 1024 * 1024
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class PrunableCleanupEntry:
47
+ receipt_id: str
48
+ allocation_id: str
49
+ contract: str
50
+ receipt_path: Path
51
+ receipt_bytes: int
52
+ action_dir: Path | None
53
+ action_files: int
54
+ action_bytes: int
55
+ timestamp: str
56
+
57
+ @property
58
+ def total_bytes(self) -> int:
59
+ return self.receipt_bytes + self.action_bytes
60
+
61
+
62
+ def _is_canonical_uuid(value: object) -> bool:
63
+ if not isinstance(value, str) or not value:
64
+ return False
65
+ try:
66
+ return str(uuid.UUID(value)) == value
67
+ except ValueError:
68
+ return False
69
+
70
+
71
+ def _parse_iso(value: object) -> datetime | None:
72
+ if not isinstance(value, str) or not value:
73
+ return None
74
+ try:
75
+ parsed = datetime.fromisoformat(value)
76
+ except ValueError:
77
+ return None
78
+ return parsed.astimezone(UTC) if parsed.tzinfo is not None else parsed.replace(tzinfo=UTC)
79
+
80
+
81
+ def _protected_receipt_ids(store: MetadataStore) -> set[str]:
82
+ """Collect every receipt/transaction id referenced by retained journals or recoveries."""
83
+ protected: set[str] = set()
84
+ if store.transactions_dir.is_dir():
85
+ for entry in store.transactions_dir.iterdir():
86
+ if entry.name.endswith(".json"):
87
+ protected.add(entry.stem)
88
+ if store.cleanup_recoveries_dir.is_dir():
89
+ for tx_dir in store.cleanup_recoveries_dir.iterdir():
90
+ if not tx_dir.is_dir() or tx_dir.is_symlink():
91
+ continue
92
+ protected.add(tx_dir.name)
93
+ for candidate in tx_dir.rglob("*.json"):
94
+ if candidate.is_symlink() or not candidate.is_file():
95
+ continue
96
+ try:
97
+ doc = json.loads(candidate.read_bytes())
98
+ except (OSError, UnicodeError, json.JSONDecodeError):
99
+ # Fail closed: unreadable recovery evidence protects its subtree.
100
+ protected.add(candidate.stem)
101
+ continue
102
+ if not isinstance(doc, dict):
103
+ continue
104
+ for key in ("completion_receipt_id", "original_transaction_id", "transaction_id"):
105
+ val = doc.get(key)
106
+ if isinstance(val, str) and val:
107
+ protected.add(val)
108
+ ref = doc.get("refusal_receipt")
109
+ if isinstance(ref, dict) and isinstance(ref.get("path"), str):
110
+ protected.add(Path(ref["path"]).stem)
111
+ return protected
112
+
113
+
114
+ def _non_terminal_intent_allocations(snapshot: MetadataSnapshot) -> set[str]:
115
+ active: set[str] = set()
116
+ for intent in snapshot.integration_intents.values():
117
+ if effective_intent_state(snapshot, intent) not in TERMINAL_INTENT_STATES:
118
+ if intent.allocation_id:
119
+ active.add(intent.allocation_id)
120
+ active.update(intent.source_allocations)
121
+ return active
122
+
123
+
124
+ def _measure_action_dir(action_dir: Path) -> tuple[int, int] | None:
125
+ """Measure regular files inside a cleanup-actions/<id> directory; return None if unsafe."""
126
+ try:
127
+ info = os.lstat(action_dir)
128
+ except FileNotFoundError:
129
+ return 0, 0
130
+ except OSError:
131
+ return None
132
+ if not stat.S_ISDIR(info.st_mode):
133
+ return None
134
+ files = 0
135
+ total = 0
136
+ try:
137
+ for entry in os.scandir(action_dir):
138
+ st = entry.stat(follow_symlinks=False)
139
+ if not stat.S_ISREG(st.st_mode):
140
+ return None
141
+ files += 1
142
+ total += st.st_size
143
+ except OSError:
144
+ return None
145
+ return files, total
146
+
147
+
148
+ def _remove_action_dir_safe(action_dir: Path) -> tuple[int, int]:
149
+ """Safely remove regular files in cleanup-actions/<id>/ and rmdir it."""
150
+ removed_files = 0
151
+ removed_bytes = 0
152
+ try:
153
+ info = os.lstat(action_dir)
154
+ except FileNotFoundError:
155
+ return 0, 0
156
+ if not stat.S_ISDIR(info.st_mode):
157
+ raise ControllerError(
158
+ "CLEANUP_RETENTION_UNSAFE", f"cleanup action entry is not a directory: {action_dir}"
159
+ )
160
+ entries = list(os.scandir(action_dir))
161
+ for entry in entries:
162
+ st = entry.stat(follow_symlinks=False)
163
+ if not stat.S_ISREG(st.st_mode):
164
+ raise ControllerError(
165
+ "CLEANUP_RETENTION_UNSAFE", f"unexpected non-regular cleanup file: {entry.path}"
166
+ )
167
+ for entry in entries:
168
+ st = entry.stat(follow_symlinks=False)
169
+ os.unlink(entry.path)
170
+ removed_files += 1
171
+ removed_bytes += st.st_size
172
+ os.rmdir(action_dir)
173
+ _fsync_dir(action_dir.parent)
174
+ return removed_files, removed_bytes
175
+
176
+
177
+ def _fsync_dir(directory: Path) -> None:
178
+ try:
179
+ fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY | os.O_CLOEXEC)
180
+ except OSError:
181
+ return
182
+ try:
183
+ os.fsync(fd)
184
+ finally:
185
+ os.close(fd)
186
+
187
+
188
+ def plan_terminal_cleanup_retention_locked(
189
+ repository: RepositoryInventory,
190
+ store: MetadataStore,
191
+ snapshot: MetadataSnapshot,
192
+ *,
193
+ keep_recent: int = 0,
194
+ older_than_days: float = 0.0,
195
+ max_total_bytes: int | None = None,
196
+ keep_allocations: frozenset[str] = frozenset(),
197
+ ) -> dict[str, Any]:
198
+ """Identify strictly proven terminal RELEASED cleanup evidence eligible for pruning."""
199
+ if keep_recent < 0 or older_than_days < 0:
200
+ raise ControllerError(
201
+ "INVALID_REQUEST", "keep_recent and older_than_days must be non-negative"
202
+ )
203
+ if max_total_bytes is not None and max_total_bytes < 0:
204
+ raise ControllerError("INVALID_REQUEST", "max_total_bytes must be non-negative")
205
+
206
+ protected_ids = _protected_receipt_ids(store)
207
+ active_intent_allocs = _non_terminal_intent_allocations(snapshot)
208
+ bound_allocs = set(snapshot.bindings.values())
209
+ leased_allocs = set(snapshot.writer_leases)
210
+ pub_alloc = snapshot.publication_lease.allocation_id if snapshot.publication_lease else None
211
+ live_worktree_paths = {str(item.path.resolve(strict=False)) for item in repository.worktrees}
212
+
213
+ release_receipts_by_alloc: dict[str, list[Any]] = {}
214
+ for rr in snapshot.release_receipts.values():
215
+ if rr.result == "RELEASED":
216
+ release_receipts_by_alloc.setdefault(rr.allocation_id, []).append(rr)
217
+
218
+ candidates: list[PrunableCleanupEntry] = []
219
+ skipped: dict[str, int] = {}
220
+ scanned_receipts = 0
221
+
222
+ def skip(reason: str) -> None:
223
+ skipped[reason] = skipped.get(reason, 0) + 1
224
+
225
+ if store.completion_receipts_dir.is_dir():
226
+ for entry in sorted(os.scandir(store.completion_receipts_dir), key=lambda e: e.name):
227
+ if not entry.name.endswith(".json") or entry.name.startswith("."):
228
+ continue
229
+ scanned_receipts += 1
230
+ path = Path(entry.path)
231
+ receipt_id = path.stem
232
+ try:
233
+ st = entry.stat(follow_symlinks=False)
234
+ except OSError:
235
+ skip("unreadable")
236
+ continue
237
+ if not stat.S_ISREG(st.st_mode):
238
+ skip("non_regular")
239
+ continue
240
+ if not _is_canonical_uuid(receipt_id):
241
+ skip("non_uuid")
242
+ continue
243
+ if receipt_id in protected_ids:
244
+ skip("referenced_by_transaction_or_recovery")
245
+ continue
246
+ try:
247
+ doc = json.loads(path.read_bytes())
248
+ except (OSError, UnicodeError, json.JSONDecodeError):
249
+ skip("unreadable")
250
+ continue
251
+ if not isinstance(doc, dict):
252
+ skip("invalid_document")
253
+ continue
254
+ contract = doc.get("contract")
255
+ if contract not in PRUNABLE_CLEANUP_CONTRACTS:
256
+ skip("non_prunable_contract")
257
+ continue
258
+ if doc.get("receipt_id") != receipt_id:
259
+ skip("receipt_id_mismatch")
260
+ continue
261
+ plan_obj = doc.get("plan") if isinstance(doc.get("plan"), dict) else {}
262
+ allocation_id = doc.get("allocation_id") or plan_obj.get("allocation_id")
263
+ if not _is_canonical_uuid(allocation_id):
264
+ skip("missing_allocation_id")
265
+ continue
266
+ assert isinstance(allocation_id, str)
267
+ if allocation_id in keep_allocations:
268
+ skip("explicitly_kept_allocation")
269
+ continue
270
+ record = snapshot.records.get(allocation_id)
271
+ if record is None or record.lifecycle != "RELEASED":
272
+ skip("allocation_not_released")
273
+ continue
274
+ if (
275
+ allocation_id in bound_allocs
276
+ or allocation_id in leased_allocs
277
+ or allocation_id == pub_alloc
278
+ or allocation_id in active_intent_allocs
279
+ ):
280
+ skip("allocation_still_referenced")
281
+ continue
282
+ matching_releases = [
283
+ rr
284
+ for rr in release_receipts_by_alloc.get(allocation_id, ())
285
+ if rr.released_record_version == record.record_version
286
+ ]
287
+ if len(matching_releases) != 1:
288
+ skip("missing_exact_release_receipt")
289
+ continue
290
+ target_path = plan_obj.get("target_path")
291
+ if isinstance(target_path, str) and target_path:
292
+ resolved_target = str(Path(target_path).resolve(strict=False))
293
+ if resolved_target in live_worktree_paths or os.path.lexists(target_path):
294
+ skip("target_still_present")
295
+ continue
296
+ action_dir = store.cleanup_actions_dir / receipt_id
297
+ action_info = _measure_action_dir(action_dir)
298
+ if action_info is None:
299
+ skip("unsafe_action_dir")
300
+ continue
301
+ action_files, action_bytes = action_info
302
+ timestamp = str(matching_releases[0].released_at or doc.get("created_at") or "")
303
+ candidates.append(
304
+ PrunableCleanupEntry(
305
+ receipt_id=receipt_id,
306
+ allocation_id=allocation_id,
307
+ contract=str(contract),
308
+ receipt_path=path,
309
+ receipt_bytes=st.st_size,
310
+ action_dir=action_dir if action_dir.exists() else None,
311
+ action_files=action_files,
312
+ action_bytes=action_bytes,
313
+ timestamp=timestamp,
314
+ )
315
+ )
316
+
317
+ # Sort newest-first so retention windows always preserve the freshest receipts.
318
+ candidates.sort(key=lambda item: (item.timestamp, item.receipt_id), reverse=True)
319
+ cutoff = datetime.now(UTC) - timedelta(days=older_than_days) if older_than_days > 0 else None
320
+
321
+ eligible: list[PrunableCleanupEntry] = []
322
+ kept: list[PrunableCleanupEntry] = []
323
+ kept_bytes = 0
324
+ for item in candidates:
325
+ if cutoff is not None:
326
+ ts = _parse_iso(item.timestamp)
327
+ if ts is None or ts > cutoff:
328
+ kept.append(item)
329
+ kept_bytes += item.total_bytes
330
+ continue
331
+ if len(kept) < keep_recent and (
332
+ max_total_bytes is None or kept_bytes + item.total_bytes <= max_total_bytes
333
+ ):
334
+ kept.append(item)
335
+ kept_bytes += item.total_bytes
336
+ continue
337
+ eligible.append(item)
338
+
339
+ return {
340
+ "scanned_receipts": scanned_receipts,
341
+ "protected_ids_count": len(protected_ids),
342
+ "skipped": dict(sorted(skipped.items())),
343
+ "kept": kept,
344
+ "kept_bytes": kept_bytes,
345
+ "eligible": eligible,
346
+ "eligible_receipts": len(eligible),
347
+ "eligible_action_dirs": sum(1 for item in eligible if item.action_dir is not None),
348
+ "eligible_action_files": sum(item.action_files for item in eligible),
349
+ "eligible_receipt_bytes": sum(item.receipt_bytes for item in eligible),
350
+ "eligible_action_bytes": sum(item.action_bytes for item in eligible),
351
+ "eligible_total_bytes": sum(item.total_bytes for item in eligible),
352
+ }
353
+
354
+
355
+ def apply_terminal_cleanup_plan_locked(plan: dict[str, Any]) -> dict[str, Any]:
356
+ """Execute a verified retention plan while the caller holds exclusive repo lock.
357
+
358
+ Removes ``cleanup-actions/<id>/`` strictly before ``completion-receipts/<id>.json``
359
+ so no orphaned cleanup-actions directory can ever exist.
360
+ """
361
+ pruned_receipts = 0
362
+ pruned_action_dirs = 0
363
+ pruned_action_files = 0
364
+ reclaimed_action_bytes = 0
365
+ reclaimed_receipt_bytes = 0
366
+ receipt_parent: Path | None = None
367
+
368
+ for item in plan["eligible"]:
369
+ assert isinstance(item, PrunableCleanupEntry)
370
+ if item.action_dir is not None and item.action_dir.exists():
371
+ files_removed, bytes_removed = _remove_action_dir_safe(item.action_dir)
372
+ pruned_action_dirs += 1
373
+ pruned_action_files += files_removed
374
+ reclaimed_action_bytes += bytes_removed
375
+ with suppress(FileNotFoundError):
376
+ os.unlink(item.receipt_path)
377
+ pruned_receipts += 1
378
+ reclaimed_receipt_bytes += item.receipt_bytes
379
+ receipt_parent = item.receipt_path.parent
380
+ if receipt_parent is not None:
381
+ _fsync_dir(receipt_parent)
382
+
383
+ return {
384
+ "pruned_receipts": pruned_receipts,
385
+ "pruned_action_dirs": pruned_action_dirs,
386
+ "pruned_action_files": pruned_action_files,
387
+ "reclaimed_action_bytes": reclaimed_action_bytes,
388
+ "reclaimed_receipt_bytes": reclaimed_receipt_bytes,
389
+ "bytes_reclaimed": reclaimed_action_bytes + reclaimed_receipt_bytes,
390
+ }
391
+
392
+
393
+ def auto_prune_terminal_cleanup_locked(
394
+ repository: RepositoryInventory,
395
+ store: MetadataStore,
396
+ snapshot: MetadataSnapshot,
397
+ *,
398
+ keep_allocations: frozenset[str] = frozenset(),
399
+ keep_recent: int | None = None,
400
+ max_total_bytes: int | None = None,
401
+ ) -> dict[str, Any]:
402
+ """Bound historical RELEASED cleanup bloat automatically under an already-held exclusive lock."""
403
+ if not store.completion_receipts_dir.is_dir():
404
+ return {"pruned_receipts": 0, "pruned_action_dirs": 0, "bytes_reclaimed": 0}
405
+ effective_keep_recent = DEFAULT_AUTO_KEEP_RECENT if keep_recent is None else keep_recent
406
+ effective_max_bytes = DEFAULT_AUTO_MAX_BYTES if max_total_bytes is None else max_total_bytes
407
+ plan = plan_terminal_cleanup_retention_locked(
408
+ repository,
409
+ store,
410
+ snapshot,
411
+ keep_recent=effective_keep_recent,
412
+ max_total_bytes=effective_max_bytes,
413
+ keep_allocations=keep_allocations,
414
+ )
415
+ if not plan["eligible"]:
416
+ return {"pruned_receipts": 0, "pruned_action_dirs": 0, "bytes_reclaimed": 0}
417
+ return apply_terminal_cleanup_plan_locked(plan)
418
+
419
+
420
+ def reconcile_cleanup_evidence(
421
+ repository_path: Path,
422
+ *,
423
+ apply: bool = False,
424
+ keep_recent: int = 0,
425
+ older_than_days: float = 0.0,
426
+ max_total_bytes: int | None = None,
427
+ ) -> dict[str, Any]:
428
+ """Dry-run plan or apply pruning of terminal RELEASED cleanup-actions & completion-receipts."""
429
+ from .controller import compact_status
430
+
431
+ repository = inventory(repository_path, observe_paths=frozenset())
432
+ store = MetadataStore(repository.common_dir)
433
+ with store.lock(exclusive=apply):
434
+ live_repo = inventory(repository.canonical_path, observe_paths=frozenset())
435
+ snapshot = store._load_unlocked()
436
+ plan = plan_terminal_cleanup_retention_locked(
437
+ live_repo,
438
+ store,
439
+ snapshot,
440
+ keep_recent=keep_recent,
441
+ older_than_days=older_than_days,
442
+ max_total_bytes=max_total_bytes,
443
+ )
444
+ applied = apply_terminal_cleanup_plan_locked(plan) if apply else None
445
+
446
+ payload = compact_status(repository.canonical_path, command="reconcile")
447
+ payload["decision"] = {
448
+ "code": "CLEANUP_EVIDENCE_PRUNED" if apply else "CLEANUP_EVIDENCE_PLAN",
449
+ "reason": (
450
+ "verified terminal RELEASED cleanup evidence pruned"
451
+ if apply
452
+ else "verified terminal RELEASED cleanup evidence plan (dry-run)"
453
+ ),
454
+ "apply": apply,
455
+ "dry_run": not apply,
456
+ "policy": {
457
+ "keep_recent": keep_recent,
458
+ "older_than_days": older_than_days,
459
+ "max_total_bytes": max_total_bytes,
460
+ "prunable_contracts": sorted(PRUNABLE_CLEANUP_CONTRACTS),
461
+ },
462
+ "scanned_receipts": plan["scanned_receipts"],
463
+ "protected_ids_count": plan["protected_ids_count"],
464
+ "skipped": plan["skipped"],
465
+ "kept_count": len(plan["kept"]),
466
+ "kept_bytes": plan["kept_bytes"],
467
+ "eligible_receipts": plan["eligible_receipts"],
468
+ "eligible_action_dirs": plan["eligible_action_dirs"],
469
+ "eligible_action_files": plan["eligible_action_files"],
470
+ "eligible_receipt_bytes": plan["eligible_receipt_bytes"],
471
+ "eligible_action_bytes": plan["eligible_action_bytes"],
472
+ "eligible_total_bytes": plan["eligible_total_bytes"],
473
+ **({"result": applied} if applied is not None else {}),
474
+ }
475
+ return payload