fix: conflict-fix lease lifecycle chain termination and TTL handling (Closes #842 )

2026-07-23 03:21:07 -04:00
55 changed files with 216 additions and 17920 deletions
@@ -53,8 +53,6 @@ OUTCOME_CANDIDATE_SET_DRIFT = "candidate_set_drift"
 SKIP_CLAIMED_BY_OTHER_SESSION = "claimed_by_other_session"
 # #776: controller-supplied pre-rank exclusion.
 SKIP_EXCLUDED_BY_CONTROLLER = "excluded_by_controller"
 # #844: epic / child-only implementation container (pre-rank).
 SKIP_EPIC_OR_CHILD_ONLY_CONTAINER = "epic_or_child_only_container"
 # Ownership verdicts for a live claim on a candidate (#765).
 OWNERSHIP_OWN = "own"
@@ -132,39 +130,6 @@ ROLE_ACTIONS: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = {
 }
 # Body phrases that prove an issue is an implementation container, not a
 # unit of direct author work (#844). Matched case-insensitively against the
 # issue body. Title alone is never sufficient (ordinary issues may mention
 # "epic" incidentally).
 _CHILD_ONLY_BODY_MARKERS: tuple[str, ...] = (
    "implementation is delivered via child issues only",
    "implementation is delivered through child issues only",
    "implementation is delivered via child issues",
    "implementation is delivered through child issues",
    "do not implement product features in this epic",
    "do not implement product features in this epic issue itself",
    "no product feature implementation is claimed complete solely on this epic",
    "implementable child issues remain independently eligible",
    "owns the product roadmap and linkage",
    "this epic owns the product roadmap",
    "coordination container",
    "child-only container",
    "implementation is delegated to child",
 )
 # Explicit epic / umbrella labels (structured evidence preferred over title).
 _EPIC_LABELS: frozenset[str] = frozenset(
    {
        "type:epic",
        "epic",
        "kind:epic",
        "scope:epic",
        "type:umbrella",
        "umbrella",
    }
 )
@dataclass
 class WorkCandidate:
    """One assignable Gitea issue or PR presented to the allocator."""
@@ -174,7 +139,6 @@ class WorkCandidate:
    state: str = "open"
    labels: tuple[str, ...] = ()
    title: str = ""
    body: str = ""
    priority: int = 0
    head_sha: str | None = None
    # Routing signals (callers derive from Gitea / review feedback).
@@ -194,7 +158,6 @@ class WorkCandidate:
        self.labels = tuple(
            str(x).strip().lower() for x in (self.labels or ()) if str(x).strip()
        )
        self.body = str(self.body or "")
        if self.kind not in WORK_KINDS:
            raise InvalidWorkKindError(
                f"candidate kind '{self.kind}' is not assignable; only "
@@ -208,7 +171,6 @@ class WorkCandidate:
            "state": self.state,
            "labels": list(self.labels),
            "title": self.title,
            "body": self.body,
            "priority": self.priority,
            "head_sha": self.head_sha,
            "request_changes_current_head": self.request_changes_current_head,
@@ -222,51 +184,6 @@ class WorkCandidate:
        }
 def classify_epic_or_child_only_container(
    c: WorkCandidate,
 ) -> tuple[bool, str | None]:
    """Return whether *c* is an epic / child-only implementation container (#844).
    Exclusion uses structured evidence first (labels, body scope language).
    A bare title containing the word "epic" is **not** enough — ordinary
    implementable issues may mention epics incidentally. A title that is
    explicitly prefixed ``Epic:`` only counts when the body also proves
    child-only / no-direct-implementation scope (or an epic label is present).
    PRs are never classified as containers here (they already have a head).
    """
    if c.kind != "issue":
        return False, None
    labels = set(c.labels)
    epic_label = sorted(labels & _EPIC_LABELS)
    body_l = (c.body or "").lower()
    title = (c.title or "").strip()
    title_l = title.lower()
    body_hits = [m for m in _CHILD_ONLY_BODY_MARKERS if m in body_l]
    title_epic_prefix = title_l.startswith("epic:") or title_l.startswith("epic ")
    if epic_label:
        detail = f"label={epic_label[0]}"
        if body_hits:
            detail = f"{detail}; body_marker={body_hits[0]!r}"
        return True, detail
    if body_hits:
        # Body proves child-only / umbrella scope. Title "Epic:" is corroborating
        # but not required — containers without the word still exclude.
        detail = f"body_marker={body_hits[0]!r}"
        if title_epic_prefix:
            detail = f"title_epic_prefix; {detail}"
        return True, detail
    # Title-only "Epic:" without body scope evidence is insufficient (#844 AC:
    # eligibility does not rely solely on the word "Epic" in a title).
    # Similarly, incidental "epic" mid-title without markers stays eligible.
    return False, None
@dataclass
 class SkipRecord:
    kind: str
@@ -933,8 +850,7 @@ def allocate_next_work(
    ownership_defects: list[dict[str, Any]] = []
    controller_excluded: list[dict[str, Any]] = []
-    # #776 AC2 + #844: remove excluded numbers *and* epic/child-only containers
+    # #776 AC2: remove excluded numbers *before* ranking / selection / lease.
    # *before* ranking / selection / lease so they never receive assignments.
    rankable: list[WorkCandidate] = []
    for c in candidates:
        if int(c.number) in exclude_set:
@@ -1013,23 +929,6 @@ def allocate_next_work(
                    },
                }
            continue
        # #844: epics / child-only containers are never direct implement targets.
        is_container, container_detail = classify_epic_or_child_only_container(c)
        if is_container:
            detail = container_detail or "epic or child-only container"
            reason = (
                f"{c.kind}#{c.number} {SKIP_EPIC_OR_CHILD_ONLY_CONTAINER}: "
                f"{detail}; implementation is delegated to child issues"
            )
            skipped.append(
                SkipRecord(
                    c.kind,
                    c.number,
                    reason,
                    SKIP_EPIC_OR_CHILD_ONLY_CONTAINER,
                )
            )
            continue
        rankable.append(c)
    ordered = sort_candidates(rankable)
@@ -1216,12 +1115,6 @@ def allocate_next_work(
            "reasons": [
                "dry-run only (apply=false); no assignment/lease created — "
                "call again with apply=true to reserve via control-plane DB"
                + (
                    "; after apply, the required-role worker consumes via "
                    "gitea_adopt_workflow_lease (#843)"
                    if mode == ALLOCATION_MODE_CROSS_ROLE and expected_role != role_norm
                    else ""
                )
            ],
            "skipped": [s.as_dict() for s in skipped],
            "terminal_pr": terminal_pr,
@@ -1253,9 +1146,6 @@ def allocate_next_work(
    # Atomic reserve via #613 substrate.
    ttl = lease_ttl_seconds if lease_ttl_seconds is not None else None
    try:
        cross_role_handoff = (
            mode == ALLOCATION_MODE_CROSS_ROLE and lease_role != role_norm
        )
        kwargs: dict[str, Any] = {
            "session_id": session_id,
            "role": lease_role,
@@ -1267,8 +1157,7 @@ def allocate_next_work(
            "expected_head_sha": selected.head_sha,
            "allowed_actions": allowed,
            "forbidden_actions": forbidden,
-            # #843: mark cross-role allocations as awaiting independent consume
+            "phase": "allocated",
            "phase": "awaiting_handoff" if cross_role_handoff else "allocated",
        }
        if ttl is not None:
            kwargs["lease_ttl_seconds"] = int(ttl)
@@ -1348,52 +1237,7 @@ def allocate_next_work(
        "lease_role": lease_role,
        "source": "control_plane_db.assign_and_lease",
    }
-    consume_allocation = None
+    return {
    if cross_role_handoff and result.lease_id:
        # Durable handoff marker so independent required-role workers can
        # consume without sharing the controller session (#843).
        handoff_prov = {
            "cross_role_handoff": True,
            "handoff_status": "pending",
            "allocating_session_id": session_id,
            "allocating_role": role_norm,
            "required_role": expected_role,
            "required_profile": selection["required_profile"],
            "required_namespace": selection["required_namespace"],
            "assignment_id": result.assignment_id,
            "lease_id": result.lease_id,
            "allocation_mode": mode,
            "adopted_by_session_id": None,
        }
        try:
            db.attach_lease_provenance(result.lease_id, handoff_prov)
        except ControlPlaneError:
            # Still return assignment evidence; consume path may be unavailable
            handoff_prov["attach_failed"] = True
        consume_allocation = {
            "tool": "gitea_adopt_workflow_lease",
            "lease_id": result.lease_id,
            "assignment_id": result.assignment_id,
            "required_role": expected_role,
            "required_profile": selection["required_profile"],
            "required_namespace": selection["required_namespace"],
            "handoff_status": "pending",
            "controller_session_required": False,
            "instructions": (
                f"From an independent {expected_role} session "
                f"({selection['required_namespace']} / "
                f"{selection['required_profile']}), call "
                f"gitea_adopt_workflow_lease(lease_id={result.lease_id!r}) "
                "to consume this controller allocation. The allocating "
                "controller process does not need to remain alive. Wrong-role "
                "and second-adoption attempts fail closed."
            ),
        }
        lease_proof["cross_role_handoff"] = True
        lease_proof["handoff_status"] = "pending"
        lease_proof["consume_tool"] = "gitea_adopt_workflow_lease"
    out = {
        "success": True,
        "outcome": OUTCOME_ASSIGNED,
        "apply": True,
@@ -1427,17 +1271,8 @@ def allocate_next_work(
            "lease_role": lease_role,
            "lease_proof": lease_proof,
            "selection_policy": SELECTION_POLICY,
            "cross_role_handoff": bool(cross_role_handoff),
        },
-        "next_valid_command": (
+        "next_valid_command": _next_command(lease_role, selected),
            (
                f"consume lease {result.lease_id} via gitea_adopt_workflow_lease "
                f"as {expected_role}, then "
            )
            + _next_command(lease_role, selected)
            if cross_role_handoff
            else _next_command(lease_role, selected)
        ),
        "substrate": "control_plane_db",
        "file_lock_only": False,
        "comment_lease_only": False,
@@ -1452,14 +1287,9 @@ def allocate_next_work(
        "downstream_note": (
            "#612 incident bridge remains downstream of #600; "
            "allocator never assigns raw monitoring incidents; "
-            "controller routes only under cross_role (#840); "
+            "controller routes only under cross_role (#840)"
            "cross-role assignments are consumable by independent "
            "required-role workers via gitea_adopt_workflow_lease (#843)"
        ),
    }
    if consume_allocation is not None:
        out["consume_allocation"] = consume_allocation
    return out
 def _next_command(role: str, c: WorkCandidate) -> str:
@@ -1511,7 +1341,6 @@ def candidate_from_dict(data: dict[str, Any]) -> WorkCandidate:
        state=str(data.get("state") or "open"),
        labels=tuple(data.get("labels") or ()),
        title=str(data.get("title") or ""),
        body=str(data.get("body") or ""),
        priority=priority,
        head_sha=data.get("head_sha"),
        request_changes_current_head=bool(data.get("request_changes_current_head")),
@@ -525,90 +525,6 @@ def assess_ownership_record_activity(record: dict[str, Any]) -> dict[str, Any]:
    }
 # Reviewer-lease reclaim is only reachable from a non-live (expired/stale) lease.
 _RECLAIMABLE_REVIEWER_STATUSES = _EXPIRED_STATUSES | _STALE_STATUSES
 def is_active_ownership_status(status: str | None) -> bool:
    """True when *status* denotes live/active ownership of a branch (#855).
    Used to decide whether a *competing* active claimant still uses a branch
    when weighing an expired reviewer lease for reclaim. Expired, stale,
    released, and terminal statuses are not active.
    """
    return _norm_str(status).lower() in _ACTIVE_OWNERSHIP_STATUSES
 def assess_expired_reviewer_lease_reclaim(
    *,
    role: str,
    status: str,
    pr_merged: bool | None,
    owner_pid_alive: bool | None,
    competing_active_claimant: bool | None,
 ) -> dict[str, Any]:
    """Decide, explicitly and fail-closed, whether an expired reviewer lease
    may stop protecting an already-merged branch (#855 AC4).
    An expired reviewer lease should not protect a merged branch forever once
    its work is done and no live claimant remains. Reclaim is permitted only
    when **every** condition below is provably satisfied; any unknown
    (``None``) or contrary value keeps the lease protective:
    - the lease is a ``reviewer`` lease (author/merger/controller/reconciler
      leases are out of scope and always keep protecting);
    - its status is expired or stale (never an active/live lease);
    - the PR is proven merged (``pr_merged is True``);
    - the lease owner process is proven dead (``owner_pid_alive is False``);
    - no competing active claimant uses the branch
      (``competing_active_claimant is False``).
    Returns a decision dict with ``reclaim_allowed`` and, when refused, the
    fail-closed ``reasons``. The reasons never contain secrets — only the
    role, the status, and which condition was unproven.
    """
    reasons: list[str] = []
    normalized_role = _norm_str(role).lower()
    normalized_status = _norm_str(status).lower()
    if normalized_role != "reviewer":
        reasons.append(
            f"lease role '{normalized_role or 'unknown'}' is not a reviewer "
            "lease; expired-reviewer reclaim does not apply"
        )
    if normalized_status not in _RECLAIMABLE_REVIEWER_STATUSES:
        reasons.append(
            f"lease status '{normalized_status or 'unknown'}' is not expired "
            "or stale; only a non-live reviewer lease may be reclaimed"
        )
    if pr_merged is not True:
        reasons.append(
            "PR merged state is not proven true; reclaim requires an "
            "already-merged PR (fail closed)"
        )
    if owner_pid_alive is not False:
        reasons.append(
            "lease owner process liveness is not proven dead; a live owner "
            "still protects the branch (fail closed)"
        )
    if competing_active_claimant is not False:
        reasons.append(
            "a competing active claimant may still use the branch; reclaim "
            "requires no other active ownership (fail closed)"
        )
    allowed = not reasons
    return {
        "reclaim_allowed": allowed,
        "role": normalized_role,
        "status": normalized_status,
        "decision": (
            "reclaim_expired_reviewer_lease" if allowed else "keep_protecting"
        ),
        "reasons": [] if allowed else reasons,
    }
 def assess_active_branch_ownership(
    *,
    remote: str,
@@ -46,17 +46,6 @@ _FIELD_RE = re.compile(
 )
 def is_known_cth_type(value: str | None) -> bool:
    """True when *value* is a declared member of the :data:`CTH_TYPES` contract.
    ``CTH_TYPES`` is the single authority for what a CTH type may be. The
    heading a comment carries is free text, so a *read* path that turns a parsed
    type into something durable — a serialized field, a routing decision — must
    check membership here rather than trust the parse or keep a list of its own.
    """
    return (value or "").strip() in CTH_TYPES
 def format_cth_body(
    *,
    cth_type: str,
@@ -71,7 +60,7 @@ def format_cth_body(
 ) -> str:
    """Render a canonical CTH comment body."""
    normalized_type = (cth_type or "").strip()
-    if not is_known_cth_type(normalized_type):
+    if normalized_type not in CTH_TYPES:
        raise ValueError(
            f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}"
        )
@@ -112,12 +101,6 @@ def parse_cth_comment(body: str) -> dict[str, Any] | None:
        fields[key] = match.group(2).strip()
    return {
        "cth_type": cth_type,
        # The heading capture is unconstrained free text, so the parse states
        # whether it satisfies the CTH_TYPES contract instead of leaving every
        # reader to decide (or forget). Parsing stays total — an unknown type is
        # still parsed and reported, never raised on — but a reader that turns
        # the type into a durable value can now tell the two apart.
        "cth_type_known": is_known_cth_type(cth_type),
        "fields": fields,
        "raw_body": text,
    }
@@ -136,7 +119,7 @@ def assess_cth_comment(body: str) -> dict[str, Any]:
        }
    cth_type = parsed.get("cth_type") or ""
-    if not is_known_cth_type(cth_type):
+    if cth_type not in CTH_TYPES:
        reasons.append(
            f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}"
        )
@@ -599,35 +599,6 @@ class ControlPlaneDB:
                (_ts(), session_id),
            )
    def list_sessions(
        self,
        *,
        statuses: Sequence[str] | None = None,
        limit: int = 500,
    ) -> list[dict[str, Any]]:
        """List session rows for restart / impact analysis (#658).
        Read-only. Sessions are the process-level unit an MCP restart
        disrupts, so the restart coordinator inventories them to compute blast
        radius. Optional ``statuses`` filter (e.g. ``('active',)``) narrows to
        live rows. Never returns secrets — only operational metadata.
        """
        clauses: list[str] = []
        params: list[Any] = []
        if statuses:
            placeholders = ", ".join("?" for _ in statuses)
            clauses.append(f"status IN ({placeholders})")
            params.extend(statuses)
        where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
        sql = (
            f"SELECT * FROM sessions {where} "
            "ORDER BY last_heartbeat_at DESC LIMIT ?"
        )
        params.append(max(1, int(limit)))
        with self._tx(immediate=False) as conn:
            rows = conn.execute(sql, params).fetchall()
            return [dict(r) for r in rows]
    # ── work items ────────────────────────────────────────────────────────
    def upsert_work_item(
@@ -1666,13 +1637,11 @@ class ControlPlaneDB:
        provenance: dict[str, Any] | None = None,
        lease_ttl_seconds: int = DEFAULT_LEASE_TTL_SECONDS,
    ) -> dict[str, Any]:
-        """Transfer or refresh a lease with provenance (#601 / #843).
+        """Transfer or refresh a lease with provenance (#601).
        * Same owner + active → refresh (owner-resume).
        * Cross-role handoff pending + matching required role → atomic consume
          (even while the allocating controller session still "owns" the lease).
        * Expired/abandoned/released → create new assignment+lease with provenance.
-        * Active foreign (non-handoff) → raise ForeignLeaseError (never silent steal).
+        * Active foreign → raise ForeignLeaseError (never silent steal).
        """
        now = _utc_now()
        now_s = _ts(now)
@@ -1708,35 +1677,7 @@ class ControlPlaneDB:
                status = "expired"
            owner = lease["session_id"]
-            # Parse durable provenance for cross-role handoff consume (#843).
+            if status == "active" and owner != adopter_session_id:
            lease_prov: dict[str, Any] = {}
            if "provenance_json" in lease.keys() and lease["provenance_json"]:
                try:
                    loaded = json.loads(lease["provenance_json"])
                    if isinstance(loaded, dict):
                        lease_prov = loaded
                except (TypeError, json.JSONDecodeError):
                    lease_prov = {}
            handoff_pending = bool(lease_prov.get("cross_role_handoff")) and (
                str(lease_prov.get("handoff_status") or "pending").strip().lower()
                == "pending"
            )
            already_adopted = bool(
                (lease["adopted_by_session_id"] if "adopted_by_session_id" in lease.keys() else None)
                or lease_prov.get("adopted_by_session_id")
            )
            required_role = str(
                lease_prov.get("required_role") or lease["role"] or ""
            ).strip().lower()
            adopter_role = (role or "").strip().lower()
            cross_role_consume = (
                handoff_pending
                and not already_adopted
                and status == "active"
                and owner != adopter_session_id
            )
            if status == "active" and owner != adopter_session_id and not cross_role_consume:
                raise ForeignLeaseError(
                    f"cannot adopt active foreign lease {lease_id} owned by {owner}"
                )
@@ -1820,142 +1761,6 @@ class ControlPlaneDB:
                    "reasons": ["owner-resume: refreshed lease with provenance"],
                }
            # #843: controller→required-role handoff consume (atomic, same lease_id)
            if cross_role_consume:
                if not required_role:
                    raise ControlPlaneError(
                        f"cross-role handoff lease {lease_id} missing required_role"
                    )
                if adopter_role != required_role:
                    raise ForeignLeaseError(
                        f"wrong role for cross-role handoff consume: "
                        f"required={required_role} adopter={adopter_role or 'none'} "
                        f"(fail closed)"
                    )
                # CAS: only transfer if still owned by allocating session and unadopted
                cols = self._lease_columns(conn)
                adopted_col_null = (
                    "(adopted_by_session_id IS NULL OR adopted_by_session_id = '')"
                    if "adopted_by_session_id" in cols
                    else "1=1"
                )
                cas = conn.execute(
                    f"""
                    UPDATE leases
                    SET session_id = ?,
                        heartbeat_at = ?,
                        expires_at = ?,
                        phase = ?,
                        role = ?
                    WHERE lease_id = ?
                      AND status = 'active'
                      AND session_id = ?
                      AND {adopted_col_null}
                    """,
                    (
                        adopter_session_id,
                        now_s,
                        expires,
                        "adopted",
                        required_role,
                        lease_id,
                        owner,
                    ),
                )
                if cas.rowcount != 1:
                    raise ForeignLeaseError(
                        f"cross-role handoff consume lost race for lease {lease_id} "
                        "(already adopted or no longer pending; fail closed)"
                    )
                if "adopted_from_session_id" in cols:
                    conn.execute(
                        """
                        UPDATE leases
                        SET adopted_from_session_id = ?, adopted_by_session_id = ?
                        WHERE lease_id = ?
                        """,
                        (owner, adopter_session_id, lease_id),
                    )
                if "worktree_path" in cols and worktree_path:
                    conn.execute(
                        "UPDATE leases SET worktree_path = ? WHERE lease_id = ?",
                        (worktree_path, lease_id),
                    )
                if "owner_pid" in cols and owner_pid is not None:
                    conn.execute(
                        "UPDATE leases SET owner_pid = ? WHERE lease_id = ?",
                        (owner_pid, lease_id),
                    )
                if "expected_head_sha" in cols and expected_head_sha:
                    conn.execute(
                        "UPDATE leases SET expected_head_sha = ? WHERE lease_id = ?",
                        (expected_head_sha, lease_id),
                    )
                # Merge handoff provenance + caller provenance
                merged = dict(lease_prov)
                merged.update(provenance or {})
                merged["cross_role_handoff"] = True
                merged["handoff_status"] = "adopted"
                merged["adopted_from_session_id"] = owner
                merged["adopted_by_session_id"] = adopter_session_id
                merged["required_role"] = required_role
                if "provenance_json" in cols:
                    conn.execute(
                        "UPDATE leases SET provenance_json = ? WHERE lease_id = ?",
                        (json.dumps(merged), lease_id),
                    )
                # Transfer active assignment ownership atomically
                asn_cas = conn.execute(
                    """
                    UPDATE assignments
                    SET session_id = ?, role = ?
                    WHERE lease_id = ? AND status = 'active' AND session_id = ?
                    """,
                    (adopter_session_id, required_role, lease_id, owner),
                )
                if asn_cas.rowcount < 1:
                    # Fail closed: assignment must move with the lease
                    raise ControlPlaneError(
                        f"cross-role handoff: no active assignment for lease {lease_id} "
                        f"owned by {owner}"
                    )
                lease2 = conn.execute(
                    "SELECT * FROM leases WHERE lease_id = ?", (lease_id,)
                ).fetchone()
                asn = conn.execute(
                    """
                    SELECT * FROM assignments
                    WHERE lease_id = ? AND status = 'active'
                    ORDER BY created_at DESC LIMIT 1
                    """,
                    (lease_id,),
                ).fetchone()
                conn.execute(
                    """
                    INSERT INTO events(work_item_id, event_type, message, created_at)
                    VALUES (?, 'lease_adopted', ?, ?)
                    """,
                    (
                        lease["work_item_id"],
                        f"cross-role handoff: {adopter_session_id} consumed "
                        f"{lease_id} from {owner} as {required_role}",
                        now_s,
                    ),
                )
                return {
                    "outcome": "adopted_cross_role_handoff",
                    "lease": dict(lease2) if lease2 else dict(lease),
                    "assignment": dict(asn) if asn else None,
                    "reasons": [
                        "cross-role handoff: independent required-role worker consumed "
                        "controller allocation without abandonment"
                    ],
                    "adopted_by_session_id": adopter_session_id,
                    "adopted_from_session_id": owner,
                    "required_role": required_role,
                    "handoff_status": "adopted",
                }
            # Non-active: create new lease + assignment (transfer)
            new_lease_id = f"lease-{uuid.uuid4().hex[:16]}"
            new_asn_id = f"asn-{uuid.uuid4().hex[:16]}"
@@ -1,223 +0,0 @@
 # ADR: MCP restart governance and authorization policy
 - **Status:** Accepted (policy effective immediately for LLM and operator sessions; enforcement tooling may lag)
 - **Date:** 2026-07-23
 - **Tracking issue:** [#656](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/656)
 - **Policy version:** `restart-governance/v1`
 - **Related:**
  - Umbrella: [#655](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/655) — governed MCP restart coordination and zero-disruption recovery
  - Vision: [#652](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/652) — MCP Control Plane Web Console product vision (§A system health and process control)
  - Roadmap: [#653](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/653) — Control Plane Web Console phased delivery (Phase 2 restart controls)
  - Contamination guard: [#630](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/630) — blocks manual process-kill recovery
  - Console restart UX: [#642](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/642) — sanctioned restart and graceful reload
  - Existing restart / reconnect paths to inventory: [#591](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/591) — auto-restart on master advance (closed); [#584](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/584) — host auto-reconnect on transport flap
  - Stable-control runtime split: `docs/architecture/mcp-stable-control-runtime-policy-adr.md` (#615)
  - Client-namespace health: `docs/mcp-namespace-health.md` (#543)
  - Reconnect-only EOF recovery: `docs/mcp-namespace-eof-recovery.md`
 ## 1. Context
 The Gitea MCP server is the **control plane** for real issue and PR mutations
 (create, comment, lock, review, merge, reconcile). The same process serves every
 role namespace (`gitea-author`, `gitea-reviewer`, `gitea-merger`,
 `gitea-reconciler`, `gitea-controller`) and holds the in-memory capability-gate
 code loaded at startup.
 Restarting that process is destructive to concurrent work:
 - It resets every session's identity, preflight, and capability-lease binding.
 - It can interrupt a mutation mid-critical-section (a lock acquire, a review
  submit, a merge), leaving durable state half-written.
 - Relaunching from the wrong checkout or worktree silently changes which code
  the control plane runs, defeating master-parity gates (#420 / #615).
 Today there is **no durable written policy** stating who may restart MCP, under
 what conditions, that restart is a last resort, and how controller approval,
 automated safety gates, and break-glass interact. Operators and LLM sessions
 therefore invent restart behavior ad hoc, which makes concurrent multi-role work
 unsafe. #630 and #642 need this policy as their backbone.
 This ADR defines that policy. It does **not** implement coordinator code or HA
 multi-instance restart (those are later children of #655).
 ## 2. Decision
 ### 2.1 v1 decision (recorded)
 **Restart authority in v1 is `controller approval + automated safety gates`.**
 A restart of the stable control runtime is authorized only when **both** hold:
 1. A **controller** role explicitly approves the restart, recording an audit
   entry (who, why, scope, affected sessions), **and**
 2. The **automated safety gates** pass: a completed drain acknowledgement (no
   affected session is mid-critical-section) or a declared break-glass incident
   (§2.5).
 Quorum among multiple controllers is **not** required day-one. It is deferred
 unless a later investigation (tracked under #653) proves single-controller
 approval is insufficient. This ADR records the v1 decision so enforcement code
 (#630) has a fixed target; changing it requires a superseding ADR.
 ### 2.2 Restart is a last resort — the recovery ladder
 Restart is the **last** rung. Before any restart, exhaust the narrower
 recoveries, in order:
 1. **Reconnect** the IDE/client MCP namespace (transport EOF, `client is
   closing: EOF`, transient `#584` flap). No process change. See
   `docs/mcp-namespace-eof-recovery.md`.
 2. **Refresh / rebind** the session workspace: re-run `gitea_whoami`,
   `gitea_resolve_task_capability`, and pass an explicit validated
   `worktree_path`. Fixes stale session context without touching the process.
 3. **Scoped restart** of a single misbehaving namespace/service (where the
   deployment supports per-service restart) rather than the whole control plane.
 4. **Full restart** of the stable control runtime process — operator-owned,
   controller-approved, drained.
 5. **Host / infrastructure restart** — the broadest action; same authorization
   as a full restart plus infrastructure ownership.
 A session **must** try rungs 1–2 and record why they were insufficient before
 requesting a restart at rung 3 or above. Skipping straight to restart is a
 policy violation.
 ### 2.3 Authorization matrix
 | Role | Reconnect (1) | Refresh/rebind (2) | Scoped restart (3) | Full restart (4) | Host restart (5) |
 |---|---|---|---|---|---|
 | **author** | self | self | request only | **forbidden** | forbidden |
 | **reviewer** | self | self | request only | **forbidden** | forbidden |
 | **merger** | self | self | request only | **forbidden** | forbidden |
 | **reconciler** | self | self | request only | **forbidden** | forbidden |
 | **controller** | self | self | **approve** (+gates) | **approve** (+gates) | request to operator |
 | **operator** | self | self | execute (controller-approved) | execute (controller-approved) | execute (controller-approved) |
 | **admin** | self | self | execute | execute | execute (break-glass) |
 Legend: *self* = may perform for its own client session; *request only* = may
 raise a restart request but not authorize or execute it; *approve* = may
 authorize under §2.1 gates; *execute* = may perform the process action after the
 authorization is recorded.
 Key invariants:
 - **No LLM worker role (author/reviewer/merger/reconciler) may perform or
  authorize a full or host restart.** They may only reconnect/rebind their own
  client and file a restart request.
 - **Controller approval authorizes; operator/admin executes.** The approving
  controller and the executing operator may be the same human, but both the
  approval and the execution are audited.
 - Privileged process actions (full restart, host restart) are reserved to
  **operator/admin**, never to an automated worker.
 ### 2.4 Approved conditions
 A restart at rung 3+ is approved only under one of these recorded conditions:
 - **No affected sessions:** the control plane has no live session that would be
  interrupted (verified, not assumed).
 - **Full drain acknowledged:** every affected session has drained
  (no open critical section — no held mutation lease mid-write) and the drain is
  acknowledged in the audit record.
 - **Controller + gates:** controller approval plus passing automated safety
  gates (§2.1), the standard v1 path.
 - **Quorum:** not required in v1; reserved for a future superseding ADR.
 - **Break-glass:** an incident-backed emergency exception (§2.5).
 Restart **never** bypasses mutation gates mid-critical-section. Drain before
 restart is mandatory except under break-glass with a declared incident.
 ### 2.5 Break-glass
 Break-glass is a **separate, narrower** authorization path for emergencies where
 the normal drain-and-approve path cannot complete (e.g. the control plane is
 wedged and cannot drain).
 Break-glass conditions:
 - A declared incident record exists (id, timestamp, declarer) **before** the
  action.
 - The action is taken by **operator or admin** authority only — never by an LLM
  worker role, and never unilaterally by an operator with active peers when a
  controller is reachable.
 - The scope is the minimum necessary rung of the ladder.
 - A **mandatory post-hoc audit** entry is filed: what was restarted, why the
  normal path was impossible, which sessions were affected, and the incident id.
 Break-glass suspends the drain requirement, not the audit requirement.
 ### 2.6 Explicit prohibitions
 - **A unilateral LLM or operator full restart while active peer sessions
  exist is forbidden.** An LLM worker role must not kill, restart, or relaunch
  the MCP process; a lone operator must not full-restart over live peer work
  without controller approval or a break-glass incident.
 - Process-kill recovery is forbidden as a routine tool (#630). This ADR does not
  introduce a kill path.
 - Ambiguous policy state **denies** restart (§4).
 ## 3. Security requirements
 - Full restart and host restart are **privileged**; only operator/admin execute
  them, only after a controller approval or break-glass incident is recorded.
 - Break-glass is a distinct authorization path with its own audit mandate; it is
  never the default and never silent.
 - **Every approval and every restart action is audited** (who approved, who
  executed, scope, affected sessions, condition, policy version). No restart is
  authorized without a durable audit entry.
 ## 4. Failure behavior
 **Ambiguous policy → deny restart.** If it cannot be established that a
 restart is authorized under §2 — unknown affected-session state, missing
 controller approval, absent break-glass incident, or an unclassifiable request —
 the safe action is to **refuse** the restart and stop with a recovery report,
 never to restart on assumption.
 ## 5. Policy IDs (for enforcement code)
 Enforcement code — the restart coordinator (a later child of #655), the #630
 contamination guard, and the #642 console restart UX — binds to these stable
 policy identifiers rather than to prose:
 | Policy ID | Statement |
 |---|---|
 | `RG-01` | Restart is last resort; rungs 1–2 must be tried and recorded first (§2.2). |
 | `RG-02` | v1 authority = controller approval + automated safety gates (§2.1). |
 | `RG-03` | No LLM worker role performs or authorizes full/host restart (§2.3). |
 | `RG-04` | Full/host restart executed by operator/admin only, post approval (§2.3). |
 | `RG-05` | Drain before restart is mandatory except break-glass with incident (§2.4). |
 | `RG-06` | Break-glass requires a pre-declared incident and post-hoc audit (§2.5). |
 | `RG-07` | Unilateral LLM/operator full restart with active peers is forbidden (§2.6). |
 | `RG-08` | Ambiguous policy state denies restart (§4). |
 The `restart-governance/v1` **policy version** field is emitted on future
 restart audit events so approvals can be reconciled against the policy revision
 in force.
 ## 6. Dogfooding
 Gitea-Tools governs its own MCP control plane by this policy. Author, reviewer,
 merger, and reconciler sessions operating on this repository use the recovery
 ladder (§2.2) — reconnect and rebind, never self-restart — and any real restart
 of the Gitea-Tools stable control runtime follows the controller-approval +
 drain path defined here.
 ## 7. Acceptance and cross-links
 This ADR is the authoritative restart-governance policy. It **must** stay
 cross-linked from the safety model and the web-console deployment boundary:
 - `docs/safety-model.md` § Process restart governance references this ADR.
 - `docs/webui-deployment.md` references this ADR for restart/reload disposition.
 It is linked to its issue lineage — umbrella **#655**, vision **#652**, roadmap
 **#653**, contamination guard **#630**, and console restart UX **#642** — in
 § Related above.
 ## 8. Non-goals
 - Implementing the restart coordinator or approval state machine (#630, later
  children of #655).
 - Implementing HA multi-instance restart or quorum machinery.
 - Introducing any process-kill or auto-restart tool; existing auto-restart
  behavior must be inventoried before any new restart tool is enabled.
@@ -1,95 +0,0 @@
 # MCP restart coordinator and impact analysis (#658)
 Before any sanctioned MCP restart, a central coordinator evaluates the live
 control-plane state and produces an **impact preview** so operators and the web
 console (#642 / #652) can see the blast radius *before* concurrent LLM work is
 disrupted. Uncoordinated restarts destroy in-flight author/reviewer/merger work
 and give operators no way to see what they are about to break.
 This lands the coordinator + impact DTO + a dry-run MCP tool. It is the single
 sanctioned entry point for restart evaluation post-#657 (which inventoried the
 restart/reload/kill paths). The **mutative apply** path — actually performing a
 restart — is a later child gated by a drain proof and is explicitly out of
 scope here.
 ## Components
 | Piece | Where | Responsibility |
 |-------|-------|----------------|
 | `restart_coordinator.evaluate_restart_impact` | `restart_coordinator.py` | Pure classification: inventory → impact report DTO. No I/O, no restart. |
 | `RestartImpactReport` / `SessionImpact` / `LeaseImpact` | `restart_coordinator.py` | Console-facing DTO (`.as_dict()` is JSON-serializable). |
 | `ControlPlaneDB.list_sessions` | `control_plane_db.py` | Read-only session inventory (the process-level unit a restart kills). |
 | `gitea_request_mcp_restart` | `gitea_mcp_server.py` | MCP tool: gathers inventory from the #613 DB, calls the coordinator, returns the report. Dry-run only. |
 ## Dimensions evaluated
 The coordinator classifies the inventory across the dimensions #658 requires:
 - **Sessions** — every active MCP session; a restart terminates all of them.
  Liveness = `status == active` **and** the owner pid is alive **and** the
  heartbeat is fresh (default window 15 min). Dead/stale sessions do not count
  toward blast radius.
 - **Leases / locks** — control-plane leases joined with work items and their
  freshness (`lease_lifecycle.classify_lease_freshness`). Only `active` (live
  owner) leases are *disruptive*; expired / released / dead-process leases never
  withhold a restart.
 - **Issue / PR work** — the issues and PRs behind disruptive leases.
 - **Mutations / critical sections** — a live lease carrying an author worktree
  or a mutating phase (`implementing`, `publishing`, `merging`, …) is a
  critical section a restart must not sever.
 - **Terminal (merge) lock** — an active terminal lock always makes a restart
  unsafe.
 - **Prior recovery attempts** — narrower recovery already tried (e.g. sanctioned
  client reconnects) is echoed so the operator sees the escalation history.
 ## Verdict
 Exactly three verdicts, matching the acceptance criteria:
 | Verdict | `allow_restart` | Meaning |
 |---------|-----------------|---------|
 | `safe` | `true` | No other live sessions, no live leases, no terminal lock. |
 | `unsafe` | `false` | Live work would be disrupted and no operator override is present — **or** the inventory could not be completed (fail closed). |
 | `override` | `true` | Live work present, but an operator override accepts the blast radius. |
 `override_would_allow` tells the console whether an override path exists for the
 current state. `blast_radius` is a `none` / `low` / `medium` / `high` severity
 band derived from the affected session and work counts.
 ### Fail closed
 If the control-plane inventory cannot be completed (DB unavailable, a listing
 failed), `inventory_complete` is `false` and the verdict is `unsafe` / deny. An
 incomplete evaluation must never green-light a restart.
 ### Operator override authority
 Override authority is read from the environment variable
 `GITEA_OPERATOR_RESTART_OVERRIDE_AUTHORIZATION` and **never** from a tool
 argument. A worker session cannot set an environment variable on an
 already-running daemon, so override cannot be self-asserted (same pattern as the
 #630 daemon-maintenance authorization). The `request_override` tool argument only
 expresses caller intent; it takes effect solely when the environment
 authorization is present.
 ## The tool
 ```text
 gitea_request_mcp_restart(remote, host, org, repo,
                          dry_run=True, request_override=False,
                          session_id=None, limit=200)
 ```
 Read-only, dry-run, and it **never restarts anything**. `apply_supported` is
 always `false`; passing `dry_run=False` performs no restart and reports that
 apply is gated by a drain proof (a separate child).
 ## Audit
 Every evaluation carries an `audit_record` (event, coordinator version, verdict,
 allow decision, blast radius, counts, timestamp) so restart decisions are
 auditable. No secrets flow through the coordinator — session ids, pids, and
 profiles are operational metadata only.
 A representative dry-run report is in
 [`mcp-restart-impact-sample.json`](./mcp-restart-impact-sample.json).
@@ -1,148 +0,0 @@
 {
  "coordinator_version": "1.0.0-issue-658",
  "evaluated_at": "2026-07-24T06:00:00+00:00",
  "dry_run": true,
  "restart_performed": false,
  "inventory_complete": true,
  "incomplete_reasons": [],
  "verdict": "unsafe",
  "allow_restart": false,
  "override_would_allow": true,
  "operator_override": false,
  "blast_radius": "high",
  "reasons": [
    "live work would be disrupted; restart denied without operator override",
    "1 critical section(s) in flight (active lease with a live owner)"
  ],
  "affected_sessions": [
    {
      "session_id": "prgs-author-30988-d6f43c25",
      "role": "author",
      "profile": "prgs-author",
      "pid": 1,
      "status": "active",
      "alive": true,
      "heartbeat_stale": false,
      "is_requester": false,
      "live": true
    },
    {
      "session_id": "prgs-reviewer-4157-0ce9",
      "role": "reviewer",
      "profile": "prgs-reviewer",
      "pid": 1,
      "status": "active",
      "alive": true,
      "heartbeat_stale": false,
      "is_requester": true,
      "live": true
    }
  ],
  "affected_leases": [
    {
      "lease_id": "lease-abc",
      "session_id": "prgs-author-30988-d6f43c25",
      "role": "author",
      "phase": "implementing",
      "freshness": "active",
      "work_kind": "issue",
      "work_number": 658,
      "worktree_path": "/repo/branches/feat-issue-658",
      "disruptive": true,
      "is_mutation": true,
      "is_critical_section": true
    },
    {
      "lease_id": "lease-dead",
      "session_id": "prgs-author-91485",
      "role": "author",
      "phase": "allocated",
      "freshness": "stale_dead_process",
      "work_kind": "issue",
      "work_number": 651,
      "worktree_path": null,
      "disruptive": false,
      "is_mutation": false,
      "is_critical_section": false
    }
  ],
  "critical_sections": [
    {
      "lease_id": "lease-abc",
      "session_id": "prgs-author-30988-d6f43c25",
      "role": "author",
      "phase": "implementing",
      "freshness": "active",
      "work_kind": "issue",
      "work_number": 658,
      "worktree_path": "/repo/branches/feat-issue-658",
      "disruptive": true,
      "is_mutation": true,
      "is_critical_section": true
    }
  ],
  "affected_issues": [
    658
  ],
  "affected_prs": [],
  "mutations": [
    {
      "lease_id": "lease-abc",
      "session_id": "prgs-author-30988-d6f43c25",
      "role": "author",
      "phase": "implementing",
      "freshness": "active",
      "work_kind": "issue",
      "work_number": 658,
      "worktree_path": "/repo/branches/feat-issue-658",
      "disruptive": true,
      "is_mutation": true,
      "is_critical_section": true
    }
  ],
  "terminal_lock": null,
  "ack_state": {
    "prgs-author-30988-d6f43c25": "pending"
  },
  "prior_recovery_attempts": [
    {
      "kind": "client_reconnect",
      "at": "2026-07-24T06:00:00+00:00",
      "outcome": "insufficient"
    }
  ],
  "counts": {
    "sessions_total": 2,
    "sessions_live_other": 1,
    "leases_total": 2,
    "leases_disruptive": 1,
    "critical_sections": 1,
    "mutations": 1,
    "affected_issues": 1,
    "affected_prs": 0,
    "prior_recovery_attempts": 1
  },
  "audit_record": {
    "event": "restart_impact_evaluated",
    "coordinator_version": "1.0.0-issue-658",
    "evaluated_at": "2026-07-24T06:00:00+00:00",
    "dry_run": true,
    "operator_override": false,
    "requesting_session_id": "prgs-reviewer-4157-0ce9",
    "inventory_complete": true,
    "verdict": "unsafe",
    "allow_restart": false,
    "blast_radius": "high",
    "counts": {
      "sessions_total": 2,
      "sessions_live_other": 1,
      "leases_total": 2,
      "leases_disruptive": 1,
      "critical_sections": 1,
      "mutations": 1,
      "affected_issues": 1,
      "affected_prs": 0,
      "prior_recovery_attempts": 1
    }
  }
 }
@@ -1,90 +0,0 @@
 # MCP restart / reload / kill path inventory (#657)
 Complete inventory of every code, script, and host path that can **restart,
 reload, reconnect, kill, or force-recreate** an MCP process in this project,
 with each path classified and linked to the guard that constrains it.
 This document is the human-readable companion to the machine-readable registry
 in [`mcp_restart_paths.py`](../mcp_restart_paths.py). The two are kept in
 lock-step by [`tests/test_mcp_restart_paths.py`](../tests/test_mcp_restart_paths.py):
 every `path_id` below must appear in this file, and the source guards are run
 against the live tree.
 Roadmap linkage: this inventory is the enumeration step of the restart
 governance work — parent **#655**, restart-governance ADR **#656**, vision
 **#652**, roadmap **#653**. Related detection/guard work: master-advance
 staleness **#591**/**#420**, side-effect-free resolver **#685**, transport flap
 **#584**, manual-kill contamination **#630**.
 ## Classifications
 | Classification | Meaning |
 |---|---|
 | `sanctioned_narrow_recovery` | One-shot, safe-by-construction recovery that never targets the running daemon. |
 | `guarded_fail_closed` | Detects a restart-requiring condition, then fails mutations closed and emits reconnect guidance. Never self-restarts. |
 | `forbidden` | A workflow-safety violation; where an LLM tool could invoke it, it is marked contamination. |
 | `removed` | A previously-existing unguarded restart primitive that has been deleted; a regression guard keeps it absent. |
 | `host_residual` | Behavior owned by the host/IDE, outside this process's control. Documented, not code-guarded here. |
 ## The rule
 **No component may perform an unguarded full restart of the MCP daemon.** The
 in-process daemon (`gitea_mcp_server.py`, `mcp_server.py`,
 `role_session_router.py`) must never replace or terminate its own process:
 replacing the process after the host has wired up the stdio pipes desyncs the
 JSON-RPC transport (observed with Antigravity/Cascade hosts). Recovery is owned
 by the host/operator via a client reconnect — the daemon only ever *detects*
 and *fails closed*.
 ## Inventory
 | path_id | Classification | Mechanism | Guard | Refs |
 |---|---|---|---|---|
 | `cli_venv_bootstrap_execv` | sanctioned_narrow_recovery | CLI wrapper scripts re-exec into `venv/bin/python3` via `os.execv`, guarded by `sys.executable != venv_python`. | One-shot pre-import bootstrap; runs before any MCP transport exists and only when not already on the venv interpreter; idempotent guard prevents a re-exec loop. | #657 |
 | `daemon_self_replacement` | forbidden | The daemon replacing/terminating its own process (`os.execv`/`os.kill`/`os._exit`) to reload code. | Forbidden by design; enforced against the source tree by `assert_no_daemon_self_replacement()`. | #657, #584 |
 | `legacy_auto_restart_helper` | removed | A helper (`_trigger_mcp_auto_restart`) that actively restarted the server from the read-only resolver path. | Removed in #685; kept absent by `assert_auto_restart_helper_absent()`. | #685, #657 |
 | `config_touch_reload` | removed | Touching (utime) the MCP client config to make the host reload the server. | Removed from the resolver in #685: stale detection is report-only, never mutating config, spawning threads, or calling `os._exit`. | #685, #657 |
 | `master_advance_auto_restart` | guarded_fail_closed | On-disk master advancing past the running code. | `master_parity_gate` captures startup parity and blocks mutations while stale, emitting restart guidance; the process never self-restarts. | #420, #591, #657 |
 | `stale_runtime_resolver_reconnect` | guarded_fail_closed | The capability resolver detecting a stale serving process. | Report-only (#685): returns `restart_required`/`stop_required` and an exact reconnect action; no restart, thread, config touch, or `os._exit`. | #685, #657 |
 | `manual_daemon_kill` | forbidden | Shell kills of the daemon: `pkill -f mcp_server.py`, `killall`, broad `pkill -f python` sweeps, or `kill <pid>` of a daemon pid. | Forbidden (#630): `runtime_recovery_guard` classifies these as contamination and `gitea_record_daemon_process_kill_attempt` writes a durable marker that fails later mutations closed. Operator maintenance authorization is read only from the environment. | #630, #657 |
 | `conflict_marker_infra_stop` | guarded_fail_closed | The daemon entrypoint scans for unresolved merge-conflict markers at startup and stops (`sys.exit(1)`). | Fail-closed startup stop, not a restart: the process exits and waits for the operator to resolve conflicts and relaunch; never loops. | #657 |
 | `ide_client_reconnect` | host_residual | A manual `/mcp reconnect` (or equivalent host action) that recreates the MCP client connection. | Outside this process's control; the sanctioned recovery the gates point operators toward. No in-process code initiates it. | #584, #656, #657 |
 | `profile_switch_runtime` | sanctioned_narrow_recovery | Switching the active execution profile at runtime (dynamic-profile mode). | In-process and restart-free: `runtime_switching_supported` is true, so a switch rebinds capability without recreating the process. | #656, #657 |
 ## Guards enforced in CI
 `tests/test_mcp_restart_paths.py` asserts, against the live source tree:
 1. **Registry well-formedness** — every path has a valid classification, a
   non-empty guard description, references, and locations; ids are unique; all
   five classifications are represented.
 2. **Unknown restart attempts fail closed** —
   `assert_restart_attempt_registered()` raises `UnknownRestartPathError` for
   any path id not in this inventory, so a novel/unnamed restart primitive
   cannot slip through silently.
 3. **Daemon never self-replaces** — `assert_no_daemon_self_replacement()` scans
   the daemon modules for `os.execv`/`os.kill`/`os._exit`/`os.abort` calls
   (comment/docstring mentions are ignored) and finds none.
 4. **Legacy helper stays removed** — `assert_auto_restart_helper_absent()`
   confirms `_trigger_mcp_auto_restart` has not returned.
 5. **pkill stays forbidden** — a daemon `pkill` command still classifies as
   contamination via `runtime_recovery_guard`.
 ## Residual host behaviors (outside process control)
 * `/mcp reconnect` in the IDE/host — the sanctioned recovery for stale-runtime,
  transport-flap (#584), and worktree-binding conditions. The daemon can only
  emit guidance toward it.
 * Host-level process management (the operator relaunching the daemon after a
  fail-closed stop, or after resolving merge conflicts).
 These are documented rather than code-guarded because the process cannot
 observe or gate them from inside itself.
 ## Rollout
 Per #657, guards are introduced flag-free as **regression assertions** (they
 codify invariants that already hold) before any hard runtime block is layered
 on. When the restart coordinator (#655/#656) lands, registered paths gain a
 coordinator token/capability check; unregistered attempts already fail closed
 today via `assert_restart_attempt_registered()`.
@@ -135,7 +135,6 @@ that gates each call, not which tools exist.
 - `gitea_release_merger_pr_lease`
 - `gitea_release_reviewer_pr_lease`
 - `gitea_release_workflow_lease`
 - `gitea_request_mcp_restart`
 - `gitea_resolve_task_capability`
 - `gitea_resume_review_draft`
 - `gitea_review_pr`
@@ -46,17 +46,3 @@ If shell helpers are unavailable and MCP commit cannot run, stop with a recovery
 report (restart session, clear hung terminals, use MCP-native commit). See
 [`llm-workflow-runbooks.md`](llm-workflow-runbooks.md) § MCP-native commit path
 (#260) and agent temp artifact cleanup (#261).
 ## 7. Process restart governance
 Restarting the MCP control-plane process is destructive to concurrent multi-role
 work and is governed by a dedicated policy. Restart is a **last resort** behind
 narrower recoveries (reconnect, rebind), full/host restart is reserved to
 operator/admin under **controller approval + automated safety gates**, a
 unilateral LLM or operator full restart with active peers is **forbidden**, and
 ambiguous policy state **denies** restart. Break-glass is a separate,
 incident-backed path with a mandatory audit.
 See [`architecture/mcp-restart-governance.md`](architecture/mcp-restart-governance.md)
 (#656) for the authorization matrix, the recovery ladder, break-glass
 conditions, and the `RG-01`–`RG-08` policy IDs.
@@ -1,122 +0,0 @@
 # Sanctioned restart and graceful reload controls (#642)
 Sessions used to recover MCP connectivity by killing the host daemon
 (`pkill -f mcp_server.py`, #630). That is forbidden and stays forbidden: it
 kills every namespace on the host, contaminates whichever session survives, and
 leaves no audit trail. This document describes the sanctioned replacement,
 implemented in `webui/sanctioned_restart.py`.
 ## What the console will and will not do
 The console **never** restarts anything. It authorizes an intent, records it,
 and hands off to a host supervisor. There is no code path in which the console
 sends a signal, spawns a process, or renders a kill command — a regression test
 asserts the module contains no `subprocess`, `signal`, `os.kill`, `os.system`,
 or `popen` reference, and that no returned payload contains a kill command.
 ## Operations
 | Mode | Action | Minimum role | Behaviour |
 |------|--------|--------------|-----------|
 | `reload` | `system.reload_namespace` | controller | Host supervisor reloads the namespace in place, draining in-flight requests. |
 | `restart` | `system.restart_namespace` | admin | Host supervisor restarts the namespace. In-flight requests are lost. |
 Scope is always exactly one namespace. A fleet-wide restart is an explicit
 non-goal: `all`, `*`, `fleet`, and an empty scope are refused with
 `fleet_scope_not_permitted`, because that is precisely the blast radius the
 forbidden kill already had. An unrecognised namespace is refused rather than
 passed through to the host.
 ## The gate sequence
 `assess_restart_request()` applies every gate in order and reports the first
 failure with a stable reason code:
 | Order | Gate | Reason code on failure |
 |-------|------|------------------------|
 | 1 | Mode is `restart` or `reload` | `unknown_mode` |
 | 2 | Scope is a single known namespace | `fleet_scope_not_permitted`, `unknown_namespace` |
 | 3 | Principal holds the required console role | `unauthorized` |
 | 4 | Confirmation phrase supplied | `confirmation_required` |
 | 5 | Confirmation names this namespace and mode | `confirmation_mismatch` |
 | 6 | Out-of-band operator authorization present | `operator_authorization_missing` |
 | 7 | Runtime is not contaminated | `contaminated_runtime` |
 | 8 | Host restart hook configured | `restart_hook_not_configured` |
 Passing every gate yields `host_action_required`, never "restarted".
 ### Confirmation binds the namespace
 The required phrase is `"<mode> <namespace>"` — for example
 `restart gitea-author`. Binding the namespace into the phrase is the point: a
 confirmation typed for one namespace cannot be replayed against another.
 ### Operator authorization is not self-assertable
 Host daemon maintenance is authorized out of band through
 `GITEA_OPERATOR_DAEMON_MAINTENANCE_AUTHORIZATION`, read from the process
 environment and nowhere else (#630; #710 finding F1). A worker session cannot
 set an environment variable for an already-running daemon, so this cannot be
 faked the way a tool argument could.
 ### The host hook
 `GITEA_SANCTIONED_RESTART_HOOK` holds an opaque reference the *host* resolves —
 a supervisor label such as a launchd job name, never a command line. With no
 hook configured the request is refused; the console does not fall back to a
 process kill. The value is read server-side and never rendered to a client.
 ## Manual kill remains contamination
 `classify_restart_command()` classifies an operator-proposed recovery command.
 A manual `pkill`/`kill`/`killall` of the MCP daemon is contamination, not a
 restart: it returns `clean_claim_allowed: false` and builds a durable
 contamination marker (redacted command only, never secrets) naming
 `system.restart_namespace` as the sanctioned alternative.
 A live, uncleared contamination marker also blocks a restart. This is stricter
 than #630's task-scoped gate, which deliberately lets a contaminated worker keep
 commenting and handing off: restarting a contaminated runtime would launder the
 contamination rather than resolve it. Clear the marker through the reconciler
 path first.
 ## Post-restart health verification
 After the host supervisor acts, `verify_post_restart_health()` decides whether
 the session may claim to be clean:
 | Status | Meaning | Clean claim |
 |--------|---------|-------------|
 | `clean` | Required tool callable, proven through the live client namespace | Allowed |
 | `unproven` | Reported healthy without live client-namespace evidence | Refused |
 | `unhealthy` | Probe failed | Refused |
 Only `probe_source=client_namespace` evidence clears a session. Static tool
 registration is not proof, and neither is an offline subprocess probe — an IDE
 client can hold a registered tool list while live calls fail with
 `client is closing: EOF` (see
 [`mcp-namespace-health.md`](mcp-namespace-health.md)).
 ## Audit
 Every attempt — allowed or denied — is recorded through
 `webui.console_audit` with actor, target namespace, mode, result, and reason
 code, and is redacted before it is persisted. `system.restart_namespace` is
 break-glass, so its records are retained for 730 days. Records carry
 `process_kill_executed: false`, which is a fact about the code path rather than
 a claim: no such path exists.
 ## Environment variables
 | Variable | Purpose |
 |----------|---------|
 | `GITEA_SANCTIONED_RESTART_HOOK` | Host supervisor reference; absent means restart is refused. |
 | `GITEA_OPERATOR_DAEMON_MAINTENANCE_AUTHORIZATION` | Out-of-band operator authorization reference. |
 | `WEBUI_AUDIT_LOG` | Console audit sink; absent means records are built but not persisted. |
 ## Non-goals
 * No unrestricted `kill` from the UI, in any role, in any phase.
 * No fleet-wide restart.
 * No silent auto-restart loop: every attempt is confirmed and audited.
 * This does not implement the Phase 1 health API (#634).
@@ -91,8 +91,6 @@ already define, and a regression test asserts each mapping matches.
 | `close_pr` | controller | privileged | `gitea.pr.close` | Yes | No | No | 3 |
 | `merge_pr` | controller | privileged | `gitea.pr.merge` | Yes | **Yes** | **Yes** | 3 |
 | `delete_branch` | admin | destructive | `gitea.branch.delete` | Yes | **Yes** | **Yes** | 3 |
 | `system.reload_namespace` | controller | privileged | `runtime.reload_namespace` | Yes | No | No | 2 |
 | `system.restart_namespace` | admin | destructive | `runtime.restart_namespace` | Yes | **Yes** | **Yes** | 2 |
 **Dual control** means the acting principal may not be the sole authority: a
 second distinct principal must confirm. **Break-glass** means the action is
@@ -104,13 +102,6 @@ honouring it.
 `delete_branch` is admin-only rather than controller because it is the one
 irreversible action in the set.
 `system.restart_namespace` is admin-only for the same reason: restarting a
 namespace drops every in-flight request on it. `system.reload_namespace` drains
 first, so it is privileged but not destructive. Neither action is ever executed
 by the console — both hand off to a host supervisor, and neither exposes a raw
 process kill. See
 [`sanctioned-restart-controls.md`](sanctioned-restart-controls.md) (#642).
 ### Authorization decision
 `authorize(action_id, principal, for_execution=False)` returns a decision
@@ -208,8 +199,8 @@ breaking the request it describes.
 | Class | Applies to | Default |
 |-------|-----------|---------|
 | `standard` | Routine gated writes | 90 days |
-| `privileged` | `review_pr`, `close_pr`, `system.reload_namespace`, and any unclassifiable action | 365 days |
+| `privileged` | `review_pr`, `close_pr`, and any unclassifiable action | 365 days |
-| `break_glass` | `merge_pr`, `delete_branch`, `system.restart_namespace` | 730 days |
+| `break_glass` | `merge_pr`, `delete_branch` | 730 days |
 Each record carries its own class, day count, and computed `expires_at`, so
 retention is auditable per record rather than inferred from file age. An
@@ -55,15 +55,6 @@ shipped to the browser.
 assumption paths, and the client-secret policy. Use it to verify an instance is
 configured for internal-only operation.
 ## Process restart / reload disposition
 The console never exposes a restart or reload control; process restart of the
 MCP control-plane runtime is governed separately. Restart is a last resort behind
 reconnect/rebind, full restart is operator/admin-only under controller approval
 plus safety gates, and break-glass is an incident-backed path. See
 [`architecture/mcp-restart-governance.md`](architecture/mcp-restart-governance.md)
 (#656).
 ## Non-goals (MVP)
 - Full SSO or session login in the UI
@@ -52,8 +52,7 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
 | Path | Description |
 |------|-------------|
 | `/` | Home / operator overview |
-| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`, `uptime_seconds`) |
+| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`) |
 | `/api/v1/system/health` | Structured read-only system health (#634) |
 | `/queue` | Live PR and issue queue dashboard (#429) |
 | `/api/queue` | JSON queue export with pagination metadata |
 | `/projects` | Project registry list with status and onboarding progress (#427, #635) |
@@ -74,95 +73,11 @@ status, onboarding checklist state, and the fail-closed error payloads (#635).
 | `/api/actions/{id}/preview` | Mutation ledger preview (GET, read-only) |
 | `/leases` | Lease and collision visibility (#433) |
 | `/api/leases` | JSON lease/collision export |
 | `/sessions` | Phase 1 shell stub — session inventory (backed by #636) |
 | `/inventory` | Phase 1 shell stub — unified inventory (backed by #636) |
 | `/timeline` | Phase 1 shell stub — workflow event timeline |
 | `/policy` | Phase 1 shell stub — capability/role policy placeholder |
 | `/insights` | Phase 1 shell stub — operational insights placeholder |
 Most routes are GET-only. POST/PUT/PATCH/DELETE return `405` with
 `read-only-mvp`, except `/audit` and `/api/audit` which accept POST for
 local validator preview only (no Gitea mutations, no server-side storage).
 ## System health API (#634)
 `GET /api/v1/system/health` is the structured, read-only health surface for
 automated readiness checks. It is the first console API under the `/api/v1`
 prefix; the unversioned MVP exports remain as compatibility aliases.
 `/health` is unchanged for existing consumers — every MVP key is still present
 — and now also carries `started_at`, `uptime_seconds`, and a
 `system_health_api` pointer. It stays deliberately cheap and runs no dependency
 probe, because answering readiness costs real work.
 **Status codes.** `200` when ready, `503` when a required dependency failed or
 was never probed. Automation can branch on the code without parsing the body.
 **Query flags.** The Gitea check is a network call, so it is opt-in:
 `GET /api/v1/system/health?deep=1` runs it and caches the result for
 `WEBUI_HEALTH_PROBE_TTL_SECONDS` (default 15s) so dashboard polling does not
 amplify into remote load. Without the flag that probe reports `skipped`.
 **Dependencies.** `control_plane_db` and `repository` are required and drive
 readiness. `gitea` is optional: when it fails the overall `status` degrades but
 `readiness.ready` stays true, because local inventory is still serveable. Each
 entry carries `status`, `detail`, `required`, and `latency_ms`.
 Two honesty rules are worth knowing before reading the payload:
 * `stale_runtime.mutation_safe` is true only when the runtime, checkout, and
  remote-tracking commits are all known and equal. An unfetched remote is
  reported as indeterminate, never as safe.
 * `mcp_namespaces` entries are always `unproven`. A web process runs outside
  the IDE-managed MCP client and cannot invoke a namespace tool, so per #543
  only a `client_namespace` probe can prove that path.
 Sample response (abridged, healthy):
 ```json
 {
  "status": "ok",
  "service": "mcp-control-plane-webui",
  "mode": "read-only",
  "api": "/api/v1/system/health",
  "timestamp": "2026-07-22T11:04:18.512034+00:00",
  "readiness": { "ready": true, "complete": true, "reasons": [] },
  "version": {
    "git_sha": "620ed6e9a9550b8da2ceb82d9ab8744e8920490f",
    "git_describe": "v1.1.0-898-g620ed6e",
    "control_plane_schema_version": 4,
    "python_version": "3.14.5",
    "known": true
  },
  "process": { "started_at": "2026-07-22T10:58:02.114+00:00", "uptime_seconds": 376.4 },
  "deep_probes_requested": false,
  "dependencies": [
    {
      "name": "control_plane_db",
      "kind": "sqlite",
      "status": "ok",
      "detail": "schema v4 readable",
      "required": true,
      "healthy": true,
      "latency_ms": 1.482,
      "metadata": { "schema_version": 4, "active_leases": 3 }
    },
    { "name": "repository", "kind": "git", "status": "ok", "required": true, "healthy": true },
    { "name": "gitea", "kind": "http", "status": "skipped", "required": false, "healthy": false }
  ],
  "mcp_namespaces": [
    { "namespace": "gitea-author", "required_tool": "gitea_whoami", "status": "unproven" }
  ],
  "stale_runtime": { "stale": false, "determinable": true, "mutation_safe": true, "reasons": [] },
  "probe_errors": []
 }
 ```
 No restart, reload, or process-kill control is exposed here: those are Phase 2
 at the earliest, and #630 forbids process-kill recovery outright. Every probe
 opens its subject read-only — the control-plane database is opened through a
 `mode=ro` URI so a health check can never create or migrate a schema.
 ## Report audit (#431)
 Paste an LLM final report at `/audit` or POST JSON to `/api/audit`. The UI
@@ -238,26 +153,6 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
 checkout is behind merged safety-gate changes. Restart guidance links to #420;
 no tokens or MCP restart actions are exposed.
 ## Application shell — Phase 1 (#638)
 The console shell (`webui/layout.py`) renders a grouped navigation driven by a
 single nav-config module, `webui/nav.py`. Nav groups follow the epic #631
 Phase 1 information architecture: **Health, Traffic, Runtime/Sessions,
 Projects, Inventory, Timeline, Policy** (placeholder), and **Insights**
 (placeholder). Live views and Phase 1 placeholders (`stub`) are declared in one
 place so the layout and the route table cannot drift.
 The header carries two read-only status badges — an **environment** badge
 (`local` for loopback binds, `remote` otherwise, derived from `WEBUI_HOST`) and
 a **mode: read-only** badge — plus a **Docs** link to this document. No
 privileged action controls are present in the Phase 1 shell.
 Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`,
 `/policy`, `/insights`) resolve to graceful read-only stub pages instead of
 404s; their backing views land in later child issues of #631 (the inventory
 surfaces are backed by #636). Mutating methods on stub routes still fail closed
 with `read-only-mvp`.
 ## Deployment boundary (#435)
 MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused**
@@ -317,108 +212,6 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the
 checkout is behind merged safety-gate changes. Restart guidance links to #420;
 no tokens or MCP restart actions are exposed.
 ## Workflow-event timeline (#637)
 `GET /api/v1/timeline` is a read-only, versioned aggregation of workflow
 events from every available source into one normalised, filterable stream. It
 is the model layer for the Phase 1 timeline console view (a later child issue
 of #631); this issue ships the schema, adapters, and read API only.
 ### Schema (versioned)
 `webui/timeline.py` declares `TIMELINE_SCHEMA_VERSION` (currently `1`) and the
 frozen `WorkflowEvent` record. Every response carries `schema_version` so a
 consumer can branch on shape. One event:
 ```json
 {
  "source": "control_plane",
  "event_type": "lease.renew",
  "event_key": "cp:1421",
  "timestamp": "2026-07-23T02:00:00Z",
  "actor": null,
  "role": null,
  "issue_number": 637,
  "pr_number": null,
  "session_id": null,
  "tool_name": null,
  "decision": null,
  "message": "lease renewed",
  "correlation_id": "issue#637",
  "evidence_refs": [],
  "sensitive": true
 }
 ```
 `event_key` is stable and unique per source (`cp:<event_id>`,
 `cth:<kind>:<number>:<comment_id>`), so pagination and dedup are deterministic.
 ### Sources and field authority
 | Source | Adapter | Authority |
 |---|---|---|
 | Control-plane `events` ⋈ `work_items` | `adapt_cp_events` | `event_type`, `message`, `timestamp`, issue/PR scope come from the CP database, read through a `mode=ro` URI (never creates the DB or runs migrations) |
 | Gitea Canonical Thread Handoff comments | `adapt_cth_comments` | `actor`, `role` (next owner), `decision`, `evidence_refs`, `timestamp` come from the parsed CTH comment body (`canonical_thread_handoff`) |
 Handoff comments are thread-scoped: they are only read when the request filters
 by a single `issue` or `pr`. Otherwise the handoff source reports `not run`
 with a reason — it is never rendered as empty-and-healthy. Each source degrades
 independently: an unavailable control-plane DB or a failed comment fetch is a
 `sources[]` entry with `ok:false` and a `reason`, never a dropped timeline.
 ### Query parameters
 `issue`, `pr`, `session` (conjunctive filters); `limit` (default 50, max 500)
 and `offset` for pagination; `remote`, `org`, `repo` to override the default
 registry-project scope. Events sort ascending by
 `(timestamp, source_rank, event_key)`; missing timestamps sort last.
 ### Filter authority, and refusing what cannot be answered
 A filter dimension is only meaningful for a source whose records carry it.
 Each source declares its own support in `_SOURCE_FILTER_SUPPORT` and reports it
 per response as `supported_filters` / `unsupported_filters`:
 | Source | issue | pr | session |
 |---|---|---|---|
 | `control_plane` | yes | yes | **no** — the `events` table is `(event_id, work_item_id, event_type, message, created_at)` and records no session |
 | `gitea_handoff` | yes | yes | yes — a CTH comment declares its own `Session:` field |
 `session_id` is read only from that declared CTH field. It is never inferred
 from a work item, an actor, or message text, and a value that is
 redaction-altering or bare-secret-shaped is dropped rather than emitted.
 When **no source that ran** can carry a requested dimension, the request is
 refused rather than answered: the response is `422` with `ok:false` and a
 structured `error` naming `unsupported_filters` and the per-source reason. A
 `200` with zero events would tell an operator that no such activity exists,
 which is a stronger — and false — claim than "this cannot be answered here".
 A source that *can* answer the dimension and simply matched nothing still
 returns `200` with `ok:true` and an empty page.
 ### Redaction
 Every free-text field (event messages, decision/proof text, roles, actors) is
 passed through the console redaction policy (`webui.console_redaction`, backed
 by `gitea_audit.redact`) before it leaves the module, failing closed to the
 placeholder. No unredacted tool arguments or secrets are ever emitted, and a
 generation error never drops raw data to a caller or a log.
 Redaction also runs *before* any structured value is derived from free text.
 `evidence_refs` are extracted from already-redacted proof/decision text, and a
 commit reference is recognised only where the text declares one (`commit`,
 `head`, `base`, `sha`, …). An undeclared 40-character hex run has the exact
 shape of a Gitea access token, so it is never lifted out of prose into a
 structured field. Every reference is then independently revalidated against an
 allowed shape and a second redaction pass immediately before serialization;
 anything unproven is dropped and the event is flagged `sensitive`.
 ### Tests
 ```bash
 pytest tests/test_webui_timeline.py -q
 ```
 ## Tests
 ```bash
@@ -16,18 +16,11 @@ ISSUE_LOCK_FILE = os.environ.get("GITEA_ISSUE_LOCK_FILE", "/tmp/gitea_issue_lock
 SOURCE_LOCK_ISSUE = "gitea_lock_issue"
 SOURCE_LOCK_ADOPTION = "gitea_lock_issue_adoption"
 SOURCE_OPERATOR_OVERRIDE = "operator_override"
 SOURCE_RECOVER_DIRTY_ORPHANED = "gitea_recover_dirty_orphaned_issue_worktree"
 # #864: dirty-preserving same-claimant author-session rebind (dead owner PID).
 SOURCE_DIRTY_SAME_CLAIMANT_REBIND = (
    "gitea_rebind_dirty_same_claimant_author_session"
 )
 SANCTIONED_LOCK_SOURCES = frozenset({
    SOURCE_LOCK_ISSUE,
    SOURCE_LOCK_ADOPTION,
    SOURCE_OPERATOR_OVERRIDE,
    SOURCE_RECOVER_DIRTY_ORPHANED,
    SOURCE_DIRTY_SAME_CLAIMANT_REBIND,
 })
 _OPERATOR_OVERRIDE_ENV = "GITEA_ISSUE_LOCK_OPERATOR_OVERRIDE"
@@ -85,12 +85,6 @@ HEAD_RELATION_STRICT_DESCENDANT = "strict_descendant"
 # #772: an unpublished claim has no recorded head to compare against at all, so
 # its head is measured against the base the branch was cut from instead.
 HEAD_RELATION_DESCENDS_FROM_BASE = "descends_from_recorded_base"
 # #871: the remote/PR head advanced *past* the recorded head via a sanctioned
 # merge-based branch synchronization (``gitea_update_pr_branch_by_merge``) while
 # the local worktree stayed at the recorded head. This is the inverse of the
 # #768 descendant relation — here the *remote* strictly descends the local head,
 # and only because a base was merged into the branch, proven server-side.
 HEAD_RELATION_REMOTE_MERGE_SYNCED = "remote_merge_synced"
 # Which body of evidence a recovery was decided on (#772 AC10). These are not
 # interchangeable: a published claim proves ownership against a remote/PR head,
@@ -272,70 +266,6 @@ def _assess_base_descendancy(
    ]
 def _assess_remote_merge_synced(
    sync_provenance: Mapping[str, Any] | None,
    *,
    recorded_head: str,
    remote_head: str,
 ) -> tuple[bool, list[str]]:
    """Did ``remote_head`` advance past ``recorded_head`` via a sanctioned
    merge-based branch sync (#871)?
    ``sync_provenance`` is the server-side git observation from
    ``issue_lock_worktree.read_merge_sync_provenance``. Its own
    ``prior_head_sha`` / ``synced_head_sha`` are re-checked against the heads
    this assessment is actually reasoning about, so an observation taken for some
    other pair of commits — stale, mismatched, or hand-built — can never
    authorize recovery. This is the inverse of ``_assess_strict_descendant``: the
    recorded head is the ancestor and the *remote* head is the descendant, and it
    is accepted only because the remote head is a base-into-branch merge that
    preserved the branch mainline back to the recorded head.
    Returns ``(proven, notes)``. Notes name the exact missing element so a
    refused caller sees why, never a bare "unproven".
    """
    if not isinstance(sync_provenance, Mapping):
        return False, [
            "no server-derived merge-sync provenance observation was available; a "
            "remote head ahead of the recorded head cannot be accepted"
        ]
    probe_prior = _text(sync_provenance.get("prior_head_sha"))
    probe_synced = _text(sync_provenance.get("synced_head_sha"))
    if probe_prior != recorded_head or probe_synced != remote_head:
        return False, [
            f"merge-sync observation covers {probe_prior or 'unknown'} -> "
            f"{probe_synced or 'unknown'}, not the heads under assessment "
            f"({recorded_head} -> {remote_head})"
        ]
    if not sync_provenance.get("probe_ok"):
        return False, (
            list(sync_provenance.get("reasons") or [])
            or ["merge-sync provenance probe did not complete; provenance unproven"]
        )
    if not sync_provenance.get("prior_is_ancestor"):
        return False, [
            f"recorded head {recorded_head} is not an ancestor of remote head "
            f"{remote_head}; a rewritten or force-moved head cannot be recovered"
        ]
    if not sync_provenance.get("is_merge_sync"):
        return False, (
            list(sync_provenance.get("reasons") or [])
            or [
                f"remote head {remote_head} is not a sanctioned merge-based sync "
                f"of the base into the branch above {recorded_head}"
            ]
        )
    proof = _text(sync_provenance.get("proof")) or (
        f"{remote_head} merged the base into the branch above {recorded_head}"
    )
    return True, [
        f"remote head {remote_head} advanced past recorded head {recorded_head} "
        f"via a sanctioned merge-based branch sync ({proof})"
    ]
 def assess_dead_session_lock_recovery(
    existing_lock: Mapping[str, Any] | None,
    *,
@@ -360,7 +290,6 @@ def assess_dead_session_lock_recovery(
    remote_branch_exists: bool | None = None,
    recorded_base_sha: str | None = None,
    base_ancestry: Mapping[str, Any] | None = None,
    sync_provenance: Mapping[str, Any] | None = None,
 ) -> dict[str, Any]:
    """Decide whether a dead-session author lock may be natively recovered.
@@ -540,39 +469,19 @@ def assess_dead_session_lock_recovery(
                    head_relation = HEAD_RELATION_STRICT_DESCENDANT
                    ancestry_proof = notes[0] if notes else None
                else:
-                    # #871: the reverse relation — the remote head advanced past
+                    reasons.append(
-                    # the recorded/local head via a sanctioned merge-based branch
+                        f"local head {local_head} does not match remote branch head "
-                    # sync while the local worktree stayed put. Accepted only on
+                        f"{remote_head}"
                    # server-proven merge-sync provenance, never a caller claim.
                    synced, sync_notes = _assess_remote_merge_synced(
                        sync_provenance,
                        recorded_head=local_head,
                        remote_head=remote_head,
                    )
-                    if synced:
+                    reasons.extend(notes)
                        head_relation = HEAD_RELATION_REMOTE_MERGE_SYNCED
                        ancestry_proof = sync_notes[0] if sync_notes else None
                    else:
                        reasons.append(
                            f"local head {local_head} does not match remote branch "
                            f"head {remote_head}"
                        )
                        reasons.extend(notes)
                        reasons.extend(sync_notes)
    evidence["recorded_base"] = recorded_base or None
    evidence["local_head"] = local_head or None
    evidence["remote_head"] = remote_head or None
    # ``recorded_head`` is the head recovery is being measured against;
    # ``accepted_head`` is the head this recovery actually adopts. They differ
    # only in the descendant case, and downstream gates need both (#768 AC2/AC7).
    # #871: in the merge-sync case the branch/PR already carries the synced
    # remote head, so that is the head recovery adopts; the local worktree stays
    # at the ancestor recorded head.
    evidence["recorded_head"] = remote_head or None
-    if head_relation == HEAD_RELATION_REMOTE_MERGE_SYNCED:
+    evidence["accepted_head"] = local_head or None
        evidence["accepted_head"] = remote_head or None
    else:
        evidence["accepted_head"] = local_head or None
    evidence["head_relation"] = head_relation
    evidence["ancestry_proof"] = ancestry_proof
@@ -584,17 +493,12 @@ def assess_dead_session_lock_recovery(
        # contradictory; re-stating it as a head mismatch would only obscure why.
        if not unpublished and local_head and pr_head != local_head:
            # A descendant recovery has not been published yet, so the open PR
-            # legitimately still points at the recorded head. A merge-sync
+            # legitimately still points at the recorded head. Any other
-            # recovery's PR legitimately sits at the advanced remote head. Any
+            # disagreement is a real mismatch.
            # other disagreement is a real mismatch.
            if not (
                head_relation == HEAD_RELATION_STRICT_DESCENDANT
                and remote_head
                and pr_head == remote_head
            ) and not (
                head_relation == HEAD_RELATION_REMOTE_MERGE_SYNCED
                and remote_head
                and pr_head == remote_head
            ):
                reasons.append(
                    f"open PR #{pr_number} head {pr_head} does not match local head "
@@ -715,11 +619,7 @@ def assess_dead_session_lock_recovery(
        )
    if (
        head_relation
-        in (
+        in (HEAD_RELATION_STRICT_DESCENDANT, HEAD_RELATION_DESCENDS_FROM_BASE)
            HEAD_RELATION_STRICT_DESCENDANT,
            HEAD_RELATION_DESCENDS_FROM_BASE,
            HEAD_RELATION_REMOTE_MERGE_SYNCED,
        )
        and ancestry_proof
    ):
        proof.append(ancestry_proof)
@@ -797,16 +697,6 @@ def owning_pr_recovery_evidence(
            return None
        if accepted_head != local_head:
            return None
    elif relation == HEAD_RELATION_REMOTE_MERGE_SYNCED:
        # #871: the PR already sits at the advanced remote head; the local
        # worktree is the ancestor the merge preserved. The head the open PR
        # shows and the head recovery adopts are both the synced remote head.
        if not remote_head or pr_head != remote_head:
            return None
        if accepted_head != remote_head:
            return None
        if not local_head or local_head == remote_head:
            return None
    else:
        return None
    try:
@@ -875,18 +765,6 @@ def recovered_owning_pr_from_lock(
            return None
        if not accepted_head or accepted_head == recorded_head:
            return None
    elif relation == HEAD_RELATION_REMOTE_MERGE_SYNCED:
        # #871: PR sits at the advanced remote head, which is both the recorded
        # measured-against head and the adopted head; the local worktree is the
        # ancestor the merge preserved.
        remote_head = _text(record.get("remote_head"))
        local_head = _text(record.get("local_head"))
        if not remote_head or pr_head != remote_head:
            return None
        if accepted_head and accepted_head != remote_head:
            return None
        if not local_head or local_head == remote_head:
            return None
    else:
        return None
    try:
@@ -169,7 +169,6 @@ def bind_session_lock(
    *,
    expected_generation: int | None = None,
    renewal_sanctioned: bool = False,
    recovery_sanctioned: bool = False,
 ) -> str:
    """Persist a keyed lock and bind it to the current process session.
@@ -214,9 +213,7 @@ def bind_session_lock(
    try:
        with _exclusive_file_lock(sentinel):
            existing = read_lock_file(path)
-            overwrite_block = assess_foreign_lock_overwrite(
+            overwrite_block = assess_foreign_lock_overwrite(existing, record)
                existing, record, recovery_sanctioned=recovery_sanctioned
            )
            if overwrite_block:
                raise RuntimeError(overwrite_block)
            lease_block = assess_same_issue_lease_conflict(
@@ -225,7 +222,6 @@ def bind_session_lock(
                branch_name=str(record.get("branch_name") or ""),
                worktree_path=str(record.get("worktree_path") or ""),
                renewal_sanctioned=renewal_sanctioned,
                recovery_sanctioned=recovery_sanctioned,
            )
            if lease_block:
                raise RuntimeError(lease_block)
@@ -384,18 +380,7 @@ def assess_lock_freshness(
    pid = lock_data.get("session_pid")
    if pid is None:
        pid = lock_data.get("pid")
-    if pid is None:
+    pid_alive = is_process_alive(pid) if pid is not None else False
        pid = lock_data.get("owner_pid")
    pid_missing = pid is None or str(pid).strip() == ""
    try:
        pid_int = int(pid) if not pid_missing else None
        if pid_int is not None and pid_int <= 0:
            pid_missing = True
            pid_int = None
    except (TypeError, ValueError):
        pid_missing = True
        pid_int = None
    pid_alive = is_process_alive(pid_int) if pid_int is not None else False
    if expires_at and expires_at <= current:
        return {
@@ -404,36 +389,15 @@ def assess_lock_freshness(
            "stale": True,
            "reason": f"lease expired at {expires_at.isoformat()}",
            "pid_alive": pid_alive,
            "pid_missing": pid_missing,
        }
-    # #860: a PID-less lock must never be considered live merely because
+    if pid is not None and not pid_alive:
    # expiration / heartbeat fields are absent. Missing PID is insufficient
    # evidence of a live owner; treat as malformed/stale so recovery routes
    # can evaluate corroborating pins instead of blocking on a false live flag.
    if pid_missing:
        return {
            "status": "malformed",
            "live": False,
            "stale": True,
            "reason": (
                "lock has no usable session pid; cannot prove live ownership "
                "(PID-less locks are never live by missing expiry alone)"
            ),
            "pid_alive": False,
            "pid_missing": True,
            "heartbeat_at": heartbeat_at.isoformat() if heartbeat_at else None,
            "expires_at": expires_at.isoformat() if expires_at else None,
        }
    if pid_int is not None and not pid_alive:
        return {
            "status": "stale",
            "live": False,
            "stale": True,
-            "reason": f"owner pid {pid_int} is not alive",
+            "reason": f"owner pid {pid} is not alive",
            "pid_alive": False,
            "pid_missing": False,
        }
    return {
@@ -442,7 +406,6 @@ def assess_lock_freshness(
        "stale": False,
        "reason": "lock heartbeat and lease are fresh",
        "pid_alive": pid_alive,
        "pid_missing": False,
        "heartbeat_at": heartbeat_at.isoformat() if heartbeat_at else None,
        "expires_at": expires_at.isoformat() if expires_at else None,
    }
@@ -523,7 +486,6 @@ def assess_same_issue_lease_conflict(
    worktree_path: str,
    operation_type: str = AUTHOR_ISSUE_WORK_LEASE,
    renewal_sanctioned: bool = False,
    recovery_sanctioned: bool = False,
    now: datetime | None = None,
 ) -> str | None:
    """Return a fail-closed error when a competing live lease blocks acquisition.
@@ -555,8 +517,6 @@ def assess_same_issue_lease_conflict(
        existing_branch == branch_name
        and _same_realpath(str(existing_worktree or ""), worktree_path)
    )
    if recovery_sanctioned and existing_issue == issue_number and existing_branch == branch_name:
        return None
    if is_lease_expired(existing_lock, now=now):
        # #760 AC1/AC2: exact-owner renewal is a different disposition from
        # foreign takeover and is evaluated first. Before this, both branches
@@ -587,26 +547,10 @@ def assess_same_issue_lease_conflict(
    )
 def _lock_claimant(lock: dict[str, Any] | None) -> dict[str, str]:
    if not isinstance(lock, dict):
        return {}
    claimant = lock.get("claimant")
    if not isinstance(claimant, dict):
        lease = lock.get("work_lease")
        claimant = lease.get("claimant") if isinstance(lease, dict) else None
    if not isinstance(claimant, dict):
        return {}
    return {
        "username": str(claimant.get("username") or ""),
        "profile": str(claimant.get("profile") or ""),
    }
 def assess_foreign_lock_overwrite(
    existing_lock: dict[str, Any] | None,
    incoming_lock: dict[str, Any],
    *,
    recovery_sanctioned: bool = False,
    now: datetime | None = None,
 ) -> str | None:
    """Block writes that would clobber an unrelated live lease on the same key."""
@@ -621,31 +565,8 @@ def assess_foreign_lock_overwrite(
    )
    if same_issue and same_branch and same_worktree:
        return None
    existing_claimant = _lock_claimant(existing_lock)
    incoming_claimant = _lock_claimant(incoming_lock)
    same_claimant = (
        bool(existing_claimant.get("username"))
        and existing_claimant.get("username") == incoming_claimant.get("username")
        and existing_claimant.get("profile") == incoming_claimant.get("profile")
    )
    if recovery_sanctioned and same_issue and same_branch and same_claimant:
        return None
    if not is_lease_live(existing_lock, now=now):
        # #860 F8: A non-live or PID-less lock still blocks foreign overwrite
        # unless same claimant or sanctioned reclaim is proven.
        if not same_claimant and same_issue:
            reclaim = assess_expired_lock_reclaim(existing_lock, now=now)
            if not reclaim.get("reclaim_allowed"):
                return (
                    "Refusing foreign overwrite of non-live issue lock "
                    f"(issue #{existing_lock.get('issue_number')}, owner '{existing_claimant.get('username')}') "
                    "without sanctioned reclaim proof (fail closed)"
                )
        return None
    return (
        "Refusing to overwrite a live foreign issue lock "
        f"(issue #{existing_lock.get('issue_number')}, "
@@ -816,308 +737,4 @@ def format_lock_proof(
        parts.append("lock released")
    elif released is False:
        parts.append("lock retained")
-    return "; ".join(parts)
+    return "; ".join(parts)
 # ── #871: durable linked-issue lock head refresh after branch synchronization ──
 _FULL_SHA_RE = re.compile(r"^[0-9a-f]{40}$", re.IGNORECASE)
 # Provenance recorded on the lock when the head is refreshed by a sanctioned
 # merge-based branch synchronization (``gitea_update_pr_branch_by_merge``).
 LOCK_HEAD_REFRESH_PROVENANCE_MERGE_SYNC = "gitea_update_pr_branch_by_merge"
 def _norm_sha(value: Any) -> str | None:
    text = str(value or "").strip().lower()
    return text if _FULL_SHA_RE.match(text) else None
 def _lock_claimant_view(lock: dict[str, Any] | None) -> dict[str, Any]:
    if not isinstance(lock, dict):
        return {}
    claimant = lock.get("claimant")
    if not isinstance(claimant, dict):
        lease = lock.get("work_lease")
        claimant = lease.get("claimant") if isinstance(lease, dict) else None
    return dict(claimant) if isinstance(claimant, dict) else {}
 def assess_durable_lock_head_refresh(
    existing_lock: dict[str, Any] | None,
    *,
    remote: str,
    org: str,
    repo: str,
    issue_number: int,
    branch_name: str,
    worktree_path: str,
    pr_number: int | None,
    identity: str | None,
    profile: str | None,
    current_pid: int | None,
    expected_old_head: str | None,
    new_head: str | None,
    base_head: str | None = None,
 ) -> dict[str, Any]:
    """Fail-closed assessment for refreshing a durable lock's recorded head (#871).
    A successful ``gitea_update_pr_branch_by_merge`` advances the *remote* PR head
    but must also advance the durable linked-issue lock so a later dead-session
    recovery can prove ownership. This decides whether that refresh is permitted;
    it mutates nothing.
    Every element of durable ownership is re-verified against the persisted lock —
    repository, issue, branch, worktree, claimant identity/profile, and the live
    owning session — and the recorded head is compare-and-swapped: the lock's
    currently recorded synced head (if any) must equal ``expected_old_head``, so a
    lock whose head or provenance changed concurrently is never overwritten.
    """
    reasons: list[str] = []
    old = _norm_sha(expected_old_head)
    new = _norm_sha(new_head)
    evidence: dict[str, Any] = {
        "issue_number": issue_number,
        "branch_name": branch_name,
        "worktree_path": worktree_path,
        "pr_number": pr_number,
        "expected_old_head": old,
        "new_head": new,
        "base_head": _norm_sha(base_head),
    }
    if not isinstance(existing_lock, dict) or not existing_lock:
        reasons.append("no durable lock exists for this issue; nothing to refresh")
        return {"allowed": False, "reasons": reasons, "evidence": evidence,
                "expected_generation": 0}
    lock = dict(existing_lock)
    evidence["current_generation"] = lock_generation(lock)
    if lock.get("issue_number") != issue_number:
        reasons.append(
            f"durable lock targets issue #{lock.get('issue_number')}, not "
            f"#{issue_number}; refusing head refresh"
        )
    for field, expected in (("remote", remote), ("org", org), ("repo", repo)):
        actual = str(lock.get(field) or "").strip()
        if actual != str(expected or "").strip():
            reasons.append(
                f"lock {field} '{actual}' does not match requested "
                f"'{str(expected or '').strip()}'"
            )
    locked_branch = str(lock.get("branch_name") or "").strip()
    if locked_branch != str(branch_name or "").strip():
        reasons.append(
            f"lock branch '{locked_branch}' does not match requested "
            f"'{str(branch_name or '').strip()}'"
        )
    locked_worktree = str(lock.get("worktree_path") or "").strip()
    try:
        same_wt = bool(locked_worktree) and bool(worktree_path) and (
            os.path.realpath(locked_worktree) == os.path.realpath(worktree_path)
        )
    except OSError:
        same_wt = locked_worktree == (worktree_path or "")
    if not same_wt:
        reasons.append(
            f"lock worktree '{locked_worktree}' does not match declared "
            f"'{str(worktree_path or '').strip()}'"
        )
    claimant = _lock_claimant_view(lock)
    locked_identity = str(claimant.get("username") or "").strip()
    locked_profile = str(claimant.get("profile") or "").strip()
    if not locked_identity or not locked_profile:
        reasons.append(
            "durable lock does not record a claimant identity/profile; "
            "ownership could not be proven for head refresh"
        )
    if not str(identity or "").strip() or not str(profile or "").strip():
        reasons.append(
            "active session identity/profile is unknown; ownership could not be "
            "proven for head refresh"
        )
    if locked_identity and str(identity or "").strip() and locked_identity != str(identity).strip():
        reasons.append(
            f"lock claimant '{locked_identity}' does not match active identity "
            f"'{str(identity).strip()}'"
        )
    if locked_profile and str(profile or "").strip() and locked_profile != str(profile).strip():
        reasons.append(
            f"lock profile '{locked_profile}' does not match active profile "
            f"'{str(profile).strip()}'"
        )
    # The refresh is written by the LIVE owning author session. A refresh is not
    # a recovery: the current process must be the recorded owner.
    recorded_pid = lock.get("session_pid")
    if recorded_pid is None:
        recorded_pid = lock.get("pid")
    evidence["recorded_pid"] = recorded_pid
    evidence["current_pid"] = current_pid
    if current_pid is None:
        reasons.append("current session pid is unknown; cannot prove live ownership")
    else:
        try:
            if recorded_pid is None or int(recorded_pid) != int(current_pid):
                reasons.append(
                    f"durable lock is owned by pid {recorded_pid}, not the current "
                    f"session pid {current_pid}; head refresh requires the live owner"
                )
        except (TypeError, ValueError):
            reasons.append(
                "durable lock owner pid is malformed; cannot prove live ownership"
            )
    if not old:
        reasons.append("expected_old_head is not a full 40-char hex SHA (fail closed)")
    if not new:
        reasons.append("new_head is not a full 40-char hex SHA (fail closed)")
    if old and new and old == new:
        reasons.append(
            "new head equals the expected old head; a sync must advance the head"
        )
    # Compare-and-swap on the recorded head: if the lock already records a synced
    # head it must be exactly the expected old head, else another sync moved it.
    recorded_synced = _norm_sha(lock.get("synced_pr_head"))
    evidence["recorded_synced_pr_head"] = recorded_synced
    if recorded_synced is not None and old is not None and recorded_synced != old:
        reasons.append(
            f"durable lock already records synced head {recorded_synced}, not the "
            f"expected old head {old}; a concurrent sync changed it (CAS fail closed)"
        )
    if reasons:
        return {"allowed": False, "reasons": reasons, "evidence": evidence,
                "expected_generation": lock_generation(lock)}
    return {
        "allowed": True,
        "reasons": [
            f"durable lock for issue #{issue_number} branch '{locked_branch}' is "
            f"owned by the live session; refresh recorded head {old} -> {new}"
        ],
        "evidence": evidence,
        "expected_generation": lock_generation(lock),
    }
 def apply_durable_lock_head_refresh(
    *,
    remote: str,
    org: str,
    repo: str,
    issue_number: int,
    branch_name: str,
    worktree_path: str,
    pr_number: int | None,
    identity: str | None,
    profile: str | None,
    current_pid: int | None,
    expected_old_head: str | None,
    new_head: str | None,
    synced_at: str,
    base_head: str | None = None,
    provenance: str = LOCK_HEAD_REFRESH_PROVENANCE_MERGE_SYNC,
    lock_dir: str | None = None,
 ) -> dict[str, Any]:
    """CAS-refresh the durable lock's recorded head after a branch sync (#871).
    Reads the durable lock from disk, re-asserts ownership via
    ``assess_durable_lock_head_refresh``, and — only when permitted — writes the
    new synced head through ``bind_session_lock`` with a generation compare-and-
    swap. Then re-reads the lock and proves it records the complete new head
    (read-after-write). Any failure at any step returns ``refreshed=False`` with
    reasons; the caller must treat that as a partial lifecycle failure and never
    report a fully successful synchronization.
    """
    existing = load_issue_lock(
        remote=remote, org=org, repo=repo, issue_number=issue_number, lock_dir=lock_dir
    )
    assessment = assess_durable_lock_head_refresh(
        existing,
        remote=remote,
        org=org,
        repo=repo,
        issue_number=issue_number,
        branch_name=branch_name,
        worktree_path=worktree_path,
        pr_number=pr_number,
        identity=identity,
        profile=profile,
        current_pid=current_pid,
        expected_old_head=expected_old_head,
        new_head=new_head,
        base_head=base_head,
    )
    result: dict[str, Any] = {
        "refreshed": False,
        "read_after_write_ok": False,
        "prior_head": _norm_sha(expected_old_head),
        "new_head": _norm_sha(new_head),
        "reasons": list(assessment.get("reasons") or []),
        "evidence": assessment.get("evidence"),
    }
    if not assessment.get("allowed"):
        return result
    new = _norm_sha(new_head)
    old = _norm_sha(expected_old_head)
    record = dict(existing or {})
    sync_block = {
        "last_synced_pr_head": new,
        "prior_pr_head": old,
        "base_head": _norm_sha(base_head),
        "pr_number": pr_number,
        "provenance": provenance,
        "synced_at": synced_at,
        "synced_by_pid": current_pid,
        "synced_by": {
            "username": str(identity or "").strip() or None,
            "profile": str(profile or "").strip() or None,
        },
    }
    record["synced_pr_head"] = new
    record["branch_sync"] = sync_block
    history = record.get("branch_sync_history")
    if not isinstance(history, list):
        history = []
    history = list(history)
    history.append(sync_block)
    record["branch_sync_history"] = history
    try:
        bind_session_lock(
            record,
            lock_dir=lock_dir,
            expected_generation=assessment.get("expected_generation"),
            renewal_sanctioned=True,
        )
    except Exception as exc:  # CAS miss or write failure — partial lifecycle failure
        result["reasons"].append(
            f"durable lock head refresh write failed (fail closed): {exc}"
        )
        return result
    after = load_issue_lock(
        remote=remote, org=org, repo=repo, issue_number=issue_number, lock_dir=lock_dir
    )
    after_head = _norm_sha((after or {}).get("synced_pr_head"))
    result["lock_generation_after"] = lock_generation(after)
    if after_head == new and new is not None:
        result["refreshed"] = True
        result["read_after_write_ok"] = True
        result["reasons"].append(
            f"durable lock recorded head refreshed to {new} and verified by "
            "read-after-write"
        )
    else:
        result["reasons"].append(
            "read-after-write verification failed: durable lock does not record "
            f"the new head {new} (found {after_head}); partial lifecycle failure"
        )
    return result
@@ -145,175 +145,6 @@ def read_head_ancestry(
    return result
 def read_merge_sync_provenance(
    worktree_path: str,
    *,
    prior_head_sha: str | None,
    synced_head_sha: str | None,
 ) -> dict:
    """Observe whether ``synced_head_sha`` is a sanctioned merge-based branch sync
    that advanced the PR branch past ``prior_head_sha`` (#871).
    ``gitea_update_pr_branch_by_merge`` advances a PR branch by merging the base
    branch *into* the branch (``POST /pulls/{n}/update?style=merge``). The result
    is a merge commit ``M`` on the branch whose **first** parent is the prior
    branch head and whose second parent is the base tip. When the owning session
    then dies without the durable lock's recorded head being refreshed, the local
    worktree still sits at ``prior_head_sha`` while the live PR head is ``M``.
    Recovering that drift safely requires proving the remote head is *exactly*
    such a merge-sync — not a rewrite, rebase, force-push, or an unrelated
    commit. This is that server-side observation. It reports facts only; the
    disposition lives in ``issue_lock_recovery``. Every field is read from git in
    the declared worktree — nothing is supplied by, or reachable from, an MCP
    caller (#871).
    Provenance is proven only when ALL hold:
    * both commits are present (a rewritten/force-moved prior head leaves the
      object graph and fails closed);
    * ``prior_head_sha`` is a strict ancestor of ``synced_head_sha`` (the branch
      history is preserved, never replaced);
    * ``synced_head_sha`` is a merge commit (two or more parents), i.e. a base
      merged in — a plain fast-forward of new direct commits is not a sync;
    * ``prior_head_sha`` is an ancestor of the merge's **first** parent, so the
      branch mainline (first-parent lineage) still reaches the prior head — a
      rebase/force-push that re-authored the branch side fails this.
    """
    path = (worktree_path or "").strip()
    prior = (prior_head_sha or "").strip()
    synced = (synced_head_sha or "").strip()
    result: dict = {
        "prior_head_sha": prior or None,
        "synced_head_sha": synced or None,
        "probe_ok": False,
        "prior_present": False,
        "synced_present": False,
        "prior_is_ancestor": False,
        "synced_is_merge": False,
        "first_parent_reaches_prior": False,
        "is_merge_sync": False,
        "first_parent_sha": None,
        "parent_count": None,
        "proof": None,
        "reasons": [],
    }
    if not path or not prior or not synced:
        result["reasons"].append(
            "merge-sync provenance probe requires a worktree path and both "
            "commit SHAs"
        )
        return result
    if prior == synced:
        result["reasons"].append(
            "prior and synced heads are identical; no branch sync occurred"
        )
        return result
    def _present(sha: str) -> bool:
        res = subprocess.run(
            ["git", "-C", path, "rev-parse", "--verify", "--quiet", f"{sha}^{{commit}}"],
            capture_output=True,
            text=True,
            check=False,
        )
        return res.returncode == 0
    def _is_ancestor(ancestor: str, descendant: str) -> bool | None:
        res = subprocess.run(
            ["git", "-C", path, "merge-base", "--is-ancestor", ancestor, descendant],
            capture_output=True,
            text=True,
            check=False,
        )
        if res.returncode == 0:
            return True
        if res.returncode == 1:
            return False
        return None  # failed probe — never a silent "no"
    try:
        result["prior_present"] = _present(prior)
        result["synced_present"] = _present(synced)
    except OSError as exc:  # git unavailable — fail closed, never assume
        result["reasons"].append(f"merge-sync provenance probe could not run: {exc}")
        return result
    if not result["prior_present"]:
        result["reasons"].append(
            f"prior head {prior} is not reachable in '{path}'; history may have "
            "been rewritten or force-moved"
        )
    if not result["synced_present"]:
        result["reasons"].append(
            f"synced head {synced} is not reachable in '{path}'"
        )
    if not (result["prior_present"] and result["synced_present"]):
        return result
    ancestor = _is_ancestor(prior, synced)
    if ancestor is None:
        result["reasons"].append(
            "ancestry probe failed; merge-sync provenance unproven"
        )
        return result
    result["prior_is_ancestor"] = bool(ancestor)
    if not ancestor:
        result["reasons"].append(
            f"prior head {prior} is not an ancestor of synced head {synced}; "
            "the branch history was not preserved (not a merge-based sync)"
        )
        return result
    parents_res = subprocess.run(
        ["git", "-C", path, "rev-list", "--parents", "-n", "1", synced],
        capture_output=True,
        text=True,
        check=False,
    )
    if parents_res.returncode != 0:
        result["reasons"].append(
            f"could not read parents of {synced}; merge-sync provenance unproven"
        )
        return result
    tokens = (parents_res.stdout or "").split()
    # tokens[0] is the commit itself; the rest are its parents.
    parents = tokens[1:]
    result["parent_count"] = len(parents)
    result["synced_is_merge"] = len(parents) >= 2
    if not result["synced_is_merge"]:
        result["probe_ok"] = True
        result["reasons"].append(
            f"synced head {synced} has {len(parents)} parent(s); a merge-based "
            "branch sync produces a merge commit (two or more parents)"
        )
        return result
    first_parent = parents[0]
    result["first_parent_sha"] = first_parent
    fp_reaches = _is_ancestor(prior, first_parent) if prior != first_parent else True
    if fp_reaches is None:
        result["reasons"].append(
            "first-parent ancestry probe failed; merge-sync provenance unproven"
        )
        return result
    result["first_parent_reaches_prior"] = bool(fp_reaches)
    result["probe_ok"] = True
    if not fp_reaches:
        result["reasons"].append(
            f"merge first parent {first_parent} does not reach prior head "
            f"{prior}; the branch mainline was re-authored (not a sanctioned sync)"
        )
        return result
    result["is_merge_sync"] = True
    result["proof"] = (
        f"synced head {synced} is a merge commit (parents={len(parents)}) whose "
        f"first-parent lineage reaches prior head {prior}; base merged into branch"
    )
    return result
 def read_recorded_base(
    worktree_path: str,
    *,
@@ -39,7 +39,6 @@ SAFE_RELEASE_OWNED = "release_owned"
 SAFE_STALE_PROMPT = "stale_prompt_lease"
 SAFE_UNKNOWN = "inspect_only"
 SAFE_NO_AUTHORITY = "file_or_comment_not_authoritative"
 SAFE_CONSUME_CROSS_ROLE = "consume_cross_role_handoff"
 LEASE_STATUS_ACTIVE = "active"
 LEASE_STATUS_RELEASED = "released"
@@ -251,23 +250,6 @@ def decide_safe_next_action(
                "same_owner": True,
                "also_allowed": [SAFE_ABANDON_ALLOWED, SAFE_RELEASE_OWNED],
            }
        handoff = is_pending_cross_role_handoff({"lease": lease})
        if handoff:
            return {
                "safe_next_action": SAFE_CONSUME_CROSS_ROLE,
                "reasons": [
                    f"controller allocation pending handoff (freshness={status}); "
                    "required-role worker may consume without abandon/reassign; "
                    f"required_role={handoff['required_role']}"
                ],
                "block": False,
                "same_owner": False,
                "owner_session_id": owner,
                "required_role": handoff["required_role"],
                "cross_role_handoff": True,
                "handoff_status": "pending",
                "also_allowed": [SAFE_ABANDON_ALLOWED],
            }
        return {
            "safe_next_action": SAFE_ABANDON_ALLOWED,
            "reasons": [
@@ -290,24 +272,6 @@ def decide_safe_next_action(
        }
    if not same_owner and status == "active":
        # #843: pending cross-role handoff is consumable by required role
        handoff = is_pending_cross_role_handoff({"lease": lease})
        if handoff:
            return {
                "safe_next_action": SAFE_CONSUME_CROSS_ROLE,
                "reasons": [
                    "controller cross-role allocation pending handoff; "
                    f"required_role={handoff['required_role']}; "
                    "consume via gitea_adopt_workflow_lease without "
                    "abandonment or sharing the controller session"
                ],
                "block": False,
                "same_owner": False,
                "owner_session_id": owner,
                "required_role": handoff["required_role"],
                "cross_role_handoff": True,
                "handoff_status": "pending",
            }
        return {
            "safe_next_action": SAFE_WAIT_FOREIGN,
            "reasons": [
@@ -476,84 +440,6 @@ def list_active_leases(
    }
 def parse_lease_provenance(lease_or_state: Mapping[str, Any] | None) -> dict[str, Any]:
    """Return durable lease provenance dict (empty when absent/unparseable)."""
    if not lease_or_state:
        return {}
    if "provenance" in lease_or_state and isinstance(lease_or_state.get("provenance"), dict):
        return dict(lease_or_state["provenance"])
    raw = None
    if "provenance_json" in lease_or_state:
        raw = lease_or_state.get("provenance_json")
    elif "lease" in lease_or_state and isinstance(lease_or_state.get("lease"), Mapping):
        raw = lease_or_state["lease"].get("provenance_json")
    if not raw:
        return {}
    if isinstance(raw, dict):
        return dict(raw)
    try:
        loaded = json.loads(raw)
    except (TypeError, json.JSONDecodeError):
        return {}
    return dict(loaded) if isinstance(loaded, dict) else {}
 def is_pending_cross_role_handoff(
    state: Mapping[str, Any] | None,
 ) -> dict[str, Any] | None:
    """Return handoff evidence when a controller allocation awaits consume (#843).
    A pending handoff is identified by durable provenance written at
    cross-role apply time — not by title heuristics or session-id guessing.
    """
    if not state:
        return None
    lease = state.get("lease") if isinstance(state.get("lease"), Mapping) else state
    if not isinstance(lease, Mapping):
        return None
    status = str(lease.get("status") or "").strip().lower()
    if status in (LEASE_STATUS_ABANDONED, LEASE_STATUS_RELEASED, LEASE_STATUS_EXPIRED):
        return None
    prov = parse_lease_provenance(state)
    if not prov and isinstance(lease, Mapping):
        prov = parse_lease_provenance(lease)
    if not prov.get("cross_role_handoff"):
        return None
    handoff_status = str(prov.get("handoff_status") or "pending").strip().lower()
    if handoff_status != "pending":
        return None
    adopted_by = (
        lease.get("adopted_by_session_id")
        or prov.get("adopted_by_session_id")
        or ""
    )
    if str(adopted_by).strip():
        return None
    required_role = str(
        prov.get("required_role") or lease.get("role") or ""
    ).strip().lower()
    if not required_role:
        return None
    return {
        "cross_role_handoff": True,
        "handoff_status": "pending",
        "required_role": required_role,
        "allocating_session_id": str(
            prov.get("allocating_session_id") or lease.get("session_id") or ""
        ),
        "allocating_role": str(prov.get("allocating_role") or "controller"),
        "lease_id": str(lease.get("lease_id") or ""),
        "assignment_id": (
            str(state["assignment"]["assignment_id"])
            if isinstance(state.get("assignment"), Mapping)
            and state["assignment"].get("assignment_id")
            else None
        ),
        "provenance": prov,
    }
 def adopt_lease(
    db: cpd.ControlPlaneDB,
    *,
@@ -564,17 +450,8 @@ def adopt_lease(
    expected_head_sha: str | None = None,
    owner_pid: int | None = None,
    operator_authorized: bool = False,
    adopter_profile_name: str | None = None,
    adopter_namespace: str | None = None,
 ) -> dict[str, Any]:
-    """Sanctioned adopt path with provenance; never silent foreign steal.
+    """Sanctioned adopt path with provenance; never silent foreign steal."""
    #843 F1: for a pending cross-role handoff, ``role`` must be the
    authoritative profile-derived role supplied by the MCP boundary — never
    caller-asserted authority. When the handoff provenance declares
    ``required_profile`` / ``required_namespace`` and the caller context is
    provided, both are validated exactly; a mismatch fails closed.
    """
    state = db.get_lease_workflow_state(lease_id)
    if not state:
        raise LeaseLifecycleError(
@@ -586,8 +463,11 @@ def adopt_lease(
    owner = str(lease.get("session_id") or "")
    same_owner = owner == str(adopter_session_id)
-    handoff = is_pending_cross_role_handoff(state)
+    if freshness["freshness"] == "active" and not same_owner:
-    adopter_role = (role or "").strip().lower()
+        raise LeaseLifecycleError(
            f"refusing to steal active foreign lease {lease_id} owned by "
            f"{owner} (fail closed)"
        )
    if freshness["freshness"] in ("abandoned", "released"):
        raise LeaseLifecycleError(
@@ -595,64 +475,13 @@ def adopt_lease(
            "(fail closed)"
        )
-    if handoff and not same_owner:
+    # Expired or stale: require abandon-style safety before ownership transfer
-        # Terminal statuses already rejected above. Freshness may be
+    # when not same owner; same owner may reclaim.
-        # active OR stale_dead_process (controller exited) — both are
+    if not same_owner and freshness["freshness"] in (
        # consumable without abandonment when handoff is still pending.
        if freshness["freshness"] not in (
            "active",
            "stale_dead_process",
            "stale_missing_worktree",
        ):
            raise LeaseLifecycleError(
                f"lease {lease_id} freshness={freshness['freshness']}; "
                "terminal or non-active allocation cannot be handoff-consumed "
                "(fail closed)"
            )
        required = handoff["required_role"]
        if adopter_role != required:
            raise LeaseLifecycleError(
                f"wrong role for cross-role handoff consume of {lease_id}: "
                f"required={required} adopter={adopter_role or 'none'} "
                "(fail closed)"
            )
        # #843 F1: provenance profile/namespace restrictions are validated
        # against the authoritative caller context when declared. Caller
        # input can never widen authority; a mismatch fails closed.
        handoff_prov = handoff.get("provenance") or {}
        required_profile = str(
            handoff_prov.get("required_profile") or ""
        ).strip()
        if required_profile and adopter_profile_name is not None:
            if str(adopter_profile_name).strip() != required_profile:
                raise LeaseLifecycleError(
                    f"wrong profile for cross-role handoff consume of "
                    f"{lease_id}: required_profile={required_profile} "
                    f"adopter_profile={adopter_profile_name} (fail closed)"
                )
        required_namespace = str(
            handoff_prov.get("required_namespace") or ""
        ).strip()
        if required_namespace and adopter_namespace is not None:
            if str(adopter_namespace).strip() != required_namespace:
                raise LeaseLifecycleError(
                    f"wrong namespace for cross-role handoff consume of "
                    f"{lease_id}: required_namespace={required_namespace} "
                    f"adopter_namespace={adopter_namespace} (fail closed)"
                )
        reason = "cross-role-handoff-consume"
    elif freshness["freshness"] == "active" and not same_owner:
        raise LeaseLifecycleError(
            f"refusing to steal active foreign lease {lease_id} owned by "
            f"{owner} (fail closed)"
        )
    elif not same_owner and freshness["freshness"] in (
        "expired",
        "stale_dead_process",
        "stale_missing_worktree",
    ):
        # Expired or stale (non-handoff): require abandon-style safety before
        # ownership transfer when not same owner; same owner may reclaim.
        if not operator_authorized and freshness["freshness"] == "expired":
            # Deterministic reclaim of expired foreign lease is allowed
            # without operator flag (sanctioned expire reclaim).
@@ -663,9 +492,6 @@ def adopt_lease(
                f"lease {lease_id} freshness={freshness['freshness']}; "
                "use abandon with proof before foreign adopt (fail closed)"
            )
        reason = "sanctioned-reclaim-adopt"
    else:
        reason = "owner-resume-adopt" if same_owner else "sanctioned-reclaim-adopt"
    provenance = build_adopt_provenance(
        adopted_from_session_id=owner,
@@ -678,14 +504,10 @@ def adopt_lease(
        worktree_path=worktree_path,
        expected_head_sha=expected_head_sha or lease.get("expected_head_sha"),
        prior_lease_id=lease_id,
-        reason=reason,
+        reason=(
            "owner-resume-adopt" if same_owner else "sanctioned-reclaim-adopt"
        ),
    )
    if handoff and not same_owner:
        provenance["cross_role_handoff"] = True
        provenance["handoff_status"] = "adopted"
        provenance["required_role"] = handoff["required_role"]
        provenance["allocating_session_id"] = handoff["allocating_session_id"]
        provenance["allocating_role"] = handoff["allocating_role"]
    result = db.adopt_lease(
        lease_id=lease_id,
@@ -696,7 +518,7 @@ def adopt_lease(
        owner_pid=owner_pid if owner_pid is not None else os.getpid(),
        provenance=provenance,
    )
-    out = {
+    return {
        "success": True,
        "outcome": result.get("outcome"),
        "same_owner": same_owner,
@@ -709,24 +531,6 @@ def adopt_lease(
        "comment_lease_only": False,
        "reasons": result.get("reasons") or [],
    }
    if handoff and not same_owner:
        out["cross_role_handoff"] = True
        out["handoff_status"] = "adopted"
        out["required_role"] = handoff["required_role"]
        out["adopted_by_session_id"] = adopter_session_id
        out["adopted_from_session_id"] = owner
        lease_row = result.get("lease") or {}
        if isinstance(lease_row, Mapping):
            out["read_after_write"] = {
                "lease_id": lease_row.get("lease_id"),
                "session_id": lease_row.get("session_id"),
                "role": lease_row.get("role"),
                "status": lease_row.get("status"),
                "adopted_by_session_id": lease_row.get("adopted_by_session_id"),
                "adopted_from_session_id": lease_row.get("adopted_from_session_id"),
                "phase": lease_row.get("phase"),
            }
    return out
 def release_lease(
@@ -1,475 +0,0 @@
 """Inventory and fail-closed guards for MCP restart/reload/kill paths (#657).
 Single source of truth enumerating every code/script/doc path that can
 restart, reload, reconnect, kill, or force-recreate an MCP process. Each path
 is classified and linked to the guard that constrains it. The companion
 human-readable inventory lives in ``docs/mcp-restart-path-inventory.md`` and is
 kept in lock-step with this module by ``tests/test_mcp_restart_paths.py``.
 Design intent (aligns with #655 restart-coordinator roadmap):
 * **No unguarded full restart.** The in-process MCP daemon
  (``gitea_mcp_server.py`` / ``mcp_server.py`` / ``role_session_router.py``)
  must never replace or kill its own process — replacing the process after the
  host wired up the stdio pipes desyncs the JSON-RPC transport (observed with
  Antigravity/Cascade hosts). ``assert_no_daemon_self_replacement`` enforces
  this against the live source tree.
 * **No legacy auto-restart helper.** ``_trigger_mcp_auto_restart`` was removed
  when the stale-runtime resolver became side-effect free (#685);
  ``assert_auto_restart_helper_absent`` keeps it removed.
 * **Unknown restart attempts fail closed.** LLM tools must route any restart
  intent through a *registered* path. ``assert_restart_attempt_registered``
  raises ``UnknownRestartPathError`` for anything not in this inventory.
 * **pkill stays forbidden (#630).** Manual daemon kills are classified as
  contamination by :mod:`runtime_recovery_guard`; this module records that path
  and the test asserts the classification still holds.
 This module performs no restarts, spawns no threads, and touches no config or
 process state. It is pure inventory + read-only source assertions.
 """
 from __future__ import annotations
 import os
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Iterable
 # --- Classifications -------------------------------------------------------
 #: A narrow, one-shot recovery that is safe by construction (e.g. a CLI wrapper
 #: re-execing into the venv interpreter before importing anything, or an
 #: in-process profile switch). Never targets the running MCP daemon process.
 CLASS_SANCTIONED_NARROW = "sanctioned_narrow_recovery"
 #: The path detects a condition that would require a restart, then *fails
 #: closed* on mutations and emits restart/reconnect guidance. It never restarts
 #: the process itself (recovery is owned by the host/operator).
 CLASS_GUARDED_FAIL_CLOSED = "guarded_fail_closed"
 #: The path is forbidden. Attempting it is a workflow-safety violation and,
 #: where an LLM tool could invoke it, is marked as contamination.
 CLASS_FORBIDDEN = "forbidden"
 #: A previously-existing unguarded restart primitive that has been deleted. A
 #: regression guard keeps it absent.
 CLASS_REMOVED = "removed"
 #: Behavior that lives in the host/IDE and is outside this process's control
 #: (e.g. a manual ``/mcp reconnect``). Documented, not code-guarded here.
 CLASS_HOST_RESIDUAL = "host_residual"
 VALID_CLASSIFICATIONS = frozenset(
    {
        CLASS_SANCTIONED_NARROW,
        CLASS_GUARDED_FAIL_CLOSED,
        CLASS_FORBIDDEN,
        CLASS_REMOVED,
        CLASS_HOST_RESIDUAL,
    }
 )
 #: The in-process MCP daemon modules. These must never self-replace/self-kill.
 DAEMON_MODULES = (
    "gitea_mcp_server.py",
    "mcp_server.py",
    "role_session_router.py",
 )
 #: The legacy auto-restart helper removed in #685. Must stay removed.
 LEGACY_AUTO_RESTART_HELPER = "_trigger_mcp_auto_restart"
 #: Call patterns that would let the daemon replace or terminate its own
 #: process. Matched as calls (trailing ``(``) so prose/docstring mentions such
 #: as "we do NOT os.execv() here" or "never calls ``os._exit``" do not trip the
 #: scanner (comment lines are stripped first regardless).
 DAEMON_SELF_REPLACEMENT_PRIMITIVES = (
    "os.execv(",
    "os.execve(",
    "os.execvp(",
    "os.execvpe(",
    "os.kill(",
    "os.killpg(",
    "os._exit(",
    "os.abort(",
 )
@dataclass(frozen=True)
 class RestartPath:
    """One classified restart/reload/kill path in the inventory."""
    path_id: str
    title: str
    mechanism: str
    classification: str
    guard: str
    locations: tuple[str, ...]
    references: tuple[str, ...]
    residual_host: bool = False
    notes: str = ""
 class UnknownRestartPathError(RuntimeError):
    """Raised when a restart attempt is not a registered, classified path."""
 # --- The inventory ---------------------------------------------------------
 _RESTART_PATHS: tuple[RestartPath, ...] = (
    RestartPath(
        path_id="cli_venv_bootstrap_execv",
        title="CLI wrapper venv re-exec",
        mechanism=(
            "Standalone CLI scripts re-exec into venv/bin/python3 via os.execv "
            "at import top, guarded by `sys.executable != venv_python`."
        ),
        classification=CLASS_SANCTIONED_NARROW,
        guard=(
            "One-shot, pre-import bootstrap; runs before any MCP transport "
            "exists and only when not already on the venv interpreter, so it "
            "cannot desync a live daemon. Idempotent guard condition prevents "
            "a re-exec loop."
        ),
        locations=(
            "create_pr.py",
            "create_issue.py",
            "close_issue.py",
            "merge_pr.py",
            "review_pr.py",
            "edit_pr.py",
            "delete_branch.py",
            "mark_issue.py",
            "manage_labels.py",
            "list_issues.py",
            "list_prs.py",
        ),
        references=("#657",),
    ),
    RestartPath(
        path_id="daemon_self_replacement",
        title="MCP daemon self-replacement",
        mechanism=(
            "The in-process MCP daemon replacing/terminating its own process "
            "(os.execv/os.kill/os._exit) to reload code."
        ),
        classification=CLASS_FORBIDDEN,
        guard=(
            "Forbidden by design: replacing the process after the host wired "
            "up stdio desyncs JSON-RPC (Antigravity/Cascade). Enforced against "
            "the source tree by assert_no_daemon_self_replacement()."
        ),
        locations=("gitea_mcp_server.py:~155 (decision comment)",) + DAEMON_MODULES,
        references=("#657", "#584"),
    ),
    RestartPath(
        path_id="legacy_auto_restart_helper",
        title="Legacy _trigger_mcp_auto_restart helper",
        mechanism=(
            "A helper that actively restarted the MCP server from the "
            "read-only resolver path."
        ),
        classification=CLASS_REMOVED,
        guard=(
            "Removed in #685 when the resolver became side-effect free. Kept "
            "absent by assert_auto_restart_helper_absent()."
        ),
        locations=("gitea_mcp_server.py", "mcp_server.py"),
        references=("#685", "#657"),
    ),
    RestartPath(
        path_id="config_touch_reload",
        title="MCP client config-touch reload",
        mechanism=(
            "Touching (utime) the MCP client config file to make the host "
            "reload/recreate the server process."
        ),
        classification=CLASS_REMOVED,
        guard=(
            "Removed from the resolver in #685: stale-runtime detection is "
            "report-only and never mutates client config, spawns threads, or "
            "calls os._exit."
        ),
        locations=("gitea_mcp_server.py (resolve_task_capability)",),
        references=("#685", "#657"),
    ),
    RestartPath(
        path_id="master_advance_auto_restart",
        title="Master-advance staleness gate",
        mechanism=(
            "On-disk master advancing past the running code. The master-parity "
            "gate detects it and fails mutations closed with restart guidance."
        ),
        classification=CLASS_GUARDED_FAIL_CLOSED,
        guard=(
            "Detect + fail closed only; the process never self-restarts. "
            "master_parity_gate captures startup parity and blocks mutations "
            "while stale, emitting restart/reconnect guidance."
        ),
        locations=(
            "master_parity_gate.py",
            "gitea_mcp_server.py (gitea_assess_master_parity)",
        ),
        references=("#420", "#591", "#657"),
    ),
    RestartPath(
        path_id="stale_runtime_resolver_reconnect",
        title="Stale-runtime resolver reconnect guidance",
        mechanism=(
            "The capability resolver detecting a stale serving process and "
            "reporting restart_required/stop_required for a client reconnect."
        ),
        classification=CLASS_GUARDED_FAIL_CLOSED,
        guard=(
            "Report-only (#685): returns restart_required/stop_required and an "
            "exact_safe_next_action pointing at IDE/client reconnect; performs "
            "no restart, thread spawn, config touch, or os._exit."
        ),
        locations=("gitea_mcp_server.py (gitea_resolve_task_capability)",),
        references=("#685", "#657"),
    ),
    RestartPath(
        path_id="manual_daemon_kill",
        title="Manual daemon kill (pkill/killall/kill)",
        mechanism=(
            "Shell kills of the MCP daemon: `pkill -f mcp_server.py`, "
            "`killall`, broad `pkill -f python` sweeps, or `kill <pid>` of a "
            "daemon pid."
        ),
        classification=CLASS_FORBIDDEN,
        guard=(
            "Forbidden (#630): runtime_recovery_guard classifies these as "
            "contamination and gitea_record_daemon_process_kill_attempt writes "
            "a durable marker that fails subsequent mutations closed. Operator "
            "maintenance authorization is read only from the environment, not "
            "from a tool argument."
        ),
        locations=(
            "runtime_recovery_guard.py",
            "gitea_mcp_server.py (gitea_record_daemon_process_kill_attempt)",
        ),
        references=("#630", "#657"),
    ),
    RestartPath(
        path_id="conflict_marker_infra_stop",
        title="Startup conflict-marker infra stop",
        mechanism=(
            "The daemon entrypoint scans for unresolved merge-conflict markers "
            "at startup and stops (sys.exit(1)) if found."
        ),
        classification=CLASS_GUARDED_FAIL_CLOSED,
        guard=(
            "Fail-closed startup stop, not a restart: the process exits and "
            "waits for the operator to resolve conflicts and relaunch. Never "
            "self-restarts or loops."
        ),
        locations=("mcp_server.py (check_conflict_markers)",),
        references=("#657",),
    ),
    RestartPath(
        path_id="ide_client_reconnect",
        title="Host/IDE MCP reconnect",
        mechanism=(
            "A manual `/mcp reconnect` (or equivalent host action) that the "
            "IDE performs to recreate the MCP client connection."
        ),
        classification=CLASS_HOST_RESIDUAL,
        guard=(
            "Outside this process's control. It is the sanctioned recovery the "
            "gates point operators toward; documented as residual host "
            "behavior. No in-process code initiates it."
        ),
        locations=("host/IDE",),
        references=("#584", "#656", "#657"),
        residual_host=True,
    ),
    RestartPath(
        path_id="profile_switch_runtime",
        title="Runtime profile switch",
        mechanism=(
            "Switching the active execution profile at runtime "
            "(dynamic-profile mode)."
        ),
        classification=CLASS_SANCTIONED_NARROW,
        guard=(
            "In-process and restart-free: runtime_switching_supported is true, "
            "so a profile switch rebinds capability without recreating the "
            "process. No restart primitive is invoked."
        ),
        locations=("gitea_mcp_server.py (gitea_activate_profile)",),
        references=("#656", "#657"),
    ),
 )
 _BY_ID: dict[str, RestartPath] = {p.path_id: p for p in _RESTART_PATHS}
 # --- Read-only accessors ---------------------------------------------------
 def iter_restart_paths() -> tuple[RestartPath, ...]:
    """Return the full inventory as an immutable tuple."""
    return _RESTART_PATHS
 def restart_path_ids() -> frozenset[str]:
    """Return the set of registered path ids."""
    return frozenset(_BY_ID)
 def get_restart_path(path_id: str) -> RestartPath:
    """Return the registered path, or raise :class:`UnknownRestartPathError`."""
    try:
        return _BY_ID[path_id]
    except KeyError as exc:
        raise UnknownRestartPathError(
            f"unknown restart path id {path_id!r}; not in the #657 inventory"
        ) from exc
 def paths_by_classification(classification: str) -> tuple[RestartPath, ...]:
    """Return all registered paths with the given classification."""
    if classification not in VALID_CLASSIFICATIONS:
        raise ValueError(f"unknown classification {classification!r}")
    return tuple(p for p in _RESTART_PATHS if p.classification == classification)
 def assert_restart_attempt_registered(path_id: str) -> RestartPath:
    """Fail closed unless ``path_id`` is a registered, classified restart path.
    LLM tools that intend to trigger any restart/reload/reconnect must name a
    registered path so an unknown/novel restart primitive cannot slip through
    silently. Forbidden and removed paths are registered too — this only
    asserts the attempt is *known*, not that it is *permitted*; callers must
    still honor the classification.
    """
    return get_restart_path(path_id)
 def assert_registry_wellformed() -> None:
    """Validate the inventory's own invariants (fail closed on drift)."""
    seen: set[str] = set()
    for path in _RESTART_PATHS:
        if path.path_id in seen:
            raise ValueError(f"duplicate restart path id {path.path_id!r}")
        seen.add(path.path_id)
        if path.classification not in VALID_CLASSIFICATIONS:
            raise ValueError(
                f"{path.path_id!r} has invalid classification "
                f"{path.classification!r}"
            )
        if not path.guard.strip():
            raise ValueError(f"{path.path_id!r} is missing a guard description")
        if not path.references:
            raise ValueError(f"{path.path_id!r} is missing references")
        if not path.locations:
            raise ValueError(f"{path.path_id!r} is missing locations")
        if path.classification == CLASS_HOST_RESIDUAL and not path.residual_host:
            raise ValueError(
                f"{path.path_id!r} is host_residual but residual_host is False"
            )
 # --- Source-tree guards ----------------------------------------------------
 def _repo_root(root: str | os.PathLike[str] | None = None) -> Path:
    if root is not None:
        return Path(root)
    return Path(__file__).resolve().parent
 def _iter_code_lines(text: str) -> Iterable[tuple[int, str]]:
    """Yield (1-based lineno, line) for lines that are not full-line comments."""
    for lineno, line in enumerate(text.splitlines(), start=1):
        if line.lstrip().startswith("#"):
            continue
        yield lineno, line
 def scan_daemon_self_replacement(
    root: str | os.PathLike[str] | None = None,
 ) -> list[dict[str, object]]:
    """Return violations where a daemon module could self-replace/self-kill.
    Scans :data:`DAEMON_MODULES` for calls in
    :data:`DAEMON_SELF_REPLACEMENT_PRIMITIVES`. Full-line comments are ignored,
    and only call forms (with a trailing ``(``) match, so decision comments and
    docstrings that merely mention the primitives do not produce false hits.
    """
    repo = _repo_root(root)
    violations: list[dict[str, object]] = []
    for module in DAEMON_MODULES:
        path = repo / module
        if not path.exists():
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        for lineno, line in _iter_code_lines(text):
            for primitive in DAEMON_SELF_REPLACEMENT_PRIMITIVES:
                if primitive in line:
                    violations.append(
                        {
                            "module": module,
                            "line": lineno,
                            "primitive": primitive,
                            "text": line.strip(),
                        }
                    )
    return violations
 def assert_no_daemon_self_replacement(
    root: str | os.PathLike[str] | None = None,
 ) -> None:
    """Fail closed if any daemon module can restart/kill its own process."""
    violations = scan_daemon_self_replacement(root)
    if violations:
        rendered = "; ".join(
            f"{v['module']}:{v['line']} {v['primitive']}" for v in violations
        )
        raise AssertionError(
            "MCP daemon must never self-replace/self-kill (#657); found: "
            f"{rendered}"
        )
 def scan_auto_restart_helper(
    root: str | os.PathLike[str] | None = None,
 ) -> list[dict[str, object]]:
    """Return occurrences of a *definition* of the legacy auto-restart helper."""
    repo = _repo_root(root)
    needle = f"def {LEGACY_AUTO_RESTART_HELPER}"
    hits: list[dict[str, object]] = []
    for module in DAEMON_MODULES:
        path = repo / module
        if not path.exists():
            continue
        text = path.read_text(encoding="utf-8", errors="replace")
        for lineno, line in _iter_code_lines(text):
            if needle in line:
                hits.append({"module": module, "line": lineno})
    return hits
 def assert_auto_restart_helper_absent(
    root: str | os.PathLike[str] | None = None,
 ) -> None:
    """Fail closed if the removed ``_trigger_mcp_auto_restart`` reappears."""
    hits = scan_auto_restart_helper(root)
    if hits:
        rendered = "; ".join(f"{h['module']}:{h['line']}" for h in hits)
        raise AssertionError(
            f"{LEGACY_AUTO_RESTART_HELPER} was removed in #685 and must not "
            f"return (#657); found definition at: {rendered}"
        )
@@ -566,10 +566,6 @@ def build_pr_cleanup_entry(
        worktree_state=worktree_state,
        active_lock=active_lock,
    )
    planned = plan_cleanup_execution_order(
        remote_assessment=remote,
        local_assessment=local,
    )
    return {
        "pr_number": pr_number,
        "issue_number": issue_number,
@@ -580,63 +576,9 @@ def build_pr_cleanup_entry(
        "merged": merged,
        "remote_branch": remote,
        "local_worktree": local,
        # #851: dry-run and execute share the same lifecycle order description.
        "planned_execution_order": planned,
    }
 def plan_cleanup_execution_order(
    *,
    remote_assessment: dict[str, Any] | None,
    local_assessment: dict[str, Any] | None,
 ) -> list[dict[str, Any]]:
    """Describe independent worktree-then-reassess-then-remote cleanup order (#851).
    Remote ownership protection remains fail-closed at execute time. A worktree
    that is independently safe to remove is never skipped merely because remote
    deletion may be blocked by that same ``worktree_binding``.
    """
    remote = remote_assessment or {}
    local = local_assessment or {}
    steps: list[dict[str, Any]] = []
    worktree_safe = bool(local.get("safe_to_remove_worktree"))
    remote_safe = bool(remote.get("safe_to_delete_remote"))
    if worktree_safe:
        steps.append(
            {
                "action": "remove_local_worktree",
                "reason": "independently_safe_to_remove",
                "phase": 1,
            }
        )
    if remote_safe:
        if worktree_safe:
            steps.append(
                {
                    "action": "reassess_branch_ownership",
                    "reason": "after_worktree_removal_clear_worktree_binding",
                    "phase": 2,
                }
            )
            steps.append(
                {
                    "action": "delete_remote_branch",
                    "reason": "only_if_independently_safe_after_reassessment",
                    "phase": 3,
                }
            )
        else:
            steps.append(
                {
                    "action": "delete_remote_branch",
                    "reason": "safe_to_delete_and_no_independent_worktree_removal",
                    "phase": 1,
                }
            )
    return steps
 def build_reconciliation_report(
    *,
    project_root: str,
@@ -1,451 +0,0 @@
 """MCP restart coordinator and impact analysis (#658).
 Before any sanctioned MCP restart, a central coordinator must evaluate the
 live control-plane state — active sessions, leases/locks, in-flight issue/PR
 work, mutations, worktrees, and recovery history — and produce an *impact
 preview* so operators (and the web console, #642/#652) can see the blast
 radius **before** concurrent LLM work is disrupted.
 Design rules (mirrors the read-only posture of ``workflow_dashboard`` /
 ``lease_lifecycle``):
 * **Pure classification.** :func:`evaluate_restart_impact` takes an already
  gathered inventory and returns a structured report. It never touches the
  network, the filesystem, or a live process, so multi-session fixtures can
  drive every branch in unit tests. The coordinator *never restarts anything*;
  a mutative apply path is a later child gated by a drain proof (non-goal here).
 * **Fail closed.** If the inventory is not explicitly complete, the verdict is
  ``unsafe`` / deny — an incomplete evaluation must never green-light a restart.
 * **No secrets.** Session ids, pids, and profiles are operational metadata, not
  credentials; nothing secret flows through this module.
 The single sanctioned entry point post-#657 is the MCP tool
 ``gitea_request_mcp_restart`` (dry-run by default), which gathers the inventory
 from the #613 control-plane DB and calls :func:`evaluate_restart_impact`.
 """
 from __future__ import annotations
 from dataclasses import dataclass, field
 from datetime import datetime, timezone
 from typing import Any, Mapping, Sequence
 import lease_lifecycle
 COORDINATOR_VERSION = "1.0.0-issue-658"
 # Restart verdicts. Exactly the three the acceptance criteria name.
 VERDICT_SAFE = "safe"
 VERDICT_UNSAFE = "unsafe"
 VERDICT_OVERRIDE = "override"
 # Blast-radius severity bands.
 BLAST_NONE = "none"
 BLAST_LOW = "low"
 BLAST_MEDIUM = "medium"
 BLAST_HIGH = "high"
 # A live lease with a live owner process is treated as active in-flight work.
 LEASE_FRESHNESS_LIVE = "active"
 # Default staleness window for a session heartbeat (seconds). A session whose
 # last heartbeat is older than this is not counted as live even if its row is
 # still marked ``active`` — it is assumed dead/detached.
 DEFAULT_SESSION_HEARTBEAT_STALE_SECONDS = 900
 def _utc_now() -> datetime:
    return datetime.now(timezone.utc)
 def _parse_ts(value: str | None) -> datetime | None:
    return lease_lifecycle._parse_ts(value)
@dataclass(frozen=True)
 class SessionImpact:
    """One MCP session a restart would terminate."""
    session_id: str
    role: str | None
    profile: str | None
    pid: int | None
    status: str | None
    alive: bool | None
    heartbeat_stale: bool
    is_requester: bool
    live: bool
    def as_dict(self) -> dict[str, Any]:
        return {
            "session_id": self.session_id,
            "role": self.role,
            "profile": self.profile,
            "pid": self.pid,
            "status": self.status,
            "alive": self.alive,
            "heartbeat_stale": self.heartbeat_stale,
            "is_requester": self.is_requester,
            "live": self.live,
        }
@dataclass(frozen=True)
 class LeaseImpact:
    """One control-plane lease a restart would disrupt."""
    lease_id: str | None
    session_id: str | None
    role: str | None
    phase: str | None
    freshness: str | None
    work_kind: str | None
    work_number: int | None
    worktree_path: str | None
    disruptive: bool
    is_mutation: bool
    is_critical_section: bool
    def as_dict(self) -> dict[str, Any]:
        return {
            "lease_id": self.lease_id,
            "session_id": self.session_id,
            "role": self.role,
            "phase": self.phase,
            "freshness": self.freshness,
            "work_kind": self.work_kind,
            "work_number": self.work_number,
            "worktree_path": self.worktree_path,
            "disruptive": self.disruptive,
            "is_mutation": self.is_mutation,
            "is_critical_section": self.is_critical_section,
        }
@dataclass(frozen=True)
 class RestartImpactReport:
    """Impact preview DTO returned to the console / operator (#642/#652)."""
    coordinator_version: str
    evaluated_at: str
    dry_run: bool
    restart_performed: bool
    inventory_complete: bool
    verdict: str
    allow_restart: bool
    override_would_allow: bool
    operator_override: bool
    blast_radius: str
    reasons: list[str]
    affected_sessions: list[SessionImpact]
    affected_leases: list[LeaseImpact]
    critical_sections: list[LeaseImpact]
    affected_issues: list[int]
    affected_prs: list[int]
    mutations: list[LeaseImpact]
    terminal_lock: dict[str, Any] | None
    ack_state: dict[str, str]
    prior_recovery_attempts: list[dict[str, Any]]
    counts: dict[str, int]
    audit_record: dict[str, Any]
    incomplete_reasons: list[str] = field(default_factory=list)
    def as_dict(self) -> dict[str, Any]:
        return {
            "coordinator_version": self.coordinator_version,
            "evaluated_at": self.evaluated_at,
            "dry_run": self.dry_run,
            "restart_performed": self.restart_performed,
            "inventory_complete": self.inventory_complete,
            "incomplete_reasons": list(self.incomplete_reasons),
            "verdict": self.verdict,
            "allow_restart": self.allow_restart,
            "override_would_allow": self.override_would_allow,
            "operator_override": self.operator_override,
            "blast_radius": self.blast_radius,
            "reasons": list(self.reasons),
            "affected_sessions": [s.as_dict() for s in self.affected_sessions],
            "affected_leases": [l.as_dict() for l in self.affected_leases],
            "critical_sections": [l.as_dict() for l in self.critical_sections],
            "affected_issues": list(self.affected_issues),
            "affected_prs": list(self.affected_prs),
            "mutations": [l.as_dict() for l in self.mutations],
            "terminal_lock": self.terminal_lock,
            "ack_state": dict(self.ack_state),
            "prior_recovery_attempts": list(self.prior_recovery_attempts),
            "counts": dict(self.counts),
            "audit_record": dict(self.audit_record),
        }
 def _classify_session(
    row: Mapping[str, Any],
    *,
    now: datetime,
    requesting_session_id: str | None,
    heartbeat_stale_seconds: int,
 ) -> SessionImpact:
    session_id = str(row.get("session_id") or "")
    pid = row.get("pid")
    status = (row.get("status") or "").strip().lower() or None
    alive = lease_lifecycle.is_process_alive(pid) if pid is not None else None
    hb = _parse_ts(row.get("last_heartbeat_at"))
    heartbeat_stale = bool(
        hb is not None and (now - hb).total_seconds() > heartbeat_stale_seconds
    )
    live = bool(status == "active" and alive is not False and not heartbeat_stale)
    return SessionImpact(
        session_id=session_id,
        role=row.get("role"),
        profile=row.get("profile"),
        pid=pid,
        status=status,
        alive=alive,
        heartbeat_stale=heartbeat_stale,
        is_requester=bool(
            requesting_session_id and session_id == requesting_session_id
        ),
        live=live,
    )
 # Lease phases that represent an active mutation in flight (as opposed to a
 # mere allocation/claim with no work committed yet). An active lease in any of
 # these phases is a critical section a restart must not sever.
 _MUTATING_PHASES = frozenset(
    {
        "implementing",
        "publishing",
        "pushing",
        "committing",
        "reviewing",
        "merging",
        "reconciling",
        "conflict_fix",
    }
 )
 def _classify_lease(row: Mapping[str, Any]) -> LeaseImpact:
    freshness_obj = row.get("freshness")
    if isinstance(freshness_obj, Mapping):
        freshness = str(freshness_obj.get("freshness") or "").strip().lower() or None
    else:
        freshness = str(freshness_obj or "").strip().lower() or None
    phase = (row.get("phase") or "").strip().lower() or None
    worktree = row.get("worktree_path")
    disruptive = freshness == LEASE_FRESHNESS_LIVE
    # A live lease is a mutation-in-flight if it carries an author worktree or
    # its phase names a mutating step. All disruptive leases are critical
    # sections a restart would sever regardless.
    is_mutation = bool(
        disruptive and (bool(worktree) or (phase in _MUTATING_PHASES))
    )
    number = row.get("work_number")
    try:
        number = int(number) if number is not None else None
    except (TypeError, ValueError):
        number = None
    return LeaseImpact(
        lease_id=row.get("lease_id"),
        session_id=row.get("session_id"),
        role=row.get("role"),
        phase=phase,
        freshness=freshness,
        work_kind=(str(row.get("work_kind") or "").strip().lower() or None),
        work_number=number,
        worktree_path=worktree,
        disruptive=disruptive,
        is_mutation=is_mutation,
        is_critical_section=disruptive,
    )
 def _blast_radius(*, session_count: int, work_count: int, mutation_count: int) -> str:
    if mutation_count > 0 or work_count >= 3 or session_count >= 3:
        return BLAST_HIGH
    if work_count > 0 or session_count == 2:
        return BLAST_MEDIUM
    if session_count == 1:
        return BLAST_LOW
    return BLAST_NONE
 def evaluate_restart_impact(
    inventory: Mapping[str, Any],
    *,
    now: datetime | None = None,
    operator_override: bool = False,
    requesting_session_id: str | None = None,
    dry_run: bool = True,
    session_heartbeat_stale_seconds: int = DEFAULT_SESSION_HEARTBEAT_STALE_SECONDS,
 ) -> RestartImpactReport:
    """Evaluate a proposed MCP restart and return an impact preview.
    ``inventory`` is a mapping with:
    * ``sessions`` — session rows (session_id, role, profile, pid, status,
      last_heartbeat_at).
    * ``leases`` — control-plane lease rows, each ideally carrying an enriched
      ``freshness`` dict (as :func:`lease_lifecycle.list_active_leases` returns);
      a bare string freshness is also accepted.
    * ``terminal_lock`` — the active terminal (merge) lock, if any.
    * ``prior_recovery_attempts`` — narrower recovery attempts already tried
      (e.g. sanctioned reconnects) so the operator sees escalation history.
    * ``inventory_complete`` — bool. **Must** be explicitly True; a missing or
      falsy value forces a deny (fail closed).
    * ``incomplete_reasons`` — optional reasons the inventory is incomplete.
    The coordinator never restarts anything: ``restart_performed`` is always
    False and the mutative apply path is a later drain-gated child.
    """
    moment = now or _utc_now()
    reasons: list[str] = []
    inventory_complete = bool(inventory.get("inventory_complete", False))
    incomplete_reasons = [str(r) for r in (inventory.get("incomplete_reasons") or [])]
    sessions_raw: Sequence[Mapping[str, Any]] = inventory.get("sessions") or []
    leases_raw: Sequence[Mapping[str, Any]] = inventory.get("leases") or []
    terminal_lock = inventory.get("terminal_lock") or None
    prior_recovery_attempts = [
        dict(a) for a in (inventory.get("prior_recovery_attempts") or [])
    ]
    session_impacts = [
        _classify_session(
            s,
            now=moment,
            requesting_session_id=requesting_session_id,
            heartbeat_stale_seconds=session_heartbeat_stale_seconds,
        )
        for s in sessions_raw
    ]
    lease_impacts = [_classify_lease(l) for l in leases_raw]
    # Only *other* live sessions and live leases constitute blast radius: a
    # restart that would kill only the requesting session with no other work in
    # flight is safe.
    other_live_sessions = [
        s for s in session_impacts if s.live and not s.is_requester
    ]
    disruptive_leases = [l for l in lease_impacts if l.disruptive]
    critical_sections = [l for l in lease_impacts if l.is_critical_section]
    mutations = [l for l in lease_impacts if l.is_mutation]
    affected_issues = sorted(
        {
            l.work_number
            for l in disruptive_leases
            if l.work_kind == "issue" and l.work_number is not None
        }
    )
    affected_prs = sorted(
        {
            l.work_number
            for l in disruptive_leases
            if l.work_kind == "pr" and l.work_number is not None
        }
    )
    disruptive = bool(disruptive_leases or other_live_sessions or terminal_lock)
    if not inventory_complete:
        verdict = VERDICT_UNSAFE
        allow_restart = False
        reasons.append(
            "inventory incomplete: restart evaluation cannot confirm blast "
            "radius — deny (fail closed, #658)"
        )
        reasons.extend(incomplete_reasons)
    elif not disruptive:
        verdict = VERDICT_SAFE
        allow_restart = True
        reasons.append("no other live sessions, live leases, or terminal lock")
    elif operator_override:
        verdict = VERDICT_OVERRIDE
        allow_restart = True
        reasons.append(
            "live work present; operator override accepts the blast radius"
        )
    else:
        verdict = VERDICT_UNSAFE
        allow_restart = False
        reasons.append(
            "live work would be disrupted; restart denied without operator "
            "override"
        )
    if critical_sections and inventory_complete:
        reasons.append(
            f"{len(critical_sections)} critical section(s) in flight "
            "(active lease with a live owner)"
        )
    if terminal_lock:
        reasons.append("active terminal (merge) lock present")
    override_would_allow = bool(inventory_complete and disruptive)
    blast_radius = _blast_radius(
        session_count=len(other_live_sessions),
        work_count=len(affected_issues) + len(affected_prs),
        mutation_count=len(mutations),
    )
    # Acknowledgement is a later child (drain protocol); expose per-session
    # placeholders so the console can render the ack column now.
    ack_state = {s.session_id: "pending" for s in other_live_sessions}
    counts = {
        "sessions_total": len(session_impacts),
        "sessions_live_other": len(other_live_sessions),
        "leases_total": len(lease_impacts),
        "leases_disruptive": len(disruptive_leases),
        "critical_sections": len(critical_sections),
        "mutations": len(mutations),
        "affected_issues": len(affected_issues),
        "affected_prs": len(affected_prs),
        "prior_recovery_attempts": len(prior_recovery_attempts),
    }
    audit_record = {
        "event": "restart_impact_evaluated",
        "coordinator_version": COORDINATOR_VERSION,
        "evaluated_at": moment.isoformat(),
        "dry_run": dry_run,
        "operator_override": bool(operator_override),
        "requesting_session_id": requesting_session_id,
        "inventory_complete": inventory_complete,
        "verdict": verdict,
        "allow_restart": allow_restart,
        "blast_radius": blast_radius,
        "counts": counts,
    }
    return RestartImpactReport(
        coordinator_version=COORDINATOR_VERSION,
        evaluated_at=moment.isoformat(),
        dry_run=dry_run,
        restart_performed=False,
        inventory_complete=inventory_complete,
        verdict=verdict,
        allow_restart=allow_restart,
        override_would_allow=override_would_allow,
        operator_override=bool(operator_override),
        blast_radius=blast_radius,
        reasons=reasons,
        affected_sessions=session_impacts,
        affected_leases=lease_impacts,
        critical_sections=critical_sections,
        affected_issues=affected_issues,
        affected_prs=affected_prs,
        mutations=mutations,
        terminal_lock=dict(terminal_lock)
        if isinstance(terminal_lock, Mapping)
        else terminal_lock,
        ack_state=ack_state,
        prior_recovery_attempts=prior_recovery_attempts,
        counts=counts,
        audit_record=audit_record,
        incomplete_reasons=incomplete_reasons,
    )
@@ -43,21 +43,19 @@ repo_root="$(cd "$script_dir/.." && pwd)"
 # Enforce issue-linked, traceable branch names (issue → branch → worktree → PR).
 if [[ "$allow_unlinked" -eq 0 ]]; then
-  if [[ "$dry_run" -eq 0 ]] && [[ ! "$branch" =~ ^review/pr-[0-9]+-.+ ]]; then
+  locked_branch=$(python3 -c "
    locked_branch=$(python3 -c "
 import sys
 sys.path.insert(0, '$repo_root')
 import issue_lock_store
 print(issue_lock_store.resolve_locked_branch_for_session('$branch'))
 ")
-    if [[ -z "$locked_branch" ]]; then
+  if [[ -z "$locked_branch" ]]; then
-      echo "Error: No session issue lock is bound. Call gitea_lock_issue before branch creation (fail closed)." >&2
+    echo "Error: No session issue lock is bound. Call gitea_lock_issue before branch creation (fail closed)." >&2
-      exit 2
+    exit 2
-    fi
+  fi
-    if [[ "$branch" != "$locked_branch" ]]; then
+  if [[ "$branch" != "$locked_branch" ]]; then
-      echo "Error: Requested branch '$branch' does not match locked branch '$locked_branch' (fail closed)." >&2
+    echo "Error: Requested branch '$branch' does not match locked branch '$locked_branch' (fail closed)." >&2
-      exit 2
+    exit 2
    fi
  fi
  if [[ "$branch" =~ ^(fix|feat|docs|chore)/issue-[0-9]+-.+ ]] \
@@ -32,26 +32,6 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
        "permission": "gitea.issue.comment",
        "role": "author",
    },
    # #860: dirty orphaned same-claimant worktree recovery (explicit operation).
    "recover_dirty_orphaned_issue_worktree": {
        "permission": "gitea.issue.comment",
        "role": "author",
    },
    "gitea_recover_dirty_orphaned_issue_worktree": {
        "permission": "gitea.issue.comment",
        "role": "author",
    },
    # #864: dirty-preserving same-claimant author-session rebind (dead owner PID).
    # Author MCP tool path. Reconciler execute is gated inside the tool via
    # authorize_reconciler_execute + role_kind checks (not this map entry).
    "rebind_dirty_same_claimant_author_session": {
        "permission": "gitea.issue.comment",
        "role": "author",
    },
    "gitea_rebind_dirty_same_claimant_author_session": {
        "permission": "gitea.issue.comment",
        "role": "author",
    },
    "set_issue_labels": {
        "permission": "gitea.issue.comment",
        "role": "author",
@@ -355,21 +335,6 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
        "role": "controller",
    },
    # #642: sanctioned host-daemon lifecycle controls. Deliberately *not* a
    # ``gitea.*`` operation — restarting an MCP namespace is a host action, not
    # a Gitea API call, and no configured Gitea profile should be able to
    # satisfy it by accident. Authority comes from the console RBAC model plus
    # out-of-band operator authorization (#630); these entries exist so the
    # console cannot invent an authority the capability layer never declared.
    "restart_namespace": {
        "permission": "runtime.restart_namespace",
        "role": "controller",
    },
    "reload_namespace": {
        "permission": "runtime.reload_namespace",
        "role": "controller",
    },
    # #601 first-class lease lifecycle — inspect/list need read; mutations gate on
    # ownership in the control-plane DB (not a separate Gitea write permission).
    "list_workflow_leases": {
@@ -512,11 +477,6 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
 # merger lease (#763).
 _PREFLIGHT_TASK_TRANSITIONS = frozenset({
    ("review_pr", "acquire_reviewer_pr_lease"),
    ("work_issue", "lock_issue"),
    ("work_issue", "recover_dirty_orphaned_issue_worktree"),
    ("work_issue", "gitea_recover_dirty_orphaned_issue_worktree"),
    ("work_issue", "commit_files"),
    ("work_issue", "gitea_commit_files"),
 })
@@ -1,243 +0,0 @@
 """Allocator epic / child-only container pre-rank exclusion (#844).
 Covers:
 * Issue #631-shaped child-only epic is excluded before ranking.
 * Implementable child issues remain eligible and can be selected.
 * Ordinary issues that merely mention "epic" in title/body are not excluded.
 * Excluded containers never receive assignments or workflow leases.
 * Structured skip reason ``epic_or_child_only_container`` is reported.
 """
 from __future__ import annotations
 import os
 import tempfile
 import unittest
 from allocator_service import (
    OUTCOME_ASSIGNED,
    OUTCOME_PREVIEW,
    SKIP_EPIC_OR_CHILD_ONLY_CONTAINER,
    WorkCandidate,
    allocate_next_work,
    classify_epic_or_child_only_container,
 )
 from control_plane_db import ControlPlaneDB
 REMOTE = "prgs"
 ORG = "Scaled-Tech-Consulting"
 REPO = "Gitea-Tools"
 # Minimal body mirroring issue #631 authoritative scope language.
 _EPIC_631_BODY = """
 ## Scope (umbrella)
 This epic owns the **product roadmap and linkage** for the Web Console.
 Implementation is delivered via child issues only.
 ## Explicit non-goals
 * Do not implement product features in this epic issue itself.
 * No product feature implementation is claimed complete solely on this epic.
 """
 _CHILD_BODY = """
 ## Problem
 Operators need a workflow-event timeline model for Phase 1.
 ## Acceptance criteria
 - [ ] Timeline model API exists
 """
 def _issue(
    number: int,
    *,
    title: str = "",
    body: str = "",
    labels: tuple[str, ...] = ("status:ready", "type:feature"),
    priority: int = 20,
 ) -> WorkCandidate:
    return WorkCandidate(
        kind="issue",
        number=number,
        state="open",
        labels=labels,
        title=title or f"issue {number}",
        body=body,
        priority=priority,
    )
 class ClassifyEpicContainerTest(unittest.TestCase):
    def test_631_shaped_body_and_title_is_container(self) -> None:
        c = _issue(
            631,
            title="Epic: MCP Control Plane Web Console",
            body=_EPIC_631_BODY,
        )
        is_c, detail = classify_epic_or_child_only_container(c)
        self.assertTrue(is_c)
        self.assertIsNotNone(detail)
        self.assertIn("body_marker", detail or "")
    def test_body_markers_without_epic_title(self) -> None:
        c = _issue(
            900,
            title="Control plane roadmap tracker",
            body="Implementation is delivered via child issues only.",
        )
        is_c, _ = classify_epic_or_child_only_container(c)
        self.assertTrue(is_c)
    def test_epic_label_alone_is_container(self) -> None:
        c = _issue(
            901,
            title="Roadmap linkage",
            body="Track children.",
            labels=("status:ready", "type:epic"),
        )
        is_c, detail = classify_epic_or_child_only_container(c)
        self.assertTrue(is_c)
        self.assertIn("type:epic", detail or "")
    def test_title_epic_prefix_alone_not_container(self) -> None:
        """Title-only 'Epic:' without body scope evidence stays eligible (#844)."""
        c = _issue(
            902,
            title="Epic: something mentioned only in title",
            body="Implement a concrete fix for the allocator skip list.",
        )
        is_c, detail = classify_epic_or_child_only_container(c)
        self.assertFalse(is_c)
        self.assertIsNone(detail)
    def test_incidental_epic_word_not_container(self) -> None:
        c = _issue(
            903,
            title="Document epic handoff conventions",
            body=(
                "Update the docs so implementable issues that mention an epic "
                "remain independently executable."
            ),
        )
        is_c, _ = classify_epic_or_child_only_container(c)
        self.assertFalse(is_c)
    def test_prs_never_classified(self) -> None:
        pr = WorkCandidate(
            kind="pr",
            number=10,
            state="open",
            title="Epic: fake",
            body="Implementation is delivered via child issues only.",
            head_sha="a" * 40,
            priority=5,
        )
        is_c, _ = classify_epic_or_child_only_container(pr)
        self.assertFalse(is_c)
 class AllocateEpicContainerExclusionTest(unittest.TestCase):
    def setUp(self) -> None:
        self._tmp = tempfile.TemporaryDirectory()
        self.addCleanup(self._tmp.cleanup)
        self.db = ControlPlaneDB(os.path.join(self._tmp.name, "cp.sqlite3"))
    def _alloc(self, candidates, **kwargs):
        defaults = dict(
            session_id="sess-844",
            role="author",
            remote=REMOTE,
            org=ORG,
            repo=REPO,
            profile_name="prgs-author",
            username="jcwalker3",
            claims={},
            apply=False,
        )
        defaults.update(kwargs)
        return allocate_next_work(self.db, candidates=candidates, **defaults)
    def test_631_shaped_epic_excluded_child_selected(self) -> None:
        epic = _issue(
            631,
            title="Epic: MCP Control Plane Web Console",
            body=_EPIC_631_BODY,
        )
        child = _issue(
            637,
            title="Web Console: Workflow-event timeline model (Phase 1)",
            body=_CHILD_BODY,
        )
        res = self._alloc([epic, child], apply=False)
        self.assertTrue(res["success"], res)
        self.assertEqual(res["outcome"], OUTCOME_PREVIEW)
        self.assertEqual(res["selected"]["number"], 637)
        skipped = {s["number"]: s for s in res["skipped"]}
        self.assertIn(631, skipped)
        self.assertEqual(
            skipped[631]["reason_code"], SKIP_EPIC_OR_CHILD_ONLY_CONTAINER
        )
        self.assertIn(SKIP_EPIC_OR_CHILD_ONLY_CONTAINER, skipped[631]["reason"])
    def test_container_cannot_receive_assignment_or_lease(self) -> None:
        epic = _issue(
            631,
            title="Epic: MCP Control Plane Web Console",
            body=_EPIC_631_BODY,
        )
        res = self._alloc([epic], apply=True)
        self.assertTrue(res["success"], res)
        # Only container present → no safe work; never assigned_work.
        self.assertNotEqual(res["outcome"], OUTCOME_ASSIGNED)
        self.assertIsNone(res.get("assignment"))
        self.assertIsNone(res.get("selected"))
        skipped = {s["number"]: s for s in res["skipped"]}
        self.assertEqual(
            skipped[631]["reason_code"], SKIP_EPIC_OR_CHILD_ONLY_CONTAINER
        )
        # No lease row for the epic.
        leases = self.db.list_active_leases(
            remote=REMOTE, org=ORG, repo=REPO
        ) if hasattr(self.db, "list_active_leases") else []
        # Prefer generic inventory if available.
        if not leases and hasattr(self.db, "list_leases"):
            leases = self.db.list_leases(remote=REMOTE, org=ORG, repo=REPO)
        for lease in leases or []:
            work_number = lease.get("work_number") if isinstance(lease, dict) else None
            self.assertNotEqual(work_number, 631)
    def test_incidental_epic_title_remains_eligible(self) -> None:
        ordinary = _issue(
            700,
            title="Document epic handoff conventions",
            body="Write runbook text about epic vs child issues.",
        )
        res = self._alloc([ordinary], apply=False)
        self.assertTrue(res["success"], res)
        self.assertEqual(res["selected"]["number"], 700)
        self.assertEqual(res["skipped"], [])
    def test_apply_selects_child_not_epic(self) -> None:
        epic = _issue(
            631,
            title="Epic: MCP Control Plane Web Console",
            body=_EPIC_631_BODY,
        )
        child = _issue(
            637,
            title="Web Console: Workflow-event timeline model (Phase 1)",
            body=_CHILD_BODY,
        )
        res = self._alloc([epic, child], apply=True)
        self.assertTrue(res["success"], res)
        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
        self.assertEqual(res["selected"]["number"], 637)
        self.assertEqual(res["assignment"]["work_number"], 637)
 if __name__ == "__main__":
    unittest.main()
@@ -1266,730 +1266,6 @@ class TestSecondRemediationIntegration(unittest.TestCase):
        self.assertIn("delete_acknowledged", delete_actions[0])
        self.assertTrue(delete_actions[0].get("verified_absent"))
    def test_issue_851_worktree_removed_when_remote_blocked_only_by_worktree_binding(self):
        """#851: remote blocked by worktree_binding must not skip safe worktree removal.
        Lifecycle: remove clean owned worktree → reassess ownership → delete
        remote only if independently safe. Unrelated entries stay untouched.
        """
        from mcp_server import gitea_reconcile_merged_cleanups
        target_branch = "fix/issue-844-exclude-epic-containers"
        foreign_branch = "fix/issue-999-unrelated-active"
        worktree_path = "/tmp/branches/fix-issue-844-exclude-epic-containers"
        ownership_calls = []
        remove_calls = []
        delete_api_calls = []
        def fake_collect(**kwargs):
            ownership_calls.append(dict(kwargs))
            # Ownership is reassessed *after* independent worktree removal (#851).
            # Target worktree is already gone → no worktree_binding remains.
            # Foreign branch keeps an active author lease → remote delete blocked.
            if kwargs.get("branch") == foreign_branch:
                # Match session-bound org/repo + host used by the tool resolve path.
                return {
                    "records": [
                        {
                            "category": guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE,
                            "status": "active",
                            "remote": kwargs.get("remote") or "prgs",
                            "host": kwargs.get("host") or "gitea.example.com",
                            "org": kwargs.get("org") or "Scaled-Tech-Consulting",
                            "repo": kwargs.get("repo") or "Gitea-Tools",
                            "branch": foreign_branch,
                            "reclaim_allowed": False,
                        }
                    ],
                    "inventory_error": False,
                }
            return {"records": [], "inventory_error": False}
        def fake_remove(project_root, branch, worktree_path=None):
            remove_calls.append(
                {"branch": branch, "worktree_path": worktree_path}
            )
            return {
                "success": True,
                "performed": True,
                "message": f"removed worktree {worktree_path}",
                "worktree_path": worktree_path,
            }
        def fake_probe(h, o, r, auth, br):
            return guard.classify_branch_readback_http_status(
                404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH
            )
        def fake_api(method, url, auth, **kwargs):
            if method == "DELETE":
                delete_api_calls.append(url)
            return {}
        report = {
            "entries": [
                {
                    "pr_number": 848,
                    "head_branch": target_branch,
                    "remote_branch": {"safe_to_delete_remote": True},
                    "local_worktree": {
                        "safe_to_remove_worktree": True,
                        "worktree_path": worktree_path,
                    },
                },
                {
                    "pr_number": 999,
                    "head_branch": foreign_branch,
                    "remote_branch": {"safe_to_delete_remote": True},
                    "local_worktree": {
                        "safe_to_remove_worktree": False,
                        "worktree_path": None,
                    },
                },
            ],
            "reviewer_scratch_entries": [],
        }
        patch(
            "mcp_server.get_profile",
            return_value={
                "profile_name": "prgs-reconciler",
                "role": "reconciler",
                "allowed_operations": [
                    "gitea.read",
                    "gitea.branch.delete",
                    "gitea.pr.close",
                ],
                "forbidden_operations": [],
            },
        ).start()
        patch("mcp_server.api_get_all", return_value=[]).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            return_value=report,
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
            return_value=[],
        ).start()
        patch(
            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
            return_value=(True, []),
        ).start()
        patch("mcp_server.verify_preflight_purity", return_value=None).start()
        patch(
            "mcp_server._collect_branch_ownership_records",
            side_effect=fake_collect,
        ).start()
        patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
            side_effect=fake_remove,
        ).start()
        self.mock_api.side_effect = fake_api
        res = gitea_reconcile_merged_cleanups(
            dry_run=False,
            execute_confirmed=True,
            remote="prgs",
        )
        self.assertTrue(res.get("performed") or res.get("executed"))
        actions = res.get("actions") or []
        remove_actions = [
            a for a in actions if a.get("action") == "remove_local_worktree"
        ]
        self.assertEqual(len(remove_actions), 1, actions)
        self.assertTrue(remove_actions[0].get("success"))
        self.assertEqual(remove_calls[0]["branch"], target_branch)
        self.assertEqual(remove_calls[0]["worktree_path"], worktree_path)
        # Target remote delete succeeds after worktree removal + reassessment.
        target_deletes = [
            a
            for a in actions
            if a.get("action") == "delete_remote_branch"
            and a.get("branch") == target_branch
        ]
        self.assertEqual(len(target_deletes), 1, actions)
        self.assertTrue(target_deletes[0].get("success"))
        self.assertTrue(target_deletes[0].get("after_worktree_removal"))
        self.assertTrue(target_deletes[0].get("ownership_reassessed"))
        self.assertTrue(target_deletes[0].get("verified_absent"))
        # Foreign branch remains protected (author lease) and is not deleted.
        foreign_deletes = [
            a
            for a in actions
            if a.get("action") == "delete_remote_branch"
            and a.get("branch") == foreign_branch
        ]
        self.assertEqual(len(foreign_deletes), 1, actions)
        self.assertFalse(foreign_deletes[0].get("success"))
        self.assertEqual(
            foreign_deletes[0].get("blocker_kind"), "active_branch_ownership"
        )
        self.assertIn(
            guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE,
            foreign_deletes[0].get("blocking_categories") or [],
        )
        # Only the target branch should hit the DELETE API.
        self.assertEqual(len(delete_api_calls), 1)
        # Ownership collected for target (post-removal) and foreign; worktree
        # removal happened before target remote delete in the action log.
        target_idx = next(
            i
            for i, a in enumerate(actions)
            if a.get("action") == "remove_local_worktree"
        )
        delete_idx = next(
            i
            for i, a in enumerate(actions)
            if a.get("action") == "delete_remote_branch"
            and a.get("branch") == target_branch
            and a.get("success")
        )
        self.assertLess(target_idx, delete_idx)
    def test_issue_851_dirty_worktree_not_removed_and_remote_stays_protected(self):
        """#851: dirty/foreign worktrees remain protected; no unsafe cleanup."""
        from mcp_server import gitea_reconcile_merged_cleanups
        branch = "fix/issue-851-dirty"
        remove_calls = []
        def fake_collect(**kwargs):
            return {
                "records": [
                    {
                        "category": guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING,
                        "status": "active",
                        "remote": kwargs.get("remote") or "prgs",
                        "host": kwargs.get("host") or "gitea.example.com",
                        "org": kwargs.get("org") or "Scaled-Tech-Consulting",
                        "repo": kwargs.get("repo") or "Gitea-Tools",
                        "branch": branch,
                        "reclaim_allowed": False,
                    }
                ],
                "inventory_error": False,
            }
        report = {
            "entries": [
                {
                    "pr_number": 851,
                    "head_branch": branch,
                    "remote_branch": {"safe_to_delete_remote": True},
                    "local_worktree": {
                        "safe_to_remove_worktree": False,
                        "worktree_path": "/tmp/dirty-wt",
                    },
                }
            ],
            "reviewer_scratch_entries": [],
        }
        patch(
            "mcp_server.get_profile",
            return_value={
                "profile_name": "prgs-reconciler",
                "role": "reconciler",
                "allowed_operations": [
                    "gitea.read",
                    "gitea.branch.delete",
                ],
                "forbidden_operations": [],
            },
        ).start()
        patch("mcp_server.api_get_all", return_value=[]).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            return_value=report,
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
            return_value=[],
        ).start()
        patch(
            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
            return_value=(True, []),
        ).start()
        patch("mcp_server.verify_preflight_purity", return_value=None).start()
        patch(
            "mcp_server._collect_branch_ownership_records",
            side_effect=fake_collect,
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
            side_effect=lambda *a, **k: remove_calls.append(k) or {
                "success": True,
                "performed": True,
            },
        ).start()
        self.mock_api.side_effect = lambda *a, **k: {}
        res = gitea_reconcile_merged_cleanups(
            dry_run=False,
            execute_confirmed=True,
            remote="prgs",
        )
        actions = res.get("actions") or []
        self.assertEqual(remove_calls, [])
        self.assertFalse(
            any(a.get("action") == "remove_local_worktree" for a in actions)
        )
        deletes = [
            a for a in actions if a.get("action") == "delete_remote_branch"
        ]
        self.assertEqual(len(deletes), 1)
        self.assertFalse(deletes[0].get("success"))
        self.assertEqual(deletes[0].get("blocker_kind"), "active_branch_ownership")
        self.assertIn(
            guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING,
            deletes[0].get("blocking_categories") or [],
        )
    def test_issue_851_idempotent_resume_when_worktree_already_absent(self):
        """#851: partial failures remain resumable and idempotent."""
        from mcp_server import gitea_reconcile_merged_cleanups
        branch = "fix/issue-851-resume"
        ownership_calls = []
        def fake_collect(**kwargs):
            ownership_calls.append(kwargs)
            return {"records": [], "inventory_error": False}
        def fake_remove(project_root, branch, worktree_path=None):
            return {
                "success": False,
                "performed": False,
                "message": f"worktree not found: {worktree_path}",
            }
        def fake_probe(h, o, r, auth, br):
            return guard.classify_branch_readback_http_status(
                404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH
            )
        report = {
            "entries": [
                {
                    "pr_number": 851,
                    "head_branch": branch,
                    "remote_branch": {"safe_to_delete_remote": True},
                    "local_worktree": {
                        "safe_to_remove_worktree": True,
                        "worktree_path": "/tmp/already-gone",
                    },
                }
            ],
            "reviewer_scratch_entries": [],
        }
        patch(
            "mcp_server.get_profile",
            return_value={
                "profile_name": "prgs-reconciler",
                "role": "reconciler",
                "allowed_operations": [
                    "gitea.read",
                    "gitea.branch.delete",
                ],
                "forbidden_operations": [],
            },
        ).start()
        patch("mcp_server.api_get_all", return_value=[]).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            return_value=report,
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
            return_value=[],
        ).start()
        patch(
            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
            return_value=(True, []),
        ).start()
        patch("mcp_server.verify_preflight_purity", return_value=None).start()
        patch(
            "mcp_server._collect_branch_ownership_records",
            side_effect=fake_collect,
        ).start()
        patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
            side_effect=fake_remove,
        ).start()
        self.mock_api.side_effect = lambda *a, **k: {}
        res = gitea_reconcile_merged_cleanups(
            dry_run=False,
            execute_confirmed=True,
            remote="prgs",
        )
        actions = res.get("actions") or []
        removes = [a for a in actions if a.get("action") == "remove_local_worktree"]
        deletes = [a for a in actions if a.get("action") == "delete_remote_branch"]
        self.assertEqual(len(removes), 1)
        self.assertFalse(removes[0].get("success"))
        self.assertEqual(len(deletes), 1)
        self.assertTrue(deletes[0].get("success"))
        self.assertTrue(deletes[0].get("after_worktree_removal"))
        self.assertTrue(ownership_calls)
 class TestIssue855ExactPrSelector(unittest.TestCase):
    """#855: exact pr_number pin for reconcile_merged_cleanups (#851 lifecycle)."""
    def setUp(self):
        self._remotes = patch.dict(
            mcp_server.REMOTES,
            {
                "prgs": {
                    "host": "gitea.example.com",
                    "org": "Scaled-Tech-Consulting",
                    "repo": "Gitea-Tools",
                }
            },
        )
        self._remotes.start()
        patch("gitea_audit.audit_enabled", return_value=False).start()
        self.mock_api = patch("mcp_server.api_request").start()
        self.mock_all = patch("mcp_server.api_get_all", return_value=[]).start()
        patch("mcp_server.get_auth_header", return_value=FAKE_AUTH).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.is_head_ancestor_of_ref",
            return_value=True,
        ).start()
        patch(
            "mcp_server.get_profile",
            return_value=dict(RECONCILER_WITH_DELETE),
        ).start()
        patch(
            "mcp_server._profile_operation_gate",
            return_value=[],
        ).start()
        patch(
            "mcp_server._collect_branch_ownership_records",
            return_value={"records": [], "inventory_error": False},
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees",
            return_value=[],
        ).start()
        patch("mcp_server.verify_preflight_purity", return_value=None).start()
        patch(
            "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed",
            return_value=(True, []),
        ).start()
    def tearDown(self):
        patch.stopall()
    def _merged_pr(self, number, branch, sha="c" * 40):
        return {
            "number": number,
            "title": f"PR {number}",
            "body": f"Closes #{number - 4}",
            "merged": True,
            "merged_at": "2026-07-23T12:00:00Z",
            "merge_commit_sha": "f" * 40,
            "state": "closed",
            "head": {"ref": branch, "sha": sha},
            "base": {"ref": "master"},
        }
    def test_exact_pr_848_ignores_newer_852_in_batch_queue(self):
        """pr_number=848 selects only #848 even when #852 is newer/first."""
        from mcp_server import gitea_reconcile_merged_cleanups
        pr_848 = self._merged_pr(
            848, "fix/issue-844-exclude-epic-containers", sha="c3f282ba" + "0" * 32
        )
        # Closed list would rank #852 first in batch mode; exact pin must ignore it.
        closed_batch = [
            self._merged_pr(852, "fix/issue-851-cleanup-worktree-before-remote-delete"),
            pr_848,
            self._merged_pr(849, "fix/issue-849-other"),
            self._merged_pr(846, "fix/issue-846-other"),
            self._merged_pr(845, "fix/issue-845-other"),
        ]
        batch_fetch_calls = []
        def fake_api(method, url, *args, **kwargs):
            if method == "GET" and url.rstrip("/").endswith("/pulls/848"):
                return dict(pr_848)
            if method == "GET" and "/pulls/" in url:
                raise AssertionError(f"unexpected PR fetch: {url}")
            if method == "GET" and "/branches/" in url:
                return {"name": "present"}
            return {}
        def fake_all(url, auth, limit=None):
            batch_fetch_calls.append((url, limit))
            if "state=open" in url:
                return []
            if "state=closed" in url:
                # Exact mode must not use the closed batch list.
                raise AssertionError(
                    "exact pr_number mode must not page closed PRs: " + url
                )
            return []
        self.mock_api.side_effect = fake_api
        self.mock_all.side_effect = fake_all
        patch(
            "mcp_server._remote_branch_exists",
            return_value=True,
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            side_effect=lambda **kwargs: {
                "entries": [
                    {
                        "pr_number": int(pr["number"]),
                        "head_branch": (pr.get("head") or {}).get("ref"),
                        "issue_number": 844,
                        "remote_branch": {
                            "safe_to_delete_remote": True,
                            "head_branch": (pr.get("head") or {}).get("ref"),
                        },
                        "local_worktree": {
                            "safe_to_remove_worktree": True,
                            "worktree_path": (
                                "/tmp/branches/fix-issue-844-exclude-epic-containers"
                            ),
                        },
                        "planned_execution_order": (
                            mcp_server.merged_cleanup_reconcile.plan_cleanup_execution_order(
                                remote_assessment={"safe_to_delete_remote": True},
                                local_assessment={"safe_to_remove_worktree": True},
                            )
                        ),
                    }
                    for pr in kwargs.get("closed_prs") or []
                    if pr.get("merged_at") or pr.get("merged")
                ],
                "reviewer_scratch_entries": [],
                "merged_pr_count": len(kwargs.get("closed_prs") or []),
            },
        ).start()
        res = gitea_reconcile_merged_cleanups(
            dry_run=True,
            pr_number=848,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
        )
        self.assertTrue(res.get("success"))
        self.assertFalse(res.get("performed"))
        self.assertEqual(res.get("selection_mode"), "exact_pr")
        self.assertEqual(res.get("selected_pr_number"), 848)
        entries = res.get("entries") or []
        self.assertEqual(len(entries), 1, entries)
        self.assertEqual(entries[0].get("pr_number"), 848)
        self.assertEqual(
            entries[0].get("head_branch"),
            "fix/issue-844-exclude-epic-containers",
        )
        # No other PR appears in plan.
        self.assertEqual(list((res.get("planned_execution_orders") or {}).keys()), ["848"])
        plan = (res.get("planned_execution_orders") or {}).get("848") or []
        actions = [s.get("action") for s in plan]
        self.assertEqual(
            actions,
            [
                "remove_local_worktree",
                "reassess_branch_ownership",
                "delete_remote_branch",
            ],
        )
        # Prove we never scanned the multi-PR closed batch.
        self.assertFalse(any("state=closed" in (u or "") for u, _ in batch_fetch_calls))
        # closed_batch fixture must remain unused (sanity).
        self.assertEqual(closed_batch[0]["number"], 852)
    def test_exact_pr_execute_only_mutates_selected_pr(self):
        """Execute with pr_number must never touch #845/#846/#849/#852."""
        from mcp_server import gitea_reconcile_merged_cleanups
        pr_848 = self._merged_pr(848, "fix/issue-844-exclude-epic-containers")
        worktree_path = "/tmp/branches/fix-issue-844-exclude-epic-containers"
        remove_calls = []
        delete_api_calls = []
        ownership_branches = []
        def fake_api(method, url, *args, **kwargs):
            if method == "GET" and url.rstrip("/").endswith("/pulls/848"):
                return dict(pr_848)
            if method == "DELETE":
                delete_api_calls.append(url)
                # Forbid foreign PR branch deletion by URL content.
                for forbidden in ("845", "846", "849", "852"):
                    self.assertNotIn(forbidden, url)
            return {}
        def fake_remove(project_root, branch, worktree_path=None):
            remove_calls.append({"branch": branch, "worktree_path": worktree_path})
            return {
                "success": True,
                "performed": True,
                "message": f"removed {worktree_path}",
                "worktree_path": worktree_path,
            }
        def fake_collect(**kwargs):
            ownership_branches.append(kwargs.get("branch"))
            return {"records": [], "inventory_error": False}
        def fake_probe(h, o, r, auth, br):
            return guard.classify_branch_readback_http_status(
                404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH
            )
        self.mock_api.side_effect = fake_api
        self.mock_all.side_effect = lambda url, auth, limit=None: []
        patch("mcp_server._remote_branch_exists", return_value=True).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            return_value={
                "entries": [
                    {
                        "pr_number": 848,
                        "head_branch": "fix/issue-844-exclude-epic-containers",
                        "remote_branch": {"safe_to_delete_remote": True},
                        "local_worktree": {
                            "safe_to_remove_worktree": True,
                            "worktree_path": worktree_path,
                        },
                        "planned_execution_order": [
                            {"action": "remove_local_worktree", "phase": 1},
                            {"action": "reassess_branch_ownership", "phase": 2},
                            {"action": "delete_remote_branch", "phase": 3},
                        ],
                    }
                ],
                "reviewer_scratch_entries": [
                    # Foreign scratch must be filtered before report execute loop;
                    # if present here it would still be a test failure if acted on.
                ],
                "merged_pr_count": 1,
            },
        ).start()
        patch(
            "mcp_server.merged_cleanup_reconcile.remove_local_worktree",
            side_effect=fake_remove,
        ).start()
        patch(
            "mcp_server._collect_branch_ownership_records",
            side_effect=fake_collect,
        ).start()
        patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start()
        res = gitea_reconcile_merged_cleanups(
            dry_run=False,
            execute_confirmed=True,
            pr_number=848,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
        )
        self.assertTrue(res.get("performed") or res.get("executed"))
        self.assertEqual(res.get("selection_mode"), "exact_pr")
        self.assertEqual(res.get("selected_pr_number"), 848)
        actions = res.get("actions") or []
        pr_numbers_touched = {
            a.get("pr_number") for a in actions if a.get("pr_number") is not None
        }
        self.assertTrue(pr_numbers_touched.issubset({None, 848}) or not pr_numbers_touched)
        removes = [a for a in actions if a.get("action") == "remove_local_worktree"]
        deletes = [a for a in actions if a.get("action") == "delete_remote_branch"]
        self.assertEqual(len(removes), 1)
        self.assertEqual(remove_calls[0]["branch"], "fix/issue-844-exclude-epic-containers")
        self.assertEqual(len(deletes), 1)
        self.assertTrue(deletes[0].get("success"))
        self.assertTrue(deletes[0].get("after_worktree_removal"))
        self.assertEqual(len(delete_api_calls), 1)
        self.assertEqual(
            ownership_branches, ["fix/issue-844-exclude-epic-containers"]
        )
    def test_exact_pr_unknown_fails_closed_without_mutation(self):
        from mcp_server import gitea_reconcile_merged_cleanups
        def fake_api(method, url, *args, **kwargs):
            if method == "GET" and "/pulls/99999" in url:
                raise RuntimeError("HTTP 404 Not Found")
            raise AssertionError(f"unexpected API call {method} {url}")
        self.mock_api.side_effect = fake_api
        res = gitea_reconcile_merged_cleanups(
            dry_run=True,
            pr_number=99999,
            remote="prgs",
        )
        self.assertFalse(res.get("success"))
        self.assertFalse(res.get("performed"))
        self.assertEqual(res.get("blocker_kind"), "pr_unresolvable")
        self.assertIn("99999", " ".join(res.get("reasons") or []))
    def test_exact_pr_not_merged_fails_closed(self):
        from mcp_server import gitea_reconcile_merged_cleanups
        def fake_api(method, url, *args, **kwargs):
            if method == "GET" and url.rstrip("/").endswith("/pulls/900"):
                return {
                    "number": 900,
                    "merged": False,
                    "merged_at": None,
                    "state": "open",
                    "head": {"ref": "feat/x", "sha": "a" * 40},
                }
            raise AssertionError(f"unexpected {method} {url}")
        self.mock_api.side_effect = fake_api
        res = gitea_reconcile_merged_cleanups(
            dry_run=False,
            execute_confirmed=True,
            pr_number=900,
            remote="prgs",
        )
        self.assertFalse(res.get("success"))
        self.assertFalse(res.get("performed"))
        self.assertEqual(res.get("blocker_kind"), "pr_not_merged")
    def test_exact_pr_invalid_number_fails_closed(self):
        from mcp_server import gitea_reconcile_merged_cleanups
        res = gitea_reconcile_merged_cleanups(
            dry_run=True,
            pr_number=0,
            remote="prgs",
        )
        self.assertFalse(res.get("success"))
        self.assertEqual(res.get("blocker_kind"), "invalid_pr_number")
        self.mock_api.assert_not_called()
    def test_batch_mode_still_works_without_pr_number(self):
        """Unfiltered batch path remains backward compatible."""
        from mcp_server import gitea_reconcile_merged_cleanups
        self.mock_all.side_effect = lambda url, auth, limit=None: []
        self.mock_api.side_effect = lambda *a, **k: {}
        patch(
            "mcp_server.merged_cleanup_reconcile.build_reconciliation_report",
            return_value={
                "entries": [],
                "reviewer_scratch_entries": [],
                "merged_pr_count": 0,
            },
        ).start()
        res = gitea_reconcile_merged_cleanups(dry_run=True, remote="prgs", limit=10)
        self.assertTrue(res.get("success"))
        self.assertEqual(res.get("selection_mode"), "batch")
        self.assertIsNone(res.get("selected_pr_number"))
 if __name__ == "__main__":
@@ -1,483 +0,0 @@
 """Synthetic regression coverage for dirty orphaned worktree recovery (#860).
 Modeled on the #850 / #855 shape without mutating their real state.
 """
 from __future__ import annotations
 import json
 import os
 import shutil
 import tempfile
 import unittest
 from unittest import mock
 import dirty_orphan_worktree_recovery as dorec
 import issue_lock_store
 DEAD_PID = 999_999_999
 LIVE_PID = os.getpid()
 BRANCH = "fix/issue-901-dirty-orphan"
 SOURCE_WT = "/repo/branches/issue-901-dirty-orphan"
 RECOVERY_WT_NAME = "recovery-issue-901-dirty-orphan"
 LOCAL_HEAD = "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
 REMOTE_HEAD = "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb"
 OTHER_HEAD = "cccccccccccccccccccccccccccccccccccccccc"
 FP_A = dorec.sha256_bytes(b"dirty-a")
 FP_B = dorec.sha256_bytes(b"dirty-b")
 FP_C = dorec.sha256_bytes(b"dirty-c-conflict")
 def durable_lock(**overrides):
    """#850-shaped PID-less malformed same-claimant lock."""
    lock = {
        "issue_number": 901,
        "branch_name": BRANCH,
        "worktree_path": SOURCE_WT,
        "remote": "prgs",
        "org": "Example-Org",
        "repo": "Example-Repo",
        # intentionally no pid / session_pid / work_lease expiry
        "claimant": {"username": "author-user", "profile": "prgs-author"},
    }
    lock.update(overrides)
    return lock
 def base_kwargs(**overrides):
    kwargs = {
        "issue_number": 901,
        "branch_name": BRANCH,
        "source_worktree_path": SOURCE_WT,
        "remote": "prgs",
        "org": "Example-Org",
        "repo": "Example-Repo",
        "identity": "author-user",
        "profile": "prgs-author",
        "expected_local_head": LOCAL_HEAD,
        "expected_remote_head": REMOTE_HEAD,
        "expected_dirty_fingerprints": {"a.py": FP_A, "b.py": FP_B},
        "current_branch": BRANCH,
        "porcelain_status": " M a.py\n M b.py\n",
        "observed_local_head": LOCAL_HEAD,
        "observed_remote_head": REMOTE_HEAD,
        "observed_dirty_fingerprints": {"a.py": FP_A, "b.py": FP_B},
        "competing_live_locks": [],
        "competing_live_sessions": [],
        "workflow_lease_active": False,
        "workflow_lease_expired": True,
        "canonical_repo_root": "/repo",
        "worktree_registered": True,
        "current_pid": LIVE_PID,
    }
    kwargs.update(overrides)
    return kwargs
 def assess(lock=None, **overrides):
    return dorec.assess_dirty_orphan_recovery(
        durable_lock() if lock is None else lock, **base_kwargs(**overrides)
    )
 class FreshnessPidLess(unittest.TestCase):
    def test_pid_less_lock_is_not_live(self):
        freshness = issue_lock_store.assess_lock_freshness(durable_lock())
        self.assertFalse(freshness["live"])
        self.assertTrue(freshness.get("pid_missing"))
        self.assertEqual(freshness["status"], "malformed")
    def test_pid_less_with_far_future_expiry_still_not_live(self):
        lock = durable_lock(
            work_lease={
                "operation_type": "author_issue_work",
                "expires_at": "2999-01-01T00:00:00Z",
                "last_heartbeat_at": "2999-01-01T00:00:00Z",
            }
        )
        freshness = issue_lock_store.assess_lock_freshness(lock)
        self.assertFalse(freshness["live"])
        self.assertTrue(freshness.get("pid_missing"))
 class EligibilityGranted(unittest.TestCase):
    def test_dead_same_claimant_pid_less_dirty(self):
        result = assess()
        self.assertEqual(result["outcome"], dorec.ELIGIBLE)
        self.assertTrue(result["eligible"])
    def test_expired_workflow_lease_corroboration(self):
        result = assess(workflow_lease_active=False, workflow_lease_expired=True)
        self.assertTrue(result["eligible"])
    def test_older_local_newer_remote_heads(self):
        result = assess()
        self.assertTrue(result["evidence"].get("heads_diverged"))
        self.assertTrue(result["eligible"])
 class EligibilityRefused(unittest.TestCase):
    def test_active_owner_with_pid(self):
        lock = durable_lock(pid=LIVE_PID, session_pid=LIVE_PID)
        result = assess(lock=lock, owner_process_alive_override=True)
        self.assertEqual(result["outcome"], dorec.REFUSED)
        self.assertFalse(result["eligible"])
        self.assertTrue(any("alive" in r for r in result["reasons"]))
    def test_foreign_claimant(self):
        result = assess(identity="other-user")
        self.assertEqual(result["outcome"], dorec.REFUSED)
        self.assertTrue(any("foreign claimant identity" in r for r in result["reasons"]))
    def test_foreign_profile(self):
        result = assess(profile="prgs-reviewer")
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_fingerprint_mismatch(self):
        result = assess(observed_dirty_fingerprints={"a.py": "0" * 64, "b.py": FP_B})
        self.assertEqual(result["outcome"], dorec.REFUSED)
        self.assertTrue(any("fingerprint mismatch" in r for r in result["reasons"]))
    def test_head_mismatch(self):
        result = assess(observed_local_head=OTHER_HEAD)
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_remote_head_mismatch(self):
        result = assess(observed_remote_head=OTHER_HEAD)
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_path_not_under_branches(self):
        result = assess(
            source_worktree_path="/tmp/branches/evil",
            # lock path also changed so worktree agreement holds
            lock=durable_lock(worktree_path="/tmp/branches/evil"),
        )
        self.assertEqual(result["outcome"], dorec.REFUSED)
        self.assertTrue(any("canonical branches" in r for r in result["reasons"]))
    def test_unregistered_worktree(self):
        result = assess(worktree_registered=False)
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_active_workflow_lease(self):
        result = assess(workflow_lease_active=True, workflow_lease_expired=False)
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_unsafe_dirty_path_pin(self):
        result = assess(
            expected_dirty_fingerprints={"../etc/passwd": FP_A},
            observed_dirty_fingerprints={"../etc/passwd": FP_A},
        )
        self.assertEqual(result["outcome"], dorec.REFUSED)
    def test_symlink_escape_rejected_by_ancestry(self):
        ok, reasons = dorec.is_path_under_canonical_branches(
            "/tmp/branches/evil", canonical_repo_root="/repo"
        )
        self.assertFalse(ok)
        self.assertTrue(reasons)
 class ConflictDetection(unittest.TestCase):
    def test_overlapping_upstream_change(self):
        conflicts = dorec.detect_path_conflicts(
            dirty_paths=["c.py"],
            local_head_contents={"c.py": b"local-base"},
            remote_head_contents={"c.py": b"remote-changed"},
            dirty_contents={"c.py": b"dirty-c-conflict"},
        )
        self.assertEqual(len(conflicts), 1)
        self.assertEqual(conflicts[0]["path"], "c.py")
    def test_unchanged_upstream_no_conflict(self):
        conflicts = dorec.detect_path_conflicts(
            dirty_paths=["a.py"],
            local_head_contents={"a.py": b"same"},
            remote_head_contents={"a.py": b"same"},
            dirty_contents={"a.py": b"dirty-a"},
        )
        self.assertEqual(conflicts, [])
 class CrashSafeRecovery(unittest.TestCase):
    def setUp(self):
        self.tmp = tempfile.mkdtemp(prefix="dirty-orphan-")
        self.repo = os.path.join(self.tmp, "repo")
        self.branches = os.path.join(self.repo, "branches")
        self.source = os.path.join(self.branches, "issue-901-dirty-orphan")
        self.recovery = os.path.join(self.branches, RECOVERY_WT_NAME)
        os.makedirs(self.source, exist_ok=True)
        os.makedirs(self.branches, exist_ok=True)
        # seed dirty files in source
        with open(os.path.join(self.source, "a.py"), "wb") as fh:
            fh.write(b"dirty-a")
        with open(os.path.join(self.source, "b.py"), "wb") as fh:
            fh.write(b"dirty-b")
        self.journal_dir = os.path.join(self.tmp, "journals")
        self.lock = durable_lock(worktree_path=self.source)
        self.assessment = dorec.assess_dirty_orphan_recovery(
            self.lock,
            **base_kwargs(
                source_worktree_path=self.source,
                canonical_repo_root=self.repo,
            ),
        )
        class FakeGit(dorec.GitOps):
            def __init__(self, recovery_path, head):
                self.recovery_path = recovery_path
                self.head = head
                self.calls = []
            def run(self, args, *, cwd):
                self.calls.append((args, cwd))
                if args[:3] == ["git", "worktree", "add"]:
                    os.makedirs(self.recovery_path, exist_ok=True)
                    return mock.Mock(returncode=0, stdout="", stderr="")
                if args[:2] == ["git", "checkout"]:
                    return mock.Mock(returncode=0, stdout="", stderr="")
                if args[:2] == ["git", "rev-parse"]:
                    return mock.Mock(returncode=0, stdout=self.head + "\n", stderr="")
                return mock.Mock(returncode=0, stdout="", stderr="")
        self.git = FakeGit(self.recovery, REMOTE_HEAD)
        self.written_locks = []
        def lock_writer(record):
            self.written_locks.append(record)
        self.lock_writer = lock_writer
    def tearDown(self):
        shutil.rmtree(self.tmp, ignore_errors=True)
    def _run(self, **overrides):
        kwargs = {
            "assessment": self.assessment,
            "existing_lock": self.lock,
            "issue_number": 901,
            "branch_name": BRANCH,
            "source_worktree_path": self.source,
            "recovery_worktree_path": self.recovery,
            "remote": "prgs",
            "org": "Example-Org",
            "repo": "Example-Repo",
            "identity": "author-user",
            "profile": "prgs-author",
            "expected_local_head": LOCAL_HEAD,
            "expected_remote_head": REMOTE_HEAD,
            "expected_dirty_fingerprints": {"a.py": FP_A, "b.py": FP_B},
            "dirty_contents": {"a.py": b"dirty-a", "b.py": b"dirty-b"},
            "local_head_contents": {"a.py": b"base-a", "b.py": b"base-b"},
            "remote_head_contents": {"a.py": b"base-a", "b.py": b"base-b"},
            "canonical_repo_root": self.repo,
            "bind_lock": True,
            "lock_writer": self.lock_writer,
            "git_ops": self.git,
            "journal_dir": self.journal_dir,
            "session_pid": LIVE_PID,
        }
        kwargs.update(overrides)
        return dorec.run_dirty_orphan_recovery(**kwargs)
    def test_success_preserves_dirty_bytes_and_source(self):
        result = self._run()
        self.assertTrue(result["success"])
        self.assertEqual(result["outcome"], dorec.RECOVERY_COMPLETED)
        self.assertTrue(os.path.isdir(self.source))
        with open(os.path.join(self.source, "a.py"), "rb") as fh:
            self.assertEqual(fh.read(), b"dirty-a")
        with open(os.path.join(self.recovery, "a.py"), "rb") as fh:
            self.assertEqual(fh.read(), b"dirty-a")
        with open(os.path.join(self.recovery, "b.py"), "rb") as fh:
            self.assertEqual(fh.read(), b"dirty-b")
        self.assertEqual(len(self.written_locks), 1)
        rec = self.written_locks[0]
        self.assertEqual(rec["session_pid"], LIVE_PID)
        self.assertTrue(rec["dirty_orphan_recovery"]["recovered"])
        self.assertTrue(rec["dirty_orphan_recovery"]["source_frozen"])
    def test_conflict_leaves_governed_state(self):
        result = self._run(
            expected_dirty_fingerprints={"c.py": FP_C},
            dirty_contents={"c.py": b"dirty-c-conflict"},
            local_head_contents={"c.py": b"local-base"},
            remote_head_contents={"c.py": b"remote-changed"},
        )
        # #860 F4: session binding is NOT finalized while conflicts remain
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], dorec.CONFLICTS_PRESENT)
        sidecar = os.path.join(self.recovery, "c.py.recovered-dirty")
        self.assertTrue(os.path.isfile(sidecar))
        state = os.path.join(
            self.recovery, dorec.CONFLICT_STATE_DIR, dorec.CONFLICT_STATE_FILE
        )
        self.assertTrue(os.path.isfile(state))
        with open(state, "r", encoding="utf-8") as fh:
            payload = json.load(fh)
        self.assertEqual(payload["resolution"], "author_edit_required")
    def test_interrupt_before_journal_no_artifacts(self):
        result = self._run(interrupt_after_phase=dorec.PHASE_ELIGIBILITY)
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "INTERRUPTED")
        self.assertFalse(os.path.isdir(self.recovery))
    def test_interrupt_after_journal_then_retry_idempotent(self):
        first = self._run(interrupt_after_phase=dorec.PHASE_JOURNAL_PERSISTED)
        self.assertEqual(first["outcome"], "INTERRUPTED")
        self.assertTrue(first["journal"]["artifacts_created"]["journal"])
        second = self._run()
        self.assertTrue(second["success"])
        # source still recoverable
        with open(os.path.join(self.source, "a.py"), "rb") as fh:
            self.assertEqual(fh.read(), b"dirty-a")
    def test_interrupt_after_worktree_then_retry(self):
        first = self._run(interrupt_after_phase=dorec.PHASE_RECOVERY_WORKTREE)
        self.assertEqual(first["outcome"], "INTERRUPTED")
        self.assertTrue(os.path.isdir(self.recovery))
        second = self._run()
        self.assertTrue(second["success"])
    def test_interrupt_after_binding_then_retry_complete(self):
        first = self._run(interrupt_after_phase=dorec.PHASE_BINDING)
        self.assertEqual(first["outcome"], "INTERRUPTED")
        second = self._run()
        self.assertTrue(second["success"])
        # completed journal makes further retries no-ops
        third = self._run()
        self.assertEqual(third["outcome"], dorec.RECOVERY_RESUMED)
    def test_source_worktree_never_deleted(self):
        self._run()
        self.assertTrue(os.path.isdir(self.source))
        self.assertTrue(os.path.isfile(os.path.join(self.source, "a.py")))
    def test_fingerprint_drift_refuses_without_mutation(self):
        result = self._run(dirty_contents={"a.py": b"CHANGED", "b.py": b"dirty-b"})
        self.assertFalse(result["success"])
        self.assertFalse(os.path.isdir(self.recovery))
 class SessionBindingPreflight(unittest.TestCase):
    def test_canonical_session_binding_recognized(self):
        lock = {
            "worktree_path": "/repo/branches/recovery",
            "session_pid": LIVE_PID,
            "dirty_orphan_recovery": {
                "recovered": True,
                "conflicts": [],
                "recovery_worktree_path": "/repo/branches/recovery",
                "source_worktree_path": SOURCE_WT,
                "accepted_head": REMOTE_HEAD,
            },
        }
        result = dorec.preflight_recognizes_recovered_provenance(lock)
        self.assertTrue(result["recognized"])
    def test_conflicts_block_commit_preflight(self):
        lock = {
            "worktree_path": "/repo/branches/recovery",
            "session_pid": LIVE_PID,
            "dirty_orphan_recovery": {
                "recovered": True,
                "conflicts": [{"path": "c.py"}],
            },
        }
        result = dorec.preflight_recognizes_recovered_provenance(lock)
        self.assertFalse(result["recognized"])
    def test_active_foreign_does_not_mutate(self):
        # assess-only path: foreign refused before run
        result = assess(identity="intruder")
        self.assertFalse(result["eligible"])
 class JournalSymlinkRefusal(unittest.TestCase):
    def test_symlink_journal_path_refused_on_load(self):
        tmp = tempfile.mkdtemp()
        try:
            real = os.path.join(tmp, "real.json")
            with open(real, "w", encoding="utf-8") as fh:
                fh.write("{}")
            link = os.path.join(tmp, "link.json")
            os.symlink(real, link)
            key = "symlink-test"
            jdir = tmp
            path = dorec._journal_path(key, journal_dir=jdir)
            with open(path, "w", encoding="utf-8") as fh:
                json.dump({"idempotency_key": key}, fh)
            os.remove(path)
            os.symlink(real, path)
            with self.assertRaises(ValueError):
                dorec.load_journal(key, journal_dir=jdir)
        finally:
            shutil.rmtree(tmp, ignore_errors=True)
 class RealGitMultiWorktreeIntegration(unittest.TestCase):
    def setUp(self):
        import subprocess
        self.tmp = tempfile.mkdtemp(prefix="git-integration-")
        self.repo = os.path.join(self.tmp, "repo")
        os.makedirs(self.repo, exist_ok=True)
        subprocess.run(["git", "init"], cwd=self.repo, check=True, capture_output=True)
        subprocess.run(["git", "config", "user.name", "Test User"], cwd=self.repo, check=True)
        subprocess.run(["git", "config", "user.email", "[email protected]"], cwd=self.repo, check=True)
        with open(os.path.join(self.repo, "init.txt"), "w") as fh:
            fh.write("init")
        subprocess.run(["git", "add", "."], cwd=self.repo, check=True)
        subprocess.run(["git", "commit", "-m", "init"], cwd=self.repo, check=True)
        branch = "fix/issue-999-test"
        subprocess.run(["git", "branch", branch], cwd=self.repo, check=True)
        self.branches = os.path.join(self.repo, "branches")
        self.source = os.path.join(self.branches, "issue-999-test")
        subprocess.run(["git", "worktree", "add", self.source, branch], cwd=self.repo, check=True)
        self.dirty_path = os.path.join(self.source, "dirty.txt")
        with open(self.dirty_path, "w") as fh:
            fh.write("dirty-data")
    def tearDown(self):
        shutil.rmtree(self.tmp, ignore_errors=True)
    def test_prepare_recovery_worktree_detached_no_exit_128(self):
        import subprocess
        head_sha = subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=self.repo, text=True).strip()
        rec_wt = os.path.join(self.branches, "recovery-issue-999-test")
        res = dorec.prepare_recovery_worktree(
            canonical_repo_root=self.repo,
            recovery_worktree_path=rec_wt,
            branch_name="fix/issue-999-test",
            remote_head=head_sha,
        )
        self.assertTrue(res["success"], res.get("reasons"))
        self.assertTrue(os.path.isdir(rec_wt))
    def test_real_lock_rebind_recovery_sanctioned(self):
        lock_dir = os.path.join(self.tmp, "locks")
        rec_wt = os.path.join(self.branches, "recovery-issue-999-test")
        os.makedirs(rec_wt, exist_ok=True)
        record = {
            "remote": "prgs",
            "org": "Example-Org",
            "repo": "Example-Repo",
            "issue_number": 999,
            "branch_name": "fix/issue-999-test",
            "worktree_path": rec_wt,
            "claimant": {"username": "author-user", "profile": "prgs-author"},
        }
        record_src = dict(record)
        record_src["worktree_path"] = self.source
        issue_lock_store.bind_session_lock(record_src, lock_dir=lock_dir)
        path = issue_lock_store.bind_session_lock(
            record,
            lock_dir=lock_dir,
            recovery_sanctioned=True,
        )
        self.assertTrue(os.path.isfile(path))
 if __name__ == "__main__":
    unittest.main()
@@ -1,682 +0,0 @@
 """Cross-role allocation handoff consumable by independent workers (#843).
 Regression coverage for the controller→required-role consume path:
 * controller allocates author work; independent author adopts successfully
 * author adoption succeeds after allocating controller process exits
 * author adoption without sharing controller session identity
 * wrong-role adoption rejected
 * concurrent/second adoption rejected without state corruption
 * terminal allocation adoption rejected
 * successful adoption produces authoritative ownership evidence
 * genuine abandoned-lease recovery remains valid
 * process_work_queue / allocate results include consume identifiers
 * same-role allocation behavior remains compatible
 """
 from __future__ import annotations
 import os
 import tempfile
 import unittest
 from datetime import timedelta
 from unittest.mock import patch
 from allocator_service import (
    ALLOCATION_MODE_CROSS_ROLE,
    ALLOCATION_MODE_ROLE_SCOPED,
    OUTCOME_ASSIGNED,
    ROLE_AUTHOR,
    ROLE_CONTROLLER,
    ROLE_REVIEWER,
    WorkCandidate,
    allocate_next_work,
 )
 from control_plane_db import ControlPlaneDB, ForeignLeaseError, _ts, _utc_now
 import lease_lifecycle as ll
 class CrossRoleHandoffTest(unittest.TestCase):
    def setUp(self) -> None:
        self._tmp = tempfile.TemporaryDirectory()
        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
        self.db = ControlPlaneDB(self.db_path)
        self.db.upsert_session(
            session_id="ctrl-session",
            role="controller",
            profile="prgs-controller",
            pid=99999999,  # dead-looking pid
        )
        self.db.upsert_session(
            session_id="author-worker",
            role="author",
            profile="prgs-author",
            pid=os.getpid(),
        )
        self.db.upsert_session(
            session_id="author-worker-2",
            role="author",
            profile="prgs-author",
            pid=os.getpid(),
        )
        self.db.upsert_session(
            session_id="reviewer-worker",
            role="reviewer",
            profile="prgs-reviewer",
            pid=os.getpid(),
        )
        self.wt = self._tmp.name
    def tearDown(self) -> None:
        self._tmp.cleanup()
    def _ready_issue(self, number: int = 843, title: str = "handoff target") -> WorkCandidate:
        return WorkCandidate(
            kind="issue",
            number=number,
            labels=("status:ready", "type:bug"),
            title=title,
            priority=20,
        )
    def _controller_allocate(self, number: int = 843, **kwargs):
        defaults = dict(
            db=self.db,
            session_id="ctrl-session",
            role=ROLE_CONTROLLER,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
            candidates=[self._ready_issue(number)],
            apply=True,
            profile_name="prgs-controller",
            username="controller-user",
            allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
        )
        defaults.update(kwargs)
        return allocate_next_work(**defaults)
    def test_controller_allocates_author_independent_author_adopts(self) -> None:
        res = self._controller_allocate()
        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
        self.assertEqual(res["required_role"], ROLE_AUTHOR)
        self.assertIn("consume_allocation", res)
        consume = res["consume_allocation"]
        self.assertEqual(consume["tool"], "gitea_adopt_workflow_lease")
        self.assertEqual(consume["required_role"], ROLE_AUTHOR)
        self.assertFalse(consume["controller_session_required"])
        lid = res["assignment"]["lease_id"]
        self.assertEqual(consume["lease_id"], lid)
        self.assertIn(lid, res["next_valid_command"])
        adopted = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertTrue(adopted["success"])
        self.assertEqual(adopted["outcome"], "adopted_cross_role_handoff")
        self.assertEqual(adopted["adopted_by_session_id"], "author-worker")
        self.assertEqual(adopted["adopted_from_session_id"], "ctrl-session")
        raw = adopted["read_after_write"]
        self.assertEqual(raw["session_id"], "author-worker")
        self.assertEqual(raw["adopted_by_session_id"], "author-worker")
        self.assertEqual(raw["status"], "active")
        self.assertEqual(raw["phase"], "adopted")
        # Authoritative re-read
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "author-worker")
        self.assertEqual(state["lease"]["adopted_by_session_id"], "author-worker")
        self.assertEqual(state["assignment"]["session_id"], "author-worker")
        self.assertEqual(state["provenance"]["handoff_status"], "adopted")
    def test_author_adoption_after_controller_process_exits(self) -> None:
        res = self._controller_allocate(number=900)
        lid = res["assignment"]["lease_id"]
        # Force owner_pid dead + freshness stale_dead_process
        import sqlite3
        conn = sqlite3.connect(self.db_path)
        try:
            conn.execute(
                "UPDATE leases SET owner_pid = 99999999 WHERE lease_id = ?",
                (lid,),
            )
            conn.commit()
        finally:
            conn.close()
        state = self.db.get_lease_workflow_state(lid)
        fr = ll.classify_lease_freshness(
            state["lease"], pid_checker=lambda _p: False
        )
        self.assertEqual(fr["freshness"], "stale_dead_process")
        adopted = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertEqual(adopted["outcome"], "adopted_cross_role_handoff")
        self.assertEqual(adopted["adopted_by_session_id"], "author-worker")
        # No abandon required
        state2 = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state2["lease"]["status"], "active")
        self.assertNotEqual(state2["lease"]["status"], "abandoned")
    def test_adoption_without_sharing_controller_session_identity(self) -> None:
        res = self._controller_allocate(number=901)
        lid = res["assignment"]["lease_id"]
        adopted = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertNotEqual(adopted["adopted_by_session_id"], "ctrl-session")
        self.assertFalse(adopted["same_owner"])
        self.assertEqual(adopted["adopted_from_session_id"], "ctrl-session")
    def test_wrong_role_adoption_rejected(self) -> None:
        res = self._controller_allocate(number=902)
        lid = res["assignment"]["lease_id"]
        with self.assertRaises(ll.LeaseLifecycleError) as ctx:
            ll.adopt_lease(
                self.db,
                lease_id=lid,
                adopter_session_id="reviewer-worker",
                role=ROLE_REVIEWER,
            )
        self.assertIn("wrong role", str(ctx.exception).lower())
        # State unchanged
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "ctrl-session")
        self.assertIsNone(state["lease"].get("adopted_by_session_id") or None)
        self.assertEqual(state["provenance"]["handoff_status"], "pending")
    def test_second_adoption_rejected_without_corruption(self) -> None:
        res = self._controller_allocate(number=903)
        lid = res["assignment"]["lease_id"]
        first = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertEqual(first["outcome"], "adopted_cross_role_handoff")
        with self.assertRaises(ll.LeaseLifecycleError):
            ll.adopt_lease(
                self.db,
                lease_id=lid,
                adopter_session_id="author-worker-2",
                role=ROLE_AUTHOR,
                worktree_path=self.wt,
            )
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "author-worker")
        self.assertEqual(state["lease"]["adopted_by_session_id"], "author-worker")
        self.assertEqual(state["assignment"]["session_id"], "author-worker")
        self.assertEqual(state["lease"]["status"], "active")
    def test_terminal_allocation_adoption_rejected(self) -> None:
        res = self._controller_allocate(number=904)
        lid = res["assignment"]["lease_id"]
        # Abandon as terminal
        proof = ll.AbandonProof(
            dead_process=True,
            missing_worktree=True,
            no_open_pr=True,
            no_live_mutation_risk=True,
            owner_pid=99999999,
            worktree_path="/nonexistent/for-843",
        )
        # Attach dead pid / missing wt for abandon eligibility
        import sqlite3
        conn = sqlite3.connect(self.db_path)
        try:
            conn.execute(
                "UPDATE leases SET owner_pid = 99999999, worktree_path = ? WHERE lease_id = ?",
                ("/nonexistent/for-843", lid),
            )
            conn.commit()
        finally:
            conn.close()
        abandoned = ll.abandon_lease(
            self.db,
            lease_id=lid,
            requester_session_id="author-worker",
            proof=proof,
        )
        self.assertEqual(abandoned["outcome"], "abandoned")
        with self.assertRaises(ll.LeaseLifecycleError) as ctx:
            ll.adopt_lease(
                self.db,
                lease_id=lid,
                adopter_session_id="author-worker",
                role=ROLE_AUTHOR,
            )
        self.assertIn("abandoned", str(ctx.exception).lower())
    def test_successful_adoption_read_after_write_ownership(self) -> None:
        res = self._controller_allocate(number=905)
        lid = res["assignment"]["lease_id"]
        adopted = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        raw = adopted["read_after_write"]
        self.assertEqual(raw["lease_id"], lid)
        self.assertEqual(raw["session_id"], "author-worker")
        self.assertEqual(raw["adopted_by_session_id"], "author-worker")
        self.assertEqual(raw["adopted_from_session_id"], "ctrl-session")
        # Re-fetch proves durable write
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], raw["session_id"])
        self.assertEqual(
            state["lease"]["adopted_by_session_id"], raw["adopted_by_session_id"]
        )
    def test_genuine_abandoned_recovery_still_valid(self) -> None:
        """Same-role author lease abandoned remains reclaimable via abandon path."""
        same = allocate_next_work(
            self.db,
            session_id="author-worker",
            role=ROLE_AUTHOR,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
            candidates=[self._ready_issue(906, "same-role")],
            apply=True,
            profile_name="prgs-author",
            username="author-user",
            allocation_mode=ALLOCATION_MODE_ROLE_SCOPED,
        )
        self.assertEqual(same["outcome"], OUTCOME_ASSIGNED)
        lid = same["assignment"]["lease_id"]
        import sqlite3
        conn = sqlite3.connect(self.db_path)
        try:
            conn.execute(
                "UPDATE leases SET owner_pid = 99999999, worktree_path = ? WHERE lease_id = ?",
                ("/nonexistent/same-role", lid),
            )
            conn.commit()
        finally:
            conn.close()
        proof = ll.AbandonProof(
            dead_process=True,
            missing_worktree=True,
            no_open_pr=True,
            no_live_mutation_risk=True,
            owner_pid=99999999,
            worktree_path="/nonexistent/same-role",
        )
        abandoned = ll.abandon_lease(
            self.db,
            lease_id=lid,
            requester_session_id="author-worker-2",
            proof=proof,
        )
        self.assertEqual(abandoned["outcome"], "abandoned")
        # Foreign author cannot handoff-consume an abandoned non-handoff lease
        with self.assertRaises(ll.LeaseLifecycleError):
            ll.adopt_lease(
                self.db,
                lease_id=lid,
                adopter_session_id="author-worker-2",
                role=ROLE_AUTHOR,
            )
        # Reclaim path still works for expired/abandoned after force-expire
        reclaimed = ll.reclaim_expired_lease(
            self.db,
            lease_id=lid,
            session_id="author-worker-2",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertEqual(reclaimed["outcome"], "reclaimed")
        self.assertEqual(reclaimed["assignment"]["session_id"], "author-worker-2")
    def test_allocate_payload_includes_consume_identifiers(self) -> None:
        res = self._controller_allocate(number=907)
        self.assertIn("consume_allocation", res)
        c = res["consume_allocation"]
        for key in (
            "tool",
            "lease_id",
            "assignment_id",
            "required_role",
            "required_profile",
            "required_namespace",
            "instructions",
            "handoff_status",
        ):
            self.assertIn(key, c)
        self.assertEqual(c["required_namespace"], "gitea-author")
        self.assertEqual(c["required_profile"], "prgs-author")
        self.assertIn("gitea_adopt_workflow_lease", c["instructions"])
        self.assertTrue(res["lease_proof"]["cross_role_handoff"])
        self.assertEqual(res["lease_proof"]["handoff_status"], "pending")
    def test_same_role_allocation_remains_compatible(self) -> None:
        res = allocate_next_work(
            self.db,
            session_id="author-worker",
            role=ROLE_AUTHOR,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
            candidates=[self._ready_issue(908)],
            apply=True,
            profile_name="prgs-author",
            username="author-user",
        )
        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
        self.assertNotIn("consume_allocation", res)
        lid = res["assignment"]["lease_id"]
        state = self.db.get_lease_workflow_state(lid)
        # No cross-role handoff provenance
        prov = state.get("provenance") or {}
        self.assertFalse(prov.get("cross_role_handoff"))
        # Owner resume still works
        resume = ll.adopt_lease(
            self.db,
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
        )
        self.assertTrue(resume["same_owner"])
        self.assertEqual(resume["outcome"], "adopted_owner_resume")
    def test_inspect_points_required_role_at_consume(self) -> None:
        res = self._controller_allocate(number=909)
        lid = res["assignment"]["lease_id"]
        decision = ll.inspect_lease(
            self.db, lid, caller_session_id="author-worker"
        )
        self.assertEqual(
            decision["safe_next_action"], ll.SAFE_CONSUME_CROSS_ROLE
        )
        self.assertFalse(decision["block"])
        self.assertEqual(decision["required_role"], ROLE_AUTHOR)
    def test_db_cas_rejects_concurrent_second_consume(self) -> None:
        res = self._controller_allocate(number=910)
        lid = res["assignment"]["lease_id"]
        # First consume via DB layer directly
        first = self.db.adopt_lease(
            lease_id=lid,
            adopter_session_id="author-worker",
            role=ROLE_AUTHOR,
            worktree_path=self.wt,
            provenance={
                "cross_role_handoff": True,
                "handoff_status": "adopted",
                "required_role": "author",
            },
        )
        self.assertEqual(first["outcome"], "adopted_cross_role_handoff")
        # Second CAS must fail
        with self.assertRaises(ForeignLeaseError):
            self.db.adopt_lease(
                lease_id=lid,
                adopter_session_id="author-worker-2",
                role=ROLE_AUTHOR,
                worktree_path=self.wt,
                provenance={
                    "cross_role_handoff": True,
                    "handoff_status": "pending",
                    "required_role": "author",
                },
            )
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "author-worker")
 class MCPBoundaryAdoptRoleBindingTest(unittest.TestCase):
    """#843 F1: MCP-boundary role binding for ``gitea_adopt_workflow_lease``.
    The library-level wrong-role test calls ``lease_lifecycle.adopt_lease``
    directly. These tests prove the MCP entry point derives the adopter role
    authoritatively from the active authenticated profile and rejects any
    caller-supplied role that disagrees, so a reviewer/merger profile cannot
    consume an author handoff by passing ``role="author"``.
    """
    AUTHOR_PROFILE = {
        "profile_name": "prgs-author",
        "role": "author",
        "allowed_operations": [
            "gitea.read",
            "gitea.pr.create",
            "gitea.branch.push",
        ],
        "forbidden_operations": [],
    }
    REVIEWER_PROFILE = {
        "profile_name": "prgs-reviewer",
        "role": "reviewer",
        "allowed_operations": [
            "gitea.read",
            "gitea.pr.review",
            "gitea.pr.approve",
            "gitea.pr.request_changes",
        ],
        "forbidden_operations": ["gitea.pr.create", "gitea.branch.push"],
    }
    MERGER_PROFILE = {
        "profile_name": "prgs-merger",
        "role": "merger",
        "allowed_operations": ["gitea.read", "gitea.pr.merge"],
        "forbidden_operations": ["gitea.pr.create", "gitea.branch.push"],
    }
    FOREIGN_AUTHOR_PROFILE = {
        "profile_name": "dadeschools-author",
        "role": "author",
        "allowed_operations": [
            "gitea.read",
            "gitea.pr.create",
            "gitea.branch.push",
        ],
        "forbidden_operations": [],
    }
    def setUp(self) -> None:
        self._tmp = tempfile.TemporaryDirectory()
        self.db_path = os.path.join(self._tmp.name, "cp.sqlite3")
        self.db = ControlPlaneDB(self.db_path)
        self.db.upsert_session(
            session_id="ctrl-session",
            role="controller",
            profile="prgs-controller",
            pid=99999999,
        )
        self.db.upsert_session(
            session_id="author-worker",
            role="author",
            profile="prgs-author",
            pid=os.getpid(),
        )
        self.wt = self._tmp.name
    def tearDown(self) -> None:
        self._tmp.cleanup()
    def _ready_issue(self, number: int) -> WorkCandidate:
        return WorkCandidate(
            kind="issue",
            number=number,
            labels=("status:ready", "type:bug"),
            title="handoff target",
            priority=20,
        )
    def _handoff_lease(self, number: int = 843) -> str:
        res = allocate_next_work(
            db=self.db,
            session_id="ctrl-session",
            role=ROLE_CONTROLLER,
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
            candidates=[self._ready_issue(number)],
            apply=True,
            profile_name="prgs-controller",
            username="controller-user",
            allocation_mode=ALLOCATION_MODE_CROSS_ROLE,
        )
        self.assertEqual(res["outcome"], OUTCOME_ASSIGNED)
        self.assertEqual(res["required_role"], ROLE_AUTHOR)
        return res["assignment"]["lease_id"]
    def _call_adopt_tool(self, profile: dict, **kwargs):
        import gitea_mcp_server as mcp_server
        with (
            patch.object(mcp_server, "get_profile", return_value=profile),
            patch.object(
                mcp_server,
                "_control_plane_db_or_error",
                return_value=(self.db, []),
            ),
        ):
            return mcp_server.gitea_adopt_workflow_lease(
                remote="prgs", **kwargs
            )
    def _assert_handoff_untouched(self, lease_id: str) -> None:
        state = self.db.get_lease_workflow_state(lease_id)
        self.assertEqual(state["lease"]["session_id"], "ctrl-session")
        self.assertIsNone(state["lease"].get("adopted_by_session_id") or None)
        self.assertEqual(state["lease"]["status"], "active")
        self.assertEqual(state["provenance"]["handoff_status"], "pending")
    def test_reviewer_profile_cannot_consume_author_handoff_via_role_author(
        self,
    ) -> None:
        lid = self._handoff_lease(920)
        result = self._call_adopt_tool(
            self.REVIEWER_PROFILE,
            lease_id=lid,
            session_id="reviewer-worker",
            role="author",
            worktree_path=self.wt,
        )
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "blocked")
        self.assertEqual(result["profile_role_kind"], "reviewer")
        self.assertEqual(result["supplied_role"], "author")
        self.assertIn("does not match", result["reasons"][0])
        self._assert_handoff_untouched(lid)
    def test_merger_profile_cannot_consume_author_handoff_via_role_author(
        self,
    ) -> None:
        lid = self._handoff_lease(921)
        result = self._call_adopt_tool(
            self.MERGER_PROFILE,
            lease_id=lid,
            session_id="merger-worker",
            role="author",
            worktree_path=self.wt,
        )
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "blocked")
        self.assertEqual(result["profile_role_kind"], "merger")
        self._assert_handoff_untouched(lid)
    def test_reviewer_profile_rejected_without_role_argument(self) -> None:
        """Even without a spoofed role, the profile-derived role binds."""
        lid = self._handoff_lease(922)
        result = self._call_adopt_tool(
            self.REVIEWER_PROFILE,
            lease_id=lid,
            session_id="reviewer-worker",
            worktree_path=self.wt,
        )
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "blocked")
        self.assertIn("wrong role", result["reasons"][0].lower())
        self._assert_handoff_untouched(lid)
    def test_author_profile_mismatching_supplied_role_rejected(self) -> None:
        lid = self._handoff_lease(923)
        result = self._call_adopt_tool(
            self.AUTHOR_PROFILE,
            lease_id=lid,
            session_id="author-worker",
            role="reviewer",
            worktree_path=self.wt,
        )
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "blocked")
        self.assertEqual(result["profile_role_kind"], "author")
        self.assertEqual(result["supplied_role"], "reviewer")
        self._assert_handoff_untouched(lid)
    def test_foreign_profile_name_rejected_for_author_handoff(self) -> None:
        """Provenance required_profile binds even when the role matches."""
        lid = self._handoff_lease(924)
        result = self._call_adopt_tool(
            self.FOREIGN_AUTHOR_PROFILE,
            lease_id=lid,
            session_id="foreign-author-worker",
            worktree_path=self.wt,
        )
        self.assertFalse(result["success"])
        self.assertEqual(result["outcome"], "blocked")
        self.assertIn("wrong profile", result["reasons"][0].lower())
        self._assert_handoff_untouched(lid)
    def test_author_profile_consumes_author_handoff(self) -> None:
        lid = self._handoff_lease(925)
        result = self._call_adopt_tool(
            self.AUTHOR_PROFILE,
            lease_id=lid,
            session_id="author-worker",
            role="author",
            worktree_path=self.wt,
        )
        self.assertTrue(result["success"])
        self.assertEqual(result["outcome"], "adopted_cross_role_handoff")
        self.assertEqual(result["adopted_by_session_id"], "author-worker")
        self.assertEqual(result["adopted_from_session_id"], "ctrl-session")
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "author-worker")
        self.assertEqual(
            state["lease"]["adopted_by_session_id"], "author-worker"
        )
        self.assertEqual(state["assignment"]["session_id"], "author-worker")
        self.assertEqual(state["provenance"]["handoff_status"], "adopted")
    def test_author_profile_consumes_author_handoff_without_role_argument(
        self,
    ) -> None:
        lid = self._handoff_lease(926)
        result = self._call_adopt_tool(
            self.AUTHOR_PROFILE,
            lease_id=lid,
            session_id="author-worker",
            worktree_path=self.wt,
        )
        self.assertTrue(result["success"])
        self.assertEqual(result["outcome"], "adopted_cross_role_handoff")
        state = self.db.get_lease_workflow_state(lid)
        self.assertEqual(state["lease"]["session_id"], "author-worker")
        self.assertEqual(state["lease"]["role"], "author")
 if __name__ == "__main__":
    unittest.main()
@@ -1,244 +0,0 @@
 """#855 AC4: an expired reviewer lease must not indefinitely protect an
 already-merged branch when no live claimant exists.
 Two layers are covered:
 * ``branch_cleanup_guard.assess_expired_reviewer_lease_reclaim`` — the pure,
  fail-closed reclaim decision. Every condition must be provably satisfied or
  the lease keeps protecting the branch.
 * ``gitea_mcp_server._collect_branch_ownership_records`` — the wiring that
  supplies authoritative evidence (PR merged state, owner-process liveness,
  competing ownership) to that decision, and flips an expired reviewer lease
  to reclaimable only under the full policy.
 All inputs are fabricated; no real repository, lease, or credential is used.
 """
 import importlib
 import unittest
 from unittest.mock import patch
 import branch_cleanup_guard
 mcp_server = importlib.import_module("gitea_mcp_server")
 FAKE_AUTH = "token fake"
 REMOTE = "prgs"
 ORG = "Scaled-Tech-Consulting"
 REPO = "Gitea-Tools"
 HOST = "gitea.prgs.cc"
 BRANCH = "feat/issue-638-webui-app-shell-phase1"
 PR_NUMBER = 818
 class TestAssessExpiredReviewerLeaseReclaim(unittest.TestCase):
    """Pure fail-closed reclaim decision (#855 AC4)."""
    def _call(self, **overrides):
        base = dict(
            role="reviewer",
            status="expired",
            pr_merged=True,
            owner_pid_alive=False,
            competing_active_claimant=False,
        )
        base.update(overrides)
        return branch_cleanup_guard.assess_expired_reviewer_lease_reclaim(**base)
    def test_full_policy_satisfied_allows_reclaim(self):
        out = self._call()
        self.assertTrue(out["reclaim_allowed"])
        self.assertEqual(out["reasons"], [])
        self.assertEqual(out["decision"], "reclaim_expired_reviewer_lease")
    def test_stale_dead_process_reviewer_also_reclaimable(self):
        out = self._call(status="stale_dead_process")
        self.assertTrue(out["reclaim_allowed"])
    def test_non_reviewer_role_never_reclaims(self):
        for role in ("author", "merger", "controller", "reconciler", "unknown"):
            with self.subTest(role=role):
                out = self._call(role=role)
                self.assertFalse(out["reclaim_allowed"])
                self.assertTrue(out["reasons"])
                self.assertEqual(out["decision"], "keep_protecting")
    def test_active_status_never_reclaims(self):
        out = self._call(status="active")
        self.assertFalse(out["reclaim_allowed"])
    def test_pr_not_merged_blocks_reclaim(self):
        out = self._call(pr_merged=False)
        self.assertFalse(out["reclaim_allowed"])
    def test_pr_merged_unknown_fails_closed(self):
        out = self._call(pr_merged=None)
        self.assertFalse(out["reclaim_allowed"])
    def test_owner_process_alive_blocks_reclaim(self):
        out = self._call(owner_pid_alive=True)
        self.assertFalse(out["reclaim_allowed"])
    def test_owner_liveness_unknown_fails_closed(self):
        out = self._call(owner_pid_alive=None)
        self.assertFalse(out["reclaim_allowed"])
    def test_competing_active_claimant_blocks_reclaim(self):
        out = self._call(competing_active_claimant=True)
        self.assertFalse(out["reclaim_allowed"])
    def test_competing_claimant_unknown_fails_closed(self):
        out = self._call(competing_active_claimant=None)
        self.assertFalse(out["reclaim_allowed"])
    def test_reasons_never_leak_secrets(self):
        out = self._call(role="author")
        blob = " ".join(out["reasons"]).lower()
        self.assertNotIn("token", blob)
        self.assertNotIn("password", blob)
 class _FakeLease(dict):
    pass
 class TestCollectorExpiredReviewerReclaimWiring(unittest.TestCase):
    """`_collect_branch_ownership_records` supplies authoritative evidence and
    flips an expired reviewer lease to reclaimable only under the full policy."""
    def _run(
        self,
        *,
        lease_role="reviewer",
        lease_freshness="stale_dead_process",
        owner_pid_alive=False,
        pr_merged=True,
        extra_leases=None,
        worktree_on_branch=False,
    ):
        lease = _FakeLease(
            role=lease_role,
            work_kind="pr",
            work_number=PR_NUMBER,
            branch=BRANCH,
            status="active",
            owner_pid=999999,
            remote=REMOTE,
            org=ORG,
            repo=REPO,
            host=HOST,
            freshness={
                "freshness": lease_freshness,
                "owner_pid": 999999,
                "owner_pid_alive": owner_pid_alive,
                "expired_by_time": lease_freshness == "expired",
            },
        )
        leases = [lease] + list(extra_leases or [])
        pr_payload = {
            "number": PR_NUMBER,
            "merged": pr_merged,
            "merged_at": "2026-07-23T00:00:00Z" if pr_merged else None,
            "head": {"ref": BRANCH},
        }
        def fake_api_request(method, url, *a, **k):
            if method == "GET" and f"/pulls/{PR_NUMBER}" in url:
                return pr_payload
            raise AssertionError(f"unexpected api_request {method} {url}")
        wt_entries = []
        if worktree_on_branch:
            wt_entries = [{"branch": BRANCH, "path": f"/x/branches/{BRANCH}"}]
        with patch.object(
            mcp_server.lease_lifecycle,
            "list_active_leases",
            return_value={"leases": leases},
        ), patch.object(
            mcp_server.control_plane_db, "get_db", return_value=object(), create=True
        ), patch.object(
            mcp_server.issue_lock_store, "iter_lock_files", return_value=[]
        ), patch.object(
            mcp_server.worktree_cleanup_audit,
            "list_worktrees",
            return_value=wt_entries,
        ), patch.object(
            mcp_server, "api_get_all", return_value=[]
        ), patch.object(
            mcp_server, "api_request", side_effect=fake_api_request
        ):
            return mcp_server._collect_branch_ownership_records(
                remote=REMOTE,
                host=HOST,
                org=ORG,
                repo=REPO,
                branch=BRANCH,
                pr_number=PR_NUMBER,
                project_root="/x",
                auth=FAKE_AUTH,
                base_api="https://gitea.prgs.cc/api/v1/repos/x/y",
            )
    def _reviewer_records(self, bundle):
        return [
            rec
            for rec in bundle["records"]
            if rec.get("category")
            == branch_cleanup_guard.OWNERSHIP_CATEGORY_REVIEWER_LEASE
        ]
    def test_merged_dead_uncontested_reviewer_lease_is_reclaimable(self):
        bundle = self._run()
        self.assertFalse(bundle["inventory_error"])
        recs = self._reviewer_records(bundle)
        self.assertEqual(len(recs), 1)
        self.assertTrue(recs[0]["reclaim_allowed"])
        # And the guard consequently does not block deletion on it.
        ownership = branch_cleanup_guard.assess_active_branch_ownership(
            remote=REMOTE, org=ORG, repo=REPO, branch=BRANCH, host=HOST,
            records=bundle["records"],
        )
        self.assertFalse(ownership["block"])
    def test_unmerged_pr_keeps_reviewer_lease_protective(self):
        bundle = self._run(pr_merged=False)
        recs = self._reviewer_records(bundle)
        self.assertEqual(len(recs), 1)
        self.assertFalse(recs[0]["reclaim_allowed"])
        ownership = branch_cleanup_guard.assess_active_branch_ownership(
            remote=REMOTE, org=ORG, repo=REPO, branch=BRANCH, host=HOST,
            records=bundle["records"],
        )
        self.assertTrue(ownership["block"])
    def test_owner_process_alive_keeps_reviewer_lease_protective(self):
        bundle = self._run(owner_pid_alive=True, lease_freshness="expired")
        recs = self._reviewer_records(bundle)
        self.assertFalse(recs[0]["reclaim_allowed"])
    def test_competing_worktree_binding_keeps_reviewer_lease_protective(self):
        bundle = self._run(worktree_on_branch=True)
        recs = self._reviewer_records(bundle)
        self.assertFalse(recs[0]["reclaim_allowed"])
        ownership = branch_cleanup_guard.assess_active_branch_ownership(
            remote=REMOTE, org=ORG, repo=REPO, branch=BRANCH, host=HOST,
            records=bundle["records"],
        )
        self.assertTrue(ownership["block"])
    def test_expired_author_lease_never_reclaimed_by_reviewer_policy(self):
        bundle = self._run(lease_role="author")
        author_recs = [
            rec
            for rec in bundle["records"]
            if rec.get("category")
            == branch_cleanup_guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE
        ]
        self.assertEqual(len(author_recs), 1)
        self.assertFalse(author_recs[0]["reclaim_allowed"])
 if __name__ == "__main__":
    unittest.main()
@@ -1,551 +0,0 @@
 """Merged-PR awareness for the worktree cleanup audit (#858).
 Before #858 an ``issue_work`` worktree could never leave ``active_issue_work``:
 the audit had no PR linkage at all (``pr_number`` was structurally ``None``)
 and its only route to ``clean_stale_removable`` was a TTL derived from a
 ``last_used_at`` that nothing ever populated. A merged, clean, unprotected
 worktree was therefore reported as active work forever, disagreeing with the
 PR-scoped reconciler.
 These tests use fabricated temporary repositories and synthetic PR records
 only. Nothing here removes a worktree or deletes a branch.
 """
 import os
 import subprocess
 import sys
 import tempfile
 import unittest
 from unittest.mock import patch
 sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
 import merged_cleanup_reconcile as mcr  # noqa: E402
 import worktree_cleanup_audit as wca  # noqa: E402
 MERGED_BRANCH = "feat/issue-777-timeline"
 MERGED_PATH = "/repo/branches/issue-777-timeline"
 HEAD_SHA = "a" * 40
 def _pr(number, branch, *, merged=True, sha=HEAD_SHA, state=None):
    """Synthetic Gitea PR payload."""
    return {
        "number": number,
        "head": {"ref": branch, "sha": sha},
        "merged_at": "2026-07-24T01:00:00Z" if merged else None,
        "state": state or ("closed" if merged else "open"),
    }
 def _porcelain(*entries):
    out = []
    for path, branch, sha in entries:
        out.append(f"worktree {path}")
        out.append(f"HEAD {sha}")
        if branch is None:
            out.append("detached")
        else:
            out.append(f"branch refs/heads/{branch}")
        out.append("")
    return "\n".join(out)
 class _AuditHarness(unittest.TestCase):
    """Runs audit_branches_directory over a fabricated worktree listing."""
    PORCELAIN = _porcelain(
        ("/repo", "master", "f" * 40),
        (MERGED_PATH, MERGED_BRANCH, HEAD_SHA),
    )
    def run_audit(self, *, dirty_paths=(), contained=True, **kwargs):
        def fake_dirty(path):
            if path in dirty_paths:
                return {"exists": True, "dirty": True, "dirty_files": [" M x.py"]}
            return {"exists": True, "dirty": False, "dirty_files": []}
        with patch.object(
            wca, "list_worktrees",
            return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
        ), patch.object(
            wca, "read_worktree_dirty", side_effect=fake_dirty
        ), patch.object(
            wca, "git_worktree_list", return_value="(mocked)"
        ), patch.object(
            wca, "is_head_ancestor_of_ref", return_value=contained
        ):
            report = wca.audit_branches_directory("/repo", **kwargs)
        return {wt["path"]: wt for wt in report["worktrees"]}, report
    def merged_audit(self, **kwargs):
        kwargs.setdefault("pr_index", wca.build_pr_index([_pr(849, MERGED_BRANCH)]))
        kwargs.setdefault("master_ref", "prgs/master")
        return self.run_audit(**kwargs)
 class TestMergedWorktreeBecomesRemovable(_AuditHarness):
    def test_clean_merged_issue_worktree_is_linked_and_removable(self):
        by_path, report = self.merged_audit()
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE)
        self.assertTrue(entry["removable"])
        self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_MERGED)
        self.assertEqual(entry["merged_pr_cleanup"]["block_reasons"], [])
        self.assertIn(MERGED_PATH, [c["path"] for c in report["removable_candidates"]])
    def test_pr_number_populated_from_authoritative_linkage(self):
        by_path, _ = self.merged_audit()
        self.assertEqual(by_path[MERGED_PATH]["pr_number"], 849)
    def test_regression_without_pr_evidence_stays_active_issue_work(self):
        """The pre-#858 behaviour, still correct when no PR state is supplied."""
        by_path, _ = self.run_audit()
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
        self.assertIsNone(entry["pr_number"])
 class TestProtectiveSignalsSurvive(_AuditHarness):
    def test_open_pr_worktree_is_not_removable(self):
        index = wca.build_pr_index([_pr(900, MERGED_BRANCH, merged=False)])
        by_path, _ = self.run_audit(
            pr_index=index,
            master_ref="prgs/master",
            open_pr_branches={MERGED_BRANCH},
        )
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_OPEN_PR)
        self.assertFalse(entry["removable"])
        # linkage still reports the owning PR, it just is not merge proof
        self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_OPEN)
        self.assertEqual(entry["pr_number"], 900)
    def test_dirty_tracked_worktree_is_not_removable(self):
        by_path, _ = self.merged_audit(dirty_paths=(MERGED_PATH,))
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL)
        self.assertFalse(entry["removable"])
        self.assertIn(
            "worktree has uncommitted changes",
            entry["merged_pr_cleanup"]["block_reasons"],
        )
    def test_untracked_only_worktree_is_not_removable(self):
        """``git status --porcelain`` reports untracked files as dirty too."""
        def untracked(path):
            if path == MERGED_PATH:
                return {"exists": True, "dirty": True, "dirty_files": ["?? scratch.txt"]}
            return {"exists": True, "dirty": False, "dirty_files": []}
        with patch.object(
            wca, "list_worktrees",
            return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
        ), patch.object(
            wca, "read_worktree_dirty", side_effect=untracked
        ), patch.object(
            wca, "git_worktree_list", return_value="(mocked)"
        ), patch.object(
            wca, "is_head_ancestor_of_ref", return_value=True
        ):
            report = wca.audit_branches_directory(
                "/repo",
                pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
                master_ref="prgs/master",
            )
        entry = {wt["path"]: wt for wt in report["worktrees"]}[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL)
        self.assertFalse(entry["removable"])
    def test_active_lease_by_issue_number_is_protective(self):
        by_path, _ = self.merged_audit(leased_issue_numbers={777})
        entry = by_path[MERGED_PATH]
        self.assertTrue(entry["has_active_lease"])
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
    def test_active_lease_by_branch_is_protective(self):
        by_path, _ = self.merged_audit(leased_branches={MERGED_BRANCH})
        entry = by_path[MERGED_PATH]
        self.assertTrue(entry["has_active_lease"])
        self.assertFalse(entry["removable"])
    def test_active_issue_lock_is_protective(self):
        by_path, _ = self.merged_audit(active_issue_branches={MERGED_BRANCH})
        entry = by_path[MERGED_PATH]
        self.assertTrue(entry["has_active_issue_lock"])
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
    def test_live_session_worktree_is_protective(self):
        by_path, _ = self.merged_audit(live_session_paths={MERGED_PATH})
        entry = by_path[MERGED_PATH]
        self.assertTrue(entry["has_live_session"])
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
    def test_head_not_contained_in_master_is_not_removable(self):
        by_path, _ = self.merged_audit(contained=False)
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
        self.assertIn(
            "worktree head is not contained in authoritative master "
            "(unmerged commits remain)",
            entry["merged_pr_cleanup"]["block_reasons"],
        )
    def test_unknown_containment_fails_closed(self):
        by_path, _ = self.merged_audit(contained=None)
        entry = by_path[MERGED_PATH]
        self.assertFalse(entry["removable"])
        self.assertIn(
            "containment of the worktree head in master is unknown",
            entry["merged_pr_cleanup"]["block_reasons"],
        )
    def test_missing_master_ref_fails_closed(self):
        by_path, _ = self.run_audit(
            pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)])
        )
        self.assertFalse(by_path[MERGED_PATH]["removable"])
    def test_unmerged_owning_pr_is_not_removable(self):
        index = wca.build_pr_index([_pr(901, MERGED_BRANCH, merged=False)])
        by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
        entry = by_path[MERGED_PATH]
        self.assertFalse(entry["removable"])
        self.assertIn(
            "owning PR #901 is not merged",
            entry["merged_pr_cleanup"]["block_reasons"],
        )
    def test_control_checkout_is_never_removable(self):
        by_path, _ = self.merged_audit()
        control = by_path["/repo"]
        self.assertTrue(control["is_protected"])
        self.assertEqual(control["classification"], wca.CLASS_UNSAFE_UNKNOWN)
        self.assertFalse(control["removable"])
    def test_control_checkout_not_removable_even_if_linked_and_merged(self):
        """A merged PR on the control checkout must not unlock removal."""
        porcelain = _porcelain(("/repo", MERGED_BRANCH, HEAD_SHA))
        with patch.object(
            wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain)
        ), patch.object(
            wca, "read_worktree_dirty",
            return_value={"exists": True, "dirty": False, "dirty_files": []},
        ), patch.object(
            wca, "git_worktree_list", return_value="(mocked)"
        ), patch.object(
            wca, "is_head_ancestor_of_ref", return_value=True
        ):
            report = wca.audit_branches_directory(
                "/repo",
                pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
                master_ref="prgs/master",
            )
        entry = report["worktrees"][0]
        self.assertEqual(entry["classification"], wca.CLASS_UNSAFE_UNKNOWN)
        self.assertFalse(entry["removable"])
 class TestAmbiguousLinkageFailsClosed(_AuditHarness):
    def test_competing_prs_on_one_branch_fail_closed(self):
        index = wca.build_pr_index(
            [_pr(849, MERGED_BRANCH), _pr(860, MERGED_BRANCH)]
        )
        by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS)
        self.assertIsNone(entry["pr_number"])
        self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(entry["removable"])
    def test_merged_plus_open_pr_on_one_branch_fails_closed(self):
        index = wca.build_pr_index(
            [_pr(849, MERGED_BRANCH), _pr(861, MERGED_BRANCH, merged=False)]
        )
        by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS)
        self.assertFalse(entry["removable"])
    def test_no_owning_pr_fails_closed(self):
        by_path, _ = self.run_audit(
            pr_index=wca.build_pr_index([_pr(849, "feat/other-branch")]),
            master_ref="prgs/master",
        )
        entry = by_path[MERGED_PATH]
        self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_NONE)
        self.assertFalse(entry["removable"])
    def test_malformed_pr_records_are_dropped_not_guessed(self):
        index = wca.build_pr_index(
            [
                {"number": None, "head": {"ref": MERGED_BRANCH}},
                {"number": 5, "head": {}},
                {"number": "not-an-int", "head": {"ref": MERGED_BRANCH}},
            ]
        )
        self.assertEqual(index, {})
        self.assertEqual(
            wca.resolve_owning_pr(branch=MERGED_BRANCH, pr_index=index)["status"],
            wca.LINKAGE_NONE,
        )
    def test_detached_worktree_has_no_branch_linkage(self):
        self.assertEqual(
            wca.resolve_owning_pr(branch=None, pr_index={})["status"],
            wca.LINKAGE_UNKNOWN,
        )
 class TestUnrelatedClassificationsUnchanged(unittest.TestCase):
    """Non-issue_work worktrees keep their pre-#858 classifications."""
    PORCELAIN = _porcelain(
        ("/repo", "master", "f" * 40),
        ("/repo/branches/review-pr42", "review-pr42", "2" * 40),
        ("/repo/branches/baseline-master-x", "baseline-master-x", "3" * 40),
        ("/repo/branches/conflict-fix-pr50", "conflict-fix-pr50", "4" * 40),
        ("/repo/branches/review-pr99", None, "5" * 40),
    )
    def _audit(self, **kwargs):
        with patch.object(
            wca, "list_worktrees",
            return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
        ), patch.object(
            wca, "read_worktree_dirty",
            return_value={"exists": True, "dirty": False, "dirty_files": []},
        ), patch.object(
            wca, "git_worktree_list", return_value="(mocked)"
        ), patch.object(
            wca, "is_head_ancestor_of_ref", return_value=True
        ):
            report = wca.audit_branches_directory("/repo", **kwargs)
        return {wt["path"]: wt for wt in report["worktrees"]}
    def test_classifications_identical_with_and_without_pr_evidence(self):
        without = self._audit()
        with_evidence = self._audit(
            pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
            master_ref="prgs/master",
        )
        self.assertEqual(
            {p: e["classification"] for p, e in without.items()},
            {p: e["classification"] for p, e in with_evidence.items()},
        )
    def test_lease_on_issue_does_not_capture_similarly_named_scratch_trees(self):
        """A lease on issue 777 protects issue work, not baseline/review trees."""
        porcelain = _porcelain(
            ("/repo/branches/baseline-master-issue-777", "baseline-issue-777", "7" * 40),
            ("/repo/branches/issue-777-timeline", MERGED_BRANCH, HEAD_SHA),
        )
        with patch.object(
            wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain)
        ), patch.object(
            wca, "read_worktree_dirty",
            return_value={"exists": True, "dirty": False, "dirty_files": []},
        ), patch.object(
            wca, "git_worktree_list", return_value="(mocked)"
        ), patch.object(
            wca, "is_head_ancestor_of_ref", return_value=True
        ):
            report = wca.audit_branches_directory(
                "/repo",
                pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
                master_ref="prgs/master",
                leased_issue_numbers={777},
            )
        by_path = {wt["path"]: wt for wt in report["worktrees"]}
        baseline = by_path["/repo/branches/baseline-master-issue-777"]
        self.assertFalse(baseline["has_active_lease"])
        self.assertEqual(baseline["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE)
        issue_work = by_path["/repo/branches/issue-777-timeline"]
        self.assertTrue(issue_work["has_active_lease"])
        self.assertFalse(issue_work["removable"])
    def test_review_and_baseline_still_removable(self):
        by_path = self._audit(
            pr_index=wca.build_pr_index([]), master_ref="prgs/master"
        )
        self.assertEqual(
            by_path["/repo/branches/review-pr42"]["classification"],
            wca.CLASS_CLEAN_STALE_REMOVABLE,
        )
        self.assertEqual(
            by_path["/repo/branches/baseline-master-x"]["classification"],
            wca.CLASS_CLEAN_STALE_REMOVABLE,
        )
        self.assertEqual(
            by_path["/repo/branches/review-pr99"]["classification"],
            wca.CLASS_DETACHED_REVIEW_LEFTOVER,
        )
    def test_conflict_fix_ttl_behaviour_unchanged(self):
        """conflict_fix still needs only TTL expiry; #858 did not touch it."""
        self.assertEqual(
            wca.classify_worktree(
                workflow_type=wca.WORKFLOW_CONFLICT_FIX,
                is_dirty=False,
                ttl_expired=True,
            ),
            wca.CLASS_CLEAN_STALE_REMOVABLE,
        )
        self.assertEqual(
            wca.classify_worktree(
                workflow_type=wca.WORKFLOW_CONFLICT_FIX,
                is_dirty=False,
                ttl_expired=False,
            ),
            wca.CLASS_ACTIVE_ISSUE_WORK,
        )
    def test_issue_work_ttl_alone_no_longer_grants_removal(self):
        """Age is not landing proof: TTL alone must not reclaim issue work."""
        self.assertEqual(
            wca.classify_worktree(
                workflow_type=wca.WORKFLOW_ISSUE_WORK,
                is_dirty=False,
                ttl_expired=True,
            ),
            wca.CLASS_ACTIVE_ISSUE_WORK,
        )
 class TestAssessorPerformsNoDeletion(_AuditHarness):
    def test_audit_never_removes_a_worktree(self):
        with patch.object(wca, "remove_worktree") as removal:
            self.merged_audit()
        removal.assert_not_called()
    def test_audit_shells_out_to_no_destructive_git_command(self):
        seen = []
        real_run = subprocess.run
        def recording_run(cmd, *args, **kwargs):
            seen.append(cmd)
            return real_run(["true"], *args, **kwargs)
        with patch.object(subprocess, "run", side_effect=recording_run):
            wca.audit_branches_directory("/nonexistent-repo-for-audit")
        joined = [" ".join(c) if isinstance(c, list) else str(c) for c in seen]
        for cmd in joined:
            self.assertNotIn("worktree remove", cmd)
            self.assertNotIn("branch -D", cmd)
            self.assertNotIn("push", cmd)
 class TestAgreementWithPrScopedReconciler(unittest.TestCase):
    """The audit and merged_cleanup_reconcile must agree on identical input.
    Uses a real throwaway git repository so containment is computed by git
    rather than asserted. Nothing outside the temporary directory is touched.
    """
    def _git(self, *args):
        subprocess.run(
            ["git", "-C", self.root, *args],
            check=True,
            capture_output=True,
            text=True,
        )
    def setUp(self):
        self._tmp = tempfile.TemporaryDirectory()
        self.root = os.path.realpath(self._tmp.name)
        self._git("init", "-b", "master", ".")
        self._git("config", "user.email", "[email protected]")
        self._git("config", "user.name", "Test")
        with open(os.path.join(self.root, "seed.txt"), "w") as fh:
            fh.write("seed\n")
        self._git("add", "seed.txt")
        self._git("commit", "-m", "seed")
        self.branch = "feat/issue-777-timeline"
        self._git("checkout", "-b", self.branch)
        with open(os.path.join(self.root, "feature.txt"), "w") as fh:
            fh.write("feature\n")
        self._git("add", "feature.txt")
        self._git("commit", "-m", "feature")
        self.head_sha = subprocess.run(
            ["git", "-C", self.root, "rev-parse", "HEAD"],
            capture_output=True, text=True, check=True,
        ).stdout.strip()
        self._git("checkout", "master")
        self._git("merge", "--no-ff", "-m", "merge feature", self.branch)
        self.worktree = os.path.join(self.root, "branches", "issue-777-timeline")
        self._git("worktree", "add", self.worktree, self.branch)
    def tearDown(self):
        self._tmp.cleanup()
    def _pr_index(self):
        return wca.build_pr_index(
            [
                {
                    "number": 849,
                    "head": {"ref": self.branch, "sha": self.head_sha},
                    "merged_at": "2026-07-24T01:00:00Z",
                }
            ]
        )
    def _audit_entry(self):
        report = wca.audit_branches_directory(
            self.root, pr_index=self._pr_index(), master_ref="master"
        )
        return next(wt for wt in report["worktrees"] if wt["path"] == self.worktree)
    def _reconciler_entry(self):
        return mcr.assess_local_worktree_cleanup(
            pr_number=849,
            head_branch=self.branch,
            merged=True,
            worktree_state=mcr.resolve_cleanup_worktree_state(
                project_root=self.root,
                head_branch=self.branch,
                issue_number=777,
                pr_head_sha=self.head_sha,
                target_ref="master",
            ),
            active_lock=False,
        )
    def test_both_assessors_agree_the_worktree_is_safe(self):
        audit_entry = self._audit_entry()
        reconciler = self._reconciler_entry()
        self.assertTrue(reconciler["safe_to_remove_worktree"], reconciler)
        self.assertTrue(audit_entry["removable"], audit_entry)
        self.assertEqual(audit_entry["pr_number"], reconciler["pr_number"])
        self.assertEqual(audit_entry["merged_pr_cleanup"]["block_reasons"], [])
        self.assertEqual(reconciler["block_reasons"], [])
    def test_both_assessors_agree_a_dirty_worktree_is_unsafe(self):
        with open(os.path.join(self.worktree, "feature.txt"), "a") as fh:
            fh.write("local edit\n")
        audit_entry = self._audit_entry()
        reconciler = self._reconciler_entry()
        self.assertFalse(audit_entry["removable"])
        self.assertFalse(reconciler["safe_to_remove_worktree"])
    def test_worktree_still_present_after_audit(self):
        self._audit_entry()
        self.assertTrue(os.path.isdir(self.worktree))
 if __name__ == "__main__":
    unittest.main()
@@ -1,630 +0,0 @@
 """Durable linked-issue lock head refresh + merge-sync dead-session recovery (#871).
 ``gitea_update_pr_branch_by_merge`` advances a PR's *remote* head but historically
 never advanced the linked durable issue lock's recorded head. After the owning
 session died the drifted lock became unrecoverable and no further synchronization
 was possible (PR #866 / issue #855).
 Two halves are covered:
 * the write-side refresh (``issue_lock_store.assess/apply_durable_lock_head_refresh``)
  that records the new synced head under compare-and-swap with read-after-write; and
 * the read-side recovery relation (``issue_lock_recovery`` +
  ``issue_lock_worktree.read_merge_sync_provenance``) that lets a dead-session lock
  whose recorded head is a merge-sync *ancestor* of the live PR head be recovered —
  and nothing else.
 """
 from __future__ import annotations
 import os
 import subprocess
 import sys
 import tempfile
 import unittest
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 import issue_lock_recovery  # noqa: E402
 import issue_lock_store  # noqa: E402
 import issue_lock_worktree  # noqa: E402
 ISSUE = 8710
 PR_NUMBER = 8711
 BRANCH = f"fix/issue-{ISSUE}-durable-lock-head-refresh"
 IDENTITY = "example-user"
 PROFILE = "example-author"
 OLD = "a" * 40
 NEW1 = "b" * 40
 NEW2 = "c" * 40
 BASE = "d" * 40
 REMOTE = "prgs"
 ORG = "ExampleOrg"
 REPO = "ExampleRepo"
 def dead_pid() -> int:
    proc = subprocess.Popen([sys.executable, "-c", "pass"])
    proc.wait()
    return proc.pid
 def future_ts(hours: int = 4) -> str:
    return (
        (datetime.now(timezone.utc) + timedelta(hours=hours))
        .isoformat()
        .replace("+00:00", "Z")
    )
 def _git(cwd, *args):
    return subprocess.run(
        ["git", "-C", cwd, *args],
        capture_output=True,
        text=True,
        check=True,
    )
 def _rev(cwd, ref="HEAD") -> str:
    return _git(cwd, "rev-parse", ref).stdout.strip()
 def build_merge_sync_repo(tmp: str) -> dict:
    """Build a repo where a feature branch was synced by merging master in.
    Returns a dict with the prior (branch) head, the synced merge-commit head,
    the master tip, plus a rebase-style linear descendant and an unrelated head.
    """
    _git(tmp, "init", "-q", "-b", "master")
    _git(tmp, "config", "user.email", "[email protected]")
    _git(tmp, "config", "user.name", "T")
    Path(tmp, "base.txt").write_text("base\n")
    _git(tmp, "add", "-A")
    _git(tmp, "commit", "-q", "-m", "root")
    # Feature branch cut from root, one commit — this is the PRIOR/recorded head.
    _git(tmp, "checkout", "-q", "-b", BRANCH)
    Path(tmp, "feature.txt").write_text("feature\n")
    _git(tmp, "add", "-A")
    _git(tmp, "commit", "-q", "-m", "feature work")
    prior = _rev(tmp)
    # Master advances (the base the sync will merge in).
    _git(tmp, "checkout", "-q", "master")
    Path(tmp, "base.txt").write_text("base\nmore\n")
    _git(tmp, "add", "-A")
    _git(tmp, "commit", "-q", "-m", "master advance")
    master_tip = _rev(tmp)
    # Sync: merge master INTO the feature branch → merge commit, first parent = prior.
    _git(tmp, "checkout", "-q", BRANCH)
    _git(tmp, "merge", "-q", "--no-ff", "-m", "Merge master into feature", "master")
    synced = _rev(tmp)
    # A plain linear descendant of prior (NOT a merge) — a rebase/extra-commit shape.
    _git(tmp, "checkout", "-q", "-b", "linear-branch", prior)
    Path(tmp, "extra.txt").write_text("extra\n")
    _git(tmp, "add", "-A")
    _git(tmp, "commit", "-q", "-m", "extra linear commit")
    linear = _rev(tmp)
    # An unrelated root (force-push / rewritten history shape).
    unrelated_dir = tempfile.mkdtemp()
    _git(unrelated_dir, "init", "-q", "-b", "x")
    _git(unrelated_dir, "config", "user.email", "[email protected]")
    _git(unrelated_dir, "config", "user.name", "T")
    Path(unrelated_dir, "z.txt").write_text("z\n")
    _git(unrelated_dir, "add", "-A")
    _git(unrelated_dir, "commit", "-q", "-m", "unrelated")
    unrelated = _rev(unrelated_dir)
    # Leave the worktree checked out on the feature branch at the PRIOR head, as
    # a dead author session that never advanced would have left it.
    _git(tmp, "checkout", "-q", BRANCH)
    _git(tmp, "reset", "-q", "--hard", prior)
    return {
        "prior": prior,
        "master_tip": master_tip,
        "synced": synced,
        "linear": linear,
        "unrelated": unrelated,
    }
 # ─────────────────────────── write-side refresh ───────────────────────────
 class TestDurableLockHeadRefresh(unittest.TestCase):
    def setUp(self):
        self.lock_dir = tempfile.mkdtemp()
        self.wt = tempfile.mkdtemp()
        lock_data = {
            "issue_number": ISSUE,
            "branch_name": BRANCH,
            "worktree_path": self.wt,
            "remote": REMOTE,
            "org": ORG,
            "repo": REPO,
            "claimant": {"username": IDENTITY, "profile": PROFILE},
            "work_lease": {
                "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
                "issue_number": ISSUE,
                "branch": BRANCH,
                "worktree_path": self.wt,
                "claimant": {"username": IDENTITY, "profile": PROFILE},
                "expires_at": future_ts(),
            },
        }
        issue_lock_store.bind_session_lock(lock_data, lock_dir=self.lock_dir)
    def _apply(self, **over):
        kw = dict(
            remote=REMOTE, org=ORG, repo=REPO, issue_number=ISSUE,
            branch_name=BRANCH, worktree_path=self.wt, pr_number=PR_NUMBER,
            identity=IDENTITY, profile=PROFILE, current_pid=os.getpid(),
            expected_old_head=OLD, new_head=NEW1, synced_at=future_ts(0),
            base_head=BASE, lock_dir=self.lock_dir,
        )
        kw.update(over)
        return issue_lock_store.apply_durable_lock_head_refresh(**kw)
    def _load(self):
        return issue_lock_store.load_issue_lock(
            remote=REMOTE, org=ORG, repo=REPO, issue_number=ISSUE,
            lock_dir=self.lock_dir,
        )
    def test_first_sync_updates_recorded_head(self):
        """AC1: first base sync writes the resulting head to the durable lock."""
        res = self._apply()
        self.assertTrue(res["refreshed"], res["reasons"])
        self.assertTrue(res["read_after_write_ok"])
        self.assertEqual(self._load().get("synced_pr_head"), NEW1)
    def test_second_sync_after_master_advance(self):
        """AC2: a later master advance permits a second sanctioned sync."""
        self.assertTrue(self._apply()["refreshed"])
        res2 = self._apply(expected_old_head=NEW1, new_head=NEW2)
        self.assertTrue(res2["refreshed"], res2["reasons"])
        self.assertEqual(self._load().get("synced_pr_head"), NEW2)
        history = self._load().get("branch_sync_history")
        self.assertEqual(len(history), 2)
        self.assertEqual(history[0]["last_synced_pr_head"], NEW1)
        self.assertEqual(history[1]["prior_pr_head"], NEW1)
    def test_cas_detects_concurrent_head_change(self):
        """AC6: CAS refuses when the recorded synced head is not the old head."""
        self.assertTrue(self._apply()["refreshed"])  # recorded head now NEW1
        # A second sync claiming the old head is still OLD must fail closed.
        res = self._apply(expected_old_head=OLD, new_head=NEW2)
        self.assertFalse(res["refreshed"])
        self.assertTrue(any("CAS" in r or "concurrent" in r for r in res["reasons"]))
        self.assertEqual(self._load().get("synced_pr_head"), NEW1)
    def test_wrong_issue_fails_closed(self):
        res = self._apply(issue_number=999999)
        self.assertFalse(res["refreshed"])
    def test_wrong_branch_fails_closed(self):
        res = self._apply(branch_name="fix/issue-8710-wrong")
        self.assertFalse(res["refreshed"])
    def test_wrong_repo_fails_closed(self):
        res = self._apply(repo="OtherRepo")
        self.assertFalse(res["refreshed"])
    def test_wrong_identity_fails_closed(self):
        res = self._apply(identity="intruder")
        self.assertFalse(res["refreshed"])
    def test_wrong_profile_fails_closed(self):
        res = self._apply(profile="prgs-reviewer")
        self.assertFalse(res["refreshed"])
    def test_foreign_session_fails_closed(self):
        """A refresh is not a recovery: the current process must own the lock."""
        path = issue_lock_store.lock_file_path(
            remote=REMOTE, org=ORG, repo=REPO, issue_number=ISSUE,
            lock_dir=self.lock_dir,
        )
        rec = issue_lock_store.read_lock_file(path)
        rec["session_pid"] = dead_pid()
        rec["pid"] = rec["session_pid"]
        issue_lock_store.save_lock_file(path, rec)
        res = self._apply()
        self.assertFalse(res["refreshed"])
        self.assertTrue(any("current session" in r or "live owner" in r for r in res["reasons"]))
    def test_new_equals_old_fails_closed(self):
        res = self._apply(expected_old_head=OLD, new_head=OLD)
        self.assertFalse(res["refreshed"])
    def test_non_full_sha_fails_closed(self):
        self.assertFalse(self._apply(new_head="deadbeef")["refreshed"])
        self.assertFalse(self._apply(expected_old_head="xyz")["refreshed"])
    def test_no_lock_fails_closed(self):
        assessment = issue_lock_store.assess_durable_lock_head_refresh(
            None, remote=REMOTE, org=ORG, repo=REPO, issue_number=ISSUE,
            branch_name=BRANCH, worktree_path=self.wt, pr_number=PR_NUMBER,
            identity=IDENTITY, profile=PROFILE, current_pid=os.getpid(),
            expected_old_head=OLD, new_head=NEW1,
        )
        self.assertFalse(assessment["allowed"])
 # ─────────────────────── merge-sync provenance (real git) ───────────────────
 class TestMergeSyncProvenanceObservation(unittest.TestCase):
    def setUp(self):
        self.tmp = tempfile.mkdtemp()
        self.shas = build_merge_sync_repo(self.tmp)
    def test_merge_sync_is_recognized(self):
        obs = issue_lock_worktree.read_merge_sync_provenance(
            self.tmp, prior_head_sha=self.shas["prior"],
            synced_head_sha=self.shas["synced"],
        )
        self.assertTrue(obs["is_merge_sync"], obs["reasons"])
        self.assertTrue(obs["prior_is_ancestor"])
        self.assertTrue(obs["synced_is_merge"])
        self.assertTrue(obs["first_parent_reaches_prior"])
    def test_linear_descendant_is_not_a_merge_sync(self):
        """A plain non-merge descendant (rebase/extra commit) is not a sync."""
        obs = issue_lock_worktree.read_merge_sync_provenance(
            self.tmp, prior_head_sha=self.shas["prior"],
            synced_head_sha=self.shas["linear"],
        )
        self.assertTrue(obs["probe_ok"])
        self.assertFalse(obs["is_merge_sync"])
        self.assertFalse(obs["synced_is_merge"])
    def test_unrelated_history_fails_closed(self):
        """A rewritten/force-pushed head where prior is unreachable fails closed."""
        obs = issue_lock_worktree.read_merge_sync_provenance(
            self.tmp, prior_head_sha=self.shas["prior"],
            synced_head_sha=self.shas["unrelated"],
        )
        self.assertFalse(obs["is_merge_sync"])
    def test_missing_args_fail_closed(self):
        obs = issue_lock_worktree.read_merge_sync_provenance(
            self.tmp, prior_head_sha=None, synced_head_sha=self.shas["synced"],
        )
        self.assertFalse(obs["is_merge_sync"])
 # ──────────────────── merge-sync dead-session recovery ──────────────────────
 def make_dead_lock(worktree, **over):
    pid = dead_pid()
    lock = {
        "issue_number": ISSUE,
        "branch_name": BRANCH,
        "worktree_path": worktree,
        "remote": REMOTE,
        "org": ORG,
        "repo": REPO,
        "session_pid": pid,
        "pid": pid,
        "claimant": {"username": IDENTITY, "profile": PROFILE},
        "work_lease": {
            "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
            "issue_number": ISSUE,
            "branch": BRANCH,
            "worktree_path": worktree,
            "claimant": {"username": IDENTITY, "profile": PROFILE},
            "expires_at": future_ts(),
        },
    }
    lock.update(over)
    return lock
 def sync_prov(prior, synced, **over):
    d = {
        "prior_head_sha": prior,
        "synced_head_sha": synced,
        "probe_ok": True,
        "prior_present": True,
        "synced_present": True,
        "prior_is_ancestor": True,
        "synced_is_merge": True,
        "first_parent_reaches_prior": True,
        "is_merge_sync": True,
        "first_parent_sha": prior,
        "parent_count": 2,
        "proof": f"{synced} merged base into branch above {prior}",
        "reasons": [],
    }
    d.update(over)
    return d
 class TestMergeSyncRecovery(unittest.TestCase):
    def setUp(self):
        self.tmp = tempfile.mkdtemp()
        self.shas = build_merge_sync_repo(self.tmp)
        self.prior = self.shas["prior"]
        self.synced = self.shas["synced"]
    def _assess(self, **over):
        lock = over.pop("_lock", None) or make_dead_lock(self.tmp)
        kw = dict(
            issue_number=ISSUE, branch_name=BRANCH, worktree_path=self.tmp,
            remote=REMOTE, org=ORG, repo=REPO, identity=IDENTITY, profile=PROFILE,
            current_branch=BRANCH, porcelain_status="",
            head_sha=self.prior, remote_head_sha=self.synced,
            pr_head_sha=self.synced, pr_number=PR_NUMBER,
            competing_live_locks=[], candidate_branches=[BRANCH],
            current_pid=os.getpid(),
            remote_branch_exists=True,
            sync_provenance=sync_prov(self.prior, self.synced),
        )
        kw.update(over)
        return issue_lock_recovery.assess_dead_session_lock_recovery(lock, **kw)
    def test_merge_sync_drift_is_recoverable(self):
        """AC3/AC4: dead session, recorded head is a merge-sync ancestor of PR head."""
        res = self._assess()
        self.assertEqual(res["outcome"], issue_lock_recovery.RECOVERY_SANCTIONED, res["reasons"])
        self.assertEqual(
            res["evidence"]["head_relation"],
            issue_lock_recovery.HEAD_RELATION_REMOTE_MERGE_SYNCED,
        )
        self.assertEqual(res["evidence"]["accepted_head"], self.synced)
    def test_missing_provenance_fails_closed(self):
        """No server-derived provenance → cannot accept a remote ahead of local."""
        res = self._assess(sync_provenance=None)
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_non_ancestor_recorded_head_fails_closed(self):
        """AC7: provenance that does not prove ancestry is rejected."""
        res = self._assess(
            sync_provenance=sync_prov(
                self.prior, self.synced, prior_is_ancestor=False, is_merge_sync=False,
                reasons=["prior head is not an ancestor"],
            )
        )
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_force_pushed_history_fails_closed(self):
        """AC8: a rewritten head (not a merge sync) stays protected."""
        res = self._assess(
            sync_provenance=sync_prov(
                self.prior, self.synced, is_merge_sync=False, synced_is_merge=False,
                reasons=["not a merge-based sync"],
            )
        )
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_provenance_for_other_commits_fails_closed(self):
        """Provenance whose endpoints differ from the heads under assessment is rejected."""
        res = self._assess(
            sync_provenance=sync_prov("f" * 40, self.synced),
        )
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_dirty_worktree_fails_closed(self):
        """AC11: dirty worktrees remain protected."""
        res = self._assess(porcelain_status=" M feature.txt\n")
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_live_owner_fails_closed(self):
        """AC10: a live recorded owner is not a dead-session recovery."""
        lock = make_dead_lock(self.tmp, session_pid=os.getpid(), pid=os.getpid())
        res = self._assess(_lock=lock)
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_competing_claimant_fails_closed(self):
        """AC13: a competing live lock blocks recovery."""
        res = self._assess(
            competing_live_locks=[{
                "issue_number": ISSUE, "branch_name": BRANCH,
                "worktree_path": "/some/other/wt", "pid": os.getpid(),
            }]
        )
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_wrong_branch_fails_closed(self):
        """AC9: worktree on a different branch fails closed."""
        res = self._assess(current_branch="fix/issue-8710-other")
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_wrong_identity_fails_closed(self):
        res = self._assess(identity="intruder")
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_pr_head_mismatch_fails_closed(self):
        """The open PR must sit at the synced remote head."""
        res = self._assess(pr_head_sha="e" * 40)
        self.assertEqual(res["outcome"], issue_lock_recovery.REFUSED)
    def test_owning_pr_evidence_for_merge_sync(self):
        res = self._assess()
        ev = issue_lock_recovery.owning_pr_recovery_evidence(res)
        self.assertIsNotNone(ev)
        self.assertEqual(ev["pr_number"], PR_NUMBER)
        self.assertEqual(ev["head_sha"], self.synced)
        self.assertEqual(
            ev["head_relation"],
            issue_lock_recovery.HEAD_RELATION_REMOTE_MERGE_SYNCED,
        )
    def test_recovered_owning_pr_from_persisted_record(self):
        res = self._assess()
        record = issue_lock_recovery.build_recovery_record(res, recovered_at=future_ts(0))
        lock = {"issue_number": ISSUE, "branch_name": BRANCH,
                "dead_session_recovery": record}
        rebuilt = issue_lock_recovery.recovered_owning_pr_from_lock(lock)
        self.assertIsNotNone(rebuilt)
        self.assertEqual(rebuilt["head_sha"], self.synced)
        self.assertEqual(
            rebuilt["head_relation"],
            issue_lock_recovery.HEAD_RELATION_REMOTE_MERGE_SYNCED,
        )
 class TestExistingRelationsUnchanged(unittest.TestCase):
    """AC14/AC15: equal-head recovery still works; merge-sync did not weaken it."""
    def setUp(self):
        self.tmp = tempfile.mkdtemp()
        self.shas = build_merge_sync_repo(self.tmp)
    def test_equal_head_recovery_still_sanctioned(self):
        # Worktree at prior head; remote also at prior head → the #753 equal case.
        prior = self.shas["prior"]
        lock = make_dead_lock(self.tmp)
        res = issue_lock_recovery.assess_dead_session_lock_recovery(
            lock, issue_number=ISSUE, branch_name=BRANCH, worktree_path=self.tmp,
            remote=REMOTE, org=ORG, repo=REPO, identity=IDENTITY, profile=PROFILE,
            current_branch=BRANCH, porcelain_status="",
            head_sha=prior, remote_head_sha=prior,
            pr_head_sha=prior, pr_number=PR_NUMBER,
            competing_live_locks=[], candidate_branches=[BRANCH],
            current_pid=os.getpid(), remote_branch_exists=True,
        )
        self.assertEqual(res["outcome"], issue_lock_recovery.RECOVERY_SANCTIONED, res["reasons"])
        self.assertEqual(
            res["evidence"]["head_relation"], issue_lock_recovery.HEAD_RELATION_EQUAL,
        )
 class TestUpdatePrWrapperPartialFailure(unittest.TestCase):
    """AC5/AC16: the tool advances the remote head then refreshes the durable lock.
    When the durable refresh fails after the remote advance, the tool must report a
    partial lifecycle failure and NOT a fully successful synchronization. Exact PR-
    head / base-head pinning is preserved (delegated to the real preflight, stubbed
    here only to isolate the post-update lifecycle branch).
    """
    def setUp(self):
        import gitea_mcp_server as gms  # noqa: E402
        self.gms = gms
        self._orig = {}
        def _patch(name, value):
            self._orig[name] = getattr(gms, name)
            setattr(gms, name, value)
        _patch("get_profile", lambda *a, **k: {
            "allowed_operations": ["gitea.branch.push"],
            "forbidden_operations": [],
            "profile_name": "prgs-author",
        })
        _patch("_role_kind", lambda *a, **k: "author")
        _patch("_profile_operation_gate", lambda *a, **k: None)
        _patch("_permission_block_report", lambda *a, **k: {})
        _patch("_resolve", lambda *a, **k: ("gitea.prgs.cc", ORG, REPO))
        _patch("_verify_role_mutation_workspace", lambda *a, **k: None)
        _patch("_get_workspace_porcelain", lambda *a, **k: "")
        _patch("_canonical_local_git_root", lambda *a, **k: "/x")
        _patch("_master_parity_block", lambda *a, **k: None)
        _patch("_auth", lambda *a, **k: {"token": "x"})
        _patch("repo_api_url", lambda *a, **k: "http://api")
        _patch("_redact", lambda s: s)
        _patch("_work_lease_claimant", lambda *a, **k: {
            "username": IDENTITY, "profile": PROFILE,
        })
        _patch("_prove_author_ownership_for_pr", lambda *a, **k: {
            "has_author_lock": True, "matched_issue": ISSUE,
            "matched_via": "branch", "linked_issues": [ISSUE],
            "recovered_owning_pr": None, "reasons": [],
        })
        # Real preflight is unit-tested elsewhere; stub it to isolate the
        # post-update durable-lock lifecycle branch under test.
        orig_pf = gms.pr_sync_status.assess_update_pr_branch_preflight
        self._orig_pf = orig_pf
        gms.pr_sync_status.assess_update_pr_branch_preflight = (
            lambda *a, **k: {"mutation_allowed": True, "reasons": [], "performed": False}
        )
        # Sequence the two GET /pulls calls: OLD before update, NEW after.
        self._pull_calls = {"n": 0}
        def fake_api_request(method, url, auth, *a, **k):
            m = method.upper()
            if m == "GET" and url.endswith(f"/pulls/{PR_NUMBER}"):
                self._pull_calls["n"] += 1
                head = OLD if self._pull_calls["n"] == 1 else NEW1
                return {
                    "state": "open",
                    "head": {"sha": head, "ref": BRANCH},
                    "base": {"sha": BASE, "ref": "master"},
                    "mergeable": True, "title": "t", "body": "b",
                }
            if m == "GET" and "/branches/" in url:
                return {"commit": {"id": BASE}}
            if m == "POST" and "/update" in url:
                return {}
            return {}
        _patch("api_request", fake_api_request)
    def tearDown(self):
        for name, value in self._orig.items():
            setattr(self.gms, name, value)
        self.gms.pr_sync_status.assess_update_pr_branch_preflight = self._orig_pf
    def _run(self):
        return self.gms.gitea_update_pr_branch_by_merge(
            pr_number=PR_NUMBER,
            expected_pr_head_sha=OLD,
            expected_base_head_sha=BASE,
            remote=REMOTE,
            worktree_path="/tmp/branches/wt-871",
        )
    def test_partial_failure_when_refresh_fails(self):
        self._orig["apply_durable_lock_head_refresh"] = (
            self.gms.issue_lock_store.apply_durable_lock_head_refresh
        )
        self.gms.issue_lock_store.apply_durable_lock_head_refresh = (
            lambda **k: {"refreshed": False, "reasons": ["forced refresh failure"]}
        )
        try:
            res = self._run()
        finally:
            self.gms.issue_lock_store.apply_durable_lock_head_refresh = (
                self._orig["apply_durable_lock_head_refresh"]
            )
        self.assertTrue(res["performed"])
        self.assertEqual(res["new_pr_head_sha"], NEW1)
        self.assertFalse(res["success"])
        self.assertTrue(res["partial_lifecycle_failure"])
        self.assertFalse(res["durable_lock_refreshed"])
    def test_full_success_when_refresh_succeeds(self):
        self._orig["apply_durable_lock_head_refresh"] = (
            self.gms.issue_lock_store.apply_durable_lock_head_refresh
        )
        self.gms.issue_lock_store.apply_durable_lock_head_refresh = (
            lambda **k: {"refreshed": True, "read_after_write_ok": True,
                         "new_head": NEW1, "reasons": ["ok"]}
        )
        try:
            res = self._run()
        finally:
            self.gms.issue_lock_store.apply_durable_lock_head_refresh = (
                self._orig["apply_durable_lock_head_refresh"]
            )
        self.assertTrue(res["success"])
        self.assertTrue(res["performed"])
        self.assertTrue(res["durable_lock_refreshed"])
        self.assertTrue(res["fully_synchronized"])
        self.assertEqual(res["new_pr_head_sha"], NEW1)
 if __name__ == "__main__":
    unittest.main()
@@ -24,8 +24,6 @@ def _lease(expires_at: str) -> dict:
 def _lock_record(**overrides) -> dict:
    # #860: live locks require a usable session pid; PID-less records are never
    # classified live merely because expiry/heartbeat fields are present.
    record = {
        "issue_number": 420,
        "branch_name": "feat/issue-420-server-code-parity",
@@ -33,8 +31,6 @@ def _lock_record(**overrides) -> dict:
        "org": "Scaled-Tech-Consulting",
        "repo": "Gitea-Tools",
        "worktree_path": "/tmp/wt-420",
        "session_pid": os.getpid(),
        "pid": os.getpid(),
        "work_lease": _lease("2999-01-01T00:00:00Z"),
    }
    record.update(overrides)
@@ -92,8 +88,6 @@ class TestIssueLockStore(unittest.TestCase):
        existing = _lock_record(
            branch_name="feat/issue-420-other",
            worktree_path="/tmp/other",
            session_pid=os.getpid(),
            pid=os.getpid(),
            work_lease=_lease("2999-01-01T00:00:00Z"),
        )
        path = ils.lock_file_path(
@@ -1,107 +0,0 @@
 """Documentation acceptance for the MCP restart governance ADR (#656).
 Enforces issue #656 acceptance criteria:
 * AC1 — policy document exists with an authorization matrix and the recorded
  v1 decision (controller approval + automated safety gates).
 * AC2 — restart is stated as a last resort with enumerated narrower recoveries.
 * AC3 — a unilateral LLM full restart with affected sessions is forbidden.
 * AC4 — break-glass conditions are listed.
 * AC5 — the ADR is linked to #655, #652, #653, #630, #642, and is cross-linked
  from the safety model and the web-console deployment boundary docs.
 """
 from pathlib import Path
 REPO_ROOT = Path(__file__).resolve().parent.parent
 ADR = REPO_ROOT / "docs" / "architecture" / "mcp-restart-governance.md"
 ADR_BASENAME = "mcp-restart-governance.md"
 CROSS_LINK_DOCS = (
    REPO_ROOT / "docs" / "safety-model.md",
    REPO_ROOT / "docs" / "webui-deployment.md",
 )
 LINKED_ISSUES = ("#655", "#652", "#653", "#630", "#642")
 POLICY_IDS = ("RG-01", "RG-02", "RG-03", "RG-04", "RG-05", "RG-06", "RG-07", "RG-08")
 def _read(path: Path) -> str:
    assert path.is_file(), f"missing {path.relative_to(REPO_ROOT)}"
    return path.read_text(encoding="utf-8")
 def test_ac1_adr_exists_with_matrix_and_v1_decision():
    text = _read(ADR)
    lower = text.lower()
    assert text.lstrip().startswith("#"), "ADR lacks a title"
    assert "#656" in text
    assert "authorization matrix" in lower
    # The matrix is a real table with the worker and privileged roles.
    for role in ("author", "reviewer", "merger", "reconciler", "controller",
                 "operator", "admin"):
        assert role in lower, f"authorization matrix missing role {role!r}"
    # Recorded v1 decision.
    assert "restart-governance/v1" in text
    assert "controller approval" in lower and "automated safety gates" in lower
 def test_ac2_restart_is_last_resort_with_narrower_recoveries():
    text = _read(ADR)
    lower = text.lower()
    assert "last resort" in lower
    # Enumerated narrower recoveries precede full restart on the ladder.
    for rung in ("reconnect", "rebind", "scoped restart", "full restart",
                 "host"):
        assert rung in lower, f"recovery ladder missing rung {rung!r}"
 def test_ac3_forbids_unilateral_llm_full_restart_with_affected_sessions():
    text = _read(ADR)
    lower = text.lower()
    assert "forbidden" in lower
    assert "llm" in lower and "restart" in lower
    assert "unilateral" in lower
    # A worker role must not perform or authorize full/host restart.
    assert "must not" in lower
 def test_ac4_break_glass_conditions_listed():
    text = _read(ADR)
    lower = text.lower()
    assert "break-glass" in lower
    assert "incident" in lower
    assert "audit" in lower
 def test_ac5_adr_links_issue_lineage():
    text = _read(ADR)
    for issue in LINKED_ISSUES:
        assert issue in text, f"ADR must link issue {issue}"
 def test_ac5_safety_model_and_deployment_cross_link_adr():
    for path in CROSS_LINK_DOCS:
        text = _read(path)
        assert ADR_BASENAME in text, (
            f"{path.relative_to(REPO_ROOT)} must cross-link {ADR_BASENAME} "
            f"(issue #656 acceptance criterion 5)"
        )
 def test_policy_ids_present_for_enforcement_code():
    text = _read(ADR)
    for pid in POLICY_IDS:
        assert pid in text, f"policy id {pid} missing from ADR"
 def test_failure_behavior_denies_on_ambiguity():
    text = _read(ADR)
    lower = text.lower()
    assert "ambiguous" in lower and "deny" in lower
 def test_cross_links_do_not_embed_secrets():
    for path in (ADR,) + CROSS_LINK_DOCS:
        text = _read(path)
        for marker in ("ghp_", "BEGIN PRIVATE KEY", "Authorization: Bearer"):
            assert marker not in text, f"{path} contains {marker!r}"
@@ -1,146 +0,0 @@
 """Tests for the MCP restart-path inventory and guards (#657).
 Covers:
 * the registry is well-formed and every path is classified;
 * unknown restart attempts fail closed (AC "fail closed on unknown restart");
 * the previously-unguarded full-restart primitives stay guarded/absent
  against the real source tree (AC "tests for at least one previously
  unguarded path");
 * pkill of the daemon is still classified as contamination (#630, AC3);
 * the inventory doc and module stay in lock-step.
 """
 import os
 import tempfile
 import unittest
 from pathlib import Path
 import mcp_restart_paths as rp
 import runtime_recovery_guard
 REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
 DOC_PATH = os.path.join(REPO_ROOT, "docs", "mcp-restart-path-inventory.md")
 class TestRegistryWellformed(unittest.TestCase):
    def test_registry_is_wellformed(self):
        # Must not raise.
        rp.assert_registry_wellformed()
    def test_every_path_has_valid_classification(self):
        for path in rp.iter_restart_paths():
            self.assertIn(path.classification, rp.VALID_CLASSIFICATIONS)
            self.assertTrue(path.guard.strip(), path.path_id)
            self.assertTrue(path.references, path.path_id)
            self.assertTrue(path.locations, path.path_id)
    def test_ids_are_unique(self):
        ids = [p.path_id for p in rp.iter_restart_paths()]
        self.assertEqual(len(ids), len(set(ids)))
    def test_covers_every_classification(self):
        present = {p.classification for p in rp.iter_restart_paths()}
        self.assertEqual(present, set(rp.VALID_CLASSIFICATIONS))
 class TestUnknownAttemptFailsClosed(unittest.TestCase):
    def test_unknown_path_raises(self):
        with self.assertRaises(rp.UnknownRestartPathError):
            rp.assert_restart_attempt_registered("totally_novel_restart_hack")
    def test_get_unknown_raises(self):
        with self.assertRaises(rp.UnknownRestartPathError):
            rp.get_restart_path("nope")
    def test_registered_attempt_returns_path(self):
        path = rp.assert_restart_attempt_registered("manual_daemon_kill")
        self.assertEqual(path.classification, rp.CLASS_FORBIDDEN)
 class TestDaemonNeverSelfReplaces(unittest.TestCase):
    """Previously-unguarded full-restart primitive: daemon self-replacement."""
    def test_no_self_replacement_in_source(self):
        # The live daemon modules must contain no os.execv/os.kill/os._exit
        # self-restart call. Must not raise.
        rp.assert_no_daemon_self_replacement(REPO_ROOT)
    def test_scanner_flags_injected_violation(self):
        # Guard the guard: prove the scanner catches a real self-replace call.
        with tempfile.TemporaryDirectory() as tmp:
            bad = Path(tmp) / "gitea_mcp_server.py"
            bad.write_text(
                "import os\n"
                "def restart():\n"
                "    os.execv('/usr/bin/python', ['python'])\n",
                encoding="utf-8",
            )
            found = rp.scan_daemon_self_replacement(tmp)
            self.assertTrue(found)
            with self.assertRaises(AssertionError):
                rp.assert_no_daemon_self_replacement(tmp)
    def test_scanner_ignores_comment_and_docstring_mentions(self):
        with tempfile.TemporaryDirectory() as tmp:
            ok = Path(tmp) / "gitea_mcp_server.py"
            ok.write_text(
                "import os\n"
                "# NOT os.execv() to re-point the interpreter here.\n"
                '"""Never calls os._exit to restart."""\n'
                "value = 1\n",
                encoding="utf-8",
            )
            self.assertEqual(rp.scan_daemon_self_replacement(tmp), [])
 class TestLegacyAutoRestartHelperRemoved(unittest.TestCase):
    """Previously-unguarded full-restart path: _trigger_mcp_auto_restart."""
    def test_helper_absent_in_source(self):
        # Must not raise: helper was removed in #685.
        rp.assert_auto_restart_helper_absent(REPO_ROOT)
    def test_scanner_flags_reintroduced_helper(self):
        with tempfile.TemporaryDirectory() as tmp:
            bad = Path(tmp) / "mcp_server.py"
            bad.write_text(
                "def _trigger_mcp_auto_restart():\n    return True\n",
                encoding="utf-8",
            )
            with self.assertRaises(AssertionError):
                rp.assert_auto_restart_helper_absent(tmp)
 class TestPkillStaysForbidden(unittest.TestCase):
    """AC3: pkill of the daemon remains forbidden/contaminating (#630)."""
    def test_manual_daemon_kill_registered_as_forbidden(self):
        path = rp.get_restart_path("manual_daemon_kill")
        self.assertEqual(path.classification, rp.CLASS_FORBIDDEN)
    def test_pkill_classified_as_contamination(self):
        assessment = runtime_recovery_guard.assess_recovery_command(
            "pkill -f mcp_server.py"
        )
        self.assertTrue(assessment["contaminated"])
    def test_read_only_probe_not_contamination(self):
        assessment = runtime_recovery_guard.assess_recovery_command(
            "ps aux | grep mcp_server"
        )
        self.assertFalse(assessment["contaminated"])
 class TestInventoryDocInSync(unittest.TestCase):
    def test_doc_exists(self):
        self.assertTrue(os.path.exists(DOC_PATH), DOC_PATH)
    def test_doc_mentions_every_path_id(self):
        with open(DOC_PATH, encoding="utf-8") as handle:
            doc = handle.read()
        for path in rp.iter_restart_paths():
            self.assertIn(path.path_id, doc, f"doc missing {path.path_id}")
 if __name__ == "__main__":
    unittest.main()
@@ -12,59 +12,6 @@ import merged_cleanup_reconcile as mcr  # noqa: E402
 class TestMergedCleanupAssessment(unittest.TestCase):
    def test_issue_851_plan_order_worktree_then_reassess_then_remote(self):
        """#851 dry-run plan: remove worktree, reassess ownership, then remote."""
        plan = mcr.plan_cleanup_execution_order(
            remote_assessment={"safe_to_delete_remote": True},
            local_assessment={"safe_to_remove_worktree": True},
        )
        actions = [s["action"] for s in plan]
        self.assertEqual(
            actions,
            [
                "remove_local_worktree",
                "reassess_branch_ownership",
                "delete_remote_branch",
            ],
        )
        self.assertEqual(plan[0]["phase"], 1)
        self.assertEqual(plan[-1]["phase"], 3)
        self.assertIn("independently_safe", plan[0]["reason"])
        self.assertIn("reassessment", plan[-1]["reason"])
    def test_issue_851_plan_remote_only_when_worktree_not_safe(self):
        plan = mcr.plan_cleanup_execution_order(
            remote_assessment={"safe_to_delete_remote": True},
            local_assessment={"safe_to_remove_worktree": False},
        )
        self.assertEqual([s["action"] for s in plan], ["delete_remote_branch"])
        self.assertNotIn("reassess_branch_ownership", [s["action"] for s in plan])
    def test_issue_851_plan_worktree_only_when_remote_not_safe(self):
        plan = mcr.plan_cleanup_execution_order(
            remote_assessment={"safe_to_delete_remote": False},
            local_assessment={"safe_to_remove_worktree": True},
        )
        self.assertEqual([s["action"] for s in plan], ["remove_local_worktree"])
    def test_issue_851_entry_includes_planned_execution_order(self):
        entry = mcr.build_pr_cleanup_entry(
            pr={
                "number": 848,
                "title": "Closes #844",
                "body": "",
                "merged_at": "2026-07-23T00:00:00Z",
                "head": {"ref": "fix/issue-844-x", "sha": "a" * 40},
            },
            project_root="/tmp/not-a-real-root",
            open_pr_heads=set(),
            remote_branch_exists=True,
            head_on_master=True,
            delete_capability_allowed=True,
        )
        self.assertIn("planned_execution_order", entry)
        self.assertIsInstance(entry["planned_execution_order"], list)
    def test_extract_linked_issue_from_closes(self):
        issue = mcr.extract_linked_issue(
            "feat: cleanup (Closes #269)",
@@ -37,7 +37,6 @@ def _live_lock(
        "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
        "acquired_at": now.isoformat(),
        "expires_at": (now + timedelta(hours=2)).isoformat(),
        "session_pid": os.getpid(),
        "owner_pid": os.getpid(),
        "status": "active",
    }
@@ -178,24 +177,11 @@ class TestAuthorOwnershipIssuePrMismatch(unittest.TestCase):
        self.assertFalse(result["proven"], result)
        self.assertTrue(any("branch" in r for r in result["reasons"]))
-    def test_pidless_durable_lock_rejected(self):
+    def test_no_lock_fail_closed(self):
        """A lock without any PID identity must be classified as malformed/non-live and fail closed."""
        lock = _live_lock(issue_number=727)
        lock.pop("session_pid", None)
        lock.pop("owner_pid", None)
        lock.pop("pid", None)
        path = issue_lock_store.lock_file_path(
            remote="prgs",
            org="Scaled-Tech-Consulting",
            repo="Gitea-Tools",
            issue_number=727,
            lock_dir=self.lock_dir,
        )
        issue_lock_store.save_lock_file(path, lock)
        result = mcp._prove_author_ownership_for_pr(
            pr_number=728,
            pr_title="feat: pr sync",
-            pr_body="Fixes #727",
+            pr_body="Closes #727",
            source_branch="feat/issue-727-pr-sync-status",
            remote="prgs",
            host=None,
@@ -1,340 +0,0 @@
 """Tests for the MCP restart coordinator and impact analysis (#658).
 Multi-session fixtures exercise every verdict branch: safe, unsafe (live work),
 override, and the fail-closed deny on incomplete inventory. Also covers the
 critical-section deny path and the new ``ControlPlaneDB.list_sessions``.
 """
 from __future__ import annotations
 import os
 import tempfile
 import unittest
 from datetime import datetime, timedelta, timezone
 import restart_coordinator as rc
 from control_plane_db import ControlPlaneDB
 NOW = datetime(2026, 7, 24, 6, 0, 0, tzinfo=timezone.utc)
 def _ts(dt: datetime) -> str:
    return dt.isoformat()
 def _live_pid() -> int:
    return os.getpid()
 def _dead_pid() -> int:
    # A pid that is essentially never alive. os.kill(0) on it raises
    # ProcessLookupError → is_process_alive False.
    return 2_000_000_000
 def _session(session_id, *, pid, status="active", heartbeat=None, role="author"):
    return {
        "session_id": session_id,
        "role": role,
        "profile": "prgs-author",
        "pid": pid,
        "status": status,
        "last_heartbeat_at": _ts(heartbeat or NOW),
    }
 def _lease(
    lease_id,
    *,
    session_id,
    freshness,
    kind="issue",
    number=658,
    phase="allocated",
    worktree=None,
    role="author",
 ):
    return {
        "lease_id": lease_id,
        "session_id": session_id,
        "role": role,
        "phase": phase,
        "work_kind": kind,
        "work_number": number,
        "worktree_path": worktree,
        "freshness": {"freshness": freshness},
    }
 class EvaluateRestartImpactTest(unittest.TestCase):
    def test_incomplete_inventory_denies_fail_closed(self) -> None:
        report = rc.evaluate_restart_impact(
            {"inventory_complete": False, "incomplete_reasons": ["db down"]},
            now=NOW,
        )
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertFalse(report.allow_restart)
        self.assertFalse(report.restart_performed)
        self.assertIn("db down", report.incomplete_reasons)
        self.assertTrue(
            any("fail closed" in reasoning for reasoning in report.reasons)
        )
    def test_missing_completeness_flag_denies(self) -> None:
        # No inventory_complete key at all → treated as incomplete.
        report = rc.evaluate_restart_impact({}, now=NOW)
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertFalse(report.allow_restart)
    def test_no_other_work_is_safe(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("requester", pid=_live_pid())],
                "leases": [],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_SAFE)
        self.assertTrue(report.allow_restart)
        self.assertEqual(report.blast_radius, rc.BLAST_NONE)
        self.assertEqual(report.affected_issues, [])
    def test_dead_foreign_session_and_lease_are_not_disruptive(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [
                    _session("requester", pid=_live_pid()),
                    _session("dead", pid=_dead_pid()),
                ],
                "leases": [
                    _lease("l-dead", session_id="dead", freshness="stale_dead_process")
                ],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_SAFE)
        self.assertTrue(report.allow_restart)
        self.assertEqual(report.counts["leases_disruptive"], 0)
        self.assertEqual(report.counts["sessions_live_other"], 0)
    def test_live_foreign_lease_denies_without_override(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [
                    _session("requester", pid=_live_pid()),
                    _session("worker", pid=_live_pid()),
                ],
                "leases": [
                    _lease(
                        "l1",
                        session_id="worker",
                        freshness="active",
                        worktree="/tmp/wt-658",
                        phase="implementing",
                    )
                ],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertFalse(report.allow_restart)
        # Critical section detected: active lease with a live owner.
        self.assertEqual(len(report.critical_sections), 1)
        self.assertEqual(report.affected_issues, [658])
        self.assertEqual(report.counts["mutations"], 1)
        self.assertTrue(report.override_would_allow)
        self.assertEqual(report.blast_radius, rc.BLAST_HIGH)
        # Placeholder ack state for the affected session.
        self.assertEqual(report.ack_state.get("worker"), "pending")
    def test_operator_override_allows_despite_live_work(self) -> None:
        inv = {
            "inventory_complete": True,
            "sessions": [
                _session("requester", pid=_live_pid()),
                _session("worker", pid=_live_pid()),
            ],
            "leases": [_lease("l1", session_id="worker", freshness="active")],
        }
        report = rc.evaluate_restart_impact(
            inv,
            now=NOW,
            requesting_session_id="requester",
            operator_override=True,
        )
        self.assertEqual(report.verdict, rc.VERDICT_OVERRIDE)
        self.assertTrue(report.allow_restart)
        self.assertFalse(report.restart_performed)
    def test_deny_when_critical_section_open(self) -> None:
        # A single live author lease in a mutating phase is a critical section
        # that must deny an un-overridden restart.
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("worker", pid=_live_pid())],
                "leases": [
                    _lease(
                        "l1",
                        session_id="worker",
                        freshness="active",
                        phase="merging",
                        kind="pr",
                        number=900,
                    )
                ],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertFalse(report.allow_restart)
        self.assertEqual(report.affected_prs, [900])
        self.assertEqual(len(report.critical_sections), 1)
    def test_terminal_lock_makes_restart_unsafe(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("requester", pid=_live_pid())],
                "leases": [],
                "terminal_lock": {"terminal_pr": 812},
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertFalse(report.allow_restart)
        self.assertIsNotNone(report.terminal_lock)
        self.assertTrue(
            any("terminal" in reasoning for reasoning in report.reasons)
        )
    def test_other_live_session_without_lease_is_disruptive(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [
                    _session("requester", pid=_live_pid()),
                    _session("idle-but-live", pid=_live_pid()),
                ],
                "leases": [],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_UNSAFE)
        self.assertEqual(report.counts["sessions_live_other"], 1)
    def test_stale_heartbeat_session_not_counted_live(self) -> None:
        stale = NOW - timedelta(hours=2)
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [
                    _session("requester", pid=_live_pid()),
                    _session("stale", pid=_live_pid(), heartbeat=stale),
                ],
                "leases": [],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.verdict, rc.VERDICT_SAFE)
        self.assertEqual(report.counts["sessions_live_other"], 0)
    def test_prior_recovery_attempts_echoed(self) -> None:
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("requester", pid=_live_pid())],
                "leases": [],
                "prior_recovery_attempts": [
                    {"kind": "client_reconnect", "at": _ts(NOW)}
                ],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(len(report.prior_recovery_attempts), 1)
        self.assertEqual(report.counts["prior_recovery_attempts"], 1)
    def test_bare_string_freshness_accepted(self) -> None:
        lease = _lease("l1", session_id="worker", freshness="active")
        lease["freshness"] = "active"  # bare string, not a dict
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("worker", pid=_live_pid())],
                "leases": [lease],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.counts["leases_disruptive"], 1)
    def test_as_dict_is_serializable_dto(self) -> None:
        import json
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": [_session("requester", pid=_live_pid())],
                "leases": [],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        payload = report.as_dict()
        # Round-trips through JSON — safe for the console DTO.
        encoded = json.dumps(payload)
        decoded = json.loads(encoded)
        self.assertEqual(decoded["verdict"], rc.VERDICT_SAFE)
        self.assertIn("audit_record", decoded)
        self.assertEqual(decoded["audit_record"]["event"], "restart_impact_evaluated")
        self.assertFalse(decoded["restart_performed"])
        self.assertIn("coordinator_version", decoded)
 class ListSessionsTest(unittest.TestCase):
    def setUp(self) -> None:
        self._tmp = tempfile.TemporaryDirectory()
        self.db = ControlPlaneDB(os.path.join(self._tmp.name, "cp.sqlite3"))
    def tearDown(self) -> None:
        self._tmp.cleanup()
    def test_list_sessions_filters_by_status(self) -> None:
        self.db.upsert_session(session_id="a", role="author", pid=1, status="active")
        self.db.upsert_session(session_id="b", role="author", pid=2, status="ended")
        active = self.db.list_sessions(statuses=("active",))
        ids = {row["session_id"] for row in active}
        self.assertEqual(ids, {"a"})
        every = self.db.list_sessions()
        self.assertEqual({row["session_id"] for row in every}, {"a", "b"})
    def test_list_sessions_feeds_coordinator(self) -> None:
        self.db.upsert_session(
            session_id="requester", role="author", pid=os.getpid(), status="active"
        )
        report = rc.evaluate_restart_impact(
            {
                "inventory_complete": True,
                "sessions": self.db.list_sessions(statuses=("active",)),
                "leases": [],
            },
            now=NOW,
            requesting_session_id="requester",
        )
        self.assertEqual(report.counts["sessions_total"], 1)
 if __name__ == "__main__":  # pragma: no cover
    unittest.main()
@@ -1,502 +0,0 @@
 """Sanctioned restart / graceful reload control tests (#642).
 Acceptance criteria under test:
 1. The sanctioned restart path is implemented behind gates (capability,
   confirmation, operator authorization, host hook).
 2. Manual ``pkill`` stays forbidden and is classified as contamination.
 3. Post-restart mutations require clean health/session proof.
 4. Authorized restart preview, unauthorized deny, contamination classification.
 5. No entry point exposes a raw kill.
 """
 import json
 import os
 import tempfile
 import unittest
 import mcp_namespace_health
 import runtime_recovery_guard
 from task_capability_map import TASK_CAPABILITY_MAP
 from webui import console_audit, console_authz, gated_actions, sanctioned_restart
 NAMESPACE = "gitea-author"
 # An operator-authorized, hook-configured host. Passed explicitly so no test
 # depends on (or mutates) the real process environment.
 READY_ENV = {
    sanctioned_restart.RESTART_HOOK_ENV: "launchd:cc.prgs.gitea-author",
    runtime_recovery_guard.OPERATOR_AUTHORIZATION_ENV: "ops-ticket-4821",
 }
 def admin(subject: str = "[email protected]") -> console_authz.Principal:
    return console_authz.Principal(
        subject=subject,
        role=console_authz.ADMIN,
        identity_source=console_authz.IDENTITY_ACCESS_PROXY,
        authenticated=True,
    )
 def viewer() -> console_authz.Principal:
    return console_authz.Principal(
        subject="[email protected]",
        role=console_authz.VIEWER,
        identity_source=console_authz.IDENTITY_ACCESS_PROXY,
        authenticated=True,
    )
 class TestCapabilityWiring(unittest.TestCase):
    """AC1: authority is declared, not invented by the console."""
    def test_actions_resolve_through_the_capability_map(self):
        for action_id in (
            sanctioned_restart.ACTION_RESTART_NAMESPACE,
            sanctioned_restart.ACTION_RELOAD_NAMESPACE,
        ):
            with self.subTest(action=action_id):
                action = console_authz.get_action(action_id)
                self.assertIsNotNone(action)
                self.assertIn(action.task_key, TASK_CAPABILITY_MAP)
                self.assertEqual(
                    action.mcp_permission,
                    TASK_CAPABILITY_MAP[action.task_key]["permission"],
                )
    def test_restart_permission_is_not_a_gitea_operation(self):
        """No configured Gitea profile should satisfy a host restart."""
        permission = TASK_CAPABILITY_MAP["restart_namespace"]["permission"]
        self.assertFalse(permission.startswith("gitea."))
    def test_restart_is_destructive_dual_control_break_glass(self):
        action = console_authz.get_action(
            sanctioned_restart.ACTION_RESTART_NAMESPACE
        )
        self.assertEqual(action.action_class, console_authz.CLASS_DESTRUCTIVE)
        self.assertEqual(action.minimum_role, console_authz.ADMIN)
        self.assertTrue(action.dual_control)
        self.assertTrue(action.break_glass)
        self.assertTrue(action.requires_confirmation)
    def test_reload_is_privileged_but_not_destructive(self):
        action = console_authz.get_action(
            sanctioned_restart.ACTION_RELOAD_NAMESPACE
        )
        self.assertEqual(action.action_class, console_authz.CLASS_PRIVILEGED)
        self.assertTrue(action.requires_confirmation)
 class TestPreview(unittest.TestCase):
    """AC4: an authorized preview renders the plan without executing it."""
    def test_preview_lists_the_mutation_ledger(self):
        preview = sanctioned_restart.build_restart_preview(
            NAMESPACE, principal=admin(), env=READY_ENV
        )
        steps = [entry["step"] for entry in preview["mutation_ledger"]]
        self.assertEqual(
            steps, ["quiesce", "host_restart_hook", "health_recheck", "audit"]
        )
        self.assertTrue(preview["scope_valid"])
        self.assertTrue(preview["post_restart_verification_required"])
    def test_reload_preview_drains_instead_of_restarting(self):
        preview = sanctioned_restart.build_restart_preview(
            NAMESPACE, sanctioned_restart.MODE_RELOAD,
            principal=admin(), env=READY_ENV,
        )
        steps = [entry["step"] for entry in preview["mutation_ledger"]]
        self.assertIn("host_graceful_reload", steps)
        self.assertNotIn("host_restart_hook", steps)
    def test_preview_never_enables_execution(self):
        preview = sanctioned_restart.build_restart_preview(
            NAMESPACE, principal=admin(), env=READY_ENV
        )
        self.assertFalse(preview["execution_enabled"])
        self.assertFalse(preview["authorization"]["execution_enabled"])
    def test_confirmation_phrase_binds_the_namespace(self):
        self.assertTrue(
            sanctioned_restart.confirmation_matches(
                NAMESPACE, sanctioned_restart.MODE_RESTART,
                "restart gitea-author",
            )
        )
        # A phrase typed for one namespace must not authorize another.
        self.assertFalse(
            sanctioned_restart.confirmation_matches(
                "gitea-merger", sanctioned_restart.MODE_RESTART,
                "restart gitea-author",
            )
        )
 class TestGates(unittest.TestCase):
    """AC1/AC4: every gate denies with a stable reason code."""
    def _assess(self, **kwargs):
        params = {
            "principal": admin(),
            "confirmation": f"restart {NAMESPACE}",
            "env": READY_ENV,
        }
        params.update(kwargs)
        namespace = params.pop("namespace", NAMESPACE)
        mode = params.pop("mode", sanctioned_restart.MODE_RESTART)
        return sanctioned_restart.assess_restart_request(
            namespace, mode, **params
        )
    def test_authorized_confirmed_request_passes_every_gate(self):
        result = self._assess()
        self.assertTrue(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.ALLOW_HOST_ACTION_REQUIRED
        )
    def test_passing_every_gate_is_not_an_execution_grant(self):
        """An allowed request still never lets the console touch the process."""
        result = self._assess()
        self.assertTrue(result["allowed"])
        self.assertFalse(result["execution_enabled"])
        self.assertFalse(result["console_executes"])
    def test_unauthorized_principal_is_denied(self):
        result = self._assess(principal=viewer())
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_UNAUTHORIZED
        )
    def test_anonymous_principal_is_denied(self):
        result = self._assess(principal=None)
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_UNAUTHORIZED
        )
    def test_missing_confirmation_is_denied(self):
        result = self._assess(confirmation=None)
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_CONFIRMATION_MISSING
        )
    def test_confirmation_for_another_namespace_is_denied(self):
        result = self._assess(confirmation="restart gitea-merger")
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_CONFIRMATION_MISMATCH
        )
    def test_missing_operator_authorization_is_denied(self):
        env = {sanctioned_restart.RESTART_HOOK_ENV: "launchd:cc.prgs.author"}
        result = self._assess(env=env)
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"],
            sanctioned_restart.DENY_OPERATOR_AUTHORIZATION,
        )
    def test_missing_host_hook_is_denied_without_kill_fallback(self):
        env = {
            runtime_recovery_guard.OPERATOR_AUTHORIZATION_ENV: "ops-ticket-1",
        }
        result = self._assess(env=env)
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_HOOK_NOT_CONFIGURED
        )
    def test_fleet_scope_is_refused(self):
        for scope in ("all", "*", "fleet"):
            with self.subTest(scope=scope):
                result = self._assess(
                    namespace=scope, confirmation=f"restart {scope}"
                )
                self.assertFalse(result["allowed"])
                self.assertEqual(
                    result["reason_code"], sanctioned_restart.DENY_FLEET_SCOPE
                )
    def test_unknown_namespace_is_refused(self):
        result = self._assess(
            namespace="gitea-nope", confirmation="restart gitea-nope"
        )
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_UNKNOWN_NAMESPACE
        )
    def test_unknown_mode_is_refused(self):
        result = self._assess(mode="obliterate")
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_UNKNOWN_MODE
        )
    def test_live_contamination_marker_blocks_restart(self):
        marker = runtime_recovery_guard.build_contamination_record(
            reason_class=runtime_recovery_guard.REASON_MANUAL_DAEMON_KILL,
            command_redacted="pkill -f mcp_server.py",
        )
        result = self._assess(contamination_marker=marker)
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["reason_code"], sanctioned_restart.DENY_CONTAMINATED_RUNTIME
        )
    def test_reconciler_cleared_marker_no_longer_blocks(self):
        marker = runtime_recovery_guard.build_contamination_record(
            reason_class=runtime_recovery_guard.REASON_MANUAL_DAEMON_KILL,
            command_redacted="pkill -f mcp_server.py",
        )
        marker = dict(marker, cleared_by_reconciler=True)
        result = self._assess(contamination_marker=marker)
        self.assertTrue(result["allowed"])
 class TestExecutionNeverKills(unittest.TestCase):
    """AC5: no path exposes or runs a raw process kill."""
    def test_authorized_execution_defers_to_the_host_supervisor(self):
        result = sanctioned_restart.execute_restart(
            NAMESPACE,
            principal=admin(),
            confirmation=f"restart {NAMESPACE}",
            env=READY_ENV,
        )
        self.assertTrue(result["allowed"])
        self.assertFalse(result["success"])
        self.assertFalse(result["process_kill_executed"])
        self.assertEqual(
            result["outcome"], sanctioned_restart.ALLOW_HOST_ACTION_REQUIRED
        )
    def test_denied_execution_reports_the_refusing_gate(self):
        result = sanctioned_restart.execute_restart(
            NAMESPACE, principal=viewer(), confirmation=f"restart {NAMESPACE}",
            env=READY_ENV,
        )
        self.assertFalse(result["allowed"])
        self.assertEqual(
            result["outcome"], sanctioned_restart.DENY_UNAUTHORIZED
        )
        self.assertFalse(result["process_kill_executed"])
    def test_module_never_spawns_a_process(self):
        path = os.path.join(
            os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
            "webui", "sanctioned_restart.py",
        )
        with open(path, encoding="utf-8") as handle:
            source = handle.read()
        for forbidden in (
            "import subprocess", "import signal", "os.kill", "os.system",
            "popen",
        ):
            with self.subTest(forbidden=forbidden):
                self.assertNotIn(forbidden, source.lower())
    def test_no_surface_returns_a_kill_command(self):
        payloads = [
            sanctioned_restart.build_restart_preview(
                NAMESPACE, principal=admin(), env=READY_ENV
            ),
            sanctioned_restart.restart_policy(),
            sanctioned_restart.execute_restart(
                NAMESPACE, principal=admin(),
                confirmation=f"restart {NAMESPACE}", env=READY_ENV,
            ),
        ]
        for payload in payloads:
            rendered = json.dumps(payload, default=str).lower()
            self.assertNotIn("kill -9", rendered)
            self.assertNotIn("pkill -f", rendered)
    def test_policy_declares_no_raw_kill_and_no_silent_restart(self):
        policy = sanctioned_restart.restart_policy()
        self.assertFalse(policy["raw_kill_exposed"])
        self.assertFalse(policy["console_executes_process_kill"])
        self.assertFalse(policy["fleet_scope_permitted"])
        self.assertFalse(policy["silent_auto_restart_permitted"])
        self.assertTrue(policy["audit_required"])
 class TestContaminationClassification(unittest.TestCase):
    """AC2: manual pkill is contamination, and it blocks clean claims."""
    def test_manual_daemon_pkill_is_contamination(self):
        result = sanctioned_restart.classify_restart_command(
            "pkill -f mcp_server.py"
        )
        self.assertTrue(result["contamination"])
        self.assertFalse(result["clean_claim_allowed"])
        self.assertIsNotNone(result["contamination_marker"])
        self.assertEqual(
            result["sanctioned_alternative"],
            sanctioned_restart.ACTION_RESTART_NAMESPACE,
        )
    def test_broad_process_kill_is_contamination(self):
        result = sanctioned_restart.classify_restart_command("killall -9 Python")
        self.assertTrue(result["contamination"])
        self.assertFalse(result["clean_claim_allowed"])
    def test_marker_names_the_sanctioned_alternative(self):
        result = sanctioned_restart.classify_restart_command(
            "pkill -f mcp_server.py"
        )
        marker = result["contamination_marker"]
        self.assertIn(
            sanctioned_restart.ACTION_RESTART_NAMESPACE, marker["detail"]
        )
    def test_benign_command_is_not_contamination(self):
        result = sanctioned_restart.classify_restart_command("git status")
        self.assertFalse(result["contamination"])
        self.assertTrue(result["clean_claim_allowed"])
    def test_no_command_is_not_contamination(self):
        result = sanctioned_restart.classify_restart_command(None)
        self.assertFalse(result["contamination"])
        self.assertTrue(result["clean_claim_allowed"])
 class TestPostRestartHealth(unittest.TestCase):
    """AC3: a clean post-restart claim needs live client-namespace proof."""
    def test_live_client_probe_clears_the_session(self):
        result = sanctioned_restart.verify_post_restart_health(
            NAMESPACE,
            probe_result={"success": True},
            probe_source=mcp_namespace_health.PROBE_SOURCE_CLIENT,
            registered_tools=["gitea_whoami"],
            required_tool="gitea_whoami",
        )
        self.assertEqual(result["status"], sanctioned_restart.HEALTH_CLEAN)
        self.assertTrue(result["clean_claim_allowed"])
        self.assertTrue(result["mutations_allowed"])
    def test_offline_probe_does_not_clear_the_session(self):
        result = sanctioned_restart.verify_post_restart_health(
            NAMESPACE,
            probe_result={"success": True},
            probe_source=mcp_namespace_health.PROBE_SOURCE_OFFLINE,
            registered_tools=["gitea_whoami"],
            required_tool="gitea_whoami",
        )
        self.assertFalse(result["clean_claim_allowed"])
        self.assertFalse(result["mutations_allowed"])
    def test_failed_probe_is_unhealthy(self):
        result = sanctioned_restart.verify_post_restart_health(
            NAMESPACE,
            probe_result={"success": False, "error": "client is closing: EOF"},
            probe_source=mcp_namespace_health.PROBE_SOURCE_CLIENT,
            registered_tools=["gitea_whoami"],
            required_tool="gitea_whoami",
        )
        self.assertEqual(result["status"], sanctioned_restart.HEALTH_UNHEALTHY)
        self.assertFalse(result["clean_claim_allowed"])
    def test_static_registration_alone_never_clears_the_session(self):
        result = sanctioned_restart.verify_post_restart_health(
            NAMESPACE,
            registered_tools=["gitea_whoami"],
            required_tool="gitea_whoami",
        )
        self.assertFalse(result["clean_claim_allowed"])
 class TestAuditEmission(unittest.TestCase):
    """Every restart attempt is audited with actor, target, and result."""
    def _run(self, principal, sink):
        prior = os.environ.get(console_audit.AUDIT_LOG_ENV)
        os.environ[console_audit.AUDIT_LOG_ENV] = sink
        try:
            return sanctioned_restart.execute_restart(
                NAMESPACE,
                principal=principal,
                confirmation=f"restart {NAMESPACE}",
                env=READY_ENV,
                request_id="req-642",
            )
        finally:
            if prior is None:
                os.environ.pop(console_audit.AUDIT_LOG_ENV, None)
            else:
                os.environ[console_audit.AUDIT_LOG_ENV] = prior
    def test_allowed_attempt_is_written_with_actor_and_target(self):
        with tempfile.TemporaryDirectory() as tmp:
            sink = os.path.join(tmp, "audit.jsonl")
            result = self._run(admin(), sink)
            self.assertTrue(result["audit"]["written"])
            with open(sink, encoding="utf-8") as handle:
                record = json.loads(handle.read().strip())
        self.assertEqual(
            record["action"], sanctioned_restart.ACTION_RESTART_NAMESPACE
        )
        self.assertEqual(record["target"]["namespace"], NAMESPACE)
        self.assertEqual(record["target"]["mode"], "restart")
        self.assertEqual(record["result"], console_audit.RESULT_ALLOWED)
        self.assertEqual(record["actor"]["subject"], "[email protected]")
        self.assertFalse(record["metadata"]["process_kill_executed"])
    def test_denied_attempt_is_audited_too(self):
        with tempfile.TemporaryDirectory() as tmp:
            sink = os.path.join(tmp, "audit.jsonl")
            self._run(viewer(), sink)
            with open(sink, encoding="utf-8") as handle:
                record = json.loads(handle.read().strip())
        self.assertEqual(record["result"], console_audit.RESULT_DENIED)
        self.assertEqual(
            record["reason_code"], sanctioned_restart.DENY_UNAUTHORIZED
        )
    def test_restart_audit_uses_break_glass_retention(self):
        action = console_authz.get_action(
            sanctioned_restart.ACTION_RESTART_NAMESPACE
        )
        self.assertEqual(
            console_audit.retention_class_for(action),
            console_audit.RETENTION_BREAK_GLASS,
        )
 class TestRegistrySurface(unittest.TestCase):
    """AC5: the console surfaces the control, still disabled, with no kill."""
    def test_registry_exposes_both_actions_disabled(self):
        registry = gated_actions.load_action_registry()
        for action_id in (
            sanctioned_restart.ACTION_RESTART_NAMESPACE,
            sanctioned_restart.ACTION_RELOAD_NAMESPACE,
        ):
            with self.subTest(action=action_id):
                action = registry.get(action_id)
                self.assertIsNotNone(action)
                self.assertFalse(action.enabled)
    def test_registry_preview_names_the_namespace_target(self):
        preview = gated_actions.preview_action(
            sanctioned_restart.ACTION_RESTART_NAMESPACE, namespace=NAMESPACE
        )
        target = preview["mutation_ledger"][0]["target"]
        self.assertIn(NAMESPACE, target)
        self.assertFalse(preview["enabled"])
    def test_registry_attempt_fails_closed(self):
        result = gated_actions.attempt_action(
            sanctioned_restart.ACTION_RESTART_NAMESPACE, namespace=NAMESPACE
        )
        self.assertFalse(result["success"])
 if __name__ == "__main__":
    unittest.main()
@@ -1,135 +0,0 @@
 """Tests for the Phase 1 operator console application shell (#638)."""
 import sys
 import unittest
 from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from starlette.routing import Route
 from starlette.testclient import TestClient
 from webui import layout
 from webui.app import create_app
 from webui.nav import NAV_GROUPS, STUB_PAGES, nav_hrefs
 class TestShellNav(unittest.TestCase):
    def setUp(self):
        self.client = TestClient(create_app())
    def test_nav_group_labels_present(self):
        text = self.client.get("/").text
        for group in NAV_GROUPS:
            with self.subTest(group=group.label):
                self.assertIn(f">{group.label}<", text)
    def test_phase1_group_labels_cover_expected_ia(self):
        labels = {group.label for group in NAV_GROUPS}
        for expected in (
            "Health",
            "Traffic",
            "Runtime/Sessions",
            "Projects",
            "Inventory",
            "Timeline",
            "Policy",
            "Insights",
        ):
            with self.subTest(label=expected):
                self.assertIn(expected, labels)
    def test_every_nav_href_resolves_to_a_get_route(self):
        app = create_app()
        get_paths = {
            route.path
            for route in app.routes
            if isinstance(route, Route) and "GET" in route.methods
        }
        for href in nav_hrefs():
            with self.subTest(href=href):
                self.assertIn(href, get_paths, f"nav href {href} has no GET route")
    def test_legacy_hrefs_still_navigable(self):
        text = self.client.get("/").text
        for href in ("/queue", "/projects", "/prompts", "/runtime",
                     "/audit", "/worktrees", "/leases", "/actions"):
            with self.subTest(href=href):
                self.assertIn(f'href="{href}"', text)
 class TestShellBadges(unittest.TestCase):
    def setUp(self):
        self.client = TestClient(create_app())
    def test_mode_badge_present(self):
        self.assertIn("mode: read-only", self.client.get("/").text)
    def test_environment_badge_present(self):
        self.assertIn("env:", self.client.get("/").text)
    def test_default_environment_is_local(self):
        self.assertEqual(layout.environment_label(), "local")
    def test_remote_bind_reports_remote_environment(self):
        import os
        prior = os.environ.get("WEBUI_HOST")
        os.environ["WEBUI_HOST"] = "10.0.0.5"
        try:
            self.assertEqual(layout.environment_label(), "remote")
        finally:
            if prior is None:
                os.environ.pop("WEBUI_HOST", None)
            else:
                os.environ["WEBUI_HOST"] = prior
    def test_docs_link_present(self):
        text = self.client.get("/").text
        self.assertIn(layout.DOCS_URL, text)
        self.assertIn(">Docs<", text)
 class TestShellStubs(unittest.TestCase):
    def setUp(self):
        self.client = TestClient(create_app())
    def test_stub_routes_render_200(self):
        for path, (title, _desc) in STUB_PAGES.items():
            with self.subTest(path=path):
                response = self.client.get(path)
                self.assertEqual(response.status_code, 200, path)
                self.assertIn(title, response.text)
                self.assertIn("placeholder", response.text)
    def test_stub_routes_are_read_only(self):
        for path in STUB_PAGES:
            with self.subTest(path=path):
                response = self.client.post(path)
                self.assertEqual(response.status_code, 405)
                self.assertEqual(response.json()["error"], "read-only-mvp")
    def test_stub_pages_carry_nav_and_badges(self):
        response = self.client.get("/inventory")
        self.assertIn("mode: read-only", response.text)
        self.assertIn('href="/queue"', response.text)
 class TestShellHome(unittest.TestCase):
    def setUp(self):
        self.client = TestClient(create_app())
    def test_home_summarizes_console(self):
        text = self.client.get("/").text
        self.assertIn("Operator console", text)
        self.assertIn("Phase 1", text)
    def test_home_links_legacy_pages(self):
        text = self.client.get("/").text
        self.assertIn("MVP legacy pages", text)
        for href in ("/queue", "/audit", "/leases"):
            with self.subTest(href=href):
                self.assertIn(f'href="{href}"', text)
 if __name__ == "__main__":
    unittest.main()
@@ -1,499 +0,0 @@
 """Tests for the read-only system-health API (#634).
 Covers the acceptance criteria directly: a structured payload with readiness
 and a dependency list (AC1), version and uptime when knowable (AC2), stale
 runtime reported without a false mutation-safe claim (AC3), and the healthy /
 degraded-dependency / redaction cases (AC4).
 """
 import json
 import os
 import sqlite3
 import sys
 import tempfile
 import unittest
 from pathlib import Path
 from unittest import mock
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
 from starlette.testclient import TestClient
 import control_plane_db
 from webui.app import create_app
 from webui.deployment_boundary import scan_text_for_client_secrets
 from webui.system_health import (
    API_PATH,
    STATUS_DEGRADED,
    STATUS_DOWN,
    STATUS_OK,
    STATUS_SKIPPED,
    DependencyProbe,
    StaleRuntime,
    assess_stale_runtime,
    clear_probe_cache,
    load_system_health,
    namespace_summaries,
    probe_control_plane_db,
    probe_gitea,
    process_uptime,
    redact,
    redact_url,
    snapshot_to_dict,
 )
 def _probe(name, status, *, required=True, detail="detail", kind="test"):
    return DependencyProbe(
        name=name,
        kind=kind,
        status=status,
        detail=detail,
        required=required,
        latency_ms=1.5,
        metadata={},
    )
 _ALL_HEALTHY = (
    _probe("control_plane_db", STATUS_OK, kind="sqlite"),
    _probe("repository", STATUS_OK, kind="git"),
    _probe("gitea", STATUS_OK, required=False, kind="http"),
 )
 _CLEAN_PARITY = StaleRuntime(
    daemon_head="abc123",
    checkout_head="abc123",
    remote_head="abc123",
    stale=False,
    determinable=True,
    mutation_safe=True,
    reasons=(),
 )
 class CleanParityMixin:
    """Pin parity for tests about aggregation rather than staleness.
    Without this the assertions depend on the real checkout: a worktree whose
    branch is ahead of its upstream is genuinely stale, which would degrade the
    overall status and make these cases fail for an unrelated reason.
    """
    def setUp(self):
        super().setUp()
        patcher = mock.patch(
            "webui.system_health.assess_stale_runtime",
            return_value=_CLEAN_PARITY,
        )
        patcher.start()
        self.addCleanup(patcher.stop)
 class TestDependencyAggregation(CleanParityMixin, unittest.TestCase):
    """AC1 — readiness and dependency list derived from probe results."""
    def test_all_healthy_is_ok_and_ready(self):
        snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc123")
        self.assertEqual(snapshot.status, STATUS_OK)
        self.assertTrue(snapshot.ready)
        self.assertTrue(snapshot.readiness_complete)
        self.assertEqual(snapshot.readiness_reasons, ())
        self.assertEqual(len(snapshot.dependencies), 3)
    def test_required_dependency_down_blocks_readiness(self):
        probes = (
            _probe("control_plane_db", STATUS_DOWN, detail="file missing", kind="sqlite"),
            _probe("repository", STATUS_OK, kind="git"),
            _probe("gitea", STATUS_OK, required=False, kind="http"),
        )
        snapshot = load_system_health(probes=probes, daemon_head="abc123")
        self.assertEqual(snapshot.status, STATUS_DOWN)
        self.assertFalse(snapshot.ready)
        self.assertTrue(
            any("control_plane_db" in reason for reason in snapshot.readiness_reasons)
        )
    def test_optional_dependency_down_degrades_but_stays_ready(self):
        """A failing optional probe must not claim the process itself is unready."""
        probes = (
            _probe("control_plane_db", STATUS_OK, kind="sqlite"),
            _probe("repository", STATUS_OK, kind="git"),
            _probe("gitea", STATUS_DOWN, required=False, detail="timeout", kind="http"),
        )
        snapshot = load_system_health(probes=probes, daemon_head="abc123")
        self.assertEqual(snapshot.status, STATUS_DEGRADED)
        self.assertTrue(snapshot.ready)
        self.assertTrue(any("gitea" in reason for reason in snapshot.readiness_reasons))
    def test_unrun_required_probe_leaves_readiness_incomplete(self):
        """Not probed is not the same as passing."""
        probes = (
            _probe("control_plane_db", STATUS_OK, kind="sqlite"),
            _probe("repository", STATUS_SKIPPED, detail="offline", kind="git"),
        )
        snapshot = load_system_health(probes=probes, daemon_head="abc123")
        self.assertFalse(snapshot.ready)
        self.assertFalse(snapshot.readiness_complete)
        self.assertEqual(snapshot.status, STATUS_DEGRADED)
    def test_skipped_optional_probe_does_not_block_readiness(self):
        probes = (
            _probe("control_plane_db", STATUS_OK, kind="sqlite"),
            _probe("repository", STATUS_OK, kind="git"),
            _probe("gitea", STATUS_SKIPPED, required=False, kind="http"),
        )
        snapshot = load_system_health(probes=probes, daemon_head="abc123")
        self.assertTrue(snapshot.ready)
        self.assertTrue(snapshot.readiness_complete)
 class TestVersionAndUptime(CleanParityMixin, unittest.TestCase):
    """AC2 — version and uptime present when knowable."""
    def test_uptime_and_start_time_present(self):
        snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc123")
        self.assertGreaterEqual(snapshot.uptime_seconds, 0.0)
        self.assertIn("T", snapshot.started_at)
    def test_process_uptime_helper_matches_shape(self):
        started_at, uptime = process_uptime()
        self.assertIn("T", started_at)
        self.assertGreaterEqual(uptime, 0.0)
    def test_version_reports_python_and_schema_version(self):
        probes = (
            DependencyProbe(
                name="control_plane_db",
                kind="sqlite",
                status=STATUS_OK,
                detail="ok",
                required=True,
                latency_ms=1.0,
                metadata={"schema_version": control_plane_db.SCHEMA_VERSION},
            ),
            _probe("repository", STATUS_OK, kind="git"),
        )
        snapshot = load_system_health(probes=probes, daemon_head="abc123")
        self.assertEqual(
            snapshot.version.control_plane_schema_version,
            control_plane_db.SCHEMA_VERSION,
        )
        self.assertTrue(snapshot.version.python_version)
    def test_version_known_flag_false_when_sha_unavailable(self):
        with mock.patch("webui.system_health._git", return_value=None):
            snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc")
        self.assertIsNone(snapshot.version.git_sha)
        self.assertFalse(snapshot.version.known)
 class TestStaleRuntime(unittest.TestCase):
    """AC3 — stale runtime reflected without a false mutation-safe claim."""
    def test_matching_commits_are_mutation_safe(self):
        assessment = assess_stale_runtime(
            Path("/tmp"),
            daemon_head="aaa",
            git_reader=lambda *args: "aaa",
        )
        self.assertFalse(assessment.stale)
        self.assertTrue(assessment.determinable)
        self.assertTrue(assessment.mutation_safe)
    def test_diverged_commits_are_stale_and_not_mutation_safe(self):
        reads = {"HEAD": "aaa", "@{upstream}": "bbb"}
        assessment = assess_stale_runtime(
            Path("/tmp"),
            daemon_head="aaa",
            git_reader=lambda *args: reads.get(args[-1]),
        )
        self.assertTrue(assessment.stale)
        self.assertFalse(assessment.mutation_safe)
        self.assertTrue(assessment.reasons)
    def test_unknown_remote_is_not_mutation_safe(self):
        """Indeterminate must never read as safe."""
        reads = {"HEAD": "aaa", "@{upstream}": None}
        assessment = assess_stale_runtime(
            Path("/tmp"),
            daemon_head="aaa",
            git_reader=lambda *args: reads.get(args[-1]),
        )
        self.assertFalse(assessment.determinable)
        self.assertFalse(assessment.mutation_safe)
        self.assertFalse(assessment.stale)
        self.assertTrue(
            any("indeterminate" in reason for reason in assessment.reasons)
        )
    def test_unobservable_daemon_head_is_disclosed(self):
        assessment = assess_stale_runtime(
            Path("/tmp"),
            git_reader=lambda *args: "aaa",
        )
        self.assertTrue(
            any("not observable" in reason for reason in assessment.reasons)
        )
    def test_stale_runtime_degrades_overall_status(self):
        reads = {"HEAD": "aaa", "@{upstream}": "bbb"}
        # Pinned rather than inherited: this path uses the default git reader,
        # so the assertion must hold whether or not the suite runs offline.
        with mock.patch.dict(os.environ, {"WEBUI_TEST_OFFLINE": ""}), mock.patch(
            "webui.system_health._git",
            side_effect=lambda repo, *args: reads.get(args[-1]),
        ):
            snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="aaa")
        self.assertTrue(snapshot.stale_runtime.stale)
        self.assertFalse(snapshot.stale_runtime.mutation_safe)
        self.assertEqual(snapshot.status, STATUS_DEGRADED)
 class TestControlPlaneDbProbe(unittest.TestCase):
    """The required local dependency, probed read-only."""
    def setUp(self):
        self.tmp = tempfile.TemporaryDirectory()
        self.addCleanup(self.tmp.cleanup)
        self.db_path = str(Path(self.tmp.name) / "control-plane.db")
    def _build_db(self, schema_version):
        conn = sqlite3.connect(self.db_path)
        conn.execute("CREATE TABLE schema_meta (key TEXT PRIMARY KEY, value TEXT)")
        conn.execute("CREATE TABLE leases (lease_id TEXT PRIMARY KEY, status TEXT)")
        conn.execute(
            "INSERT INTO schema_meta(key, value) VALUES ('schema_version', ?)",
            (str(schema_version),),
        )
        conn.execute("INSERT INTO leases(lease_id, status) VALUES ('l1', 'active')")
        conn.commit()
        conn.close()
    def test_missing_database_is_down(self):
        probe = probe_control_plane_db(str(Path(self.tmp.name) / "absent.db"))
        self.assertEqual(probe.status, STATUS_DOWN)
        self.assertTrue(probe.required)
        self.assertIsNotNone(probe.latency_ms)
    def test_matching_schema_is_ok(self):
        self._build_db(control_plane_db.SCHEMA_VERSION)
        probe = probe_control_plane_db(self.db_path)
        self.assertEqual(probe.status, STATUS_OK)
        self.assertEqual(
            probe.metadata["schema_version"], control_plane_db.SCHEMA_VERSION
        )
        self.assertEqual(probe.metadata["active_leases"], 1)
    def test_mismatched_schema_is_degraded(self):
        self._build_db(control_plane_db.SCHEMA_VERSION + 99)
        probe = probe_control_plane_db(self.db_path)
        self.assertEqual(probe.status, STATUS_DEGRADED)
    def test_probe_does_not_create_a_database(self):
        """A health check must never initialise the substrate it inspects."""
        absent = str(Path(self.tmp.name) / "never-created.db")
        probe_control_plane_db(absent)
        self.assertFalse(Path(absent).exists())
    def test_unreadable_database_is_down_not_raised(self):
        Path(self.db_path).write_text("this is not a sqlite database")
        probe = probe_control_plane_db(self.db_path)
        self.assertEqual(probe.status, STATUS_DOWN)
 class TestRedaction(unittest.TestCase):
    """AC4 — redaction. No credential-shaped text crosses the boundary."""
    def test_redacts_token_assignment(self):
        cleaned = redact("failed with token=ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345")
        self.assertNotIn("ghp_ABCDEFGHIJKLMNOPQRSTUVWXYZ012345", cleaned)
        self.assertIn("[redacted]", cleaned)
    def test_redacts_authorization_header_text(self):
        cleaned = redact("Authorization: Bearer abcdefghijklmnopqrstuvwxyz123456")
        self.assertNotIn("abcdefghijklmnopqrstuvwxyz123456", cleaned)
    def test_redacts_long_opaque_strings(self):
        cleaned = redact("value 0123456789abcdef0123456789abcdef here")
        self.assertNotIn("0123456789abcdef0123456789abcdef", cleaned)
    def test_url_userinfo_and_query_are_stripped(self):
        cleaned = redact_url("https://user:[email protected]/api/v1?token=xyz")
        self.assertNotIn("secretpass", cleaned)
        self.assertNotIn("token=xyz", cleaned)
        self.assertEqual(cleaned, "https://gitea.example.com/api/v1")
    def test_url_inside_free_text_is_redacted(self):
        cleaned = redact("GET https://u:[email protected]/x?token=abc failed")
        self.assertNotIn("u:p@", cleaned)
        self.assertNotIn("token=abc", cleaned)
    def test_gitea_probe_failure_detail_is_redacted(self):
        boom = RuntimeError(
            "connection refused for https://user:[email protected]/api/v1/version"
        )
        with mock.patch("webui.system_health.get_auth_header", return_value="token x"), \
                mock.patch("webui.system_health.api_request", side_effect=boom):
            probe = probe_gitea("gitea.example.com")
        self.assertEqual(probe.status, STATUS_DOWN)
        self.assertNotIn("hunter2", probe.detail)
        self.assertEqual(scan_text_for_client_secrets(probe.detail), [])
    def test_credential_guard_refusal_is_a_status_not_a_crash(self):
        with mock.patch(
            "webui.system_health.get_auth_header",
            side_effect=RuntimeError("daemon guard refused"),
        ):
            probe = probe_gitea("gitea.example.com")
        self.assertEqual(probe.status, STATUS_DEGRADED)
        self.assertFalse(probe.required)
 class TestNamespaceSummaries(unittest.TestCase):
    """A web process cannot prove IDE namespace health, and must not claim to."""
    def test_every_namespace_reports_unproven(self):
        rows = namespace_summaries()
        self.assertTrue(rows)
        for row in rows:
            with self.subTest(namespace=row["namespace"]):
                self.assertEqual(row["status"], "unproven")
                self.assertFalse(row["ide_namespace_proven"])
                self.assertIn("client_namespace", row["reason"])
 class TestSystemHealthRoutes(CleanParityMixin, unittest.TestCase):
    """The HTTP surface: versioned path, status codes, read-only guard."""
    def setUp(self):
        super().setUp()
        clear_probe_cache()
        self.addCleanup(clear_probe_cache)
        self.client = TestClient(create_app())
    def _patch_snapshot(self, probes, daemon_head="abc123"):
        snapshot = load_system_health(probes=probes, daemon_head=daemon_head)
        patcher = mock.patch(
            "webui.app.load_system_health",
            return_value=snapshot,
        )
        patcher.start()
        self.addCleanup(patcher.stop)
        return snapshot
    def test_versioned_route_is_registered(self):
        self.assertEqual(API_PATH, "/api/v1/system/health")
        self._patch_snapshot(_ALL_HEALTHY)
        response = self.client.get(API_PATH)
        self.assertEqual(response.status_code, 200)
    def test_healthy_payload_shape(self):
        self._patch_snapshot(_ALL_HEALTHY)
        data = self.client.get(API_PATH).json()
        self.assertEqual(data["status"], STATUS_OK)
        self.assertTrue(data["readiness"]["ready"])
        self.assertTrue(data["readiness"]["complete"])
        self.assertEqual(data["api"], API_PATH)
        self.assertEqual(len(data["dependencies"]), 3)
        for key in ("version", "process", "stale_runtime", "mcp_namespaces"):
            self.assertIn(key, data)
        self.assertIn("uptime_seconds", data["process"])
        self.assertIn("mutation_safe", data["stale_runtime"])
    def test_degraded_dependency_returns_503(self):
        probes = (
            _probe("control_plane_db", STATUS_DOWN, detail="missing", kind="sqlite"),
            _probe("repository", STATUS_OK, kind="git"),
        )
        self._patch_snapshot(probes)
        response = self.client.get(API_PATH)
        self.assertEqual(response.status_code, 503)
        data = response.json()
        self.assertFalse(data["readiness"]["ready"])
        self.assertTrue(data["readiness"]["reasons"])
    def test_dependency_entries_expose_status_and_latency(self):
        self._patch_snapshot(_ALL_HEALTHY)
        data = self.client.get(API_PATH).json()
        names = {entry["name"] for entry in data["dependencies"]}
        self.assertEqual(names, {"control_plane_db", "repository", "gitea"})
        for entry in data["dependencies"]:
            with self.subTest(dependency=entry["name"]):
                self.assertIn("status", entry)
                self.assertIn("required", entry)
                self.assertIn("latency_ms", entry)
    def test_response_body_carries_no_client_secrets(self):
        self._patch_snapshot(_ALL_HEALTHY)
        body = self.client.get(API_PATH).text
        self.assertEqual(scan_text_for_client_secrets(body), [])
    def test_deep_flag_is_forwarded(self):
        snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc")
        with mock.patch(
            "webui.app.load_system_health", return_value=snapshot
        ) as loader:
            self.client.get(f"{API_PATH}?deep=1")
            loader.assert_called_once_with(deep=True)
    def test_shallow_is_the_default(self):
        snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc")
        with mock.patch(
            "webui.app.load_system_health", return_value=snapshot
        ) as loader:
            self.client.get(API_PATH)
            loader.assert_called_once_with(deep=False)
    def test_route_rejects_mutation_methods(self):
        for method in ("POST", "PUT", "PATCH", "DELETE"):
            with self.subTest(method=method):
                response = self.client.request(method, API_PATH)
                self.assertEqual(response.status_code, 405)
                self.assertEqual(response.json()["error"], "read-only-mvp")
    def test_default_shallow_call_skips_the_network_probe(self):
        """The expensive probe must not run unless it was asked for."""
        with mock.patch("webui.system_health.probe_gitea") as probe:
            snapshot = load_system_health(deep=False)
        probe.assert_not_called()
        gitea = next(p for p in snapshot.dependencies if p.name == "gitea")
        self.assertEqual(gitea.status, STATUS_SKIPPED)
 class TestHealthRouteBackwardCompatibility(unittest.TestCase):
    """`/health` is expanded additively; MVP consumers must keep working."""
    def setUp(self):
        self.client = TestClient(create_app())
    def test_mvp_keys_are_unchanged(self):
        data = self.client.get("/health").json()
        self.assertEqual(data["status"], "ok")
        self.assertEqual(data["service"], "mcp-control-plane-webui")
        self.assertEqual(data["mode"], "read-only-mvp")
        self.assertIn("timestamp", data)
        self.assertEqual(data["deployment"]["mode"], "internal-operator-console")
    def test_health_points_at_the_versioned_api(self):
        data = self.client.get("/health").json()
        self.assertEqual(data["system_health_api"], API_PATH)
        self.assertIn("uptime_seconds", data)
        self.assertIn("started_at", data)
    def test_health_runs_no_dependency_probe(self):
        """Liveness must stay cheap: no probe, no snapshot assembly."""
        with mock.patch("webui.app.load_system_health") as loader:
            response = self.client.get("/health")
        self.assertEqual(response.status_code, 200)
        loader.assert_not_called()
 class TestSnapshotSerialisation(CleanParityMixin, unittest.TestCase):
    def test_snapshot_dict_is_json_serialisable(self):
        snapshot = load_system_health(probes=_ALL_HEALTHY, daemon_head="abc123")
        encoded = json.dumps(snapshot_to_dict(snapshot))
        self.assertIn("readiness", encoded)
 if __name__ == "__main__":
    unittest.main()
@@ -134,35 +134,13 @@ class TestClassification(unittest.TestCase):
        self.assertEqual(cls, wca.CLASS_ACTIVE_OPEN_PR)
        self.assertFalse(wca.is_removable(cls))
-    def test_stale_clean_issue_worktree_needs_merged_pr_proof(self):
+    def test_stale_clean_issue_worktree_removable(self):
-        # Scenario 5 (#858): age is not proof that the branch landed, so a
+        # Scenario 5: clean issue worktree, TTL expired, no lock -> removable.
        # TTL-expired issue worktree stays active work. Only authoritative
        # merged-PR evidence makes it removable, which is what keeps a
        # worktree holding unmerged commits from being reclaimed by age.
        cls = wca.classify_worktree(
            workflow_type=wca.WORKFLOW_ISSUE_WORK,
            is_dirty=False,
            ttl_expired=True,
        )
        self.assertEqual(cls, wca.CLASS_ACTIVE_ISSUE_WORK)
        self.assertFalse(wca.is_removable(cls))
        cls = wca.classify_worktree(
            workflow_type=wca.WORKFLOW_ISSUE_WORK,
            is_dirty=False,
            ttl_expired=True,
            merged_pr_cleanup={"proven": True},
        )
        self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE)
        self.assertTrue(wca.is_removable(cls))
    def test_stale_clean_conflict_fix_worktree_removable(self):
        # conflict_fix keeps the original TTL rule; #858 changed issue work only.
        cls = wca.classify_worktree(
            workflow_type=wca.WORKFLOW_CONFLICT_FIX,
            is_dirty=False,
            ttl_expired=True,
        )
        self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE)
        self.assertTrue(wca.is_removable(cls))
@@ -12,7 +12,6 @@ from starlette.routing import Route
 from webui.deployment_boundary import deployment_snapshot
 from webui.layout import render_page
 from webui.nav import NAV_GROUPS, STUB_PAGES
 from webui.project_registry import (
    ProjectRegistry,
    RegistryError,
@@ -46,13 +45,6 @@ from webui.worktree_scanner import load_hygiene_snapshot, snapshot_to_dict as wo
 from webui.worktree_views import render_worktrees_page
 from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict
 from webui.runtime_views import render_runtime_page
 from webui.timeline import load_timeline, snapshot_to_dict as timeline_snapshot_to_dict
 from webui.system_health import (
    API_PATH as SYSTEM_HEALTH_API_PATH,
    load_system_health,
    process_uptime,
    snapshot_to_dict as system_health_to_dict,
 )
 _READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
 _AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
@@ -67,100 +59,35 @@ def _stub_page(title: str, description: str) -> HTMLResponse:
    return HTMLResponse(render_page(title=title, body_html=body))
 _LEGACY_PAGES = (
    ("/queue", "Queue", "live PR and issue dashboard (#429)"),
    ("/projects", "Projects", "registry and onboarding (#427)"),
    ("/prompts", "Prompts", "canonical workflow prompt library (#428)"),
    ("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"),
    ("/audit", "Audit", "final-report paste and validator preview (#431)"),
    ("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"),
    ("/leases", "Leases", "collision and lease visibility (#433)"),
    ("/actions", "Actions", "gated write-action framework (#434)"),
 )
 def _render_home_nav_groups() -> str:
    groups = []
    for group in NAV_GROUPS:
        items = "".join(
            f'<li><a href="{item.href}">{item.label}</a>'
            + ("" if item.status == "live" else " <span class=\"muted\">(stub)</span>")
            + "</li>"
            for item in group.items
        )
        groups.append(f"<h3>{group.label}</h3><ul>{items}</ul>")
    return "".join(groups)
 async def home(_request: Request) -> HTMLResponse:
    legacy = "".join(
        f"<li><strong>{label}</strong> — {desc} "
        f'(<a href="{href}">{href}</a>)</li>'
        for href, label, desc in _LEGACY_PAGES
    )
    body = (
        "<h2>Operator console</h2>"
-        "<p>Read-only home for the MCP Control Plane Phase 1 operator console. "
+        "<p>Local entry point for MCP Control Plane operational views.</p>"
-        "Gitea, MCP capability gates, and canonical workflows remain the source "
+        "<ul>"
-        "of truth; this console never mutates them.</p>"
+        "<li><strong>Queue</strong> — live PR and issue dashboard (#429)</li>"
-        "<h2>Phase 1 surfaces</h2>"
+        "<li><strong>Projects</strong> — registry and onboarding (#427)</li>"
-        + _render_home_nav_groups()
+        "<li><strong>Prompts</strong> — canonical workflow prompt library (#428)</li>"
-        + "<h2>MVP legacy pages</h2>"
+        "<li><strong>Runtime</strong> — MCP health and stale-runtime detection (#430)</li>"
-        "<ul>" + legacy + "</ul>"
+        "<li><strong>Audit</strong> — final-report paste and validator preview (#431)</li>"
        "<li><strong>Worktrees</strong> — branch hygiene dashboard (#432)</li>"
        "<li><strong>Leases</strong> — collision and lease visibility (#433)</li>"
        "<li><strong>Actions</strong> — gated write-action framework (#434)</li>"
        "</ul>"
    )
    return HTMLResponse(render_page(title="Home", body_html=body))
 async def phase_stub(request: Request) -> HTMLResponse:
    """Graceful read-only placeholder for a not-yet-implemented Phase 1 surface."""
    title, description = STUB_PAGES[request.url.path]
    body = (
        f"<h2>{title}</h2>"
        f'<div class="stub"><p>{description}</p>'
        "<p>Phase 1 shell placeholder — no write actions. Tracked under "
        "epic #631.</p></div>"
    )
    return HTMLResponse(render_page(title=title, body_html=body))
 async def health(_request: Request) -> JSONResponse:
    """Liveness only — deliberately cheap, runs no dependency probe (#634).
    Every MVP key is retained so existing pollers keep working; the additions
    are a pointer to the structured API and the in-memory process uptime.
    Readiness lives at that API because answering it costs real probes.
    """
    bind_host = _request.app.state.webui_bind_host
    started_at, uptime_seconds = process_uptime()
    return JSONResponse({
        "status": "ok",
        "service": "mcp-control-plane-webui",
        "mode": "read-only-mvp",
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "deployment": deployment_snapshot(bind_host=bind_host),
        "started_at": started_at,
        "uptime_seconds": uptime_seconds,
        "system_health_api": SYSTEM_HEALTH_API_PATH,
    })
 def _truthy_flag(value: str | None) -> bool:
    return (value or "").strip().lower() in {"1", "true", "yes", "on"}
 async def api_system_health(request: Request) -> JSONResponse:
    """Structured read-only system health (#634).
    `?deep=1` opts into the expensive network probe. The response status code
    reflects readiness so automated checks can branch on it without parsing the
    body: 200 when ready, 503 when a required dependency failed or never ran.
    """
    deep = _truthy_flag(request.query_params.get("deep"))
    snapshot = load_system_health(deep=deep)
    payload = system_health_to_dict(snapshot)
    return JSONResponse(payload, status_code=200 if snapshot.ready else 503)
 async def queue(_request: Request) -> HTMLResponse:
    snapshot = load_queue_snapshot()
    return HTMLResponse(render_page(title="Queue", body_html=render_queue_page(snapshot)))
@@ -450,104 +377,6 @@ async def api_console_security_model(_request: Request) -> JSONResponse:
    })
 def _query_int(request: Request, key: str) -> int | None:
    """Parse an optional integer query parameter; None when absent/invalid."""
    raw = request.query_params.get(key)
    if raw is None or not str(raw).strip():
        return None
    try:
        return int(str(raw).strip())
    except (TypeError, ValueError):
        return None
 def _derive_remote(host: str) -> str:
    """Map a Gitea host to its known short remote name (control-plane scope key)."""
    text = (host or "").lower()
    if "prgs" in text:
        return "prgs"
    if "dadeschools" in text:
        return "dadeschools"
    return text.split(".")[0] if text else ""
 def _timeline_comment_source(host: str, org: str, repo: str):
    """Build a fail-soft CTH-comment fetcher for one repo, or None when offline.
    Returns a callable ``(kind, number) -> list[comment]``. Credentials or
    network failures raise inside the callable so ``load_timeline`` degrades the
    handoff source rather than the whole timeline. Offline test mode yields no
    live source so the handoff section reports ``not run``.
    """
    import os
    from gitea_auth import api_fetch_page, get_auth_header, repo_api_url
    offline = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip().lower() in {"1", "true", "yes"}
    if offline:
        return None
    auth = get_auth_header(host)
    if not auth:
        return None
    def _fetch(kind: str, number: int) -> list:
        segment = "pulls" if kind == "pr" else "issues"
        url = f"{repo_api_url(host, org, repo)}/{segment}/{int(number)}/comments"
        comments: list = []
        page = 1
        while page <= 20:
            raw, meta = api_fetch_page(url, auth, page=page, limit=50)
            comments.extend(raw)
            if bool(meta["is_final_page"]):
                break
            page += 1
        return comments
    return _fetch
 async def api_v1_timeline(request: Request) -> JSONResponse:
    """Read-only workflow-event timeline (#637). Filter by issue/PR/session."""
    from webui.queue_loader import _host_from_url  # host normalisation helper
    registry, error = _load_project_registry()
    if error is not None:
        return JSONResponse(error.to_dict(), status_code=500)
    project = registry.projects[0] if registry.projects else None
    org = request.query_params.get("org") or (project.gitea_owner if project else "")
    repo = request.query_params.get("repo") or (project.repo_name if project else "")
    host = _host_from_url(project.remote_host) if project else ""
    remote = request.query_params.get("remote") or _derive_remote(host)
    if not (remote and org and repo):
        return JSONResponse(
            {
                "error": "timeline_scope_unresolved",
                "detail": "no project in registry and no remote/org/repo query params provided",
            },
            status_code=400,
        )
    comment_source = _timeline_comment_source(host, org, repo) if (host and org and repo) else None
    snapshot = load_timeline(
        remote=remote,
        org=org,
        repo=repo,
        issue=_query_int(request, "issue"),
        pr=_query_int(request, "pr"),
        session=(request.query_params.get("session") or None),
        limit=_query_int(request, "limit"),
        offset=_query_int(request, "offset"),
        comment_source=comment_source,
    )
    # A filter no surviving source can carry is refused, not answered empty:
    # a 200 with zero events would tell the operator no such activity exists.
    status_code = 200 if snapshot.ok else 422
    return JSONResponse(timeline_snapshot_to_dict(snapshot), status_code=status_code)
 async def method_not_allowed(request: Request, _exc: Exception) -> Response:
    path = request.url.path
    if path in _AUDIT_MUTATION_PATHS and request.method == "POST":
@@ -570,7 +399,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
        routes=[
            Route("/", home, methods=["GET"]),
            Route("/health", health, methods=["GET"]),
            Route(SYSTEM_HEALTH_API_PATH, api_system_health, methods=["GET"]),
            Route("/queue", queue, methods=["GET"]),
            Route("/api/queue", api_queue, methods=["GET"]),
            Route("/projects", projects, methods=["GET"]),
@@ -587,7 +415,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
            Route("/api/prompts", api_prompts, methods=["GET"]),
            Route("/runtime", runtime, methods=["GET"]),
            Route("/api/runtime", api_runtime, methods=["GET"]),
            Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]),
            Route("/audit", audit, methods=["GET", "POST"]),
            Route("/api/audit", api_audit, methods=["GET", "POST"]),
            Route("/worktrees", worktrees, methods=["GET"]),
@@ -611,10 +438,6 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
                api_console_security_model,
                methods=["GET"],
            ),
            *[
                Route(path, phase_stub, methods=["GET"])
                for path in STUB_PAGES
            ],
        ],
        exception_handlers={405: method_not_allowed},
    )
@@ -236,34 +236,6 @@ _ACTION_SPECS: tuple[ConsoleAction, ...] = (
        phase=3,
        summary="Remove a remote feature branch.",
    ),
    # #642: sanctioned daemon lifecycle. These exist so operators have an
    # audited path off `pkill -f mcp_server.py` (#630). Restart drops every
    # in-flight request on a namespace, so it carries the same dual-control and
    # break-glass weight as a merge; reload drains first and is privileged but
    # not destructive. Neither ever exposes a raw kill: execution is handed to
    # a host supervisor by ``webui.sanctioned_restart``.
    ConsoleAction(
        action_id="system.reload_namespace",
        task_key="reload_namespace",
        action_class=CLASS_PRIVILEGED,
        minimum_role=CONTROLLER,
        requires_confirmation=True,
        dual_control=False,
        break_glass=False,
        phase=2,
        summary="Gracefully reload one MCP namespace via the host supervisor.",
    ),
    ConsoleAction(
        action_id="system.restart_namespace",
        task_key="restart_namespace",
        action_class=CLASS_DESTRUCTIVE,
        minimum_role=ADMIN,
        requires_confirmation=True,
        dual_control=True,
        break_glass=True,
        phase=2,
        summary="Restart one MCP namespace via the host supervisor.",
    ),
 )
 ACTIONS: dict[str, ConsoleAction] = {a.action_id: a for a in _ACTION_SPECS}
@@ -110,8 +110,6 @@ def _format_target(action_id: str, params: dict[str, Any]) -> str:
        )
    if action_id == "create_issue":
        return f"issue {params.get('title', '?')!r}"
    if action_id in {"system.restart_namespace", "system.reload_namespace"}:
        return f"MCP namespace {params.get('namespace', '?')!r}"
    return "unspecified"
@@ -167,17 +165,6 @@ def build_action_registry() -> ActionRegistry:
         "gitea_create_issue_comment", "Post a PR review thread comment."),
        ("close_pr", "Close PR", "close_pr", "gitea_edit_pr",
         "Close a pull request without merge."),
        # #642: the sanctioned replacement for the forbidden manual daemon-kill
        # recovery path (#630). The "tool" is a host supervisor hook, not an MCP
        # call — the console never signals a process. Preview and gating live in
        # ``webui.sanctioned_restart``; these stay disabled like every other
        # registry entry.
        ("system.reload_namespace", "Reload MCP namespace", "reload_namespace",
         "host.supervisor_reload",
         "Gracefully reload one MCP namespace via the host supervisor."),
        ("system.restart_namespace", "Restart MCP namespace",
         "restart_namespace", "host.supervisor_restart",
         "Restart one MCP namespace via the host supervisor."),
    )
    actions = tuple(
        GatedAction(
@@ -2,66 +2,28 @@
 from __future__ import annotations
-import os
+NAV_ITEMS = (
-
+    ("/", "Home"),
-from webui.nav import NAV_GROUPS
+    ("/queue", "Queue"),
    ("/projects", "Projects"),
    ("/prompts", "Prompts"),
    ("/runtime", "Runtime"),
    ("/audit", "Audit"),
    ("/worktrees", "Worktrees"),
    ("/leases", "Leases"),
    ("/actions", "Actions"),
 )
 MVP_NOTICE = (
    "Read-only MVP — Gitea, MCP tools, and canonical workflows remain the "
    "source of truth. No mutation endpoints."
 )
 # Canonical docs entry point surfaced from the shell header (#638).
 DOCS_URL = (
    "https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/src/branch/"
    "master/docs/webui-local-dev.md"
 )
 _LOCAL_HOSTS = frozenset({"", "127.0.0.1", "localhost", "::1"})
 def environment_label() -> str:
    """Classify the serving environment as ``local`` or ``remote`` (#638).
    Derived from the same ``WEBUI_HOST`` default the app binds to; loopback
    hosts are ``local``, anything else is ``remote``. Read-only signal only.
    """
    host = (os.environ.get("WEBUI_HOST", "127.0.0.1") or "").strip().lower()
    return "local" if host in _LOCAL_HOSTS else "remote"
 def _render_nav() -> str:
    groups_html = []
    for group in NAV_GROUPS:
        links = "".join(
            f'<a href="{item.href}"'
            + (' class="nav-stub"' if item.status == "stub" else "")
            + f'>{item.label}</a>'
            for item in group.items
        )
        groups_html.append(
            '<div class="nav-group">'
            f'<span class="nav-group-label">{group.label}</span>'
            f'<span class="nav-group-links">{links}</span>'
            "</div>"
        )
    return "".join(groups_html)
 def _render_badges() -> str:
    env = environment_label()
    return (
        '<div class="header-badges">'
        f'<span class="badge env-badge env-{env}">env: {env}</span>'
        '<span class="badge mode-badge">mode: read-only</span>'
        f'<a class="badge docs-link" href="{DOCS_URL}">Docs</a>'
        "</div>"
    )
 def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
-    nav_links = _render_nav()
+    nav_links = "".join(
-    header_badges = _render_badges()
+        f'<a href="{href}">{label}</a>' for href, label in NAV_ITEMS
    )
    return f"""<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -91,58 +53,21 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
      padding: 0.75rem 1.25rem;
    }}
    header h1 {{
-      margin: 0;
+      margin: 0 0 0.5rem;
      font-size: 1.1rem;
      font-weight: 600;
    }}
    .header-top {{
      display: flex;
      flex-wrap: wrap;
      align-items: center;
      justify-content: space-between;
      gap: 0.5rem 1rem;
      margin-bottom: 0.6rem;
    }}
    .header-badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.4rem; }}
    .env-badge.env-local {{ color: #8fd19e; border-color: #3d6b4a; }}
    .env-badge.env-remote {{ color: #e0c27a; border-color: #6b5730; }}
    .mode-badge {{ color: #9ec8f0; border-color: #3d5f7a; }}
    a.docs-link {{
      color: var(--accent);
      border-color: var(--accent);
      text-decoration: none;
      text-transform: none;
    }}
    a.docs-link:hover {{ filter: brightness(1.12); }}
    nav {{
      display: flex;
      flex-wrap: wrap;
-      gap: 0.5rem 1.25rem;
+      gap: 0.75rem 1rem;
    }}
    .nav-group {{
      display: flex;
      flex-direction: column;
      gap: 0.15rem;
    }}
    .nav-group-label {{
      font-size: 0.68rem;
      text-transform: uppercase;
      letter-spacing: 0.04em;
      color: var(--muted);
    }}
    .nav-group-links {{ display: inline-flex; flex-wrap: wrap; gap: 0.6rem; }}
    nav a {{
      color: var(--accent);
      text-decoration: none;
      font-size: 0.9rem;
    }}
    nav a:hover {{ text-decoration: underline; }}
    nav a.nav-stub {{ color: var(--muted); }}
    nav a.nav-stub::after {{
      content: " ·stub";
      font-size: 0.7rem;
      color: var(--muted);
    }}
    main {{
      max-width: 52rem;
      margin: 0 auto;
@@ -241,10 +166,7 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
 </head>
 <body>
  <header>
-    <div class="header-top">
+    <h1>MCP Control Plane</h1>
      <h1>MCP Control Plane</h1>
      {header_badges}
    </div>
    <nav>{nav_links}</nav>
  </header>
  <main>
@@ -1,111 +0,0 @@
 """Navigation IA for the Phase 1 operator console shell (#638).
 Single source of truth for the console navigation so ``webui/layout.py`` and
 the ``webui/app.py`` route table stay aligned with epic #631. Read-only: every
 destination is a GET view or a Phase 1 placeholder. No mutation links.
 Nav groups follow the #631 Phase 1 information architecture: Health, Traffic,
 Runtime/Sessions, Projects, Inventory, Timeline, Policy (placeholder), and
 Insights (placeholder). Later-phase surfaces are declared as ``stub`` items and
 backed by ``STUB_PAGES`` so their nav links resolve to a graceful placeholder
 instead of a 404.
 """
 from __future__ import annotations
 from dataclasses import dataclass
@dataclass(frozen=True)
 class NavItem:
    """A single navigation destination.
    ``status`` is ``"live"`` for implemented views and ``"stub"`` for Phase 1
    placeholders whose backing view lands in a later child issue.
    """
    href: str
    label: str
    status: str = "live"
@dataclass(frozen=True)
 class NavGroup:
    label: str
    items: tuple[NavItem, ...]
 NAV_GROUPS: tuple[NavGroup, ...] = (
    NavGroup("Health", (
        NavItem("/health", "Liveness"),
    )),
    NavGroup("Traffic", (
        NavItem("/queue", "Queue"),
        NavItem("/leases", "Leases"),
        NavItem("/actions", "Actions"),
    )),
    NavGroup("Runtime/Sessions", (
        NavItem("/runtime", "Runtime health"),
        NavItem("/sessions", "Sessions", "stub"),
    )),
    NavGroup("Projects", (
        NavItem("/projects", "Projects"),
    )),
    NavGroup("Inventory", (
        NavItem("/inventory", "Inventory", "stub"),
        NavItem("/worktrees", "Worktrees"),
    )),
    NavGroup("Timeline", (
        NavItem("/timeline", "Timeline", "stub"),
    )),
    NavGroup("Policy", (
        NavItem("/policy", "Policy", "stub"),
        NavItem("/prompts", "Prompts"),
    )),
    NavGroup("Insights", (
        NavItem("/insights", "Insights", "stub"),
        NavItem("/audit", "Audit"),
    )),
 )
 # Phase 1 placeholder destinations whose backing views land in later child
 # issues of epic #631. Each maps a path to (title, description). Routes are
 # registered so nav links resolve to a graceful, read-only stub page.
 STUB_PAGES: dict[str, tuple[str, str]] = {
    "/sessions": (
        "Sessions",
        "Active session, capability, and role inventory. Backed by the unified "
        "inventory API (#636) once it lands.",
    ),
    "/inventory": (
        "Inventory",
        "Unified sessions, leases, locks, namespaces, and worktree inventory. "
        "Backed by the Phase 1 inventory API (#636).",
    ),
    "/timeline": (
        "Timeline",
        "Workflow event timeline across issues and PRs. A later Phase 1 surface.",
    ),
    "/policy": (
        "Policy",
        "Capability and role policy surface. Placeholder until a later phase.",
    ),
    "/insights": (
        "Insights",
        "Aggregate operational insights and trends. Placeholder until a later "
        "phase.",
    ),
 }
 def iter_nav_items():
    """Yield every ``NavItem`` across all groups in declared order."""
    for group in NAV_GROUPS:
        for item in group.items:
            yield item
 def nav_hrefs() -> tuple[str, ...]:
    """Return every navigation href in declared order."""
    return tuple(item.href for item in iter_nav_items())
@@ -1,613 +0,0 @@
 """Sanctioned MCP restart and graceful reload controls (#642, Phase 2).
 Sessions have historically recovered MCP connectivity by killing the host
 daemon (``pkill -f mcp_server.py``, #630). That path stays forbidden: it kills
 every namespace on the host, contaminates the surviving session, and leaves no
 audit trail. This module is the sanctioned replacement.
 A restart is modelled as a *gated action*, never as a command:
 1. **Capability** — the console action resolves through ``console_authz``
   against ``task_capability_map``, so the console cannot invent an authority
   the MCP layer does not already define.
 2. **Preview** — :func:`build_restart_preview` renders a mutation ledger and
   the exact confirmation phrase. It never returns a shell command.
 3. **Confirmation** — the operator echoes a phrase naming the exact namespace
   and mode. A phrase for one namespace never authorizes another.
 4. **Operator authorization** — host daemon maintenance is authorized out of
   band through the environment (#630, and #710 finding F1: a worker session
   cannot set an env var for an already-running daemon, so this cannot be
   self-asserted the way a tool argument could).
 5. **Execution** — :func:`execute_restart` never spawns a process. Once every
   gate passes it hands the request to the configured host-managed restart
   hook; with no hook configured it fails closed.
 6. **Health recheck** — :func:`verify_post_restart_health` requires live
   client-namespace probe evidence before any post-restart clean claim.
 Manual ``pkill`` remains forbidden and is classified as contamination by
 :func:`classify_restart_command`, which blocks clean claims (#630 AC3).
 This module performs no I/O beyond reading its own environment configuration,
 imports no MCP client, and holds no credential.
 """
 from __future__ import annotations
 import os
 from dataclasses import asdict, dataclass
 from typing import Any
 import mcp_namespace_health
 import runtime_recovery_guard
 from webui import console_audit, console_authz
 # --- Operations -------------------------------------------------------------
 MODE_RESTART = "restart"
 MODE_RELOAD = "reload"
 MODES: tuple[str, ...] = (MODE_RESTART, MODE_RELOAD)
 ACTION_RESTART_NAMESPACE = "system.restart_namespace"
 ACTION_RELOAD_NAMESPACE = "system.reload_namespace"
 ACTION_FOR_MODE: dict[str, str] = {
    MODE_RESTART: ACTION_RESTART_NAMESPACE,
    MODE_RELOAD: ACTION_RELOAD_NAMESPACE,
 }
 # Namespaces the console may target. An unlisted name fails closed rather than
 # being passed through to a host hook.
 KNOWN_NAMESPACES: tuple[str, ...] = tuple(
    sorted(
        set(mcp_namespace_health.DEFAULT_NAMESPACES)
        | {"gitea-author", "gitea-reviewer", "gitea-merger",
           "gitea-reconciler", "gitea-controller"}
    )
 )
 # Scope tokens that would mean "everything at once". Explicit non-goal: the
 # console never offers a fleet-wide restart, because that is the blast radius
 # `pkill -f mcp_server.py` already had.
 _FLEET_TOKENS = frozenset({"*", "all", "fleet", "any", ""})
 # --- Environment configuration ----------------------------------------------
 # Read server-side only; the value is an opaque host hook reference (e.g. a
 # launchd label), never a command line, and is never rendered to a client.
 RESTART_HOOK_ENV = "GITEA_SANCTIONED_RESTART_HOOK"
 # --- Reason codes -----------------------------------------------------------
 DENY_UNKNOWN_MODE = "unknown_mode"
 DENY_UNKNOWN_NAMESPACE = "unknown_namespace"
 DENY_FLEET_SCOPE = "fleet_scope_not_permitted"
 DENY_UNAUTHORIZED = "unauthorized"
 DENY_CONFIRMATION_MISSING = "confirmation_required"
 DENY_CONFIRMATION_MISMATCH = "confirmation_mismatch"
 DENY_OPERATOR_AUTHORIZATION = "operator_authorization_missing"
 DENY_HOOK_NOT_CONFIGURED = "restart_hook_not_configured"
 DENY_CONTAMINATED_RUNTIME = "contaminated_runtime"
 ALLOW_HOST_ACTION_REQUIRED = "host_action_required"
 # Post-restart verification outcomes.
 HEALTH_CLEAN = "clean"
 HEALTH_UNPROVEN = "unproven"
 HEALTH_UNHEALTHY = "unhealthy"
 def _clean(value: Any) -> str:
    return str(value or "").strip()
 # --- Mutation ledger --------------------------------------------------------
@dataclass(frozen=True)
 class RestartLedgerEntry:
    """One planned step, shown before anything is asked of the host."""
    sequence: int
    step: str
    summary: str
    executes_process_kill: bool = False
 def _mutation_ledger(namespace: str, mode: str) -> tuple[RestartLedgerEntry, ...]:
    if mode == MODE_RELOAD:
        middle = RestartLedgerEntry(
            sequence=2,
            step="host_graceful_reload",
            summary=(
                f"Ask the configured host supervisor to reload {namespace} "
                "in place, draining in-flight requests. The console does not "
                "signal the process itself."
            ),
        )
    else:
        middle = RestartLedgerEntry(
            sequence=2,
            step="host_restart_hook",
            summary=(
                f"Ask the configured host supervisor to restart {namespace}. "
                "The console never sends a signal and never runs a kill."
            ),
        )
    return (
        RestartLedgerEntry(
            sequence=1,
            step="quiesce",
            summary=(
                f"Stop admitting new gated mutations for {namespace} and "
                "record the intent before anything restarts."
            ),
        ),
        middle,
        RestartLedgerEntry(
            sequence=3,
            step="health_recheck",
            summary=(
                f"Re-probe {namespace} through the live client namespace and "
                "prove the required tool is callable again."
            ),
        ),
        RestartLedgerEntry(
            sequence=4,
            step="audit",
            summary=(
                "Append actor, target namespace, mode, and result to the "
                "console audit log."
            ),
        ),
    )
 # --- Confirmation -----------------------------------------------------------
 def confirmation_phrase(namespace: str, mode: str) -> str:
    """Exact phrase an operator must echo, naming the namespace and mode.
    Binding the namespace into the phrase is the point: a confirmation typed
    for ``gitea-author`` cannot be replayed against ``gitea-merger``.
    """
    return f"{_clean(mode)} {_clean(namespace)}"
 def confirmation_matches(
    namespace: str, mode: str, confirmation: str | None
 ) -> bool:
    """Compare *confirmation* to the required phrase (exact, whitespace-trimmed)."""
    return _clean(confirmation) == confirmation_phrase(namespace, mode)
 # --- Scope validation -------------------------------------------------------
 def _validate_scope(namespace: str, mode: str) -> tuple[str, str] | None:
    """Return ``(reason_code, detail)`` when the scope is refused."""
    ns = _clean(namespace)
    md = _clean(mode)
    if md not in MODES:
        return (
            DENY_UNKNOWN_MODE,
            f"Mode {md!r} is not one of {', '.join(MODES)}.",
        )
    if ns.lower() in _FLEET_TOKENS:
        return (
            DENY_FLEET_SCOPE,
            (
                "Fleet-wide restart is an explicit non-goal: it reproduces the "
                "blast radius of `pkill -f mcp_server.py` (#630). Restart one "
                "namespace at a time."
            ),
        )
    if ns not in KNOWN_NAMESPACES:
        return (
            DENY_UNKNOWN_NAMESPACE,
            f"Namespace {ns!r} is not a known MCP namespace.",
        )
    return None
 # --- Host hook --------------------------------------------------------------
 def restart_hook(env: dict[str, str] | None = None) -> dict[str, Any]:
    """Report the configured host-managed restart hook.
    The hook is a reference the *host* resolves (a supervisor label), not a
    command this process runs. ``configured=False`` fails restart closed.
    """
    source = env if env is not None else os.environ
    reference = _clean(source.get(RESTART_HOOK_ENV))
    return {
        "configured": bool(reference),
        "reference": reference or None,
        "source": RESTART_HOOK_ENV if reference else None,
        "self_assertable": False,
        "console_executes_process": False,
    }
 # --- Preview ----------------------------------------------------------------
 def build_restart_preview(
    namespace: str,
    mode: str = MODE_RESTART,
    *,
    principal: console_authz.Principal | None = None,
    env: dict[str, str] | None = None,
 ) -> dict[str, Any]:
    """Render the dry-run preview for a restart/reload request.
    Read-only: no authorization is granted, no host is contacted, and the
    result never contains a shell command.
    """
    ns = _clean(namespace)
    md = _clean(mode)
    action_id = ACTION_FOR_MODE.get(md, ACTION_RESTART_NAMESPACE)
    action = console_authz.get_action(action_id)
    decision = console_authz.authorize(action_id, principal)
    scope_error = _validate_scope(ns, md)
    hook = restart_hook(env)
    operator = runtime_recovery_guard.operator_authorization(env)
    return {
        "action_id": action_id,
        "namespace": ns,
        "mode": md,
        "scope_valid": scope_error is None,
        "scope_reason_code": scope_error[0] if scope_error else None,
        "scope_detail": scope_error[1] if scope_error else None,
        "required_role": action.minimum_role if action else None,
        "required_permission": action.mcp_permission if action else None,
        "action_class": action.action_class if action else None,
        "dual_control": action.dual_control if action else True,
        "break_glass": action.break_glass if action else True,
        "requires_confirmation": True,
        "confirmation_phrase": confirmation_phrase(ns, md),
        "mutation_ledger": [asdict(entry) for entry in _mutation_ledger(ns, md)],
        "authorization": decision.to_dict(),
        "operator_authorization": operator,
        "restart_hook": hook,
        "execution_enabled": False,
        "raw_process_kill_exposed": False,
        "known_namespaces": list(KNOWN_NAMESPACES),
        "post_restart_verification_required": True,
    }
 # --- Gate -------------------------------------------------------------------
 def assess_restart_request(
    namespace: str,
    mode: str = MODE_RESTART,
    *,
    principal: console_authz.Principal | None = None,
    confirmation: str | None = None,
    contamination_marker: dict[str, Any] | None = None,
    env: dict[str, str] | None = None,
 ) -> dict[str, Any]:
    """Decide whether a restart request may proceed to the host hook.
    Every gate must pass. The first failure wins and is reported with a stable
    reason code; a pass never means "restarted", only "may be handed to the
    configured host hook".
    """
    ns = _clean(namespace)
    md = _clean(mode)
    action_id = ACTION_FOR_MODE.get(md, ACTION_RESTART_NAMESPACE)
    preview = build_restart_preview(ns, md, principal=principal, env=env)
    def refuse(reason_code: str, detail: str) -> dict[str, Any]:
        return {
            "allowed": False,
            "gates_passed": False,
            "reason_code": reason_code,
            "detail": detail,
            "action_id": action_id,
            "namespace": ns,
            "mode": md,
            "preview": preview,
            "execution_enabled": False,
        }
    scope_error = _validate_scope(ns, md)
    if scope_error is not None:
        return refuse(*scope_error)
    # Authority is checked as an authorization decision, not an execution
    # grant. ``for_execution=True`` asks "may the console perform this write?",
    # and the answer here is permanently no: step 2 of the ledger is a request
    # to the host supervisor, so the console's Phase 2 execution gate is not
    # the relevant gate. Every branch below keeps ``execution_enabled`` False
    # and :func:`execute_restart` never touches a process.
    decision = console_authz.authorize(action_id, principal)
    if not decision.allowed:
        return refuse(DENY_UNAUTHORIZED, decision.detail)
    if not _clean(confirmation):
        return refuse(
            DENY_CONFIRMATION_MISSING,
            (
                "Type the confirmation phrase "
                f"{preview['confirmation_phrase']!r} to proceed."
            ),
        )
    if not confirmation_matches(ns, md, confirmation):
        return refuse(
            DENY_CONFIRMATION_MISMATCH,
            (
                "Confirmation does not name this namespace and mode; expected "
                f"{preview['confirmation_phrase']!r}."
            ),
        )
    operator = preview["operator_authorization"]
    if not operator["authorized"]:
        return refuse(
            DENY_OPERATOR_AUTHORIZATION,
            (
                "Host daemon maintenance requires out-of-band operator "
                "authorization via "
                f"{runtime_recovery_guard.OPERATOR_AUTHORIZATION_ENV}."
            ),
        )
    # #630's task-scoped gate deliberately lets a contaminated worker keep
    # commenting and handing off. Restart is stricter and unconditional: a
    # runtime already contaminated by a manual kill must be reconciled before
    # it is restarted again, or the restart just launders the contamination.
    if contamination_marker and not contamination_marker.get(
        "cleared_by_reconciler"
    ):
        return refuse(
            DENY_CONTAMINATED_RUNTIME,
            (
                "A live contamination marker is present; clear it through the "
                "reconciler path before restarting."
            ),
        )
    hook = preview["restart_hook"]
    if not hook["configured"]:
        return refuse(
            DENY_HOOK_NOT_CONFIGURED,
            (
                "No host-managed restart hook is configured "
                f"({RESTART_HOOK_ENV}). The console will not fall back to a "
                "process kill."
            ),
        )
    return {
        "allowed": True,
        "gates_passed": True,
        "reason_code": ALLOW_HOST_ACTION_REQUIRED,
        "detail": (
            "Every gate passed. The restart must be performed by the "
            "configured host supervisor; the console does not signal the "
            "process."
        ),
        "action_id": action_id,
        "namespace": ns,
        "mode": md,
        "preview": preview,
        "execution_enabled": False,
        "console_executes": False,
        "console_active_phase": console_authz.ACTIVE_PHASE,
    }
 # --- Execution --------------------------------------------------------------
 def execute_restart(
    namespace: str,
    mode: str = MODE_RESTART,
    *,
    principal: console_authz.Principal | None = None,
    confirmation: str | None = None,
    contamination_marker: dict[str, Any] | None = None,
    env: dict[str, str] | None = None,
    request_id: str | None = None,
    session_id: str | None = None,
 ) -> dict[str, Any]:
    """Run every gate, audit the outcome, and hand off to the host.
    This function never spawns a process, never sends a signal, and never
    builds a command line. ``success`` is False in both directions: a refused
    request is refused, and an authorized request still requires the host
    supervisor to act.
    """
    assessment = assess_restart_request(
        namespace,
        mode,
        principal=principal,
        confirmation=confirmation,
        contamination_marker=contamination_marker,
        env=env,
    )
    action_id = assessment["action_id"]
    allowed = assessment["allowed"]
    audit = console_audit.record_event(
        action_id=action_id,
        result=(
            console_audit.RESULT_ALLOWED if allowed
            else console_audit.RESULT_DENIED
        ),
        principal=principal,
        target={"namespace": assessment["namespace"], "mode": assessment["mode"]},
        reason_code=assessment["reason_code"],
        detail=assessment["detail"],
        request_id=request_id,
        session_id=session_id,
        metadata={
            "gates_passed": assessment["gates_passed"],
            "process_kill_executed": False,
            "post_restart_verification_required": True,
        },
    )
    return {
        "success": False,
        "outcome": (
            ALLOW_HOST_ACTION_REQUIRED if allowed else assessment["reason_code"]
        ),
        "allowed": allowed,
        "detail": assessment["detail"],
        "namespace": assessment["namespace"],
        "mode": assessment["mode"],
        "action_id": action_id,
        "process_kill_executed": False,
        "host_hook": assessment["preview"]["restart_hook"],
        "next_action": (
            "Have the host supervisor perform the restart, then call "
            "verify_post_restart_health with live client-namespace evidence "
            "before claiming a clean session."
            if allowed
            else assessment["detail"]
        ),
        "assessment": assessment,
        "audit": audit,
    }
 # --- Contamination classification -------------------------------------------
 def classify_restart_command(
    command: str | None,
    *,
    mcp_pids: list[Any] | tuple[Any, ...] | None = None,
    session_id: str | None = None,
    remote: str | None = None,
    role: str | None = None,
 ) -> dict[str, Any]:
    """Classify an operator-proposed recovery command (#630 AC2).
    A manual ``pkill``/``kill`` of the MCP daemon is contamination, not a
    restart. When contaminating, a durable marker is returned so downstream
    gated mutations and clean claims fail closed.
    """
    classification = runtime_recovery_guard.classify_recovery_command(
        command, mcp_pids=mcp_pids
    )
    contaminating = bool(classification.get("contamination"))
    marker = None
    if contaminating:
        marker = runtime_recovery_guard.build_contamination_record(
            reason_class=(
                classification.get("reason_class")
                or runtime_recovery_guard.REASON_MANUAL_DAEMON_KILL
            ),
            command_redacted=classification.get("redacted_command"),
            session_id=session_id,
            remote=remote,
            role=role,
            detail=(
                "Manual daemon kill is forbidden; use the sanctioned "
                f"{ACTION_RESTART_NAMESPACE} gated action instead."
            ),
        )
    return {
        "contamination": contaminating,
        "sanctioned": not contaminating and not classification.get("process_kill"),
        "clean_claim_allowed": not contaminating,
        "reason_class": classification.get("reason_class"),
        "redacted_command": classification.get("redacted_command"),
        "classification": classification,
        "contamination_marker": marker,
        "sanctioned_alternative": ACTION_RESTART_NAMESPACE,
    }
 # --- Post-restart health verification ---------------------------------------
 def verify_post_restart_health(
    namespace: str,
    *,
    probe_result: dict[str, Any] | None = None,
    probe_source: str | None = None,
    registered_tools: list[str] | tuple[str, ...] | None = None,
    required_tool: str | None = None,
    profile: str | None = None,
 ) -> dict[str, Any]:
    """Require live proof a namespace is callable before any clean claim (AC3).
    Static registration is not proof and neither is an offline subprocess
    probe: only ``probe_source=client_namespace`` evidence can clear a
    post-restart session for mutations.
    """
    ns = _clean(namespace)
    health = mcp_namespace_health.classify_namespace_probe(
        ns,
        required_tool=required_tool,
        registered_tools=registered_tools,
        probe_result=probe_result,
        profile=profile,
        probe_source=probe_source,
    )
    healthy = bool(health.get("healthy"))
    proven = bool(health.get("ide_namespace_proven"))
    if healthy and proven:
        status = HEALTH_CLEAN
    elif healthy:
        status = HEALTH_UNPROVEN
    else:
        status = HEALTH_UNHEALTHY
    reasons = list(health.get("reasons") or [])
    if status == HEALTH_UNPROVEN:
        reasons.append(
            "Namespace reported healthy without live client-namespace "
            "evidence; a post-restart clean claim requires "
            f"probe_source={mcp_namespace_health.PROBE_SOURCE_CLIENT!r}."
        )
    return {
        "namespace": ns,
        "status": status,
        "healthy": healthy,
        "ide_namespace_proven": proven,
        "clean_claim_allowed": status == HEALTH_CLEAN,
        "mutations_allowed": status == HEALTH_CLEAN,
        "reasons": reasons,
        "health": health,
    }
 # --- Policy surface ---------------------------------------------------------
 def restart_policy() -> dict[str, Any]:
    """Machine-readable description of the sanctioned restart contract."""
    return {
        "policy_version": 1,
        "modes": list(MODES),
        "actions": [ACTION_RESTART_NAMESPACE, ACTION_RELOAD_NAMESPACE],
        "known_namespaces": list(KNOWN_NAMESPACES),
        "fleet_scope_permitted": False,
        "console_executes_process_kill": False,
        "raw_kill_exposed": False,
        "requires_confirmation": True,
        "confirmation_binds_namespace": True,
        "operator_authorization_env": (
            runtime_recovery_guard.OPERATOR_AUTHORIZATION_ENV
        ),
        "restart_hook_env": RESTART_HOOK_ENV,
        "manual_kill_classified_as": runtime_recovery_guard.CONTAMINATION_KIND,
        "post_restart_clean_claim_requires": (
            mcp_namespace_health.PROBE_SOURCE_CLIENT
        ),
        "audit_required": True,
        "silent_auto_restart_permitted": False,
    }
@@ -1,682 +0,0 @@
 """Read-only system-health model for the operator console API (#634).
 `/health` answers liveness only. Operators automating readiness checks need a
 structured view of *why* the control plane is or is not usable: which
 dependencies answered, how long they took, what version of the code is running,
 and whether the runtime is stale relative to its remote.
 Three rules shape this module.
 * **Read-only.** Every probe opens its subject read-only. The control-plane
  database is opened through a ``mode=ro`` URI so a health check can never
  create or migrate a schema, and no probe writes, restarts, or reloads
  anything — restart controls are Phase 2, and #630 forbids process-kill
  recovery outright.
 * **Fail-soft.** A dependency that is unreachable is a *status*, not an
  exception. Probes catch their own failures and report them as a degraded or
  down entry carrying a reason.
 * **Never claim more than was proven.** Readiness is derived only from probes
  that actually ran, ``mutation_safe`` stays false unless the parity commits are
  known and equal, and an MCP namespace is reported unproven because a web
  process cannot exercise the IDE-managed client path (#543).
 """
 from __future__ import annotations
 import os
 import re
 import sqlite3
 import subprocess
 import time
 from dataclasses import dataclass
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any, Callable
 from urllib.parse import urlsplit, urlunsplit
 import control_plane_db
 import mcp_namespace_health
 from gitea_auth import api_request, get_auth_header, gitea_url
 from webui.project_registry import load_registry
 SERVICE_NAME = "mcp-control-plane-webui"
 API_PATH = "/api/v1/system/health"
 STATUS_OK = "ok"
 STATUS_DEGRADED = "degraded"
 STATUS_DOWN = "down"
 STATUS_SKIPPED = "skipped"
 STATUS_UNPROVEN = "unproven"
 # Statuses that count as a healthy answer from a probe.
 _HEALTHY_STATUSES = frozenset({STATUS_OK})
 # Statuses meaning "this probe did not run", as opposed to "it ran and failed".
 _NOT_RUN_STATUSES = frozenset({STATUS_SKIPPED})
 _DEEP_PROBE_TTL_ENV = "WEBUI_HEALTH_PROBE_TTL_SECONDS"
 _DEFAULT_DEEP_PROBE_TTL = 15.0
 _GITEA_PROBE_TIMEOUT_SECONDS = 5.0
 _OFFLINE_ENV = "WEBUI_TEST_OFFLINE"
 # Credential-shaped material that must never reach the browser, mirroring the
 # forbidden client patterns in webui/deployment_boundary.py.
 _SECRET_RE = re.compile(
    r"(?i)\b(token|password|passwd|secret|authorization|bearer)\b\s*[:=]?\s*\S+"
 )
 _LONG_OPAQUE_RE = re.compile(r"\b[A-Za-z0-9_\-]{32,}\b")
 # Captured once at import so uptime measures this process, not the request.
 _STARTED_AT = datetime.now(timezone.utc)
 _STARTED_MONOTONIC = time.monotonic()
 # TTL cache for the expensive (network) probe only.
 _deep_cache: dict[str, tuple[float, "DependencyProbe"]] = {}
@dataclass(frozen=True)
 class DependencyProbe:
    """One dependency check, fail-soft, with its own latency."""
    name: str
    kind: str
    status: str
    detail: str
    required: bool
    latency_ms: float | None = None
    metadata: dict[str, Any] | None = None
    @property
    def healthy(self) -> bool:
        return self.status in _HEALTHY_STATUSES
    @property
    def ran(self) -> bool:
        return self.status not in _NOT_RUN_STATUSES
@dataclass(frozen=True)
 class VersionInfo:
    git_sha: str | None
    git_describe: str | None
    control_plane_schema_version: int | None
    python_version: str
    known: bool
@dataclass(frozen=True)
 class StaleRuntime:
    """Parity between the running code, the checkout, and the remote.
    ``mutation_safe`` is deliberately conservative: unknown is not safe.
    """
    daemon_head: str | None
    checkout_head: str | None
    remote_head: str | None
    stale: bool
    determinable: bool
    mutation_safe: bool
    reasons: tuple[str, ...]
@dataclass(frozen=True)
 class SystemHealthSnapshot:
    status: str
    ready: bool
    readiness_complete: bool
    readiness_reasons: tuple[str, ...]
    service: str
    mode: str
    version: VersionInfo
    started_at: str
    uptime_seconds: float
    timestamp: str
    deep_probes_requested: bool
    dependencies: tuple[DependencyProbe, ...]
    mcp_namespaces: tuple[dict[str, Any], ...]
    stale_runtime: StaleRuntime
    probe_errors: tuple[str, ...] = ()
 def process_uptime() -> tuple[str, float]:
    """Process start timestamp and uptime — in-memory, safe for `/health`."""
    return _STARTED_AT.isoformat(), round(time.monotonic() - _STARTED_MONOTONIC, 3)
 def _offline() -> bool:
    return (os.environ.get(_OFFLINE_ENV) or "").strip().lower() in {"1", "true", "yes"}
 def _repo_root() -> Path:
    override = (os.environ.get("WEBUI_REPO_ROOT") or "").strip()
    if override:
        return Path(override).resolve()
    return Path(__file__).resolve().parent.parent
 def _deep_probe_ttl() -> float:
    raw = (os.environ.get(_DEEP_PROBE_TTL_ENV) or "").strip()
    if not raw:
        return _DEFAULT_DEEP_PROBE_TTL
    try:
        value = float(raw)
    except ValueError:
        return _DEFAULT_DEEP_PROBE_TTL
    return value if value >= 0 else _DEFAULT_DEEP_PROBE_TTL
 def redact(text: str) -> str:
    """Strip credential-shaped material from operator-visible probe text.
    Probe details carry exception strings, and an exception raised by an HTTP
    client can quote the request that failed. Redaction happens here, at the
    boundary where those strings become part of a browser-bound payload.
    """
    if not text:
        return ""
    cleaned = _redact_urls(text)
    cleaned = _SECRET_RE.sub(lambda m: f"{m.group(1)}=[redacted]", cleaned)
    return _LONG_OPAQUE_RE.sub("[redacted]", cleaned)
 def _redact_urls(text: str) -> str:
    return re.sub(r"https?://\S+", lambda m: redact_url(m.group(0)), text)
 def redact_url(url: str) -> str:
    """Reduce a URL to scheme://host/path — no userinfo, no query, no fragment."""
    try:
        parts = urlsplit(url)
    except ValueError:
        return "[redacted-url]"
    if not parts.scheme or not parts.hostname:
        return "[redacted-url]"
    netloc = parts.hostname
    if parts.port:
        netloc = f"{netloc}:{parts.port}"
    return urlunsplit((parts.scheme, netloc, parts.path, "", ""))
 def _git(repo: Path, *args: str) -> str | None:
    try:
        completed = subprocess.run(
            ["git", "-C", str(repo), *args],
            capture_output=True,
            text=True,
            check=False,
            timeout=10,
        )
    except (OSError, subprocess.SubprocessError):
        return None
    if completed.returncode != 0:
        return None
    return (completed.stdout or "").strip() or None
 def _load_version(repo: Path, *, schema_version: int | None) -> VersionInfo:
    import platform
    git_sha = None if _offline() else _git(repo, "rev-parse", "HEAD")
    describe = None if _offline() else _git(repo, "describe", "--tags", "--always")
    return VersionInfo(
        git_sha=git_sha,
        git_describe=describe,
        control_plane_schema_version=schema_version,
        python_version=platform.python_version(),
        known=bool(git_sha),
    )
 # ---------------------------------------------------------------------------
 # Dependency probes
 # ---------------------------------------------------------------------------
 def _elapsed_ms(started: float) -> float:
    return round((time.monotonic() - started) * 1000, 3)
 def probe_control_plane_db(db_path: str | None = None) -> DependencyProbe:
    """Read-only reachability check for the control-plane SQLite substrate.
    Opened through a ``mode=ro`` URI on purpose: ``ControlPlaneDB.__init__``
    creates directories and runs schema migrations, which a health check must
    never do.
    """
    path = (db_path or control_plane_db.default_db_path()).strip()
    started = time.monotonic()
    metadata: dict[str, Any] = {"path": path}
    def _result(status: str, detail: str) -> DependencyProbe:
        return DependencyProbe(
            name="control_plane_db",
            kind="sqlite",
            status=status,
            detail=detail,
            required=True,
            latency_ms=_elapsed_ms(started),
            metadata=metadata,
        )
    if not path or not os.path.exists(path):
        return _result(STATUS_DOWN, "control-plane database file does not exist yet")
    try:
        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True, timeout=5)
        try:
            row = conn.execute(
                "SELECT value FROM schema_meta WHERE key = 'schema_version'"
            ).fetchone()
            leases = conn.execute(
                "SELECT COUNT(*) FROM leases WHERE status = 'active'"
            ).fetchone()
        finally:
            conn.close()
    except sqlite3.Error as exc:
        return _result(STATUS_DOWN, redact(f"control-plane database unreadable: {exc}"))
    schema_version = int(row[0]) if row and str(row[0]).isdigit() else None
    metadata["schema_version"] = schema_version
    metadata["active_leases"] = int(leases[0]) if leases else None
    if schema_version is None:
        return _result(
            STATUS_DEGRADED, "control-plane database has no recorded schema version"
        )
    if schema_version != control_plane_db.SCHEMA_VERSION:
        return _result(
            STATUS_DEGRADED,
            f"control-plane schema version {schema_version} does not match the "
            f"version this code expects ({control_plane_db.SCHEMA_VERSION})",
        )
    return _result(STATUS_OK, f"schema v{schema_version} readable")
 def probe_repository(repo: Path) -> DependencyProbe:
    """Local checkout reachability — required, cheap, no network."""
    started = time.monotonic()
    metadata: dict[str, Any] = {"repo_root": str(repo)}
    if _offline():
        return DependencyProbe(
            name="repository",
            kind="git",
            status=STATUS_SKIPPED,
            detail=f"{_OFFLINE_ENV} is set; git probe skipped",
            required=True,
            latency_ms=_elapsed_ms(started),
            metadata=metadata,
        )
    head = _git(repo, "rev-parse", "HEAD")
    if not head:
        return DependencyProbe(
            name="repository",
            kind="git",
            status=STATUS_DOWN,
            detail=f"HEAD could not be read at {repo}",
            required=True,
            latency_ms=_elapsed_ms(started),
            metadata=metadata,
        )
    branch = _git(repo, "rev-parse", "--abbrev-ref", "HEAD")
    metadata["head"] = head
    metadata["branch"] = branch
    return DependencyProbe(
        name="repository",
        kind="git",
        status=STATUS_OK,
        detail=f"checkout readable at {branch or 'detached HEAD'}",
        required=True,
        latency_ms=_elapsed_ms(started),
        metadata=metadata,
    )
 def probe_gitea(host: str) -> DependencyProbe:
    """Live Gitea reachability. Expensive (network), so opt-in via ``deep``.
    Optional by design: the console stays useful for local inventory when the
    remote is unreachable, so a failure here degrades status without claiming
    the process itself is unready.
    """
    started = time.monotonic()
    metadata: dict[str, Any] = {"host": host}
    def _failure(status: str, detail: str) -> DependencyProbe:
        return DependencyProbe(
            name="gitea",
            kind="http",
            status=status,
            detail=detail,
            required=False,
            latency_ms=_elapsed_ms(started),
            metadata=metadata,
        )
    if not host:
        return _failure(STATUS_DEGRADED, "no Gitea host is configured in the registry")
    try:
        auth = get_auth_header(host)
    except Exception as exc:  # noqa: BLE001 — credential guards are a status here
        return _failure(STATUS_DEGRADED, redact(f"credential lookup refused: {exc}"))
    if not auth:
        return _failure(STATUS_DEGRADED, f"no credentials available for {host}")
    url = gitea_url(host, "/api/v1/version")
    metadata["endpoint"] = redact_url(url)
    try:
        data = api_request("GET", url, auth, timeout=_GITEA_PROBE_TIMEOUT_SECONDS)
    except Exception as exc:  # noqa: BLE001 — a down dependency is a status
        return _failure(STATUS_DOWN, redact(f"Gitea probe failed: {exc}"))
    if isinstance(data, dict) and data.get("version"):
        metadata["gitea_version"] = str(data["version"])
    return DependencyProbe(
        name="gitea",
        kind="http",
        status=STATUS_OK,
        detail=f"{host} reachable",
        required=False,
        latency_ms=_elapsed_ms(started),
        metadata=metadata,
    )
 def _skipped_gitea(host: str) -> DependencyProbe:
    return DependencyProbe(
        name="gitea",
        kind="http",
        status=STATUS_SKIPPED,
        detail="network probe not requested; call with ?deep=1 to run it",
        required=False,
        latency_ms=None,
        metadata={"host": host},
    )
 def namespace_summaries() -> tuple[dict[str, Any], ...]:
    """Declared MCP namespaces, each honestly reported as unproven.
    The web process runs outside the IDE-managed MCP client, so it cannot
    invoke a namespace tool. Per #543 only a ``client_namespace`` probe proves
    that path, and inventing a healthy verdict here is exactly the false claim
    the mutation gates exist to prevent.
    """
    rows: list[dict[str, Any]] = []
    for namespace, required_tool in sorted(
        mcp_namespace_health.REQUIRED_NAMESPACE_TOOLS.items()
    ):
        classification = mcp_namespace_health.classify_namespace_probe(
            namespace,
            required_tool=required_tool,
            probe_result=None,
            probe_source=mcp_namespace_health.PROBE_SOURCE_UNKNOWN,
        )
        rows.append(
            {
                "namespace": namespace,
                "required_tool": required_tool,
                "status": STATUS_UNPROVEN,
                "ide_namespace_proven": bool(classification.get("ide_namespace_proven")),
                "reason": (
                    "the web console cannot invoke the IDE-managed MCP client; "
                    "namespace health must be proven with a client_namespace "
                    "probe (#543)"
                ),
                "error_type": classification.get("error_type"),
            }
        )
    return tuple(rows)
 def assess_stale_runtime(
    repo: Path,
    *,
    daemon_head: str | None = None,
    git_reader: Callable[..., str | None] | None = None,
 ) -> StaleRuntime:
    """Three-way parity view: running code, local checkout, remote-tracking ref.
    ``mutation_safe`` requires all three to be known and equal. Anything less —
    including "the remote ref was never fetched" — is reported as not safe with
    a reason, so an operator never reads an unproven green.
    """
    reader = git_reader or (lambda *args: _git(repo, *args))
    reasons: list[str] = []
    # The offline switch suppresses real subprocess calls; an explicitly
    # injected reader is already a substitute for them and is always used.
    offline = _offline() and git_reader is None
    checkout_head = None if offline else reader("rev-parse", "HEAD")
    remote_head = None if offline else reader("rev-parse", "@{upstream}")
    if offline:
        reasons.append(f"{_OFFLINE_ENV} is set; parity commits were not read")
    else:
        if checkout_head is None:
            reasons.append("local checkout HEAD could not be read")
        if remote_head is None:
            reasons.append(
                "no remote-tracking commit is known for the current branch; "
                "remote staleness is indeterminate (no fetch is performed here)"
            )
    effective_daemon = daemon_head if daemon_head is not None else checkout_head
    if daemon_head is None:
        reasons.append(
            "the running MCP daemon's startup commit is not observable from the "
            "web process; the checkout commit is reported in its place"
        )
    determinable = bool(checkout_head and remote_head and effective_daemon)
    stale = bool(
        determinable and len({checkout_head, remote_head, effective_daemon}) > 1
    )
    if stale:
        reasons.append(
            "runtime, checkout, and remote commits disagree; restart the MCP "
            "server after updating the checkout before trusting capability gates"
        )
    return StaleRuntime(
        daemon_head=effective_daemon,
        checkout_head=checkout_head,
        remote_head=remote_head,
        stale=stale,
        determinable=determinable,
        mutation_safe=bool(determinable and not stale),
        reasons=tuple(reasons),
    )
 # ---------------------------------------------------------------------------
 # Snapshot assembly
 # ---------------------------------------------------------------------------
 def _default_host() -> str:
    registry = load_registry()
    if not registry.projects:
        return ""
    raw = registry.projects[0].remote_host
    parts = urlsplit(raw.strip())
    return parts.netloc or raw.strip().rstrip("/")
 def _aggregate(
    probes: tuple[DependencyProbe, ...],
 ) -> tuple[str, bool, bool, tuple[str, ...]]:
    """Fold probe results into overall status and readiness.
    Required probes drive readiness; optional probes can only degrade status.
    A probe that did not run leaves readiness incomplete rather than passing.
    """
    reasons: list[str] = []
    required = [probe for probe in probes if probe.required]
    unrun_required = [probe for probe in required if not probe.ran]
    failed_required = [probe for probe in required if probe.ran and not probe.healthy]
    failed_optional = [
        probe
        for probe in probes
        if not probe.required and probe.ran and not probe.healthy
    ]
    for probe in unrun_required:
        reasons.append(
            f"required dependency '{probe.name}' was not probed: {probe.detail}"
        )
    for probe in failed_required:
        reasons.append(
            f"required dependency '{probe.name}' is {probe.status}: {probe.detail}"
        )
    for probe in failed_optional:
        reasons.append(
            f"optional dependency '{probe.name}' is {probe.status}: {probe.detail}"
        )
    readiness_complete = not unrun_required
    ready = readiness_complete and not failed_required
    if any(probe.status == STATUS_DOWN for probe in failed_required):
        status = STATUS_DOWN
    elif failed_required or failed_optional or unrun_required:
        status = STATUS_DEGRADED
    else:
        status = STATUS_OK
    return status, ready, readiness_complete, tuple(reasons)
 def load_system_health(
    *,
    deep: bool = False,
    host: str | None = None,
    probes: tuple[DependencyProbe, ...] | None = None,
    daemon_head: str | None = None,
    use_cache: bool = True,
 ) -> SystemHealthSnapshot:
    """Assemble the read-only system-health snapshot.
    ``deep=True`` adds the network probe against Gitea; its result is cached for
    a short TTL so repeated dashboard polls do not amplify into remote load.
    """
    repo = _repo_root()
    probe_errors: list[str] = []
    if probes is None:
        collected: list[DependencyProbe] = []
        for probe_fn in (
            lambda: probe_control_plane_db(),
            lambda: probe_repository(repo),
        ):
            try:
                collected.append(probe_fn())
            except Exception as exc:  # noqa: BLE001 — a probe must not 500 the API
                probe_errors.append(redact(f"probe raised: {exc}"))
        resolved_host = host if host is not None else _default_host()
        if deep and not _offline():
            collected.append(_cached_gitea_probe(resolved_host, use_cache=use_cache))
        else:
            collected.append(_skipped_gitea(resolved_host))
        probes = tuple(collected)
    status, ready, readiness_complete, reasons = _aggregate(probes)
    stale = assess_stale_runtime(repo, daemon_head=daemon_head)
    if stale.stale:
        if status == STATUS_OK:
            status = STATUS_DEGRADED
        reasons = reasons + (
            "runtime is stale relative to its remote-tracking commit",
        )
    db_probe = next((p for p in probes if p.name == "control_plane_db"), None)
    schema_version = None
    if db_probe and db_probe.metadata:
        schema_version = db_probe.metadata.get("schema_version")
    return SystemHealthSnapshot(
        status=status,
        ready=ready,
        readiness_complete=readiness_complete,
        readiness_reasons=reasons,
        service=SERVICE_NAME,
        mode="read-only",
        version=_load_version(repo, schema_version=schema_version),
        started_at=_STARTED_AT.isoformat(),
        uptime_seconds=round(time.monotonic() - _STARTED_MONOTONIC, 3),
        timestamp=datetime.now(timezone.utc).isoformat(),
        deep_probes_requested=deep,
        dependencies=probes,
        mcp_namespaces=namespace_summaries(),
        stale_runtime=stale,
        probe_errors=tuple(probe_errors),
    )
 def _cached_gitea_probe(host: str, *, use_cache: bool = True) -> DependencyProbe:
    ttl = _deep_probe_ttl()
    now = time.monotonic()
    if use_cache and ttl > 0:
        cached = _deep_cache.get(host)
        if cached and (now - cached[0]) < ttl:
            return cached[1]
    probe = probe_gitea(host)
    if use_cache and ttl > 0:
        _deep_cache[host] = (now, probe)
    return probe
 def clear_probe_cache() -> None:
    """Drop cached deep-probe results (tests and operator-forced refresh)."""
    _deep_cache.clear()
 def probe_to_dict(probe: DependencyProbe) -> dict[str, Any]:
    return {
        "name": probe.name,
        "kind": probe.kind,
        "status": probe.status,
        "detail": probe.detail,
        "required": probe.required,
        "healthy": probe.healthy,
        "latency_ms": probe.latency_ms,
        "metadata": dict(probe.metadata or {}),
    }
 def snapshot_to_dict(snapshot: SystemHealthSnapshot) -> dict[str, Any]:
    return {
        "status": snapshot.status,
        "service": snapshot.service,
        "mode": snapshot.mode,
        "api": API_PATH,
        "timestamp": snapshot.timestamp,
        "readiness": {
            "ready": snapshot.ready,
            "complete": snapshot.readiness_complete,
            "reasons": list(snapshot.readiness_reasons),
        },
        "version": {
            "git_sha": snapshot.version.git_sha,
            "git_describe": snapshot.version.git_describe,
            "control_plane_schema_version": (
                snapshot.version.control_plane_schema_version
            ),
            "python_version": snapshot.version.python_version,
            "known": snapshot.version.known,
        },
        "process": {
            "started_at": snapshot.started_at,
            "uptime_seconds": snapshot.uptime_seconds,
        },
        "deep_probes_requested": snapshot.deep_probes_requested,
        "dependencies": [probe_to_dict(probe) for probe in snapshot.dependencies],
        "mcp_namespaces": [dict(row) for row in snapshot.mcp_namespaces],
        "stale_runtime": {
            "daemon_head": snapshot.stale_runtime.daemon_head,
            "checkout_head": snapshot.stale_runtime.checkout_head,
            "remote_head": snapshot.stale_runtime.remote_head,
            "stale": snapshot.stale_runtime.stale,
            "determinable": snapshot.stale_runtime.determinable,
            "mutation_safe": snapshot.stale_runtime.mutation_safe,
            "reasons": list(snapshot.stale_runtime.reasons),
        },
        "probe_errors": list(snapshot.probe_errors),
    }
@@ -1,906 +0,0 @@
 """Workflow-event and conversation timeline model (#637, Phase 1).
 Operators cannot browse a unified timeline of workflow events, decisions,
 tool calls, and handoffs: the evidence is scattered across control-plane
 events, Gitea canonical handoff comments, and local logs. This module defines
 one durable, versioned event schema and per-source adapters that normalise
 those scattered records into a single ``WorkflowEvent`` stream, plus a
 read-only query layer (filter by issue / PR / session, stable ordering,
 pagination) that the ``/api/v1/timeline`` route serves.
 Design rules honoured here:
 - **Read-only.** Sources are read; nothing is mutated. The control-plane
  database is opened through a ``mode=ro`` URI so a missing or unwritable DB
  degrades to a reason instead of creating directories or running migrations.
 - **Fail-soft per source.** An unavailable source degrades to a status with a
  reason rather than raising, and a source that could not run is never
  rendered as an empty-and-healthy timeline.
 - **Answerable filters only.** Each source declares which filter dimensions it
  can actually answer. A filter dimension no source that ran can carry is
  refused with an explicit reason rather than silently matching nothing: an
  empty page from an unanswerable filter reads to an operator as "no such
  activity", which is a different — and false — statement.
 - **Redaction at the boundary, fail closed.** Every free-text field (event
  messages, redacted tool arguments, decision/proof text) is run through the
  console redaction policy before it leaves this module, and *before* any
  structured value is derived from it — evidence references are extracted from
  redacted text, then independently revalidated before serialization. An
  unredactable value becomes the placeholder, and a value that cannot be proven
  safe is dropped — an unredacted payload is never emitted, and a generation
  error never drops raw data to a caller or a log.
 - **Stable ordering.** Events sort by ``(timestamp, source_rank, event_key)``
  with a deterministic tiebreak, so pagination is stable across calls and
  events with equal or missing timestamps keep a fixed order.
 Non-goals (from the issue): no full chat replay, no mutation of historical
 events, no unredacted tool-argument storage.
 """
 from __future__ import annotations
 import re
 import sqlite3
 from dataclasses import dataclass, replace
 from datetime import datetime, timezone
 from typing import Any, Callable, Iterable
 import control_plane_db
 from webui import console_redaction
 # The schema is versioned so consumers can branch on shape. Bump on any
 # breaking change to WorkflowEvent's serialized form.
 TIMELINE_SCHEMA_VERSION = 1
 # Known event sources and their deterministic ordering rank. When two events
 # carry the same timestamp, the source rank breaks the tie before the
 # per-source event key, so a control-plane event and a handoff comment minted
 # in the same second always sort in a fixed order.
 SOURCE_CONTROL_PLANE = "control_plane"
 SOURCE_GITEA_HANDOFF = "gitea_handoff"
 _SOURCE_RANK = {
    SOURCE_CONTROL_PLANE: 0,
    SOURCE_GITEA_HANDOFF: 1,
 }
 # The filter dimensions the query layer accepts.
 FILTER_ISSUE = "issue"
 FILTER_PR = "pr"
 FILTER_SESSION = "session"
 # Which dimensions each source can actually answer. This is a property of the
 # underlying records, not of the query code: the control-plane ``events`` table
 # is (event_id, work_item_id, event_type, message, created_at) and carries no
 # session identity at all, so no control-plane event can ever match a session
 # filter. A CTH handoff comment can declare its session as a field, so the
 # handoff source answers all three. Filtering on a dimension the surviving
 # sources cannot carry is refused in ``load_timeline`` rather than answered
 # with an empty page.
 _SOURCE_FILTER_SUPPORT: dict[str, tuple[str, ...]] = {
    SOURCE_CONTROL_PLANE: (FILTER_ISSUE, FILTER_PR),
    SOURCE_GITEA_HANDOFF: (FILTER_ISSUE, FILTER_PR, FILTER_SESSION),
 }
 # Why a source cannot answer a dimension, for the refusal reason an operator reads.
 _SOURCE_FILTER_LIMITS: dict[tuple[str, str], str] = {
    (SOURCE_CONTROL_PLANE, FILTER_SESSION): (
        "control-plane events carry no session identity "
        "(the events table has no session column)"
    ),
 }
 # A timestamp far in the future so events with no parseable timestamp sort
 # last (after everything real) instead of first, without raising.
 _MISSING_TS_SORT = "9999-12-31T23:59:59Z"
 def _parse_ts(value: str | None) -> str | None:
    """Normalise a timestamp to ``...Z`` UTC, or None when unparseable."""
    if not value:
        return None
    text = str(value).strip()
    if not text:
        return None
    candidate = text[:-1] + "+00:00" if text.endswith("Z") else text
    try:
        parsed = datetime.fromisoformat(candidate)
    except ValueError:
        return None
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=timezone.utc)
    return parsed.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")
 def _redact(value: Any) -> Any:
    """Redact a single free-text field, failing closed to the placeholder."""
    if value is None:
        return None
    return console_redaction.redact_text(str(value))
@dataclass(frozen=True)
 class WorkflowEvent:
    """One normalised timeline event.
    Every field is optional except ``source``/``event_type``/``event_key``
    because sources carry different subsets. The class is frozen so an adapted
    event is an immutable record; a consumer that needs a variant builds a new
    one rather than mutating history.
    """
    source: str
    event_type: str
    event_key: str
    timestamp: str | None = None
    actor: str | None = None
    role: str | None = None
    issue_number: int | None = None
    pr_number: int | None = None
    session_id: str | None = None
    tool_name: str | None = None
    decision: str | None = None
    message: str | None = None
    correlation_id: str | None = None
    evidence_refs: tuple[str, ...] = ()
    sensitive: bool = False
    def sort_key(self) -> tuple[str, int, str]:
        return (
            self.timestamp or _MISSING_TS_SORT,
            _SOURCE_RANK.get(self.source, 99),
            self.event_key,
        )
    def to_dict(self) -> dict[str, Any]:
        return {
            "source": self.source,
            "event_type": self.event_type,
            "event_key": self.event_key,
            "timestamp": self.timestamp,
            "actor": self.actor,
            "role": self.role,
            "issue_number": self.issue_number,
            "pr_number": self.pr_number,
            "session_id": self.session_id,
            "tool_name": self.tool_name,
            "decision": self.decision,
            "message": self.message,
            "correlation_id": self.correlation_id,
            "evidence_refs": list(self.evidence_refs),
            "sensitive": self.sensitive,
        }
 # --------------------------------------------------------------------------- #
 # Adapters — pure functions from a source's raw records to WorkflowEvents.     #
 # Each is total: a malformed record is skipped, never raised on.               #
 # --------------------------------------------------------------------------- #
 # Event types whose payload is treated as sensitive and always redaction-hard
 # (they can carry lease/session provenance or tool arguments).
 _SENSITIVE_EVENT_HINTS = ("lease", "capability", "token", "auth", "secret")
 # Reference tokens (issue/PR/comment ids) and SHAs parsed out of proof text.
 _EVIDENCE_REF_RE = re.compile(r"(?:#|PR\s*#?|issue\s*#?|comment\s*#?)(\d+)", re.IGNORECASE)
 # A commit reference is only recognised when the text *declares* it as one.
 # A bare lowercase hex run is not evidence of anything: at 40 characters it is
 # exactly the shape of a Gitea personal access token, and at 7 it also matches
 # ordinary words such as "defaced". Requiring an anchoring keyword keeps real
 # references ("commit abc1234", "at head a209756...", "base caaae9b6") usable
 # while refusing to lift an undeclared secret-shaped run out of free text.
 _SHA_RE = re.compile(
    r"(?i:\b(?:commit|sha|head|base|parent|revision|rev|merge[- ]base)\b[\s:=@#]*)"
    r"([0-9a-f]{7,40})\b"
 )
 # Shapes a serialized evidence reference is allowed to take. Anything else is
 # dropped rather than emitted.
 _REF_ISSUE_SHAPE = re.compile(r"^#[0-9]{1,9}$")
 _REF_SHA_SHAPE = re.compile(r"^[0-9a-f]{7,40}$")
 # A long undelimited hex run with no declaring context is treated as credential
 # material wherever it appears, never as an identifier.
 _BARE_SECRET_SHAPE = re.compile(r"^[0-9a-f]{32,}$")
 # An event type reads like an identifier, but a stored one is externally
 # influenced: any producer that writes the control-plane ``events`` table
 # chooses the string. It reaches ``to_dict`` verbatim, so it is validated here
 # rather than trusted because of where it came from.
 _CP_EVENT_TYPE_SHAPE = re.compile(r"^[A-Za-z][A-Za-z0-9._:+-]{0,63}$")
 # Emitted in place of a value that cannot be proven safe. Deliberately not a
 # plausible workflow type: an unsafe value is refused, never quietly rewritten
 # into a different valid-looking one that would misdescribe the record.
 UNSAFE_EVENT_TYPE = "unsafe:redacted"
 # Emitted for a CTH heading that is not a declared member of ``CTH_TYPES``. The
 # contract is enforced on write (``format_cth_body``) and on assess; the read
 # path the timeline uses enforces it too rather than assuming it was.
 UNKNOWN_HANDOFF_EVENT_TYPE = "handoff:unrecognized"
 # A source record id is a plain integer in both sources it comes from: the
 # control-plane ``events`` primary key and a Gitea comment id. ``event_key`` is
 # serialized verbatim and is the pagination tiebreak, so anything else is
 # refused rather than interpolated into it.
 _RECORD_ID_SHAPE = re.compile(r"^[0-9]{1,19}$")
 def _kind_to_numbers(kind: str | None, number: int | None) -> tuple[int | None, int | None]:
    """Map a control-plane work-item (kind, number) to (issue_no, pr_no)."""
    if number is None:
        return (None, None)
    if kind == "pr":
        return (None, int(number))
    if kind == "issue":
        return (int(number), None)
    return (None, None)
 def _correlation_for(kind: str | None, number: int | None) -> str | None:
    if number is None or kind not in ("issue", "pr"):
        return None
    return f"{kind}#{number}"
 def _extract_evidence_refs(*texts: str | None) -> tuple[str, ...]:
    """Extract issue/PR and declared-commit references from **redacted** text.
    Callers must pass text that has already been through :func:`_redact`; this
    function derives a structured field from its input, so extracting ahead of
    redaction would republish whatever redaction was about to remove. Every
    reference is revalidated by :func:`_validated_evidence_refs` before it is
    serialized.
    """
    refs: list[str] = []
    for text in texts:
        if not text:
            continue
        for match in _EVIDENCE_REF_RE.finditer(text):
            token = f"#{match.group(1)}"
            if token not in refs:
                refs.append(token)
        for match in _SHA_RE.finditer(text):
            token = match.group(1)
            if token not in refs:
                refs.append(token)
    return tuple(refs)
 def _validated_evidence_refs(refs: Iterable[str]) -> tuple[tuple[str, ...], bool]:
    """Independently revalidate references immediately before serialization.
    Extraction is not trusted on its own. A reference survives only when it has
    a known reference shape and is unchanged by a second redaction pass — a
    value the redaction policy would alter is credential material that must not
    be emitted as a structured field. A full 40-character SHA stays usable
    because extraction only accepts a hex run the source text explicitly
    declared as a commit. Returns ``(safe_refs, dropped_any)``; ``dropped_any``
    marks the event sensitive so the drop is visible rather than silent.
    """
    safe: list[str] = []
    dropped = False
    for ref in refs or ():
        try:
            token = str(ref).strip()
            if not token:
                continue
            recognised = bool(_REF_ISSUE_SHAPE.match(token) or _REF_SHA_SHAPE.match(token))
            if not recognised:
                dropped = True
                continue
            if _redact(token) != token:
                dropped = True
                continue
            if token not in safe:
                safe.append(token)
        except Exception:
            # Fail closed: a reference that cannot be proven safe is dropped.
            dropped = True
            continue
    return (tuple(safe), dropped)
 def _safe_session_id(value: Any) -> str | None:
    """Return a session identifier only when it is safe to emit.
    The value is authoritative source data — a session the record names for
    itself — but it is still free text. It is dropped when redaction alters it
    or when it is a bare secret-shaped hex run, so a credential parked in a
    session field can never reach the payload or be echoed back by a filter.
    """
    if value is None:
        return None
    text = str(value).strip()
    if not text:
        return None
    if _BARE_SECRET_SHAPE.match(text):
        return None
    return text if _redact(text) == text else None
 def _safe_record_id(value: Any) -> str | None:
    """Return a source record id only when it is a plain numeric identifier.
    ``event_key`` is serialized verbatim and is the deterministic pagination
    tiebreak, so an id is interpolated into it only when it has the shape both
    real sources actually produce. A record whose identity cannot be trusted is
    refused by the caller rather than keyed on.
    """
    if value is None or isinstance(value, bool):
        return None
    if isinstance(value, int):
        return str(value)
    text = str(value).strip()
    return text if _RECORD_ID_SHAPE.match(text) else None
 def _safe_cp_event_type(value: Any) -> tuple[str, bool]:
    """Validate a stored control-plane event type. Returns ``(type, unsafe)``.
    The stored value is externally influenced — whichever producer wrote the
    ``events`` row chose the string — and ``to_dict`` serializes it verbatim, so
    it passes a boundary of its own instead of relying on the one ``message``
    passes. A value survives only when it is an ordinary identifier, is not a
    bare secret-shaped hex run, and is unchanged by a redaction pass. Anything
    else fails closed to :data:`UNSAFE_EVENT_TYPE`: the record stays visible as
    an audit entry, but the value itself is never republished — not verbatim,
    not partially sanitized, and not rewritten into some other valid-looking
    type that would misdescribe what happened.
    """
    text = ("" if value is None else str(value)).strip()
    if not text:
        return ("", False)
    if _BARE_SECRET_SHAPE.match(text):
        return (UNSAFE_EVENT_TYPE, True)
    if not _CP_EVENT_TYPE_SHAPE.match(text):
        return (UNSAFE_EVENT_TYPE, True)
    if _redact(text) != text:
        return (UNSAFE_EVENT_TYPE, True)
    return (text, False)
 def _safe_echo(value: Any) -> Any:
    """Guard a scalar that is echoed back rather than derived from a record.
    Query scope and filter values are caller-supplied and are reflected in the
    response so an operator can see what was asked. Reflection is still
    emission: a value redaction would alter, or a bare secret-shaped hex run, is
    replaced by the placeholder instead of being echoed verbatim. Ordinary
    scope and filter values pass through untouched.
    """
    if value is None or isinstance(value, (int, bool)):
        return value
    text = str(value)
    if _BARE_SECRET_SHAPE.match(text.strip()):
        return console_redaction.REDACTED
    return _redact(text)
 def adapt_cp_events(rows: Iterable[dict[str, Any]]) -> list[WorkflowEvent]:
    """Adapt control-plane ``events`` rows (joined to work_items) into events.
    Each row is expected to carry ``event_id``, ``event_type``, ``message``,
    ``created_at`` and the joined work-item ``kind``/``number``. Rows missing
    an id or type are skipped so a partially written table never raises.
    """
    events: list[WorkflowEvent] = []
    for row in rows or []:
        try:
            event_id = _safe_record_id(row.get("event_id"))
            raw_event_type = (row.get("event_type") or "").strip()
            if event_id is None or not raw_event_type:
                continue
            # The stored type is source data, not a trusted constant: validate
            # it before it is serialized, exactly as `message` below is redacted
            # before it is serialized.
            event_type, event_type_unsafe = _safe_cp_event_type(raw_event_type)
            kind = row.get("kind")
            number = row.get("number")
            issue_no, pr_no = _kind_to_numbers(kind, number)
            sensitive = event_type_unsafe or any(
                hint in raw_event_type.lower() for hint in _SENSITIVE_EVENT_HINTS
            )
            events.append(
                WorkflowEvent(
                    source=SOURCE_CONTROL_PLANE,
                    event_type=event_type,
                    event_key=f"cp:{event_id}",
                    timestamp=_parse_ts(row.get("created_at")),
                    issue_number=issue_no,
                    pr_number=pr_no,
                    # No session_id: the control-plane events table is
                    # (event_id, work_item_id, event_type, message, created_at)
                    # and records no session. Inventing one from the work item
                    # or the message text would be a guess, so this source
                    # declares the session dimension unsupported instead
                    # (_SOURCE_FILTER_SUPPORT) and the query layer refuses a
                    # session filter it cannot honestly answer.
                    message=_redact(row.get("message")),
                    correlation_id=_correlation_for(kind, number),
                    sensitive=sensitive,
                )
            )
        except Exception:
            # A single malformed row must not sink the whole adaptation.
            continue
    return events
 def adapt_cth_comments(
    comments: Iterable[dict[str, Any]],
    *,
    kind: str,
    number: int,
 ) -> list[WorkflowEvent]:
    """Adapt Gitea Canonical Thread Handoff (CTH) comments into events.
    Only comments that parse as a CTH (``canonical_thread_handoff.parse_cth_comment``)
    become events; ordinary comments are ignored. ``kind``/``number`` scope the
    events to the issue or PR the comments belong to.
    """
    # Imported lazily so this module has no import-time dependency on the
    # handoff parser when only the control-plane adapter is used.
    from canonical_thread_handoff import is_known_cth_type, parse_cth_comment
    # ``kind``/``number`` are interpolated into event_key and correlation_id, so
    # they are normalised once here. A scope this adapter cannot express is
    # refused outright rather than serialized into an identifier.
    kind = (kind or "").strip().lower()
    if kind not in ("issue", "pr"):
        return []
    try:
        number = int(number)
    except (TypeError, ValueError):
        return []
    issue_no, pr_no = _kind_to_numbers(kind, number)
    correlation = _correlation_for(kind, number)
    events: list[WorkflowEvent] = []
    for comment in comments or []:
        try:
            body = comment.get("body") or ""
            parsed = parse_cth_comment(body)
            if not parsed:
                continue
            fields = parsed.get("fields") or {}
            cth_type = parsed.get("cth_type") or ""
            comment_id = _safe_record_id(comment.get("id"))
            if comment_id is None:
                continue
            # The CTH heading is free text: the parser accepts whatever follows
            # "## CTH:", and only the write and assess paths check it against
            # the contract. Check it here too — an unrecognised heading is
            # reported as such rather than serialized into event_type, so
            # arbitrary, malformed, or secret-shaped heading content has no way
            # through. Declared types are preserved exactly.
            cth_type_known = is_known_cth_type(cth_type)
            # Redaction runs first, and every derived value is taken from the
            # redacted text — deriving evidence refs from the raw proof would
            # re-emit exactly what redaction was about to remove.
            decision = _redact(fields.get("decision"))
            proof = _redact(fields.get("proof"))
            next_action = _redact(fields.get("next action"))
            refs, refs_dropped = _validated_evidence_refs(
                _extract_evidence_refs(proof, decision)
            )
            events.append(
                WorkflowEvent(
                    source=SOURCE_GITEA_HANDOFF,
                    event_type=(
                        f"handoff:{cth_type.strip()}"
                        if cth_type_known
                        else UNKNOWN_HANDOFF_EVENT_TYPE
                    ),
                    event_key=f"cth:{kind}:{number}:{comment_id}",
                    timestamp=_parse_ts(comment.get("created_at")),
                    actor=_redact((comment.get("user") or {}).get("login")),
                    role=_redact(fields.get("next owner")),
                    issue_number=issue_no,
                    pr_number=pr_no,
                    # A CTH names its own session when the producer records one;
                    # it is read from that declared field, never inferred from
                    # unrelated text.
                    session_id=_safe_session_id(fields.get("session")),
                    decision=decision,
                    message=next_action or _redact(fields.get("status")),
                    correlation_id=correlation,
                    evidence_refs=refs,
                    sensitive=refs_dropped or not cth_type_known,
                )
            )
        except Exception:
            continue
    return events
 # --------------------------------------------------------------------------- #
 # Read-only control-plane event source.                                       #
 # --------------------------------------------------------------------------- #
 _CP_EVENTS_QUERY = """
 SELECT e.event_id   AS event_id,
       e.event_type AS event_type,
       e.message    AS message,
       e.created_at AS created_at,
       w.kind       AS kind,
       w.number     AS number
 FROM events e
 JOIN work_items w ON e.work_item_id = w.work_item_id
 WHERE w.remote = ? AND w.org = ? AND w.repo = ?
 """
@dataclass(frozen=True)
 class SourceStatus:
    """Fail-soft status for one timeline source.
    ``supported_filters`` states which filter dimensions this source's records
    can carry; ``unsupported_filters`` names the requested dimensions it cannot,
    so an operator can see *why* a source contributed nothing rather than being
    left to read an empty list as an absence of activity.
    """
    name: str
    ok: bool
    reason: str | None = None
    count: int = 0
    supported_filters: tuple[str, ...] = ()
    unsupported_filters: tuple[str, ...] = ()
    def to_dict(self) -> dict[str, Any]:
        return {
            "name": self.name,
            "ok": self.ok,
            "reason": self.reason,
            "count": self.count,
            "supported_filters": list(self.supported_filters),
            "unsupported_filters": list(self.unsupported_filters),
        }
 def _cp_status(*, ok: bool, reason: str | None = None, count: int = 0) -> SourceStatus:
    return SourceStatus(
        SOURCE_CONTROL_PLANE,
        ok=ok,
        # A failure reason is serialized like any other field and is often an
        # exception string carrying a path or a transport error, so it crosses
        # the redaction boundary too. Static reasons pass through unchanged.
        reason=_redact(reason),
        count=count,
        supported_filters=_SOURCE_FILTER_SUPPORT[SOURCE_CONTROL_PLANE],
    )
 def _handoff_status(*, ok: bool, reason: str | None = None, count: int = 0) -> SourceStatus:
    return SourceStatus(
        SOURCE_GITEA_HANDOFF,
        ok=ok,
        # Same boundary as the control-plane status: this reason can quote an
        # error raised by a live authenticated fetch.
        reason=_redact(reason),
        count=count,
        supported_filters=_SOURCE_FILTER_SUPPORT[SOURCE_GITEA_HANDOFF],
    )
 def read_cp_events(
    *,
    remote: str,
    org: str,
    repo: str,
    db_path: str | None = None,
 ) -> tuple[list[WorkflowEvent], SourceStatus]:
    """Read scoped control-plane events read-only. Never creates the DB.
    Opens the SQLite file through a ``mode=ro`` URI: a health/timeline read
    must never create directories or run the schema migration that
    ``ControlPlaneDB()`` performs on construction. A missing or unreadable DB
    degrades to a status with a reason.
    """
    path = (db_path or control_plane_db.default_db_path()).strip()
    conn: sqlite3.Connection | None = None
    try:
        conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True)
        conn.row_factory = sqlite3.Row
        cursor = conn.execute(_CP_EVENTS_QUERY, (remote, org, repo))
        rows = [dict(r) for r in cursor.fetchall()]
    except sqlite3.OperationalError as exc:
        return ([], _cp_status(ok=False, reason=f"control-plane DB unavailable: {exc}"))
    except sqlite3.Error as exc:
        return ([], _cp_status(ok=False, reason=f"control-plane read failed: {exc}"))
    finally:
        if conn is not None:
            conn.close()
    events = adapt_cp_events(rows)
    return (events, _cp_status(ok=True, count=len(events)))
 # --------------------------------------------------------------------------- #
 # Filter, sort, paginate.                                                     #
 # --------------------------------------------------------------------------- #
 def filter_events(
    events: Iterable[WorkflowEvent],
    *,
    issue: int | None = None,
    pr: int | None = None,
    session: str | None = None,
 ) -> list[WorkflowEvent]:
    """Filter events by issue number, PR number, and/or session id.
    Filters are conjunctive. A filter that names a dimension an event does not
    carry excludes that event (an issue filter excludes PR-only events).
    """
    out: list[WorkflowEvent] = []
    for ev in events:
        if issue is not None and ev.issue_number != issue:
            continue
        if pr is not None and ev.pr_number != pr:
            continue
        if session is not None and ev.session_id != session:
            continue
        out.append(ev)
    return out
 def sort_events(events: Iterable[WorkflowEvent]) -> list[WorkflowEvent]:
    """Return events in stable timeline order (ascending)."""
    return sorted(events, key=lambda ev: ev.sort_key())
@dataclass(frozen=True)
 class TimelinePage:
    """One page of the sorted, filtered timeline."""
    events: tuple[WorkflowEvent, ...]
    total: int
    limit: int
    offset: int
    @property
    def next_offset(self) -> int | None:
        nxt = self.offset + len(self.events)
        return nxt if nxt < self.total else None
    def to_dict(self) -> dict[str, Any]:
        return {
            "events": [ev.to_dict() for ev in self.events],
            "pagination": {
                "total": self.total,
                "limit": self.limit,
                "offset": self.offset,
                "returned": len(self.events),
                "next_offset": self.next_offset,
                "has_more": self.next_offset is not None,
            },
        }
 _MAX_LIMIT = 500
 _DEFAULT_LIMIT = 50
 def _coerce_bounds(limit: int | None, offset: int | None) -> tuple[int, int]:
    try:
        lim = int(limit) if limit is not None else _DEFAULT_LIMIT
    except (TypeError, ValueError):
        lim = _DEFAULT_LIMIT
    try:
        off = int(offset) if offset is not None else 0
    except (TypeError, ValueError):
        off = 0
    lim = max(1, min(lim, _MAX_LIMIT))
    off = max(0, off)
    return (lim, off)
 def paginate(events: list[WorkflowEvent], *, limit: int | None, offset: int | None) -> TimelinePage:
    lim, off = _coerce_bounds(limit, offset)
    window = events[off : off + lim]
    return TimelinePage(events=tuple(window), total=len(events), limit=lim, offset=off)
 # --------------------------------------------------------------------------- #
 # Composition — load_timeline aggregates all sources, fail-soft.              #
 # --------------------------------------------------------------------------- #
 # A comment source is a callable that, given (kind, number), returns the raw
 # Gitea comment list for that issue/PR. The route supplies a live fail-soft
 # fetcher; tests supply a fixture. When None, the handoff source is reported as
 # not-run (never silently empty-and-healthy).
 CommentSource = Callable[[str, int], list[dict[str, Any]]]
@dataclass(frozen=True)
 class TimelineSnapshot:
    """One answered timeline query.
    ``ok`` is False when the query could not be answered as asked — currently
    when a requested filter dimension no surviving source can carry was
    supplied. The page is then empty *and* the snapshot says so, because an
    ``ok`` empty page is a claim that no such activity exists.
    """
    schema_version: int
    remote: str
    org: str
    repo: str
    filters: dict[str, Any]
    page: TimelinePage
    sources: tuple[SourceStatus, ...]
    ok: bool = True
    error: dict[str, Any] | None = None
    def to_dict(self) -> dict[str, Any]:
        return {
            "ok": self.ok,
            "error": self.error,
            "schema_version": self.schema_version,
            # Scope and filters are echoed caller input, not derived record
            # data. Reflecting a value is still emitting it, so both cross the
            # same boundary; ordinary scope and filter values are unchanged.
            "scope": {
                "remote": _safe_echo(self.remote),
                "org": _safe_echo(self.org),
                "repo": _safe_echo(self.repo),
            },
            "filters": {key: _safe_echo(value) for key, value in self.filters.items()},
            "sources": [s.to_dict() for s in self.sources],
            **self.page.to_dict(),
        }
 def _unanswerable_reasons(
    statuses: Iterable[SourceStatus], unanswerable: Iterable[str]
 ) -> list[dict[str, str]]:
    """Explain, per source, why each unanswerable dimension went unanswered."""
    out: list[dict[str, str]] = []
    for status in statuses:
        for dim in unanswerable:
            if dim not in status.supported_filters:
                reason = _SOURCE_FILTER_LIMITS.get(
                    (status.name, dim), f"this source's records carry no {dim} identity"
                )
            elif not status.ok:
                reason = (
                    f"this source can carry {dim} but did not run: "
                    f"{status.reason or 'unavailable'}"
                )
            else:
                continue
            out.append({"source": status.name, "filter": dim, "reason": reason})
    return out
 def load_timeline(
    *,
    remote: str,
    org: str,
    repo: str,
    issue: int | None = None,
    pr: int | None = None,
    session: str | None = None,
    limit: int | None = None,
    offset: int | None = None,
    db_path: str | None = None,
    comment_source: CommentSource | None = None,
 ) -> TimelineSnapshot:
    """Aggregate every timeline source into one filtered, paginated snapshot.
    Sources are read independently and fail soft: an unavailable source
    contributes a ``SourceStatus`` with ``ok=False`` and a reason, and never
    collapses the whole timeline. The handoff source only runs when a specific
    issue or PR is requested (a handoff comment belongs to one thread) and a
    ``comment_source`` is available; otherwise it is reported as ``not run``
    rather than as an empty-and-healthy source.
    A filter dimension that no surviving source can carry — a ``session``
    filter when the only source that ran is the control plane, whose events
    record no session — is refused with ``ok=False`` and a structured error
    instead of being answered with an empty page.
    """
    all_events: list[WorkflowEvent] = []
    statuses: list[SourceStatus] = []
    cp_events, cp_status = read_cp_events(remote=remote, org=org, repo=repo, db_path=db_path)
    all_events.extend(cp_events)
    statuses.append(cp_status)
    # Gitea handoff comments are thread-scoped: only fetch when the caller
    # narrowed to one issue or PR, and only when a source was provided.
    handoff_target: tuple[str, int] | None = None
    if pr is not None:
        handoff_target = ("pr", pr)
    elif issue is not None:
        handoff_target = ("issue", issue)
    if handoff_target is None:
        statuses.append(
            _handoff_status(
                ok=False,
                reason="not run: handoff comments are thread-scoped; filter by issue or pr to include them",
            )
        )
    elif comment_source is None:
        statuses.append(
            _handoff_status(
                ok=False,
                reason="not run: no comment source configured for this timeline read",
            )
        )
    else:
        kind, number = handoff_target
        try:
            comments = comment_source(kind, number) or []
            handoff_events = adapt_cth_comments(comments, kind=kind, number=number)
            all_events.extend(handoff_events)
            statuses.append(_handoff_status(ok=True, count=len(handoff_events)))
        except Exception as exc:  # fail soft: a fetch/parse error degrades this source only
            statuses.append(_handoff_status(ok=False, reason=f"handoff source failed: {exc}"))
    requested = tuple(
        name
        for name, value in ((FILTER_ISSUE, issue), (FILTER_PR, pr), (FILTER_SESSION, session))
        if value is not None
    )
    statuses = [
        replace(
            status,
            unsupported_filters=tuple(
                dim for dim in requested if dim not in status.supported_filters
            ),
        )
        for status in statuses
    ]
    filters = {"issue": issue, "pr": pr, "session": session}
    # A dimension is answerable only if a source that actually ran can carry it.
    # If none can, refuse: an empty page would assert "no such activity", which
    # is a claim this timeline is not in a position to make.
    answerable: set[str] = set()
    for status in statuses:
        if status.ok:
            answerable.update(status.supported_filters)
    unanswerable = tuple(dim for dim in requested if dim not in answerable)
    if unanswerable:
        return TimelineSnapshot(
            schema_version=TIMELINE_SCHEMA_VERSION,
            remote=remote,
            org=org,
            repo=repo,
            filters=filters,
            page=paginate([], limit=limit, offset=offset),
            sources=tuple(statuses),
            ok=False,
            error={
                "code": "filter_not_supported",
                "unsupported_filters": list(unanswerable),
                "detail": (
                    "no timeline source that ran can answer "
                    + ", ".join(f"'{dim}'" for dim in unanswerable)
                    + "; the result is refused rather than returned empty"
                ),
                "sources": _unanswerable_reasons(statuses, unanswerable),
            },
        )
    filtered = filter_events(all_events, issue=issue, pr=pr, session=session)
    ordered = sort_events(filtered)
    page = paginate(ordered, limit=limit, offset=offset)
    return TimelineSnapshot(
        schema_version=TIMELINE_SCHEMA_VERSION,
        remote=remote,
        org=org,
        repo=repo,
        filters=filters,
        page=page,
        sources=tuple(statuses),
    )
 def snapshot_to_dict(snapshot: TimelineSnapshot) -> dict[str, Any]:
    return snapshot.to_dict()
@@ -34,11 +34,7 @@ import subprocess
 from datetime import datetime, timezone
 from typing import Any
-from merged_cleanup_reconcile import (
+from merged_cleanup_reconcile import branch_worktree_folder, read_local_worktree_state
    branch_worktree_folder,
    is_head_ancestor_of_ref,
    read_local_worktree_state,
 )
 from reviewer_worktree import parse_dirty_tracked_files, REVIEW_WORKTREE_RE
 PROTECTED_BRANCHES = frozenset({"master", "main", "dev"})
@@ -71,14 +67,6 @@ REMOVABLE_CLASSES = frozenset(
    {CLASS_CLEAN_STALE_REMOVABLE, CLASS_DETACHED_REVIEW_LEFTOVER}
 )
 # Merged-PR linkage outcomes for issue worktrees (#858). Only ``LINKAGE_MERGED``
 # is ownership proof; every other outcome leaves the worktree protected.
 LINKAGE_MERGED = "merged_pr"
 LINKAGE_OPEN = "open_pr"
 LINKAGE_NONE = "no_owning_pr"
 LINKAGE_AMBIGUOUS = "ambiguous"
 LINKAGE_UNKNOWN = "unknown"
 _ISSUE_REF_RE = re.compile(r"issue-(\d+)", re.IGNORECASE)
 _ISSUE_BRANCH_PREFIXES = ("feat/", "fix/", "docs/", "chore/")
@@ -181,186 +169,6 @@ def is_ttl_expired(
    return (now_dt - last).total_seconds() > ttl_hours * 3600.0
 def build_pr_index(prs: list[dict[str, Any]] | None) -> dict[str, list[dict[str, Any]]]:
    """Index PR records by head branch for deterministic worktree linkage (#858).
    Accepts Gitea PR payloads (``head`` as a dict) and pre-flattened records
    (``head_branch``/``head_sha``). Records without a usable head branch or
    number are dropped rather than guessed at, so a branch is only ever linked
    to a PR the caller actually proved.
    """
    index: dict[str, list[dict[str, Any]]] = {}
    for pr in prs or []:
        head = pr.get("head")
        if isinstance(head, dict):
            head_branch = head.get("ref")
            head_sha = head.get("sha")
        else:
            head_branch = pr.get("head_branch") or (head if isinstance(head, str) else None)
            head_sha = pr.get("head_sha")
        number = pr.get("number")
        if not head_branch or number is None:
            continue
        try:
            pr_number = int(number)
        except (TypeError, ValueError):
            continue
        index.setdefault(str(head_branch).strip(), []).append(
            {
                "pr_number": pr_number,
                "head_branch": str(head_branch).strip(),
                "head_sha": head_sha,
                "merged": bool(pr.get("merged") or pr.get("merged_at")),
                "state": pr.get("state"),
            }
        )
    return index
 def resolve_owning_pr(
    *,
    branch: str | None,
    pr_index: dict[str, list[dict[str, Any]]] | None,
 ) -> dict[str, Any]:
    """Resolve the single PR that owns ``branch``, failing closed when unclear.
    Ownership is only ``LINKAGE_MERGED`` when exactly one PR claims the branch
    and that PR is merged. Several distinct PRs on one branch is a competing
    claim (``LINKAGE_AMBIGUOUS``), and a still-open owner is reported as
    ``LINKAGE_OPEN`` — both keep the worktree protected while still exposing
    the PR number the audit resolved.
    """
    if pr_index is None:
        return {
            "status": LINKAGE_UNKNOWN,
            "pr_number": None,
            "candidate_pr_numbers": [],
            "reasons": ["live PR state was not supplied; ownership unproven"],
        }
    branch_name = (branch or "").strip()
    if not branch_name:
        return {
            "status": LINKAGE_UNKNOWN,
            "pr_number": None,
            "candidate_pr_numbers": [],
            "reasons": ["worktree has no attached branch; ownership unproven"],
        }
    candidates = list(pr_index.get(branch_name) or [])
    numbers = sorted({c["pr_number"] for c in candidates})
    if not candidates:
        return {
            "status": LINKAGE_NONE,
            "pr_number": None,
            "candidate_pr_numbers": [],
            "reasons": [f"no PR claims branch '{branch_name}'"],
        }
    if len(numbers) > 1:
        return {
            "status": LINKAGE_AMBIGUOUS,
            "pr_number": None,
            "candidate_pr_numbers": numbers,
            "reasons": [
                f"branch '{branch_name}' is claimed by competing PRs {numbers}; "
                "ownership is ambiguous"
            ],
        }
    owner = candidates[0]
    pr_number = owner["pr_number"]
    if owner.get("head_branch") != branch_name:
        return {
            "status": LINKAGE_UNKNOWN,
            "pr_number": pr_number,
            "candidate_pr_numbers": numbers,
            "reasons": [
                f"PR #{pr_number} head branch '{owner.get('head_branch')}' does not "
                f"match worktree branch '{branch_name}'"
            ],
        }
    if not owner.get("merged"):
        return {
            "status": LINKAGE_OPEN,
            "pr_number": pr_number,
            "candidate_pr_numbers": numbers,
            "pr_head_sha": owner.get("head_sha"),
            "reasons": [f"owning PR #{pr_number} is not merged"],
        }
    return {
        "status": LINKAGE_MERGED,
        "pr_number": pr_number,
        "candidate_pr_numbers": numbers,
        "pr_head_sha": owner.get("head_sha"),
        "reasons": [],
    }
 def assess_merged_pr_worktree_cleanup(
    *,
    linkage: dict[str, Any] | None,
    head_sha: str | None,
    head_in_master: bool | None,
    is_dirty: bool,
    has_open_pr: bool,
    has_active_lease: bool,
    has_active_issue_lock: bool,
    is_protected: bool,
    has_live_session: bool = False,
 ) -> dict[str, Any]:
    """Decide whether a merged issue worktree satisfies the full cleanup policy.
    Every condition must be independently proven: conclusive merged-PR
    ownership, agreement between the worktree branch and the PR head branch,
    containment of the worktree head in authoritative master (which is what
    proves no unmerged commits remain), absence of any open/competing PR,
    lease, issue lock, or live session, a clean tree, and a worktree that is
    not the protected control checkout. Anything unknown blocks.
    """
    link = linkage or {
        "status": LINKAGE_UNKNOWN,
        "pr_number": None,
        "reasons": ["no linkage assessment supplied"],
    }
    status = link.get("status")
    reasons: list[str] = []
    if status != LINKAGE_MERGED:
        reasons.extend(
            link.get("reasons") or ["owning PR could not be conclusively identified"]
        )
    if is_protected:
        reasons.append("worktree is protected or the stable control checkout")
    if is_dirty:
        reasons.append("worktree has uncommitted changes")
    if has_open_pr:
        reasons.append("worktree branch has an open PR")
    if has_active_lease:
        reasons.append("worktree has an active lease")
    if has_active_issue_lock:
        reasons.append("an active issue lock references this branch")
    if has_live_session:
        reasons.append("a live process or session is using this worktree")
    if not head_sha:
        reasons.append("worktree head sha is unknown")
    if head_in_master is None:
        reasons.append("containment of the worktree head in master is unknown")
    elif not head_in_master:
        reasons.append(
            "worktree head is not contained in authoritative master "
            "(unmerged commits remain)"
        )
    proven = not reasons
    return {
        "linkage_status": status,
        "pr_number": link.get("pr_number"),
        "pr_head_sha": link.get("pr_head_sha"),
        "head_in_master": head_in_master,
        "proven": proven,
        "block_reasons": reasons,
    }
 def classify_worktree(
    *,
    workflow_type: str,
@@ -373,8 +181,6 @@ def classify_worktree(
    ttl_expired: bool = False,
    is_protected: bool = False,
    metadata_known: bool = True,
    merged_pr_cleanup: dict[str, Any] | None = None,
    has_live_session: bool = False,
 ) -> str:
    """Classify a worktree, safety-first: any preservation signal wins.
@@ -393,8 +199,6 @@ def classify_worktree(
        return CLASS_ACTIVE_ISSUE_WORK  # never auto-deleted (criterion 8)
    if has_active_issue_lock:
        return CLASS_ACTIVE_ISSUE_WORK
    if has_live_session:
        return CLASS_ACTIVE_ISSUE_WORK  # a live session still owns this tree
    if not metadata_known or workflow_type == WORKFLOW_UNKNOWN:
        return CLASS_UNSAFE_UNKNOWN  # never auto-deleted without proof
@@ -403,15 +207,7 @@ def classify_worktree(
        if is_detached or branch_gone:
            return CLASS_DETACHED_REVIEW_LEFTOVER
        return CLASS_CLEAN_STALE_REMOVABLE
-    if workflow_type == WORKFLOW_ISSUE_WORK:
+    # issue_work / conflict_fix: only removable once the TTL has expired.
        # #858: an issue worktree becomes removable only on authoritative
        # merged-PR evidence satisfying the whole cleanup policy. Age alone
        # never proves the branch landed, so TTL cannot qualify one by itself
        # — otherwise a worktree holding unmerged commits would be reclaimed.
        if (merged_pr_cleanup or {}).get("proven"):
            return CLASS_CLEAN_STALE_REMOVABLE
        return CLASS_ACTIVE_ISSUE_WORK
    # conflict_fix: only removable once the TTL has expired.
    if ttl_expired:
        return CLASS_CLEAN_STALE_REMOVABLE
    return CLASS_ACTIVE_ISSUE_WORK
@@ -604,20 +400,6 @@ def remove_worktree(project_root: str, path: str) -> dict[str, Any]:
    }
 def head_contained_in_ref(
    project_root: str, head_sha: str | None, ref: str | None
 ) -> bool | None:
    """Return True when ``head_sha`` is already contained in ``ref``.
    Shares :mod:`merged_cleanup_reconcile`'s ancestry check so the audit and
    the PR-scoped reconciler agree on what "already landed" means (#858).
    Returns None when containment cannot be determined, which fails closed.
    """
    if not head_sha or not ref:
        return None
    return is_head_ancestor_of_ref(project_root, head_sha, ref)
 def _is_under_branches(project_root: str, path: str) -> bool:
    branches_root = os.path.join(os.path.abspath(project_root), "branches")
    return os.path.abspath(path or "").startswith(branches_root + os.sep)
@@ -631,30 +413,16 @@ def audit_branches_directory(
    active_issue_branches: set[str] | None = None,
    now: datetime | str | None = None,
    ttl_hours: float = DEFAULT_TTL_HOURS,
    pr_index: dict[str, list[dict[str, Any]]] | None = None,
    leased_issue_numbers: set[int] | None = None,
    live_session_paths: set[str] | None = None,
    master_ref: str | None = None,
 ) -> dict[str, Any]:
    """Classify every session-owned worktree under ``branches/``.
    Read-only: shells out to git for discovery and dirty state, then applies
    the pure classifier. Returns per-worktree classifications, counts, the
    list of removable candidates, and the ``git worktree list`` proof.
    ``pr_index`` (see :func:`build_pr_index`) supplies the authoritative PR
    ownership used to link issue worktrees to their merged PR (#858).
    ``master_ref`` is the ref a worktree head must be contained in before it
    can be considered landed. Both are optional and their absence only ever
    fails closed: without them no issue worktree becomes removable.
    """
    open_pr_branches = open_pr_branches or set()
    leased_branches = leased_branches or set()
    active_issue_branches = active_issue_branches or set()
    leased_issue_numbers = leased_issue_numbers or set()
    live_session_paths = {
        os.path.abspath(p) for p in (live_session_paths or set()) if p
    }
    worktrees: list[dict[str, Any]] = []
    for entry in list_worktrees(project_root):
@@ -665,42 +433,12 @@ def audit_branches_directory(
        )
        dirty_state = read_worktree_dirty(path)
        is_dirty = bool(dirty_state.get("dirty"))
        head_sha = entry.get("head")
        linkage = resolve_owning_pr(branch=branch, pr_index=pr_index)
        metadata = build_worktree_metadata(
-            path=path,
+            path=path, branch=branch, head_sha=entry.get("head")
            branch=branch,
            head_sha=head_sha,
            pr_number=linkage.get("pr_number"),
        )
        has_open_pr = bool(branch) and branch in open_pr_branches
-        # A lease on issue N protects that issue's own work worktree. It must
+        has_active_lease = bool(branch) and branch in leased_branches
        # not incidentally protect a baseline/review scratch tree that merely
        # carries the same issue marker in its name, which would change the
        # classification of worktrees this policy does not own.
        has_active_lease = (bool(branch) and branch in leased_branches) or (
            metadata["workflow_type"] == WORKFLOW_ISSUE_WORK
            and metadata.get("issue_number") is not None
            and metadata["issue_number"] in leased_issue_numbers
        )
        has_active_lock = bool(branch) and branch in active_issue_branches
        has_live_session = bool(path) and os.path.abspath(path) in live_session_paths
        head_in_master = (
            head_contained_in_ref(project_root, head_sha, master_ref)
            if master_ref
            else None
        )
        merged_pr_cleanup = assess_merged_pr_worktree_cleanup(
            linkage=linkage,
            head_sha=head_sha,
            head_in_master=head_in_master,
            is_dirty=is_dirty,
            has_open_pr=has_open_pr,
            has_active_lease=has_active_lease,
            has_active_issue_lock=has_active_lock,
            is_protected=is_protected,
            has_live_session=has_live_session,
        )
        ttl_expired = is_ttl_expired(
            last_used_at=metadata.get("last_used_at"), now=now, ttl_hours=ttl_hours
        )
@@ -714,8 +452,6 @@ def audit_branches_directory(
            branch_gone=branch is None and not entry.get("detached"),
            ttl_expired=ttl_expired,
            is_protected=is_protected,
            merged_pr_cleanup=merged_pr_cleanup,
            has_live_session=has_live_session,
        )
        metadata["cleanup_eligibility"] = classification
        worktrees.append(
@@ -727,10 +463,7 @@ def audit_branches_directory(
                "has_open_pr": has_open_pr,
                "has_active_lease": has_active_lease,
                "has_active_issue_lock": has_active_lock,
                "has_live_session": has_live_session,
                "is_protected": is_protected,
                "merged_pr_linkage": linkage,
                "merged_pr_cleanup": merged_pr_cleanup,
                "classification": classification,
                "removable": is_removable(classification),
            }