diff --git a/allocator_service.py b/allocator_service.py index 40787ce..2b752b1 100644 --- a/allocator_service.py +++ b/allocator_service.py @@ -53,6 +53,8 @@ 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" @@ -78,6 +80,33 @@ VALID_ROLES = frozenset( {ROLE_AUTHOR, ROLE_REVIEWER, ROLE_MERGER, ROLE_RECONCILER, ROLE_CONTROLLER} ) +# Allocation modes (#840). +# role_scoped: only candidates whose expected role matches the caller role. +# cross_role: controller-owned generic queue selection — inspect full queue, +# rank/eligibility canonically, return one selection naming the required +# downstream role/profile. Controller routes; it does not perform mutations. +ALLOCATION_MODE_ROLE_SCOPED = "role_scoped" +ALLOCATION_MODE_CROSS_ROLE = "cross_role" +VALID_ALLOCATION_MODES = frozenset( + {ALLOCATION_MODE_ROLE_SCOPED, ALLOCATION_MODE_CROSS_ROLE} +) + +# Default execution-profile / MCP-namespace names for each role. +DEFAULT_ROLE_PROFILES: dict[str, str] = { + ROLE_AUTHOR: "prgs-author", + ROLE_REVIEWER: "prgs-reviewer", + ROLE_MERGER: "prgs-merger", + ROLE_RECONCILER: "prgs-reconciler", + ROLE_CONTROLLER: "prgs-controller", +} +DEFAULT_ROLE_NAMESPACES: dict[str, str] = { + ROLE_AUTHOR: "gitea-author", + ROLE_REVIEWER: "gitea-reviewer", + ROLE_MERGER: "gitea-merger", + ROLE_RECONCILER: "gitea-reconciler", + ROLE_CONTROLLER: "gitea-controller", +} + # Default action matrices by role (mutation gate will re-check). ROLE_ACTIONS: dict[str, tuple[tuple[str, ...], tuple[str, ...]]] = { ROLE_AUTHOR: ( @@ -103,6 +132,39 @@ 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.""" @@ -112,6 +174,7 @@ 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). @@ -131,6 +194,7 @@ 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 " @@ -144,6 +208,7 @@ 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, @@ -157,6 +222,51 @@ 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 @@ -259,6 +369,126 @@ def normalize_role(role: str | None, *, profile_name: str | None = None) -> str: ) +def resolve_allocation_mode( + role: str, + allocation_mode: str | None = None, +) -> str: + """Resolve allocation mode; controller defaults to cross_role (#840).""" + raw = (allocation_mode or "").strip().lower() + if raw: + if raw not in VALID_ALLOCATION_MODES: + raise ControlPlaneError( + f"unknown allocation_mode {allocation_mode!r}; expected one of " + f"{sorted(VALID_ALLOCATION_MODES)}" + ) + return raw + if role == ROLE_CONTROLLER: + return ALLOCATION_MODE_CROSS_ROLE + return ALLOCATION_MODE_ROLE_SCOPED + + +def required_profile_for_role( + role: str, + *, + profile_name: str | None = None, +) -> str: + """Map a required role to the canonical execution profile name.""" + role_norm = (role or "").strip().lower() + # Preserve remote/env prefix from the active profile when present + # (e.g. dadeschools-author → dadeschools-reviewer). + active = (profile_name or "").strip() + if active: + lower = active.lower() + for token in ("author", "reviewer", "merger", "reconciler", "controller"): + if lower.endswith(f"-{token}") or lower == token: + prefix = active[: -len(token)].rstrip("-") + if prefix: + return f"{prefix}-{role_norm}" + return role_norm + return DEFAULT_ROLE_PROFILES.get(role_norm, f"prgs-{role_norm}") + + +def required_namespace_for_role( + role: str, + *, + profile_name: str | None = None, +) -> str: + """Map a required role to the canonical MCP namespace name.""" + role_norm = (role or "").strip().lower() + profile = required_profile_for_role(role_norm, profile_name=profile_name) + # Namespace is typically gitea-; keep stable mapping when profile is + # non-prgs (still gitea- for isolation). + return DEFAULT_ROLE_NAMESPACES.get(role_norm, f"gitea-{role_norm}") + + +def selected_action_for_candidate(c: WorkCandidate, required_role: str) -> str: + """Canonical next action for the selected work under *required_role*.""" + role = (required_role or "").strip().lower() + if role == ROLE_AUTHOR: + if c.kind == "pr" and c.request_changes_current_head: + return "address_pr_change_requests" + if c.kind == "pr": + return "update_pr" + return "implement" + if role == ROLE_REVIEWER: + if c.approval_stale: + return "re_review" + return "review" + if role == ROLE_MERGER: + return "merge" + if role == ROLE_RECONCILER: + if c.approval_contaminated: + return "reconcile_contaminated_approval" + return "reconcile" + if role == ROLE_CONTROLLER: + return "diagnose" + return "process" + + +def build_selection_dict( + selected: WorkCandidate, + *, + active_role: str, + required_role: str, + profile_name: str | None = None, + allocation_mode: str, +) -> dict[str, Any]: + """Authoritative single selection payload for allocator results (#840).""" + action = selected_action_for_candidate(selected, required_role) + req_profile = required_profile_for_role( + required_role, profile_name=profile_name + ) + req_ns = required_namespace_for_role( + required_role, profile_name=profile_name + ) + return { + "kind": selected.kind, + "number": selected.number, + "title": selected.title, + "labels": list(selected.labels), + "head_sha": selected.head_sha, + "priority": selected.priority, + "expected_role_next": required_role, + "required_role": required_role, + "selected_action": action, + "action": action, + "required_profile": req_profile, + "required_namespace": req_ns, + "pinned": { + "kind": selected.kind, + "number": selected.number, + "head_sha": selected.head_sha, + "issue_number": selected.number if selected.kind == "issue" else None, + "pr_number": selected.number if selected.kind == "pr" else None, + }, + "reason_selected": ( + f"highest-priority eligible candidate under allocation_mode=" + f"'{allocation_mode}' (active_role={active_role}, " + f"required_role={required_role}, action={action})" + ), + } + + def expected_role_for_candidate(c: WorkCandidate) -> str: """ADR §5.3 routing: which role should take this work next.""" if c.kind == "pr": @@ -289,6 +519,7 @@ def classify_skip( role: str, terminal_pr: int | None, claim_ownership: str | None = None, + allocation_mode: str | None = None, ) -> str | None: """Return skip reason, or None if candidate is selectable for *role*. @@ -297,7 +528,12 @@ def classify_skip( and unknown claims are excluded so one session's in-progress task can never blockade the queue for a different controller; ``own`` stays selectable so a controller can resume its own work. + + *allocation_mode* (#840): ``cross_role`` (controller default) ranks the full + queue and selects the highest-priority eligible item for any downstream + role. ``role_scoped`` retains prior role-match filtering. """ + mode = resolve_allocation_mode(role, allocation_mode) if c.state in ("merged", "closed"): return f"{c.kind}#{c.number} is {c.state}; never assign" if c.blocked or "status:blocked" in c.labels: @@ -322,34 +558,58 @@ def classify_skip( if c.kind == "pr" and not (c.head_sha or "").strip(): return f"pr#{c.number} missing head_sha pin" + expected = expected_role_for_candidate(c) + # Terminal path first: when an active terminal PR exists, only that PR - # (or controller diagnosis) is assignable for review-path roles. + # is assignable for review-path roles (or for work whose expected role is + # review/merge under cross_role selection). if terminal_pr is not None and c.kind == "pr" and c.number != terminal_pr: - if role in (ROLE_REVIEWER, ROLE_MERGER): + terminal_roles = (ROLE_REVIEWER, ROLE_MERGER) + if mode == ALLOCATION_MODE_CROSS_ROLE: + if expected in terminal_roles: + return ( + f"pr#{c.number} skipped: active terminal-review lock on " + f"PR #{terminal_pr} must be resolved first" + ) + elif role in terminal_roles: return ( f"pr#{c.number} skipped: active terminal-review lock on " f"PR #{terminal_pr} must be resolved first" ) - expected = expected_role_for_candidate(c) - if role == ROLE_CONTROLLER: - # Controller may inspect anything but only assigns diagnosis targets - # when contaminated / blocked. + if mode == ALLOCATION_MODE_CROSS_ROLE: + # Cross-role controller selection: eligibility only — no active-role + # match filter. The selection payload names required_role. + pass + elif role == ROLE_CONTROLLER: + # Legacy diagnosis-only controller path (role_scoped): only reconciler- + # needed targets. Prefer cross_role for generic queue allocation. if expected == ROLE_RECONCILER or c.blocked: return None - return f"{c.kind}#{c.number} does not require controller (expected {expected})" - - if role != expected: + return ( + f"{c.kind}#{c.number} does not require controller " + f"(expected {expected})" + ) + elif role != expected: return ( f"{c.kind}#{c.number} expects role '{expected}', active role is '{role}'" ) # Ready-gate for issues: prefer status:ready when labels present. + # Applies for author-bound work in both modes (cross_role only gates + # author-expected issues so reconciler/reviewer PRs stay selectable). if c.kind == "issue" and c.labels: - if "status:ready" not in c.labels and "status:in-progress" not in c.labels: - # Allow unlabeled open issues; only skip explicit non-ready states. - if any(l.startswith("status:") for l in c.labels): - return f"issue#{c.number} not status:ready ({','.join(c.labels)})" + gate_role = expected if mode == ALLOCATION_MODE_CROSS_ROLE else role + if gate_role in (ROLE_AUTHOR, ROLE_CONTROLLER): + if ( + "status:ready" not in c.labels + and "status:in-progress" not in c.labels + ): + if any(l.startswith("status:") for l in c.labels): + return ( + f"issue#{c.number} not status:ready " + f"({','.join(c.labels)})" + ) return None @@ -501,12 +761,19 @@ def allocate_next_work( claims: Mapping[tuple[str, int], dict[str, Any]] | None = None, exclude_issue_numbers: Sequence[int] | None = None, expected_candidate_set_fingerprint: str | None = None, + allocation_mode: str | None = None, ) -> dict[str, Any]: """Select and optionally reserve the next work unit via control-plane DB. *apply=False* (default): dry-run selection only — no lease/assignment. *apply=True*: atomic ``assign_and_lease`` for the selected candidate. + *allocation_mode* (#840): ``cross_role`` (default for controller) inspects + the complete queue and returns one authoritative selection naming the + required downstream role/profile/action. ``role_scoped`` keeps prior + per-role filtering. Controller routes only — never grants author/reviewer/ + merger/reconciler mutation rights to the controller session. + *exclude_issue_numbers* (#776): numbers removed before ranking. Omitted / empty preserves prior behavior. @@ -541,6 +808,19 @@ def allocate_next_work( "substrate": "control_plane_db", } + try: + mode = resolve_allocation_mode(role_norm, allocation_mode) + except ControlPlaneError as exc: + return { + "success": False, + "outcome": OUTCOME_ROLE_INELIGIBLE, + "reasons": [str(exc)], + "skipped": [], + "assignment": None, + "substrate": "control_plane_db", + "allocation_mode": (allocation_mode or "").strip() or None, + } + session_id = (session_id or "").strip() or f"alloc-{uuid.uuid4().hex[:12]}" try: db.upsert_session( @@ -653,7 +933,8 @@ def allocate_next_work( ownership_defects: list[dict[str, Any]] = [] controller_excluded: list[dict[str, Any]] = [] - # #776 AC2: remove excluded numbers *before* ranking / selection / lease. + # #776 AC2 + #844: remove excluded numbers *and* epic/child-only containers + # *before* ranking / selection / lease so they never receive assignments. rankable: list[WorkCandidate] = [] for c in candidates: if int(c.number) in exclude_set: @@ -732,6 +1013,23 @@ 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) @@ -748,6 +1046,7 @@ def allocate_next_work( role=role_norm, terminal_pr=terminal_pr, claim_ownership=ownership, + allocation_mode=mode, ) if reason: is_claim_skip = SKIP_CLAIMED_BY_OTHER_SESSION in reason @@ -828,6 +1127,10 @@ def allocate_next_work( "outcome": outcome, "apply": bool(apply), "role": role_norm, + "allocation_mode": mode, + "routing_role": role_norm, + "required_role": None, + "selected_action": None, "profile_name": profile_name, "username": username, "session_id": session_id, @@ -840,6 +1143,12 @@ def allocate_next_work( "skipped": [s.as_dict() for s in skipped], "terminal_pr": terminal_pr, "assignment": None, + "allocation_evidence": { + "mode": "empty", + "allocation_mode": mode, + "lease_created": False, + "selection_policy": SELECTION_POLICY, + }, "substrate": "control_plane_db", "file_lock_only": False, "comment_lease_only": False, @@ -852,25 +1161,37 @@ def allocate_next_work( "owner_session_id": owner_session_id, "downstream_note": ( "#612 incident bridge remains downstream of #600; " - "allocator never assigns raw monitoring incidents" + "allocator never assigns raw monitoring incidents; " + "controller routes only under cross_role (#840)" ), } expected_role = expected_role_for_candidate(selected) - allowed, forbidden = role_actions(role_norm) - selection = { - "kind": selected.kind, - "number": selected.number, - "title": selected.title, - "labels": list(selected.labels), - "head_sha": selected.head_sha, - "priority": selected.priority, - "expected_role_next": expected_role, - "reason_selected": ( - f"highest-priority candidate for role '{role_norm}' " - f"(expected_role={expected_role})" - ), - } + # Cross-role: lease/action matrix follows the required downstream role so + # evidence names the worker that must act. Controller session still owns + # the routing decision; mutation isolation is enforced by role gates on + # mutation tools (controller profile lacks author/review/merge ops). + lease_role = ( + expected_role if mode == ALLOCATION_MODE_CROSS_ROLE else role_norm + ) + allowed, forbidden = role_actions(lease_role) + # Controller must never receive mutation-class rights via cross-role apply. + if role_norm == ROLE_CONTROLLER: + ctrl_allowed, ctrl_forbidden = role_actions(ROLE_CONTROLLER) + # Keep controller session capability evidence separate from lease_role. + controller_allowed_actions = ctrl_allowed + controller_forbidden_actions = ctrl_forbidden + else: + controller_allowed_actions = allowed + controller_forbidden_actions = forbidden + + selection = build_selection_dict( + selected, + active_role=role_norm, + required_role=expected_role, + profile_name=profile_name, + allocation_mode=mode, + ) if not apply: return { @@ -878,6 +1199,12 @@ def allocate_next_work( "outcome": OUTCOME_PREVIEW, "apply": False, "role": role_norm, + "allocation_mode": mode, + "routing_role": role_norm, + "required_role": expected_role, + "selected_action": selection["selected_action"], + "required_profile": selection["required_profile"], + "required_namespace": selection["required_namespace"], "profile_name": profile_name, "username": username, "session_id": session_id, @@ -889,10 +1216,22 @@ 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, "assignment": None, + "allocation_evidence": { + "mode": "preview", + "allocation_mode": mode, + "lease_created": False, + "selection_policy": SELECTION_POLICY, + }, "substrate": "control_plane_db", "file_lock_only": False, "comment_lease_only": False, @@ -902,18 +1241,24 @@ def allocate_next_work( "controller_excluded": list(controller_excluded), "exclude_issue_numbers": list(exclude_nums), "candidate_set_fingerprint": cas_fp, + "controller_allowed_actions": list(controller_allowed_actions), + "controller_forbidden_actions": list(controller_forbidden_actions), "downstream_note": ( "#612 incident bridge remains downstream of #600; " - "allocator never assigns raw monitoring incidents" + "allocator never assigns raw monitoring incidents; " + "controller routes only under cross_role (#840)" ), } # 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": role_norm, + "role": lease_role, "remote": remote, "org": org, "repo": repo, @@ -922,7 +1267,8 @@ def allocate_next_work( "expected_head_sha": selected.head_sha, "allowed_actions": allowed, "forbidden_actions": forbidden, - "phase": "allocated", + # #843: mark cross-role allocations as awaiting independent consume + "phase": "awaiting_handoff" if cross_role_handoff else "allocated", } if ttl is not None: kwargs["lease_ttl_seconds"] = int(ttl) @@ -992,11 +1338,72 @@ def allocate_next_work( } # assigned - return { + lease_proof = { + "assignment_id": result.assignment_id, + "lease_id": result.lease_id, + "expires_at": result.expires_at, + "expected_head_sha": result.expected_head_sha, + "allowed_actions": list(result.allowed_actions), + "forbidden_actions": list(result.forbidden_actions), + "lease_role": lease_role, + "source": "control_plane_db.assign_and_lease", + } + consume_allocation = None + 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, "role": role_norm, + "allocation_mode": mode, + "routing_role": role_norm, + "required_role": expected_role, + "selected_action": selection["selected_action"], + "required_profile": selection["required_profile"], + "required_namespace": selection["required_namespace"], "profile_name": profile_name, "username": username, "session_id": session_id, @@ -1012,16 +1419,25 @@ def allocate_next_work( "skipped": [s.as_dict() for s in skipped], "terminal_pr": terminal_pr, "assignment": result.as_dict(), - "lease_proof": { - "assignment_id": result.assignment_id, - "lease_id": result.lease_id, - "expires_at": result.expires_at, - "expected_head_sha": result.expected_head_sha, - "allowed_actions": list(result.allowed_actions), - "forbidden_actions": list(result.forbidden_actions), - "source": "control_plane_db.assign_and_lease", + "lease_proof": lease_proof, + "allocation_evidence": { + "mode": "assigned", + "allocation_mode": mode, + "lease_created": True, + "lease_role": lease_role, + "lease_proof": lease_proof, + "selection_policy": SELECTION_POLICY, + "cross_role_handoff": bool(cross_role_handoff), }, - "next_valid_command": _next_command(role_norm, selected), + "next_valid_command": ( + ( + 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, @@ -1031,11 +1447,19 @@ def allocate_next_work( "controller_excluded": list(controller_excluded), "exclude_issue_numbers": list(exclude_nums), "candidate_set_fingerprint": cas_fp, + "controller_allowed_actions": list(controller_allowed_actions), + "controller_forbidden_actions": list(controller_forbidden_actions), "downstream_note": ( "#612 incident bridge remains downstream of #600; " - "allocator never assigns raw monitoring incidents" + "allocator never assigns raw monitoring incidents; " + "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: @@ -1087,6 +1511,7 @@ 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")), diff --git a/arch01_platform.py b/arch01_platform.py new file mode 100644 index 0000000..9d18f5f --- /dev/null +++ b/arch01_platform.py @@ -0,0 +1,892 @@ +"""ARCH-01 Foundation Slice A — atomic platform installation + authority kernel (#822). + +Parents: #820, #821. **First implementation leaf of the ARCH-01 program.** + +This module implements the smallest executable ARCH-01 foundation: + +* a connection-bound authenticated actor context (``cp_actor_*`` / + ``cp_operation_mode`` / ``cp_context_epoch`` SQLite scalar functions that SQL + may *read* but can never *set* — ``[TRUSTED-SERVICE]`` authenticity); +* an immutable authority-dominance lattice with an exact seeded tuple set + (``[SCHEMA]``); +* the principal-equivalence root (a class exists *before* its first principal; + ``principals.current_class_id`` is ``NOT NULL``; ``[SCHEMA]``); +* a single-transaction platform installation that seeds the initial + ``platform.bootstrap`` grant and an immutable ``installed`` marker, validated + by a fail-closed ``install_state`` ``BEFORE INSERT`` trigger (``[SCHEMA]``). + +Everything else in the ARCH-01/02/04 program (evidence stores, repository +bindings, workspaces, PostgreSQL parity, full grant succession, full principal +merge) is out of scope here and tracked in its own issue — see #822 §5/§17. + +**Readiness / production posture.** This subsystem is *disabled by default*. +Nothing in the running MCP server imports or enables it. It becomes a security +boundary only once its readiness checks (the ACs in #822) pass in the target +environment. Instantiating :class:`PlatformKernel` creates an isolated SQLite +database and never touches the operational control-plane store. + +Enforcement classification (per #820 vocabulary): + +* ``[TRUSTED-SERVICE]`` — actor-context authenticity: the scalar functions are + registered by the trusted Python process; SQL cannot define or redefine them. +* ``[SCHEMA]`` — fail-closed aborts, the dominance/immutability/NOT-NULL-class/ + last-active-grant invariants, enforced by CHECK/FK/trigger. +* ``[RUNTIME-ADAPTER]`` — *none* in this slice. + +SQLite-first. ``BEGIN IMMEDIATE`` serializes concurrent installs and concurrent +grant/revoke on the singleton invariant row. PostgreSQL parity is a distinct +issue (#827); this module does **not** claim it. +""" + +from __future__ import annotations + +import os +import sqlite3 +import threading +from contextlib import contextmanager +from dataclasses import dataclass +from datetime import datetime, timezone +from typing import Iterator, Optional + +# --------------------------------------------------------------------------- # +# Closed enumerations (#822 §4). +# --------------------------------------------------------------------------- # + +ACTOR_KINDS = ("operator", "supervisor", "service", "installer") +OPERATION_MODES = ("normal", "install", "merge", "internal_service") + +# Exact seeded authority-dominance tuple set (#822 §4). This set is normative: +# the install-state trigger rejects any missing, additional, or malformed tuple. +DOMINANCE_TUPLES = ( + ("platform.bootstrap", "platform.bootstrap"), + ("platform.bootstrap", "project.admin"), + ("platform.bootstrap", "supervisor.root.establish"), + ("supervisor.root", "supervisor.register"), + ("supervisor.root", "supervisor.verify"), + ("supervisor.root", "supervisor.recover"), +) + +# The distinguished operator-key issuer seeded during install. +DISTINGUISHED_ISSUER_KIND = "operator-key" +DISTINGUISHED_ISSUER_ID = "platform.bootstrap.operator-key" + +# Structured result codes (#822 §10). +INSTALLED = "INSTALLED" +ALREADY_INSTALLED = "ALREADY_INSTALLED" +INVALID_ACTOR_CONTEXT = "INVALID_ACTOR_CONTEXT" +INVALID_BOOTSTRAP_STATE = "INVALID_BOOTSTRAP_STATE" +DOMINANCE_SET_MISMATCH = "DOMINANCE_SET_MISMATCH" +AUTHORIZATION_DENIED = "AUTHORIZATION_DENIED" +CONCURRENT_INSTALLATION_LOST = "CONCURRENT_INSTALLATION_LOST" + +# Required audit events (#822 §14). +EVT_PLATFORM_INSTALLED = "platform_installed" +EVT_GRANT_CREATED = "platform_grant_created" +EVT_GRANT_REVOKED = "platform_grant_revoked" +EVT_PRINCIPAL_REGISTERED = "principal_registered" + +SCHEMA_VERSION = 1 + +DB_PATH_ENV = "ARCH01_PLATFORM_DB" + + +class PlatformKernelError(RuntimeError): + """Base class for structured, code-bearing kernel failures.""" + + def __init__(self, code: str, message: str = "") -> None: + super().__init__(message or code) + self.code = code + + +class ActorContextError(PlatformKernelError): + """Raised when a mutation is attempted without a valid actor context.""" + + +# --------------------------------------------------------------------------- # +# Schema (#822 §6). Tables + fail-closed triggers. +# +# Every *mutating* trigger opens with the actor protocol: read the context +# epoch, read the actor fields, and abort unless the context is present, +# non-null, mode/kind well-formed, and epoch-consistent with the active +# transaction. The scalar functions ``cp_*`` are registered from Python only; +# SQL has no statement that can set them, which is the trusted-service boundary. +# --------------------------------------------------------------------------- # + +_ACTOR_KINDS_SQL = ", ".join("'%s'" % k for k in ACTOR_KINDS) +_OP_MODES_SQL = ", ".join("'%s'" % m for m in OPERATION_MODES) + +# Actor-protocol predicate: TRUE when the context is INVALID and the trigger +# must abort. ``cp_actor_context_valid()`` folds "present + non-expired + +# live-epoch == bound-epoch" (the read/re-read epoch equality of #822 §4) into +# one trusted-service answer; the remaining reads assert field well-formedness. +_INVALID_ACTOR = ( + "cp_actor_context_valid() IS NOT 1 " + "OR cp_context_epoch() IS NULL " + "OR cp_actor_principal() IS NULL " + "OR cp_actor_kind() NOT IN (%s) " + "OR cp_operation_mode() NOT IN (%s)" % (_ACTOR_KINDS_SQL, _OP_MODES_SQL) +) + +_ACTOR_GUARD = ( + "SELECT CASE WHEN (%s) " + "THEN RAISE(ABORT, 'INVALID_ACTOR_CONTEXT') END;" % _INVALID_ACTOR +) + +# require_installed: abort a privileged mutation when there is no install +# marker and we are not currently installing (#822 §4). +_REQUIRE_INSTALLED = ( + "SELECT CASE WHEN ((SELECT COUNT(*) FROM install_state) = 0 " + "AND cp_operation_mode() <> 'install') " + "THEN RAISE(ABORT, 'NOT_INSTALLED') END;" +) + +_SCHEMA_SQL = f""" +PRAGMA foreign_keys = ON; + +CREATE TABLE IF NOT EXISTS arch01_meta ( + key TEXT PRIMARY KEY, + value TEXT NOT NULL +); + +-- Equivalence classes are created BEFORE their first principal (#822 §4). +CREATE TABLE IF NOT EXISTS principal_equivalence_classes ( + class_id INTEGER PRIMARY KEY AUTOINCREMENT, + created_at TEXT NOT NULL +); + +CREATE TABLE IF NOT EXISTS authoritative_issuers ( + issuer_id INTEGER PRIMARY KEY AUTOINCREMENT, + issuer_kind TEXT NOT NULL, + issuer_ref TEXT NOT NULL, + created_at TEXT NOT NULL, + UNIQUE (issuer_kind, issuer_ref) +); + +-- current_class_id is NOT NULL: a principal cannot exist without a class +-- (#822 AC6). issuer_id is nullable ONLY for the installer during install +-- (#822 AC7), enforced by trg_principals_null_issuer below. +CREATE TABLE IF NOT EXISTS principals ( + principal_id TEXT PRIMARY KEY, + actor_kind TEXT NOT NULL CHECK (actor_kind IN ({_ACTOR_KINDS_SQL})), + current_class_id INTEGER NOT NULL REFERENCES principal_equivalence_classes(class_id), + issuer_id INTEGER REFERENCES authoritative_issuers(issuer_id), + registered_by TEXT REFERENCES principals(principal_id), + created_at TEXT NOT NULL +); + +CREATE TABLE IF NOT EXISTS authority_dominance ( + dominant TEXT NOT NULL, + subordinate TEXT NOT NULL, + PRIMARY KEY (dominant, subordinate) +); + +CREATE TABLE IF NOT EXISTS platform_bootstrap_seed ( + seed_id INTEGER PRIMARY KEY CHECK (seed_id = 1), + installer_principal_id TEXT NOT NULL REFERENCES principals(principal_id), + created_at TEXT NOT NULL +); + +CREATE TABLE IF NOT EXISTS platform_bootstrap_grants ( + grant_id INTEGER PRIMARY KEY AUTOINCREMENT, + grantee_principal_id TEXT NOT NULL REFERENCES principals(principal_id), + granted_by TEXT REFERENCES principals(principal_id), + active INTEGER NOT NULL DEFAULT 1 CHECK (active IN (0, 1)), + created_at TEXT NOT NULL, + revoked_at TEXT +); + +-- Singleton row; active_count floored at 1 by CHECK so the last active grant +-- can never be revoked (#822 AC11). +CREATE TABLE IF NOT EXISTS platform_active_invariant ( + id INTEGER PRIMARY KEY CHECK (id = 1), + active_count INTEGER NOT NULL CHECK (active_count >= 1) +); + +-- The immutable install marker; inserted LAST in the install transaction. +CREATE TABLE IF NOT EXISTS install_state ( + id INTEGER PRIMARY KEY CHECK (id = 1), + marker TEXT NOT NULL CHECK (marker = 'installed'), + installed_at TEXT NOT NULL +); + +-- Append-only (#822 AC14). +CREATE TABLE IF NOT EXISTS audit_records ( + audit_id INTEGER PRIMARY KEY AUTOINCREMENT, + event TEXT NOT NULL, + principal_id TEXT, + detail TEXT, + created_at TEXT NOT NULL +); + +-- ------------------------------------------------------------------------- -- +-- Actor protocol on every mutating trigger (#822 §4, [SCHEMA] fail-closed). +-- ------------------------------------------------------------------------- -- + +CREATE TRIGGER IF NOT EXISTS trg_classes_actor +BEFORE INSERT ON principal_equivalence_classes +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_issuers_actor +BEFORE INSERT ON authoritative_issuers +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_principals_actor +BEFORE INSERT ON principals +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_dominance_actor +BEFORE INSERT ON authority_dominance +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_seed_actor +BEFORE INSERT ON platform_bootstrap_seed +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_grants_actor_insert +BEFORE INSERT ON platform_bootstrap_grants +BEGIN + {_ACTOR_GUARD} + {_REQUIRE_INSTALLED} +END; + +CREATE TRIGGER IF NOT EXISTS trg_grants_actor_update +BEFORE UPDATE ON platform_bootstrap_grants +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_insert +BEFORE INSERT ON platform_active_invariant +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_invariant_actor_update +BEFORE UPDATE ON platform_active_invariant +BEGIN + {_ACTOR_GUARD} +END; + +CREATE TRIGGER IF NOT EXISTS trg_audit_actor +BEFORE INSERT ON audit_records +BEGIN + {_ACTOR_GUARD} +END; + +-- ------------------------------------------------------------------------- -- +-- NOT-NULL-issuer exception for the installer only (#822 AC7). +-- A NULL issuer_id is accepted solely for an installer principal during +-- install mode, before the marker exists; any other NULL-issuer principal is +-- rejected. install-time issuer linkage (installer -> distinguished issuer) +-- is applied by a later UPDATE, permitted while no marker exists. +-- ------------------------------------------------------------------------- -- + +CREATE TRIGGER IF NOT EXISTS trg_principals_null_issuer +BEFORE INSERT ON principals +WHEN NEW.issuer_id IS NULL +BEGIN + SELECT CASE WHEN NOT ( + NEW.actor_kind = 'installer' + AND cp_operation_mode() = 'install' + AND (SELECT COUNT(*) FROM install_state) = 0 + AND (SELECT COUNT(*) FROM principals WHERE issuer_id IS NULL) = 0 + ) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END; +END; + +-- ------------------------------------------------------------------------- -- +-- Post-install immutability of the authority root (#822 §4, AC9). +-- Registration fields freeze only AFTER the marker exists, so the install +-- transaction's own installer issuer-linkage UPDATE is permitted. +-- ------------------------------------------------------------------------- -- + +CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_update +BEFORE UPDATE ON principals +WHEN (SELECT COUNT(*) FROM install_state) > 0 +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_principals_frozen_delete +BEFORE DELETE ON principals +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_PRINCIPAL'); +END; + +-- Distinguished issuer identity is immutable once written. +CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_update +BEFORE UPDATE ON authoritative_issuers +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_issuers_immutable_delete +BEFORE DELETE ON authoritative_issuers +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_ISSUER'); +END; + +-- The dominance lattice is immutable once seeded. +CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_update +BEFORE UPDATE ON authority_dominance +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_dominance_immutable_delete +BEFORE DELETE ON authority_dominance +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_DOMINANCE'); +END; + +-- The bootstrap seed is immutable once written. +CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_update +BEFORE UPDATE ON platform_bootstrap_seed +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_SEED'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_seed_immutable_delete +BEFORE DELETE ON platform_bootstrap_seed +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_SEED'); +END; + +-- The install marker is immutable once written. +CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_update +BEFORE UPDATE ON install_state +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_install_state_immutable_delete +BEFORE DELETE ON install_state +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_INSTALL_STATE'); +END; + +-- Grants: identity is immutable; the ONLY permitted mutation is a single +-- active 1 -> 0 revocation (#822 §4 initial-grant identity immutability + +-- grant/revoke). Reactivation and identity edits are rejected. +CREATE TRIGGER IF NOT EXISTS trg_grants_identity_frozen +BEFORE UPDATE ON platform_bootstrap_grants +WHEN NOT ( + NEW.grant_id = OLD.grant_id + AND NEW.grantee_principal_id = OLD.grantee_principal_id + AND NEW.granted_by IS OLD.granted_by + AND NEW.created_at = OLD.created_at + AND OLD.active = 1 + AND NEW.active = 0 +) +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_GRANT'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_grants_no_delete +BEFORE DELETE ON platform_bootstrap_grants +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_GRANT'); +END; + +-- audit_records is append-only. +CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_update +BEFORE UPDATE ON audit_records +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT'); +END; + +CREATE TRIGGER IF NOT EXISTS trg_audit_immutable_delete +BEFORE DELETE ON audit_records +BEGIN + SELECT RAISE(ABORT, 'IMMUTABLE_AUDIT'); +END; + +-- ------------------------------------------------------------------------- -- +-- install_state BEFORE INSERT: validate the whole bootstrap atomically +-- (#822 §4, AC4). Each dominance tuple is checked individually; a missing, +-- additional, or malformed tuple -> DOMINANCE_SET_MISMATCH. The seed<->installer +-- link, the single active NULL-grantor installer grant, the installer's +-- non-NULL issuer, the active invariant, and "no extra principal created under +-- the NULL-issuer exception" -> INVALID_BOOTSTRAP_STATE. +-- ------------------------------------------------------------------------- -- + +CREATE TRIGGER IF NOT EXISTS trg_install_state_validate +BEFORE INSERT ON install_state +BEGIN + SELECT CASE WHEN NOT ( + (SELECT COUNT(*) FROM authority_dominance) = {len(DOMINANCE_TUPLES)} + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='platform.bootstrap') + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='project.admin') + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='platform.bootstrap' AND subordinate='supervisor.root.establish') + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.register') + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.verify') + AND EXISTS (SELECT 1 FROM authority_dominance WHERE dominant='supervisor.root' AND subordinate='supervisor.recover') + ) THEN RAISE(ABORT, 'DOMINANCE_SET_MISMATCH') END; + + SELECT CASE WHEN NOT ( + (SELECT COUNT(*) FROM platform_bootstrap_seed) = 1 + AND (SELECT COUNT(*) FROM principals) = 1 + AND (SELECT actor_kind FROM principals + WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1) + ) = 'installer' + AND (SELECT issuer_id FROM principals + WHERE principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1) + ) IS NOT NULL + AND (SELECT COUNT(*) FROM platform_bootstrap_grants + WHERE granted_by IS NULL AND active = 1 + AND grantee_principal_id = (SELECT installer_principal_id FROM platform_bootstrap_seed WHERE seed_id = 1) + ) = 1 + AND (SELECT COUNT(*) FROM platform_bootstrap_grants) = 1 + AND (SELECT active_count FROM platform_active_invariant WHERE id = 1) = 1 + ) THEN RAISE(ABORT, 'INVALID_BOOTSTRAP_STATE') END; +END; +""" + + +def default_db_path() -> str: + return os.environ.get( + DB_PATH_ENV, + os.path.expanduser("~/.cache/gitea-tools/arch01/platform.sqlite3"), + ) + + +def _utc_now_iso() -> str: + return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +@dataclass(frozen=True) +class OperationResult: + """Structured result of a kernel operation (#822 §10).""" + + code: str + detail: str = "" + + @property + def ok(self) -> bool: + return self.code in (INSTALLED, ALREADY_INSTALLED) + + +@dataclass +class _ActorContext: + principal: str + kind: str + mode: str + session: Optional[str] + bound_epoch: int + live_epoch: int + expired: bool = False + + +class PlatformKernel: + """ARCH-01 authority kernel over a single SQLite connection. + + The connection carries the trusted-service actor context: the ``cp_*`` + scalar functions read the context this object holds. Only Python code here + can bind or clear it, so no SQL statement can assert an actor identity — the + trusted-service authenticity boundary of #822 §4. + """ + + def __init__(self, db_path: Optional[str] = None, *, busy_timeout_ms: int = 5000) -> None: + self.db_path = db_path or default_db_path() + if self.db_path != ":memory:": + parent = os.path.dirname(self.db_path) + if parent: + os.makedirs(parent, exist_ok=True) + self._ctx: Optional[_ActorContext] = None + self._epoch_seq = 0 + self._lock = threading.Lock() + # check_same_thread=False is safe: every mutation path is serialized + # by self._lock, so the connection is never used concurrently even when + # callers drive the kernel from different threads (concurrency tests). + self._conn = sqlite3.connect( + self.db_path, isolation_level=None, check_same_thread=False + ) + self._conn.execute("PRAGMA foreign_keys = ON") + self._conn.execute(f"PRAGMA busy_timeout = {int(busy_timeout_ms)}") + self._register_actor_functions() + self._migrate() + + # -- trusted-service actor functions ---------------------------------- # + + def _register_actor_functions(self) -> None: + c = self._conn + c.create_function("cp_actor_principal", 0, lambda: self._ctx.principal if self._ctx else None) + c.create_function("cp_actor_kind", 0, lambda: self._ctx.kind if self._ctx else None) + c.create_function("cp_operation_mode", 0, lambda: self._ctx.mode if self._ctx else None) + c.create_function("cp_service_session", 0, lambda: self._ctx.session if self._ctx else None) + c.create_function("cp_context_epoch", 0, self._fn_context_epoch) + # Trusted-service helper: folds present + non-expired + epoch-consistent + # into the read/re-read epoch equality of #822 §4. + c.create_function("cp_actor_context_valid", 0, self._fn_context_valid) + + def _fn_context_epoch(self) -> Optional[int]: + if self._ctx is None or self._ctx.expired: + return None + return self._ctx.live_epoch + + def _fn_context_valid(self) -> int: + ctx = self._ctx + if ctx is None or ctx.expired: + return 0 + # read/re-read epoch equality: a context whose live epoch has drifted + # from the epoch it was bound to (a stale/replaced connection context) + # is not bound to the active transaction and fails closed. + if ctx.live_epoch != ctx.bound_epoch: + return 0 + if ctx.principal is None: + return 0 + if ctx.kind not in ACTOR_KINDS or ctx.mode not in OPERATION_MODES: + return 0 + return 1 + + # -- context lifecycle ------------------------------------------------ # + + @contextmanager + def actor_context( + self, principal: str, kind: str, mode: str, session: Optional[str] = None + ) -> Iterator[None]: + """Bind a trusted actor context for the duration of the block.""" + prev = self._ctx + self._epoch_seq += 1 + epoch = self._epoch_seq + self._ctx = _ActorContext( + principal=principal, kind=kind, mode=mode, session=session, + bound_epoch=epoch, live_epoch=epoch, + ) + try: + yield + finally: + self._ctx = prev + + def _clear_context(self) -> None: + self._ctx = None + + # -- migration -------------------------------------------------------- # + + def _migrate(self) -> None: + self._conn.executescript(_SCHEMA_SQL) + self._conn.execute( + "INSERT OR IGNORE INTO arch01_meta(key, value) VALUES ('schema_version', ?)", + (str(SCHEMA_VERSION),), + ) + self._conn.execute( + "INSERT OR IGNORE INTO arch01_meta(key, value) VALUES " + "('architecture', 'ARCH-01 Slice A: atomic install + authority kernel (#822); " + "disabled by default until readiness checks pass')" + ) + + # -- introspection ---------------------------------------------------- # + + def is_installed(self) -> bool: + row = self._conn.execute("SELECT COUNT(*) FROM install_state").fetchone() + return bool(row[0]) + + def active_grant_count(self) -> int: + row = self._conn.execute( + "SELECT active_count FROM platform_active_invariant WHERE id = 1" + ).fetchone() + return int(row[0]) if row else 0 + + def audit_events(self) -> list[str]: + return [ + r[0] + for r in self._conn.execute( + "SELECT event FROM audit_records ORDER BY audit_id" + ).fetchall() + ] + + def close(self) -> None: + self._conn.close() + + # -- operations ------------------------------------------------------- # + + def install_platform( + self, + installer_principal_id: str = "platform.installer", + *, + session: Optional[str] = None, + ) -> OperationResult: + """Single atomic install transaction (#822 §4/§7). + + ``BEGIN IMMEDIATE`` serializes concurrent installs; the loser rechecks + the marker and returns ``ALREADY_INSTALLED``, or — if it never acquires + the write lock — ``CONCURRENT_INSTALLATION_LOST``. On any stage failure + the whole transaction rolls back leaving no partial rows (AC3/AC5). + """ + now = _utc_now_iso() + with self._lock: + try: + self._conn.execute("BEGIN IMMEDIATE") + except sqlite3.OperationalError as exc: + if "locked" in str(exc).lower() or "busy" in str(exc).lower(): + return OperationResult(CONCURRENT_INSTALLATION_LOST, str(exc)) + raise + try: + if self.is_installed(): + self._conn.execute("ROLLBACK") + return OperationResult(ALREADY_INSTALLED, "install marker already present") + + with self.actor_context(installer_principal_id, "installer", "install", session): + c = self._conn + # class -> installer principal (temporary NULL issuer) + cur = c.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", + (now,), + ) + class_id = cur.lastrowid + c.execute( + "INSERT INTO principals" + "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES (?, 'installer', ?, NULL, ?, ?)", + (installer_principal_id, class_id, installer_principal_id, now), + ) + # distinguished operator-key issuer + cur = c.execute( + "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) " + "VALUES (?, ?, ?)", + (DISTINGUISHED_ISSUER_KIND, DISTINGUISHED_ISSUER_ID, now), + ) + issuer_id = cur.lastrowid + # link installer -> issuer (permitted pre-marker) + c.execute( + "UPDATE principals SET issuer_id = ? WHERE principal_id = ?", + (issuer_id, installer_principal_id), + ) + # dominance tuples + c.executemany( + "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)", + DOMINANCE_TUPLES, + ) + # seed + c.execute( + "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) " + "VALUES (1, ?, ?)", + (installer_principal_id, now), + ) + # initial grant (granted_by NULL, active) + c.execute( + "INSERT INTO platform_bootstrap_grants" + "(grantee_principal_id, granted_by, active, created_at) " + "VALUES (?, NULL, 1, ?)", + (installer_principal_id, now), + ) + # active invariant + c.execute( + "INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)" + ) + # audit rows for the security-sensitive operation + c.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_PRINCIPAL_REGISTERED, installer_principal_id, "installer", now), + ) + c.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_GRANT_CREATED, installer_principal_id, "initial platform.bootstrap grant", now), + ) + # install marker LAST -> fires the whole-bootstrap validator + c.execute( + "INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)", + (now,), + ) + c.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_PLATFORM_INSTALLED, installer_principal_id, "platform installed", now), + ) + self._conn.execute("COMMIT") + return OperationResult(INSTALLED, "platform installed") + except sqlite3.Error as exc: + self._safe_rollback() + return OperationResult(self._classify(exc), str(exc)) + + def register_principal( + self, + principal_id: str, + actor_kind: str, + issuer_ref: str, + *, + actor_principal: str, + actor_kind_ctx: str = "operator", + session: Optional[str] = None, + ) -> OperationResult: + """Atomically create an equivalence class and its first principal. + + The class is inserted *before* the principal, and ``current_class_id`` + is ``NOT NULL`` (#822 AC6): a principal can never exist classless. + The principal references an existing issuer (non-NULL); the temporary + NULL-issuer exception is reserved for the installer during install + (AC7). + """ + if actor_kind not in ACTOR_KINDS: + return OperationResult(INVALID_BOOTSTRAP_STATE, f"bad actor_kind {actor_kind!r}") + now = _utc_now_iso() + with self._lock: + try: + self._conn.execute("BEGIN IMMEDIATE") + except sqlite3.OperationalError as exc: + return OperationResult(AUTHORIZATION_DENIED, str(exc)) + try: + if not self.is_installed(): + self._conn.execute("ROLLBACK") + return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed") + row = self._conn.execute( + "SELECT issuer_id FROM authoritative_issuers WHERE issuer_ref = ?", + (issuer_ref,), + ).fetchone() + if row is None: + self._conn.execute("ROLLBACK") + return OperationResult(INVALID_BOOTSTRAP_STATE, f"unknown issuer {issuer_ref!r}") + issuer_id = row[0] + with self.actor_context(actor_principal, actor_kind_ctx, "normal", session): + cur = self._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", + (now,), + ) + class_id = cur.lastrowid + self._conn.execute( + "INSERT INTO principals" + "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES (?, ?, ?, ?, ?, ?)", + (principal_id, actor_kind, class_id, issuer_id, actor_principal, now), + ) + self._conn.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_PRINCIPAL_REGISTERED, principal_id, actor_kind, now), + ) + self._conn.execute("COMMIT") + return OperationResult(INSTALLED, f"registered {principal_id}") + except sqlite3.Error as exc: + self._safe_rollback() + return OperationResult(self._classify(exc), str(exc)) + + def grant_platform_bootstrap( + self, + grantee_principal_id: str, + granted_by: str, + *, + actor_kind_ctx: str = "operator", + session: Optional[str] = None, + ) -> OperationResult: + """Create an additional active platform.bootstrap grant. + + Serialized on the singleton invariant row via ``BEGIN IMMEDIATE``. + """ + now = _utc_now_iso() + with self._lock: + try: + self._conn.execute("BEGIN IMMEDIATE") + except sqlite3.OperationalError as exc: + return OperationResult(AUTHORIZATION_DENIED, str(exc)) + try: + if not self.is_installed(): + self._conn.execute("ROLLBACK") + return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed") + with self.actor_context(granted_by, actor_kind_ctx, "normal", session): + self._conn.execute( + "INSERT INTO platform_bootstrap_grants" + "(grantee_principal_id, granted_by, active, created_at) " + "VALUES (?, ?, 1, ?)", + (grantee_principal_id, granted_by, now), + ) + self._conn.execute( + "UPDATE platform_active_invariant SET active_count = active_count + 1 WHERE id = 1" + ) + self._conn.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_GRANT_CREATED, grantee_principal_id, f"granted_by={granted_by}", now), + ) + self._conn.execute("COMMIT") + return OperationResult(INSTALLED, f"granted to {grantee_principal_id}") + except sqlite3.Error as exc: + self._safe_rollback() + return OperationResult(self._classify(exc), str(exc)) + + def revoke_platform_bootstrap( + self, + grant_id: int, + *, + actor_principal: str, + actor_kind_ctx: str = "operator", + session: Optional[str] = None, + ) -> OperationResult: + """Revoke an active grant, floored so the last one can never drop. + + The ``active_count >= 1`` CHECK plus ``BEGIN IMMEDIATE`` serialization + make two concurrent revocations unable to remove the final active grant + (#822 AC11): the decrement that would reach zero fails and rolls back. + """ + now = _utc_now_iso() + with self._lock: + try: + self._conn.execute("BEGIN IMMEDIATE") + except sqlite3.OperationalError as exc: + return OperationResult(AUTHORIZATION_DENIED, str(exc)) + try: + if not self.is_installed(): + self._conn.execute("ROLLBACK") + return OperationResult(INVALID_BOOTSTRAP_STATE, "platform not installed") + row = self._conn.execute( + "SELECT active, grantee_principal_id FROM platform_bootstrap_grants WHERE grant_id = ?", + (grant_id,), + ).fetchone() + if row is None or row[0] != 1: + self._conn.execute("ROLLBACK") + return OperationResult(AUTHORIZATION_DENIED, "grant absent or already inactive") + grantee = row[1] + with self.actor_context(actor_principal, actor_kind_ctx, "normal", session): + # Decrement first: the CHECK floor rejects dropping below 1, + # aborting the whole revoke before the grant flips inactive. + self._conn.execute( + "UPDATE platform_active_invariant SET active_count = active_count - 1 WHERE id = 1" + ) + self._conn.execute( + "UPDATE platform_bootstrap_grants SET active = 0, revoked_at = ? WHERE grant_id = ?", + (now, grant_id), + ) + self._conn.execute( + "INSERT INTO audit_records(event, principal_id, detail, created_at) " + "VALUES (?, ?, ?, ?)", + (EVT_GRANT_REVOKED, grantee, f"grant_id={grant_id}", now), + ) + self._conn.execute("COMMIT") + return OperationResult(INSTALLED, f"revoked grant {grant_id}") + except sqlite3.Error as exc: + self._safe_rollback() + return OperationResult(self._classify(exc), str(exc)) + + # -- helpers ---------------------------------------------------------- # + + def _safe_rollback(self) -> None: + try: + self._conn.execute("ROLLBACK") + except sqlite3.Error: + pass + + @staticmethod + def _classify(exc: sqlite3.Error) -> str: + msg = str(exc) + if "INVALID_ACTOR_CONTEXT" in msg: + return INVALID_ACTOR_CONTEXT + if "DOMINANCE_SET_MISMATCH" in msg: + return DOMINANCE_SET_MISMATCH + if "active_count" in msg or "CHECK constraint failed: platform_active_invariant" in msg: + # last-active-grant floor tripped + return AUTHORIZATION_DENIED + if any(tag in msg for tag in ( + "INVALID_BOOTSTRAP_STATE", "IMMUTABLE_", "NOT_INSTALLED", + )): + return INVALID_BOOTSTRAP_STATE + return INVALID_BOOTSTRAP_STATE diff --git a/canonical_thread_handoff.py b/canonical_thread_handoff.py index aa0a85b..6d262c2 100644 --- a/canonical_thread_handoff.py +++ b/canonical_thread_handoff.py @@ -46,6 +46,17 @@ _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, @@ -60,7 +71,7 @@ def format_cth_body( ) -> str: """Render a canonical CTH comment body.""" normalized_type = (cth_type or "").strip() - if normalized_type not in CTH_TYPES: + if not is_known_cth_type(normalized_type): raise ValueError( f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}" ) @@ -101,6 +112,12 @@ 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, } @@ -119,7 +136,7 @@ def assess_cth_comment(body: str) -> dict[str, Any]: } cth_type = parsed.get("cth_type") or "" - if cth_type not in CTH_TYPES: + if not is_known_cth_type(cth_type): reasons.append( f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}" ) diff --git a/control_plane_db.py b/control_plane_db.py index 8994a08..75af7c9 100644 --- a/control_plane_db.py +++ b/control_plane_db.py @@ -1637,11 +1637,13 @@ 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). + """Transfer or refresh a lease with provenance (#601 / #843). * 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 → raise ForeignLeaseError (never silent steal). + * Active foreign (non-handoff) → raise ForeignLeaseError (never silent steal). """ now = _utc_now() now_s = _ts(now) @@ -1677,7 +1679,35 @@ class ControlPlaneDB: status = "expired" owner = lease["session_id"] - if status == "active" and owner != adopter_session_id: + # Parse durable provenance for cross-role handoff consume (#843). + 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}" ) @@ -1761,6 +1791,142 @@ 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]}" diff --git a/dirty_same_claimant_session_rebind.py b/dirty_same_claimant_session_rebind.py new file mode 100644 index 0000000..fc29add --- /dev/null +++ b/dirty_same_claimant_session_rebind.py @@ -0,0 +1,1565 @@ +"""Dirty-preserving same-claimant author-session rebind (#864 / #868). + +A registered issue worktree can be dirty while its durable lock owner PID is +provably dead. Ordinary ``gitea_lock_issue`` refuses dirty trees, and dead-session +recovery (#753) also requires cleanliness. This module is the *only* sanctioned +path that rebinds session/lock provenance onto the *same* worktree without +touching tracked or untracked content. + +This is SEPARATE from #860 dirty-orphan recovery (PID-less + remote sync). +This operation: + +* acts only on an already-registered dirty worktree +* updates only stale lock/session provenance (PID, session pointer, generation, + heartbeat) +* preserves every tracked/untracked byte +* does NOT sync remote, create recovery worktrees, clean, reset, or change heads + +#868 hardens: + +* complete dirty-inventory revalidation (full path set + fingerprints) + immediately before and after ``bind_session_lock`` +* durable recovery-journal operation identity (remote, org, repo, claimant + identity, claimant profile) validated on execute / resume / retry / + already_rebound +""" + +from __future__ import annotations + +import hashlib +import json +import os +import subprocess +import tempfile +from datetime import datetime, timezone +from typing import Any, Mapping, Sequence + +from author_mutation_worktree import is_path_under_branches +from issue_lock_provenance import ( + SOURCE_DIRTY_SAME_CLAIMANT_REBIND, + build_sanctioned_lock_provenance, +) +from issue_lock_store import ( + AUTHOR_ISSUE_WORK_LEASE, + bind_session_lock, + is_process_alive, + lock_file_path, + lock_generation, + read_lock_file, +) +from reviewer_worktree import parse_dirty_tracked_files + +# Outcomes +REBIND_SANCTIONED = "REBIND_SANCTIONED" +REFUSED = "REFUSED" +NO_CANDIDATE = "NO_CANDIDATE" + +# Provenance / tool identity +SOURCE_TOOL = SOURCE_DIRTY_SAME_CLAIMANT_REBIND +SOURCE = SOURCE_DIRTY_SAME_CLAIMANT_REBIND + +# Journal phases (crash-safe apply) +JOURNAL_PHASE_ASSESSED = "assessed" +JOURNAL_PHASE_PRE_BIND = "pre_bind" +JOURNAL_PHASE_BOUND = "bound" +JOURNAL_PHASE_COMPLETE = "complete" +JOURNAL_PHASE_ALREADY_REBOUND = "already_rebound" + +REQUIRED_LOCK_FIELDS = ( + "issue_number", + "branch_name", + "worktree_path", + "remote", + "org", + "repo", +) + +# Durable journal operation identity (#868 F2). All five must be persisted on +# JOURNAL_PHASE_ASSESSED and re-validated on resume / retry / already_rebound. +REQUIRED_JOURNAL_IDENTITY_FIELDS = ( + "remote", + "org", + "repo", + "claimant_identity", + "claimant_profile", +) + + +def _utc_now_iso() -> str: + return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + + +def _text(value: Any) -> str: + return str(value or "").strip() + + +def _same_realpath(left: str | None, right: str | None) -> bool: + if not left or not right: + return False + try: + return os.path.realpath(left) == os.path.realpath(right) + except OSError: + return left == right + + +def _lock_claimant(lock: Mapping[str, Any]) -> dict[str, Any]: + claimant = lock.get("claimant") + if not isinstance(claimant, Mapping): + lease = lock.get("work_lease") + claimant = lease.get("claimant") if isinstance(lease, Mapping) else None + return dict(claimant) if isinstance(claimant, Mapping) else {} + + +def _recorded_pid(lock: Mapping[str, Any]) -> Any: + pid = lock.get("session_pid") + if pid is None: + pid = lock.get("pid") + return pid + + +def content_fingerprint(path: str) -> str: + """Return sha256 hex digest of file bytes at *path*. + + Missing or unreadable files raise ``OSError`` / ``FileNotFoundError`` so + callers fail closed rather than inventing an empty hash. + """ + digest = hashlib.sha256() + with open(path, "rb") as handle: + while True: + chunk = handle.read(1024 * 1024) + if not chunk: + break + digest.update(chunk) + return digest.hexdigest() + + +def parse_dirty_paths(porcelain: str) -> list[str]: + """Tracked + untracked paths from ``git status --porcelain -uall`` output.""" + paths: list[str] = [] + seen: set[str] = set() + for line in (porcelain or "").splitlines(): + if not line or len(line) < 4: + continue + if line.startswith("??"): + path = line[3:].strip() + else: + path = line[3:].strip() + if " -> " in path: + path = path.split(" -> ", 1)[1].strip() + if not path or path in seen: + continue + seen.add(path) + paths.append(path) + return paths + + +def collect_dirty_inventory(worktree_path: str) -> dict[str, Any]: + """Observe dirty tracked + untracked paths and content fingerprints. + + Uses ``git status --porcelain -uall`` so every untracked file is listed + individually (not collapsed into a directory). + """ + path = (worktree_path or "").strip() + if not path: + return { + "worktree_path": path, + "porcelain_status": "", + "dirty_paths": [], + "fingerprints": {}, + "ok": False, + "reasons": ["worktree path is empty"], + } + + status_res = subprocess.run( + ["git", "-C", path, "status", "--porcelain", "-uall"], + capture_output=True, + text=True, + check=False, + ) + if status_res.returncode != 0: + err = (status_res.stderr or status_res.stdout or "").strip() + return { + "worktree_path": path, + "porcelain_status": "", + "dirty_paths": [], + "fingerprints": {}, + "ok": False, + "reasons": [f"git status failed in '{path}': {err or 'unknown error'}"], + } + + porcelain = status_res.stdout or "" + dirty_paths = parse_dirty_paths(porcelain) + fingerprints: dict[str, str] = {} + reasons: list[str] = [] + for rel in dirty_paths: + abs_path = os.path.join(path, rel) + if os.path.isdir(abs_path) and not os.path.islink(abs_path): + # Directories appear only if git reported them; fingerprinting a + # directory is not defined — fail closed. + reasons.append(f"dirty path '{rel}' is a directory; cannot fingerprint") + continue + try: + fingerprints[rel] = content_fingerprint(abs_path) + except OSError as exc: + reasons.append(f"could not fingerprint '{rel}': {exc}") + + return { + "worktree_path": os.path.realpath(path), + "porcelain_status": porcelain, + "dirty_paths": dirty_paths, + "fingerprints": fingerprints, + "ok": not reasons, + "reasons": reasons, + "tracked_dirty": parse_dirty_tracked_files(porcelain), + } + + +def revalidate_complete_dirty_inventory( + worktree_path: str, + *, + expected_dirty_paths: Sequence[str] | None, + expected_fingerprints: Mapping[str, str] | None, + phase: str = "inventory", +) -> dict[str, Any]: + """Collect the full dirty inventory and require exact pin equality (#868 F1). + + Unlike fingerprint-only checks over the expected path list, this recollects + the authoritative tracked+untracked inventory and refuses added, removed, + or renamed paths as well as fingerprint movement. + """ + reasons: list[str] = [] + inv = collect_dirty_inventory(worktree_path) + if inv.get("ok") is False: + reasons.extend(list(inv.get("reasons") or []) or [f"{phase}: dirty inventory collection failed"]) + + observed_paths = sorted( + {_text(p) for p in (inv.get("dirty_paths") or []) if _text(p)} + ) + pin_paths = sorted( + {_text(p) for p in (expected_dirty_paths or []) if _text(p)} + ) + if not pin_paths: + reasons.append( + f"{phase}: expected_dirty_paths pin is empty; complete inventory " + "revalidation requires a non-empty pin (fail closed)" + ) + if set(observed_paths) != set(pin_paths): + extra = sorted(set(observed_paths) - set(pin_paths)) + missing = sorted(set(pin_paths) - set(observed_paths)) + if extra: + reasons.append( + f"{phase}: complete dirty inventory path-set disagreement: " + f"unexpected paths {extra}" + ) + if missing: + reasons.append( + f"{phase}: complete dirty inventory path-set disagreement: " + f"missing expected paths {missing}" + ) + + obs_fps = { + _text(k): _text(v) + for k, v in dict(inv.get("fingerprints") or {}).items() + if _text(k) + } + pin_fps = { + _text(k): _text(v) + for k, v in dict(expected_fingerprints or {}).items() + if _text(k) + } + if not pin_fps: + reasons.append( + f"{phase}: expected_fingerprints pin is empty; byte-level pins " + "are required (fail closed)" + ) + else: + for rel, expected_hash in pin_fps.items(): + if rel not in set(pin_paths): + reasons.append( + f"{phase}: expected_fingerprints contains '{rel}' which is " + "not in expected_dirty_paths" + ) + continue + actual_hash = obs_fps.get(rel) + if not actual_hash: + reasons.append( + f"{phase}: fingerprint missing for dirty path '{rel}'" + ) + elif actual_hash != expected_hash: + reasons.append( + f"{phase}: fingerprint disagreement for '{rel}': " + f"observed {actual_hash}, expected {expected_hash}" + ) + for rel in observed_paths: + if rel not in pin_fps: + reasons.append( + f"{phase}: observed dirty path '{rel}' has no fingerprint pin" + ) + + return { + "ok": not reasons, + "reasons": reasons, + "inventory": inv, + "observed_dirty_paths": observed_paths, + "expected_dirty_paths": pin_paths, + "observed_fingerprints": obs_fps, + "expected_fingerprints": pin_fps, + "phase": phase, + } + + +def build_journal_operation_identity( + *, + remote: str, + org: str, + repo: str, + claimant_identity: str | None, + claimant_profile: str | None, +) -> dict[str, str]: + """Return the five-field durable operation identity for the recovery journal.""" + return { + "remote": _text(remote), + "org": _text(org), + "repo": _text(repo), + "claimant_identity": _text(claimant_identity), + "claimant_profile": _text(claimant_profile), + } + + +def validate_journal_operation_identity( + journal: Mapping[str, Any] | None, + *, + remote: str, + org: str, + repo: str, + claimant_identity: str | None, + claimant_profile: str | None, + require_present: bool = True, +) -> list[str]: + """Validate durable journal identity fields (#868 F2). + + Rejects missing, mismatched, stale, cross-repository, or cross-claimant + journal state. When *require_present* is True, incomplete legacy journals + (any of the five fields absent/empty) fail closed. + """ + reasons: list[str] = [] + if not isinstance(journal, Mapping): + if require_present: + reasons.append( + "recovery journal is missing or unreadable; complete operation " + "identity cannot be proven (fail closed)" + ) + return reasons + + expected = build_journal_operation_identity( + remote=remote, + org=org, + repo=repo, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + ) + for field in REQUIRED_JOURNAL_IDENTITY_FIELDS: + observed = _text(journal.get(field)) + want = expected[field] + if not observed: + reasons.append( + f"recovery journal omits operation identity field '{field}' " + "(incomplete legacy or malformed journal identity; fail closed)" + ) + continue + if not want: + reasons.append( + f"caller pin for journal identity field '{field}' is empty " + "(fail closed)" + ) + continue + if observed != want: + reasons.append( + f"recovery journal identity mismatch for '{field}': " + f"journal={observed!r}, expected={want!r} " + "(cross-repository / cross-claimant / replay refused)" + ) + return reasons + + +def journal_path(lock_dir: str, issue_number: int) -> str: + root = (lock_dir or "").strip() + return os.path.join(root, f".rebind-journal-{int(issue_number)}.json") + + +def _atomic_write_json(path: str, data: dict[str, Any]) -> None: + parent = os.path.dirname(path) or "." + os.makedirs(parent, mode=0o700, exist_ok=True) + payload = json.dumps(data, indent=2, sort_keys=True) + "\n" + fd, temp_path = tempfile.mkstemp(prefix=".rebind-j-", suffix=".json", dir=parent) + try: + with os.fdopen(fd, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) + os.replace(temp_path, path) + finally: + if os.path.exists(temp_path): + try: + os.remove(temp_path) + except OSError: + pass + + +def _read_json(path: str) -> dict[str, Any] | None: + if not path or not os.path.exists(path): + return None + try: + with open(path, encoding="utf-8") as handle: + data = json.load(handle) + except (OSError, json.JSONDecodeError): + return None + return data if isinstance(data, dict) else None + + +def _malformed_lock_reasons(lock: Mapping[str, Any]) -> list[str]: + missing: list[str] = [] + for field in REQUIRED_LOCK_FIELDS: + if not _text(lock.get(field)): + missing.append(field) + pid = _recorded_pid(lock) + if pid is None or _text(pid) == "": + missing.append("session_pid/pid") + else: + try: + if int(pid) <= 0: + missing.append("session_pid/pid") + except (TypeError, ValueError): + missing.append("session_pid/pid") + return missing + + +def _canonical_under_branches(worktree_path: str, repo_root: str | None) -> tuple[bool, list[str]]: + """Prove worktree is a realpath under ``/branches/`` with no symlink escape.""" + reasons: list[str] = [] + path = (worktree_path or "").strip() + if not path: + return False, ["worktree path is empty"] + try: + real = os.path.realpath(path) + except OSError as exc: + return False, [f"worktree path could not be realpath-resolved: {exc}"] + if not os.path.isdir(real): + reasons.append(f"worktree path '{path}' is not an existing directory") + + root = (repo_root or "").strip() + if root: + try: + root_real = os.path.realpath(root) + except OSError as exc: + return False, [f"repo root could not be realpath-resolved: {exc}"] + if not is_path_under_branches(real, root_real): + reasons.append( + f"worktree '{real}' is not under branches/ of repo root '{root_real}' " + "(unregistered/noncanonical worktree; fail closed)" + ) + # Symlink escape: the declared path must not resolve outside branches/. + declared_abs = os.path.abspath(path) + if os.path.islink(path) or declared_abs != real: + if not is_path_under_branches(real, root_real): + reasons.append( + f"worktree path '{path}' escapes branches/ via symlink/realpath " + f"(resolves to '{real}')" + ) + else: + # Without an explicit repo root, still require a /branches/ segment. + if not is_path_under_branches(real, None): + reasons.append( + f"worktree '{real}' is not under a branches/ directory " + "(unregistered/noncanonical worktree; fail closed)" + ) + return not reasons, reasons + + +def assess_dirty_same_claimant_session_rebind( + *, + remote: str, + org: str, + repo: str, + issue_number: int, + branch_name: str, + worktree_path: str, + claimant_identity: str | None, + claimant_profile: str | None, + old_pid: int | None, + expected_local_head: str | None, + expected_remote_head: str | None, + expected_dirty_paths: Sequence[str] | None, + expected_fingerprints: Mapping[str, str] | None, + existing_lock: Mapping[str, Any] | None, + current_identity: str | None, + current_profile: str | None, + role_kind: str | None, + current_pid: int | None, + current_branch: str | None, + local_head: str | None, + remote_head: str | None, + porcelain_status: str | None = None, + dirty_inventory: Mapping[str, Any] | None = None, + competing_live_locks: Sequence[Mapping[str, Any]] | None = None, + competing_sessions: Sequence[Mapping[str, Any]] | None = None, + workflow_lease_active: bool = False, + authorize_reconciler_execute: bool = False, + permission_allowed: bool = False, + repo_root: str | None = None, +) -> dict[str, Any]: + """Pure assessment: may this dirty same-claimant lock be session-rebound? + + Every pin must agree. ``permission_allowed=True`` alone is never ownership + proof. Fail closed on live old PID, foreign identity/profile, pin mismatch, + unregistered/noncanonical worktree, head movement, dirty path/fingerprint + disagreement, competing ownership, malformed lock, empty PID, wrong role. + """ + reasons: list[str] = [] + evidence: dict[str, Any] = { + "issue_number": issue_number, + "branch_name": branch_name, + "worktree_path": worktree_path, + "remote": remote, + "org": org, + "repo": repo, + "old_pid": old_pid, + "current_pid": current_pid if current_pid is not None else os.getpid(), + "role_kind": _text(role_kind).lower() or None, + "permission_allowed": bool(permission_allowed), + } + + if not existing_lock: + return _assessment_result( + NO_CANDIDATE, + False, + ["no existing durable lock for this issue; not a rebind candidate"], + evidence, + ) + + lock = dict(existing_lock) + if lock.get("issue_number") != issue_number: + return _assessment_result( + NO_CANDIDATE, + False, + [ + f"existing lock targets issue #{lock.get('issue_number')}, " + f"not #{issue_number}; not a rebind candidate" + ], + evidence, + ) + + missing = _malformed_lock_reasons(lock) + if missing: + return _assessment_result( + REFUSED, + False, + [ + "durable lock record is incomplete and cannot prove ownership " + f"(missing/unusable: {', '.join(missing)})" + ], + evidence, + ) + + recorded_pid = _recorded_pid(lock) + evidence["recorded_pid"] = recorded_pid + evidence["lock_generation"] = lock_generation(lock) + + # ── Role gate ─────────────────────────────────────────────────────────── + role = _text(role_kind).lower() + if role in {"reviewer", "merger"}: + reasons.append( + f"role '{role}' cannot rebind dirty same-claimant author sessions " + "(fail closed)" + ) + elif role == "reconciler": + if not authorize_reconciler_execute: + reasons.append( + "reconciler role requires authorize_reconciler_execute=True " + "to execute dirty same-claimant rebind (fail closed)" + ) + elif role == "author": + pass + elif role: + reasons.append(f"role '{role}' is not authorized for dirty same-claimant rebind") + else: + reasons.append("role_kind is unknown; dirty same-claimant rebind refused") + + # permission_allowed is explicitly NOT ownership proof + evidence["note_permission_not_ownership"] = ( + "permission_allowed is not treated as ownership proof" + ) + + # ── Repository / issue / branch / worktree pins ───────────────────────── + for field, expected in (("remote", remote), ("org", org), ("repo", repo)): + actual = _text(lock.get(field)) + if actual != _text(expected): + reasons.append( + f"lock {field} '{actual}' does not match requested '{_text(expected)}'" + ) + + locked_branch = _text(lock.get("branch_name")) + if locked_branch != _text(branch_name): + reasons.append( + f"lock branch '{locked_branch}' does not match requested " + f"'{_text(branch_name)}'" + ) + + checked_out = _text(current_branch) + if not checked_out: + reasons.append( + "worktree is not on a named branch (detached HEAD); locked-branch " + "occupancy could not be proven" + ) + elif checked_out != locked_branch: + reasons.append( + f"worktree is on branch '{checked_out}', not the locked branch " + f"'{locked_branch}'" + ) + + locked_worktree = _text(lock.get("worktree_path")) + if not _same_realpath(locked_worktree, worktree_path): + reasons.append( + f"lock worktree '{locked_worktree}' does not match declared " + f"'{_text(worktree_path)}'" + ) + evidence["locked_worktree_path"] = locked_worktree + + under_ok, under_reasons = _canonical_under_branches(worktree_path, repo_root) + if not under_ok: + reasons.extend(under_reasons) + + # ── old_pid pin + liveness ────────────────────────────────────────────── + if old_pid is None or _text(old_pid) == "": + reasons.append("old_pid pin is empty; rebind refused (fail closed)") + else: + try: + old_pid_i = int(old_pid) + except (TypeError, ValueError): + reasons.append(f"old_pid '{old_pid}' is not a valid PID") + old_pid_i = None + if old_pid_i is not None: + if old_pid_i <= 0: + reasons.append("old_pid must be a positive integer (fail closed)") + try: + recorded_i = int(recorded_pid) + except (TypeError, ValueError): + recorded_i = None + if recorded_i is None or recorded_i != old_pid_i: + reasons.append( + f"old_pid {old_pid_i} does not match lock session_pid/pid " + f"{recorded_pid}" + ) + if is_process_alive(old_pid_i): + reasons.append( + f"old_pid {old_pid_i} is still alive; dirty same-claimant " + "rebind requires a provably dead owner (fail closed)" + ) + evidence["old_pid_alive"] = is_process_alive(old_pid_i) + if current_pid is not None: + try: + if int(current_pid) == old_pid_i: + reasons.append( + "old_pid is the current session PID; nothing to rebind" + ) + except (TypeError, ValueError): + pass + + # ── Claimant identity / profile ───────────────────────────────────────── + lock_claimant = _lock_claimant(lock) + locked_identity = _text(lock_claimant.get("username")) + locked_profile = _text(lock_claimant.get("profile")) + pin_identity = _text(claimant_identity) + pin_profile = _text(claimant_profile) + active_identity = _text(current_identity) + active_profile = _text(current_profile) + evidence["locked_identity"] = locked_identity or None + evidence["locked_profile"] = locked_profile or None + + if not locked_identity or not locked_profile: + reasons.append( + "durable lock does not record a claimant identity/profile; " + "ownership could not be proven" + ) + if not pin_identity or not pin_profile: + reasons.append( + "claimant_identity/claimant_profile pins are required (fail closed)" + ) + if locked_identity and pin_identity and locked_identity != pin_identity: + reasons.append( + f"claimant_identity pin '{pin_identity}' does not match lock " + f"claimant '{locked_identity}'" + ) + if locked_profile and pin_profile and locked_profile != pin_profile: + reasons.append( + f"claimant_profile pin '{pin_profile}' does not match lock profile " + f"'{locked_profile}'" + ) + + # Author path: active session must be the same claimant. Reconciler execute + # may rebind for the recorded claimant when explicitly authorized. + if role == "author": + if not active_identity or not active_profile: + reasons.append( + "active session identity/profile is unknown; author ownership " + "could not be proven" + ) + if locked_identity and active_identity and locked_identity != active_identity: + reasons.append( + f"lock claimant '{locked_identity}' does not match active " + f"identity '{active_identity}' (foreign claimant refused)" + ) + if locked_profile and active_profile and locked_profile != active_profile: + reasons.append( + f"lock profile '{locked_profile}' does not match active profile " + f"'{active_profile}' (profile mismatch refused)" + ) + if pin_identity and active_identity and pin_identity != active_identity: + reasons.append( + f"claimant_identity pin '{pin_identity}' does not match active " + f"identity '{active_identity}'" + ) + if pin_profile and active_profile and pin_profile != active_profile: + reasons.append( + f"claimant_profile pin '{pin_profile}' does not match active " + f"profile '{active_profile}'" + ) + + # ── Heads (must match pins and each other for this rebind class) ──────── + obs_local = _text(local_head) + obs_remote = _text(remote_head) + pin_local = _text(expected_local_head) + pin_remote = _text(expected_remote_head) + evidence["local_head"] = obs_local or None + evidence["remote_head"] = obs_remote or None + evidence["expected_local_head"] = pin_local or None + evidence["expected_remote_head"] = pin_remote or None + + if not pin_local or not pin_remote: + reasons.append( + "expected_local_head and expected_remote_head pins are required " + "(fail closed)" + ) + if not obs_local: + reasons.append("local head SHA could not be determined") + if not obs_remote: + reasons.append("remote head SHA could not be determined") + if pin_local and obs_local and pin_local != obs_local: + reasons.append( + f"local head moved or mismatched pin: observed {obs_local}, " + f"expected {pin_local}" + ) + if pin_remote and obs_remote and pin_remote != obs_remote: + reasons.append( + f"remote head moved or mismatched pin: observed {obs_remote}, " + f"expected {pin_remote}" + ) + if obs_local and obs_remote and obs_local != obs_remote: + # Dirty rebind does not allow unpublished head movement; heads must agree. + reasons.append( + f"local head {obs_local} does not match remote head {obs_remote}; " + "dirty same-claimant rebind requires matching heads (fail closed)" + ) + + # ── Dirty inventory + fingerprint pins ────────────────────────────────── + inv: dict[str, Any] + if isinstance(dirty_inventory, Mapping) and dirty_inventory.get("dirty_paths") is not None: + inv = dict(dirty_inventory) + if not inv.get("fingerprints") and porcelain_status is not None: + # Allow fingerprints-only refresh via recompute if needed. + pass + elif porcelain_status is not None: + # Porcelain alone proves path set, not bytes. Fingerprints must come from + # dirty_inventory (or apply()'s collect_dirty_inventory) — never from the + # caller's expected_fingerprints pin (that would make the pin tautological). + dirty_paths_obs = parse_dirty_paths(porcelain_status) + inv = { + "porcelain_status": porcelain_status, + "dirty_paths": dirty_paths_obs, + "fingerprints": {}, + "ok": True, + "reasons": [], + } + else: + reasons.append( + "neither dirty_inventory nor porcelain_status was provided; " + "dirty state could not be proven" + ) + inv = {"dirty_paths": [], "fingerprints": {}, "ok": False} + + if inv.get("ok") is False and inv.get("reasons"): + reasons.extend(list(inv.get("reasons") or [])) + + observed_paths = sorted({_text(p) for p in (inv.get("dirty_paths") or []) if _text(p)}) + pin_paths = sorted({_text(p) for p in (expected_dirty_paths or []) if _text(p)}) + evidence["observed_dirty_paths"] = observed_paths + evidence["expected_dirty_paths"] = pin_paths + + if not pin_paths: + reasons.append( + "expected_dirty_paths pin is empty; dirty same-claimant rebind " + "requires a non-empty dirty inventory pin (fail closed)" + ) + if set(observed_paths) != set(pin_paths): + extra = sorted(set(observed_paths) - set(pin_paths)) + missing_p = sorted(set(pin_paths) - set(observed_paths)) + if extra: + reasons.append( + f"dirty path set disagreement: unexpected paths {extra}" + ) + if missing_p: + reasons.append( + f"dirty path set disagreement: missing expected paths {missing_p}" + ) + + obs_fps = { + _text(k): _text(v) + for k, v in dict(inv.get("fingerprints") or {}).items() + if _text(k) + } + pin_fps = { + _text(k): _text(v) + for k, v in dict(expected_fingerprints or {}).items() + if _text(k) + } + evidence["observed_fingerprints"] = obs_fps + evidence["expected_fingerprints"] = pin_fps + + if not pin_fps: + reasons.append( + "expected_fingerprints pin is empty; byte-level pins are required " + "(fail closed)" + ) + else: + for rel, expected_hash in pin_fps.items(): + if rel not in set(pin_paths): + reasons.append( + f"expected_fingerprints contains '{rel}' which is not in " + "expected_dirty_paths" + ) + actual_hash = obs_fps.get(rel) + if not actual_hash: + reasons.append( + f"fingerprint missing for dirty path '{rel}'" + ) + elif actual_hash != expected_hash: + reasons.append( + f"fingerprint disagreement for '{rel}': observed " + f"{actual_hash}, expected {expected_hash}" + ) + for rel in obs_fps: + if rel in set(pin_paths) and rel not in pin_fps: + reasons.append( + f"expected_fingerprints missing pin for observed dirty path '{rel}'" + ) + + # ── Competing ownership ───────────────────────────────────────────────── + competing: list[dict[str, Any]] = [] + for entry in competing_live_locks or (): + if not isinstance(entry, Mapping): + continue + same_issue = entry.get("issue_number") == issue_number + same_branch = _text(entry.get("branch_name")) == locked_branch + if not (same_issue or same_branch): + continue + if ( + same_issue + and same_branch + and _same_realpath(_text(entry.get("worktree_path")), worktree_path) + ): + # The lock we are rebinding is not competition with itself, but a + # *live* competing owner on the same worktree is still a problem. + entry_pid = entry.get("pid") or entry.get("session_pid") + try: + entry_pid_i = int(entry_pid) if entry_pid is not None else None + except (TypeError, ValueError): + entry_pid_i = None + if entry_pid_i is not None and is_process_alive(entry_pid_i): + if old_pid is None or entry_pid_i != int(old_pid): + competing.append( + { + "issue_number": entry.get("issue_number"), + "branch_name": entry.get("branch_name"), + "worktree_path": entry.get("worktree_path"), + "pid": entry_pid_i, + } + ) + continue + competing.append( + { + "issue_number": entry.get("issue_number"), + "branch_name": entry.get("branch_name"), + "worktree_path": entry.get("worktree_path"), + "pid": entry.get("pid") or entry.get("session_pid"), + } + ) + if competing: + described = ", ".join( + f"issue #{c['issue_number']} branch '{c['branch_name']}' pid={c.get('pid')}" + for c in competing + ) + reasons.append(f"competing live lock exists ({described})") + evidence["competing_live_locks"] = competing + + competing_sess: list[dict[str, Any]] = [] + for entry in competing_sessions or (): + if not isinstance(entry, Mapping): + continue + sess_pid = entry.get("pid") or entry.get("session_pid") + try: + sess_pid_i = int(sess_pid) if sess_pid is not None else None + except (TypeError, ValueError): + sess_pid_i = None + if sess_pid_i is None: + continue + if current_pid is not None and sess_pid_i == int(current_pid): + continue + if old_pid is not None: + try: + if sess_pid_i == int(old_pid) and not is_process_alive(sess_pid_i): + continue + except (TypeError, ValueError): + pass + if is_process_alive(sess_pid_i) or entry.get("live") is True: + competing_sess.append( + { + "pid": sess_pid_i, + "lock_file_path": entry.get("lock_file_path"), + } + ) + if competing_sess: + reasons.append( + "competing live session pointer(s) claim this lock: " + + ", ".join(str(s["pid"]) for s in competing_sess) + ) + evidence["competing_sessions"] = competing_sess + + if workflow_lease_active: + reasons.append( + "workflow lease is active for this scope; dirty same-claimant " + "rebind refused (fail closed)" + ) + evidence["workflow_lease_active"] = bool(workflow_lease_active) + + if reasons: + return _assessment_result(REFUSED, False, reasons, evidence) + + proof = [ + f"registered dirty worktree for issue #{issue_number} on branch " + f"'{locked_branch}' matches claimant '{locked_identity}' / profile " + f"'{locked_profile}'; old_pid {recorded_pid} is dead; heads " + f"{obs_local} match; {len(pin_paths)} dirty paths fingerprint-pinned; " + "provenance-only rebind sanctioned" + ] + return _assessment_result(REBIND_SANCTIONED, True, proof, evidence) + + +def _assessment_result( + outcome: str, + sanctioned: bool, + reasons: list[str], + evidence: dict[str, Any], +) -> dict[str, Any]: + return { + "outcome": outcome, + "rebind_sanctioned": sanctioned, + "is_candidate": outcome != NO_CANDIDATE, + "reasons": reasons, + "evidence": evidence, + "expected_generation": evidence.get("lock_generation"), + } + + +def _already_rebound( + *, + existing_lock: Mapping[str, Any], + current_pid: int, + worktree_path: str, + expected_dirty_paths: Sequence[str] | None, + expected_fingerprints: Mapping[str, str], + worktree_for_fps: str, + remote: str, + org: str, + repo: str, + claimant_identity: str | None, + claimant_profile: str | None, + journal: Mapping[str, Any] | None = None, +) -> tuple[bool, list[str]]: + """Return (True, notes) when lock is already rebound to this session. + + #868: require complete matching operation identity (remote/org/repo/ + claimant) and complete dirty-inventory revalidation, not fingerprint-only + checks. Incomplete or mismatched journal identity fails closed. + """ + notes: list[str] = [] + pid = _recorded_pid(existing_lock) + try: + pid_i = int(pid) if pid is not None else None + except (TypeError, ValueError): + return False, [] + if pid_i != int(current_pid): + return False, [] + if not _same_realpath(_text(existing_lock.get("worktree_path")), worktree_path): + return False, [] + + # Durable lock repo binding must still match the caller's target. + for field, expected in (("remote", remote), ("org", org), ("repo", repo)): + observed = _text(existing_lock.get(field)) + want = _text(expected) + if observed and want and observed != want: + notes.append( + f"already_rebound refused: lock {field}={observed!r} does not " + f"match expected {want!r} (cross-repository replay)" + ) + return False, notes + + lock_claimant = _lock_claimant(existing_lock) + locked_identity = _text(lock_claimant.get("username")) + locked_profile = _text(lock_claimant.get("profile")) + pin_identity = _text(claimant_identity) + pin_profile = _text(claimant_profile) + if pin_identity and locked_identity and pin_identity != locked_identity: + notes.append( + f"already_rebound refused: lock claimant '{locked_identity}' does " + f"not match pin '{pin_identity}' (cross-claimant replay)" + ) + return False, notes + if pin_profile and locked_profile and pin_profile != locked_profile: + notes.append( + f"already_rebound refused: lock profile '{locked_profile}' does " + f"not match pin '{pin_profile}' (cross-claimant replay)" + ) + return False, notes + + # When a durable journal is present, require complete matching identity. + if isinstance(journal, Mapping) and journal: + id_reasons = validate_journal_operation_identity( + journal, + remote=remote, + org=org, + repo=repo, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + require_present=True, + ) + if id_reasons: + notes.extend(id_reasons) + return False, notes + + inv_check = revalidate_complete_dirty_inventory( + worktree_for_fps, + expected_dirty_paths=expected_dirty_paths, + expected_fingerprints=expected_fingerprints, + phase="already_rebound", + ) + if not inv_check["ok"]: + notes.extend(list(inv_check["reasons"] or [])) + return False, notes + + gen = lock_generation(existing_lock) + if gen < 1: + # A never-written generation is suspicious for a completed rebind, but + # a same-pid lock with matching fingerprints is still "ours". + notes.append("lock generation is 0; treating same-pid match as rebound") + return True, notes or ["lock already bound to current session PID"] + + +def apply_dirty_same_claimant_session_rebind( + *, + remote: str, + org: str, + repo: str, + issue_number: int, + branch_name: str, + worktree_path: str, + claimant_identity: str | None, + claimant_profile: str | None, + old_pid: int | None, + expected_local_head: str | None, + expected_remote_head: str | None, + expected_dirty_paths: Sequence[str] | None, + expected_fingerprints: Mapping[str, str] | None, + existing_lock: Mapping[str, Any] | None, + current_identity: str | None, + current_profile: str | None, + role_kind: str | None, + current_pid: int | None = None, + current_branch: str | None, + local_head: str | None, + remote_head: str | None, + porcelain_status: str | None = None, + dirty_inventory: Mapping[str, Any] | None = None, + competing_live_locks: Sequence[Mapping[str, Any]] | None = None, + competing_sessions: Sequence[Mapping[str, Any]] | None = None, + workflow_lease_active: bool = False, + authorize_reconciler_execute: bool = False, + permission_allowed: bool = False, + repo_root: str | None = None, + dry_run: bool = False, + lock_dir: str | None = None, +) -> dict[str, Any]: + """Assess and (unless dry_run) apply a dirty same-claimant session rebind.""" + pid_now = int(current_pid) if current_pid is not None else os.getpid() + wt = os.path.realpath((worktree_path or "").strip()) if worktree_path else "" + + # Prefer a live inventory when applying so fingerprints are re-observed. + inv = dict(dirty_inventory) if isinstance(dirty_inventory, Mapping) else None + if inv is None and wt: + inv = collect_dirty_inventory(wt) + + assessment = assess_dirty_same_claimant_session_rebind( + remote=remote, + org=org, + repo=repo, + issue_number=issue_number, + branch_name=branch_name, + worktree_path=worktree_path, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + old_pid=old_pid, + expected_local_head=expected_local_head, + expected_remote_head=expected_remote_head, + expected_dirty_paths=expected_dirty_paths, + expected_fingerprints=expected_fingerprints, + existing_lock=existing_lock, + current_identity=current_identity, + current_profile=current_profile, + role_kind=role_kind, + current_pid=pid_now, + current_branch=current_branch, + local_head=local_head, + remote_head=remote_head, + porcelain_status=porcelain_status + if porcelain_status is not None + else (inv or {}).get("porcelain_status"), + dirty_inventory=inv, + competing_live_locks=competing_live_locks, + competing_sessions=competing_sessions, + workflow_lease_active=workflow_lease_active, + authorize_reconciler_execute=authorize_reconciler_execute, + permission_allowed=permission_allowed, + repo_root=repo_root, + ) + + base_result: dict[str, Any] = { + "success": False, + "dry_run": bool(dry_run), + "outcome": assessment["outcome"], + "rebind_sanctioned": assessment["rebind_sanctioned"], + "reasons": list(assessment.get("reasons") or []), + "evidence": assessment.get("evidence") or {}, + "old_pid": old_pid, + "new_pid": pid_now, + "already_rebound": False, + "dirty_paths": list(expected_dirty_paths or []), + "fingerprints": dict(expected_fingerprints or {}), + "local_head": local_head, + "remote_head": remote_head, + } + + root_for_journal = (lock_dir or "").strip() or None + if root_for_journal is None and isinstance(existing_lock, Mapping): + root_for_journal = os.path.dirname( + _text(existing_lock.get("lock_file_path")) + or lock_file_path( + remote=remote, org=org, repo=repo, issue_number=issue_number + ) + ) + jpath_probe = ( + journal_path(root_for_journal, issue_number) if root_for_journal else "" + ) + existing_journal = _read_json(jpath_probe) if jpath_probe else None + + # Resume / retry: reject incomplete, mismatched, or cross-repo journal + # identity before treating any prior journal as authoritative (#868 F2). + if isinstance(existing_journal, Mapping) and existing_journal: + journal_id_reasons = validate_journal_operation_identity( + existing_journal, + remote=remote, + org=org, + repo=repo, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + require_present=True, + ) + # Incomplete legacy journals from pre-#868 apply paths must fail closed + # when any identity field is missing — even if the rest of the payload + # looks familiar. Only a complete matching identity may proceed. + phase = _text(existing_journal.get("phase")) + if journal_id_reasons and phase not in ("", JOURNAL_PHASE_COMPLETE): + # Allow a completed journal with missing legacy identity only when + # already_rebound path will re-validate lock + inventory; for + # mid-flight incomplete journals, refuse. + if phase in ( + JOURNAL_PHASE_ASSESSED, + JOURNAL_PHASE_PRE_BIND, + JOURNAL_PHASE_BOUND, + "bind_failed", + ): + return { + **base_result, + "success": False, + "reasons": journal_id_reasons, + "journal_path": jpath_probe, + "journal_phase": phase or None, + } + + # Retry-safe: if already rebound to this session, succeed even when assess + # refuses because old_pid no longer matches the (updated) lock. + if ( + isinstance(existing_lock, Mapping) + and expected_fingerprints + and wt + ): + done, notes = _already_rebound( + existing_lock=existing_lock, + current_pid=pid_now, + worktree_path=worktree_path, + expected_dirty_paths=expected_dirty_paths, + expected_fingerprints=expected_fingerprints, + worktree_for_fps=wt, + remote=remote, + org=org, + repo=repo, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + journal=existing_journal, + ) + if done: + lock_path = _text(existing_lock.get("lock_file_path")) or lock_file_path( + remote=remote, + org=org, + repo=repo, + issue_number=issue_number, + lock_dir=lock_dir, + ) + session_ptr = os.path.join( + (lock_dir or os.path.dirname(lock_path) or "."), + f"session-{pid_now}.json", + ) + return { + **base_result, + "success": True, + "outcome": REBIND_SANCTIONED, + "rebind_sanctioned": True, + "already_rebound": True, + "reasons": notes, + "lock_path": lock_path, + "session_pointer": session_ptr, + "generation_before": lock_generation(existing_lock), + "generation_after": lock_generation(existing_lock), + "journal_phase": JOURNAL_PHASE_ALREADY_REBOUND, + } + # Same-pid candidate that failed complete identity/inventory checks + # must not fall through into a fresh bind that would re-mint authority. + if _recorded_pid(existing_lock) is not None: + try: + if int(_recorded_pid(existing_lock)) == int(pid_now) and notes: + return { + **base_result, + "success": False, + "already_rebound": False, + "reasons": notes, + "journal_path": jpath_probe or None, + } + except (TypeError, ValueError): + pass + + if not assessment["rebind_sanctioned"]: + return base_result + + if dry_run: + return { + **base_result, + "success": True, + "message": "dry_run: rebind sanctioned; no lock/session writes performed", + "generation_before": assessment.get("expected_generation"), + "generation_after": assessment.get("expected_generation"), + } + + lock = dict(existing_lock or {}) + gen_before = lock_generation(lock) + root = (lock_dir or "").strip() or None + jpath = journal_path( + root or os.path.dirname( + _text(lock.get("lock_file_path")) + or lock_file_path( + remote=remote, org=org, repo=repo, issue_number=issue_number + ) + ), + issue_number, + ) + + op_identity = build_journal_operation_identity( + remote=remote, + org=org, + repo=repo, + claimant_identity=claimant_identity, + claimant_profile=claimant_profile, + ) + # Refuse incomplete caller identity before any durable write. + for field, value in op_identity.items(): + if not value: + return { + **base_result, + "success": False, + "reasons": [ + f"cannot write recovery journal: operation identity field " + f"'{field}' is empty (fail closed)" + ], + } + + journal = { + "phase": JOURNAL_PHASE_ASSESSED, + "issue_number": issue_number, + "branch_name": branch_name, + "worktree_path": wt, + "old_pid": old_pid, + "new_pid": pid_now, + "expected_generation": gen_before, + "expected_fingerprints": dict(expected_fingerprints or {}), + "expected_dirty_paths": list(expected_dirty_paths or []), + "local_head": local_head, + "remote_head": remote_head, + "started_at": _utc_now_iso(), + "source": SOURCE, + # #868 F2 — complete durable operation identity + **op_identity, + } + _atomic_write_json(jpath, journal) + + # #868 F1 — complete dirty-inventory revalidation immediately before mutation. + # Fail closed with no bind so failures cannot leave a newly authoritative + # live session. + pre_inv = revalidate_complete_dirty_inventory( + wt, + expected_dirty_paths=expected_dirty_paths, + expected_fingerprints=expected_fingerprints, + phase="pre-bind", + ) + if not pre_inv["ok"]: + journal["phase"] = "pre_bind_inventory_failed" + journal["pre_bind_inventory"] = { + "observed_dirty_paths": pre_inv.get("observed_dirty_paths"), + "reasons": pre_inv.get("reasons"), + } + _atomic_write_json(jpath, journal) + return { + **base_result, + "success": False, + "reasons": list(pre_inv["reasons"] or []), + "journal_path": jpath, + "journal_phase": "pre_bind_inventory_failed", + } + + pre_fps = dict(pre_inv.get("observed_fingerprints") or {}) + + journal["phase"] = JOURNAL_PHASE_PRE_BIND + journal["pre_bind_fingerprints"] = pre_fps + journal["pre_bind_dirty_paths"] = list(pre_inv.get("observed_dirty_paths") or []) + _atomic_write_json(jpath, journal) + + now = _utc_now_iso() + new_lock = dict(lock) + new_lock["session_pid"] = pid_now + new_lock["pid"] = pid_now + new_lock["last_heartbeat_at"] = now + new_lock["remote"] = remote + new_lock["org"] = org + new_lock["repo"] = repo + new_lock["issue_number"] = issue_number + new_lock["branch_name"] = branch_name + new_lock["worktree_path"] = _text(lock.get("worktree_path")) or wt + + # Preserve work_lease (including expires_at); refresh heartbeat only. + lease = new_lock.get("work_lease") + if isinstance(lease, dict): + lease = dict(lease) + lease["last_heartbeat_at"] = now + if not lease.get("operation_type"): + lease["operation_type"] = AUTHOR_ISSUE_WORK_LEASE + new_lock["work_lease"] = lease + + claimant = _lock_claimant(lock) + new_lock["lock_provenance"] = build_sanctioned_lock_provenance( + tool=SOURCE_TOOL, + source=SOURCE, + claimant=claimant or { + "username": claimant_identity, + "profile": claimant_profile, + }, + ) + new_lock["rebind_record"] = { + "source": SOURCE, + "old_pid": old_pid, + "new_pid": pid_now, + "rebound_at": now, + "local_head": local_head, + "remote_head": remote_head, + "dirty_path_count": len(list(expected_dirty_paths or [])), + "generation_before": gen_before, + "evidence": { + "fingerprints": dict(expected_fingerprints or {}), + "dirty_paths": list(expected_dirty_paths or []), + }, + } + + try: + lock_path = bind_session_lock( + new_lock, + lock_dir=root, + expected_generation=gen_before, + ) + except Exception as exc: + journal["phase"] = "bind_failed" + journal["error"] = str(exc) + _atomic_write_json(jpath, journal) + return { + **base_result, + "success": False, + "reasons": [f"bind_session_lock failed: {exc}"], + "journal_path": jpath, + "generation_before": gen_before, + } + + journal["phase"] = JOURNAL_PHASE_BOUND + journal["lock_path"] = lock_path + _atomic_write_json(jpath, journal) + + # #868 F1 — complete dirty-inventory revalidation immediately after mutation. + # Path set must remain exactly equal; fingerprints must be unchanged. + post_inv = revalidate_complete_dirty_inventory( + wt, + expected_dirty_paths=expected_dirty_paths, + expected_fingerprints=expected_fingerprints, + phase="post-bind", + ) + post_fps = dict(post_inv.get("observed_fingerprints") or {}) + if not post_inv["ok"]: + journal["phase"] = "post_bind_inventory_failed" + journal["post_bind_inventory"] = { + "observed_dirty_paths": post_inv.get("observed_dirty_paths"), + "reasons": post_inv.get("reasons"), + } + journal["post_bind_fingerprints"] = post_fps + _atomic_write_json(jpath, journal) + return { + **base_result, + "success": False, + "reasons": list(post_inv["reasons"] or []) + [ + "post-bind complete inventory revalidation failed after " + "bind_session_lock; lock may be rebound but content/path " + "verification failed (fail closed)" + ], + "lock_path": lock_path, + "journal_path": jpath, + "journal_phase": "post_bind_inventory_failed", + "generation_before": gen_before, + "fingerprints_after": post_fps, + } + + # Remove stale session pointer for old_pid when it points at this lock. + removed_old_pointer = False + if old_pid is not None and root: + old_ptr = os.path.join(root, f"session-{int(old_pid)}.json") + if os.path.exists(old_ptr): + ptr = _read_json(old_ptr) or {} + ptr_lock = _text(ptr.get("lock_file_path")) + if not ptr_lock or os.path.realpath(ptr_lock) == os.path.realpath(lock_path): + try: + os.remove(old_ptr) + removed_old_pointer = True + except OSError: + pass + + bound = read_lock_file(lock_path) or new_lock + gen_after = lock_generation(bound) + session_ptr = os.path.join( + root or os.path.dirname(lock_path), + f"session-{pid_now}.json", + ) + + journal["phase"] = JOURNAL_PHASE_COMPLETE + journal["completed_at"] = _utc_now_iso() + journal["generation_after"] = gen_after + journal["removed_old_session_pointer"] = removed_old_pointer + journal["post_bind_fingerprints"] = post_fps + journal["post_bind_dirty_paths"] = list( + post_inv.get("observed_dirty_paths") or [] + ) + _atomic_write_json(jpath, journal) + + return { + **base_result, + "success": True, + "message": ( + f"Rebound dirty same-claimant author session for issue #{issue_number} " + f"from dead pid {old_pid} to pid {pid_now}; dirty bytes preserved" + ), + "lock_path": lock_path, + "session_pointer": session_ptr, + "generation_before": gen_before, + "generation_after": gen_after, + "fingerprints": post_fps, + "fingerprints_before": pre_fps, + "removed_old_session_pointer": removed_old_pointer, + "journal_path": jpath, + "journal_phase": JOURNAL_PHASE_COMPLETE, + "rebind_record": bound.get("rebind_record") or new_lock.get("rebind_record"), + "lock_provenance": bound.get("lock_provenance"), + } + + +def build_issue_860_regression_fixture_spec() -> dict[str, Any]: + """Data-only fixture describing the #860 class scenario (no real mutation). + + Claimant jcwalker3 / prgs-author, dead PID, no live session pointer, seven + dirty paths with fingerprint pins, matching local/remote heads. + """ + dirty_paths = [ + "dirty_same_claimant_session_rebind.py", + "issue_lock_provenance.py", + "task_capability_map.py", + "gitea_mcp_server.py", + "tests/test_dirty_same_claimant_session_rebind.py", + "docs/runbook-dirty-rebind.md", + "scratch/notes-untracked.txt", + ] + # Stable placeholder digests — tests replace with real fingerprints when + # constructing on-disk fixtures. These exist so the spec is self-describing. + fingerprints = { + path: hashlib.sha256(f"issue-860-fixture:{path}".encode()).hexdigest() + for path in dirty_paths + } + head = "a" * 40 + dead = 424860 + return { + "issue_class": "issue-860-dirty-orphan-class-fixture", + "description": ( + "Registered dirty worktree, same claimant, dead owner PID, no live " + "session pointer, seven fingerprint-pinned dirty paths, matching heads. " + "Data only — does not mutate any real worktree." + ), + "remote": "prgs", + "org": "Scaled-Tech-Consulting", + "repo": "Gitea-Tools", + "issue_number": 860, + "branch_name": "fix/issue-860-dirty-orphan-recovery", + "worktree_path": "/scratch/branches/fix-issue-860-dirty-orphan-recovery", + "claimant_identity": "jcwalker3", + "claimant_profile": "prgs-author", + "old_pid": dead, + "old_pid_alive": False, + "live_session_pointer": None, + "expected_local_head": head, + "expected_remote_head": head, + "expected_dirty_paths": dirty_paths, + "expected_fingerprints": fingerprints, + "dirty_path_count": 7, + "role_kind": "author", + "notes": [ + "Distinct from #864 apply path: this fixture documents the #860 class " + "inputs (dead PID + dirty inventory) without remote sync or recovery " + "worktree creation.", + ], + } diff --git a/docs/architecture/mcp-restart-governance.md b/docs/architecture/mcp-restart-governance.md new file mode 100644 index 0000000..2931d10 --- /dev/null +++ b/docs/architecture/mcp-restart-governance.md @@ -0,0 +1,223 @@ +# 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. diff --git a/docs/safety-model.md b/docs/safety-model.md index 31c740a..bbab241 100644 --- a/docs/safety-model.md +++ b/docs/safety-model.md @@ -46,3 +46,17 @@ 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. diff --git a/docs/webui-authz-audit.md b/docs/webui-authz-audit.md new file mode 100644 index 0000000..8776429 --- /dev/null +++ b/docs/webui-authz-audit.md @@ -0,0 +1,295 @@ +# Web console authorization, RBAC, redaction, and audit model (#633) + +**Phase 1. Read-only. This document defines the model that future console +writes must pass through; it enables none of them.** + +The MVP deployment boundary ([`webui-deployment.md`](webui-deployment.md), #435) +documents internal-only serving and states plainly that MVP authentication is +*none* — protection comes from network placement. That is adequate while every +route is a GET, and inadequate the moment a gated write ships. This document +and the three modules it describes land **before** any write exists, so no +Phase 2 action can be added without an authority to check it against. + +| Concern | Module | +|---------|--------| +| Identity, roles, authorization decision | `webui/console_authz.py` | +| Secret redaction for every surface | `webui/console_redaction.py` | +| Audit event schema, retention, sink | `webui/console_audit.py` | +| Machine-readable publication | `GET /api/console/security-model` | + +Two invariants hold everywhere and are non-negotiable for every child of #631: + +1. **No secrets reach the browser.** Credentials are resolved server-side and + redacted before any payload, page, log line, or audit record leaves. +2. **No ungated mutations.** Authorization is necessary but never sufficient; + execution stays disabled until the Phase 2 framework ships. + +## Identity sources + +The console performs *authorization*. Authentication is delegated, because a +console that mints its own sessions is a credential store, and this one must +not be. + +| Source | Mode value | Authenticated | Shared host | Phase | +|--------|-----------|---------------|-------------|-------| +| None | `none` (default) | No — anonymous, capped at `viewer` | No | 1 | +| Local dev | `local-dev` / `local_dev` | Yes, **asserted not verified** | No | 1 | +| Access proxy | `access-proxy` / `access_proxy` | Yes, asserted by trusted proxy | Yes | 2 | + +Selected by `WEBUI_AUTH_MODE`. An unrecognised value falls back to `none` +rather than erroring open. + +**Access-proxy mode** reads the subject from the +`Cf-Access-Authenticated-User-Email` header, set by Cloudflare Access, WARP, or +an equivalent org portal that terminates authentication in front of the +console. If the header is absent the request did not traverse the proxy, so the +principal degrades to anonymous — it is never trusted by default. + +The **role is always server-side configuration**, never a client assertion. It +comes from `WEBUI_ROLE_MAP`, a JSON object of subject → role: + +```json +{"ops@example.com": "operator", "lead@example.com": "controller"} +``` + +An unmapped subject gets `viewer`. Malformed JSON yields an empty map, so +everyone gets `viewer` — a parse failure loses authority rather than granting +it. + +Full SSO is explicitly a non-goal of this issue. + +## Role matrix + +Four roles, ordered least to most authority. Each role inherits every lower +role's actions; the table states the *minimum* rank required. + +| Role | Authority | +|------|-----------| +| `viewer` | Read every console view. No write, ever, in any phase. | +| `operator` | Viewer, plus author-class work: claim, comment, open a PR. | +| `controller` | Operator, plus reviewer/merger-class decisions on a PR. | +| `admin` | Controller, plus destructive and policy-editing actions. | + +`viewer` holds the empty write set by construction, and a test asserts it stays +empty. + +## Privileged actions + +Every console action maps to a `task_key` in `task_capability_map.py`, the same +single source of truth `gitea_resolve_task_capability` and the MCP tool gates +use. The console therefore cannot invent an authority the MCP layer does not +already define, and a regression test asserts each mapping matches. + +| Action | Minimum role | Class | MCP permission | Confirm | Dual control | Break-glass | Phase | +|--------|--------------|-------|----------------|---------|--------------|-------------|-------| +| `claim_issue` | operator | gated_write | `gitea.issue.comment` | Yes | No | No | 2 | +| `comment_issue` | operator | gated_write | `gitea.issue.comment` | Yes | No | No | 2 | +| `create_issue` | operator | gated_write | `gitea.issue.create` | Yes | No | No | 2 | +| `comment_pr` | operator | gated_write | `gitea.pr.comment` | Yes | No | No | 2 | +| `create_pr` | operator | gated_write | `gitea.pr.create` | Yes | No | No | 2 | +| `review_pr` | controller | privileged | `gitea.pr.review` | Yes | No | No | 3 | +| `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 | + +**Dual control** means the acting principal may not be the sole authority: a +second distinct principal must confirm. **Break-glass** means the action is +expected to be unavailable in normal operation and its use is retained for two +years. Both are declared here and enforced by the Phase 2 framework; Phase 1 +records the requirement on every decision so the framework cannot ship without +honouring it. + +`delete_branch` is admin-only rather than controller because it is the one +irreversible action in the set. + +### Authorization decision + +`authorize(action_id, principal, for_execution=False)` returns a decision +record and **denies by default**. The deny reasons are closed and enumerated: + +| Reason code | Meaning | +|-------------|---------| +| `unknown_action` | No such console action is registered. | +| `unauthenticated` | The principal is anonymous. | +| `unknown_role` | The role is not in the matrix. | +| `insufficient_role` | The role ranks below the action's minimum. | +| `phase_not_active` | Execution requested for an action whose phase is not open. | +| `allowed_preview_only` | Authorized — preview only, execution still disabled. | + +There is no implicit allow branch. Even the allow result reports +`execution_enabled: false` while the console is in Phase 1, so no caller can +read an allow as permission to mutate. + +## Secret redaction + +One pass applies to **API payloads, rendered HTML, server logs, and audit +records** — the four surfaces where a credential could escape. + +Redaction reuses `gitea_audit.redact` rather than forking it: that remains the +authority for secret-looking dict keys, `Authorization` material, and raw URLs. +The console layer then applies its own patterns: + +Each rule below matches an *assignment form*: the named key, followed by `=` or +`:`, followed by the value. The keys are listed bare rather than spelled out as +complete assignments, because this document is itself scanned by +`scan_for_secrets` — writing the examples in full assignment form would make the +documentation trip the very detectors it documents. + +| Rule | Catches (as an assignment) | +|------|----------------------------| +| `credential_assignment` | `token`, `password`, `passwd`, `secret`, `api_key`, `access_key`, `client_secret`, `private_key` | +| `credential_env_assignment` | `GITEA_TOKEN`, `GITEA_PASS`, `GITEA_PASSWORD` and suffixed variants | +| `keychain_reference` | `keychain:` entry references | +| `keychain_command` | macOS `security` keychain lookups (`find-generic-password`, `find-internet-password`) | +| `private_key_block` | PEM `BEGIN ... PRIVATE KEY` blocks | +| `json_web_token` | Three-segment `eyJ...` JWTs | +| `bearer_credential` | `Bearer` / `Basic` credentials | + +Assignments keep the key and replace only the value, so an operator can still +see *what* was removed. Two behaviours are deliberate: + +- **Fail closed.** A value that cannot be redacted becomes `[REDACTED]` + outright rather than being emitted raw. Redaction never raises. +- **Redact before persist.** `console_audit.build_event` redacts before + serialization, and `write_event` re-scans and **drops** any record that still + trips a detector. An unredacted record is never durable. + +`scan_for_secrets` is the assertion helper: it returns the detector names still +matching a payload, and already-redacted hits are not findings. Tests use it to +prove the published policy, the security-model endpoint, and this document +itself carry no secret material. + +## Audit event schema + +`gitea_audit` records MCP-side *mutations* — which profile and Gitea user +performed which tool call. It has no console actor, no identity source, no +correlation identifier, and no retention class, and an authorization **denial** +is not a mutation, so it would never appear there at all. The console record is +additive, not a replacement: a Phase 2 action emits both, joined on +`correlation.request_id`. + +Required fields, all asserted by tests so an edit cannot quietly drop one: + +| Field | Content | +|-------|---------| +| `schema_version` | Currently `1`. | +| `event_id` | Unique per record. | +| `timestamp` | Timezone-aware ISO-8601, UTC. | +| `actor` | `subject`, `role`, `identity_source`, `authenticated`. | +| `action` | Console action id. | +| `action_class` | `gated_write`, `privileged`, `destructive`, or `unknown`. | +| `target` | `{kind, ref}`, e.g. `{"kind": "pr", "ref": "#123"}`. | +| `result` | `allowed`, `denied`, `previewed`, `failed`, `succeeded`. | +| `reason_code` | The authorization reason code above. | +| `correlation` | `request_id`, `session_id`, `mcp_task`, `mcp_permission`. | +| `retention` | `class`, `days`, `expires_at`. | +| `redacted` | Always `true`; records are redacted at build time. | + +An unrecognised `result` degrades to `failed` rather than being stored +verbatim. + +The sink is an append-only JSON Lines file named by +`WEBUI_CONSOLE_AUDIT_LOG`. It is **off by default**: with the variable unset, +events are still built — so callers and tests exercise the schema — but nothing +is written. Auditing never raises; a failed write returns `False` rather than +breaking the request it describes. + +## Retention + +| Class | Applies to | Default | +|-------|-----------|---------| +| `standard` | Routine gated writes | 90 days | +| `privileged` | `review_pr`, `close_pr`, and any unclassifiable action | 365 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 +**unknown action is retained as privileged, not standard** — for a safety +control the conservative direction is to keep the record longer. + +Nothing in this module updates or deletes. Expiry is enforced by an +operator-run policy against `expires_at`, never by the console silently +rewriting its own history. + +## Phase 2 integration + +Phase 2 opens gated writes. It must reuse this model rather than introduce a +second one. The integration points are already wired and observable: + +- **`GET /api/actions/{action_id}/preview`** attaches an `authorization` block + to the existing preview payload and records a `previewed` audit event. +- **`POST /api/actions/{action_id}/attempt`** attaches the same block and + records a `denied` event. The terminal outcome is unchanged — the MVP + registry in `webui/gated_actions.py` still fails closed for every action — so + Phase 1 cannot loosen anything. Phase 2 enforces on this same decision + instead of adding a parallel check. +- **`GET /api/console/security-model`** publishes the RBAC matrix, redaction + policy, and audit policy as JSON for operators and tests. + +To open Phase 2, a child issue must: raise `ACTIVE_PHASE`, implement the +confirmation and dual-control flow the matrix already declares, emit a +`succeeded` or `failed` record alongside the `gitea_audit` mutation record, and +keep `viewer` unable to reach any of it. Turning on execution without the +confirmation flow contradicts a declared requirement and is a review failure, +not a shortcut. + +## Local-dev mode + +`WEBUI_AUTH_MODE=local-dev` reads the principal straight from the environment: + +| Variable | Purpose | +|----------|---------| +| `WEBUI_DEV_SUBJECT` | Subject string; absent ⇒ anonymous | +| `WEBUI_DEV_ROLE` | One of `viewer`, `operator`, `controller`, `admin`; unrecognised ⇒ `viewer` | + +**INSECURE — this mode is for loopback development only.** The subject and role +are *asserted by the developer running the process and verified by nothing*. +Anyone able to set an environment variable on the host is an `admin`, and +anyone able to reach the port inherits that principal. It provides no +authentication whatsoever; it exists so Phase 2 authorization paths can be +exercised without standing up a proxy. + +Never enable local-dev mode on a non-loopback bind. Combining it with +`WEBUI_ALLOW_PUBLIC_BIND=1` or `WEBUI_ALLOW_REMOTE_BIND=1` publishes an +unauthenticated admin console. + +For anything beyond a laptop use `access-proxy` mode behind Cloudflare Access, +WARP, or a VPN, as [`webui-deployment.md`](webui-deployment.md) requires. + +### Probe authentication + +`WEBUI_REQUIRE_PROBE_AUTH=1` declares that non-public probes should require an +authenticated principal. It is **opt-in**: the default is off so the MVP +`/health` contract is unchanged. + +**This flag is declarative in Phase 1 and enforces nothing today.** +`console_authz.probe_auth_required()` reports the operator's intent, and no +route consults it — setting the variable does not currently change the +behaviour of `/health` or any other endpoint. It is published here so the Phase +2 action framework has a declared policy to honour rather than inventing a +second one, exactly as `ACTIVE_PHASE` gates execution while the matrix is +already declared. A regression test pins this "declared, not enforced" status, +so wiring it later is a deliberate change rather than a silent one. + +Until Phase 2 wires it, probe protection rests on network placement alone, as +[`webui-deployment.md`](webui-deployment.md) (#435) states. + +## Environment variables + +| Variable | Default | Purpose | +|----------|---------|---------| +| `WEBUI_AUTH_MODE` | `none` | Identity source selection | +| `WEBUI_DEV_SUBJECT` | unset | Local-dev subject (insecure) | +| `WEBUI_DEV_ROLE` | `viewer` | Local-dev role (insecure) | +| `WEBUI_ROLE_MAP` | unset | JSON subject → role map | +| `WEBUI_REQUIRE_PROBE_AUTH` | unset | Require auth for non-public probes | +| `WEBUI_CONSOLE_AUDIT_LOG` | unset | Append-only audit sink path | + +All are read server-side only. None is ever rendered into a page or returned by +an API. + +## Non-goals + +- No full SSO product; authentication stays delegated to the proxy. +- No browser-initiated merges or approvals in any phase covered here. +- No tokens in the frontend, in browser storage, or in committed config. diff --git a/docs/webui-deployment.md b/docs/webui-deployment.md index 22b3906..2ad46ab 100644 --- a/docs/webui-deployment.md +++ b/docs/webui-deployment.md @@ -7,7 +7,10 @@ only. ## MVP deployment model - **Default bind:** `127.0.0.1:8765` (`WEBUI_HOST` / `WEBUI_PORT`) -- **Authentication:** none in MVP — protection comes from network placement +- **Authentication:** none in MVP — protection comes from network placement. + The authorization, RBAC, redaction, and audit model that future gated writes + must pass through is defined in + [`webui-authz-audit.md`](webui-authz-audit.md) (#633). - **Mutations:** read-only routes; gated write actions remain disabled (#434) - **Secrets:** resolved server-side via `gitea_auth` / `GITEA_MCP_CONFIG`; never embedded in HTML, JavaScript, or browser storage @@ -52,6 +55,15 @@ 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 diff --git a/docs/webui-local-dev.md b/docs/webui-local-dev.md index ba2c120..ad3ef66 100644 --- a/docs/webui-local-dev.md +++ b/docs/webui-local-dev.md @@ -52,7 +52,8 @@ status, onboarding checklist state, and the fail-closed error payloads (#635). | Path | Description | |------|-------------| | `/` | Home / operator overview | -| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`) | +| `/health` | JSON liveness (`status`, `service`, `mode`, `timestamp`, `uptime_seconds`) | +| `/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) | @@ -73,11 +74,95 @@ 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 @@ -153,6 +238,26 @@ 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** @@ -259,6 +364,108 @@ or migrates it; paths are collapsed against `$HOME`, URLs lose userinfo and query strings, and credential-shaped values are redacted at the boundary. Lease steal/release and worktree deletion are Phase 2+ and have no representation here. +## 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:`, +`cth:::`), 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 diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py index acd56ca..fb50976 100644 --- a/gitea_mcp_server.py +++ b/gitea_mcp_server.py @@ -234,12 +234,25 @@ def _effective_workspace_role() -> str: def _profile_role_kind(profile: dict) -> str: - """Resolve a profile's declared role before inferring from permissions.""" - role = (profile.get("role") or profile.get("role_kind") or "").strip() + """Resolve a profile's declared role before inferring from permissions. + + Declared ``role`` / ``role_kind`` always wins so a controller profile is + never reclassified as reconciler from permission inference (#840). + """ + role = (profile.get("role") or profile.get("role_kind") or "").strip().lower() if role: + # Normalize aliases / case. + if "control" in role: + return "controller" return role profile_name = (profile.get("profile_name") or "").strip().lower() - for candidate in ("reconciler", "merger", "reviewer", "author"): + for candidate in ( + "controller", + "reconciler", + "merger", + "reviewer", + "author", + ): if candidate in profile_name: return candidate return _role_kind( @@ -427,13 +440,32 @@ def _session_author_lock_worktree() -> str | None: Used to derive the author mutation workspace when no explicit ``worktree_path`` or env binding is provided. Never invents a path. + + #864: a session pointer whose owner PID is dead and is not this process + must not force workspace binding for other issues — rebind is required for + that issue, and a stale dead-owner pointer must not poison unrelated work. """ try: lock = issue_lock_store.read_session_issue_lock() or {} except Exception: return None path = (lock.get("worktree_path") or "").strip() - return path or None + if not path: + return None + pid = lock.get("session_pid") + if pid is None: + pid = lock.get("pid") + try: + pid_i = int(pid) if pid is not None else None + except (TypeError, ValueError): + pid_i = None + if ( + pid_i is not None + and pid_i != os.getpid() + and not issue_lock_store.is_process_alive(pid_i) + ): + return None + return path def _resolve_preflight_workspace_path(worktree_path: str | None = None) -> str: @@ -2018,6 +2050,7 @@ import issue_lock_store # noqa: E402 import issue_lock_adoption # noqa: E402 import issue_lock_recovery # noqa: E402 import issue_lock_renewal # noqa: E402 +import dirty_same_claimant_session_rebind # noqa: E402 # #864 import stacked_pr_support # noqa: E402 import merge_approval_gate # noqa: E402 import review_quarantine # noqa: E402 # #695 contaminated formal-review quarantine @@ -2412,6 +2445,20 @@ def _evaluate_issue_lock_recovery( descendant_sha=local_head, ) + # #871: the inverse of the #768 descendant relation — the *remote* head may + # have advanced past the local/recorded head via a sanctioned merge-based + # branch sync (``gitea_update_pr_branch_by_merge``) while the local worktree + # stayed put. Observe that provenance server-side so the assessor can prove + # it and nothing else. Probed only when the heads differ; never from any + # caller-supplied value. + sync_provenance: dict | None = None + if remote_head and local_head and remote_head != local_head: + sync_provenance = issue_lock_worktree.read_merge_sync_provenance( + worktree_path, + prior_head_sha=local_head, + synced_head_sha=remote_head, + ) + # #772: with no remote branch there is no head to measure against, so the # base the branch was cut from is observed instead. Probed only in that # case, so the published path's evidence is untouched (#772 AC8). @@ -2454,6 +2501,7 @@ def _evaluate_issue_lock_recovery( remote_branch_exists=remote_branch_exists, recorded_base_sha=recorded_base, base_ancestry=base_ancestry, + sync_provenance=sync_provenance, ) @@ -4329,6 +4377,263 @@ def gitea_lock_issue( return result +@mcp.tool() +def gitea_rebind_dirty_same_claimant_author_session( + issue_number: int, + branch_name: str, + worktree_path: str, + old_pid: int, + expected_local_head: str, + expected_remote_head: str, + expected_dirty_paths: list[str], + expected_fingerprints: dict, + remote: str = "dadeschools", + host: str | None = None, + org: str | None = None, + repo: str | None = None, + dry_run: bool = False, + authorize_reconciler_execute: bool = False, +) -> dict: + """Rebind a dirty registered issue worktree to this session (#864). + + Sanctioned only when every pin agrees: same claimant, dead old_pid matching + the durable lock, matching local/remote heads, exact dirty path set, and + per-path sha256 fingerprints. Preserves every tracked/untracked byte. + Does not sync remote, create recovery worktrees, clean, reset, or move heads. + + Role gate: + * author — must match the lock claimant identity/profile + * reconciler — execute only when ``authorize_reconciler_execute=True`` + * reviewer/merger — always refuse + + ``gitea.issue.comment`` (author map entry) is required for mutation; dry_run + still assesses fully but writes nothing. Permission alone is never ownership + proof — every pin is re-checked server-side. + + Args: + issue_number: Tracking issue number on the durable lock. + branch_name: Exact locked branch name. + worktree_path: Registered dirty worktree path (must be under branches/). + old_pid: Dead owner PID recorded on the lock (must match session_pid/pid). + expected_local_head: Full local HEAD sha the caller observed. + expected_remote_head: Full remote-tracking HEAD sha the caller observed. + expected_dirty_paths: Exact set of dirty relative paths (tracked+untracked). + expected_fingerprints: Map of relative path -> sha256 hex of file bytes. + remote: Known instance — 'dadeschools' or 'prgs'. + host/org/repo: Optional target overrides (validated against binding). + dry_run: When true, assess only (no lock/session writes). + authorize_reconciler_execute: Reconciler-only execute gate. + """ + role = _profile_role_kind(get_profile()) + role_norm = (role or "").strip().lower() + + # Permission: authors need comment; dry_run assess is reachable under read + # for diagnosis, but execute always needs comment. Reconciler execute also + # needs comment when authorized. + if dry_run: + read_block = _profile_operation_gate("gitea.read") + if read_block: + return { + "success": False, + "dry_run": True, + "reasons": read_block, + "permission_report": _permission_block_report("gitea.read"), + } + else: + blocked = _profile_permission_block( + task_capability_map.required_permission( + "rebind_dirty_same_claimant_author_session" + ), + issue_number=issue_number, + remote=remote, + host=host, + org=org, + repo=repo, + org_explicit=org is not None, + repo_explicit=repo is not None, + ) + if blocked: + return blocked + + if role_norm in {"reviewer", "merger"}: + return { + "success": False, + "dry_run": bool(dry_run), + "outcome": dirty_same_claimant_session_rebind.REFUSED, + "reasons": [ + f"role '{role_norm}' cannot rebind dirty same-claimant author " + "sessions (fail closed)" + ], + } + if role_norm == "reconciler" and not authorize_reconciler_execute and not dry_run: + return { + "success": False, + "dry_run": False, + "outcome": dirty_same_claimant_session_rebind.REFUSED, + "reasons": [ + "reconciler role requires authorize_reconciler_execute=True " + "to execute dirty same-claimant rebind (fail closed)" + ], + } + + h, o, r = _resolve(remote, host, org, repo) + try: + identity = _authenticated_username(h) + except Exception: + identity = None + profile = get_profile() + profile_name = profile.get("profile_name") + + existing = _load_existing_issue_lock( + remote=remote, org=o, repo=r, issue_number=issue_number + ) + resolved_wt = os.path.realpath(os.path.abspath((worktree_path or "").strip())) + inv = dirty_same_claimant_session_rebind.collect_dirty_inventory(resolved_wt) + + branch_res = subprocess.run( + ["git", "-C", resolved_wt, "branch", "--show-current"], + capture_output=True, + text=True, + check=False, + ) + current_branch = (branch_res.stdout or "").strip() or None + head_res = subprocess.run( + ["git", "-C", resolved_wt, "rev-parse", "HEAD"], + capture_output=True, + text=True, + check=False, + ) + local_head = (head_res.stdout or "").strip() if head_res.returncode == 0 else None + + # Observe remote-tracking head without network when possible. + remote_head = None + for ref in ( + f"refs/remotes/origin/{branch_name}", + f"origin/{branch_name}", + f"refs/remotes/{remote}/{branch_name}", + f"{remote}/{branch_name}", + ): + rh = subprocess.run( + ["git", "-C", resolved_wt, "rev-parse", "--verify", "--quiet", ref], + capture_output=True, + text=True, + check=False, + ) + if rh.returncode == 0 and (rh.stdout or "").strip(): + remote_head = (rh.stdout or "").strip() + break + if remote_head is None: + # Fall back to caller's pin only for observation absence — assessment + # still requires pin==observed, so missing observation fails closed. + remote_head = None + + # Competing live locks (other issues / other worktrees). + competing_live = [] + for entry in issue_lock_store.list_live_locks(): + competing_live.append(entry) + + # Session pointers that claim this issue lock. + competing_sessions = [] + lock_dir = issue_lock_store.default_lock_dir() + lock_path = issue_lock_store.lock_file_path( + remote=remote, org=o, repo=r, issue_number=issue_number, lock_dir=lock_dir + ) + try: + for name in os.listdir(lock_dir): + if not name.startswith("session-") or not name.endswith(".json"): + continue + ptr = issue_lock_store.read_lock_file(os.path.join(lock_dir, name)) + if not ptr: + continue + ptr_lock = str(ptr.get("lock_file_path") or "").strip() + if not ptr_lock: + continue + try: + same = os.path.realpath(ptr_lock) == os.path.realpath(lock_path) + except OSError: + same = ptr_lock == lock_path + if not same: + continue + try: + sess_pid = int(str(name)[len("session-") : -len(".json")]) + except ValueError: + sess_pid = ptr.get("pid") + competing_sessions.append( + { + "pid": sess_pid, + "lock_file_path": ptr_lock, + "live": issue_lock_store.is_process_alive(sess_pid), + } + ) + except OSError: + pass + + # Best-effort workflow-lease scan: any live lock file whose work_lease is a + # non-author workflow lease on this issue/branch counts as active. + workflow_lease_active = False + for path in issue_lock_store.iter_lock_files(lock_dir): + rec = issue_lock_store.read_lock_file(path) + if not rec: + continue + lease = rec.get("work_lease") if isinstance(rec.get("work_lease"), dict) else {} + op = str(lease.get("operation_type") or "") + if op and op != issue_lock_store.AUTHOR_ISSUE_WORK_LEASE: + if rec.get("issue_number") == issue_number or str( + rec.get("branch_name") or "" + ) == branch_name: + if issue_lock_store.is_lease_live(rec): + workflow_lease_active = True + break + + repo_root = _canonical_local_git_root() + # permission_allowed reflects profile gate only — never ownership proof. + permission_allowed = True + + result = dirty_same_claimant_session_rebind.apply_dirty_same_claimant_session_rebind( + remote=remote, + org=o, + repo=r, + issue_number=issue_number, + branch_name=branch_name, + worktree_path=resolved_wt, + claimant_identity=identity, + claimant_profile=profile_name, + old_pid=old_pid, + expected_local_head=expected_local_head, + expected_remote_head=expected_remote_head, + expected_dirty_paths=list(expected_dirty_paths or []), + expected_fingerprints=dict(expected_fingerprints or {}), + existing_lock=existing, + current_identity=identity, + current_profile=profile_name, + role_kind=role_norm or role, + current_pid=os.getpid(), + current_branch=current_branch, + local_head=local_head, + remote_head=remote_head, + dirty_inventory=inv, + competing_live_locks=competing_live, + competing_sessions=competing_sessions, + workflow_lease_active=workflow_lease_active, + authorize_reconciler_execute=bool(authorize_reconciler_execute), + permission_allowed=permission_allowed, + repo_root=repo_root, + dry_run=bool(dry_run), + lock_dir=lock_dir, + ) + result["observed"] = { + "local_head": local_head, + "remote_head": remote_head, + "current_branch": current_branch, + "dirty_paths": inv.get("dirty_paths"), + "fingerprints": inv.get("fingerprints"), + "identity": identity, + "profile": profile_name, + "role_kind": role_norm, + } + return result + + @mcp.tool() def gitea_assess_work_issue_duplicate( issue_number: int, @@ -11229,127 +11534,163 @@ def gitea_reconcile_merged_cleanups( if dry_run: report["dry_run"] = True report["executed"] = False + # #851: surface planned lifecycle order so dry-run matches execute. + report["planned_execution_orders"] = { + str(entry.get("pr_number")): entry.get("planned_execution_order") or [] + for entry in (report.get("entries") or []) + } return {"success": True, "performed": False, **report} verify_preflight_purity( remote, task="reconcile_merged_cleanups", org=org, repo=repo ) actions: list[dict] = [] + project_root = _canonical_local_git_root() + + def _ownership_records_for_branch( + head_branch: str, pr_num_int: int | None + ) -> list[dict]: + ownership_bundle = _collect_branch_ownership_records( + remote=remote, + host=h, + org=o, + repo=r, + branch=head_branch, + pr_number=pr_num_int, + project_root=project_root, + auth=auth, + base_api=base, + ) + ownership_records = list(ownership_bundle.get("records") or []) + if ownership_bundle.get("inventory_error"): + ownership_records.append( + { + "category": ( + branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR + ), + "status": "unknown", + "remote": remote, + "host": h, + "org": o, + "repo": r, + "branch": head_branch, + "reclaim_allowed": False, + "role": "inventory", + } + ) + return ownership_records + + def _attempt_owned_remote_delete( + *, + head_branch: str, + pr_num_int: int | None, + after_worktree_removal: bool = False, + ) -> dict: + """Fail-closed remote delete with live ownership reassessment (#851).""" + import urllib.parse + + ownership_records = _ownership_records_for_branch(head_branch, pr_num_int) + ownership = branch_cleanup_guard.assess_active_branch_ownership( + remote=remote, + org=o, + repo=r, + branch=head_branch, + host=h, + records=ownership_records, + ) + if ownership.get("block"): + return { + "action": "delete_remote_branch", + "branch": head_branch, + "success": False, + "performed": False, + "delete_acknowledged": False, + "verified_absent": False, + "blocker_kind": "active_branch_ownership", + "reasons": ownership.get("reasons") or [], + "blocking_categories": ownership.get("blocking_categories") or [], + "after_worktree_removal": after_worktree_removal, + "ownership_reassessed": after_worktree_removal, + } + + encoded = urllib.parse.quote(head_branch, safe="") + url = f"{base}/branches/{encoded}" + with _audited( + "delete_branch", + host=h, + remote=remote, + org=o, + repo=r, + target_branch=head_branch, + request_metadata={ + "branch": head_branch, + "source": "reconcile_merged_cleanups", + "ownership_checked": True, + "after_worktree_removal": after_worktree_removal, + }, + ): + api_request("DELETE", url, auth) + readback = _probe_remote_branch(h, o, r, auth, head_branch) + readback_assessment = branch_cleanup_guard.assess_post_delete_readback( + readback + ) + verified = bool(readback_assessment.get("verified_absent")) + return { + "action": "delete_remote_branch", + "branch": head_branch, + "success": bool(readback_assessment.get("ok")), + "performed": True, + "delete_acknowledged": True, + "verified_absent": verified, + "readback": readback_assessment.get("readback"), + "reasons": readback_assessment.get("reasons") or [], + "after_worktree_removal": after_worktree_removal, + "ownership_reassessed": after_worktree_removal, + } + for entry in report.get("entries") or []: head_branch = entry.get("head_branch") or "" remote_assessment = entry.get("remote_branch") or {} local_assessment = entry.get("local_worktree") or {} + pr_num = entry.get("pr_number") + try: + pr_num_int = int(pr_num) if pr_num is not None else None + except (TypeError, ValueError): + pr_num_int = None - if remote_assessment.get("safe_to_delete_remote"): - import urllib.parse - - pr_num = entry.get("pr_number") - try: - pr_num_int = int(pr_num) if pr_num is not None else None - except (TypeError, ValueError): - pr_num_int = None - ownership_bundle = _collect_branch_ownership_records( - remote=remote, - host=h, - org=o, - repo=r, - branch=head_branch, - pr_number=pr_num_int, - project_root=_canonical_local_git_root(), - auth=auth, - base_api=base, - ) - ownership_records = list(ownership_bundle.get("records") or []) - if ownership_bundle.get("inventory_error"): - ownership_records.append( - { - "category": ( - branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR - ), - "status": "unknown", - "remote": remote, - "host": h, - "org": o, - "repo": r, - "branch": head_branch, - "reclaim_allowed": False, - "role": "inventory", - } - ) - ownership = branch_cleanup_guard.assess_active_branch_ownership( - remote=remote, - org=o, - repo=r, - branch=head_branch, - host=h, - records=ownership_records, - ) - if ownership.get("block"): - actions.append( - { - "action": "delete_remote_branch", - "branch": head_branch, - "success": False, - "performed": False, - "delete_acknowledged": False, - "verified_absent": False, - "blocker_kind": "active_branch_ownership", - "reasons": ownership.get("reasons") or [], - "blocking_categories": ownership.get( - "blocking_categories" - ) - or [], - } - ) - continue - - encoded = urllib.parse.quote(head_branch, safe="") - url = f"{base}/branches/{encoded}" - with _audited( - "delete_branch", - host=h, - remote=remote, - org=o, - repo=r, - target_branch=head_branch, - request_metadata={ - "branch": head_branch, - "source": "reconcile_merged_cleanups", - "ownership_checked": True, - }, - ): - api_request("DELETE", url, auth) - readback = _probe_remote_branch(h, o, r, auth, head_branch) - readback_assessment = branch_cleanup_guard.assess_post_delete_readback( - readback - ) - verified = bool(readback_assessment.get("verified_absent")) - actions.append( - { - "action": "delete_remote_branch", - "branch": head_branch, - "success": bool(readback_assessment.get("ok")), - "performed": True, - "delete_acknowledged": True, - "verified_absent": verified, - "readback": readback_assessment.get("readback"), - "reasons": readback_assessment.get("reasons") or [], - } - ) - + # #851 lifecycle: when the target worktree is independently safe, remove + # it first so worktree_binding ownership does not permanently strand + # both the worktree and the remote branch. Never skip worktree removal + # merely because remote delete would be blocked by that binding. + # Ownership protection for remote delete remains fail-closed below. + worktree_removed = False if local_assessment.get("safe_to_remove_worktree"): result = merged_cleanup_reconcile.remove_local_worktree( - _canonical_local_git_root(), + project_root, head_branch, worktree_path=local_assessment.get("worktree_path"), ) actions.append({"action": "remove_local_worktree", **result}) + # Idempotent resume: absent worktree is already gone. + msg = (result.get("message") or "").lower() + worktree_removed = bool(result.get("success")) or ( + "not found" in msg + ) + + if remote_assessment.get("safe_to_delete_remote"): + actions.append( + _attempt_owned_remote_delete( + head_branch=head_branch, + pr_num_int=pr_num_int, + after_worktree_removal=worktree_removed, + ) + ) for scratch in report.get("reviewer_scratch_entries") or []: if not scratch.get("safe_to_remove_worktree"): continue result = merged_cleanup_reconcile.remove_reviewer_scratch_worktree( - _canonical_local_git_root(), scratch.get("worktree_path") or "" + project_root, scratch.get("worktree_path") or "" ) actions.append({"action": "remove_reviewer_scratch_worktree", **result}) @@ -11585,6 +11926,7 @@ def gitea_audit_worktree_cleanup( org: str | None = None, repo: str | None = None, ttl_hours: float = worktree_cleanup_audit.DEFAULT_TTL_HOURS, + merged_pr_limit: int = 200, ) -> dict: """Read-only: classify every session-owned worktree under ``branches/`` (#401). @@ -11595,17 +11937,26 @@ def gitea_audit_worktree_cleanup( the active issue-lock branch is read from the local lock file and treated as active work. Deletes nothing and mutates no Gitea state. - Fails closed if the live open-PR list cannot be fetched: without it, - removability cannot be proven, so no candidates are returned. + Merged PRs are fetched as well, so an issue worktree can be linked to the + PR that owns its branch (#858). Such a worktree only becomes removable + when that owning PR is unambiguous and merged, the worktree head is + already contained in authoritative master, and nothing else protects it — + no open or competing PR, lease, issue lock, live session, dirty file, or + protected/control checkout. Anything unproven keeps it classified as + active issue work. + + Fails closed if the live open-PR list, the merged-PR list, or the + control-plane lease state cannot be read: without them removability + cannot be proven, so no candidates are returned. Args: remote: Known instance — 'dadeschools' or 'prgs'. host: Override the Gitea host. org: Override the owner/organization. repo: Override the repository name. - ttl_hours: Age (hours) after which a clean issue/conflict-fix - worktree becomes stale-removable (default from - GITEA_WORKTREE_TTL_HOURS). + ttl_hours: Age (hours) after which a clean conflict-fix worktree + becomes stale-removable (default from GITEA_WORKTREE_TTL_HOURS). + merged_pr_limit: Max closed PRs scanned for merged-PR ownership. Returns: dict with per-worktree classifications, counts, removable @@ -11641,22 +11992,84 @@ def gitea_audit_worktree_cleanup( if (pr.get("head") or {}).get("ref") } + # #858: merged PRs are the ownership evidence that lets a landed issue + # worktree stop being reported as active work. Without them the audit can + # never agree with the PR-scoped reconciler, so treat a fetch failure the + # same way an open-PR fetch failure is treated: fail closed. + try: + closed_prs = api_get_all( + f"{repo_api_url(h, o, r)}/pulls?state=closed", auth, limit=merged_pr_limit + ) + except Exception as exc: + return { + "success": False, + "performed": False, + "open_pr_state_verified": True, + "merged_pr_state_verified": False, + "reasons": [ + "could not fetch merged PRs; worktree ownership unverified " + f"(fail closed): {_redact(str(exc))}" + ], + } + merged_prs = [pr for pr in closed_prs if (pr.get("merged") or pr.get("merged_at"))] + pr_index = worktree_cleanup_audit.build_pr_index(list(open_prs) + merged_prs) + + # #858: the auditor already accepted lease evidence but nothing ever + # supplied it, so every worktree looked unleased. Removability is now + # reachable for issue worktrees, so authoritative control-plane leases + # must be readable or the audit fails closed. + db, lease_errs = _control_plane_db_or_error() + if db is None: + return { + "success": False, + "performed": False, + "open_pr_state_verified": True, + "merged_pr_state_verified": True, + "lease_state_verified": False, + "reasons": [ + "could not read control-plane leases; worktree protection " + "unverified (fail closed)", + *lease_errs, + ], + } + lease_result = lease_lifecycle.list_active_leases( + db, remote=remote, org=o, repo=r, include_non_active=False, limit=500 + ) + leased_issue_numbers: set[int] = set() + live_session_paths: set[str] = set() + for lease in lease_result.get("leases") or []: + if lease.get("work_kind") == "issue" and lease.get("work_number") is not None: + try: + leased_issue_numbers.add(int(lease["work_number"])) + except (TypeError, ValueError): + pass + if lease.get("worktree_path"): + live_session_paths.add(str(lease["worktree_path"])) + active_issue_branches: set[str] = set() lock = merged_cleanup_reconcile.read_issue_lock(ISSUE_LOCK_FILE) if lock and lock.get("branch_name"): active_issue_branches.add(str(lock["branch_name"]).strip()) + master_ref = f"{remote}/master" if remote in REMOTES else "origin/master" report = worktree_cleanup_audit.audit_branches_directory( _canonical_local_git_root(), open_pr_branches=open_pr_branches, active_issue_branches=active_issue_branches, now=datetime.now(timezone.utc), ttl_hours=ttl_hours, + pr_index=pr_index, + leased_issue_numbers=leased_issue_numbers, + live_session_paths=live_session_paths, + master_ref=master_ref, ) return { "success": True, "performed": False, "open_pr_state_verified": True, + "merged_pr_state_verified": True, + "lease_state_verified": True, + "master_ref": master_ref, "task_mode": "work-issue", **report, } @@ -15538,7 +15951,8 @@ def mcp_get_control_plane_guide( profile = get_profile() allowed = profile["allowed_operations"] forbidden = profile["forbidden_operations"] - role = _role_kind(allowed, forbidden) + # Prefer declared profile role so controller is not mislabeled reconciler (#840). + role = _profile_role_kind(profile) username = _authenticated_username(h) identity = { @@ -15597,6 +16011,16 @@ def mcp_get_control_plane_guide( "user, and merging requires explicit operator authorization plus the " "'MERGE PR ' confirmation. " "Review and merge are separate workflow roles. A reviewer approval is not merge authorization.") + elif role == "controller": + guidance.append( + "Controller profile: route work via " + "gitea_route_task_session(task_type='process_work_queue') then " + "gitea_allocate_next_work (allocation_mode=cross_role by default). " + "The allocator returns exactly one authoritative selection with " + "required_role / required_profile / selected_action. Do not " + "implement, review, approve, or merge in this session — schedule " + "the matching role namespace instead. Dashboard output is " + "explanatory only and never replaces allocator selection.") elif role == "mixed": guidance.append( "WARNING: this profile allows both authoring and " @@ -15806,7 +16230,8 @@ def gitea_whoami( "environment": profile.get("environment"), "service": profile.get("service"), "identity": profile.get("identity"), - "role": profile.get("role"), + "role": profile.get("role") or _profile_role_kind(profile), + "role_kind": _profile_role_kind(profile), "profile_address": profile.get("profile_path"), "execution_profile": profile.get("execution_profile"), "audit_label": profile.get("audit_label"), @@ -18479,10 +18904,59 @@ def gitea_update_pr_branch_by_merge( prepared_verdict_head_sha=live_pr_head, ) - return { - "success": True, + # #871: the remote head is now advanced; the durable linked-issue lock must + # be advanced with it, or a later dead-session recovery can never prove + # ownership at the new head. This runs AFTER the successful remote update, so + # a failure here is a *partial* lifecycle failure — the remote moved but the + # durable state did not — and must never be reported as a full success. + claimant = _work_lease_claimant(h) + matched_issue = ownership.get("matched_issue") + synced_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ") + lock_refresh: dict = { + "refreshed": False, + "reasons": ["durable lock head refresh was not attempted"], + } + if new_head and matched_issue and source_branch and (wt or None): + try: + lock_refresh = issue_lock_store.apply_durable_lock_head_refresh( + remote=remote, + org=o, + repo=r, + issue_number=int(matched_issue), + branch_name=source_branch, + worktree_path=wt, + pr_number=pr_number, + identity=claimant.get("username"), + profile=claimant.get("profile"), + current_pid=os.getpid(), + expected_old_head=live_pr_head, + new_head=new_head, + synced_at=synced_at, + base_head=live_base_head, + ) + except Exception as exc: + lock_refresh = { + "refreshed": False, + "reasons": [ + f"durable lock head refresh raised (fail closed): {_redact(str(exc))}" + ], + } + else: + lock_refresh = { + "refreshed": False, + "reasons": [ + "durable lock head refresh could not run: missing new head, " + "linked issue, source branch, or worktree binding" + ], + } + + durable_refreshed = bool(lock_refresh.get("refreshed")) + base_result = { "performed": True, "mutation_allowed": True, + "durable_lock_refreshed": durable_refreshed, + "durable_lock_refresh": lock_refresh, + "fully_synchronized": durable_refreshed, "style": "merge", "force_push": False, "rebase": False, @@ -18504,19 +18978,37 @@ def gitea_update_pr_branch_by_merge( "prepared_verdict_invalidated": transition.get( "prepared_verdict_invalidated" ), - "recommended_next_action": transition.get( - "recommended_next_action", - pr_sync_status.ACTION_FRESH_REVIEW_REQUIRED, - ), "transition": transition, "role_kind": role, "profile_name": profile.get("profile_name"), "worktree_path": wt or None, - "reasons": list(transition.get("reasons") or []) + [ - "update-by-merge completed via native Gitea API (style=merge only)" - ], } + if durable_refreshed: + base_result["success"] = True + base_result["recommended_next_action"] = transition.get( + "recommended_next_action", + pr_sync_status.ACTION_FRESH_REVIEW_REQUIRED, + ) + base_result["reasons"] = list(transition.get("reasons") or []) + [ + "update-by-merge completed via native Gitea API (style=merge only)", + f"durable linked-issue lock #{matched_issue} head refreshed to " + f"{new_head} (verified by read-after-write)", + ] + return base_result + + # Partial lifecycle failure: the remote advanced but the durable lock did + # not. Do NOT report a fully successful synchronization (#871). + base_result["success"] = False + base_result["partial_lifecycle_failure"] = True + base_result["recommended_next_action"] = pr_sync_status.ACTION_BLOCKED + base_result["reasons"] = list(lock_refresh.get("reasons") or []) + [ + f"PARTIAL LIFECYCLE FAILURE: PR #{pr_number} remote head advanced to " + f"{new_head} but the durable linked-issue lock head was not refreshed; " + "the synchronization is NOT complete", + ] + return base_result + @mcp.tool() def gitea_assess_conflict_fix_push( @@ -19887,6 +20379,7 @@ def _allocator_candidates_from_gitea( state="open", labels=tuple(labels), title=title, + body=body, priority=20 if "status:ready" in labels else 1, blocked=blocked, dependency_unmet=dep_unmet, @@ -20590,9 +21083,10 @@ def gitea_allocate_next_work( candidates_json: Any = None, exclude_issue_numbers: list[int] | None = None, expected_candidate_set_fingerprint: str | None = None, + allocation_mode: str | None = None, limit: int = 50, ) -> dict: - """Controller-owned next-work allocator using the #613 control-plane DB (#600). + """Controller-owned next-work allocator using the #613 control-plane DB (#600/#840). Workers must not self-select exclusive work under the standard multi-LLM workflow. Call this tool instead. @@ -20602,6 +21096,14 @@ def gitea_allocate_next_work( ``ControlPlaneDB.assign_and_lease`` (never file locks or comment-only leases as the coordination source). + *allocation_mode* (#840): when the active role is controller (or mode is + ``cross_role``), inspect the complete queue and return exactly one + authoritative selection with selected item, action, required_role, + required_profile/namespace, pins, and allocation/lease evidence. + Role-scoped workers pass ``role=author|reviewer|merger|reconciler`` (or + omit for profile role) for single-role filtering. Controller routes only + and does not perform downstream mutations. + Outcomes include: ``assigned_work``, ``preview``, ``wait``, ``blocked_by_terminal_path``, ``no_safe_work``, ``role_ineligible``, ``blocked_by_excluded_own_lease``, ``candidate_set_drift``. @@ -20736,6 +21238,7 @@ def gitea_allocate_next_work( controller_instance_id=allocator_service.resolve_controller_instance_id(), exclude_issue_numbers=exclude_issue_numbers, expected_candidate_set_fingerprint=expected_candidate_set_fingerprint, + allocation_mode=allocation_mode, ) except ValueError as exc: return { @@ -21113,10 +21616,21 @@ def gitea_adopt_workflow_lease( remote: str = "dadeschools", host: str | None = None, ) -> dict: - """Adopt a control-plane lease through the sanctioned path (#601). + """Adopt a control-plane lease through the sanctioned path (#601 / #843). - Same-owner resume refreshes provenance. Foreign active leases are refused. - Expired leases may be reclaimed; provenance records adopted_from/by. + Same-owner resume refreshes provenance. Foreign active leases are refused + unless the lease is a pending controller cross-role handoff and the caller + holds the required role (independent consume without sharing the + controller session). Expired leases may be reclaimed; provenance records + adopted_from/by. Terminal (abandoned/released) leases cannot be adopted. + + #843 F1: the adopter role is derived authoritatively from the active + authenticated profile — never from caller input. A supplied ``role`` that + does not exactly match the profile-derived role is rejected (no silent + accept or reinterpretation), and handoff provenance ``required_profile`` / + ``required_namespace`` restrictions are validated against the same + authoritative caller context. Caller-supplied role/profile/namespace can + never grant authority. """ read_block = _profile_operation_gate("gitea.read") if read_block: @@ -21125,25 +21639,64 @@ def gitea_adopt_workflow_lease( "reasons": read_block, "permission_report": _permission_block_report("gitea.read"), } + profile = get_profile() + profile_name = (profile.get("profile_name") or "").strip() or "session" + active_role = (_profile_role_kind(profile) or "").strip().lower() + if not active_role: + return { + "success": False, + "outcome": "blocked", + "mutation_performed": False, + "reasons": [ + "active profile role could not be derived authoritatively; " + "refusing lease adoption (fail closed, #843)" + ], + "lease_id": lease_id, + "authoritative_source": "control_plane_db", + "file_lock_only": False, + "comment_lease_only": False, + } + if role is not None and str(role).strip(): + supplied_role = str(role).strip().lower() + if supplied_role != active_role: + return { + "success": False, + "outcome": "blocked", + "mutation_performed": False, + "profile_role_kind": active_role, + "supplied_role": supplied_role, + "reasons": [ + f"caller-supplied role '{supplied_role}' does not match " + f"the authenticated profile-derived role '{active_role}'; " + "caller-supplied role/profile/namespace can never grant " + "authority (fail closed, #843)" + ], + "lease_id": lease_id, + "authoritative_source": "control_plane_db", + "file_lock_only": False, + "comment_lease_only": False, + } db, errs = _control_plane_db_or_error() if db is None: return {"success": False, "reasons": errs} - profile = get_profile() - profile_name = (profile.get("profile_name") or "").strip() or "session" - active_role = _profile_role_kind(profile) or "author" sid = (session_id or "").strip() or ( f"{profile_name}-{os.getpid()}-{uuid.uuid4().hex[:8]}" ) + adopter_namespace = allocator_service.DEFAULT_ROLE_NAMESPACES.get( + active_role, f"gitea-{active_role}" + ) try: return lease_lifecycle.adopt_lease( db, lease_id=lease_id, adopter_session_id=sid, - role=(role or active_role).strip() or "author", + role=active_role, worktree_path=worktree_path, expected_head_sha=expected_head_sha, owner_pid=os.getpid(), operator_authorized=bool(operator_authorized), + adopter_profile_name=profile_name, + adopter_namespace=adopter_namespace, ) except (lease_lifecycle.LeaseLifecycleError, control_plane_db.ControlPlaneError) as exc: return { diff --git a/issue_lock_provenance.py b/issue_lock_provenance.py index 87ee38f..544e017 100644 --- a/issue_lock_provenance.py +++ b/issue_lock_provenance.py @@ -16,11 +16,16 @@ 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" +# #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_DIRTY_SAME_CLAIMANT_REBIND, }) _OPERATOR_OVERRIDE_ENV = "GITEA_ISSUE_LOCK_OPERATOR_OVERRIDE" diff --git a/issue_lock_recovery.py b/issue_lock_recovery.py index ecc99c6..ae0cc35 100644 --- a/issue_lock_recovery.py +++ b/issue_lock_recovery.py @@ -85,6 +85,12 @@ 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, @@ -266,6 +272,70 @@ 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, *, @@ -290,6 +360,7 @@ 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. @@ -469,19 +540,39 @@ def assess_dead_session_lock_recovery( head_relation = HEAD_RELATION_STRICT_DESCENDANT ancestry_proof = notes[0] if notes else None else: - reasons.append( - f"local head {local_head} does not match remote branch head " - f"{remote_head}" + # #871: the reverse relation — the remote head advanced past + # the recorded/local head via a sanctioned merge-based branch + # sync while the local worktree stayed put. Accepted only on + # 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, ) - reasons.extend(notes) + if synced: + 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 - evidence["accepted_head"] = local_head or None + if head_relation == HEAD_RELATION_REMOTE_MERGE_SYNCED: + 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 @@ -493,12 +584,17 @@ 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. Any other - # disagreement is a real mismatch. + # legitimately still points at the recorded head. A merge-sync + # recovery's PR legitimately sits at the advanced remote head. Any + # 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 " @@ -619,7 +715,11 @@ def assess_dead_session_lock_recovery( ) if ( head_relation - in (HEAD_RELATION_STRICT_DESCENDANT, HEAD_RELATION_DESCENDS_FROM_BASE) + in ( + HEAD_RELATION_STRICT_DESCENDANT, + HEAD_RELATION_DESCENDS_FROM_BASE, + HEAD_RELATION_REMOTE_MERGE_SYNCED, + ) and ancestry_proof ): proof.append(ancestry_proof) @@ -697,6 +797,16 @@ 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: @@ -765,6 +875,18 @@ 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: diff --git a/issue_lock_store.py b/issue_lock_store.py index 713fa2a..a963174 100644 --- a/issue_lock_store.py +++ b/issue_lock_store.py @@ -737,4 +737,308 @@ def format_lock_proof( parts.append("lock released") elif released is False: parts.append("lock retained") - return "; ".join(parts) \ No newline at end of file + 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 \ No newline at end of file diff --git a/issue_lock_worktree.py b/issue_lock_worktree.py index de52ff7..8188536 100644 --- a/issue_lock_worktree.py +++ b/issue_lock_worktree.py @@ -145,6 +145,175 @@ 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, *, diff --git a/lease_lifecycle.py b/lease_lifecycle.py index 2049962..c42be14 100644 --- a/lease_lifecycle.py +++ b/lease_lifecycle.py @@ -39,6 +39,7 @@ 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" @@ -250,6 +251,23 @@ 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": [ @@ -272,6 +290,24 @@ 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": [ @@ -440,6 +476,84 @@ 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, *, @@ -450,8 +564,17 @@ 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( @@ -463,11 +586,8 @@ def adopt_lease( owner = str(lease.get("session_id") or "") same_owner = owner == str(adopter_session_id) - if freshness["freshness"] == "active" and not same_owner: - raise LeaseLifecycleError( - f"refusing to steal active foreign lease {lease_id} owned by " - f"{owner} (fail closed)" - ) + handoff = is_pending_cross_role_handoff(state) + adopter_role = (role or "").strip().lower() if freshness["freshness"] in ("abandoned", "released"): raise LeaseLifecycleError( @@ -475,13 +595,64 @@ def adopt_lease( "(fail closed)" ) - # Expired or stale: require abandon-style safety before ownership transfer - # when not same owner; same owner may reclaim. - if not same_owner and freshness["freshness"] in ( + if handoff and not same_owner: + # Terminal statuses already rejected above. Freshness may be + # active OR stale_dead_process (controller exited) — both are + # 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). @@ -492,6 +663,9 @@ 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, @@ -504,10 +678,14 @@ 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=( - "owner-resume-adopt" if same_owner else "sanctioned-reclaim-adopt" - ), + reason=reason, ) + 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, @@ -518,7 +696,7 @@ def adopt_lease( owner_pid=owner_pid if owner_pid is not None else os.getpid(), provenance=provenance, ) - return { + out = { "success": True, "outcome": result.get("outcome"), "same_owner": same_owner, @@ -531,6 +709,24 @@ 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( diff --git a/merged_cleanup_reconcile.py b/merged_cleanup_reconcile.py index 4a7299a..b436750 100644 --- a/merged_cleanup_reconcile.py +++ b/merged_cleanup_reconcile.py @@ -566,6 +566,10 @@ 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, @@ -576,9 +580,63 @@ 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, diff --git a/namespace_workspace_binding.py b/namespace_workspace_binding.py index fa006b6..be2ca82 100644 --- a/namespace_workspace_binding.py +++ b/namespace_workspace_binding.py @@ -24,7 +24,12 @@ ROLE_WORKTREE_ENVS: dict[str, str] = { "reconciler": RECONCILER_WORKTREE_ENV, } -NON_AUTHOR_ROLES = frozenset({"reviewer", "merger", "reconciler"}) +# Controller has no task worktree env — it routes only (#840). +KNOWN_ROLE_KINDS = frozenset( + {"author", "reviewer", "merger", "reconciler", "controller"} +) + +NON_AUTHOR_ROLES = frozenset({"reviewer", "merger", "reconciler", "controller"}) def normalize_role_kind( @@ -37,8 +42,12 @@ def normalize_role_kind( profile = (profile_name or "").strip().lower() if role == "reviewer" and "merger" in profile: return "merger" + if "controller" in profile or role == "controller": + return "controller" if role in ROLE_WORKTREE_ENVS: return role + if role in KNOWN_ROLE_KINDS: + return role return "author" @@ -80,7 +89,7 @@ def resolve_namespace_workspace( """ env_map = env if env is not None else os.environ role = normalize_role_kind(role_kind, profile_name=profile_name) - role_env_key = ROLE_WORKTREE_ENVS[role] + role_env_key = ROLE_WORKTREE_ENVS.get(role) # #618: durable author resolution — no silent control/master fallback. if role == "author" and verify_paths: @@ -108,13 +117,17 @@ def resolve_namespace_workspace( ) return workspace, source + role_env_candidate = ( + (_env_value(env_map, role_env_key), f"{role_env_key} environment variable", True) + if role_env_key + else (None, "no role worktree env", True) + ) for candidate, source, env_sourced in ( (worktree_path, "worktree_path argument", False), (worktree, "worktree argument", False), (_env_value(env_map, ACTIVE_WORKTREE_ENV), f"{ACTIVE_WORKTREE_ENV} environment variable", True), - (_env_value(env_map, role_env_key), - f"{role_env_key} environment variable", True), + role_env_candidate, (session_lease_worktree if role in {"reviewer", "merger"} else None, "reviewer PR lease worktree", False), # Author lock derivation is handled by the durable path above when @@ -433,7 +446,8 @@ def assess_namespace_mutation_workspace( reasons.append( f"{role} mutation blocked: workspace is the stable control checkout; " f"create or reconnect to a session-owned worktree under branches/ " - f"or set {ROLE_WORKTREE_ENVS[role]} / {ACTIVE_WORKTREE_ENV}" + f"or set {ROLE_WORKTREE_ENVS.get(role, ACTIVE_WORKTREE_ENV)} / " + f"{ACTIVE_WORKTREE_ENV}" ) elif ( role in {"reviewer", "merger"} diff --git a/role_session_router.py b/role_session_router.py index 4f331b8..f756c71 100644 --- a/role_session_router.py +++ b/role_session_router.py @@ -81,6 +81,12 @@ AUTHOR_TASKS = frozenset({ "reconcile_landed_pr", }) +CONTROLLER_TASKS = frozenset({ + "process_work_queue", + "process-work-queue", + "cross_role_allocate", +}) + RECONCILER_TASKS = frozenset({ "cleanup_merged_pr_branch", # #729: delete_branch is reconciler-owned (gitea.branch.delete is granted @@ -132,6 +138,10 @@ TASK_REQUIRED_ROLE = { "reconcile_close_superseded_pr": "reconciler", "reconcile_close_satisfied_issue": "reconciler", "reconcile_create_followup_issue": "reconciler", + # #840: controller-owned generic queue allocation / routing. + "process_work_queue": "controller", + "process-work-queue": "controller", + "cross_role_allocate": "controller", } WRONG_ROLE_REVIEWER_MSG = ( @@ -147,6 +157,10 @@ WRONG_ROLE_MERGER_MSG = ( "Wrong role/session for merger task. Launch merger MCP namespace." ) +WRONG_ROLE_CONTROLLER_MSG = ( + "Wrong role/session for controller task. Launch controller MCP namespace." +) + _session_last_route: dict | None = None @@ -281,6 +295,27 @@ def route_task_session( _record_route(result) return result + if required_role == "controller": + result = { + "task_type": task_type, + "required_role": required_role, + "active_role": active_role_kind, + "active_profile": active_profile, + "route_result": ROUTE_WRONG_ROLE, + "downstream_allowed": False, + "reasons": [ + WRONG_ROLE_CONTROLLER_MSG, + "Controller tasks (process_work_queue / cross-role allocate) " + "cannot run in author, reviewer, merger, or reconciler " + "worker sessions.", + ], + "message": WRONG_ROLE_CONTROLLER_MSG, + "runtime_switching_supported": runtime_switching_supported, + "profile_switch_blocked": not runtime_switching_supported, + } + _record_route(result) + return result + if required_role == "author": route = ROUTE_TO_AUTHOR message = ( diff --git a/task_capability_map.py b/task_capability_map.py index 0a21063..7d7b76b 100644 --- a/task_capability_map.py +++ b/task_capability_map.py @@ -32,6 +32,17 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = { "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", @@ -309,8 +320,10 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = { "permission": "gitea.pr.create", "role": "author", }, - # #600: controller-owned allocator — any authenticated profile may call; - # routing enforces role match to selected work. Uses control-plane DB (#613). + # #600: workers and controller may call with gitea.read; role-scoped workers + # pass role=author|reviewer|merger|reconciler. Cross-role routing is the + # controller default (#840). The canonical generic queue *task type* is + # process_work_queue (controller-only below). "allocate_next_work": { "permission": "gitea.read", "role": "author", @@ -319,6 +332,19 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = { "permission": "gitea.read", "role": "author", }, + # #840: documented generic queue task — controller routes only. + "process_work_queue": { + "permission": "gitea.read", + "role": "controller", + }, + "process-work-queue": { + "permission": "gitea.read", + "role": "controller", + }, + "cross_role_allocate": { + "permission": "gitea.read", + "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). diff --git a/tests/test_allocator_epic_container_exclusion.py b/tests/test_allocator_epic_container_exclusion.py new file mode 100644 index 0000000..0b9fa78 --- /dev/null +++ b/tests/test_allocator_epic_container_exclusion.py @@ -0,0 +1,243 @@ +"""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() diff --git a/tests/test_arch01_platform.py b/tests/test_arch01_platform.py new file mode 100644 index 0000000..bb4272c --- /dev/null +++ b/tests/test_arch01_platform.py @@ -0,0 +1,572 @@ +"""Executable acceptance tests for ARCH-01 Slice A (#822). + +Each acceptance criterion (#822 §12) and named test (#822 §13) is exercised +against a real SQLite database. The migration runs on a fresh DB in ``setUp``; +the test-run output is the durable evidence the issue requires (§14). + +Enforcement being proven: + +* ``[TRUSTED-SERVICE]`` — the ``cp_*`` actor functions exist only on the + trusted kernel connection; a raw connection cannot satisfy the triggers. +* ``[SCHEMA]`` — fail-closed aborts, exact dominance set, NOT-NULL class, + immutability, and the last-active-grant floor are enforced by + CHECK/FK/trigger, verified here including raw-write bypass and concurrency. +""" + +from __future__ import annotations + +import os +import sqlite3 +import tempfile +import threading +import unittest +from concurrent.futures import ThreadPoolExecutor + +import arch01_platform as ap +from arch01_platform import ( + ALREADY_INSTALLED, + AUTHORIZATION_DENIED, + CONCURRENT_INSTALLATION_LOST, + DISTINGUISHED_ISSUER_ID, + DOMINANCE_SET_MISMATCH, + DOMINANCE_TUPLES, + INSTALLED, + INVALID_ACTOR_CONTEXT, + INVALID_BOOTSTRAP_STATE, + PlatformKernel, +) + +INSTALLER = "platform.installer" + +_BOOTSTRAP_TABLES = ( + "principal_equivalence_classes", + "principals", + "authoritative_issuers", + "authority_dominance", + "platform_bootstrap_seed", + "platform_bootstrap_grants", + "platform_active_invariant", + "install_state", +) + + +def _count(kernel: PlatformKernel, table: str) -> int: + return kernel._conn.execute(f"SELECT COUNT(*) FROM {table}").fetchone()[0] + + +def _count_where(kernel: PlatformKernel, table: str, where: str) -> int: + return kernel._conn.execute(f"SELECT COUNT(*) FROM {table} WHERE {where}").fetchone()[0] + + +def _all_bootstrap_empty(kernel: PlatformKernel) -> bool: + return all(_count(kernel, t) == 0 for t in _BOOTSTRAP_TABLES) + + +class Arch01MemoryTest(unittest.TestCase): + """Single-connection behavior on an in-memory database.""" + + def setUp(self) -> None: + self.kernel = PlatformKernel(":memory:") + + def tearDown(self) -> None: + self.kernel.close() + + # -- AC1 -------------------------------------------------------------- # + def test_install_clean(self) -> None: # t_install_clean(+) + res = self.kernel.install_platform(INSTALLER) + self.assertEqual(res.code, INSTALLED) + self.assertTrue(self.kernel.is_installed()) + self.assertEqual(_count(self.kernel, "install_state"), 1) + self.assertEqual(self.kernel.active_grant_count(), 1) + self.assertIn(ap.EVT_PLATFORM_INSTALLED, self.kernel.audit_events()) + rows = set( + self.kernel._conn.execute( + "SELECT dominant, subordinate FROM authority_dominance" + ).fetchall() + ) + self.assertEqual(rows, set(DOMINANCE_TUPLES)) + issuer_ref = self.kernel._conn.execute( + "SELECT i.issuer_ref FROM principals p JOIN authoritative_issuers i " + "ON p.issuer_id = i.issuer_id WHERE p.principal_id = ?", + (INSTALLER,), + ).fetchone() + self.assertEqual(issuer_ref[0], DISTINGUISHED_ISSUER_ID) + + # -- AC2 -------------------------------------------------------------- # + def test_install_twice(self) -> None: # t_install_twice(-) + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + res2 = self.kernel.install_platform(INSTALLER) + self.assertEqual(res2.code, ALREADY_INSTALLED) + self.assertEqual(_count(self.kernel, "principals"), 1) + self.assertEqual(_count(self.kernel, "platform_bootstrap_grants"), 1) + self.assertEqual(_count(self.kernel, "install_state"), 1) + + # -- AC3 / AC5 -------------------------------------------------------- # + def test_install_stage_rollback(self) -> None: # t_install_stage_rollback + for stop in range(1, 9): + with self.subTest(stages=stop): + k = PlatformKernel(":memory:") + try: + self._partial_bootstrap_then_rollback(k, stop) + self.assertTrue( + _all_bootstrap_empty(k), + f"partial rows survived rollback at stage {stop}", + ) + self.assertFalse(k.is_installed()) + finally: + k.close() + + def test_no_partial_after_rollback(self) -> None: # t_no_partial_after_rollback + k = PlatformKernel(":memory:") + try: + code = self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1]) + self.assertEqual(code, DOMINANCE_SET_MISMATCH) + self.assertTrue(_all_bootstrap_empty(k)) + self.assertFalse(k.is_installed()) + finally: + k.close() + + # -- AC4 -------------------------------------------------------------- # + def test_dominance_missing(self) -> None: # t_dominance_missing(-) + k = PlatformKernel(":memory:") + try: + self.assertEqual( + self._seed_bootstrap_and_mark(k, dominance=DOMINANCE_TUPLES[:-1]), + DOMINANCE_SET_MISMATCH, + ) + self.assertFalse(k.is_installed()) + finally: + k.close() + + def test_dominance_extra(self) -> None: # t_dominance_extra(-) + k = PlatformKernel(":memory:") + try: + extra = DOMINANCE_TUPLES + (("platform.bootstrap", "rogue.extra"),) + self.assertEqual( + self._seed_bootstrap_and_mark(k, dominance=extra), + DOMINANCE_SET_MISMATCH, + ) + self.assertFalse(k.is_installed()) + finally: + k.close() + + def test_dominance_malformed(self) -> None: # t_dominance_malformed(-) + k = PlatformKernel(":memory:") + try: + malformed = DOMINANCE_TUPLES[:-1] + (("supervisor.root", "WRONG.subordinate"),) + self.assertEqual( + self._seed_bootstrap_and_mark(k, dominance=malformed), + DOMINANCE_SET_MISMATCH, + ) + self.assertFalse(k.is_installed()) + finally: + k.close() + + # -- AC6 -------------------------------------------------------------- # + def test_principal_no_class(self) -> None: # t_principal_no_class(-) + with self.kernel.actor_context("op", "operator", "install"): + with self.assertRaises(sqlite3.IntegrityError): + self.kernel._conn.execute( + "INSERT INTO principals" + "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES ('x', 'operator', NULL, NULL, NULL, '2026-01-01T00:00:00Z')" + ) + + # -- AC7 -------------------------------------------------------------- # + def test_noninstaller_null_issuer(self) -> None: # t_nonobstaller_null_issuer(-) + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + with self.kernel.actor_context("op", "operator", "normal"): + cur = self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')" + ) + class_id = cur.lastrowid + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute( + "INSERT INTO principals" + "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES ('rogue', 'operator', ?, NULL, NULL, '2026-01-01T00:00:00Z')", + (class_id,), + ) + self.assertIn("INVALID_BOOTSTRAP_STATE", str(ctx.exception)) + + def test_installer_null_issuer_only_during_install(self) -> None: + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + with self.kernel.actor_context("i2", "installer", "install"): + cur = self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')" + ) + class_id = cur.lastrowid + with self.assertRaises(sqlite3.IntegrityError): + self.kernel._conn.execute( + "INSERT INTO principals" + "(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES ('i2', 'installer', ?, NULL, NULL, '2026-01-01T00:00:00Z')", + (class_id,), + ) + + # -- AC8 -------------------------------------------------------------- # + def test_context_missing(self) -> None: # t_context_missing(-) + self.assertIsNone(self.kernel._ctx) + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')" + ) + self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception)) + + def test_context_stale(self) -> None: # t_context_stale(-) + with self.kernel.actor_context("op", "operator", "normal"): + self.kernel._ctx.expired = True + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')" + ) + self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception)) + + def test_context_epoch_shift(self) -> None: # t_context_epoch_shift(-) + with self.kernel.actor_context("op", "operator", "normal"): + self.kernel._ctx.live_epoch = self.kernel._ctx.bound_epoch + 99 + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES ('2026-01-01T00:00:00Z')" + ) + self.assertIn("INVALID_ACTOR_CONTEXT", str(ctx.exception)) + + def test_bad_actor_kind_or_mode_rejected(self) -> None: + for kind, mode in (("intruder", "normal"), ("operator", "sabotage")): + with self.subTest(kind=kind, mode=mode): + with self.kernel.actor_context("op", kind, mode): + with self.assertRaises(sqlite3.IntegrityError): + self.kernel._conn.execute( + "INSERT INTO principal_equivalence_classes(created_at) " + "VALUES ('2026-01-01T00:00:00Z')" + ) + + # -- AC9 -------------------------------------------------------------- # + def test_bootstrap_immutable_update(self) -> None: # t_bootstrap_immutable_{update} + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + cases = [ + ("UPDATE install_state SET installed_at = 'x' WHERE id = 1", "IMMUTABLE_INSTALL_STATE"), + ("UPDATE platform_bootstrap_seed SET created_at = 'x' WHERE seed_id = 1", "IMMUTABLE_SEED"), + ("UPDATE authority_dominance SET subordinate = 'x' WHERE dominant = 'supervisor.root'", "IMMUTABLE_DOMINANCE"), + (f"UPDATE authoritative_issuers SET issuer_ref = 'x' WHERE issuer_ref = '{DISTINGUISHED_ISSUER_ID}'", "IMMUTABLE_ISSUER"), + (f"UPDATE principals SET actor_kind = 'operator' WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"), + ] + for sql, tag in cases: + with self.subTest(sql=sql): + with self.kernel.actor_context("op", "operator", "normal"): + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute(sql) + self.assertIn(tag, str(ctx.exception)) + + def test_bootstrap_immutable_delete(self) -> None: # t_bootstrap_immutable_{delete} + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + cases = [ + ("DELETE FROM install_state WHERE id = 1", "IMMUTABLE_INSTALL_STATE"), + ("DELETE FROM platform_bootstrap_seed WHERE seed_id = 1", "IMMUTABLE_SEED"), + ("DELETE FROM authority_dominance", "IMMUTABLE_DOMINANCE"), + ("DELETE FROM authoritative_issuers", "IMMUTABLE_ISSUER"), + (f"DELETE FROM principals WHERE principal_id = '{INSTALLER}'", "IMMUTABLE_PRINCIPAL"), + ("DELETE FROM platform_bootstrap_grants", "IMMUTABLE_GRANT"), + ] + for sql, tag in cases: + with self.subTest(sql=sql): + with self.kernel.actor_context("op", "operator", "normal"): + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute(sql) + self.assertIn(tag, str(ctx.exception)) + + def test_grant_reactivation_rejected(self) -> None: + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + self.kernel.register_principal( + "op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER + ) + self.assertEqual( + self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED + ) + gid = self.kernel._conn.execute( + "SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'" + ).fetchone()[0] + self.assertEqual( + self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code, + INSTALLED, + ) + with self.kernel.actor_context("op", "operator", "normal"): + with self.assertRaises(sqlite3.IntegrityError) as ctx: + self.kernel._conn.execute( + "UPDATE platform_bootstrap_grants SET active = 1 WHERE grant_id = ?", + (gid,), + ) + self.assertIn("IMMUTABLE_GRANT", str(ctx.exception)) + + # -- AC12 ------------------------------------------------------------- # + def test_raw_write_bypass(self) -> None: # t_raw_write_bypass(raw-bypass) + with tempfile.TemporaryDirectory() as tmp: + path = os.path.join(tmp, "p.sqlite3") + k = PlatformKernel(path) + self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED) + k.close() + raw = sqlite3.connect(path) + raw.execute("PRAGMA foreign_keys = ON") + try: + with self.assertRaises(sqlite3.Error): + raw.execute( + "INSERT INTO audit_records(event, created_at) " + "VALUES ('forged', '2026-01-01T00:00:00Z')" + ) + raw.commit() + with self.assertRaises(sqlite3.Error): + raw.execute("UPDATE install_state SET installed_at = 'x' WHERE id = 1") + raw.commit() + with self.assertRaises(sqlite3.Error): + raw.execute("DELETE FROM platform_bootstrap_grants") + raw.commit() + finally: + raw.close() + + # -- AC13 ------------------------------------------------------------- # + def test_audit_created(self) -> None: # t_audit_created(+) + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + self.kernel.register_principal( + "op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER + ) + self.assertEqual( + self.kernel.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED + ) + gid = self.kernel._conn.execute( + "SELECT grant_id FROM platform_bootstrap_grants WHERE grantee_principal_id = 'op1'" + ).fetchone()[0] + self.assertEqual( + self.kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code, + INSTALLED, + ) + events = self.kernel.audit_events() + for evt in ( + ap.EVT_PLATFORM_INSTALLED, + ap.EVT_GRANT_CREATED, + ap.EVT_GRANT_REVOKED, + ap.EVT_PRINCIPAL_REGISTERED, + ): + self.assertIn(evt, events) + + # -- AC14 ------------------------------------------------------------- # + def test_audit_immutable(self) -> None: # t_audit_immutable(raw-bypass) + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + with self.kernel.actor_context("op", "operator", "normal"): + with self.assertRaises(sqlite3.IntegrityError) as up: + self.kernel._conn.execute("UPDATE audit_records SET event = 'x' WHERE audit_id = 1") + self.assertIn("IMMUTABLE_AUDIT", str(up.exception)) + with self.assertRaises(sqlite3.IntegrityError) as dl: + self.kernel._conn.execute("DELETE FROM audit_records WHERE audit_id = 1") + self.assertIn("IMMUTABLE_AUDIT", str(dl.exception)) + + # -- meta ------------------------------------------------------------- # + def test_schema_meta(self) -> None: + rows = dict(self.kernel._conn.execute("SELECT key, value FROM arch01_meta").fetchall()) + self.assertEqual(rows["schema_version"], str(ap.SCHEMA_VERSION)) + self.assertIn("disabled by default", rows["architecture"]) + + def test_register_principal_creates_class_first(self) -> None: + self.assertEqual(self.kernel.install_platform(INSTALLER).code, INSTALLED) + res = self.kernel.register_principal( + "svc1", "service", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER + ) + self.assertEqual(res.code, INSTALLED) + row = self.kernel._conn.execute( + "SELECT current_class_id FROM principals WHERE principal_id = 'svc1'" + ).fetchone() + self.assertIsNotNone(row[0]) + + # -- helpers ---------------------------------------------------------- # + def _partial_bootstrap_then_rollback(self, k: PlatformKernel, stop: int) -> None: + """Execute the first ``stop`` bootstrap statements, then ROLLBACK.""" + now = "2026-01-01T00:00:00Z" + k._conn.execute("BEGIN IMMEDIATE") + class_id = None + issuer_id = None + try: + with k.actor_context(INSTALLER, "installer", "install"): + c = k._conn + if stop >= 1: + class_id = c.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,) + ).lastrowid + if stop >= 2: + c.execute( + "INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES (?, 'installer', ?, NULL, ?, ?)", + (INSTALLER, class_id, INSTALLER, now), + ) + if stop >= 3: + issuer_id = c.execute( + "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)", + (DISTINGUISHED_ISSUER_ID, now), + ).lastrowid + if stop >= 4: + c.execute( + "UPDATE principals SET issuer_id = ? WHERE principal_id = ?", + (issuer_id, INSTALLER), + ) + if stop >= 5: + c.executemany( + "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)", + DOMINANCE_TUPLES, + ) + if stop >= 6: + c.execute( + "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)", + (INSTALLER, now), + ) + if stop >= 7: + c.execute( + "INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)", + (INSTALLER, now), + ) + if stop >= 8: + c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)") + finally: + k._conn.execute("ROLLBACK") + + def _seed_bootstrap_and_mark(self, k: PlatformKernel, dominance) -> str: + """Seed a full bootstrap with a caller-supplied dominance set, then + attempt the marker insert. Returns the classified failure code (or + INSTALLED). Rolls back on failure so no partial rows remain.""" + now = "2026-01-01T00:00:00Z" + k._conn.execute("BEGIN IMMEDIATE") + try: + with k.actor_context(INSTALLER, "installer", "install"): + c = k._conn + class_id = c.execute( + "INSERT INTO principal_equivalence_classes(created_at) VALUES (?)", (now,) + ).lastrowid + c.execute( + "INSERT INTO principals(principal_id, actor_kind, current_class_id, issuer_id, registered_by, created_at) " + "VALUES (?, 'installer', ?, NULL, ?, ?)", + (INSTALLER, class_id, INSTALLER, now), + ) + issuer_id = c.execute( + "INSERT INTO authoritative_issuers(issuer_kind, issuer_ref, created_at) VALUES ('operator-key', ?, ?)", + (DISTINGUISHED_ISSUER_ID, now), + ).lastrowid + c.execute( + "UPDATE principals SET issuer_id = ? WHERE principal_id = ?", + (issuer_id, INSTALLER), + ) + c.executemany( + "INSERT INTO authority_dominance(dominant, subordinate) VALUES (?, ?)", + dominance, + ) + c.execute( + "INSERT INTO platform_bootstrap_seed(seed_id, installer_principal_id, created_at) VALUES (1, ?, ?)", + (INSTALLER, now), + ) + c.execute( + "INSERT INTO platform_bootstrap_grants(grantee_principal_id, granted_by, active, created_at) VALUES (?, NULL, 1, ?)", + (INSTALLER, now), + ) + c.execute("INSERT INTO platform_active_invariant(id, active_count) VALUES (1, 1)") + c.execute( + "INSERT INTO install_state(id, marker, installed_at) VALUES (1, 'installed', ?)", + (now,), + ) + k._conn.execute("COMMIT") + return INSTALLED + except sqlite3.Error as exc: + k._safe_rollback() + return PlatformKernel._classify(exc) + + +class Arch01ConcurrencyTest(unittest.TestCase): + """Concurrency invariants require file-backed DBs and independent connections.""" + + def setUp(self) -> None: + self._tmp = tempfile.TemporaryDirectory() + self.path = os.path.join(self._tmp.name, "p.sqlite3") + + def tearDown(self) -> None: + self._tmp.cleanup() + + # -- AC10 ------------------------------------------------------------- # + def test_concurrent_install(self) -> None: # t_concurrent_install(concurrency) + k1 = PlatformKernel(self.path, busy_timeout_ms=0) + k2 = PlatformKernel(self.path, busy_timeout_ms=0) + barrier = threading.Barrier(2) + results = {} + + def _install(name, kernel): + barrier.wait() + results[name] = kernel.install_platform(INSTALLER).code + + try: + with ThreadPoolExecutor(max_workers=2) as ex: + f1 = ex.submit(_install, "a", k1) + f2 = ex.submit(_install, "b", k2) + f1.result() + f2.result() + codes = sorted(results.values()) + self.assertEqual(codes.count(INSTALLED), 1, f"exactly one install expected: {results}") + other = [c for c in results.values() if c != INSTALLED][0] + self.assertIn(other, (ALREADY_INSTALLED, CONCURRENT_INSTALLATION_LOST)) + self.assertTrue(k1.is_installed()) + self.assertEqual(_count(k1, "install_state"), 1) + self.assertEqual(_count(k1, "principals"), 1) + finally: + k1.close() + k2.close() + + # -- AC11 ------------------------------------------------------------- # + def test_concurrent_last_grant_revoke(self) -> None: # t_concurrent_last_grant_revoke + setup = PlatformKernel(self.path) + self.assertEqual(setup.install_platform(INSTALLER).code, INSTALLED) + setup.register_principal("op1", "operator", DISTINGUISHED_ISSUER_ID, actor_principal=INSTALLER) + self.assertEqual(setup.grant_platform_bootstrap("op1", INSTALLER).code, INSTALLED) + self.assertEqual(setup.active_grant_count(), 2) + gids = [ + r[0] + for r in setup._conn.execute( + "SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1 ORDER BY grant_id" + ).fetchall() + ] + setup.close() + self.assertEqual(len(gids), 2) + + k1 = PlatformKernel(self.path, busy_timeout_ms=3000) + k2 = PlatformKernel(self.path, busy_timeout_ms=3000) + barrier = threading.Barrier(2) + results = {} + + def _revoke(name, kernel, gid): + barrier.wait() + results[name] = kernel.revoke_platform_bootstrap(gid, actor_principal=INSTALLER).code + + try: + with ThreadPoolExecutor(max_workers=2) as ex: + f1 = ex.submit(_revoke, "a", k1, gids[0]) + f2 = ex.submit(_revoke, "b", k2, gids[1]) + f1.result() + f2.result() + codes = list(results.values()) + self.assertEqual(codes.count(INSTALLED), 1, f"exactly one revoke should win: {results}") + self.assertEqual(codes.count(AUTHORIZATION_DENIED), 1, f"one revoke must be denied: {results}") + self.assertEqual(k1.active_grant_count(), 1) + self.assertEqual(_count_where(k1, "platform_bootstrap_grants", "active = 1"), 1) + finally: + k1.close() + k2.close() + + def test_revoke_final_grant_denied(self) -> None: + k = PlatformKernel(self.path) + try: + self.assertEqual(k.install_platform(INSTALLER).code, INSTALLED) + gid = k._conn.execute( + "SELECT grant_id FROM platform_bootstrap_grants WHERE active = 1" + ).fetchone()[0] + res = k.revoke_platform_bootstrap(gid, actor_principal=INSTALLER) + self.assertEqual(res.code, AUTHORIZATION_DENIED) + self.assertEqual(k.active_grant_count(), 1) + self.assertEqual(_count_where(k, "platform_bootstrap_grants", "active = 1"), 1) + finally: + k.close() + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_branch_cleanup_guard.py b/tests/test_branch_cleanup_guard.py index 7a78998..0bd1fda 100644 --- a/tests/test_branch_cleanup_guard.py +++ b/tests/test_branch_cleanup_guard.py @@ -1266,6 +1266,378 @@ 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) + if __name__ == "__main__": diff --git a/tests/test_cross_role_queue_allocation.py b/tests/test_cross_role_queue_allocation.py new file mode 100644 index 0000000..4126d30 --- /dev/null +++ b/tests/test_cross_role_queue_allocation.py @@ -0,0 +1,581 @@ +"""Authoritative controller cross-role generic queue allocation (#840).""" + +from __future__ import annotations + +import os +import tempfile +import unittest +from unittest.mock import patch + +from allocator_service import ( + ALLOCATION_MODE_CROSS_ROLE, + ALLOCATION_MODE_ROLE_SCOPED, + OUTCOME_NO_SAFE, + OUTCOME_PREVIEW, + OUTCOME_WAIT, + ROLE_AUTHOR, + ROLE_CONTROLLER, + ROLE_MERGER, + ROLE_RECONCILER, + ROLE_REVIEWER, + WorkCandidate, + allocate_next_work, + build_selection_dict, + classify_skip, + required_namespace_for_role, + required_profile_for_role, + resolve_allocation_mode, + selected_action_for_candidate, +) +from control_plane_db import ControlPlaneDB +import role_session_router +from role_session_router import ( + ROUTE_ALLOWED, + ROUTE_AMBIGUOUS, + ROUTE_WRONG_ROLE, + route_task_session, +) +import namespace_workspace_binding as nwb +import task_capability_map + + +class CrossRoleAllocationModeTest(unittest.TestCase): + def test_controller_defaults_to_cross_role(self) -> None: + self.assertEqual( + resolve_allocation_mode(ROLE_CONTROLLER), + ALLOCATION_MODE_CROSS_ROLE, + ) + + def test_worker_defaults_to_role_scoped(self) -> None: + for role in (ROLE_AUTHOR, ROLE_REVIEWER, ROLE_MERGER, ROLE_RECONCILER): + self.assertEqual( + resolve_allocation_mode(role), + ALLOCATION_MODE_ROLE_SCOPED, + ) + + def test_explicit_modes(self) -> None: + self.assertEqual( + resolve_allocation_mode(ROLE_CONTROLLER, "role_scoped"), + ALLOCATION_MODE_ROLE_SCOPED, + ) + self.assertEqual( + resolve_allocation_mode(ROLE_AUTHOR, "cross_role"), + ALLOCATION_MODE_CROSS_ROLE, + ) + + +class CrossRoleSelectionPayloadTest(unittest.TestCase): + def test_selection_contains_required_fields(self) -> None: + c = WorkCandidate( + kind="issue", + number=840, + labels=("status:ready",), + title="cross-role", + priority=20, + ) + sel = build_selection_dict( + c, + active_role=ROLE_CONTROLLER, + required_role=ROLE_AUTHOR, + profile_name="prgs-controller", + allocation_mode=ALLOCATION_MODE_CROSS_ROLE, + ) + self.assertEqual(sel["number"], 840) + self.assertEqual(sel["kind"], "issue") + self.assertEqual(sel["required_role"], ROLE_AUTHOR) + self.assertEqual(sel["selected_action"], "implement") + self.assertEqual(sel["action"], "implement") + self.assertEqual(sel["required_profile"], "prgs-author") + self.assertEqual(sel["required_namespace"], "gitea-author") + self.assertEqual(sel["pinned"]["number"], 840) + self.assertIsNone(sel["pinned"]["head_sha"]) + + def test_profile_prefix_preserved(self) -> None: + self.assertEqual( + required_profile_for_role(ROLE_REVIEWER, profile_name="dadeschools-controller"), + "dadeschools-reviewer", + ) + self.assertEqual( + required_namespace_for_role(ROLE_MERGER), + "gitea-merger", + ) + + def test_selected_actions_per_role(self) -> None: + issue = WorkCandidate(kind="issue", number=1, labels=("status:ready",)) + pr_review = WorkCandidate(kind="pr", number=2, head_sha="a" * 40) + pr_rc = WorkCandidate( + kind="pr", + number=3, + head_sha="b" * 40, + request_changes_current_head=True, + ) + pr_merge = WorkCandidate( + kind="pr", + number=4, + head_sha="c" * 40, + approval_on_current_head=True, + mergeable=True, + ) + pr_recon = WorkCandidate( + kind="pr", + number=5, + head_sha="d" * 40, + approval_contaminated=True, + ) + self.assertEqual(selected_action_for_candidate(issue, ROLE_AUTHOR), "implement") + self.assertEqual( + selected_action_for_candidate(pr_rc, ROLE_AUTHOR), + "address_pr_change_requests", + ) + self.assertEqual( + selected_action_for_candidate(pr_review, ROLE_REVIEWER), "review" + ) + self.assertEqual(selected_action_for_candidate(pr_merge, ROLE_MERGER), "merge") + self.assertEqual( + selected_action_for_candidate(pr_recon, ROLE_RECONCILER), + "reconcile_contaminated_approval", + ) + + +class CrossRoleAllocateServiceTest(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 _alloc(self, **kwargs): + defaults = dict( + db=self.db, + session_id="ctrl-session", + role=ROLE_CONTROLLER, + remote="prgs", + org="org", + repo="repo", + candidates=[], + apply=False, + profile_name="prgs-controller", + username="controller-bot", + controller_instance_id="ctrl-1", + ) + defaults.update(kwargs) + return allocate_next_work(**defaults) + + def test_eligible_author_work(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=100, + labels=("status:ready",), + title="author work", + priority=20, + ), + ] + res = self._alloc(candidates=cands) + self.assertTrue(res["success"]) + self.assertEqual(res["outcome"], OUTCOME_PREVIEW) + self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_CROSS_ROLE) + self.assertIsNotNone(res["selected"]) + self.assertEqual(res["selected"]["number"], 100) + self.assertEqual(res["required_role"], ROLE_AUTHOR) + self.assertEqual(res["selected_action"], "implement") + self.assertEqual(res["required_profile"], "prgs-author") + self.assertEqual(res["required_namespace"], "gitea-author") + self.assertIn("allocate", res["controller_allowed_actions"]) + self.assertIn("merge", res["controller_forbidden_actions"]) + self.assertFalse(res["allocation_evidence"]["lease_created"]) + + def test_eligible_reviewer_work(self) -> None: + cands = [ + WorkCandidate( + kind="pr", + number=200, + head_sha="e" * 40, + title="needs review", + priority=30, + ), + ] + res = self._alloc(candidates=cands) + self.assertEqual(res["selected"]["number"], 200) + self.assertEqual(res["required_role"], ROLE_REVIEWER) + self.assertEqual(res["selected_action"], "review") + self.assertEqual(res["required_profile"], "prgs-reviewer") + self.assertEqual(res["selected"]["pinned"]["head_sha"], "e" * 40) + + def test_eligible_merger_work(self) -> None: + cands = [ + WorkCandidate( + kind="pr", + number=300, + head_sha="f" * 40, + approval_on_current_head=True, + mergeable=True, + priority=40, + ), + ] + res = self._alloc(candidates=cands) + self.assertEqual(res["selected"]["number"], 300) + self.assertEqual(res["required_role"], ROLE_MERGER) + self.assertEqual(res["selected_action"], "merge") + + def test_eligible_reconciler_work(self) -> None: + cands = [ + WorkCandidate( + kind="pr", + number=400, + head_sha="1" * 40, + approval_contaminated=True, + priority=50, + ), + ] + res = self._alloc(candidates=cands) + self.assertEqual(res["selected"]["number"], 400) + self.assertEqual(res["required_role"], ROLE_RECONCILER) + self.assertIn("reconcile", res["selected_action"]) + + def test_no_eligible_work(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=10, + labels=("status:blocked",), + blocked=True, + priority=99, + ), + WorkCandidate( + kind="issue", + number=11, + labels=("status:ready",), + dependency_unmet=True, + dependency_reason="blocked by #10", + priority=98, + ), + ] + res = self._alloc(candidates=cands) + self.assertTrue(res["success"]) + self.assertEqual(res["outcome"], OUTCOME_NO_SAFE) + self.assertIsNone(res["selected"]) + self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_CROSS_ROLE) + + def test_leased_work_skipped(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=50, + labels=("status:ready",), + priority=20, + ), + WorkCandidate( + kind="issue", + number=51, + labels=("status:ready",), + priority=10, + ), + ] + # Seed a foreign lease on issue 50 via assign_and_lease under another session. + other = allocate_next_work( + self.db, + session_id="other-worker", + role=ROLE_AUTHOR, + remote="prgs", + org="org", + repo="repo", + candidates=cands[:1], + apply=True, + profile_name="prgs-author", + controller_instance_id="other-ctrl", + ) + self.assertEqual(other["outcome"], "assigned_work") + res = self._alloc(candidates=cands) + self.assertIsNotNone(res["selected"]) + self.assertEqual(res["selected"]["number"], 51) + self.assertTrue(any(s["number"] == 50 for s in res["skipped"])) + self.assertTrue(res["claims_excluded"]) + + def test_dependencies_skipped(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=1, + labels=("status:ready",), + priority=99, + dependency_unmet=True, + dependency_reason="needs #2", + ), + WorkCandidate( + kind="issue", + number=2, + labels=("status:ready",), + priority=1, + ), + ] + res = self._alloc(candidates=cands) + self.assertEqual(res["selected"]["number"], 2) + skipped = {s["number"]: s["reason"] for s in res["skipped"]} + self.assertIn(1, skipped) + self.assertIn("needs #2", skipped[1]) + + def test_pagination_limit_only_truncates_skip_report(self) -> None: + """Ranking uses full inventory; reporting limit is MCP-layer only. + + Service ranks all candidates; prove higher-priority eligible item + wins even when many skipped precede it. + """ + cands = [] + for n in range(1, 30): + cands.append( + WorkCandidate( + kind="issue", + number=n, + labels=("status:ready",), + priority=100 - n, + dependency_unmet=True, + dependency_reason=f"dep {n}", + ) + ) + cands.append( + WorkCandidate( + kind="issue", + number=999, + labels=("status:ready",), + priority=1, + ) + ) + res = self._alloc(candidates=cands) + self.assertEqual(res["selected"]["number"], 999) + self.assertGreaterEqual(len(res["skipped"]), 29) + + def test_role_scoped_controller_legacy_still_restricts(self) -> None: + """role_scoped controller only takes reconciler-needed items.""" + cands = [ + WorkCandidate( + kind="issue", + number=1, + labels=("status:ready",), + priority=50, + ), + WorkCandidate( + kind="pr", + number=2, + head_sha="a" * 40, + approval_contaminated=True, + priority=1, + ), + ] + res = self._alloc( + candidates=cands, + allocation_mode=ALLOCATION_MODE_ROLE_SCOPED, + ) + self.assertEqual(res["allocation_mode"], ALLOCATION_MODE_ROLE_SCOPED) + self.assertEqual(res["selected"]["number"], 2) + self.assertEqual(res["required_role"], ROLE_RECONCILER) + + def test_cross_role_prefers_highest_priority_across_roles(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=10, + labels=("status:ready",), + priority=10, + ), + WorkCandidate( + kind="pr", + number=20, + head_sha="b" * 40, + priority=50, + ), + WorkCandidate( + kind="pr", + number=30, + head_sha="c" * 40, + approval_on_current_head=True, + mergeable=True, + priority=20, + ), + ] + res = self._alloc(candidates=cands) + # PR #20 highest priority → reviewer + self.assertEqual(res["selected"]["number"], 20) + self.assertEqual(res["required_role"], ROLE_REVIEWER) + + def test_apply_creates_lease_evidence_for_required_role(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=777, + labels=("status:ready",), + priority=20, + ), + ] + res = self._alloc(candidates=cands, apply=True) + self.assertEqual(res["outcome"], "assigned_work") + self.assertTrue(res["allocation_evidence"]["lease_created"]) + self.assertEqual(res["allocation_evidence"]["lease_role"], ROLE_AUTHOR) + proof = res["lease_proof"] + self.assertIsNotNone(proof["lease_id"]) + self.assertEqual(proof["lease_role"], ROLE_AUTHOR) + self.assertIn("implement", proof["allowed_actions"]) + # Controller isolation: controller still forbids merge/push/create_pr + self.assertIn("merge", res["controller_forbidden_actions"]) + self.assertIn("push", res["controller_forbidden_actions"]) + + def test_metadata_consistency_role_is_controller(self) -> None: + cands = [ + WorkCandidate( + kind="issue", + number=1, + labels=("status:ready",), + ), + ] + res = self._alloc(candidates=cands) + self.assertEqual(res["role"], ROLE_CONTROLLER) + self.assertEqual(res["routing_role"], ROLE_CONTROLLER) + self.assertEqual(res["required_role"], ROLE_AUTHOR) + + +class ProcessWorkQueueRouterTest(unittest.TestCase): + def tearDown(self) -> None: + role_session_router.clear_route_state() + + def test_process_work_queue_allowed_for_controller(self) -> None: + res = route_task_session( + "process_work_queue", + active_profile="prgs-controller", + active_role_kind="controller", + allowed_in_current_session=True, + ) + self.assertEqual(res["route_result"], ROUTE_ALLOWED) + self.assertEqual(res["required_role"], "controller") + self.assertTrue(res["downstream_allowed"]) + + def test_process_work_queue_hyphen_alias(self) -> None: + res = route_task_session( + "process-work-queue", + active_profile="prgs-controller", + active_role_kind="controller", + allowed_in_current_session=True, + ) + self.assertEqual(res["route_result"], ROUTE_ALLOWED) + + def test_process_work_queue_wrong_role_for_author(self) -> None: + res = route_task_session( + "process_work_queue", + active_profile="prgs-author", + active_role_kind="author", + allowed_in_current_session=False, + ) + self.assertEqual(res["route_result"], ROUTE_WRONG_ROLE) + self.assertEqual(res["required_role"], "controller") + self.assertFalse(res["downstream_allowed"]) + + def test_unknown_still_ambiguous(self) -> None: + res = route_task_session( + "not_a_real_task", + active_profile="prgs-controller", + active_role_kind="controller", + allowed_in_current_session=False, + ) + self.assertEqual(res["route_result"], ROUTE_AMBIGUOUS) + + def test_capability_map_process_work_queue_is_controller(self) -> None: + self.assertEqual( + task_capability_map.required_role("process_work_queue"), + "controller", + ) + self.assertEqual( + task_capability_map.required_permission("process_work_queue"), + "gitea.read", + ) + + +class ControllerRoleMetadataTest(unittest.TestCase): + def test_normalize_role_kind_controller(self) -> None: + self.assertEqual( + nwb.normalize_role_kind("controller"), + "controller", + ) + self.assertEqual( + nwb.normalize_role_kind("author", profile_name="prgs-controller"), + "controller", + ) + self.assertEqual( + nwb.normalize_role_kind("reconciler", profile_name="prgs-controller"), + "controller", + ) + + def test_profile_role_kind_prefers_declared_controller(self) -> None: + # Import from worktree package path via sys.path already set by pytest. + import gitea_mcp_server as mcp + + profile = { + "profile_name": "prgs-controller", + "role": "controller", + "allowed_operations": [ + "gitea.read", + "gitea.issue.comment", + "gitea.pr.close", + ], + "forbidden_operations": [ + "gitea.pr.approve", + "gitea.pr.merge", + "gitea.pr.create", + "gitea.branch.push", + ], + } + # Declared role wins even if permissions look reconciler-like. + self.assertEqual(mcp._profile_role_kind(profile), "controller") + # Name-based fallback. + profile_no_role = dict(profile) + profile_no_role["role"] = None + profile_no_role["role_kind"] = None + self.assertEqual(mcp._profile_role_kind(profile_no_role), "controller") + + def test_permission_inference_without_controller_name_stays_reconciler(self) -> None: + import gitea_mcp_server as mcp + + # Pure permission inference still may return reconciler when no controller + # declaration exists — that is intentional for reconciler profiles. + role = mcp._role_kind( + ["gitea.read", "gitea.pr.close", "gitea.issue.comment"], + ["gitea.pr.approve", "gitea.pr.merge", "gitea.pr.create", "gitea.branch.push"], + ) + self.assertEqual(role, "reconciler") + + +class DashboardRemainsExplanatoryTest(unittest.TestCase): + def test_dashboard_prompt_points_at_allocator_not_self_select(self) -> None: + import workflow_dashboard as wd + + self.assertIn("gitea_allocate_next_work", wd.PROMPT_CONTROLLER) + self.assertIn("process_work_queue", wd.PROMPT_CONTROLLER) + self.assertIn("never replaces allocator", wd.PROMPT_CONTROLLER.lower()) + self.assertNotIn("self-select", wd.PROMPT_CONTROLLER.lower()) + + +class ClassifySkipCrossRoleTest(unittest.TestCase): + def test_controller_cross_role_accepts_author_issue(self) -> None: + c = WorkCandidate(kind="issue", number=1, labels=("status:ready",)) + self.assertIsNone( + classify_skip( + c, + role=ROLE_CONTROLLER, + terminal_pr=None, + allocation_mode=ALLOCATION_MODE_CROSS_ROLE, + ) + ) + + def test_legacy_controller_skips_author_issue(self) -> None: + c = WorkCandidate(kind="issue", number=1, labels=("status:ready",)) + reason = classify_skip( + c, + role=ROLE_CONTROLLER, + terminal_pr=None, + allocation_mode=ALLOCATION_MODE_ROLE_SCOPED, + ) + self.assertIsNotNone(reason) + self.assertIn("does not require controller", reason or "") + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_dirty_same_claimant_session_rebind.py b/tests/test_dirty_same_claimant_session_rebind.py new file mode 100644 index 0000000..c40933e --- /dev/null +++ b/tests/test_dirty_same_claimant_session_rebind.py @@ -0,0 +1,1346 @@ +"""Integration tests for dirty same-claimant author-session rebind (#864 / #868). + +Uses real temp git repos/worktrees and a temp GITEA_ISSUE_LOCK_DIR. Does not +mutate any real #860/#864/#868 worktree on disk. + +#868 adds complete dirty-inventory revalidation around bind_session_lock and +complete recovery-journal operation identity (remote/org/repo/claimant). +""" + +from __future__ import annotations + +import json +import os +import subprocess +import sys +import tempfile +from datetime import datetime, timedelta, timezone +from pathlib import Path + +import pytest + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +import dirty_same_claimant_session_rebind as rebind # noqa: E402 +import issue_lock_provenance # noqa: E402 +import issue_lock_store as ils # noqa: E402 +import issue_lock_worktree # noqa: E402 + +ISSUE = 864 +BRANCH = f"fix/issue-{ISSUE}-dirty-same-claimant-session-rebind" +REMOTE = "prgs" +ORG = "Scaled-Tech-Consulting" +REPO = "Gitea-Tools" +IDENTITY = "jcwalker3" +PROFILE = "prgs-author" + + +def _git(cwd: str, *args: str, check: bool = True) -> subprocess.CompletedProcess: + return subprocess.run( + ["git", "-C", cwd, *args], + capture_output=True, + text=True, + check=check, + ) + + +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") + ) + + +@pytest.fixture +def lock_dir(tmp_path, monkeypatch): + d = tmp_path / "issue-locks" + d.mkdir() + monkeypatch.setenv("GITEA_ISSUE_LOCK_DIR", str(d)) + return str(d) + + +@pytest.fixture +def dirty_repo(tmp_path): + """Canonical repo root with branches/ worktree and dirty content.""" + root = tmp_path / "repo" + root.mkdir() + main = root / "main" + main.mkdir() + subprocess.run(["git", "init", "-q", str(main)], check=True, capture_output=True) + _git(str(main), "config", "user.email", "t@t") + _git(str(main), "config", "user.name", "t") + (main / "README.md").write_text("base\n", encoding="utf-8") + _git(str(main), "add", "README.md") + _git(str(main), "commit", "-q", "-m", "base") + _git(str(main), "branch", "-M", "master") + + # Bare remote + origin tracking so remote head is observable offline. + bare = tmp_path / "remote.git" + subprocess.run( + ["git", "init", "--bare", "-q", str(bare)], check=True, capture_output=True + ) + _git(str(main), "remote", "add", "origin", str(bare)) + _git(str(main), "push", "-q", "origin", "master:master") + + branches = root / "branches" + branches.mkdir() + wt_name = f"fix-issue-{ISSUE}-dirty-same-claimant-session-rebind" + wt = branches / wt_name + _git(str(main), "worktree", "add", "-q", "-b", BRANCH, str(wt)) + _git(str(wt), "push", "-q", "-u", "origin", BRANCH) + + # Seed committed files we will dirty. + tracked = [ + "dirty_same_claimant_session_rebind.py", + "issue_lock_provenance.py", + "task_capability_map.py", + ] + for rel in tracked: + p = wt / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(f"seed {rel}\n", encoding="utf-8") + _git(str(wt), "add", *tracked) + _git(str(wt), "commit", "-q", "-m", "seed tracked") + _git(str(wt), "push", "-q", "origin", BRANCH) + + # Dirty tracked + untracked. + for rel in tracked: + (wt / rel).write_text(f"dirty {rel}\n", encoding="utf-8") + untracked = [ + "tests/test_dirty_same_claimant_session_rebind.py", + "docs/runbook-dirty-rebind.md", + "scratch/notes-untracked.txt", + "extra_untracked.txt", + ] + for rel in untracked: + p = wt / rel + p.parent.mkdir(parents=True, exist_ok=True) + p.write_text(f"untracked {rel}\n", encoding="utf-8") + + inv = rebind.collect_dirty_inventory(str(wt)) + assert inv["ok"], inv.get("reasons") + head = _git(str(wt), "rev-parse", "HEAD").stdout.strip() + remote_head = _git( + str(wt), "rev-parse", f"refs/remotes/origin/{BRANCH}" + ).stdout.strip() + assert head == remote_head + + return { + "root": str(root), + "main": str(main), + "worktree": str(wt), + "branch": BRANCH, + "inventory": inv, + "local_head": head, + "remote_head": remote_head, + "dirty_paths": list(inv["dirty_paths"]), + "fingerprints": dict(inv["fingerprints"]), + } + + +def _make_lock( + *, + worktree: str, + pid: int, + lock_dir: str, + identity: str = IDENTITY, + profile: str = PROFILE, + **overrides, +) -> dict: + lease = { + "operation_type": ils.AUTHOR_ISSUE_WORK_LEASE, + "issue_number": ISSUE, + "branch": BRANCH, + "worktree_path": worktree, + "claimant": {"username": identity, "profile": profile}, + "created_at": "2026-01-01T00:00:00Z", + "expires_at": future_ts(), + "last_heartbeat_at": "2026-01-01T00:00:00Z", + } + lock = { + "issue_number": ISSUE, + "branch_name": BRANCH, + "worktree_path": worktree, + "remote": REMOTE, + "org": ORG, + "repo": REPO, + "session_pid": pid, + "pid": pid, + "work_lease": lease, + "lock_generation": 1, + "lock_provenance": issue_lock_provenance.build_sanctioned_lock_provenance( + tool="gitea_lock_issue", + claimant={"username": identity, "profile": profile}, + ), + } + lock.update(overrides) + path = ils.lock_file_path( + remote=REMOTE, org=ORG, repo=REPO, issue_number=ISSUE, lock_dir=lock_dir + ) + lock["lock_file_path"] = path + ils.save_lock_file(path, lock) + # Stale session pointer for the dead owner. + ptr = { + "pid": pid, + "lock_file_path": path, + "issue_number": ISSUE, + "branch_name": BRANCH, + "remote": REMOTE, + "org": ORG, + "repo": REPO, + } + ils.save_lock_file(os.path.join(lock_dir, f"session-{pid}.json"), ptr) + return ils.read_lock_file(path) or lock + + +def _apply_kwargs(repo, lock, lock_dir, **overrides): + kwargs = { + "remote": REMOTE, + "org": ORG, + "repo": REPO, + "issue_number": ISSUE, + "branch_name": BRANCH, + "worktree_path": repo["worktree"], + "claimant_identity": IDENTITY, + "claimant_profile": PROFILE, + "old_pid": lock.get("session_pid") or lock.get("pid"), + "expected_local_head": repo["local_head"], + "expected_remote_head": repo["remote_head"], + "expected_dirty_paths": repo["dirty_paths"], + "expected_fingerprints": repo["fingerprints"], + "existing_lock": lock, + "current_identity": IDENTITY, + "current_profile": PROFILE, + "role_kind": "author", + "current_pid": os.getpid(), + "current_branch": BRANCH, + "local_head": repo["local_head"], + "remote_head": repo["remote_head"], + "dirty_inventory": repo["inventory"], + "competing_live_locks": [], + "competing_sessions": [], + "workflow_lease_active": False, + "repo_root": repo["root"], + "dry_run": False, + "lock_dir": lock_dir, + } + kwargs.update(overrides) + return kwargs + + +# ── 1. Successful dead-PID same-claimant dirty rebind ─────────────────────── + + +def test_successful_dead_pid_same_claimant_dirty_rebind(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert result["success"], result + assert result["outcome"] == rebind.REBIND_SANCTIONED + assert result["old_pid"] == old + assert result["new_pid"] == os.getpid() + assert result["generation_after"] == result["generation_before"] + 1 + + rebound = ils.read_lock_file(result["lock_path"]) + assert rebound is not None + assert int(rebound["session_pid"]) == os.getpid() + assert int(rebound["pid"]) == os.getpid() + assert ( + rebound.get("lock_provenance", {}).get("source") + == issue_lock_provenance.SOURCE_DIRTY_SAME_CLAIMANT_REBIND + ) + assert rebound.get("rebind_record", {}).get("old_pid") == old + + +# ── 2. Byte-for-byte preservation ─────────────────────────────────────────── + + +def test_byte_for_byte_preservation(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + before = { + rel: rebind.content_fingerprint(os.path.join(dirty_repo["worktree"], rel)) + for rel in dirty_repo["dirty_paths"] + } + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert result["success"], result + after = { + rel: rebind.content_fingerprint(os.path.join(dirty_repo["worktree"], rel)) + for rel in dirty_repo["dirty_paths"] + } + assert before == after + assert result["fingerprints"] == before + + +# ── 3. Exact dirty-path and fingerprint enforcement ───────────────────────── + + +def test_extra_dirty_path_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + pins = list(dirty_repo["dirty_paths"])[:-1] # missing one observed path + fps = {p: dirty_repo["fingerprints"][p] for p in pins} + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_dirty_paths=pins, + expected_fingerprints=fps, + ) + ) + assert not result["success"] + assert any("unexpected paths" in r for r in result["reasons"]) + + +def test_missing_expected_dirty_path_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + pins = list(dirty_repo["dirty_paths"]) + ["not_really_dirty.txt"] + fps = dict(dirty_repo["fingerprints"]) + fps["not_really_dirty.txt"] = "0" * 64 + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_dirty_paths=pins, + expected_fingerprints=fps, + ) + ) + assert not result["success"] + assert any("missing expected" in r for r in result["reasons"]) + + +def test_modified_fingerprint_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + fps = dict(dirty_repo["fingerprints"]) + victim = dirty_repo["dirty_paths"][0] + fps[victim] = "f" * 64 + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_fingerprints=fps, + ) + ) + assert not result["success"] + assert any("fingerprint disagreement" in r for r in result["reasons"]) + + +# ── 4. Atomic session-pointer replacement ─────────────────────────────────── + + +def test_session_pointer_points_to_lock(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert result["success"], result + new_ptr_path = os.path.join(lock_dir, f"session-{os.getpid()}.json") + assert os.path.exists(new_ptr_path) + ptr = ils.read_lock_file(new_ptr_path) + assert ptr is not None + assert os.path.realpath(ptr["lock_file_path"]) == os.path.realpath( + result["lock_path"] + ) + # Old pointer removed when it targeted this lock. + old_ptr = os.path.join(lock_dir, f"session-{old}.json") + assert not os.path.exists(old_ptr) + assert result.get("removed_old_session_pointer") is True + + +# ── 5. Retry after interruption (journal mid-state) ───────────────────────── + + +def test_retry_after_journal_mid_state(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + # Complete operation identity required for mid-flight resume (#868 F2). + rebind._atomic_write_json( + jpath, + { + "phase": rebind.JOURNAL_PHASE_PRE_BIND, + "issue_number": ISSUE, + "old_pid": old, + "new_pid": os.getpid(), + "expected_generation": 1, + "remote": REMOTE, + "org": ORG, + "repo": REPO, + "claimant_identity": IDENTITY, + "claimant_profile": PROFILE, + "source": rebind.SOURCE, + }, + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert result["success"], result + assert result["journal_phase"] == rebind.JOURNAL_PHASE_COMPLETE + + # Second apply is already_rebound (retry-safe). + rebound_lock = ils.read_lock_file(result["lock_path"]) + result2 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + rebound_lock, + lock_dir, + old_pid=old, + existing_lock=rebound_lock, + ) + ) + assert result2["success"], result2 + assert result2["already_rebound"] is True + + +# ── 6. Active-PID refusal ─────────────────────────────────────────────────── + + +def test_active_pid_refused(dirty_repo, lock_dir): + live = os.getpid() + # Use a different "current" identity of session via fake current_pid... + # Owner is live (this process). Rebind must refuse. + lock = _make_lock(worktree=dirty_repo["worktree"], pid=live, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=live, + current_pid=live + 10_000_000, # distinct "new" session id for pin check + ) + ) + assert not result["success"] + assert any("still alive" in r for r in result["reasons"]) + + +# ── 7. Foreign claimant refusal ───────────────────────────────────────────── + + +def test_foreign_claimant_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + current_identity="someone-else", + claimant_identity="someone-else", + ) + ) + assert not result["success"] + assert any("foreign claimant" in r or "does not match" in r for r in result["reasons"]) + + +# ── 8. Profile mismatch refusal ───────────────────────────────────────────── + + +def test_profile_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + current_profile="other-profile", + claimant_profile="other-profile", + ) + ) + assert not result["success"] + assert any("profile" in r for r in result["reasons"]) + + +# ── 9. Competing session/lock/lease refusal ───────────────────────────────── + + +def test_competing_live_lock_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + competing = [ + { + "issue_number": ISSUE, + "branch_name": BRANCH, + "worktree_path": dirty_repo["worktree"] + "-other", + "pid": os.getpid(), + } + ] + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + competing_live_locks=competing, + ) + ) + assert not result["success"] + assert any("competing live lock" in r for r in result["reasons"]) + + +def test_competing_session_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + competing_sessions=[ + {"pid": os.getpid(), "lock_file_path": lock["lock_file_path"], "live": True} + ], + ) + ) + # current_pid is os.getpid(), so same session is skipped — use another live pid. + # Spawn a long-lived process to act as competing live session. + rival = subprocess.Popen([sys.executable, "-c", "import time; time.sleep(30)"]) + try: + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + competing_sessions=[ + { + "pid": rival.pid, + "lock_file_path": lock["lock_file_path"], + "live": True, + } + ], + ) + ) + assert not result["success"] + assert any("competing live session" in r for r in result["reasons"]) + finally: + rival.kill() + rival.wait() + + +def test_workflow_lease_active_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + workflow_lease_active=True, + ) + ) + assert not result["success"] + assert any("workflow lease" in r for r in result["reasons"]) + + +# ── 10. Local- and remote-head movement refusal ───────────────────────────── + + +def test_local_head_movement_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_local_head="b" * 40, + ) + ) + assert not result["success"] + assert any("local head" in r for r in result["reasons"]) + + +def test_remote_head_movement_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_remote_head="c" * 40, + ) + ) + assert not result["success"] + assert any("remote head" in r for r in result["reasons"]) + + +# ── 11. Path/symlink/registration mismatches ──────────────────────────────── + + +def test_worktree_not_under_branches_refused(dirty_repo, lock_dir, tmp_path): + old = dead_pid() + # Use a path outside branches/ as the declared worktree (still real dir). + outside = tmp_path / "outside-wt" + outside.mkdir() + lock = _make_lock(worktree=str(outside), pid=old, lock_dir=lock_dir) + # Inventory empty for outside path; use empty pins to hit path gate first + # by providing matching empty-ish inventory after we force path checks. + inv = { + "dirty_paths": dirty_repo["dirty_paths"], + "fingerprints": dirty_repo["fingerprints"], + "ok": True, + "reasons": [], + } + result = rebind.assess_dirty_same_claimant_session_rebind( + remote=REMOTE, + org=ORG, + repo=REPO, + issue_number=ISSUE, + branch_name=BRANCH, + worktree_path=str(outside), + claimant_identity=IDENTITY, + claimant_profile=PROFILE, + old_pid=old, + expected_local_head=dirty_repo["local_head"], + expected_remote_head=dirty_repo["remote_head"], + expected_dirty_paths=dirty_repo["dirty_paths"], + expected_fingerprints=dirty_repo["fingerprints"], + existing_lock=lock, + current_identity=IDENTITY, + current_profile=PROFILE, + role_kind="author", + current_pid=os.getpid(), + current_branch=BRANCH, + local_head=dirty_repo["local_head"], + remote_head=dirty_repo["remote_head"], + dirty_inventory=inv, + repo_root=dirty_repo["root"], + ) + assert not result["rebind_sanctioned"] + assert any("branches/" in r for r in result["reasons"]) + + +def test_lock_worktree_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock( + worktree=dirty_repo["worktree"] + "-elsewhere", + pid=old, + lock_dir=lock_dir, + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("does not match declared" in r for r in result["reasons"]) + + +# ── 12. Malformed lock/session records ────────────────────────────────────── + + +def test_malformed_lock_missing_pid_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + lock.pop("session_pid", None) + lock.pop("pid", None) + ils.save_lock_file(lock["lock_file_path"], lock) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("incomplete" in r or "session_pid" in r for r in result["reasons"]) + + +def test_empty_old_pid_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=None) + ) + assert not result["success"] + assert any("old_pid" in r for r in result["reasons"]) + + +def test_reviewer_role_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old, role_kind="reviewer") + ) + assert not result["success"] + assert any("reviewer" in r for r in result["reasons"]) + + +def test_reconciler_without_authorize_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + role_kind="reconciler", + authorize_reconciler_execute=False, + ) + ) + assert not result["success"] + assert any("authorize_reconciler_execute" in r for r in result["reasons"]) + + +# ── 13. No duplicate ownership after success or retry ─────────────────────── + + +def test_no_duplicate_ownership_after_success_or_retry(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + r1 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert r1["success"], r1 + rebound = ils.read_lock_file(r1["lock_path"]) + r2 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, rebound, lock_dir, old_pid=old, existing_lock=rebound) + ) + assert r2["success"], r2 + assert r2["already_rebound"] is True + + # Only one durable lock file for this issue; session pointer is current pid. + # Skip session pointers and rebind journals (dotfiles / non-lock records). + matching = [] + for p in ils.iter_lock_files(lock_dir): + name = os.path.basename(p) + if name.startswith(".") or name.startswith("session-"): + continue + rec = ils.read_lock_file(p) + if not rec: + continue + if ( + rec.get("issue_number") == ISSUE + and rec.get("remote") == REMOTE + and rec.get("branch_name") == BRANCH + and rec.get("session_pid") is not None + ): + matching.append(rec) + assert len(matching) == 1 + assert int(matching[0]["session_pid"]) == os.getpid() + # No live session pointer for the dead old pid. + assert not os.path.exists(os.path.join(lock_dir, f"session-{old}.json")) + + +# ── 14. Ordinary dirty-worktree locking remains fail-closed ───────────────── + + +def test_ordinary_dirty_lock_worktree_assessment_blocks(dirty_repo): + porcelain = dirty_repo["inventory"]["porcelain_status"] + assessment = issue_lock_worktree.assess_issue_lock_worktree( + worktree_path=dirty_repo["worktree"], + current_branch=BRANCH, + porcelain_status=porcelain, + base_equivalent=False, + ) + assert assessment["block"] is True + assert any( + "tracked file edits exist before issue lock" in r + for r in assessment["reasons"] + ) + + +# ── 15. Fixture matching #860 class with 7 fingerprint-pinned dirty paths ─── + + +def test_issue_860_regression_fixture_spec(): + spec = rebind.build_issue_860_regression_fixture_spec() + assert spec["claimant_identity"] == "jcwalker3" + assert spec["claimant_profile"] == "prgs-author" + assert spec["old_pid_alive"] is False + assert spec["live_session_pointer"] is None + assert spec["dirty_path_count"] == 7 + assert len(spec["expected_dirty_paths"]) == 7 + assert len(spec["expected_fingerprints"]) == 7 + assert spec["expected_local_head"] == spec["expected_remote_head"] + for path in spec["expected_dirty_paths"]: + assert path in spec["expected_fingerprints"] + assert len(spec["expected_fingerprints"][path]) == 64 + + +def test_dry_run_does_not_write(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + before = ils.read_lock_file(lock["lock_file_path"]) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old, dry_run=True) + ) + assert result["success"], result + assert result["dry_run"] is True + after = ils.read_lock_file(lock["lock_file_path"]) + assert after["session_pid"] == before["session_pid"] + assert not os.path.exists(os.path.join(lock_dir, f"session-{os.getpid()}.json")) + + +def test_provenance_source_is_sanctioned(): + assert ( + issue_lock_provenance.SOURCE_DIRTY_SAME_CLAIMANT_REBIND + in issue_lock_provenance.SANCTIONED_LOCK_SOURCES + ) + assessment = issue_lock_provenance.assess_lock_file_for_create_pr( + { + "work_lease": {"operation_type": "author_issue_work"}, + "lock_provenance": { + "source": issue_lock_provenance.SOURCE_DIRTY_SAME_CLAIMANT_REBIND, + "written_by_tool": issue_lock_provenance.SOURCE_DIRTY_SAME_CLAIMANT_REBIND, + "written_at": "2026-01-01T00:00:00Z", + }, + } + ) + assert assessment["proven"] is True + + +def test_permission_allowed_is_not_ownership_proof(dirty_repo, lock_dir): + """permission_allowed=True must not bypass foreign claimant refusal.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.assess_dirty_same_claimant_session_rebind( + remote=REMOTE, + org=ORG, + repo=REPO, + issue_number=ISSUE, + branch_name=BRANCH, + worktree_path=dirty_repo["worktree"], + claimant_identity=IDENTITY, + claimant_profile=PROFILE, + old_pid=old, + expected_local_head=dirty_repo["local_head"], + expected_remote_head=dirty_repo["remote_head"], + expected_dirty_paths=dirty_repo["dirty_paths"], + expected_fingerprints=dirty_repo["fingerprints"], + existing_lock=lock, + current_identity="intruder", + current_profile=PROFILE, + role_kind="author", + current_pid=os.getpid(), + current_branch=BRANCH, + local_head=dirty_repo["local_head"], + remote_head=dirty_repo["remote_head"], + dirty_inventory=dirty_repo["inventory"], + permission_allowed=True, + repo_root=dirty_repo["root"], + ) + assert not result["rebind_sanctioned"] + assert any("does not match active identity" in r for r in result["reasons"]) + + +def test_content_fingerprint_stable(tmp_path): + p = tmp_path / "f.txt" + p.write_bytes(b"abc123") + a = rebind.content_fingerprint(str(p)) + b = rebind.content_fingerprint(str(p)) + assert a == b + assert len(a) == 64 + + +# ── #868 F1 — Complete dirty-inventory revalidation ───────────────────────── + + +def test_extra_tracked_dirty_path_before_bind_refused(dirty_repo, lock_dir): + """Extra tracked dirty path appearing immediately before binding fails closed.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + wt = dirty_repo["worktree"] + # Seed a tracked file, then dirty it without including it in the pin set. + tracked_extra = "tracked_extra_before_bind.txt" + path = Path(wt) / tracked_extra + path.write_text("seed tracked extra\n", encoding="utf-8") + _git(wt, "add", tracked_extra) + _git(wt, "commit", "-q", "-m", "seed extra tracked") + # Heads moved — re-pin heads so only inventory disagreement is tested. + head = _git(wt, "rev-parse", "HEAD").stdout.strip() + _git(wt, "push", "-q", "origin", BRANCH) + remote_head = _git(wt, "rev-parse", f"refs/remotes/origin/{BRANCH}").stdout.strip() + path.write_text("dirty tracked extra\n", encoding="utf-8") + # Pins still describe the original inventory (without tracked_extra). + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + expected_local_head=head, + expected_remote_head=remote_head, + local_head=head, + remote_head=remote_head, + dirty_inventory=None, # force live recollect in apply + ) + ) + assert not result["success"] + joined = " ".join(result["reasons"]) + assert "unexpected paths" in joined or "path-set disagreement" in joined + # Must not leave a newly authoritative live session for this pid. + rebound = ils.read_lock_file(lock["lock_file_path"]) + assert rebound is not None + assert int(rebound.get("session_pid") or 0) == old + + +def test_extra_untracked_path_before_bind_refused(dirty_repo, lock_dir): + """Extra untracked path appearing immediately before binding fails closed.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + wt = dirty_repo["worktree"] + extra = Path(wt) / "surprise_untracked_before_bind.txt" + extra.write_text("sneaky\n", encoding="utf-8") + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + dirty_inventory=None, + ) + ) + assert not result["success"] + joined = " ".join(result["reasons"]) + assert "unexpected paths" in joined or "path-set disagreement" in joined + rebound = ils.read_lock_file(lock["lock_file_path"]) + assert int(rebound.get("session_pid") or 0) == old + + +def test_path_added_during_mutation_window_refused(dirty_repo, lock_dir, monkeypatch): + """Path added during the mutation window is detected by post-bind inventory.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + wt = dirty_repo["worktree"] + real_bind = ils.bind_session_lock + + def _bind_then_add_path(lock_payload, **kwargs): + path = real_bind(lock_payload, **kwargs) + surprise = Path(wt) / "added_during_bind.txt" + surprise.write_text("during bind\n", encoding="utf-8") + return path + + monkeypatch.setattr(rebind, "bind_session_lock", _bind_then_add_path) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old, dirty_inventory=None) + ) + assert not result["success"] + joined = " ".join(result["reasons"]) + assert "post-bind" in joined + assert "unexpected paths" in joined or "path-set disagreement" in joined + assert result.get("journal_phase") == "post_bind_inventory_failed" + + +def test_path_removed_during_mutation_window_refused(dirty_repo, lock_dir, monkeypatch): + """Path removed during the mutation window is detected by post-bind inventory.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + wt = dirty_repo["worktree"] + victim = dirty_repo["dirty_paths"][-1] # prefer untracked for easy remove + real_bind = ils.bind_session_lock + + def _bind_then_remove_path(lock_payload, **kwargs): + path = real_bind(lock_payload, **kwargs) + target = Path(wt) / victim + if target.exists(): + target.unlink() + return path + + monkeypatch.setattr(rebind, "bind_session_lock", _bind_then_remove_path) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old, dirty_inventory=None) + ) + assert not result["success"] + joined = " ".join(result["reasons"]) + assert "post-bind" in joined + assert "missing expected" in joined or "path-set disagreement" in joined + + +def test_fingerprint_movement_unchanged_path_set_refused(dirty_repo, lock_dir, monkeypatch): + """Fingerprint movement with unchanged path set fails pre- or post-bind check.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + wt = dirty_repo["worktree"] + victim = dirty_repo["dirty_paths"][0] + real_bind = ils.bind_session_lock + + def _bind_then_mutate_bytes(lock_payload, **kwargs): + path = real_bind(lock_payload, **kwargs) + target = Path(wt) / victim + target.write_text(target.read_text(encoding="utf-8") + "mutated\n", encoding="utf-8") + return path + + monkeypatch.setattr(rebind, "bind_session_lock", _bind_then_mutate_bytes) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old, dirty_inventory=None) + ) + assert not result["success"] + joined = " ".join(result["reasons"]) + assert "fingerprint" in joined + assert "post-bind" in joined + + +# ── #868 F2 — Complete recovery-journal identity ──────────────────────────── + + +def _complete_journal(**overrides): + base = { + "phase": rebind.JOURNAL_PHASE_ASSESSED, + "issue_number": ISSUE, + "branch_name": BRANCH, + "worktree_path": "/tmp/wt", + "old_pid": 1, + "new_pid": os.getpid(), + "remote": REMOTE, + "org": ORG, + "repo": REPO, + "claimant_identity": IDENTITY, + "claimant_profile": PROFILE, + "source": rebind.SOURCE, + } + base.update(overrides) + return base + + +def test_journal_remote_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_PRE_BIND, + old_pid=old, + remote="dadeschools", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("remote" in r and "mismatch" in r for r in result["reasons"]) + + +def test_journal_org_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_PRE_BIND, + old_pid=old, + org="Other-Org", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("org" in r and "mismatch" in r for r in result["reasons"]) + + +def test_journal_repo_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_PRE_BIND, + old_pid=old, + repo="Other-Repo", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("repo" in r and "mismatch" in r for r in result["reasons"]) + + +def test_journal_claimant_identity_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_PRE_BIND, + old_pid=old, + claimant_identity="intruder", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("claimant_identity" in r for r in result["reasons"]) + + +def test_journal_claimant_profile_mismatch_refused(dirty_repo, lock_dir): + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_PRE_BIND, + old_pid=old, + claimant_profile="prgs-reviewer", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("claimant_profile" in r for r in result["reasons"]) + + +def test_incomplete_legacy_journal_identity_refused(dirty_repo, lock_dir): + """Pre-#868 journals missing the five identity fields fail closed mid-flight.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + { + "phase": rebind.JOURNAL_PHASE_PRE_BIND, + "issue_number": ISSUE, + "old_pid": old, + "new_pid": os.getpid(), + # deliberately omit remote/org/repo/claimant_* + }, + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("omits operation identity" in r for r in result["reasons"]) + + +def test_journal_replay_cross_repository_refused(dirty_repo, lock_dir): + """Replaying a journal from another repository is refused.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_ASSESSED, + old_pid=old, + remote="dadeschools", + org="Other-Org", + repo="Other-Repo", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("replay" in r or "mismatch" in r for r in result["reasons"]) + + +def test_journal_replay_cross_claimant_refused(dirty_repo, lock_dir): + """Replaying a journal from another claimant is refused.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + jpath = rebind.journal_path(lock_dir, ISSUE) + rebind._atomic_write_json( + jpath, + _complete_journal( + phase=rebind.JOURNAL_PHASE_ASSESSED, + old_pid=old, + claimant_identity="other-user", + claimant_profile="other-profile", + ), + ) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert not result["success"] + assert any("claimant" in r for r in result["reasons"]) + + +def test_successful_exact_retry_with_complete_identity(dirty_repo, lock_dir): + """Exact retry after success is already_rebound with complete matching identity.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + r1 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert r1["success"], r1 + # Journal must persist the five identity fields. + jpath = rebind.journal_path(lock_dir, ISSUE) + journal = rebind._read_json(jpath) + assert journal is not None + assert journal["phase"] == rebind.JOURNAL_PHASE_COMPLETE + for field in rebind.REQUIRED_JOURNAL_IDENTITY_FIELDS: + assert journal.get(field), field + assert journal["remote"] == REMOTE + assert journal["org"] == ORG + assert journal["repo"] == REPO + assert journal["claimant_identity"] == IDENTITY + assert journal["claimant_profile"] == PROFILE + + rebound = ils.read_lock_file(r1["lock_path"]) + r2 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + rebound, + lock_dir, + old_pid=old, + existing_lock=rebound, + ) + ) + assert r2["success"], r2 + assert r2["already_rebound"] is True + + +def test_already_rebound_requires_complete_matching_identity(dirty_repo, lock_dir): + """already_rebound with mismatched journal identity fails closed.""" + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + r1 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs(dirty_repo, lock, lock_dir, old_pid=old) + ) + assert r1["success"], r1 + # Corrupt journal identity after success. + jpath = rebind.journal_path(lock_dir, ISSUE) + journal = rebind._read_json(jpath) + assert journal is not None + journal["claimant_identity"] = "not-the-owner" + rebind._atomic_write_json(jpath, journal) + + rebound = ils.read_lock_file(r1["lock_path"]) + r2 = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + rebound, + lock_dir, + old_pid=old, + existing_lock=rebound, + ) + ) + # Same pid on lock would look like already_rebound, but identity must match. + assert not r2["success"] + assert any("claimant_identity" in r or "mismatch" in r for r in r2["reasons"]) + + +def test_ordinary_dirty_worktree_refusal_preserved(dirty_repo): + """#868 must not weaken ordinary dirty-worktree refusal on lock_issue path.""" + porcelain = dirty_repo["inventory"]["porcelain_status"] + assessment = issue_lock_worktree.assess_issue_lock_worktree( + worktree_path=dirty_repo["worktree"], + current_branch=BRANCH, + porcelain_status=porcelain, + base_equivalent=False, + ) + assert assessment["block"] is True + + +# ── #868 — Reconciler success path ────────────────────────────────────────── + + +def test_reconciler_success_path_tightly_pinned(dirty_repo, lock_dir): + """Reconciler with authorize_reconciler_execute=True may execute rebind. + + Reconciler execution grants no commit/push/publication/review/merge + capability — only the tightly pinned session rebind. + """ + old = dead_pid() + lock = _make_lock(worktree=dirty_repo["worktree"], pid=old, lock_dir=lock_dir) + result = rebind.apply_dirty_same_claimant_session_rebind( + **_apply_kwargs( + dirty_repo, + lock, + lock_dir, + old_pid=old, + role_kind="reconciler", + authorize_reconciler_execute=True, + # Reconciler may act for the recorded claimant without being that + # identity in the active session (still pin-checked against lock). + current_identity="sysadmin", + current_profile="prgs-reconciler", + ) + ) + assert result["success"], result + assert result["outcome"] == rebind.REBIND_SANCTIONED + rebound = ils.read_lock_file(result["lock_path"]) + assert int(rebound["session_pid"]) == os.getpid() + # Provenance records the rebind tool; no publication authority is granted. + assert ( + rebound.get("lock_provenance", {}).get("source") + == issue_lock_provenance.SOURCE_DIRTY_SAME_CLAIMANT_REBIND + ) + # Reconciler rebind does not stamp commit/push/review/merge capabilities. + prov = rebound.get("lock_provenance") or {} + blob = json.dumps(prov) + for forbidden in ( + "gitea.repo.commit", + "gitea.branch.push", + "gitea.pr.approve", + "gitea.pr.merge", + "gitea.pr.create", + ): + assert forbidden not in blob + + +def test_revalidate_complete_dirty_inventory_helper(dirty_repo): + ok = rebind.revalidate_complete_dirty_inventory( + dirty_repo["worktree"], + expected_dirty_paths=dirty_repo["dirty_paths"], + expected_fingerprints=dirty_repo["fingerprints"], + phase="unit", + ) + assert ok["ok"] is True + + bad = rebind.revalidate_complete_dirty_inventory( + dirty_repo["worktree"], + expected_dirty_paths=dirty_repo["dirty_paths"][:-1], + expected_fingerprints={ + p: dirty_repo["fingerprints"][p] for p in dirty_repo["dirty_paths"][:-1] + }, + phase="unit", + ) + assert bad["ok"] is False + assert any("unexpected paths" in r for r in bad["reasons"]) + + +def test_validate_journal_operation_identity_helper(): + complete = _complete_journal() + assert ( + rebind.validate_journal_operation_identity( + complete, + remote=REMOTE, + org=ORG, + repo=REPO, + claimant_identity=IDENTITY, + claimant_profile=PROFILE, + ) + == [] + ) + incomplete = {"phase": "assessed", "remote": REMOTE} + reasons = rebind.validate_journal_operation_identity( + incomplete, + remote=REMOTE, + org=ORG, + repo=REPO, + claimant_identity=IDENTITY, + claimant_profile=PROFILE, + ) + assert any("omits operation identity" in r for r in reasons) + assert any("org" in r for r in reasons) diff --git a/tests/test_issue_843_cross_role_handoff.py b/tests/test_issue_843_cross_role_handoff.py new file mode 100644 index 0000000..4fe0028 --- /dev/null +++ b/tests/test_issue_843_cross_role_handoff.py @@ -0,0 +1,682 @@ +"""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() diff --git a/tests/test_issue_858_audit_merged_pr_aware.py b/tests/test_issue_858_audit_merged_pr_aware.py new file mode 100644 index 0000000..3232318 --- /dev/null +++ b/tests/test_issue_858_audit_merged_pr_aware.py @@ -0,0 +1,551 @@ +"""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", "test@example.invalid") + 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() diff --git a/tests/test_issue_871_durable_lock_head_refresh.py b/tests/test_issue_871_durable_lock_head_refresh.py new file mode 100644 index 0000000..37851b1 --- /dev/null +++ b/tests/test_issue_871_durable_lock_head_refresh.py @@ -0,0 +1,630 @@ +"""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", "t@example.com") + _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", "t@example.com") + _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() diff --git a/tests/test_mcp_restart_governance_docs.py b/tests/test_mcp_restart_governance_docs.py new file mode 100644 index 0000000..5b12e50 --- /dev/null +++ b/tests/test_mcp_restart_governance_docs.py @@ -0,0 +1,107 @@ +"""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}" diff --git a/tests/test_merged_cleanup_reconcile.py b/tests/test_merged_cleanup_reconcile.py index 284ad37..e9a8709 100644 --- a/tests/test_merged_cleanup_reconcile.py +++ b/tests/test_merged_cleanup_reconcile.py @@ -12,6 +12,59 @@ 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)", diff --git a/tests/test_webui_console_authz_audit.py b/tests/test_webui_console_authz_audit.py new file mode 100644 index 0000000..5996f7c --- /dev/null +++ b/tests/test_webui_console_authz_audit.py @@ -0,0 +1,703 @@ +"""Console authorization, redaction, and audit model tests (#633). + +Covers each acceptance criterion and each required test named in the issue: + +* AC1 — RBAC matrix and privileged-action list. +* AC2 — redaction rules, unit-tested against sample payloads. +* AC3 — audit event schema with required fields and retention defaults. +* AC4 — Phase 2 integration points. +* AC5 — local-dev mode with explicit insecurity warnings. + +Required tests: redaction units (token, keychain, password patterns), +default-deny for unauthenticated write stubs, and audit record creation for a +simulated privileged preview. +""" + +from __future__ import annotations + +import datetime +import json +import os +import pathlib +import sys +import tempfile +import unittest + +from starlette.testclient import TestClient + +sys.path.insert(0, str(pathlib.Path(__file__).resolve().parents[1])) + +from task_capability_map import TASK_CAPABILITY_MAP # noqa: E402 +from webui import console_audit, console_authz # noqa: E402 +from webui.app import create_app # noqa: E402 +from webui.console_redaction import ( # noqa: E402 + REDACTED, + redact_payload, + redact_text, + redaction_policy, + scan_for_secrets, +) + +DOCS = pathlib.Path(__file__).resolve().parents[1] / "docs" +AUTHZ_DOC = DOCS / "webui-authz-audit.md" + + +def _principal(role: str) -> console_authz.Principal: + return console_authz.Principal( + subject=f"{role}@example.com", + role=role, + identity_source=console_authz.IDENTITY_ACCESS_PROXY, + authenticated=True, + ) + + +class TestRoleMatrix(unittest.TestCase): + """AC1 — the written RBAC matrix and privileged-action list.""" + + def test_roles_are_ordered_least_to_most_authority(self): + self.assertEqual( + console_authz.ROLE_ORDER, + ("viewer", "operator", "controller", "admin"), + ) + + def test_every_role_has_a_description(self): + for role in console_authz.ROLE_ORDER: + with self.subTest(role=role): + self.assertTrue(console_authz.ROLE_DESCRIPTIONS[role].strip()) + + def test_higher_roles_inherit_lower_role_actions(self): + matrix = { + entry["role"]: set(entry["permitted_actions"]) + for entry in console_authz.rbac_matrix()["roles"] + } + for lower, higher in zip( + console_authz.ROLE_ORDER, console_authz.ROLE_ORDER[1:] + ): + with self.subTest(lower=lower, higher=higher): + self.assertTrue(matrix[lower].issubset(matrix[higher])) + + def test_viewer_holds_no_write_action(self): + matrix = { + entry["role"]: set(entry["permitted_actions"]) + for entry in console_authz.rbac_matrix()["roles"] + } + self.assertEqual(matrix["viewer"], set()) + + def test_privileged_action_list_is_non_empty_and_classified(self): + privileged = console_authz.privileged_actions() + self.assertTrue(privileged) + ids = {action.action_id for action in privileged} + # Merge and branch deletion are the canonical privileged pair. + self.assertIn("merge_pr", ids) + self.assertIn("delete_branch", ids) + + def test_merge_and_delete_require_dual_control_and_break_glass(self): + for action_id in ("merge_pr", "delete_branch"): + with self.subTest(action=action_id): + action = console_authz.get_action(action_id) + self.assertTrue(action.dual_control) + self.assertTrue(action.break_glass) + self.assertTrue(action.requires_confirmation) + + def test_every_write_action_requires_confirmation(self): + for action in console_authz.ACTIONS.values(): + with self.subTest(action=action.action_id): + self.assertTrue(action.requires_confirmation) + + def test_delete_branch_is_admin_only(self): + self.assertEqual( + console_authz.get_action("delete_branch").minimum_role, + console_authz.ADMIN, + ) + + def test_actions_map_to_real_mcp_capability_vocabulary(self): + """The console must not invent an authority the MCP layer lacks.""" + for action in console_authz.ACTIONS.values(): + with self.subTest(action=action.action_id): + self.assertIn(action.task_key, TASK_CAPABILITY_MAP) + self.assertEqual( + action.mcp_permission, + TASK_CAPABILITY_MAP[action.task_key]["permission"], + ) + self.assertEqual( + action.mcp_role, + TASK_CAPABILITY_MAP[action.task_key]["role"], + ) + + def test_matrix_declares_deny_by_default_and_execution_disabled(self): + matrix = console_authz.rbac_matrix() + self.assertEqual(matrix["default_decision"], "deny") + self.assertFalse(matrix["execution_enabled"]) + + +class TestAuthorizeDefaultDeny(unittest.TestCase): + """Fail-closed behaviour of the authorization decision.""" + + def test_anonymous_is_denied_every_action(self): + for action_id in console_authz.ACTIONS: + with self.subTest(action=action_id): + decision = console_authz.authorize(action_id) + self.assertFalse(decision.allowed) + self.assertEqual( + decision.reason_code, console_authz.DENY_UNAUTHENTICATED + ) + + def test_unknown_action_is_denied(self): + decision = console_authz.authorize( + "not_a_real_action", _principal("admin") + ) + self.assertFalse(decision.allowed) + self.assertEqual(decision.reason_code, console_authz.DENY_UNKNOWN_ACTION) + + def test_unknown_role_is_denied(self): + rogue = console_authz.Principal( + subject="x@example.com", + role="superuser", + identity_source=console_authz.IDENTITY_ACCESS_PROXY, + authenticated=True, + ) + decision = console_authz.authorize("comment_issue", rogue) + self.assertFalse(decision.allowed) + self.assertEqual(decision.reason_code, console_authz.DENY_UNKNOWN_ROLE) + + def test_insufficient_role_is_denied(self): + decision = console_authz.authorize("merge_pr", _principal("operator")) + self.assertFalse(decision.allowed) + self.assertEqual( + decision.reason_code, console_authz.DENY_INSUFFICIENT_ROLE + ) + + def test_sufficient_role_allows_preview_only(self): + decision = console_authz.authorize("merge_pr", _principal("controller")) + self.assertTrue(decision.allowed) + self.assertFalse(decision.execution_enabled) + + def test_execution_is_refused_while_phase_is_not_active(self): + decision = console_authz.authorize( + "merge_pr", _principal("controller"), for_execution=True + ) + self.assertFalse(decision.allowed) + self.assertEqual( + decision.reason_code, console_authz.DENY_PHASE_NOT_ACTIVE + ) + + def test_allowed_decision_never_reports_execution_enabled(self): + for action_id in console_authz.ACTIONS: + with self.subTest(action=action_id): + decision = console_authz.authorize( + action_id, _principal("admin") + ) + self.assertFalse(decision.execution_enabled) + + +class TestIdentityResolution(unittest.TestCase): + """AC5 — identity sources, including the insecure local-dev mode.""" + + def test_no_auth_mode_yields_anonymous_viewer(self): + principal = console_authz.resolve_principal(env={}) + self.assertFalse(principal.authenticated) + self.assertEqual(principal.role, console_authz.VIEWER) + self.assertEqual(principal.identity_source, console_authz.IDENTITY_NONE) + + def test_local_dev_mode_warns_that_identity_is_unverified(self): + principal = console_authz.resolve_principal( + env={ + console_authz.AUTH_MODE_ENV: "local-dev", + console_authz.DEV_SUBJECT_ENV: "dev@example.com", + console_authz.DEV_ROLE_ENV: "admin", + } + ) + self.assertTrue(principal.authenticated) + self.assertEqual(principal.role, "admin") + self.assertTrue(principal.warnings) + self.assertIn("asserted", " ".join(principal.warnings).lower()) + + def test_local_dev_without_subject_falls_back_to_anonymous(self): + principal = console_authz.resolve_principal( + env={console_authz.AUTH_MODE_ENV: "local-dev"} + ) + self.assertFalse(principal.authenticated) + + def test_local_dev_unknown_role_degrades_to_viewer(self): + principal = console_authz.resolve_principal( + env={ + console_authz.AUTH_MODE_ENV: "local_dev", + console_authz.DEV_SUBJECT_ENV: "dev@example.com", + console_authz.DEV_ROLE_ENV: "root", + } + ) + self.assertEqual(principal.role, console_authz.VIEWER) + + def test_access_proxy_without_header_fails_closed(self): + """A proxy-mode request that did not traverse the proxy is anonymous.""" + principal = console_authz.resolve_principal( + headers={}, + env={console_authz.AUTH_MODE_ENV: "access_proxy"}, + ) + self.assertFalse(principal.authenticated) + + def test_access_proxy_role_comes_from_server_config_not_client(self): + env = { + console_authz.AUTH_MODE_ENV: "access_proxy", + console_authz.ROLE_MAP_ENV: json.dumps( + {"ops@example.com": "controller"} + ), + } + principal = console_authz.resolve_principal( + headers={ + console_authz.ACCESS_SUBJECT_HEADER: "ops@example.com", + "x-role": "admin", # client-supplied role must be ignored + }, + env=env, + ) + self.assertEqual(principal.role, "controller") + + def test_access_proxy_unmapped_subject_defaults_to_viewer(self): + principal = console_authz.resolve_principal( + headers={ + console_authz.ACCESS_SUBJECT_HEADER: "stranger@example.com" + }, + env={console_authz.AUTH_MODE_ENV: "access_proxy"}, + ) + self.assertEqual(principal.role, console_authz.VIEWER) + + def test_malformed_role_map_does_not_raise_and_denies(self): + principal = console_authz.resolve_principal( + headers={console_authz.ACCESS_SUBJECT_HEADER: "ops@example.com"}, + env={ + console_authz.AUTH_MODE_ENV: "access_proxy", + console_authz.ROLE_MAP_ENV: "{not json", + }, + ) + self.assertEqual(principal.role, console_authz.VIEWER) + + def test_probe_auth_is_opt_in(self): + self.assertFalse(console_authz.probe_auth_required(env={})) + self.assertTrue( + console_authz.probe_auth_required( + env={console_authz.REQUIRE_PROBE_AUTH_ENV: "1"} + ) + ) + + def test_probe_auth_is_declared_but_not_yet_enforced(self): + """Phase 1 declares the probe-auth policy; no route enforces it yet. + + The flag exists so the Phase 2 action framework has a declared policy + to honour instead of inventing a second one. Pinning the current + not-enforced status here means wiring it later is a deliberate change + that updates this test and the documentation together, rather than a + silent behaviour shift. The documentation must say so plainly, because + an operator who sets the variable believing it protects a probe is + worse off than one who knows it does not. + """ + import inspect + + from webui import app as webui_app + + source = inspect.getsource(webui_app) + self.assertNotIn( + "probe_auth_required", + source, + msg=( + "webui.app now consults probe_auth_required, so probe auth is " + "no longer merely declared. Update the 'Probe authentication' " + "section of docs/webui-authz-audit.md, which states it " + "enforces nothing, and replace this test with real " + "enforcement coverage." + ), + ) + self.assertIn( + "enforces nothing today", + AUTHZ_DOC.read_text(encoding="utf-8"), + ) + + +class TestRedaction(unittest.TestCase): + """AC2 — required redaction units: token, keychain, password patterns.""" + + def test_token_assignment_is_redacted(self): + out = redact_text("GITEA_TOKEN=abcd1234efgh5678ijkl") + self.assertIn(REDACTED, out) + self.assertNotIn("abcd1234efgh5678ijkl", out) + + def test_password_assignment_is_redacted(self): + out = redact_text("password: hunter2supersecret") + self.assertIn(REDACTED, out) + self.assertNotIn("hunter2supersecret", out) + + def test_keychain_reference_is_redacted(self): + out = redact_text("keychain:gitea-prgs-token") + self.assertIn(REDACTED, out) + self.assertNotIn("gitea-prgs-token", out) + + def test_keychain_command_is_redacted(self): + out = redact_text("security find-generic-password -s gitea -w") + self.assertIn(REDACTED, out) + self.assertNotIn("find-generic-password -s gitea", out) + + def test_bearer_credential_is_redacted(self): + out = redact_text("Authorization: Bearer abcdef1234567890abcdef") + self.assertNotIn("abcdef1234567890abcdef", out) + + def test_jwt_is_redacted(self): + token = "eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxIn0.abcdefghijklmnop" + out = redact_text(f"session={token}") + self.assertNotIn(token, out) + + def test_private_key_block_is_redacted(self): + pem = ( + "-----BEGIN RSA PRIVATE KEY-----\n" + "MIIEowIBAAKCAQEAsecretmaterial\n" + "-----END RSA PRIVATE KEY-----" + ) + out = redact_text(pem) + self.assertNotIn("MIIEowIBAAKCAQEAsecretmaterial", out) + + def test_api_key_assignment_is_redacted(self): + out = redact_text('api_key = "sk-live-9f8e7d6c5b4a3210"') + self.assertNotIn("sk-live-9f8e7d6c5b4a3210", out) + + def test_nested_payload_is_redacted_recursively(self): + payload = { + "token": "abc123456789", + "nested": {"note": "password=letmein12345"}, + "list": ["keychain:some-entry"], + "safe": "plain text", + } + out = redact_payload(payload) + self.assertEqual(out["token"], REDACTED) + self.assertNotIn("letmein12345", json.dumps(out)) + self.assertNotIn("some-entry", json.dumps(out)) + self.assertEqual(out["safe"], "plain text") + + def test_scan_reports_findings_before_and_none_after(self): + dirty = "password: hunter2supersecret" + self.assertTrue(scan_for_secrets(dirty)) + self.assertEqual(scan_for_secrets(redact_text(dirty)), []) + + def test_non_strings_pass_through_untouched(self): + self.assertEqual(redact_text(42), 42) + self.assertEqual( + redact_payload({"n": 1, "b": True}), {"n": 1, "b": True} + ) + + def test_policy_is_documented_and_declares_redact_before_persist(self): + policy = redaction_policy() + self.assertTrue(policy["redact_before_persist"]) + self.assertIn("audit_records", policy["applies_to"]) + self.assertTrue(policy["console_rules"]) + + def test_policy_statement_contains_no_secret_material(self): + self.assertEqual(scan_for_secrets(redaction_policy()), []) + + +class TestAuditSchema(unittest.TestCase): + """AC3 — audit event schema, required fields, and retention defaults.""" + + def _event(self, action_id="merge_pr", **kwargs): + return console_audit.build_event( + action_id=action_id, + result=console_audit.RESULT_DENIED, + decision=console_authz.authorize(action_id, _principal("operator")), + target={"kind": "pr", "ref": "#123"}, + request_id="req-test", + **kwargs, + ) + + def test_every_required_field_is_present(self): + event = self._event() + for field in console_audit.REQUIRED_FIELDS: + with self.subTest(field=field): + self.assertIn(field, event) + + def test_actor_carries_who_and_how_they_were_identified(self): + event = self._event() + for field in console_audit.REQUIRED_ACTOR_FIELDS: + with self.subTest(field=field): + self.assertIn(field, event["actor"]) + + def test_correlation_ids_are_present(self): + event = self._event() + for field in console_audit.REQUIRED_CORRELATION_FIELDS: + with self.subTest(field=field): + self.assertIn(field, event["correlation"]) + self.assertEqual(event["correlation"]["request_id"], "req-test") + self.assertEqual(event["correlation"]["mcp_task"], "merge_pr") + + def test_timestamp_is_timezone_aware_utc_iso8601(self): + now = datetime.datetime( + 2026, 7, 22, 10, 16, 42, tzinfo=datetime.timezone.utc + ) + event = self._event(now=now) + self.assertEqual(event["timestamp"], "2026-07-22T10:16:42+00:00") + parsed = datetime.datetime.fromisoformat(event["timestamp"]) + self.assertIsNotNone(parsed.tzinfo) + + def test_retention_defaults_by_class(self): + self.assertEqual( + console_audit.RETENTION_DAYS[console_audit.RETENTION_STANDARD], 90 + ) + self.assertEqual( + console_audit.RETENTION_DAYS[console_audit.RETENTION_PRIVILEGED], + 365, + ) + self.assertEqual( + console_audit.RETENTION_DAYS[console_audit.RETENTION_BREAK_GLASS], + 730, + ) + + def test_break_glass_action_retains_longest(self): + event = self._event("merge_pr") + self.assertEqual( + event["retention"]["class"], console_audit.RETENTION_BREAK_GLASS + ) + + def test_routine_write_uses_standard_retention(self): + event = self._event("comment_issue") + self.assertEqual( + event["retention"]["class"], console_audit.RETENTION_STANDARD + ) + + def test_unknown_action_retains_as_privileged_not_standard(self): + """Conservative direction: keep an unclassifiable record longer.""" + self.assertEqual( + console_audit.retention_class_for(None), + console_audit.RETENTION_PRIVILEGED, + ) + + def test_retention_expiry_matches_declared_days(self): + now = datetime.datetime(2026, 7, 22, tzinfo=datetime.timezone.utc) + event = self._event("comment_issue", now=now) + expires = datetime.datetime.fromisoformat( + event["retention"]["expires_at"] + ) + self.assertEqual((expires - now).days, 90) + + def test_invalid_result_degrades_to_failed(self): + event = console_audit.build_event(action_id="merge_pr", result="banana") + self.assertEqual(event["result"], console_audit.RESULT_FAILED) + + def test_denied_result_is_representable(self): + """An authorization denial has no MCP-side mutation record.""" + self.assertIn(console_audit.RESULT_DENIED, console_audit.RESULTS) + + def test_event_is_redacted_before_it_is_returned(self): + event = console_audit.build_event( + action_id="merge_pr", + result=console_audit.RESULT_DENIED, + detail="failed with token=abcdef1234567890", + metadata={"password": "hunter2supersecret"}, + ) + serialized = json.dumps(event) + self.assertNotIn("abcdef1234567890", serialized) + self.assertNotIn("hunter2supersecret", serialized) + self.assertTrue(event["redacted"]) + + def test_audit_policy_reports_schema_and_retention(self): + policy = console_audit.audit_policy() + self.assertTrue(policy["append_only"]) + self.assertTrue(policy["redact_before_persist"]) + self.assertEqual( + policy["retention_defaults_days"], console_audit.RETENTION_DAYS + ) + + +class TestAuditSink(unittest.TestCase): + """Append-only persistence behaviour.""" + + def test_write_is_a_noop_when_sink_is_unconfigured(self): + saved = os.environ.pop(console_audit.AUDIT_LOG_ENV, None) + try: + self.assertFalse(console_audit.audit_enabled()) + self.assertFalse(console_audit.write_event({"schema_version": 1})) + finally: + if saved is not None: + os.environ[console_audit.AUDIT_LOG_ENV] = saved + + def test_records_append_one_json_line_each(self): + with tempfile.TemporaryDirectory() as tmp: + sink = os.path.join(tmp, "console-audit.jsonl") + for _ in range(3): + event = console_audit.build_event( + action_id="merge_pr", result=console_audit.RESULT_DENIED + ) + self.assertTrue(console_audit.write_event(event, path=sink)) + with open(sink, encoding="utf-8") as handle: + lines = [json.loads(line) for line in handle if line.strip()] + self.assertEqual(len(lines), 3) + self.assertEqual(len({line["event_id"] for line in lines}), 3) + + def test_a_record_that_still_carries_a_secret_is_not_persisted(self): + with tempfile.TemporaryDirectory() as tmp: + sink = os.path.join(tmp, "console-audit.jsonl") + leaky = { + "schema_version": 1, + "detail": "password: hunter2supersecret", + } + self.assertFalse(console_audit.write_event(leaky, path=sink)) + self.assertFalse(os.path.exists(sink)) + + def test_write_never_raises_on_a_bad_path(self): + self.assertFalse( + console_audit.write_event( + {"schema_version": 1}, path="/nonexistent-dir/audit.jsonl" + ) + ) + + def test_simulated_privileged_preview_creates_an_audit_record(self): + """Required test: audit record creation for a privileged preview.""" + with tempfile.TemporaryDirectory() as tmp: + sink = os.path.join(tmp, "console-audit.jsonl") + os.environ[console_audit.AUDIT_LOG_ENV] = sink + try: + decision = console_authz.authorize( + "merge_pr", _principal("controller") + ) + outcome = console_audit.record_event( + action_id="merge_pr", + result=console_audit.RESULT_PREVIEWED, + decision=decision, + target={"kind": "pr", "ref": "#123"}, + request_id="req-preview", + ) + finally: + os.environ.pop(console_audit.AUDIT_LOG_ENV, None) + self.assertTrue(outcome["written"]) + with open(sink, encoding="utf-8") as handle: + record = json.loads(handle.read().strip()) + self.assertEqual(record["action"], "merge_pr") + self.assertEqual(record["result"], console_audit.RESULT_PREVIEWED) + self.assertEqual(record["action_class"], "privileged") + self.assertTrue(record["decision"]["allowed"]) + self.assertFalse(record["decision"]["execution_enabled"]) + self.assertEqual(record["actor"]["role"], "controller") + + def test_decision_block_survives_redaction(self): + """Regression: naming it 'authorization' collided with a secret hint. + + ``gitea_audit._SECRET_KEY_HINTS`` contains "authorization" (for the + HTTP header), so a block under that key was replaced wholesale by the + placeholder and the record lost its decision entirely. + """ + event = console_audit.build_event( + action_id="merge_pr", + result=console_audit.RESULT_DENIED, + decision=console_authz.authorize("merge_pr", _principal("admin")), + ) + self.assertIsInstance(event["decision"], dict) + self.assertIn("allowed", event["decision"]) + + +class TestConsoleRoutes(unittest.TestCase): + """AC4 — the wired Phase 2 integration points, still fail-closed.""" + + def setUp(self): + self.client = TestClient(create_app(bind_host="127.0.0.1")) + + def test_unauthenticated_write_stub_is_denied(self): + """Required test: default-deny for unauthenticated write stubs.""" + response = self.client.post( + "/api/actions/merge_pr/attempt", json={"pr_number": 99} + ) + self.assertEqual(response.status_code, 403) + body = response.json() + self.assertFalse(body["success"]) + authorization = body["authorization"] + self.assertFalse(authorization["allowed"]) + self.assertEqual( + authorization["reason_code"], console_authz.DENY_UNAUTHENTICATED + ) + self.assertFalse(authorization["execution_enabled"]) + + def test_preview_reports_an_authorization_decision(self): + response = self.client.get("/api/actions/merge_pr/preview?pr_number=7") + self.assertEqual(response.status_code, 200) + authorization = response.json()["authorization"] + self.assertFalse(authorization["allowed"]) + self.assertTrue(authorization["dual_control"]) + self.assertEqual(authorization["required_role"], "controller") + + def test_unknown_action_preview_still_404s(self): + response = self.client.get("/api/actions/no_such_action/preview") + self.assertEqual(response.status_code, 404) + + def test_security_model_endpoint_publishes_all_three_policies(self): + response = self.client.get("/api/console/security-model") + self.assertEqual(response.status_code, 200) + body = response.json() + self.assertIn("rbac", body) + self.assertIn("redaction", body) + self.assertIn("audit", body) + self.assertEqual(body["rbac"]["default_decision"], "deny") + + def test_security_model_endpoint_leaks_no_secrets(self): + response = self.client.get("/api/console/security-model") + self.assertEqual(scan_for_secrets(response.json()), []) + + def test_security_model_rejects_writes(self): + response = self.client.post("/api/console/security-model", json={}) + self.assertEqual(response.status_code, 405) + + def test_existing_read_routes_are_unaffected(self): + for path in ("/", "/health", "/actions", "/api/actions"): + with self.subTest(path=path): + self.assertEqual(self.client.get(path).status_code, 200) + + +class TestAuthzAuditDoc(unittest.TestCase): + """The model must be written down, not only coded.""" + + @classmethod + def setUpClass(cls): + cls.text = ( + AUTHZ_DOC.read_text(encoding="utf-8") if AUTHZ_DOC.exists() else "" + ) + + def test_doc_exists(self): + self.assertTrue(AUTHZ_DOC.exists(), f"missing {AUTHZ_DOC}") + + def test_doc_covers_each_required_section(self): + for heading in ( + "Identity sources", + "Role matrix", + "Privileged actions", + "Secret redaction", + "Audit event schema", + "Retention", + "Phase 2 integration", + "Local-dev mode", + ): + with self.subTest(heading=heading): + self.assertIn(heading, self.text) + + def test_doc_names_every_role(self): + for role in console_authz.ROLE_ORDER: + with self.subTest(role=role): + self.assertIn(role, self.text) + + def test_doc_names_every_console_action(self): + for action_id in console_authz.ACTIONS: + with self.subTest(action=action_id): + self.assertIn(action_id, self.text) + + def test_doc_states_retention_defaults(self): + for days in console_audit.RETENTION_DAYS.values(): + with self.subTest(days=days): + self.assertIn(str(days), self.text) + + def test_doc_warns_local_dev_is_insecure(self): + self.assertIn("INSECURE", self.text.upper()) + + def test_doc_states_default_deny(self): + self.assertIn("deny", self.text.lower()) + + def test_doc_contains_no_secret_material(self): + self.assertEqual(scan_for_secrets(self.text), []) + + def test_deployment_doc_links_to_the_model(self): + deployment = (DOCS / "webui-deployment.md").read_text(encoding="utf-8") + self.assertIn("webui-authz-audit", deployment) + + +if __name__ == "__main__": # pragma: no cover + unittest.main() diff --git a/tests/test_webui_shell.py b/tests/test_webui_shell.py new file mode 100644 index 0000000..e3c117f --- /dev/null +++ b/tests/test_webui_shell.py @@ -0,0 +1,135 @@ +"""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() diff --git a/tests/test_webui_system_health.py b/tests/test_webui_system_health.py new file mode 100644 index 0000000..69cd1dd --- /dev/null +++ b/tests/test_webui_system_health.py @@ -0,0 +1,499 @@ +"""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:secretpass@gitea.example.com/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:p@host.example.com/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:hunter2@gitea.example.com/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() diff --git a/tests/test_webui_timeline.py b/tests/test_webui_timeline.py new file mode 100644 index 0000000..39c7ea5 --- /dev/null +++ b/tests/test_webui_timeline.py @@ -0,0 +1,1021 @@ +"""Tests for the workflow-event timeline model and read API (#637). + +Covers the acceptance criteria: versioned schema, adaptation of control-plane +events and Gitea handoff comments, filter by issue/PR/session, redaction of +secret-like payloads, and stable pagination. +""" +import json +import os +import sqlite3 +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from starlette.testclient import TestClient + +import control_plane_db +from canonical_thread_handoff import ( + CTH_TYPES, + MARKER, + format_cth_body, + is_known_cth_type, + parse_cth_comment, +) +from webui import timeline +from webui.app import create_app + + +def _seed_db(path: str) -> None: + """Create a control-plane DB and seed scoped work_items + events.""" + # Constructing ControlPlaneDB runs the schema migration once. + control_plane_db.ControlPlaneDB(db_path=path) + conn = sqlite3.connect(path) + try: + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "issue", 637, "open", "2026-07-23T00:00:00Z"), + ) + issue_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "pr", 813, "open", "2026-07-23T00:00:00Z"), + ) + pr_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + # A work item for a different repo — must never appear in prgs/Gitea-Tools scope. + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("dadeschools", "Other", "Elsewhere", "issue", 1, "open", "2026-07-23T00:00:00Z"), + ) + other_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + + rows = [ + (issue_wid, "allocation", "assigned author work", "2026-07-23T01:00:00Z"), + (issue_wid, "lease.renew", "token=ghs_ABCDEF1234567890abcdef lease renewed", "2026-07-23T02:00:00Z"), + (pr_wid, "pr.opened", "PR opened for review", "2026-07-23T03:00:00Z"), + (other_wid, "allocation", "off-scope event", "2026-07-23T04:00:00Z"), + ] + conn.executemany( + "INSERT INTO events(work_item_id, event_type, message, created_at) VALUES (?,?,?,?)", + rows, + ) + conn.commit() + finally: + conn.close() + + +class TestSchema(unittest.TestCase): + def test_schema_is_versioned(self): + self.assertIsInstance(timeline.TIMELINE_SCHEMA_VERSION, int) + self.assertGreaterEqual(timeline.TIMELINE_SCHEMA_VERSION, 1) + + def test_event_to_dict_shape(self): + ev = timeline.WorkflowEvent( + source=timeline.SOURCE_CONTROL_PLANE, + event_type="allocation", + event_key="cp:1", + timestamp="2026-07-23T01:00:00Z", + issue_number=637, + ) + d = ev.to_dict() + for key in ( + "source", "event_type", "event_key", "timestamp", "actor", "role", + "issue_number", "pr_number", "session_id", "tool_name", "decision", + "message", "correlation_id", "evidence_refs", "sensitive", + ): + self.assertIn(key, d) + self.assertEqual(d["evidence_refs"], []) + + +class TestCpAdapter(unittest.TestCase): + def test_issue_and_pr_mapping(self): + rows = [ + {"event_id": 1, "event_type": "allocation", "message": "x", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 637}, + {"event_id": 2, "event_type": "pr.opened", "message": "y", "created_at": "2026-07-23T02:00:00Z", "kind": "pr", "number": 813}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 2) + self.assertEqual(events[0].issue_number, 637) + self.assertIsNone(events[0].pr_number) + self.assertEqual(events[0].correlation_id, "issue#637") + self.assertIsNone(events[1].issue_number) + self.assertEqual(events[1].pr_number, 813) + + def test_malformed_rows_skipped(self): + rows = [ + {"event_id": None, "event_type": "x", "kind": "issue", "number": 1}, + {"event_id": 5, "event_type": "", "kind": "issue", "number": 1}, + {"event_id": 6, "event_type": "ok", "message": "m", "created_at": None, "kind": "issue", "number": 1}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 1) + self.assertIsNone(events[0].timestamp) + + def test_sensitive_event_flagged(self): + rows = [{"event_id": 1, "event_type": "lease.renew", "message": "m", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}] + events = timeline.adapt_cp_events(rows) + self.assertTrue(events[0].sensitive) + + +class TestCthAdapter(unittest.TestCase): + def test_cth_comment_becomes_event(self): + body = format_cth_body( + cth_type="Author Handoff", + status="ready", + next_owner="reviewer", + decision="implement timeline", + proof="commit abc1234 closes #637", + next_action="review PR", + ready_to_paste_prompt="Review PR #900 as reviewer", + ) + comments = [{"id": 42, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "jcwalker3"}}] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + ev = events[0] + self.assertEqual(ev.source, timeline.SOURCE_GITEA_HANDOFF) + self.assertEqual(ev.event_type, "handoff:Author Handoff") + self.assertEqual(ev.actor, "jcwalker3") + self.assertEqual(ev.issue_number, 637) + self.assertEqual(ev.event_key, "cth:issue:637:42") + self.assertIn("#637", ev.evidence_refs) + self.assertIn("abc1234", ev.evidence_refs) + + def test_non_cth_comment_ignored(self): + comments = [{"id": 1, "body": "just a normal comment", "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}] + self.assertEqual(timeline.adapt_cth_comments(comments, kind="issue", number=1), []) + + +class TestRedaction(unittest.TestCase): + def test_cp_message_redacted(self): + rows = [{"event_id": 1, "event_type": "lease", "message": "token=ghs_ABCDEF1234567890abcdef here", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}] + events = timeline.adapt_cp_events(rows) + self.assertNotIn("ghs_ABCDEF1234567890abcdef", events[0].message or "") + + def test_handoff_decision_redacted(self): + body = format_cth_body( + cth_type="Blocker", + status="blocked", + next_owner="author", + decision="password=SuperSecret123! must rotate", + proof="none", + next_action="rotate", + ready_to_paste_prompt="Rotate the credential and retry", + ) + comments = [{"id": 7, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}] + events = timeline.adapt_cth_comments(comments, kind="issue", number=1) + self.assertNotIn("SuperSecret123!", events[0].decision or "") + + +class TestFilterSortPaginate(unittest.TestCase): + def _events(self): + return [ + timeline.WorkflowEvent(source="control_plane", event_type="a", event_key="cp:3", timestamp="2026-07-23T03:00:00Z", pr_number=813), + timeline.WorkflowEvent(source="control_plane", event_type="b", event_key="cp:1", timestamp="2026-07-23T01:00:00Z", issue_number=637), + timeline.WorkflowEvent(source="control_plane", event_type="c", event_key="cp:2", timestamp="2026-07-23T02:00:00Z", issue_number=637, session_id="sess-1"), + ] + + def test_filter_by_issue(self): + out = timeline.filter_events(self._events(), issue=637) + self.assertEqual({e.event_key for e in out}, {"cp:1", "cp:2"}) + + def test_filter_by_pr(self): + out = timeline.filter_events(self._events(), pr=813) + self.assertEqual([e.event_key for e in out], ["cp:3"]) + + def test_filter_by_session(self): + out = timeline.filter_events(self._events(), session="sess-1") + self.assertEqual([e.event_key for e in out], ["cp:2"]) + + def test_stable_sort_ascending(self): + out = timeline.sort_events(self._events()) + self.assertEqual([e.event_key for e in out], ["cp:1", "cp:2", "cp:3"]) + + def test_missing_timestamp_sorts_last(self): + evs = self._events() + [ + timeline.WorkflowEvent(source="control_plane", event_type="z", event_key="cp:9", timestamp=None) + ] + out = timeline.sort_events(evs) + self.assertEqual(out[-1].event_key, "cp:9") + + def test_pagination_windows_and_next_offset(self): + evs = timeline.sort_events(self._events()) + page1 = timeline.paginate(evs, limit=2, offset=0) + self.assertEqual(len(page1.events), 2) + self.assertEqual(page1.total, 3) + self.assertEqual(page1.next_offset, 2) + page2 = timeline.paginate(evs, limit=2, offset=2) + self.assertEqual(len(page2.events), 1) + self.assertIsNone(page2.next_offset) + + def test_pagination_bounds_coerced(self): + evs = self._events() + page = timeline.paginate(evs, limit=-5, offset=-3) + self.assertGreaterEqual(page.limit, 1) + self.assertEqual(page.offset, 0) + + +class TestCpReader(unittest.TestCase): + def test_reads_scoped_events_only(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + events, status = timeline.read_cp_events( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db + ) + self.assertTrue(status.ok) + # 3 scoped events; the dadeschools/Other event is excluded. + self.assertEqual(len(events), 3) + self.assertTrue(all(e.source == "control_plane" for e in events)) + # Redaction applied to the token-bearing message. + joined = " ".join(e.message or "" for e in events) + self.assertNotIn("ghs_ABCDEF1234567890abcdef", joined) + + def test_missing_db_degrades(self): + events, status = timeline.read_cp_events( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + db_path="/nonexistent/path/to/cp.sqlite3", + ) + self.assertEqual(events, []) + self.assertFalse(status.ok) + self.assertIsNotNone(status.reason) + + +class TestLoadTimeline(unittest.TestCase): + def test_handoff_not_run_without_thread_filter(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertFalse(handoff["ok"]) + self.assertIn("thread-scoped", handoff["reason"]) + self.assertEqual(d["schema_version"], timeline.TIMELINE_SCHEMA_VERSION) + + def test_handoff_included_via_injected_source(self): + import tempfile + + body = format_cth_body( + cth_type="Author Handoff", status="ready", next_owner="reviewer", + decision="d", proof="#637", next_action="review", ready_to_paste_prompt="Review PR #1 now", + ) + + def source(kind, number): + return [{"id": 1, "body": body, "created_at": "2026-07-23T09:00:00Z", "user": {"login": "jcwalker3"}}] + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=source, + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertTrue(handoff["ok"]) + self.assertEqual(handoff["count"], 1) + # Both a CP event and the handoff event for issue 637 appear, sorted. + kinds = {e["source"] for e in d["events"]} + self.assertEqual(kinds, {"control_plane", "gitea_handoff"}) + + def test_failing_comment_source_degrades_only_handoff(self): + import tempfile + + def boom(kind, number): + raise RuntimeError("network down") + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=boom, + ) + d = snap.to_dict() + cp = [s for s in d["sources"] if s["name"] == "control_plane"][0] + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertTrue(cp["ok"]) + self.assertFalse(handoff["ok"]) + self.assertIn("network down", handoff["reason"]) + + +# A fabricated 40-character lowercase hex value with the shape of a Gitea +# personal access token. Never a real credential — its only job is to prove it +# cannot reach any part of a serialized timeline payload. +SYNTHETIC_SECRET_40_HEX = "a3f9c17be44d2058e6b17c9d0f5321ab77c4e9d1" + + +def _cth_comment(comment_id, *, created_at, session=None, decision="d", proof="none", **kw): + """Build one real CTH comment record, optionally declaring a session.""" + extra = {"Session": session} if session is not None else None + body = format_cth_body( + cth_type=kw.pop("cth_type", "Author Handoff"), + status=kw.pop("status", "ready"), + next_owner=kw.pop("next_owner", "reviewer"), + decision=decision, + proof=proof, + next_action=kw.pop("next_action", "review"), + ready_to_paste_prompt=kw.pop("ready_to_paste_prompt", "Review PR #1 now"), + extra_fields=extra, + ) + return { + "id": comment_id, + "body": body, + "created_at": created_at, + "user": {"login": kw.pop("login", "jcwalker3")}, + } + + +class TestSessionFilterThroughAdapter(unittest.TestCase): + """F1: the session dimension must be real, or explicitly refused. + + These drive the filter through the CTH adapter and the composed + ``load_timeline``/API path, never through a hand-built ``WorkflowEvent``. + """ + + def _source(self, comments): + return lambda kind, number: list(comments) + + def test_adapter_populates_declared_session(self): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", session="sess-alpha")], + kind="issue", + number=637, + ) + self.assertEqual(len(events), 1) + self.assertEqual(events[0].session_id, "sess-alpha") + + def test_session_filter_matches_through_adapter(self): + import tempfile + + comments = [ + _cth_comment(1, created_at="2026-07-23T09:00:00Z", session="sess-alpha"), + _cth_comment(2, created_at="2026-07-23T08:00:00Z", session="sess-alpha"), + _cth_comment(3, created_at="2026-07-23T10:00:00Z", session="sess-beta"), + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source(comments), + ) + d = snap.to_dict() + self.assertTrue(d["ok"]) + self.assertIsNone(d["error"]) + keys = [e["event_key"] for e in d["events"]] + # Only the two sess-alpha events, still in ascending timestamp order. + self.assertEqual(keys, ["cth:issue:637:2", "cth:issue:637:1"]) + self.assertTrue(all(e["session_id"] == "sess-alpha" for e in d["events"])) + self.assertEqual(d["pagination"]["total"], 2) + + def test_session_filter_paginates_and_keeps_order(self): + import tempfile + + comments = [ + _cth_comment(i, created_at=f"2026-07-23T0{i}:00:00Z", session="sess-alpha") + for i in range(1, 4) + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + kwargs = dict( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source(comments), + ) + page1 = timeline.load_timeline(limit=2, offset=0, **kwargs).to_dict() + page2 = timeline.load_timeline(limit=2, offset=2, **kwargs).to_dict() + self.assertEqual( + [e["event_key"] for e in page1["events"]], + ["cth:issue:637:1", "cth:issue:637:2"], + ) + self.assertEqual(page1["pagination"]["next_offset"], 2) + self.assertEqual([e["event_key"] for e in page2["events"]], ["cth:issue:637:3"]) + self.assertIsNone(page2["pagination"]["next_offset"]) + + def test_unknown_session_is_honestly_empty_when_supported(self): + """A source that *can* answer the dimension may legitimately match nothing.""" + import tempfile + + comments = [_cth_comment(1, created_at="2026-07-23T09:00:00Z", session="sess-alpha")] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-nope", db_path=db, + comment_source=self._source(comments), + ).to_dict() + self.assertTrue(d["ok"]) + self.assertEqual(d["events"], []) + + def test_session_filter_refused_when_no_source_can_answer(self): + """The F1 defect: an empty-and-healthy page for an unanswerable filter.""" + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, comment_source=None, + ).to_dict() + self.assertFalse(d["ok"]) + self.assertEqual(d["error"]["code"], "filter_not_supported") + self.assertEqual(d["error"]["unsupported_filters"], ["session"]) + self.assertEqual(d["events"], []) + self.assertEqual(d["pagination"]["total"], 0) + # The refusal states which source could not answer, and why. + explained = {r["source"] for r in d["error"]["sources"]} + self.assertEqual(explained, {"control_plane", "gitea_handoff"}) + + def test_control_plane_declares_session_unsupported(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source([]), + ).to_dict() + cp = [s for s in d["sources"] if s["name"] == "control_plane"][0] + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertNotIn("session", cp["supported_filters"]) + self.assertEqual(cp["unsupported_filters"], ["session"]) + self.assertIn("session", handoff["supported_filters"]) + self.assertEqual(handoff["unsupported_filters"], []) + + def test_secret_shaped_session_value_is_dropped(self): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", session=SYNTHETIC_SECRET_40_HEX)], + kind="issue", + number=637, + ) + self.assertIsNone(events[0].session_id) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(events[0].to_dict())) + + +class TestEvidenceRefRedaction(unittest.TestCase): + """F2: evidence_refs must not be a hole in the redaction boundary.""" + + def _refs_for(self, *, proof="none", decision="d"): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", proof=proof, decision=decision)], + kind="issue", + number=637, + ) + self.assertEqual(len(events), 1) + return events[0] + + def test_assigned_secret_never_reaches_evidence_refs(self): + ev = self._refs_for(proof=f"authenticated with token={SYNTHETIC_SECRET_40_HEX}") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.evidence_refs) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_bare_secret_shaped_value_never_reaches_evidence_refs(self): + # An undeclared hex run in proof text is not evidence of anything, and + # proof itself is never serialized — so the value has no way out. + ev = self._refs_for(proof=f"proof {SYNTHETIC_SECRET_40_HEX}", decision="rotate the credential") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.evidence_refs) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_secret_absent_from_complete_serialized_payload(self): + import tempfile + + comments = [ + _cth_comment( + 1, + created_at="2026-07-23T09:00:00Z", + proof=f"lease token={SYNTHETIC_SECRET_40_HEX} and bare {SYNTHETIC_SECRET_40_HEX}", + decision=f"rotate api_key={SYNTHETIC_SECRET_40_HEX}", + ) + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + payload = json.dumps(snap.to_dict()) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, payload) + # And the surface is clean by the redaction policy's own detectors. + from webui import console_redaction + + self.assertEqual(console_redaction.scan_for_secrets(snap.to_dict()), []) + + def test_legitimate_references_still_usable(self): + head = "4f3a464a1c455b6ecaaae9b6eef496c8f8ed451a" + ev = self._refs_for( + proof=f"closes #637, PR #849, commit abc1234, at head {head}", + decision="none", + ) + for token in ("#637", "#849", "abc1234", head): + self.assertIn(token, ev.evidence_refs) + + def test_undeclared_hex_words_are_not_references(self): + ev = self._refs_for(proof="the record was defaced and the facade decayed") + self.assertEqual(ev.evidence_refs, ()) + + def test_refs_revalidated_independently_before_serialization(self): + """Extraction is not trusted: the validator drops anything unproven.""" + safe, dropped = timeline._validated_evidence_refs( + ["#637", "abc1234", "not-a-ref", f"token={SYNTHETIC_SECRET_40_HEX}", ""] + ) + self.assertEqual(safe, ("#637", "abc1234")) + self.assertTrue(dropped) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(list(safe))) + + def test_clean_event_is_not_marked_sensitive(self): + ev = self._refs_for(proof="closes #637") + self.assertEqual(ev.evidence_refs, ("#637",)) + self.assertFalse(ev.sensitive) + + +class TestTimelineApi(unittest.TestCase): + def setUp(self): + self._prev_db = os.environ.get(control_plane_db.DB_PATH_ENV) + self._prev_offline = os.environ.get("WEBUI_TEST_OFFLINE") + import tempfile + + self._tmpdir = tempfile.TemporaryDirectory() + self._db = os.path.join(self._tmpdir.name, "cp.sqlite3") + _seed_db(self._db) + os.environ[control_plane_db.DB_PATH_ENV] = self._db + os.environ["WEBUI_TEST_OFFLINE"] = "1" + self.client = TestClient(create_app()) + + def tearDown(self): + if self._prev_db is None: + os.environ.pop(control_plane_db.DB_PATH_ENV, None) + else: + os.environ[control_plane_db.DB_PATH_ENV] = self._prev_db + if self._prev_offline is None: + os.environ.pop("WEBUI_TEST_OFFLINE", None) + else: + os.environ["WEBUI_TEST_OFFLINE"] = self._prev_offline + self._tmpdir.cleanup() + + def test_api_returns_timeline(self): + resp = self.client.get("/api/v1/timeline") + self.assertEqual(resp.status_code, 200) + body = resp.json() + self.assertEqual(body["schema_version"], timeline.TIMELINE_SCHEMA_VERSION) + self.assertIn("events", body) + self.assertIn("pagination", body) + self.assertGreaterEqual(body["pagination"]["total"], 1) + + def test_api_filter_by_issue(self): + resp = self.client.get("/api/v1/timeline?issue=637") + self.assertEqual(resp.status_code, 200) + events = resp.json()["events"] + self.assertTrue(events) + self.assertTrue(all(e["issue_number"] == 637 for e in events)) + + def test_api_pagination(self): + resp = self.client.get("/api/v1/timeline?limit=1&offset=0") + self.assertEqual(resp.status_code, 200) + pg = resp.json()["pagination"] + self.assertEqual(pg["limit"], 1) + self.assertEqual(len(resp.json()["events"]), 1) + if pg["total"] > 1: + self.assertTrue(pg["has_more"]) + + def test_api_is_read_only(self): + resp = self.client.post("/api/v1/timeline") + self.assertIn(resp.status_code, (404, 405)) + + def test_api_no_secret_leak(self): + resp = self.client.get("/api/v1/timeline?issue=637") + self.assertNotIn("ghs_ABCDEF1234567890abcdef", resp.text) + + def test_api_refuses_unanswerable_session_filter(self): + """No handoff source is configured offline, so nothing can carry a session.""" + resp = self.client.get("/api/v1/timeline?issue=637&session=sess-alpha") + self.assertEqual(resp.status_code, 422) + body = resp.json() + self.assertFalse(body["ok"]) + self.assertEqual(body["error"]["code"], "filter_not_supported") + self.assertEqual(body["error"]["unsupported_filters"], ["session"]) + self.assertEqual(body["events"], []) + self.assertEqual(body["pagination"]["total"], 0) + + def test_api_unfiltered_read_stays_ok(self): + body = self.client.get("/api/v1/timeline?issue=637").json() + self.assertTrue(body["ok"]) + self.assertIsNone(body["error"]) + + +def _seed_event(path: str, *, event_type: str, message: str, created_at: str) -> None: + """Append one control-plane event with a caller-chosen ``event_type``. + + The ``events`` table stores whatever a producer writes, so this seeds the + adapter the way a hostile or buggy producer would. + """ + conn = sqlite3.connect(path) + try: + wid = conn.execute( + "SELECT work_item_id FROM work_items WHERE kind='issue' AND number=637" + ).fetchone()[0] + conn.execute( + "INSERT INTO events(work_item_id, event_type, message, created_at) VALUES (?,?,?,?)", + (wid, event_type, message, created_at), + ) + conn.commit() + finally: + conn.close() + + +def _raw_cth_body(heading: str, **fields) -> str: + """Build a CTH comment with an arbitrary heading. + + ``format_cth_body`` refuses an undeclared type, which is exactly the write + path already covered. The read path must cope with a body that never went + through it, so this writes the marker and heading directly. + """ + lines = [MARKER, f"## CTH: {heading}", ""] + base = { + "Status": "ready", + "Next owner": "reviewer", + "Current blocker": "none", + "Decision": "d", + "Proof": "none", + "Next action": "review", + "Ready-to-paste prompt": "Review PR #1 now", + } + base.update(fields) + lines.extend(f"{key}: {value}" for key, value in base.items()) + return "\n".join(lines) + + +class TestEventTypeBoundary(unittest.TestCase): + """F2 residual: event_type must cross the same boundary as every other field. + + The canary is seeded through ``event_type`` *only*, with a benign message, + so message redaction cannot be what makes these pass. Each case inspects + ``event_type`` explicitly and then the complete serialized payload. + """ + + # ---- control-plane stored event_type ---------------------------------- # + + def test_cp_event_type_canary_never_serialized(self): + rows = [{ + "event_id": 1, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": "deploy completed", # benign: no redaction happens here + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 1) + ev = events[0] + # The field itself, inspected directly. + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertEqual(ev.event_type, timeline.UNSAFE_EVENT_TYPE) + # Message redaction is provably not what saved us: it is untouched. + self.assertEqual(ev.message, "deploy completed") + # And nowhere in the serialized record. + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + # An unsafe value is a visible fact, not a silent substitution. + self.assertTrue(ev.sensitive) + + def test_cp_same_canary_in_message_and_event_type(self): + """The decisive case: one record, one value, two fields, one verdict.""" + rows = [{ + "event_id": 2, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": f"deploy token={SYNTHETIC_SECRET_40_HEX}", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.message or "") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cp_unsafe_event_type_is_not_rewritten_as_a_valid_one(self): + """A refused value must not be disguised as some other real event type.""" + rows = [{ + "event_id": 3, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + for legitimate in ("allocation", "pr.opened", "lease.renew", "assigned"): + self.assertNotEqual(ev.event_type, legitimate) + + def test_cp_assigned_secret_in_event_type_refused(self): + rows = [{ + "event_id": 4, + "event_type": f"token={SYNTHETIC_SECRET_40_HEX}", + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + self.assertEqual(ev.event_type, timeline.UNSAFE_EVENT_TYPE) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cp_legitimate_event_types_preserved(self): + """Every real producer type in this repo must survive untouched.""" + legitimate = [ + "allocation", "pr.opened", "lease.renew", "assigned", + "lease_released", "lease_expired", "lease_abandoned", + "lease_adopted", "dependency_edge_state_change", + ] + rows = [ + { + "event_id": i, + "event_type": name, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + } + for i, name in enumerate(legitimate, start=1) + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual([e.event_type for e in events], legitimate) + + def test_cp_malformed_event_type_shapes_refused(self): + for bad in ("has space", "1leading-digit", "x" * 200, "semi;colon", "new\nline"): + with self.subTest(event_type=bad): + rows = [{ + "event_id": 1, + "event_type": bad, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + events = timeline.adapt_cp_events(rows) + self.assertEqual(events[0].event_type, timeline.UNSAFE_EVENT_TYPE) + self.assertNotIn(bad, json.dumps(events[0].to_dict())) + + # ---- CTH heading event_type ------------------------------------------- # + + def test_cth_heading_canary_never_serialized(self): + comments = [{ + "id": 11, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "jcwalker3"}, + }] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + ev = events[0] + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertEqual(ev.event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + # No message redaction is doing the work here — the message is benign. + self.assertEqual(ev.message, "review") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + self.assertTrue(ev.sensitive) + + def test_cth_assigned_secret_heading_refused(self): + comments = [{ + "id": 12, + "body": _raw_cth_body(f"token={SYNTHETIC_SECRET_40_HEX}"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "jcwalker3"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cth_unknown_and_whitespace_headings_normalized(self): + for heading in ("Totally Made Up", "Author Handoff", "author handoff"): + with self.subTest(heading=heading): + comments = [{ + "id": 13, + "body": _raw_cth_body(heading), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + self.assertEqual(events[0].event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + + def test_cth_declared_types_all_preserved(self): + """Point 5: no legitimate declared type is lost to the new check.""" + for cth_type in sorted(CTH_TYPES): + with self.subTest(cth_type=cth_type): + comments = [{ + "id": 14, + "body": _raw_cth_body(cth_type), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, f"handoff:{cth_type}") + self.assertFalse(ev.sensitive) + + def test_cth_surrounding_whitespace_still_matches_contract(self): + comments = [{ + "id": 15, + "body": _raw_cth_body(" Author Handoff "), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, "handoff:Author Handoff") + + # ---- complete serialized payload, both paths -------------------------- # + + def _payload_clean(self, snapshot): + payload = json.dumps(snapshot.to_dict()) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, payload) + from webui import console_redaction + + self.assertEqual(console_redaction.scan_for_secrets(snapshot.to_dict()), []) + return snapshot.to_dict() + + def test_canary_absent_from_full_payload_via_cp_event_type(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + _seed_event( + db, + event_type=SYNTHETIC_SECRET_40_HEX, + message="routine deploy", + created_at="2026-07-23T06:00:00Z", + ) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: [], + ) + d = self._payload_clean(snap) + types = [e["event_type"] for e in d["events"]] + self.assertIn(timeline.UNSAFE_EVENT_TYPE, types) + # The legitimate seeded types are still present and unchanged. + self.assertIn("allocation", types) + + def test_canary_absent_from_full_payload_via_cth_heading(self): + import tempfile + + comments = [{ + "id": 21, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T09:00:00Z", + "user": {"login": "jcwalker3"}, + }] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + d = self._payload_clean(snap) + self.assertIn( + timeline.UNKNOWN_HANDOFF_EVENT_TYPE, + [e["event_type"] for e in d["events"]], + ) + + def test_canary_absent_when_seeded_through_both_paths_at_once(self): + import tempfile + + comments = [{ + "id": 22, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T09:00:00Z", + "user": {"login": "jcwalker3"}, + }] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + _seed_event( + db, + event_type=SYNTHETIC_SECRET_40_HEX, + message=f"deploy token={SYNTHETIC_SECRET_40_HEX}", + created_at="2026-07-23T06:00:00Z", + ) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + self._payload_clean(snap) + + +class TestSerializedFieldAudit(unittest.TestCase): + """The remaining externally influenced strings that reach the payload.""" + + def test_event_key_ids_must_be_plain_identifiers(self): + rows = [ + {"event_id": SYNTHETIC_SECRET_40_HEX, "event_type": "allocation", + "message": "m", "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", "number": 637}, + {"event_id": 8, "event_type": "allocation", "message": "m", + "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 637}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual([e.event_key for e in events], ["cp:8"]) + + def test_comment_id_must_be_a_plain_identifier(self): + comments = [{ + "id": SYNTHETIC_SECRET_40_HEX, + "body": _raw_cth_body("Author Handoff"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + self.assertEqual(timeline.adapt_cth_comments(comments, kind="issue", number=637), []) + + def test_adapter_refuses_a_scope_it_cannot_express(self): + comments = [{ + "id": 1, + "body": _raw_cth_body("Author Handoff"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + self.assertEqual( + timeline.adapt_cth_comments(comments, kind="issue", number=SYNTHETIC_SECRET_40_HEX), + [], + ) + self.assertEqual( + timeline.adapt_cth_comments(comments, kind=SYNTHETIC_SECRET_40_HEX, number=1), + [], + ) + + def test_source_failure_reason_is_redacted(self): + def boom(kind, number): + raise RuntimeError(f"auth failed with token={SYNTHETIC_SECRET_40_HEX}") + + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=boom, + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertFalse(handoff["ok"]) + self.assertIn("handoff source failed", handoff["reason"]) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(d)) + + def test_echoed_scope_and_filters_are_guarded(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session=SYNTHETIC_SECRET_40_HEX, db_path=db, + comment_source=lambda k, n: [], + ).to_dict() + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(d)) + # Ordinary scope values are untouched, so the echo stays useful. + self.assertEqual( + d["scope"], + {"remote": "prgs", "org": "Scaled-Tech-Consulting", "repo": "Gitea-Tools"}, + ) + self.assertEqual(d["filters"]["issue"], 637) + + +class TestCthTypeContract(unittest.TestCase): + """The contract has one authority; the read path consults it.""" + + def test_declared_types_are_known(self): + for cth_type in CTH_TYPES: + self.assertTrue(is_known_cth_type(cth_type)) + + def test_undeclared_types_are_not_known(self): + for value in ("", None, "Made Up", SYNTHETIC_SECRET_40_HEX, "author handoff"): + self.assertFalse(is_known_cth_type(value)) + + def test_parse_reports_contract_membership(self): + known = parse_cth_comment(_raw_cth_body("Author Handoff")) + self.assertTrue(known["cth_type_known"]) + self.assertEqual(known["cth_type"], "Author Handoff") + unknown = parse_cth_comment(_raw_cth_body("Not A Real Type")) + # Parsing stays total: the type is still reported, just not endorsed. + self.assertEqual(unknown["cth_type"], "Not A Real Type") + self.assertFalse(unknown["cth_type_known"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_worktree_cleanup_audit.py b/tests/test_worktree_cleanup_audit.py index f55b652..f3fc510 100644 --- a/tests/test_worktree_cleanup_audit.py +++ b/tests/test_worktree_cleanup_audit.py @@ -134,13 +134,35 @@ class TestClassification(unittest.TestCase): self.assertEqual(cls, wca.CLASS_ACTIVE_OPEN_PR) self.assertFalse(wca.is_removable(cls)) - def test_stale_clean_issue_worktree_removable(self): - # Scenario 5: clean issue worktree, TTL expired, no lock -> removable. + def test_stale_clean_issue_worktree_needs_merged_pr_proof(self): + # Scenario 5 (#858): age is not proof that the branch landed, so a + # 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)) diff --git a/webui/app.py b/webui/app.py index 0dc4a87..de3a5f8 100644 --- a/webui/app.py +++ b/webui/app.py @@ -2,6 +2,7 @@ from __future__ import annotations +import uuid from datetime import datetime, timezone from starlette.applications import Starlette @@ -11,6 +12,7 @@ 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, @@ -31,6 +33,9 @@ from final_report_validator import FINAL_REPORT_TASK_KINDS from webui.gated_actions import attempt_action, load_action_registry, preview_action from webui.gated_action_views import render_actions_page +from webui import console_audit +from webui.console_authz import authorize, rbac_matrix, resolve_principal +from webui.console_redaction import redaction_policy from webui.audit_validator import audit_report, audit_to_dict from webui.audit_views import render_audit_page from webui.lease_loader import load_lease_snapshot, snapshot_to_dict as lease_snapshot_to_dict @@ -46,6 +51,13 @@ from webui.inventory import ( load_inventory_snapshot, snapshot_to_dict as inventory_snapshot_to_dict, ) +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"}) @@ -60,35 +72,100 @@ 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'
  • {item.label}' + + ("" if item.status == "live" else " (stub)") + + "
    • " + for item in group.items + ) + groups.append(f"

    {group.label}

      {items}
    ") + return "".join(groups) + + async def home(_request: Request) -> HTMLResponse: + legacy = "".join( + f"
  • {label} — {desc} " + f'({href})
    • ' + for href, label, desc in _LEGACY_PAGES + ) body = ( "

    Operator console

    " - "

    Local entry point for MCP Control Plane operational views.

    " - "
      " - "
    • Queue — live PR and issue dashboard (#429)
      • " - "
    • Projects — registry and onboarding (#427)
      • " - "
    • Prompts — canonical workflow prompt library (#428)
      • " - "
    • Runtime — MCP health and stale-runtime detection (#430)
      • " - "
    • Audit — final-report paste and validator preview (#431)
      • " - "
    • Worktrees — branch hygiene dashboard (#432)
      • " - "
    • Leases — collision and lease visibility (#433)
      • " - "
    • Actions — gated write-action framework (#434)
      • " - "
    " + "

    Read-only home for the MCP Control Plane Phase 1 operator console. " + "Gitea, MCP capability gates, and canonical workflows remain the source " + "of truth; this console never mutates them.

    " + "

    Phase 1 surfaces

    " + + _render_home_nav_groups() + + "

    MVP legacy pages

    " + "
      " + legacy + "
    " ) 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"

    {title}

    " + f'

    {description}

    ' + "

    Phase 1 shell placeholder — no write actions. Tracked under " + "epic #631.

    " + ) + 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))) @@ -281,6 +358,49 @@ async def api_actions(_request: Request) -> JSONResponse: return JSONResponse(load_action_registry().to_dict()) +def _request_id() -> str: + return f"req-{uuid.uuid4().hex}" + + +def _audit_target(action_id: str, params: dict[str, object]) -> dict[str, object]: + """Describe the action target for the audit record (never secrets).""" + if "pr_number" in params: + return {"kind": "pr", "ref": f"#{params['pr_number']}"} + if "issue_number" in params: + return {"kind": "issue", "ref": f"#{params['issue_number']}"} + if "branch_name" in params: + return {"kind": "branch", "ref": str(params["branch_name"])} + return {"kind": "unspecified", "ref": action_id} + + +def _authorize_request( + request: Request, + action_id: str, + params: dict[str, object], + *, + for_execution: bool, + result: str, +) -> dict[str, object]: + """Resolve principal, decide, and audit. Returns the decision payload. + + Phase 1 records the decision rather than enforcing it as the terminal + outcome: ``webui.gated_actions`` already fails closed for every action, so + this layer cannot loosen anything. Phase 2 enforces on this same decision. + """ + principal = resolve_principal(headers=dict(request.headers)) + decision = authorize(action_id, principal, for_execution=for_execution) + console_audit.record_event( + action_id=action_id, + result=result, + decision=decision, + principal=principal, + target=_audit_target(action_id, params), + request_id=_request_id(), + detail=decision.detail, + ) + return decision.to_dict() + + async def api_action_preview(request: Request) -> JSONResponse: action_id = request.path_params["action_id"] params = dict(request.query_params) @@ -290,6 +410,13 @@ async def api_action_preview(request: Request) -> JSONResponse: result = preview_action(action_id, **params) if "error" in result: return JSONResponse(result, status_code=404) + result["authorization"] = _authorize_request( + request, + action_id, + params, + for_execution=False, + result=console_audit.RESULT_PREVIEWED, + ) return JSONResponse(result) @@ -303,6 +430,18 @@ async def api_action_attempt(request: Request) -> JSONResponse: if not isinstance(body, dict): body = {} result = attempt_action(action_id, **body) + authorization = _authorize_request( + request, + action_id, + body, + for_execution=True, + result=( + console_audit.RESULT_DENIED + if not result.get("success") + else console_audit.RESULT_ALLOWED + ), + ) + result["authorization"] = authorization status = 403 if not result.get("success") else 200 return JSONResponse(result, status_code=status) @@ -331,6 +470,113 @@ async def api_inventory_section(request: Request) -> JSONResponse: return JSONResponse(payload) +async def api_console_security_model(_request: Request) -> JSONResponse: + """Read-only publication of the #633 authorization/redaction/audit model.""" + return JSONResponse({ + "rbac": rbac_matrix(), + "redaction": redaction_policy(), + "audit": console_audit.audit_policy(), + }) + + +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": @@ -353,6 +599,7 @@ 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"]), @@ -369,6 +616,7 @@ 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"]), @@ -393,6 +641,15 @@ def create_app(*, bind_host: str | None = None) -> Starlette: api_inventory_section, methods=["GET"], ), + Route( + "/api/console/security-model", + api_console_security_model, + methods=["GET"], + ), + *[ + Route(path, phase_stub, methods=["GET"]) + for path in STUB_PAGES + ], ], exception_handlers={405: method_not_allowed}, ) diff --git a/webui/console_audit.py b/webui/console_audit.py new file mode 100644 index 0000000..fd560ee --- /dev/null +++ b/webui/console_audit.py @@ -0,0 +1,281 @@ +"""Console audit event schema, retention, and append-only sink (#633). + +``gitea_audit`` records MCP-side *mutations*: which profile and Gitea user +performed which tool call. It carries no console actor, no identity source, no +correlation identifier, and no retention class, so it cannot answer the +question #633 exists to answer — *who sat at the console, what did they +attempt, and was it authorized?* An authorization denial is not a mutation and +would never appear there at all. + +This module adds the console-side record. It does not replace ``gitea_audit``: +when a Phase 2 action eventually reaches MCP, both fire, correlated by +``correlation.request_id``. + +Design constraints: + +- **Redact before persist.** Every record passes through + ``webui.console_redaction.redact_payload`` before serialization, so an + unredacted field is never durable. +- **Append-only.** Records are appended as JSON lines. Nothing here updates or + deletes; retention is metadata on each record, enforced by an operator-run + policy, never by silent rewriting. +- **Never raises.** Auditing must not break the request it describes. A failed + write returns ``False``. +- **Off by default.** With ``WEBUI_CONSOLE_AUDIT_LOG`` unset, events are still + *built* (so callers and tests see the schema) but nothing is written. + +A record looks like this (synthetic values): + + {"schema_version": 1, "event_id": "evt-0001", + "timestamp": "2026-07-22T10:16:42+00:00", + "actor": {"subject": "ops@example.com", "role": "operator", + "identity_source": "access_proxy", "authenticated": true}, + "action": "merge_pr", "action_class": "privileged", + "target": {"kind": "pr", "ref": "#123"}, + "result": "denied", "reason_code": "insufficient_role", + "correlation": {"request_id": "req-abc", "session_id": null, + "mcp_task": "merge_pr", "mcp_permission": "gitea.pr.merge"}, + "retention": {"class": "privileged", "days": 365, + "expires_at": "2027-07-22T10:16:42+00:00"}, + "redacted": true} + +Timestamps are timezone-aware ISO-8601 in UTC. +""" + +from __future__ import annotations + +import datetime +import json +import os +import uuid +from typing import Any + +from webui import console_authz +from webui.console_redaction import redact_payload, scan_for_secrets + +SCHEMA_VERSION = 1 + +AUDIT_LOG_ENV = "WEBUI_CONSOLE_AUDIT_LOG" + +# Result vocabulary. ``denied`` is the one ``gitea_audit`` has no equivalent +# for: an authorization refusal never reaches the MCP layer. +RESULT_ALLOWED = "allowed" +RESULT_DENIED = "denied" +RESULT_PREVIEWED = "previewed" +RESULT_FAILED = "failed" +RESULT_SUCCEEDED = "succeeded" + +RESULTS = frozenset( + { + RESULT_ALLOWED, + RESULT_DENIED, + RESULT_PREVIEWED, + RESULT_FAILED, + RESULT_SUCCEEDED, + } +) + +# Retention classes and default lifetimes in days. Privileged and break-glass +# records outlive routine ones because they are what an incident review needs. +RETENTION_STANDARD = "standard" +RETENTION_PRIVILEGED = "privileged" +RETENTION_BREAK_GLASS = "break_glass" + +RETENTION_DAYS: dict[str, int] = { + RETENTION_STANDARD: 90, + RETENTION_PRIVILEGED: 365, + RETENTION_BREAK_GLASS: 730, +} + +# Fields every record must carry. Asserted by the test suite so a future edit +# cannot quietly drop one. +REQUIRED_FIELDS: tuple[str, ...] = ( + "schema_version", + "event_id", + "timestamp", + "actor", + "action", + "action_class", + "target", + "result", + "reason_code", + "correlation", + "retention", + "redacted", +) + +REQUIRED_ACTOR_FIELDS: tuple[str, ...] = ( + "subject", + "role", + "identity_source", + "authenticated", +) + +REQUIRED_CORRELATION_FIELDS: tuple[str, ...] = ( + "request_id", + "session_id", + "mcp_task", + "mcp_permission", +) + + +def audit_log_path() -> str | None: + """Configured sink path, or ``None`` when console auditing is off.""" + return (os.environ.get(AUDIT_LOG_ENV) or "").strip() or None + + +def audit_enabled() -> bool: + return audit_log_path() is not None + + +def retention_class_for(action: console_authz.ConsoleAction | None) -> str: + """Classify retention from the action, defaulting to the longest-lived. + + An unknown action is treated as privileged rather than standard: for a + safety control the conservative direction is to keep the record longer. + """ + if action is None: + return RETENTION_PRIVILEGED + if action.break_glass: + return RETENTION_BREAK_GLASS + if action.privileged: + return RETENTION_PRIVILEGED + return RETENTION_STANDARD + + +def _retention_block( + retention_class: str, now: datetime.datetime +) -> dict[str, Any]: + days = RETENTION_DAYS.get( + retention_class, RETENTION_DAYS[RETENTION_PRIVILEGED] + ) + return { + "class": retention_class, + "days": days, + "expires_at": (now + datetime.timedelta(days=days)).isoformat(), + } + + +def build_event( + *, + action_id: str, + result: str, + decision: console_authz.AuthorizationDecision | None = None, + principal: console_authz.Principal | None = None, + target: dict[str, Any] | None = None, + reason_code: str | None = None, + request_id: str | None = None, + session_id: str | None = None, + detail: str | None = None, + metadata: dict[str, Any] | None = None, + now: datetime.datetime | None = None, + event_id: str | None = None, +) -> dict[str, Any]: + """Build one redacted, JSON-able console audit record. + + Redaction runs here rather than at write time so an in-memory record handed + to a template or an API response is already clean. + """ + ts = now or datetime.datetime.now(datetime.timezone.utc) + action = console_authz.get_action(action_id) + who = principal or ( + decision.principal if decision else console_authz.ANONYMOUS + ) + resolved_result = result if result in RESULTS else RESULT_FAILED + resolved_reason = reason_code or ( + decision.reason_code if decision else "unspecified" + ) + retention_class = retention_class_for(action) + + event: dict[str, Any] = { + "schema_version": SCHEMA_VERSION, + "event_id": event_id or f"evt-{uuid.uuid4().hex}", + "timestamp": ts.isoformat(), + "actor": who.to_dict(), + "action": action_id, + "action_class": action.action_class if action else "unknown", + "target": dict(target or {}), + "result": resolved_result, + "reason_code": resolved_reason, + "correlation": { + "request_id": request_id, + "session_id": session_id, + "mcp_task": action.task_key if action else None, + "mcp_permission": action.mcp_permission if action else None, + }, + "retention": _retention_block(retention_class, ts), + "redacted": True, + "detail": detail, + "metadata": dict(metadata or {}), + } + if decision is not None: + # Deliberately *not* named "authorization": ``gitea_audit`` treats that + # substring as a secret key hint (it matches the HTTP Authorization + # header) and would replace this whole block with the placeholder. + event["decision"] = { + "allowed": decision.allowed, + "required_role": decision.required_role, + "requires_confirmation": decision.requires_confirmation, + "dual_control": decision.dual_control, + "break_glass": decision.break_glass, + "execution_enabled": decision.execution_enabled, + } + + redacted = redact_payload(event) + if not isinstance(redacted, dict): # pragma: no cover - defensive + return {"schema_version": SCHEMA_VERSION, "redacted": True} + return redacted + + +def write_event(event: dict[str, Any], path: str | None = None) -> bool: + """Append *event* as one JSON line. Never raises. + + Returns ``True`` when a line was written, ``False`` when auditing is off or + the write failed. A record that still trips a secret detector is dropped + rather than persisted. + """ + sink = path or audit_log_path() + if not sink: + return False + try: + if scan_for_secrets(event): + return False + line = json.dumps(event, default=str, sort_keys=True) + with open(sink, "a", encoding="utf-8") as handle: + handle.write(line + "\n") + return True + except Exception: + return False + + +def record_event(**kwargs: Any) -> dict[str, Any]: + """Build and persist one record; return the record either way. + + Callers get the record back so it can be surfaced in a response or a test + regardless of whether a sink is configured. + """ + event = build_event(**kwargs) + written = write_event(event) + return {"event": event, "written": written} + + +def audit_policy() -> dict[str, Any]: + """Machine-readable audit schema and retention defaults (never secrets).""" + return { + "schema_version": SCHEMA_VERSION, + "required_fields": list(REQUIRED_FIELDS), + "required_actor_fields": list(REQUIRED_ACTOR_FIELDS), + "required_correlation_fields": list(REQUIRED_CORRELATION_FIELDS), + "results": sorted(RESULTS), + "retention_defaults_days": dict(RETENTION_DAYS), + "sink_env": AUDIT_LOG_ENV, + "enabled": audit_enabled(), + "append_only": True, + "redact_before_persist": True, + "timestamp_format": "ISO-8601, timezone-aware, UTC", + "relationship_to_mcp_audit": ( + "webui.console_audit records console intent and authorization " + "outcomes; gitea_audit records MCP mutations. A Phase 2 action " + "emits both, correlated by correlation.request_id." + ), + } diff --git a/webui/console_authz.py b/webui/console_authz.py new file mode 100644 index 0000000..2e64b2c --- /dev/null +++ b/webui/console_authz.py @@ -0,0 +1,537 @@ +"""Console authorization and RBAC model (#633, Phase 1). + +The read-only MVP (#426–#436) ships with no authentication: protection comes +from network placement alone (#435). That is adequate while every route is a +GET, and inadequate the moment Phase 2 wires a gated write. This module is the +authorization model those writes must go through, landed *before* any of them +exists so no write can be added without an authority to check against. + +Phase 1 scope is the model itself: identity resolution, the role matrix, the +privileged-action list, and a fail-closed :func:`authorize`. It deliberately +does **not** enable any write. ``webui.gated_actions`` stays globally disabled, +so an allow decision here is necessary but never sufficient. + +Two invariants hold for every caller: + +- **Default deny.** An unrecognised action, an unknown role, or an absent + principal denies. There is no implicit allow branch and no "unless" clause. +- **Authorization is not execution.** :func:`authorize` returns a decision + record. It never calls MCP, never mutates, and never consults credentials. +""" + +from __future__ import annotations + +import json +import os +from dataclasses import asdict, dataclass, field +from typing import Any + +from task_capability_map import required_permission, required_role + +# --- Roles ------------------------------------------------------------------ +# Ordered least to most authority. Higher ranks inherit every lower rank's +# permitted actions; the matrix below is expressed as a minimum required rank. +VIEWER = "viewer" +OPERATOR = "operator" +CONTROLLER = "controller" +ADMIN = "admin" + +ROLE_ORDER: tuple[str, ...] = (VIEWER, OPERATOR, CONTROLLER, ADMIN) +_ROLE_RANK: dict[str, int] = {role: idx for idx, role in enumerate(ROLE_ORDER)} + +ROLE_DESCRIPTIONS: dict[str, str] = { + VIEWER: "Read every console view. No write, ever, in any phase.", + OPERATOR: "Viewer, plus author-class work: claim, comment, open a PR.", + CONTROLLER: "Operator, plus reviewer/merger-class decisions on a PR.", + ADMIN: "Controller, plus destructive and policy-editing actions.", +} + +# --- Identity sources ------------------------------------------------------- +IDENTITY_NONE = "none" +IDENTITY_LOCAL_DEV = "local_dev" +IDENTITY_ACCESS_PROXY = "access_proxy" + +IDENTITY_SOURCES: dict[str, dict[str, Any]] = { + IDENTITY_NONE: { + "description": ( + "No authentication configured. Every request is anonymous and " + "capped at viewer. This is the MVP default and the only mode " + "whose safety rests entirely on network placement (#435)." + ), + "authenticated": False, + "safe_for_shared_host": False, + "phase_available": 1, + }, + IDENTITY_LOCAL_DEV: { + "description": ( + "Developer-supplied principal read from the environment. INSECURE: " + "the subject and role are asserted, never verified. Loopback only." + ), + "authenticated": True, + "safe_for_shared_host": False, + "phase_available": 1, + }, + IDENTITY_ACCESS_PROXY: { + "description": ( + "Subject asserted by a trusted access proxy (Cloudflare Access, " + "WARP, or an org VPN portal) via a verified request header. The " + "proxy performs authentication; the console performs authorization." + ), + "authenticated": True, + "safe_for_shared_host": True, + "phase_available": 2, + }, +} + +# Environment configuration. All are read server-side and never rendered. +AUTH_MODE_ENV = "WEBUI_AUTH_MODE" +DEV_SUBJECT_ENV = "WEBUI_DEV_SUBJECT" +DEV_ROLE_ENV = "WEBUI_DEV_ROLE" +ROLE_MAP_ENV = "WEBUI_ROLE_MAP" +REQUIRE_PROBE_AUTH_ENV = "WEBUI_REQUIRE_PROBE_AUTH" +ACCESS_SUBJECT_HEADER = "cf-access-authenticated-user-email" + +# --- Action classes --------------------------------------------------------- +CLASS_READ = "read" +CLASS_WRITE = "gated_write" +CLASS_PRIVILEGED = "privileged" +CLASS_DESTRUCTIVE = "destructive" + +# --- Privileged action list ------------------------------------------------- +# ``task_key`` ties each console action back to ``task_capability_map``, so the +# console cannot invent an authority the MCP layer does not already define. + + +@dataclass(frozen=True) +class ConsoleAction: + """One console action and the authority required to invoke it.""" + + action_id: str + task_key: str + action_class: str + minimum_role: str + requires_confirmation: bool + dual_control: bool + break_glass: bool + phase: int + summary: str + + @property + def mcp_permission(self) -> str: + return required_permission(self.task_key) + + @property + def mcp_role(self) -> str: + return required_role(self.task_key) + + @property + def privileged(self) -> bool: + return self.action_class in {CLASS_PRIVILEGED, CLASS_DESTRUCTIVE} + + def to_dict(self) -> dict[str, Any]: + data = asdict(self) + data["mcp_permission"] = self.mcp_permission + data["mcp_role"] = self.mcp_role + data["privileged"] = self.privileged + return data + + +_ACTION_SPECS: tuple[ConsoleAction, ...] = ( + ConsoleAction( + action_id="claim_issue", + task_key="claim_issue", + action_class=CLASS_WRITE, + minimum_role=OPERATOR, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=2, + summary="Apply status:in-progress to an issue.", + ), + ConsoleAction( + action_id="comment_issue", + task_key="comment_issue", + action_class=CLASS_WRITE, + minimum_role=OPERATOR, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=2, + summary="Post an issue comment.", + ), + ConsoleAction( + action_id="create_issue", + task_key="create_issue", + action_class=CLASS_WRITE, + minimum_role=OPERATOR, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=2, + summary="Open a new tracking issue.", + ), + ConsoleAction( + action_id="comment_pr", + task_key="comment_pr", + action_class=CLASS_WRITE, + minimum_role=OPERATOR, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=2, + summary="Post a PR thread comment.", + ), + ConsoleAction( + action_id="create_pr", + task_key="create_pr", + action_class=CLASS_WRITE, + minimum_role=OPERATOR, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=2, + summary="Open a PR from a locked feature branch.", + ), + ConsoleAction( + action_id="review_pr", + task_key="review_pr", + action_class=CLASS_PRIVILEGED, + minimum_role=CONTROLLER, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=3, + summary="Submit an approve / request-changes verdict.", + ), + ConsoleAction( + action_id="close_pr", + task_key="close_pr", + action_class=CLASS_PRIVILEGED, + minimum_role=CONTROLLER, + requires_confirmation=True, + dual_control=False, + break_glass=False, + phase=3, + summary="Close a pull request without merging.", + ), + ConsoleAction( + action_id="merge_pr", + task_key="merge_pr", + action_class=CLASS_PRIVILEGED, + minimum_role=CONTROLLER, + requires_confirmation=True, + dual_control=True, + break_glass=True, + phase=3, + summary="Merge an approved pull request.", + ), + ConsoleAction( + action_id="delete_branch", + task_key="delete_branch", + action_class=CLASS_DESTRUCTIVE, + minimum_role=ADMIN, + requires_confirmation=True, + dual_control=True, + break_glass=True, + phase=3, + summary="Remove a remote feature branch.", + ), +) + +ACTIONS: dict[str, ConsoleAction] = {a.action_id: a for a in _ACTION_SPECS} + + +def privileged_actions() -> tuple[ConsoleAction, ...]: + """Actions requiring dual control, break-glass, or controller+ authority.""" + return tuple(a for a in _ACTION_SPECS if a.privileged) + + +def get_action(action_id: str) -> ConsoleAction | None: + return ACTIONS.get(action_id) + + +# --- Principals ------------------------------------------------------------- + + +@dataclass(frozen=True) +class Principal: + """Who is making a request, and how strongly that is known.""" + + subject: str + role: str + identity_source: str + authenticated: bool + warnings: tuple[str, ...] = field(default_factory=tuple) + + @property + def rank(self) -> int: + return _ROLE_RANK.get(self.role, -1) + + def to_dict(self) -> dict[str, Any]: + return { + "subject": self.subject, + "role": self.role, + "identity_source": self.identity_source, + "authenticated": self.authenticated, + "warnings": list(self.warnings), + } + + +ANONYMOUS = Principal( + subject="anonymous", + role=VIEWER, + identity_source=IDENTITY_NONE, + authenticated=False, + warnings=("No authentication configured; capped at viewer.",), +) + + +def auth_mode(env: dict[str, str] | None = None) -> str: + """Resolve the configured identity source, defaulting to ``none``.""" + source = env if env is not None else os.environ + raw = (source.get(AUTH_MODE_ENV) or "").strip().lower().replace("-", "_") + if raw in IDENTITY_SOURCES: + return raw + return IDENTITY_NONE + + +def _role_map(env: dict[str, str]) -> dict[str, str]: + """Parse ``WEBUI_ROLE_MAP`` (JSON subject→role). Invalid config yields {}.""" + raw = (env.get(ROLE_MAP_ENV) or "").strip() + if not raw: + return {} + try: + parsed = json.loads(raw) + except Exception: + return {} + if not isinstance(parsed, dict): + return {} + return { + str(k): str(v).strip().lower() + for k, v in parsed.items() + if str(v).strip().lower() in _ROLE_RANK + } + + +def resolve_principal( + headers: dict[str, str] | None = None, + env: dict[str, str] | None = None, +) -> Principal: + """Resolve the requesting principal. Unknown or unconfigured → anonymous. + + Never raises and never trusts a client-supplied role: the role always comes + from server-side configuration keyed by the resolved subject. + """ + source_env = dict(env) if env is not None else dict(os.environ) + lowered = {str(k).lower(): str(v) for k, v in (headers or {}).items()} + mode = auth_mode(source_env) + + if mode == IDENTITY_LOCAL_DEV: + subject = (source_env.get(DEV_SUBJECT_ENV) or "").strip() + if not subject: + return ANONYMOUS + role = (source_env.get(DEV_ROLE_ENV) or VIEWER).strip().lower() + if role not in _ROLE_RANK: + role = VIEWER + return Principal( + subject=subject, + role=role, + identity_source=IDENTITY_LOCAL_DEV, + authenticated=True, + warnings=( + "local-dev identity is asserted, not verified; never use " + "outside loopback.", + ), + ) + + if mode == IDENTITY_ACCESS_PROXY: + subject = (lowered.get(ACCESS_SUBJECT_HEADER) or "").strip() + if not subject: + # Proxy mode with no proxy header means the request did not + # traverse the proxy. Fail closed rather than trust it. + return ANONYMOUS + role = _role_map(source_env).get(subject, VIEWER) + return Principal( + subject=subject, + role=role, + identity_source=IDENTITY_ACCESS_PROXY, + authenticated=True, + ) + + return ANONYMOUS + + +def probe_auth_required(env: dict[str, str] | None = None) -> bool: + """Whether non-public probes must be authenticated. Default False. + + #633 requires the console to *fail closed on missing auth for non-public + health probes if configured*. The default stays off so the MVP ``/health`` + contract is unchanged; an operator opts in explicitly. + """ + source = env if env is not None else os.environ + return (source.get(REQUIRE_PROBE_AUTH_ENV) or "").strip().lower() in { + "1", + "true", + "yes", + } + + +# --- Authorization ---------------------------------------------------------- + +DENY_UNKNOWN_ACTION = "unknown_action" +DENY_UNAUTHENTICATED = "unauthenticated" +DENY_INSUFFICIENT_ROLE = "insufficient_role" +DENY_UNKNOWN_ROLE = "unknown_role" +DENY_PHASE_NOT_ACTIVE = "phase_not_active" +ALLOW_PREVIEW = "allowed_preview_only" + +# Phase 1 is the only active console phase. Phase 2 opens gated writes and is +# gated on this model landing; nothing here enables it. +ACTIVE_PHASE = 1 + + +@dataclass(frozen=True) +class AuthorizationDecision: + """Result of an authorization check. Never an execution grant.""" + + allowed: bool + reason_code: str + detail: str + action_id: str + principal: Principal + required_role: str | None = None + action_class: str | None = None + requires_confirmation: bool = False + dual_control: bool = False + break_glass: bool = False + execution_enabled: bool = False + + def to_dict(self) -> dict[str, Any]: + return { + "allowed": self.allowed, + "reason_code": self.reason_code, + "detail": self.detail, + "action_id": self.action_id, + "principal": self.principal.to_dict(), + "required_role": self.required_role, + "action_class": self.action_class, + "requires_confirmation": self.requires_confirmation, + "dual_control": self.dual_control, + "break_glass": self.break_glass, + "execution_enabled": self.execution_enabled, + "active_phase": ACTIVE_PHASE, + } + + +def authorize( + action_id: str, + principal: Principal | None = None, + *, + for_execution: bool = False, +) -> AuthorizationDecision: + """Decide whether *principal* may invoke *action_id*. Deny by default. + + ``for_execution`` distinguishes a read-only preview from a real invocation. + Even an allowed decision reports ``execution_enabled=False`` while the + console is in Phase 1, so no caller can read an allow as permission to + mutate. + """ + who = principal if principal is not None else ANONYMOUS + action = get_action(action_id) + + if action is None: + return AuthorizationDecision( + allowed=False, + reason_code=DENY_UNKNOWN_ACTION, + detail=f"No console action registered as {action_id!r}.", + action_id=action_id, + principal=who, + ) + + base: dict[str, Any] = { + "action_id": action_id, + "principal": who, + "required_role": action.minimum_role, + "action_class": action.action_class, + "requires_confirmation": action.requires_confirmation, + "dual_control": action.dual_control, + "break_glass": action.break_glass, + "execution_enabled": False, + } + + if not who.authenticated: + return AuthorizationDecision( + allowed=False, + reason_code=DENY_UNAUTHENTICATED, + detail=( + "Write actions require an authenticated principal; this " + "request is anonymous." + ), + **base, + ) + + if who.rank < 0: + return AuthorizationDecision( + allowed=False, + reason_code=DENY_UNKNOWN_ROLE, + detail=f"Role {who.role!r} is not in the console role matrix.", + **base, + ) + + if who.rank < _ROLE_RANK[action.minimum_role]: + return AuthorizationDecision( + allowed=False, + reason_code=DENY_INSUFFICIENT_ROLE, + detail=( + f"Action {action_id!r} requires {action.minimum_role!r}; " + f"principal holds {who.role!r}." + ), + **base, + ) + + if for_execution and action.phase > ACTIVE_PHASE: + return AuthorizationDecision( + allowed=False, + reason_code=DENY_PHASE_NOT_ACTIVE, + detail=( + f"Action {action_id!r} belongs to phase {action.phase}; the " + f"console is in phase {ACTIVE_PHASE}. Execution is not wired." + ), + **base, + ) + + return AuthorizationDecision( + allowed=True, + reason_code=ALLOW_PREVIEW, + detail=( + "Principal holds the required role. Preview only — execution " + "remains disabled until the Phase 2 action framework ships." + ), + **base, + ) + + +def rbac_matrix() -> dict[str, Any]: + """Machine-readable RBAC matrix and privileged-action list.""" + return { + "model_version": 1, + "active_phase": ACTIVE_PHASE, + "roles": [ + { + "role": role, + "rank": _ROLE_RANK[role], + "description": ROLE_DESCRIPTIONS[role], + "permitted_actions": sorted( + a.action_id + for a in _ACTION_SPECS + if _ROLE_RANK[role] >= _ROLE_RANK[a.minimum_role] + ), + } + for role in ROLE_ORDER + ], + "identity_sources": IDENTITY_SOURCES, + "actions": [a.to_dict() for a in _ACTION_SPECS], + "privileged_actions": [a.action_id for a in privileged_actions()], + "default_decision": "deny", + "execution_enabled": False, + } diff --git a/webui/console_redaction.py b/webui/console_redaction.py new file mode 100644 index 0000000..06773a8 --- /dev/null +++ b/webui/console_redaction.py @@ -0,0 +1,169 @@ +"""Secret redaction policy for every console surface (#633). + +The MVP already redacts MCP-side mutation records through ``gitea_audit``. +This module is the console-facing policy: one redaction pass applied to API +payloads, rendered HTML, log lines, and audit records *before* they leave the +server or reach persistent storage. + +Design constraints: + +- **Reuse, never fork.** ``gitea_audit.redact`` remains the authority for + secret-looking dict keys, ``Authorization`` material, and raw URLs. This + module runs that pass first and then applies console-specific patterns for + keychain references, key/value assignments, private-key blocks, and JWTs. +- **Never raises.** Redaction is a safety control; a malformed payload must + degrade to a redacted placeholder rather than propagate an exception. +- **Redact before persist.** ``webui.console_audit`` calls this module before + writing, so an unredacted record is never durable. +""" + +from __future__ import annotations + +import json +import re +from typing import Any + +import gitea_audit + +REDACTED = gitea_audit.REDACTED + +# Console-specific patterns applied after the shared ``gitea_audit`` pass. +# Each keeps the identifying key so an operator can still tell *what* was +# removed, and replaces only the secret run itself. +_KEYCHAIN_REF = re.compile(r"(?i)\bkeychain:[\w.\-/@]+") +_KEYCHAIN_CMD = re.compile( + r"(?i)\bsecurity\s+find-(?:generic|internet)-password\b[^\n]*" +) +_ASSIGNMENT = re.compile( + r"(?i)\b(token|password|passwd|secret|api[_-]?key|access[_-]?key|" + r"client[_-]?secret|private[_-]?key)\b(\s*[:=]\s*)" + r"(\"[^\"]*\"|'[^']*'|\S+)" +) +_ENV_ASSIGNMENT = re.compile( + r"(?i)\b(GITEA_(?:TOKEN|PASS|PASSWORD)[A-Z0-9_]*)(\s*=\s*)" + r"(\"[^\"]*\"|'[^']*'|\S+)" +) +_PRIVATE_KEY_BLOCK = re.compile( + r"-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----", + re.S, +) +_JWT = re.compile( + r"\beyJ[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\.[A-Za-z0-9_\-]{8,}\b" +) + +# Shapes that mean a payload still carries a secret. ``scan_for_secrets`` uses +# these to assert a surface is clean. +_DETECTORS: tuple[tuple[str, re.Pattern[str]], ...] = ( + ("keychain_reference", _KEYCHAIN_REF), + ("keychain_command", _KEYCHAIN_CMD), + ("credential_assignment", _ASSIGNMENT), + ("credential_env_assignment", _ENV_ASSIGNMENT), + ("private_key_block", _PRIVATE_KEY_BLOCK), + ("json_web_token", _JWT), + ("bearer_credential", re.compile(r"(?i)\b(?:bearer|basic)\s+\S{8,}")), +) + + +def _mask_assignment(match: re.Match[str]) -> str: + """Keep the key and separator, replace the value.""" + return f"{match.group(1)}{match.group(2)}{REDACTED}" + + +def redact_text(text: Any) -> Any: + """Redact secret material from a single string. + + Non-strings are returned unchanged so this is safe to map over mixed + payloads. Runs the shared ``gitea_audit`` pass first, then the + console-specific patterns. + """ + if not isinstance(text, str) or not text: + return text + try: + out = gitea_audit.redact(text) + if not isinstance(out, str): # defensive; redact() returns str for str + return REDACTED + out = _PRIVATE_KEY_BLOCK.sub(f"{REDACTED}_PRIVATE_KEY", out) + out = _ENV_ASSIGNMENT.sub(_mask_assignment, out) + out = _ASSIGNMENT.sub(_mask_assignment, out) + out = _KEYCHAIN_CMD.sub(f"{REDACTED}_KEYCHAIN_COMMAND", out) + out = _KEYCHAIN_REF.sub(f"{REDACTED}_KEYCHAIN_REF", out) + out = _JWT.sub(f"{REDACTED}_JWT", out) + return out + except Exception: + # Fail closed: an unredactable string is dropped rather than emitted raw. + return REDACTED + + +def redact_payload(value: Any) -> Any: + """Recursively redact a JSON-able payload for any console surface. + + Secret-looking dict keys are replaced wholesale by the shared + ``gitea_audit`` policy; every remaining string is run through + :func:`redact_text`. + """ + try: + shared = gitea_audit.redact(value) + except Exception: + return REDACTED + return _walk(shared) + + +def _walk(value: Any) -> Any: + if isinstance(value, dict): + return {k: _walk(v) for k, v in value.items()} + if isinstance(value, (list, tuple)): + return [_walk(v) for v in value] + if isinstance(value, str): + return redact_text(value) + return value + + +def scan_for_secrets(value: Any) -> list[str]: + """Return detector names that still match *value* after serialization. + + Used to assert an outbound payload or rendered page is clean. An empty + list means no known secret shape was found. Already-redacted hits are not + findings. + """ + if isinstance(value, str): + text = value + else: + try: + text = json.dumps(value, default=str) + except Exception: + text = str(value) + findings: list[str] = [] + for name, pattern in _DETECTORS: + for match in pattern.finditer(text): + if REDACTED in match.group(0): + continue + findings.append(name) + break + return findings + + +def redaction_policy() -> dict[str, Any]: + """Machine-readable statement of the redaction rules (never secrets).""" + return { + "policy_version": 1, + "applies_to": [ + "json_api_responses", + "rendered_html", + "server_logs", + "audit_records", + ], + "ordering": "shared gitea_audit pass, then console patterns", + "redact_before_persist": True, + "shared_rules": { + "source": "gitea_audit.redact", + "secret_key_hints": list(gitea_audit._SECRET_KEY_HINTS), + "secret_value_prefixes": list(gitea_audit._SECRET_VALUE_PREFIXES), + "urls": "credentials, secret query parameters, and real hosts redacted", + }, + "console_rules": [ + {"name": name, "pattern": pattern.pattern} + for name, pattern in _DETECTORS + ], + "placeholder": REDACTED, + "failure_mode": "fail closed — unredactable values become the placeholder", + } diff --git a/webui/layout.py b/webui/layout.py index 47bedc1..4d62eca 100644 --- a/webui/layout.py +++ b/webui/layout.py @@ -2,28 +2,66 @@ from __future__ import annotations -NAV_ITEMS = ( - ("/", "Home"), - ("/queue", "Queue"), - ("/projects", "Projects"), - ("/prompts", "Prompts"), - ("/runtime", "Runtime"), - ("/audit", "Audit"), - ("/worktrees", "Worktrees"), - ("/leases", "Leases"), - ("/actions", "Actions"), -) +import os + +from webui.nav import NAV_GROUPS 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'{item.label}' + for item in group.items + ) + groups_html.append( + '
    ' + f'{group.label}' + f'{links}' + "
    " + ) + return "".join(groups_html) + + +def _render_badges() -> str: + env = environment_label() + return ( + '
    ' + f'env: {env}' + 'mode: read-only' + f'Docs' + "
    " + ) + def render_page(*, title: str, body_html: str, extra_head: str = "") -> str: - nav_links = "".join( - f'{label}' for href, label in NAV_ITEMS - ) + nav_links = _render_nav() + header_badges = _render_badges() return f""" @@ -53,21 +91,58 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str: padding: 0.75rem 1.25rem; }} header h1 {{ - margin: 0 0 0.5rem; + margin: 0; 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.75rem 1rem; + gap: 0.5rem 1.25rem; }} + .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; @@ -166,7 +241,10 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
    -

    MCP Control Plane

    +
    +

    MCP Control Plane

    + {header_badges} +
    diff --git a/webui/nav.py b/webui/nav.py new file mode 100644 index 0000000..edb128c --- /dev/null +++ b/webui/nav.py @@ -0,0 +1,111 @@ +"""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()) diff --git a/webui/system_health.py b/webui/system_health.py new file mode 100644 index 0000000..a36438b --- /dev/null +++ b/webui/system_health.py @@ -0,0 +1,682 @@ +"""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), + } diff --git a/webui/timeline.py b/webui/timeline.py new file mode 100644 index 0000000..1ec8284 --- /dev/null +++ b/webui/timeline.py @@ -0,0 +1,906 @@ +"""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() diff --git a/workflow_dashboard.py b/workflow_dashboard.py index d2b10ee..e47b2dc 100644 --- a/workflow_dashboard.py +++ b/workflow_dashboard.py @@ -65,9 +65,11 @@ PROMPT_RECONCILER = ( "reconciliation (already-landed / post-merge cleanup). Do not approve or merge." ) PROMPT_CONTROLLER = ( - "CONTROLLER session: inspect gitea_workflow_dashboard + control-plane leases, " - "diagnose blocked/terminal-locked items for {remote}/{org}/{repo}, and schedule " - "exactly one fresh role-scoped cycle. Do not implement, review, or merge in-band." + "CONTROLLER session: call gitea_route_task_session(task_type='process_work_queue') " + "then gitea_allocate_next_work (cross_role default) for {remote}/{org}/{repo}; " + "use the returned required_role/profile/action to schedule exactly one downstream " + "role cycle. Dashboard is explanatory only and never replaces allocator selection. " + "Do not implement, review, approve, or merge in-band." ) PROMPT_IDLE = ( "IDLE: no safe assignable work for role '{role}' on {remote}/{org}/{repo}. " diff --git a/worktree_cleanup_audit.py b/worktree_cleanup_audit.py index 261164a..9eb4b35 100644 --- a/worktree_cleanup_audit.py +++ b/worktree_cleanup_audit.py @@ -34,7 +34,11 @@ import subprocess from datetime import datetime, timezone from typing import Any -from merged_cleanup_reconcile import branch_worktree_folder, read_local_worktree_state +from merged_cleanup_reconcile import ( + 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"}) @@ -67,6 +71,14 @@ 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/") @@ -169,6 +181,186 @@ 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, @@ -181,6 +373,8 @@ 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. @@ -199,6 +393,8 @@ 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 @@ -207,7 +403,15 @@ def classify_worktree( if is_detached or branch_gone: return CLASS_DETACHED_REVIEW_LEFTOVER return CLASS_CLEAN_STALE_REMOVABLE - # issue_work / conflict_fix: only removable once the TTL has expired. + if workflow_type == WORKFLOW_ISSUE_WORK: + # #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 @@ -400,6 +604,20 @@ 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) @@ -413,16 +631,30 @@ 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): @@ -433,12 +665,42 @@ 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, branch=branch, head_sha=entry.get("head") + path=path, + branch=branch, + head_sha=head_sha, + pr_number=linkage.get("pr_number"), ) has_open_pr = bool(branch) and branch in open_pr_branches - has_active_lease = bool(branch) and branch in leased_branches + # A lease on issue N protects that issue's own work worktree. It must + # 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 ) @@ -452,6 +714,8 @@ 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( @@ -463,7 +727,10 @@ 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), }