Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 73 Pull Requests 9 Actions Packages Projects Releases Wiki Activity

feat(recovery): stale worktree binding demotion and crash-orphan lease recovery (Closes #702)

Browse Source 
An unhandled daemon crash skips teardown: the durable reviewer lease
comment survives, the in-memory session lease dies, and the
auto-reconnected daemon inherits a stale GITEA_ACTIVE_WORKTREE from its
parent environment (PR #701 / branches/review-pr-654 incident).

AC2 — safe clear/re-bind of stale bindings:
- new stale_binding_recovery.py: classifies the active env binding
  (corroborated / unverified_inherited / provably_stale_missing_path /
  superseded_by_session_lease) and produces a fail-closed recovery plan;
  only provably stale bindings are clear-eligible
- gitea_resolve_task_capability and daemon boot run the sanctioned
  recovery (durable audit via session state); runtime context surfaces
  the classification read-only
- namespace_workspace_binding.resolve_namespace_workspace(verify_paths=…)
  demotes env-bound worktrees whose path no longer exists; mutation and
  runtime-context resolution always verify

AC3 — recoverable lease cleanup after unexpected exit:
- durable session-lease shadow (KIND_REVIEWER_SESSION_LEASE) written on
  sanctioned record/heartbeat, removed on sanctioned clear; a crash
  leaves provable orphan evidence (owner pid + session id)
- assess_crashed_session_lease_orphan derives tri-state
  owner_process_alive: only a dead recorded owner pid proves exit; PID
  liveness is never ownership proof
- diagnose/cleanup wrappers consume the shadow instead of passing
  owner_process_alive=None
- new classification orphaned_expired_superseded_head: an expired
  superseded-head lease with no terminal review stops being a permanent
  ambiguous/wait; post-expiry it unlocks fresh acquisition, and guarded
  cleanup becomes eligible only with owner-exit evidence + clean/absent
  worktree + controller authorization + confirmation. Pre-expiry
  behavior is unchanged (fail-closed wait, no steal).

Validation: tests/test_issue_702_stale_binding_lease_recovery.py (29
tests covering lost in-session leases, old-head leases, runtime/worktree
mismatch, managed reconnect, safe expiry); full suite 2665 passed,
6 skipped, 161 subtests.

Co-Authored-By: Claude Fable 5 <[email protected]>
This commit is contained in:
sysadmin
2026-07-13 14:35:15 -04:00
co-authored by Claude Fable 5
parent 237656702f
commit 889931d553
7 changed files with 1136 additions and 13 deletions
Download Patch File Download Diff File Expand all files Collapse all files
gitea_mcp_server.py
+116 -1
View File
@@ -195,6 +195,12 @@ RECONCILER_WORKTREE_ENV = "GITEA_RECONCILER_WORKTREE"
import namespace_workspace_binding as nwb # noqa: E402
import mcp_namespace_health # noqa: E402
import stale_binding_recovery # noqa: E402
# Worktree env bindings inherited from the parent environment at daemon boot
# (#702). A value that still equals its boot snapshot was never established by
# a sanctioned tool in this daemon's lifetime.
_BOOT_ENV_WORKTREE_BINDINGS = stale_binding_recovery.snapshot_boot_bindings()
def _preflight_in_test_mode() -> bool:
@@ -260,6 +266,71 @@ def _actual_profile_role() -> str:
)
def _assess_stale_active_binding(auto_recover: bool = False) -> dict:
"""Classify the GITEA_ACTIVE_WORKTREE binding; recover when provably stale (#702).
Runs during ``gitea_resolve_task_capability`` / runtime context. Clearing
is the sanctioned in-daemon mechanism and happens only for the two
provably-stale classes (missing path, superseded by a sanctioned session
lease); an uncorroborated boot-inherited binding is surfaced with the
managed-reconnect next action, never cleared silently.
"""
active_value = (os.environ.get(ACTIVE_WORKTREE_ENV) or "").strip() or None
try:
role = _actual_profile_role()
except Exception:
role = "author"
role_env_key = nwb.ROLE_WORKTREE_ENVS.get(role, AUTHOR_WORKTREE_ENV)
boot_value = (
(_BOOT_ENV_WORKTREE_BINDINGS.get("active_worktree") or "").strip() or None
)
classification = stale_binding_recovery.classify_active_worktree_binding(
active_value=active_value,
role_env_value=(os.environ.get(role_env_key) or "").strip() or None,
session_lease_worktree=_reviewer_session_worktree(),
boot_inherited=bool(active_value and boot_value == active_value),
path_exists=os.path.isdir(active_value) if active_value else None,
role_kind=role,
)
plan = stale_binding_recovery.plan_recovery(classification)
applied: dict = {"performed": False}
recovery_enabled = (
not _preflight_in_test_mode()
or os.environ.get("GITEA_FORCE_STALE_BINDING_RECOVERY") == "1"
)
if auto_recover and plan.get("clear_allowed") and recovery_enabled:
applied = stale_binding_recovery.apply_recovery(plan)
if applied.get("performed"):
try:
import mcp_session_state as mss
mss.save_state(
kind=mss.KIND_STALE_BINDING_RECOVERY,
payload={
"cleared_env": applied.get("cleared_env"),
"cleared_value": applied.get("cleared_value"),
"classification": applied.get("classification"),
"reasons": applied.get("reasons"),
},
)
except Exception:
pass
report = {
"classification": classification.get("classification"),
"active_worktree": classification.get("active_worktree"),
"boot_inherited": classification.get("boot_inherited", False),
"clear_eligible": bool(classification.get("clear_eligible")),
"recovery_action": plan.get("action"),
"recovery_performed": bool(applied.get("performed")),
"reasons": classification.get("reasons") or [],
}
if applied.get("performed"):
report["cleared_value"] = applied.get("cleared_value")
if plan.get("exact_next_action"):
report["exact_next_action"] = plan.get("exact_next_action")
return report
def _resolve_preflight_workspace_path(worktree_path: str | None = None) -> str:
"""Resolve the namespace-scoped workspace root inspected by pre-flight guards."""
role = _effective_workspace_role()
@@ -8052,6 +8123,13 @@ def gitea_diagnose_reviewer_pr_lease_handoff(
except Exception:
worktree_clean = None
# #702: derive owner-process evidence from the durable session-lease
# shadow left behind by a crashed daemon. Only a provably dead recorded
# owner pid yields False; PID liveness alone never proves ownership.
orphan_evidence = reviewer_pr_lease.assess_crashed_session_lease_orphan(
reviewer_pr_lease.load_session_lease_shadow(), lease=active
)
diagnosis = reviewer_pr_lease.diagnose_reviewer_pr_lease_handoff(
comments,
pr_number=pr_number,
@@ -8065,8 +8143,9 @@ def gitea_diagnose_reviewer_pr_lease_handoff(
formal_reviews=formal_reviews,
worktree_exists=worktree_exists,
worktree_clean=worktree_clean,
owner_process_alive=None, # PID never proves ownership; leave unset
owner_process_alive=orphan_evidence.get("owner_process_alive"),
)
diagnosis["crashed_session_lease_evidence"] = orphan_evidence
diagnosis["success"] = True
diagnosis["remote"] = remote
diagnosis["authenticated_user"] = username
@@ -8296,6 +8375,12 @@ def gitea_cleanup_obsolete_reviewer_comment_lease(
worktree_clean = None
session = reviewer_pr_lease.get_session_lease() or {}
# #702: when the caller supplies no owner evidence, consult the durable
# session-lease shadow; an explicitly passed value always wins.
if owner_process_alive is None:
owner_process_alive = reviewer_pr_lease.assess_crashed_session_lease_orphan(
reviewer_pr_lease.load_session_lease_shadow(), lease=lease
).get("owner_process_alive")
assessment = reviewer_pr_lease.assess_obsolete_reviewer_comment_lease_cleanup(
comments,
pr_number=pr_number,
@@ -10145,6 +10230,17 @@ def gitea_get_runtime_context(
PROJECT_ROOT),
}
# #702: read-only visibility into the inherited GITEA_ACTIVE_WORKTREE
# binding; recovery itself runs during capability resolution.
try:
stale_binding = _assess_stale_active_binding(auto_recover=False)
if stale_binding.get("classification") != (
stale_binding_recovery.CLASSIFICATION_UNBOUND
):
result["stale_binding_recovery"] = stale_binding
except Exception:
pass
parity = _current_master_parity()
result["master_parity"] = {
"in_parity": parity["in_parity"],
@@ -11790,6 +11886,14 @@ def gitea_resolve_task_capability(
record_mutation_authority(profile["profile_name"], username, remote if remote in REMOTES else None, task)
# #702: validate the inherited GITEA_ACTIVE_WORKTREE binding during
# capability resolution; provably-stale bindings are cleared by the
# sanctioned in-daemon mechanism with a durable audit record.
try:
stale_binding = _assess_stale_active_binding(auto_recover=True)
except Exception:
stale_binding = None
result = {
"requested_task": task,
"required_operation_permission": required_permission,
@@ -11810,6 +11914,10 @@ def gitea_resolve_task_capability(
"different_mcp_namespace_required": different_namespace_required,
"exact_safe_next_action": next_safe_action,
}
if stale_binding is not None and stale_binding.get("classification") != (
stale_binding_recovery.CLASSIFICATION_UNBOUND
):
result["stale_binding_recovery"] = stale_binding
if reason_msg:
result["reason"] = reason_msg
if task in ("review_pr", "merge_pr"):
@@ -12685,4 +12793,11 @@ if __name__ == "__main__":
# processes (e.g. review_pr.py) can detect and refuse profile
# side-channel overrides (#199).
_export_session_profile_lock()
# #702: an auto-reconnected daemon inherits GITEA_ACTIVE_WORKTREE from its
# parent environment. Validate it at boot and clear it only when provably
# stale (missing path); anything less certain is surfaced, not cleared.
try:
_assess_stale_active_binding(auto_recover=True)
except Exception:
pass
mcp.run(transport="stdio")