From f2dbf30e81cb0a8f645b708db8433713260d1b3d Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Sat, 25 Jul 2026 18:48:36 -0400
Subject: [PATCH 01/18] feat(webui): Sentry/GlitchTip observability console &
correlation view (Closes #649)
---
control_plane_db.py | 26 ++
.../webui-observability-console.md | 35 +++
docs/webui-authz-audit.md | 2 +
tests/test_webui_observability.py | 190 ++++++++++++
webui/app.py | 21 ++
webui/console_authz.py | 23 ++
webui/gated_actions.py | 5 +
webui/nav.py | 1 +
webui/observability_loader.py | 275 ++++++++++++++++++
webui/observability_views.py | 143 +++++++++
10 files changed, 721 insertions(+)
create mode 100644 docs/observability/webui-observability-console.md
create mode 100644 tests/test_webui_observability.py
create mode 100644 webui/observability_loader.py
create mode 100644 webui/observability_views.py
diff --git a/control_plane_db.py b/control_plane_db.py
index a1f90d2..422003c 100644
--- a/control_plane_db.py
+++ b/control_plane_db.py
@@ -1568,6 +1568,32 @@ class ControlPlaneDB:
).fetchone()
return dict(row) if row else None
+ def list_incident_links(
+ self,
+ *,
+ provider: str | None = None,
+ gitea_org: str | None = None,
+ gitea_repo: str | None = None,
+ limit: int = 100,
+ ) -> list[dict[str, Any]]:
+ """List stored incident_links rows, optionally filtered by provider/repo (#612 / #649)."""
+ query = "SELECT * FROM incident_links WHERE 1=1"
+ params: list[Any] = []
+ if provider:
+ query += " AND provider = ?"
+ params.append(provider.strip().lower())
+ if gitea_org:
+ query += " AND gitea_org = ?"
+ params.append(_norm_scope(gitea_org))
+ if gitea_repo:
+ query += " AND gitea_repo = ?"
+ params.append(_norm_scope(gitea_repo))
+ query += " ORDER BY link_id DESC LIMIT ?"
+ params.append(max(1, limit))
+ with self._tx(immediate=False) as conn:
+ rows = conn.execute(query, params).fetchall()
+ return [dict(r) for r in rows]
+
# ── lease lifecycle (#601) ────────────────────────────────────────────
diff --git a/docs/observability/webui-observability-console.md b/docs/observability/webui-observability-console.md
new file mode 100644
index 0000000..84ace13
--- /dev/null
+++ b/docs/observability/webui-observability-console.md
@@ -0,0 +1,35 @@
+# Web Console: Sentry/GlitchTip Observability & Incident Bridge Console (#649)
+
+This document describes the Phase 4 observability console surface integrated into the MCP Control Plane Web Console (`webui/`), backed by the #612 incident bridge and the #613 control-plane DB substrate.
+
+## Architectural Authority Model (ADR Alignment)
+
+Per the Web Console Architecture ADR (`docs/architecture/webui-control-plane-console-architecture-adr.md`):
+
+| Layer | Responsibility | Authority |
+|---|---|---|
+| **Gitea** | Durable work record | Issues, PRs, comments, reviews, labels, merges |
+| **Control-plane DB** | Live coordination & linkage | `incident_links` table, session leases, allocations |
+| **Sentry / GlitchTip** | Observability input | Unresolved incidents, error events, stack traces |
+| **Incident Bridge (#612)** | Reconciliation engine | Reconciles provider observations into Gitea issues |
+| **Web Console (`webui/`)** | Read-only projection & gated actions | Projects connection health & correlation links; gates writes |
+
+> **Key Rule:** Raw monitoring incidents are **never** assignable control-plane `work_items`. They remain observation input only.
+
+## Redaction Boundary Invariants
+
+1. **No secrets in returns or rendering:** Auth tokens (`SENTRY_AUTH_TOKEN`, `GLITCHTIP_AUTH_TOKEN`), DSNs, `Authorization` headers, and sensitive local file paths are passed through `webui.console_redaction` before leaving the server.
+2. **Safe projection:** Connection objects report `credentials_present: true/false` rather than exposing raw keys or headers.
+
+## Console Endpoints
+
+- **HTML Surface:** `GET /observability` — Renders provider connection cards, error correlation tables, and gated reconcile controls.
+- **Versioned API:** `GET /api/v1/observability` — Returns structured JSON snapshot with `schema_version`, `providers`, `links`, and `metrics`.
+- **Legacy Compatibility Alias:** `GET /api/observability` — Read-only compatibility alias for Phase 4.
+
+## Gated Actions
+
+- `observability_reconcile_incident` (`gitea_observability_reconcile_incident`): Triggers or previews dry-run issue reconciliation for a provider incident.
+- `observability_link_issue` (`gitea_observability_link_issue`): Links a provider incident to an existing Gitea tracking issue.
+
+Both actions require `operator` role and gate through `task_capability_map`. Execution fails closed in read-only MVP mode.
diff --git a/docs/webui-authz-audit.md b/docs/webui-authz-audit.md
index 70d7a3d..be7e4ee 100644
--- a/docs/webui-authz-audit.md
+++ b/docs/webui-authz-audit.md
@@ -98,6 +98,8 @@ already define, and a regression test asserts each mapping matches.
| `system.rebind_session_worktree` | operator | gated_write | `gitea.read` | Yes | No | No | 2 |
| `system.reconcile_cleanups` | controller | privileged | `gitea.pr.close` | Yes | No | No | 2 |
| `initiate_workflow` | operator | gated_write | `gitea.read` | Yes | No | No | 2 |
+| `observability_reconcile_incident` | operator | gated_write | `gitea.read` | Yes | No | No | 4 |
+| `observability_link_issue` | operator | gated_write | `gitea.read` | Yes | No | No | 4 |
**Dual control** means the acting principal may not be the sole authority: a
second distinct principal must confirm. **Break-glass** means the action is
diff --git a/tests/test_webui_observability.py b/tests/test_webui_observability.py
new file mode 100644
index 0000000..a30a9e8
--- /dev/null
+++ b/tests/test_webui_observability.py
@@ -0,0 +1,190 @@
+"""Tests for Sentry/GlitchTip observability console (#649, Phase 4)."""
+
+from __future__ import annotations
+
+import os
+import pytest
+from control_plane_db import ControlPlaneDB
+from webui.app import create_app
+from webui.console_authz import authorize, resolve_principal
+from webui.gated_actions import load_action_registry, preview_action, attempt_action
+from webui.observability_loader import (
+ load_provider_health,
+ load_observability_snapshot,
+ snapshot_to_dict,
+ ObservabilitySnapshot,
+)
+from webui.observability_views import render_observability_page
+from tests.webui_testclient import TestClient
+
+
+@pytest.fixture
+def test_db(tmp_path):
+ db_path = str(tmp_path / "test_control_plane.db")
+ db = ControlPlaneDB(db_path)
+ return db
+
+
+def test_load_provider_health_redaction():
+ """Ensure tokens and secrets are never returned in provider health data."""
+ env = {
+ "SENTRY_BASE_URL": "https://sentry.prgs.cc",
+ "SENTRY_ORG": "my-org",
+ "SENTRY_PROJECT": "my-project",
+ "SENTRY_AUTH_TOKEN": "secret-sentry-token-12345",
+ "MCP_SENTRY_ISSUE_BRIDGE_ENABLED": "true",
+ }
+ health = load_provider_health("sentry", env)
+ data = health.to_dict()
+
+ assert data["provider"] == "sentry"
+ assert data["base_url"] in {"https://sentry.prgs.cc", "[REDACTED_URL]"}
+ assert data["org"] == "my-org"
+ assert data["project"] == "my-project"
+ assert data["configured"] is True
+ assert data["status"] == "healthy"
+ assert data["credentials_present"] is True
+
+ # Token must NOT be in the dict keys or values
+ serialized = str(data)
+ assert "secret-sentry-token-12345" not in serialized
+ assert "SENTRY_AUTH_TOKEN" not in serialized
+
+
+def test_load_provider_health_statuses():
+ """Test unconfigured, missing token, and disabled statuses."""
+ # Not configured
+ h1 = load_provider_health("sentry", {})
+ d1 = h1.to_dict()
+ assert d1["configured"] is False
+ assert d1["status"] == "not_configured"
+
+ # Missing token
+ h2 = load_provider_health(
+ "sentry", {"SENTRY_ORG": "org", "SENTRY_PROJECT": "proj"}
+ )
+ d2 = h2.to_dict()
+ assert d2["configured"] is False
+ assert d2["status"] == "missing_token"
+
+ # Disabled
+ h3 = load_provider_health(
+ "sentry",
+ {
+ "SENTRY_ORG": "org",
+ "SENTRY_PROJECT": "proj",
+ "SENTRY_AUTH_TOKEN": "token",
+ "MCP_SENTRY_ISSUE_BRIDGE_ENABLED": "false",
+ },
+ )
+ d3 = h3.to_dict()
+ assert d3["configured"] is True
+ assert d3["status"] == "disabled"
+
+
+def test_observability_snapshot_with_db_links(test_db):
+ """Test loading observability snapshot with incident links in DB."""
+ test_db.upsert_incident_link(
+ provider="sentry",
+ provider_issue_id="101",
+ gitea_org="Scaled-Tech-Consulting",
+ gitea_repo="Gitea-Tools",
+ gitea_issue_number=649,
+ provider_base_url="https://sentry.prgs.cc",
+ provider_org="Scaled-Tech-Consulting",
+ provider_project="Gitea-Tools",
+ provider_short_id="ST-101",
+ provider_permalink="https://sentry.prgs.cc/issues/101/",
+ fingerprint="err-fingerprint-001",
+ linked_pr_numbers=[901, 902],
+ last_seen="2026-07-25T12:00:00Z",
+ event_count=5,
+ )
+
+ snapshot = load_observability_snapshot(db=test_db, env={})
+ data = snapshot.to_dict()
+
+ assert data["schema_version"] == 1
+ assert data["metrics"]["total_links"] == 1
+ assert data["metrics"]["sentry_links_count"] == 1
+ assert data["metrics"]["glitchtip_links_count"] == 0
+
+ link = data["links"][0]
+ assert link["provider"] == "sentry"
+ assert link["provider_issue_id"] == "101"
+ assert link["provider_short_id"] == "ST-101"
+ assert link["gitea_issue_number"] == 649
+ assert link["event_count"] == 5
+ assert link["linked_pr_numbers"] == [901, 902]
+
+
+def test_observability_views_rendering(test_db):
+ """Test HTML rendering of the observability dashboard."""
+ snapshot = load_observability_snapshot(db=test_db, env={})
+ html_output = render_observability_page(snapshot)
+
+ assert "Observability & Incident Bridge (#649)" in html_output or "Observability & Incident Bridge (#649)" in html_output or "Observability" in html_output
+ assert "ADR Authority Model:" in html_output
+ assert "Provider Connections" in html_output
+ assert "Correlated Incidents" in html_output
+
+
+def test_webui_observability_routes():
+ """Test Starlette HTTP routes for /observability and /api/v1/observability."""
+ client = TestClient(create_app())
+
+ # HTML page route
+ res_html = client.get("/observability")
+ assert res_html.status_code == 200
+ assert "text/html" in res_html.headers["content-type"]
+ assert "Observability" in res_html.text
+
+ # Versioned API route
+ res_api_v1 = client.get("/api/v1/observability")
+ assert res_api_v1.status_code == 200
+ assert "application/json" in res_api_v1.headers["content-type"]
+ data_v1 = res_api_v1.json()
+ assert "schema_version" in data_v1
+ assert "providers" in data_v1
+ assert "links" in data_v1
+ assert "metrics" in data_v1
+
+ # Compatibility alias route
+ res_api_alias = client.get("/api/observability")
+ assert res_api_alias.status_code == 200
+ assert res_api_alias.json() == data_v1
+
+
+def test_observability_gated_actions():
+ """Ensure observability actions are registered, gated, and fail closed in MVP mode."""
+ registry = load_action_registry()
+
+ action_reconcile = registry.get("observability_reconcile_incident")
+ assert action_reconcile is not None
+ assert action_reconcile.task_key == "observability_reconcile_incident"
+ assert action_reconcile.mcp_tool == "gitea_observability_reconcile_incident"
+
+ action_link = registry.get("observability_link_issue")
+ assert action_link is not None
+ assert action_link.task_key == "observability_link_issue"
+
+ # Preview returns mutation ledger
+ prev = preview_action("observability_reconcile_incident", provider="sentry", issue_id="101")
+ assert prev["action_id"] == "observability_reconcile_incident"
+ assert prev["enabled"] is False
+
+ # Execution fails closed in MVP mode
+ att = attempt_action("observability_reconcile_incident", provider="sentry", issue_id="101")
+ assert att["success"] is False
+ assert att["error"] == "action_disabled"
+
+
+def test_observability_authz_rbac():
+ """Test RBAC authorization for observability actions."""
+ principal = resolve_principal({})
+
+ # Check authorize decision
+ decision = authorize("observability_reconcile_incident", principal)
+ assert decision.action_id == "observability_reconcile_incident"
+ # Phase 4 action denies in Phase 1 runtime by default
+ assert decision.allowed is False
diff --git a/webui/app.py b/webui/app.py
index 2da41e2..3dddaa7 100644
--- a/webui/app.py
+++ b/webui/app.py
@@ -87,6 +87,11 @@ from webui.notifications import (
from webui.notification_views import render_notifications_page
from webui import request_service
from webui.request_views import render_requests_page
+from webui.observability_loader import (
+ load_observability_snapshot,
+ snapshot_to_dict as observability_snapshot_to_dict,
+)
+from webui.observability_views import render_observability_page
_READ_ONLY_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
_AUDIT_MUTATION_PATHS = frozenset({"/audit", "/api/audit"})
@@ -910,6 +915,19 @@ async def api_notifications(request: Request) -> JSONResponse:
data = notifications_snapshot_to_dict(snap)
return JSONResponse(data)
+
+async def observability_route(request: Request) -> HTMLResponse:
+ snap = load_observability_snapshot()
+ html_content = render_observability_page(snap)
+ return HTMLResponse(html_content)
+
+
+async def api_observability(request: Request) -> JSONResponse:
+ snap = load_observability_snapshot()
+ data = observability_snapshot_to_dict(snap)
+ return JSONResponse(data)
+
+
def _default_request_scope() -> dict[str, str]:
"""Resolve remote/org/repo from the project registry for request forms.
@@ -1075,6 +1093,9 @@ def create_app(*, bind_host: str | None = None) -> Starlette:
Route("/api/analytics", api_v1_analytics, methods=["GET"]),
Route("/api/v1/analytics", api_v1_analytics, methods=["GET"]),
Route("/api/v1/analytics/usage", api_v1_analytics_ingest, methods=["POST"]),
+ Route("/observability", observability_route, methods=["GET"]),
+ Route("/api/observability", api_observability, methods=["GET"]),
+ Route("/api/v1/observability", api_observability, methods=["GET"]),
Route("/audit", audit, methods=["GET", "POST"]),
Route("/api/audit", api_audit, methods=["GET", "POST"]),
Route("/worktrees", worktrees, methods=["GET"]),
diff --git a/webui/console_authz.py b/webui/console_authz.py
index 266d6b2..6d6d0f9 100644
--- a/webui/console_authz.py
+++ b/webui/console_authz.py
@@ -317,6 +317,29 @@ _ACTION_SPECS: tuple[ConsoleAction, ...] = (
phase=2,
summary="Run reconciler cleanup for merged or superseded PR branches.",
),
+ # #649: Phase 4 observability & incident bridge actions.
+ ConsoleAction(
+ action_id="observability_reconcile_incident",
+ task_key="observability_reconcile_incident",
+ action_class=CLASS_WRITE,
+ minimum_role=OPERATOR,
+ requires_confirmation=True,
+ dual_control=False,
+ break_glass=False,
+ phase=4,
+ summary="Trigger/reconcile durable Gitea issue creation from a provider incident.",
+ ),
+ ConsoleAction(
+ action_id="observability_link_issue",
+ task_key="observability_link_issue",
+ action_class=CLASS_WRITE,
+ minimum_role=OPERATOR,
+ requires_confirmation=True,
+ dual_control=False,
+ break_glass=False,
+ phase=4,
+ summary="Link a provider incident to an existing Gitea issue.",
+ ),
# #643: submit a work request — desired role, issue/PR, intent — and let
# the allocator reserve it. This is the one Phase 2 action whose execution
# path is actually implemented (``webui.request_service``), so it carries
diff --git a/webui/gated_actions.py b/webui/gated_actions.py
index 7e42861..a258b0e 100644
--- a/webui/gated_actions.py
+++ b/webui/gated_actions.py
@@ -185,6 +185,11 @@ def build_action_registry() -> ActionRegistry:
"console.rebind_session_worktree", "Rebind session worktree to verified lease."),
("system.reconcile_cleanups", "Reconcile cleanups", "reconcile_cleanups",
"console.reconcile_cleanups", "Run reconciler cleanup for merged or superseded PRs."),
+ # #649: Phase 4 observability & incident bridge actions.
+ ("observability_reconcile_incident", "Reconcile incident", "observability_reconcile_incident",
+ "gitea_observability_reconcile_incident", "Trigger or dry-run durable issue reconciliation for a provider incident."),
+ ("observability_link_issue", "Link incident issue", "observability_link_issue",
+ "gitea_observability_link_issue", "Link a provider incident to a Gitea tracking issue."),
)
actions = tuple(
GatedAction(
diff --git a/webui/nav.py b/webui/nav.py
index 2c2bdc3..6acbecc 100644
--- a/webui/nav.py
+++ b/webui/nav.py
@@ -73,6 +73,7 @@ NAV_GROUPS: tuple[NavGroup, ...] = (
)),
NavGroup("Insights", (
NavItem("/insights", "Insights", "stub"),
+ NavItem("/observability", "Observability"),
NavItem("/analytics", "Analytics"),
NavItem("/audit", "Audit"),
)),
diff --git a/webui/observability_loader.py b/webui/observability_loader.py
new file mode 100644
index 0000000..6793368
--- /dev/null
+++ b/webui/observability_loader.py
@@ -0,0 +1,275 @@
+"""Sentry/GlitchTip observability and incident correlation loader for the console (#649, Phase 4).
+
+Operators need to inspect provider connection status (Sentry/GlitchTip), error
+correlations, and durable Gitea issue linkage — without treating raw incidents
+as allocator work.
+
+ADR authority model:
+* Gitea owns work.
+* Providers (Sentry/GlitchTip) observe incidents.
+* Control-plane DB coordinates incident links.
+* The #612 bridge reconciles observations into durable Gitea issues.
+* The web console projects read-only state and gates mutations.
+
+Redaction boundary:
+* Provider auth tokens, DSNs, Authorization headers, and sensitive local file
+ paths are ALWAYS redacted before leaving this module.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from control_plane_db import ControlPlaneDB
+import sentry_incident_bridge
+from webui import console_redaction
+
+OBSERVABILITY_SCHEMA_VERSION = 1
+
+
+@dataclass(frozen=True)
+class ProviderHealth:
+ """Connection and health status of an observability provider."""
+
+ provider: str
+ base_url: str
+ org: str
+ project: str
+ configured: bool
+ status: str
+ bridge_enabled: bool
+ lookback: str
+ min_events_for_issue: int
+ self_hosted: bool
+ environment: str | None = None
+ credentials_present: bool = False
+
+ def to_dict(self) -> dict[str, Any]:
+ data = {
+ "provider": self.provider,
+ "base_url": self.base_url,
+ "org": self.org,
+ "project": self.project,
+ "configured": self.configured,
+ "status": self.status,
+ "bridge_enabled": self.bridge_enabled,
+ "lookback": self.lookback,
+ "min_events_for_issue": self.min_events_for_issue,
+ "self_hosted": self.self_hosted,
+ "environment": self.environment,
+ "credentials_present": self.credentials_present,
+ }
+ return console_redaction.redact_payload(data)
+
+
+@dataclass(frozen=True)
+class CorrelatedIncidentLink:
+ """One linked provider incident ↔ Gitea issue correlation record."""
+
+ link_id: int
+ provider: str
+ provider_base_url: str
+ provider_org: str
+ provider_project: str
+ provider_issue_id: str
+ provider_short_id: str | None
+ provider_permalink: str | None
+ fingerprint: str | None
+ gitea_org: str
+ gitea_repo: str
+ gitea_issue_number: int
+ linked_pr_numbers: list[int]
+ last_seen: str | None
+ event_count: int
+ created_at: str | None
+ updated_at: str | None
+
+ def to_dict(self) -> dict[str, Any]:
+ data = {
+ "link_id": self.link_id,
+ "provider": self.provider,
+ "provider_base_url": self.provider_base_url,
+ "provider_org": self.provider_org,
+ "provider_project": self.provider_project,
+ "provider_issue_id": self.provider_issue_id,
+ "provider_short_id": self.provider_short_id,
+ "provider_permalink": self.provider_permalink,
+ "fingerprint": self.fingerprint,
+ "gitea_org": self.gitea_org,
+ "gitea_repo": self.gitea_repo,
+ "gitea_issue_number": self.gitea_issue_number,
+ "linked_pr_numbers": self.linked_pr_numbers,
+ "last_seen": self.last_seen,
+ "event_count": self.event_count,
+ "created_at": self.created_at,
+ "updated_at": self.updated_at,
+ }
+ return console_redaction.redact_payload(data)
+
+
+@dataclass(frozen=True)
+class ObservabilitySnapshot:
+ """Read-only snapshot of observability provider status and incident correlations."""
+
+ schema_version: int
+ providers: list[ProviderHealth]
+ links: list[CorrelatedIncidentLink]
+ total_links: int
+ sentry_links_count: int
+ glitchtip_links_count: int
+ bridge_active: bool
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "schema_version": self.schema_version,
+ "providers": [p.to_dict() for p in self.providers],
+ "links": [link.to_dict() for link in self.links],
+ "metrics": {
+ "total_links": self.total_links,
+ "sentry_links_count": self.sentry_links_count,
+ "glitchtip_links_count": self.glitchtip_links_count,
+ "bridge_active": self.bridge_active,
+ },
+ }
+
+
+def load_provider_health(
+ provider_name: str = "sentry",
+ env: dict[str, str] | None = None,
+) -> ProviderHealth:
+ """Inspect configuration and connection health for an observability provider."""
+ source_env = dict(env if env is not None else os.environ)
+ if provider_name.lower() == "sentry":
+ config = sentry_incident_bridge.load_bridge_config(source_env)
+ token = sentry_incident_bridge.resolve_token(source_env)
+ has_token = bool(token)
+ configured = bool(config.org and config.project and has_token)
+
+ if not config.org or not config.project:
+ status = "not_configured"
+ elif not has_token:
+ status = "missing_token"
+ elif not config.bridge_enabled:
+ status = "disabled"
+ else:
+ status = "healthy"
+
+ return ProviderHealth(
+ provider="sentry",
+ base_url=config.base_url,
+ org=config.org or "unconfigured",
+ project=config.project or "unconfigured",
+ configured=configured,
+ status=status,
+ bridge_enabled=config.bridge_enabled,
+ lookback=config.lookback,
+ min_events_for_issue=config.min_events_for_issue,
+ self_hosted=not config.base_url.rstrip("/").endswith("sentry.io"),
+ environment=config.environment,
+ credentials_present=has_token,
+ )
+
+ # GlitchTip or fallback provider configuration
+ glitchtip_url = (source_env.get("GLITCHTIP_BASE_URL") or "https://glitchtip.prgs.cc").strip()
+ glitchtip_org = (source_env.get("GLITCHTIP_ORG") or "").strip()
+ glitchtip_proj = (source_env.get("GLITCHTIP_PROJECT") or "").strip()
+ glitchtip_token = (source_env.get("GLITCHTIP_AUTH_TOKEN") or "").strip()
+
+ has_token = bool(glitchtip_token)
+ configured = bool(glitchtip_org and glitchtip_proj and has_token)
+ status = "healthy" if configured else ("missing_token" if glitchtip_org and glitchtip_proj else "not_configured")
+
+ return ProviderHealth(
+ provider="glitchtip",
+ base_url=glitchtip_url,
+ org=glitchtip_org or "unconfigured",
+ project=glitchtip_proj or "unconfigured",
+ configured=configured,
+ status=status,
+ bridge_enabled=configured,
+ lookback="24h",
+ min_events_for_issue=2,
+ self_hosted=True,
+ environment=source_env.get("GLITCHTIP_ENVIRONMENT"),
+ credentials_present=has_token,
+ )
+
+
+def _parse_pr_numbers(raw: Any) -> list[int]:
+ if isinstance(raw, list):
+ return [int(x) for x in raw if str(x).isdigit()]
+ if isinstance(raw, str) and raw.strip():
+ import json
+ try:
+ parsed = json.loads(raw)
+ if isinstance(parsed, list):
+ return [int(x) for x in parsed if str(x).isdigit()]
+ except Exception:
+ pass
+ return []
+
+
+def load_observability_snapshot(
+ db: ControlPlaneDB | None = None,
+ env: dict[str, str] | None = None,
+) -> ObservabilitySnapshot:
+ """Build a read-only snapshot of observability connection health and incident links."""
+ sentry_health = load_provider_health("sentry", env)
+ glitchtip_health = load_provider_health("glitchtip", env)
+ providers = [sentry_health, glitchtip_health]
+
+ target_db = db or ControlPlaneDB()
+ raw_links = target_db.list_incident_links(limit=100)
+
+ links: list[CorrelatedIncidentLink] = []
+ sentry_cnt = 0
+ glitchtip_cnt = 0
+
+ for r in raw_links:
+ prov = (r.get("provider") or "sentry").lower()
+ if prov == "sentry":
+ sentry_cnt += 1
+ elif prov == "glitchtip":
+ glitchtip_cnt += 1
+
+ pr_nums = _parse_pr_numbers(r.get("linked_pr_numbers"))
+
+ links.append(
+ CorrelatedIncidentLink(
+ link_id=int(r.get("link_id", 0)),
+ provider=prov,
+ provider_base_url=r.get("provider_base_url") or "",
+ provider_org=r.get("provider_org") or "",
+ provider_project=r.get("provider_project") or "",
+ provider_issue_id=str(r.get("provider_issue_id") or ""),
+ provider_short_id=r.get("provider_short_id"),
+ provider_permalink=r.get("provider_permalink"),
+ fingerprint=r.get("fingerprint"),
+ gitea_org=r.get("gitea_org") or "Scaled-Tech-Consulting",
+ gitea_repo=r.get("gitea_repo") or "Gitea-Tools",
+ gitea_issue_number=int(r.get("gitea_issue_number", 0)),
+ linked_pr_numbers=pr_nums,
+ last_seen=r.get("last_seen"),
+ event_count=int(r.get("event_count", 1)),
+ created_at=r.get("created_at"),
+ updated_at=r.get("updated_at"),
+ )
+ )
+
+ bridge_active = any(p.bridge_enabled for p in providers)
+
+ return ObservabilitySnapshot(
+ schema_version=OBSERVABILITY_SCHEMA_VERSION,
+ providers=providers,
+ links=links,
+ total_links=len(links),
+ sentry_links_count=sentry_cnt,
+ glitchtip_links_count=glitchtip_cnt,
+ bridge_active=bridge_active,
+ )
+
+
+def snapshot_to_dict(snapshot: ObservabilitySnapshot) -> dict[str, Any]:
+ return snapshot.to_dict()
diff --git a/webui/observability_views.py b/webui/observability_views.py
new file mode 100644
index 0000000..29463fa
--- /dev/null
+++ b/webui/observability_views.py
@@ -0,0 +1,143 @@
+"""HTML view renderer for the Sentry/GlitchTip observability console (#649, Phase 4).
+
+Renders connection status widgets, error correlation links, and gated issue creation
+affordances over the read-only observability snapshot.
+"""
+
+from __future__ import annotations
+
+import html
+from typing import Any
+
+from webui.layout import render_page
+from webui.observability_loader import ObservabilitySnapshot, snapshot_to_dict
+
+
+def _badge(status: str) -> str:
+ st = (status or "").lower()
+ if st == "healthy":
+ return 'healthy'
+ if st == "disabled":
+ return 'disabled (dry-run)'
+ if st in {"missing_token", "not_configured"}:
+ return f'{html.escape(st)}'
+ return f'{html.escape(st)}'
+
+
+def _provider_card(p: dict[str, Any]) -> str:
+ name = html.escape(str(p.get("provider", "provider")).upper())
+ base_url = html.escape(str(p.get("base_url", "")))
+ org = html.escape(str(p.get("org", "")))
+ proj = html.escape(str(p.get("project", "")))
+ status_badge = _badge(str(p.get("status", "")))
+ min_events = p.get("min_events_for_issue", 2)
+ lookback = html.escape(str(p.get("lookback", "24h")))
+ bridge_enabled = "yes" if p.get("bridge_enabled") else "no"
+
+ return f"""
+
+
+
{name} Connection
+
{status_badge}
+
+
+ | Base URL: | {base_url} |
+ | Scope: | {org} / {proj} |
+ | Bridge Enabled: | {bridge_enabled} |
+ | Min Events for Issue: | {min_events} |
+ | Lookback Window: | {lookback} |
+
+
No providers configured.
"
+
+ links = data.get("links", [])
+ link_rows = []
+
+ for l in links:
+ prov = html.escape(str(l.get("provider", "")))
+ p_issue_id = html.escape(str(l.get("provider_issue_id", "")))
+ fingerprint = html.escape(str(l.get("fingerprint") or "—"))
+ g_issue_num = int(l.get("gitea_issue_number", 0))
+ g_org = html.escape(str(l.get("gitea_org", "")))
+ g_repo = html.escape(str(l.get("gitea_repo", "")))
+ g_issue_link = f'#{g_issue_num} ({g_org}/{g_repo})'
+ event_cnt = int(l.get("event_count", 1))
+ last_seen = html.escape(str(l.get("last_seen") or "—"))
+ short_id = html.escape(str(l.get("provider_short_id") or p_issue_id))
+
+ link_rows.append(f"""
+
+ {prov} |
+ {short_id}
id: {p_issue_id} |
+ {fingerprint} |
+ {g_issue_link} |
+ {event_cnt} |
+ {last_seen} |
+
+ """)
+
+ table_body = "".join(link_rows) if link_rows else '| No correlated incident links stored. Bridge operates under dry-run default. |
'
+
+ metrics = data.get("metrics", {})
+ total_links = metrics.get("total_links", 0)
+ sentry_cnt = metrics.get("sentry_links_count", 0)
+ glitchtip_cnt = metrics.get("glitchtip_links_count", 0)
+
+ body_html = f"""
+ Observability & Incident Bridge (#649)
+ Read-only console surface for Sentry/GlitchTip provider connections, error correlation,
+ and durable Gitea issue linkage.
+
+
+ ADR Authority Model: Gitea records durable issue history. Control-plane DB coordinates incident links.
+ Sentry/GlitchTip observe errors. Raw monitoring incidents are never assignable control-plane work items.
+ Durable issue creation is gated and dry-runable via the #612 bridge APIs.
+
+
+ Provider Connections
+
+ {provider_cards}
+
+
+
+
Correlated Incidents ({total_links})
+
+ Sentry: {sentry_cnt}
+ GlitchTip: {glitchtip_cnt}
+
+
+
+
+ | Provider |
+ Incident ID |
+ Fingerprint |
+ Gitea Issue Link |
+ Events |
+ Last Seen |
+
+
+
+ {table_body}
+
+
+
+
+
Reconcile & Link Controls (Gated)
+
+ Create or reconcile durable Gitea issues from provider observations using the #612 incident bridge:
+
+
mcp call gitea_observability_reconcile_incident --provider sentry --apply false
+
- -w`. | `security(1)` is a macOS binary reading the calling user's login keychain. It does not exist on a Linux host and would be the wrong identity even on a shared Mac. | cannot be remote | #933 |
+| C2 | `gitea_config.py:974` | `resolve_token(profile, keychain_lookup=_keychain_token)` dispatches on `auth.type` of `env` or `keychain`, defaulting the lookup to C1. | The injectable `keychain_lookup` parameter is the existing seam; a remote credential provider plugs in here without changing the dispatch. | needs a seam | #933 |
+| C3 | `gitea_config.py:1015` | `keychain_auth(item_id)` constructs the `{"type": "keychain", "id": ...}` reference stored in profiles. | The reference type itself encodes "macOS keychain" into persisted config. A remote provider needs a new auth reference type, not a new value of this one. | needs a replacement | #933 |
+| C4 | `mcp_daemon_guard.py:440` | `assert_keychain_access_allowed()` fails closed for git-credential keychain fill outside a sanctioned daemon, with an operator opt-out env var. | The gate protects a mechanism that will not exist remotely. Its replacement must gate the *credential provider* call, not the keychain call, or the protection silently lapses. | needs a replacement | #933 |
+| C5 | `sentry_incident_bridge.py:190` | `resolve_token(env)` resolves the Sentry token from an injected env mapping with no keychain path. | Already host-neutral; it is the shape the Gitea credential path should converge on. | portable as written | #933 |
+| C6 | `gitea_mcp_server.py:18469` | The profile-audit tool calls `gitea_config.resolve_token(p)` for every configured profile to report "credentials present" without networking. | On a remote host this would materialize every principal's credential inside one process — an audit surface that becomes a credential-aggregation risk. | needs a seam | #933 |
+
+## 5. Runtime freshness
+
+The mutation gate is defined as "the commit this process started at matches the checkout on
+this disk, and both match live master". Two of those three terms are local-disk facts.
+
+| ID | Anchor | Assumes today | Observes remotely | Class | Owner |
+| -- | ------ | ------------- | ----------------- | ----- | ----- |
+| F1 | `master_parity_gate.py:168` | `capture_startup_parity(root)` reads git `HEAD` from the server's own root once at startup and returns it as the baseline. | A remote host carries a deployed artifact, not the operator's checkout. Its `HEAD` says nothing about the operator's working tree, which is the thing the gate exists to protect. | cannot be remote | #935 |
+| F2 | `master_parity_gate.py:255` | `mutation_safe = determinable and in_parity and live_known and not live_stale` — a conjunction of two local-HEAD comparisons and one live-remote comparison. | Two of the three conjuncts lose meaning, so the whole verdict does. A remote deployment needs a redefined, testable freshness predicate rather than this one relocated. | needs a replacement | #935 |
+| F3 | `master_parity_gate.py:164` | The live-remote head is probed and cached per `(root, remote, branch)`, keyed on the local root. | The live-remote probe is the one conjunct that survives; it needs a key that is not the operator's filesystem path. | needs a seam | #935 |
+| F4 | `gitea_mcp_server.py:18262` | `gitea_assess_master_parity` publishes `startup_head` / `local_head` / `live_remote_head` / `mutation_safe` as the authoritative mutation-safety verdict. | The tool's contract is consumed by every mutation caller and by the operator; it must keep its shape while its semantics are redefined, or every consumer breaks at once. | needs a replacement | #935 |
+| F5 | `gitea_mcp_server.py:23054` | Falls back to `_process_boot_head_sha` — the commit this process booted at — when the parity payload has no `startup_head`. | Same defect as F1, in a fallback path that is easy to miss when F1 is fixed. | needs a seam | #935 |
+| F6 | `gitea_mcp_server.py:20615` | Staleness is also inferred from `os.path.getmtime()` of `gitea_mcp_server.py` under `PROJECT_ROOT` (`gitea_mcp_server.py:20611`), compared against peer process start times. | File mtime on a deployed artifact tracks the deploy, not the operator's edits, and the peer start times it is compared against come from the unavailable process table (P4). | cannot be remote | #935 |
+
+## 6. Local filesystem
+
+Author and reviewer tools act directly on the operator's checkout.
+
+| ID | Anchor | Assumes today | Observes remotely | Class | Owner |
+| -- | ------ | ------------- | ----------------- | ----- | ----- |
+| L1 | `gitea_mcp_server.py:10122` | `gitea_bootstrap_author_issue_worktree` creates and binds a git worktree on the server's own disk. | The remote host has no operator checkout to add a worktree to. Executing this remotely would act on the wrong disk while reporting success. | cannot be remote | #936 |
+| L2 | `gitea_mcp_server.py:190` | `ACTIVE_WORKTREE_ENV = "GITEA_ACTIVE_WORKTREE"` and `AUTHOR_WORKTREE_ENV` (`gitea_mcp_server.py:191`) carry the active workspace as process-wide environment. | Process-wide workspace state cannot represent per-session workspaces on a shared endpoint. | needs a replacement | #936 |
+| L3 | `gitea_mcp_server.py:9801` | Binding a worktree writes `os.environ["GITEA_AUTHOR_WORKTREE"]` and `os.environ["GITEA_ACTIVE_WORKTREE"]` (`gitea_mcp_server.py:9802`), mutating global process state. | One session's bind would silently retarget every other concurrent session in the same process. This is a correctness bug the moment concurrency is real. | needs a replacement | #936 |
+| L4 | `reviewer_inventory_worktree.py:48` | `_BRANCHES_WORKTREE_RE = re.compile(r"\bbranches/", re.I)` requires review worktree paths to sit under `branches/`. | A path convention on the operator's machine, asserted as a validation rule. It needs to become a property of a declared workspace, not a substring test. | needs a seam | #936 |
+| L5 | `stable_control_runtime.py:54` | `DEV_WORKTREE_SEGMENT = "branches"` classifies a process root as a development worktree by path segment. | Same class of assumption as L4, on the runtime-classification side. | needs a seam | #936 |
+| L6 | `mcp_server.py:42` | `check_conflict_markers()` runs at import and `os.walk`s the install directory for unresolved conflict markers, `sys.exit(1)` on a hit. | On a remote host it scans a deployed artifact, which by construction never has conflict markers — so the guard passes trivially and stops protecting the thing it was written to protect. | needs a replacement | #936 |
+| L7 | `role_session_router.py:487` | `check_mid_merge()` reports infra-stop from `.git/MERGE_HEAD`, `rebase-merge`, `rebase-apply` and a source conflict scan under the server's project root. | Same inversion as L6: it would report the deployment's git state, not the operator's. | needs a replacement | #936 |
+| L8 | `author_issue_bootstrap.py:996` | Enumerates worktrees with `git -C worktree list --porcelain`. | Requires a real local clone with real worktrees; there is nothing equivalent to enumerate remotely. | cannot be remote | #936 |
+| L9 | `mcp_server.py:10` | Redirects `sys.stderr` to the fixed path `/tmp/mcp_server_stderr.log` outside pytest. | A single fixed `/tmp` path is shared by every concurrent server on a host and is not a deployment's logging surface. | needs a replacement | #938 |
+| L10 | `gitea_mcp_server.py:2314` | `ISSUE_LOCK_FILE = "/tmp/gitea_issue_lock.json"` — the legacy single global lock slot. | One global `/tmp` slot per host cannot represent concurrent remote sessions and is world-visible on a shared machine. | needs a replacement | #937 |
+| L11 | `issue_lock_provenance.py:14` | `ISSUE_LOCK_FILE = os.environ.get("GITEA_ISSUE_LOCK_FILE", "/tmp/gitea_issue_lock.json")` keeps the same `/tmp` default in the provenance path. | Same as L10; the env override is a local escape hatch, not a remote design. | needs a replacement | #937 |
+
+## 7. Durable state
+
+Locks, leases, session state, and the control-plane database live in the operator's home
+directory and are keyed on local PIDs.
+
+| ID | Anchor | Assumes today | Observes remotely | Class | Owner |
+| -- | ------ | ------------- | ----------------- | ----- | ----- |
+| S1 | `issue_lock_store.py:26` | `DEFAULT_LOCK_DIR = ~/.cache/gitea-tools/issue-locks` — per-issue lock files under one user's home. | A shared endpoint has no single operator home; per-user paths make locks invisible across sessions and hosts. | needs a replacement | #937 |
+| S2 | `issue_lock_store.py:83` | `session_pointer_path()` names the session pointer file `session-.json`. | Many sessions share one PID on a remote server, so the pointer collapses to a single slot and sessions overwrite each other. | cannot be remote | #937 |
+| S3 | `issue_lock_store.py:98` | `is_process_alive(pid)` decides lock liveness by probing the local process table. | A PID recorded by one host is meaningless on another, and may coincidentally match a live unrelated process. | cannot be remote | #937 |
+| S4 | `issue_lock_store.py:213` | Lock records stamp `session_pid` and `pid` from `os.getpid()`. | The recorded identity no longer distinguishes sessions; ownership checks silently pass for the wrong caller. | needs a replacement | #937 |
+| S5 | `mcp_session_state.py:27` | `DEFAULT_STATE_DIR = ~/.cache/gitea-tools/session-state`, mode `0o700`. | Same home-directory coupling as S1, for review decision locks and workflow proofs. | needs a replacement | #937 |
+| S6 | `mcp_session_state.py:559` | Session bodies stamp `session_pid` and `writer_pid` from `os.getpid()` (`mcp_session_state.py:560`). | Writer attribution collapses across concurrent sessions in one process. | needs a replacement | #937 |
+| S7 | `control_plane_db.py:47` | `DEFAULT_DB_PATH = ~/.cache/gitea-tools/control-plane/control_plane.sqlite3`. | A per-user SQLite file is not reachable by, or safe for, multiple remote sessions or multiple hosts. | needs a replacement | #937 |
+| S8 | `control_plane_db.py:386` | `sqlite3.connect(self.db_path, timeout=30)` — single-writer file locking tuned for one local process. | SQLite's write lock does not extend across hosts and degrades sharply under real concurrency; the store needs a concurrency-safe backend. | needs a replacement | #937 |
+| S9 | `control_plane_db.py:1145` | Lease rows record `owner_pid` defaulting to `os.getpid()` (also `control_plane_db.py:2039`). | PID-keyed lease ownership is unusable across hosts and ambiguous within one shared process. | cannot be remote | #937 |
+| S10 | `mcp_daemon_guard.py:53` | `_DEFAULT_SESSION_STATE_DIR` is pinned once at transport bind so a later `GITEA_MCP_SESSION_STATE_DIR` change cannot manufacture a second authority domain (#695 AC2). | The single-authority-domain invariant is exactly right and must be preserved; only its backing location needs to move. | needs a seam | #937 |
+| S11 | `gitea_mcp_server.py:11875` | Reviewer-lease reclaim reads `owner_pid_alive` from the lease freshness record to decide whether an owner is dead. | Consumes S3/S9; a false "owner alive" or "owner dead" here reclaims or refuses a live lease. This is the highest-consequence consumer of PID liveness. | cannot be remote | #937 |
+
+---
+
+## Summary
+
+### Entries per category
+
+| Category | Entries |
+| -------- | ------: |
+| 1. Transport bind | 9 |
+| 2. Launch provenance | 12 |
+| 3. Role binding | 7 |
+| 4. Credentials | 6 |
+| 5. Runtime freshness | 6 |
+| 6. Local filesystem | 11 |
+| 7. Durable state | 11 |
+| **Total** | **62** |
+
+No category is empty, so no "this category has no coupling" justification is required.
+
+### Entries per classification
+
+| Classification | Entries |
+| -------------- | ------: |
+| portable as written | 5 |
+| needs a seam | 16 |
+| needs a replacement | 26 |
+| cannot be remote | 15 |
+| **Total** | **62** |
+
+### Category × classification
+
+| Category | portable | seam | replacement | cannot | Total |
+| -------- | -------: | ---: | ----------: | -----: | ----: |
+| 1. Transport bind | 4 | 4 | 1 | 0 | 9 |
+| 2. Launch provenance | 0 | 2 | 5 | 5 | 12 |
+| 3. Role binding | 0 | 3 | 3 | 1 | 7 |
+| 4. Credentials | 1 | 2 | 2 | 1 | 6 |
+| 5. Runtime freshness | 0 | 2 | 2 | 2 | 6 |
+| 6. Local filesystem | 0 | 2 | 7 | 2 | 11 |
+| 7. Durable state | 0 | 1 | 6 | 4 | 11 |
+| **Total** | **5** | **16** | **26** | **15** | **62** |
+
+### Entries per epic child
+
+Every child from 2 through 10 is named by at least one entry, and every entry names exactly
+one child.
+
+| Child | Issue | Title | Entries | IDs |
+| ----: | ----- | ----- | ------: | --- |
+| 2 | #931 | Transport-neutral bind seam | 9 | T1–T9 |
+| 3 | #932 | Per-request principal resolution | 7 | R1–R7 |
+| 4 | #933 | Server-side credential provider | 6 | C1–C6 |
+| 5 | #934 | Remote-session provenance | 9 | P1–P9 |
+| 6 | #935 | Redefined master-parity gate | 6 | F1–F6 |
+| 7 | #936 | Local-filesystem vs remotable tool split | 8 | L1–L8 |
+| 8 | #937 | Concurrency-safe session, lock, and lease state | 13 | L10, L11, S1–S11 |
+| 9 | #938 | Authenticated remote MCP endpoint | 2 | P10, L9 |
+| 10 | #939 | Dual-run cutover and rollback | 2 | P11, P12 |
+| | | **Total** | **62** | |
+
+## Notes for downstream children
+
+- **The three highest-risk entries are P5, F2, and S11.** Each is a guard that does not
+ merely stop working remotely — it inverts. P5 turns concurrency into a reported fault,
+ F2 returns a verdict computed from terms that no longer mean anything, and S11 reclaims
+ or refuses leases on a PID-liveness answer that is wrong rather than unknown. A gate that
+ fails open while still reporting green is worse than one that fails to start.
+- **T4, T5, T7, T8, and C5 are the portable core.** They show the target shape: predicates
+ over injected inputs, with no reference to the host, the process table, or the operator's
+ disk.
+- **The keychain seam already exists** at C2 (`resolve_token`'s injectable `keychain_lookup`).
+ #933 should widen that seam rather than introduce a parallel path, and must remember C4 —
+ the guard protecting the old mechanism has to be re-pointed, or the protection lapses
+ silently when the mechanism is replaced.
+- **`branches/` appears as a validation rule in at least two independent places** (L4, L5).
+ Path-substring conventions tend to have more copies than expected; #936 should re-grep
+ rather than trust this list to be exhaustive for that specific pattern.
From a09c485fc0eba75b35986a1833dba986be6c2101 Mon Sep 17 00:00:00 2001
From: jcwalker3
Date: Sun, 26 Jul 2026 05:00:09 -0500
Subject: [PATCH 09/18] fix(scope): wire author bootstrap scope into workflow
scope guard (Closes #941)
PR #926 (#892) taught create_issue_bootstrap.bootstrap_permits_control_checkout
to accept task_scope=author_issue_bootstrap and wired that canonical decision
into the #274 branches-only enforcer and the #604 anti-stomp preflight. A third
enforcement path was left unwired.
workflow_scope_guard kept its own copy of the clean-root author decision, gated
on create_issue_bootstrap.is_create_issue_task -- a task-name allowlist that
never contained bootstrap_author_issue_worktree. The real call path
gitea_bootstrap_author_issue_worktree
-> verify_preflight_purity
-> _enforce_issue_scope_guard
-> workflow_scope_guard.assess_production_mutation_guards
therefore raised ProductionGuardError(missing_issue_worktree) before
assess_author_issue_bootstrap was ever consulted, leaving the #892 deadlock
partially present and blocking issue #931.
Changes:
* workflow_scope_guard.assess_root_source_mutation accepts the server-derived
bootstrap_assessment and, for the clean-root author case, consults the
canonical bootstrap_permits_control_checkout decision instead of a local
task-name allowlist. The create_issue arm is unchanged.
* workflow_scope_guard.assess_production_mutation_guards forwards the evidence.
* _enforce_issue_scope_guard accepts and threads the same assessment the #274
and #604 guards already consume, so all three judge identical evidence, and
waives the pre-ownership issue-lock requirement for the bootstrap task via
that same canonical decision rather than a second task-name allowlist.
* verify_preflight_purity passes the once-computed assessment at both sites.
The waiver cannot widen: the predicate fails closed on missing, malformed,
cross-scope, dirty, drifted, or wrongly bound evidence, so ordinary author
source and test mutation from the control checkout stays forbidden and the
#274/#604/#618/#683 protections are unchanged.
Regression: tests/test_issue_941_scope_guard_bootstrap_wiring.py drives the
real enforcer rather than the authorization helper in isolation, which is why
#892's own predicate tests passed while the live bootstrap stayed blocked.
Closes #941
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
gitea_mcp_server.py | 33 +-
..._issue_941_scope_guard_bootstrap_wiring.py | 346 ++++++++++++++++++
workflow_scope_guard.py | 31 +-
3 files changed, 408 insertions(+), 2 deletions(-)
create mode 100644 tests/test_issue_941_scope_guard_bootstrap_wiring.py
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index ed25bfd..f3f6edc 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -1546,6 +1546,7 @@ def verify_preflight_purity(
task=task,
target_issue_number=target_issue_number,
require_author_lock=require_author_lock,
+ bootstrap_assessment=bootstrap_assessment,
)
# #604: common anti-stomp preflight after legacy + #683 enforcers.
_run_anti_stomp_preflight(
@@ -1585,6 +1586,7 @@ def verify_preflight_purity(
task=task,
target_issue_number=target_issue_number,
require_author_lock=require_author_lock,
+ bootstrap_assessment=bootstrap_assessment,
)
if force_anti_stomp:
_run_anti_stomp_preflight(
@@ -1652,8 +1654,15 @@ def _enforce_issue_scope_guard(
task: str | None = None,
target_issue_number: int | None = None,
require_author_lock: bool = False,
+ bootstrap_assessment: object = _BOOTSTRAP_UNSET,
) -> None:
- """#683: fail closed on missing/out-of-scope issue ownership for mutations."""
+ """#683: fail closed on missing/out-of-scope issue ownership for mutations.
+
+ #941: the shared bootstrap assessment is threaded in so this guard judges
+ the author issue-worktree bootstrap on the same server-derived evidence as
+ the #274 branches-only and #604 anti-stomp guards. Callers that supply
+ none fall back to computing it here, which preserves behaviour.
+ """
ctx = _resolve_namespace_mutation_context(worktree_path)
workspace = ctx["workspace_path"]
git_state = issue_lock_worktree.read_worktree_git_state(workspace)
@@ -1703,11 +1712,32 @@ def _enforce_issue_scope_guard(
import create_issue_bootstrap as _cib
is_create_issue = _cib.is_create_issue_task(task)
+ # #941: consume the caller-computed bootstrap assessment when one was
+ # threaded in, so this guard and the #274/#604 guards judge identical
+ # evidence. Falling back preserves behaviour for callers that supply none.
+ bootstrap = (
+ _create_issue_bootstrap_assessment(task, worktree_path)
+ if bootstrap_assessment is _BOOTSTRAP_UNSET
+ else bootstrap_assessment
+ )
+ # #941: the author issue-worktree bootstrap is pre-ownership for the same
+ # reason create_issue is — it exists to break the lock<->worktree cycle, so
+ # no owning lock can exist yet. The exemption is granted by the canonical
+ # shared decision over server-derived evidence, never by a task-name list,
+ # and fails closed on missing, malformed, cross-scope, dirty, drifted, or
+ # wrongly bound evidence.
+ bootstrap_waives_ownership = _cib.bootstrap_permits_control_checkout(
+ bootstrap,
+ task=task,
+ workspace_path=workspace,
+ canonical_repo_root=ctx["canonical_repo_root"],
+ )
require_lock = bool(require_author_lock) or (
authorish
and workflow_scope_guard.production_guards_forced()
and role == "author"
and not is_create_issue
+ and not bootstrap_waives_ownership
)
assessment = workflow_scope_guard.assess_production_mutation_guards(
workspace_path=workspace,
@@ -1720,6 +1750,7 @@ def _enforce_issue_scope_guard(
require_author_lock=require_lock,
in_test_mode=_preflight_in_test_mode(),
mutation_task=task,
+ bootstrap_assessment=bootstrap,
)
workflow_scope_guard.raise_if_blocked(assessment)
diff --git a/tests/test_issue_941_scope_guard_bootstrap_wiring.py b/tests/test_issue_941_scope_guard_bootstrap_wiring.py
new file mode 100644
index 0000000..f4b7351
--- /dev/null
+++ b/tests/test_issue_941_scope_guard_bootstrap_wiring.py
@@ -0,0 +1,346 @@
+"""Regression: author bootstrap scope reaches workflow_scope_guard (#941).
+
+PR #926 (#892) made ``bootstrap_permits_control_checkout`` accept
+``task_scope=author_issue_bootstrap`` and wired that canonical decision into
+the #274 branches-only enforcer and the #604 anti-stomp preflight. A third
+enforcement path was left unwired.
+
+``workflow_scope_guard.assess_root_source_mutation`` kept its own copy of the
+clean-root author decision, gated on ``create_issue_bootstrap.is_create_issue_task``
+— a task-name allowlist that never contained ``bootstrap_author_issue_worktree``.
+So the real call path
+
+ gitea_bootstrap_author_issue_worktree
+ -> verify_preflight_purity
+ -> _enforce_issue_scope_guard
+ -> workflow_scope_guard.assess_production_mutation_guards
+
+raised ProductionGuardError(missing_issue_worktree) before
+``assess_author_issue_bootstrap`` was ever consulted.
+
+These tests drive the real enforcer, not the authorization helper in
+isolation. A helper-only test cannot observe this defect: #892's own predicate
+tests all passed while the live bootstrap stayed blocked.
+"""
+
+from __future__ import annotations
+
+import os
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+
+import author_issue_bootstrap as aib
+import create_issue_bootstrap as cib
+import workflow_scope_guard
+
+BOOTSTRAP_TASK = "bootstrap_author_issue_worktree"
+BOOTSTRAP_TOOL = "gitea_bootstrap_author_issue_worktree"
+
+
+def _make_control_repo(tmp: str) -> tuple[str, str]:
+ """Create a clean control checkout on master and return (path, head)."""
+ repo = os.path.join(tmp, "repo")
+ os.makedirs(os.path.join(repo, "branches"))
+ subprocess.check_call(
+ ["git", "init", "-b", "master", repo],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ subprocess.check_call(
+ [
+ "git", "-C", repo,
+ "-c", "user.email=t@t", "-c", "user.name=t",
+ "commit", "--allow-empty", "-m", "init",
+ ],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ head = subprocess.check_output(
+ ["git", "-C", repo, "rev-parse", "HEAD"], text=True
+ ).strip()
+ return repo, head
+
+
+def _assessment(
+ repo: str,
+ head: str,
+ *,
+ task: str = BOOTSTRAP_TASK,
+ porcelain: str = "",
+ remote: str | None = None,
+) -> dict:
+ return aib.assess_author_issue_bootstrap(
+ workspace_path=repo,
+ canonical_repo_root=repo,
+ current_branch="master",
+ head_sha=head,
+ porcelain_status=porcelain,
+ remote_master_sha=head if remote is None else remote,
+ task=task,
+ )
+
+
+class _ControlCheckoutHarness(unittest.TestCase):
+ """Drive the real server guard against a temporary clean control checkout."""
+
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self._tmp.cleanup)
+ self.repo, self.head = _make_control_repo(self._tmp.name)
+
+ # #683 force-on: production guards must execute under pytest.
+ patcher = mock.patch.dict(
+ os.environ,
+ {workflow_scope_guard.FORCE_PRODUCTION_GUARDS_ENV: "1"},
+ )
+ patcher.start()
+ self.addCleanup(patcher.stop)
+
+ def _enforce(
+ self,
+ task: str,
+ *,
+ porcelain: str = "",
+ assessment: object = "auto",
+ role_kind: str = "author",
+ ):
+ """Call the real _enforce_issue_scope_guard for *task*."""
+ import gitea_mcp_server as srv
+
+ if assessment == "auto":
+ assessment = _assessment(
+ self.repo, self.head, task=task, porcelain=porcelain
+ )
+
+ ctx = {
+ "workspace_path": self.repo,
+ "canonical_repo_root": self.repo,
+ "workspace_role_kind": role_kind,
+ "workspace_binding_source": "process_project_root",
+ }
+ git_state = {
+ "current_branch": "master",
+ "head_sha": self.head,
+ "porcelain_status": porcelain,
+ }
+
+ with mock.patch.object(
+ srv, "_resolve_namespace_mutation_context", return_value=ctx
+ ), mock.patch.object(
+ srv.issue_lock_worktree,
+ "read_worktree_git_state",
+ return_value=git_state,
+ ), mock.patch.object(
+ srv,
+ "_session_issue_lock_snapshot",
+ return_value={
+ "locked_issue_number": None,
+ "lock_branch_name": None,
+ "worktrees_match": False,
+ },
+ ), mock.patch.object(
+ srv, "_actual_profile_role", return_value=role_kind
+ ), mock.patch.object(
+ srv, "_effective_workspace_role", return_value=role_kind
+ ), mock.patch.object(
+ srv, "_create_issue_bootstrap_assessment", return_value=assessment
+ ):
+ srv._enforce_issue_scope_guard(None, task=task)
+
+
+class TestRealPathBootstrapReachesGuard(_ControlCheckoutHarness):
+ """The defect and its fix, observed through the real enforcer."""
+
+ def test_bootstrap_task_passes_scope_guard_from_clean_control(self):
+ # Pre-fix this raises ProductionGuardError(missing_issue_worktree)
+ # because the guard consulted a task-name allowlist instead of the
+ # canonical authorization decision.
+ self._enforce(BOOTSTRAP_TASK)
+
+ def test_bootstrap_tool_alias_passes_scope_guard(self):
+ self._enforce(BOOTSTRAP_TOOL)
+
+ def test_guard_consults_canonical_predicate(self):
+ """The guard must reach bootstrap_permits_control_checkout, not a name list."""
+ real = cib.bootstrap_permits_control_checkout
+ seen: list[str | None] = []
+
+ def _spy(assessment, *, task, workspace_path, canonical_repo_root):
+ seen.append(task)
+ return real(
+ assessment,
+ task=task,
+ workspace_path=workspace_path,
+ canonical_repo_root=canonical_repo_root,
+ )
+
+ with mock.patch.object(
+ cib, "bootstrap_permits_control_checkout", side_effect=_spy
+ ):
+ self._enforce(BOOTSTRAP_TASK)
+
+ self.assertIn(
+ BOOTSTRAP_TASK,
+ seen,
+ "workflow_scope_guard did not consult the canonical bootstrap "
+ "authorization decision",
+ )
+
+
+class TestFailClosedOnBadEvidence(_ControlCheckoutHarness):
+ """Missing, malformed, or mismatched scope evidence must still block."""
+
+ def _assert_blocked(self, **kwargs):
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce(BOOTSTRAP_TASK, **kwargs)
+
+ def test_missing_assessment_fails_closed(self):
+ self._assert_blocked(assessment=None)
+
+ def test_malformed_assessment_fails_closed(self):
+ self._assert_blocked(assessment={"allowed": True})
+
+ def test_non_dict_assessment_fails_closed(self):
+ self._assert_blocked(assessment="allowed")
+
+ def test_wrong_task_scope_fails_closed(self):
+ bad = dict(_assessment(self.repo, self.head))
+ bad["task_scope"] = "create_issue_only"
+ self._assert_blocked(assessment=bad)
+
+ def test_nonempty_reasons_fail_closed(self):
+ bad = dict(_assessment(self.repo, self.head), reasons=["note"])
+ self._assert_blocked(assessment=bad)
+
+ def test_mismatched_base_tips_fail_closed(self):
+ bad = dict(_assessment(self.repo, self.head))
+ bad["remote_master_sha"] = "b" * 40
+ self._assert_blocked(assessment=bad)
+
+ def test_unverified_base_tips_fail_closed(self):
+ bad = dict(_assessment(self.repo, self.head), base_tips_verified=False)
+ self._assert_blocked(assessment=bad)
+
+ def test_mismatched_workspace_binding_fails_closed(self):
+ bad = dict(_assessment(self.repo, self.head))
+ bad["workspace_path"] = os.path.join(self.repo, "elsewhere")
+ self._assert_blocked(assessment=bad)
+
+ def test_mismatched_repo_root_binding_fails_closed(self):
+ bad = dict(_assessment(self.repo, self.head))
+ bad["canonical_repo_root"] = os.path.join(self.repo, "other-root")
+ self._assert_blocked(assessment=bad)
+
+ def test_blocked_assessment_fails_closed(self):
+ bad = dict(_assessment(self.repo, self.head), block=True, allowed=False)
+ self._assert_blocked(assessment=bad)
+
+
+class TestOrdinaryControlCheckoutMutationStillForbidden(_ControlCheckoutHarness):
+ """The waiver must not leak to ordinary author work."""
+
+ def test_ordinary_author_task_still_blocked(self):
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce("commit_files", assessment=None)
+
+ def test_lock_issue_still_blocked_from_control(self):
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce("lock_issue", assessment=None)
+
+ def test_bootstrap_assessment_cannot_license_other_task(self):
+ # Cross-task smuggling: valid bootstrap evidence must not waive a
+ # different author mutation.
+ good = _assessment(self.repo, self.head)
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce("commit_files", assessment=good)
+
+ def test_dirty_control_checkout_still_blocked_for_bootstrap(self):
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce(BOOTSTRAP_TASK, porcelain=" M gitea_mcp_server.py\n")
+
+
+class TestCreateIssueBehaviorUnchanged(_ControlCheckoutHarness):
+ """#749 create_issue keeps its own sanctioned path."""
+
+ def test_create_issue_still_allowed_from_clean_control(self):
+ self._enforce("create_issue", assessment=None)
+
+ def test_create_issue_tool_alias_still_allowed(self):
+ self._enforce("gitea_create_issue", assessment=None)
+
+ def test_create_issue_blocked_when_control_dirty(self):
+ with self.assertRaises(workflow_scope_guard.ProductionGuardError):
+ self._enforce(
+ "create_issue",
+ porcelain=" M gitea_mcp_server.py\n",
+ assessment=None,
+ )
+
+
+class TestGuardUnitLevelWiring(unittest.TestCase):
+ """assess_root_source_mutation itself must accept and honour the evidence."""
+
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self._tmp.cleanup)
+ self.repo, self.head = _make_control_repo(self._tmp.name)
+ patcher = mock.patch.dict(
+ os.environ,
+ {workflow_scope_guard.FORCE_PRODUCTION_GUARDS_ENV: "1"},
+ )
+ patcher.start()
+ self.addCleanup(patcher.stop)
+
+ def _assess(self, *, task=BOOTSTRAP_TASK, bootstrap_assessment="auto"):
+ if bootstrap_assessment == "auto":
+ bootstrap_assessment = _assessment(self.repo, self.head, task=task)
+ return workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ porcelain_status="",
+ current_branch="master",
+ role_kind="author",
+ mutation_task=task,
+ bootstrap_assessment=bootstrap_assessment,
+ )
+
+ def test_valid_evidence_unblocks(self):
+ result = self._assess()
+ self.assertFalse(result["block"])
+ self.assertIsNone(result["blocker_kind"])
+
+ def test_absent_evidence_blocks(self):
+ result = self._assess(bootstrap_assessment=None)
+ self.assertTrue(result["block"])
+ self.assertEqual(
+ result["blocker_kind"], workflow_scope_guard.BLOCKER_MISSING_WORKTREE
+ )
+
+ def test_reconciler_exemption_preserved(self):
+ result = workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ porcelain_status="",
+ current_branch="master",
+ role_kind="reconciler",
+ mutation_task=BOOTSTRAP_TASK,
+ )
+ self.assertFalse(result["block"])
+
+ def test_signature_accepts_evidence_without_it_being_required(self):
+ # Callers that supply no evidence keep the pre-existing behaviour.
+ result = workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ porcelain_status="",
+ current_branch="master",
+ role_kind="author",
+ mutation_task="create_issue",
+ )
+ self.assertFalse(result["block"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/workflow_scope_guard.py b/workflow_scope_guard.py
index 3996102..91ad4e6 100644
--- a/workflow_scope_guard.py
+++ b/workflow_scope_guard.py
@@ -279,6 +279,7 @@ def assess_root_source_mutation(
locked_issue_number: int | None = None,
role_kind: str | None = None,
mutation_task: str | None = None,
+ bootstrap_assessment: Any | None = None,
) -> dict[str, Any]:
"""Fail closed for diagnostic/source edits on the control/root checkout.
@@ -286,6 +287,13 @@ def assess_root_source_mutation(
tracked source/test files on the control checkout always block, including
temporary/diagnostic/test-only intent.
+ #941: ``bootstrap_author_issue_worktree`` is judged by the canonical
+ ``create_issue_bootstrap.bootstrap_permits_control_checkout`` decision over
+ *bootstrap_assessment* — the same server-derived evidence the #274 and
+ #604 guards consume — instead of a task-name allowlist local to this
+ module. Evidence that is absent, malformed, wrongly scoped, or bound to
+ another workspace leaves the ordinary block in force.
+
#749: ``create_issue`` is a pure remote mutation with no local tree write.
When *mutation_task* is create_issue and the control checkout has no dirty
source/test files, the missing-worktree signal is suppressed so the
@@ -336,6 +344,19 @@ def assess_root_source_mutation(
if _cib is not None and _cib.is_create_issue_task(mutation_task):
# #749: clean-root create_issue is the sanctioned bootstrap path.
create_issue_bootstrap = True
+ elif _cib is not None and _cib.bootstrap_permits_control_checkout(
+ bootstrap_assessment,
+ task=mutation_task,
+ workspace_path=workspace,
+ canonical_repo_root=root,
+ ):
+ # #941: the author issue-worktree bootstrap is authorized by the
+ # canonical shared decision over server-derived task-scope
+ # evidence, never by a task-name allowlist kept in this module.
+ # The predicate fails closed on missing, malformed, cross-scope,
+ # dirty, drifted, or wrongly bound evidence, so this arm cannot
+ # widen the waiver beyond the one sanctioned bootstrap task.
+ create_issue_bootstrap = True
else:
# Explicit missing-worktree signal for force-on author entrypoints.
reasons.append(
@@ -393,8 +414,15 @@ def assess_production_mutation_guards(
require_author_lock: bool = False,
in_test_mode: bool = False,
mutation_task: str | None = None,
+ bootstrap_assessment: Any | None = None,
) -> dict[str, Any]:
- """Compose root + scope production guards when they must be active (#683)."""
+ """Compose root + scope production guards when they must be active (#683).
+
+ #941: *bootstrap_assessment* is the server-derived author-bootstrap
+ evidence, forwarded unchanged to :func:`assess_root_source_mutation` so
+ this guard reaches the same canonical decision as the #274 and #604
+ guards. Omitting it preserves the pre-existing behaviour.
+ """
if not production_guards_active(in_test_mode=in_test_mode):
return {
"proven": True,
@@ -414,6 +442,7 @@ def assess_production_mutation_guards(
locked_issue_number=locked_issue_number,
role_kind=role_kind,
mutation_task=mutation_task,
+ bootstrap_assessment=bootstrap_assessment,
)
if root_assess["block"]:
return {**root_assess, "skipped": False}
From f49e781102b9f363834c28c055f69639d16290c9 Mon Sep 17 00:00:00 2001
From: jcwalker3
Date: Sun, 26 Jul 2026 07:56:14 -0500
Subject: [PATCH 10/18] fix(author bootstrap): restore missing runtime identity
and session helpers (Closes #943)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
gitea_bootstrap_author_issue_worktree referenced four globals that commit
a942afe (#850) introduced without ever defining:
_active_username 1 reference, 0 definitions
_active_profile_name 1 reference, 0 definitions
_current_session_id 1 reference, 0 definitions
_author_mutation_block 1 reference, 0 definitions
Evaluating the call arguments therefore raised
NameError: name '_active_username' is not defined
before author_issue_bootstrap.bootstrap_author_issue_worktree was entered, so
the capability was unusable for every caller including dry_run=true. The fourth
name, _author_mutation_block, sits on the reviewer-stop refusal path and was
found by the generalised regression test rather than by the original report.
The defect was unreachable until PR #942 (#941) wired the bootstrap scope into
workflow_scope_guard: before that, verify_preflight_purity refused first with
missing_issue_worktree, masking it.
Changes:
* _active_username reads the immutable #714 session context that gitea_whoami
seeds — the identity pin every other mutation gate already consults. An
unbound context returns None so callers fail closed rather than acting as an
unverified actor; a profile's expected_username is never substituted.
* _active_profile_name prefers the live get_profile() and falls back to the
bound session context only when the profile cannot be read.
* _current_session_id mints the same "--" shape as the three
pre-existing lease call sites, bound once per process so repeated calls
describe one session instead of a fresh owner per call, which would make
lease-ownership comparisons unsatisfiable. None is never memoised.
* _author_mutation_block returns the uniform refusal shape the other author
mutations already return for the same check_author_mutation_after_reviewer_stop
block.
No guard, signature, or permission changes. Wrong-role, wrong-profile,
wrong-identity, stale-runtime, expected-base and workflow-scope enforcement all
still gate the call; the helpers only supply values the service then validates
fail-closed (missing_active_identity / missing_active_profile /
missing_owner_session / stale_concurrency_pin).
Regression: tests/test_issue_943_runtime_context_helpers.py (27 tests). The
generalised test resolves every global the wrapper's body references against
module globals and builtins, so the next missing reference fails too rather
than only the three named here — that test is what found
_author_mutation_block. Coverage also coversdry-run reaching and completing the
service with helper-produced bindings, dry-run leaving no branch, worktree,
assignment or lease, apply reaching its intended transition, each fail-closed
mismatch, expected-base mismatch, and the #941/PR #942 scope wiring.
Pre-fix 20 failed / 13 passed against unmodified aab54d48; post-fix 27 passed.
Targeted bootstrap and guard suites: 245 passed, 59 subtests.
Full suite: 28 failed, 5552 passed, 6 skipped, 1006 subtests — the 28 are the
standing baseline, every one of which also fails on the unmodified base.
Closes #943
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_013ygVZQLbbhJTChuVuLaJWb
---
gitea_mcp_server.py | 76 +++
.../test_issue_943_runtime_context_helpers.py | 458 ++++++++++++++++++
2 files changed, 534 insertions(+)
create mode 100644 tests/test_issue_943_runtime_context_helpers.py
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index f3f6edc..d974a68 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -3580,6 +3580,64 @@ def _authenticated_username(host: str):
return user
+# #943: process-local session identifier. The pre-existing call sites that mint a
+# session id (workflow dashboard, lease adopt, lease reclaim) all build the same
+# "--" shape when the caller supplies none. Binding it once per
+# process keeps lease-ownership comparisons stable for the life of the session
+# instead of minting a fresh identifier — and therefore a fresh owner — on every
+# call. Process-local only, never shared to a file (same rationale as the
+# immutable session context in session_context_binding).
+_ACTIVE_SESSION_ID: str | None = None
+
+
+def _active_username() -> str | None:
+ """Authenticated identity bound to this session, or None when unbound.
+
+ Reads the immutable #714 session context that ``gitea_whoami`` seeds; it is
+ the authoritative identity pin every other mutation gate already consults.
+ Never re-derives or fabricates an identity: an unbound context returns None
+ so callers fail closed instead of acting as an unverified actor.
+ """
+ ctx = session_ctx.get_session_context() or {}
+ return ((ctx.get("identity") or "").strip()) or None
+
+
+def _active_profile_name() -> str | None:
+ """Active runtime profile name, or None when it cannot be determined.
+
+ The live profile is authoritative (``get_profile``); the bound session
+ context is consulted only when the profile cannot be read, so the reported
+ name always describes the profile actually serving this process.
+ """
+ try:
+ profile = get_profile() or {}
+ except Exception:
+ profile = {}
+ name = (profile.get("profile_name") or "").strip()
+ if name:
+ return name
+ ctx = session_ctx.get_session_context() or {}
+ return ((ctx.get("profile_name") or "").strip()) or None
+
+
+def _current_session_id() -> str | None:
+ """Session identifier for this process, or None when the profile is unknown.
+
+ Uses the same "--" shape as the existing lease call
+ sites. Bound once per process so repeated calls describe one session; fails
+ soft to None when the profile is undeterminable, letting callers fail closed
+ rather than inventing an owner.
+ """
+ global _ACTIVE_SESSION_ID
+ if _ACTIVE_SESSION_ID:
+ return _ACTIVE_SESSION_ID
+ profile_name = _active_profile_name()
+ if not profile_name:
+ return None
+ _ACTIVE_SESSION_ID = f"{profile_name}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
+ return _ACTIVE_SESSION_ID
+
+
def _authenticated_actor(host: str) -> dict:
"""Resolve the authenticated actor's stable identity (#709 F7 review 438).
@@ -9902,6 +9960,24 @@ def gitea_commit_files(
}
+def _author_mutation_block(reasons: list[str], **extra) -> dict:
+ """Uniform fail-closed shape for an author mutation refused after a reviewer stop.
+
+ #943: referenced by ``gitea_bootstrap_author_issue_worktree`` and never
+ defined, so the reviewer-stop refusal path raised ``NameError`` instead of
+ returning its refusal. Mirrors the inline shape the other author mutations
+ return for the same ``check_author_mutation_after_reviewer_stop`` block.
+ """
+ payload = {
+ "success": False,
+ "performed": False,
+ "outcome": "REFUSED",
+ "reasons": reasons,
+ }
+ payload.update(extra)
+ return payload
+
+
def _publication_block(reasons: list[str], **extra) -> dict:
"""Uniform fail-closed shape for publication refusals (#812 AC20)."""
payload = {
diff --git a/tests/test_issue_943_runtime_context_helpers.py b/tests/test_issue_943_runtime_context_helpers.py
new file mode 100644
index 0000000..f954249
--- /dev/null
+++ b/tests/test_issue_943_runtime_context_helpers.py
@@ -0,0 +1,458 @@
+"""Regression: the author bootstrap wrapper's runtime-context helpers (#943).
+
+``gitea_bootstrap_author_issue_worktree`` passed three values down to
+``author_issue_bootstrap.bootstrap_author_issue_worktree``::
+
+ active_identity=_active_username(),
+ active_profile=_active_profile_name(),
+ owner_session=_current_session_id(),
+
+None of those three names was ever defined. Commit ``a942afe`` (#850) introduced
+the references and no definition, so every call — dry-run included — raised
+``NameError: name '_active_username' is not defined`` while evaluating the
+arguments, before the bootstrap service was entered.
+
+The defect was unreachable until PR #942 (#941) wired the bootstrap scope into
+``workflow_scope_guard``: until then ``verify_preflight_purity`` refused first
+with ``missing_issue_worktree``, so the guard fix is what exposed this.
+
+``test_every_global_referenced_by_the_wrapper_resolves`` is the test that would
+have caught the original defect: it resolves every global name the wrapper's
+body references. Asserting only that the three known helpers now exist would
+not generalise to the next missing reference.
+"""
+
+from __future__ import annotations
+
+import ast
+import builtins
+import os
+import re
+import subprocess
+import tempfile
+import unittest
+from unittest import mock
+
+import author_issue_bootstrap as aib
+import create_issue_bootstrap as cib
+import gitea_mcp_server as gms
+import workflow_scope_guard
+
+BOOTSTRAP_TASK = "bootstrap_author_issue_worktree"
+WRAPPER_NAME = "gitea_bootstrap_author_issue_worktree"
+RUNTIME_HELPERS = ("_active_username", "_active_profile_name", "_current_session_id")
+
+# "--", the shape the pre-existing lease call sites mint.
+SESSION_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+-\d+-[0-9a-f]{8}$")
+
+
+def _make_control_repo(tmp: str) -> tuple[str, str]:
+ """Create a clean control checkout on master and return (path, head)."""
+ repo = os.path.join(tmp, "repo")
+ os.makedirs(os.path.join(repo, "branches"))
+ subprocess.check_call(
+ ["git", "init", "-b", "master", repo],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ subprocess.check_call(
+ [
+ "git", "-C", repo,
+ "-c", "user.email=t@t", "-c", "user.name=t",
+ "commit", "--allow-empty", "-m", "init",
+ ],
+ stdout=subprocess.DEVNULL,
+ stderr=subprocess.DEVNULL,
+ )
+ head = subprocess.check_output(
+ ["git", "-C", repo, "rev-parse", "HEAD"], text=True
+ ).strip()
+ return repo, head
+
+
+def _wrapper_ast() -> ast.FunctionDef:
+ """Return the AST of the bootstrap wrapper as it exists on disk.
+
+ Read from source rather than ``inspect``: the tool decorator may replace the
+ callable, and the defect lived in the *source* argument expressions.
+ """
+ path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+ "gitea_mcp_server.py")
+ with open(path, encoding="utf-8") as fh:
+ tree = ast.parse(fh.read())
+ for node in ast.walk(tree):
+ if isinstance(node, ast.FunctionDef) and node.name == WRAPPER_NAME:
+ return node
+ raise AssertionError(f"{WRAPPER_NAME} not found in gitea_mcp_server.py")
+
+
+class RuntimeHelperResolutionTests(unittest.TestCase):
+ """AC: every runtime helper the wrapper references is defined and callable."""
+
+ def test_three_named_helpers_are_defined_and_callable(self):
+ for name in RUNTIME_HELPERS:
+ with self.subTest(helper=name):
+ self.assertTrue(
+ hasattr(gms, name), f"{name} is referenced but not defined"
+ )
+ self.assertTrue(callable(getattr(gms, name)), f"{name} not callable")
+
+ def test_helpers_accept_zero_arguments_as_called(self):
+ """The wrapper calls each with no arguments; the signature must allow it."""
+ prior = gms._ACTIVE_SESSION_ID
+ self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
+ for name in RUNTIME_HELPERS:
+ with self.subTest(helper=name):
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None):
+ gms._ACTIVE_SESSION_ID = None
+ getattr(gms, name)() # must not raise TypeError
+
+ def test_every_global_referenced_by_the_wrapper_resolves(self):
+ """The generalised form of this defect: an unresolvable global name.
+
+ Collects every ``Name`` load in the wrapper body, subtracts locals
+ (arguments, assignments, comprehension targets, imports), and asserts the
+ remainder resolves against module globals or builtins.
+ """
+ fn = _wrapper_ast()
+ bound: set[str] = {a.arg for a in fn.args.args}
+ bound |= {a.arg for a in fn.args.kwonlyargs}
+ if fn.args.vararg:
+ bound.add(fn.args.vararg.arg)
+ if fn.args.kwarg:
+ bound.add(fn.args.kwarg.arg)
+ for node in ast.walk(fn):
+ if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+ bound.add(node.id)
+ elif isinstance(node, (ast.Import, ast.ImportFrom)):
+ for alias in node.names:
+ bound.add((alias.asname or alias.name).split(".")[0])
+ elif isinstance(node, ast.ExceptHandler) and node.name:
+ bound.add(node.name)
+
+ unresolved = sorted(
+ node.id
+ for node in ast.walk(fn)
+ if isinstance(node, ast.Name)
+ and isinstance(node.ctx, ast.Load)
+ and node.id not in bound
+ and not hasattr(gms, node.id)
+ and not hasattr(builtins, node.id)
+ )
+ self.assertEqual(
+ unresolved, [], f"{WRAPPER_NAME} references undefined globals: {unresolved}"
+ )
+
+ def test_wrapper_still_passes_all_three_runtime_values(self):
+ """Guard the wiring itself: the fix must not be 'stop passing them'."""
+ fn = _wrapper_ast()
+ called = {
+ node.func.id
+ for node in ast.walk(fn)
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
+ }
+ for name in RUNTIME_HELPERS:
+ with self.subTest(helper=name):
+ self.assertIn(name, called)
+
+
+class ActiveUsernameTests(unittest.TestCase):
+ """AC: identity comes from the authoritative pin, and fails closed."""
+
+ def test_returns_identity_from_bound_session_context(self):
+ with mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"identity": "jcwalker3", "profile_name": "prgs-author"},
+ ):
+ self.assertEqual(gms._active_username(), "jcwalker3")
+
+ def test_unbound_context_returns_none_so_callers_fail_closed(self):
+ with mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None
+ ):
+ self.assertIsNone(gms._active_username())
+
+ def test_blank_identity_is_not_treated_as_an_identity(self):
+ for blank in ("", " ", None):
+ with self.subTest(identity=blank):
+ with mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"identity": blank},
+ ):
+ self.assertIsNone(gms._active_username())
+
+ def test_identity_is_not_fabricated_from_the_profile(self):
+ """A profile's expected username must never stand in for a real identity."""
+ with mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"identity": None, "expected_username": "jcwalker3"},
+ ):
+ self.assertIsNone(gms._active_username())
+
+
+class ActiveProfileNameTests(unittest.TestCase):
+ """AC: profile name comes from the live profile, context only as fallback."""
+
+ def test_prefers_the_live_profile(self):
+ with mock.patch.object(
+ gms, "get_profile", return_value={"profile_name": "prgs-author"}
+ ), mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"profile_name": "prgs-reviewer"},
+ ):
+ self.assertEqual(gms._active_profile_name(), "prgs-author")
+
+ def test_falls_back_to_session_context_when_profile_unreadable(self):
+ with mock.patch.object(gms, "get_profile", side_effect=RuntimeError("no cfg")), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"profile_name": "prgs-author"}):
+ self.assertEqual(gms._active_profile_name(), "prgs-author")
+
+ def test_returns_none_when_neither_source_knows(self):
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None):
+ self.assertIsNone(gms._active_profile_name())
+
+
+class CurrentSessionIdTests(unittest.TestCase):
+ """AC: a real, stable session identifier — never a fresh owner per call."""
+
+ def setUp(self):
+ self._prior = gms._ACTIVE_SESSION_ID
+ gms._ACTIVE_SESSION_ID = None
+ self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", self._prior)
+
+ def test_shape_matches_the_existing_lease_call_sites(self):
+ with mock.patch.object(
+ gms, "get_profile", return_value={"profile_name": "prgs-author"}
+ ):
+ sid = gms._current_session_id()
+ self.assertRegex(sid, SESSION_ID_RE)
+ self.assertTrue(sid.startswith("prgs-author-"))
+ self.assertIn(str(os.getpid()), sid)
+
+ def test_stable_across_calls_within_one_process(self):
+ """A new id per call would make lease-ownership checks unsatisfiable."""
+ with mock.patch.object(
+ gms, "get_profile", return_value={"profile_name": "prgs-author"}
+ ):
+ first = gms._current_session_id()
+ second = gms._current_session_id()
+ third = gms._current_session_id()
+ self.assertEqual(first, second)
+ self.assertEqual(second, third)
+
+ def test_returns_none_when_profile_undeterminable(self):
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None):
+ self.assertIsNone(gms._current_session_id())
+
+ def test_none_result_is_not_memoised_as_a_session(self):
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None):
+ self.assertIsNone(gms._current_session_id())
+ with mock.patch.object(
+ gms, "get_profile", return_value={"profile_name": "prgs-author"}
+ ):
+ self.assertIsNotNone(gms._current_session_id())
+
+
+class BootstrapServiceReachedTests(unittest.TestCase):
+ """AC: the values the helpers produce carry a dry-run into the service."""
+
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self._tmp.cleanup)
+ self.tmp = self._tmp.name
+ self.repo, self.head = _make_control_repo(self.tmp)
+ self.journals = os.path.join(self.tmp, "journals")
+ os.makedirs(self.journals)
+
+ def _bootstrap(self, **over):
+ kwargs = dict(
+ issue_number=943,
+ canonical_repo_root=self.repo,
+ expected_base_sha=self.head,
+ branch_name="fix/issue-943-runtime-context-helpers",
+ remote="prgs",
+ org="Scaled-Tech-Consulting",
+ repo="Gitea-Tools",
+ active_identity="jcwalker3",
+ active_profile="prgs-author",
+ owner_session="prgs-author-4242-abcdef12",
+ lock_dir=self.journals,
+ idempotency_key="test-943",
+ dry_run=True,
+ )
+ kwargs.update(over)
+ return aib.bootstrap_author_issue_worktree(**kwargs)
+
+ def test_dry_run_succeeds_with_helper_produced_bindings(self):
+ """Feed the service exactly what the live helpers return."""
+ prior = gms._ACTIVE_SESSION_ID
+ self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
+ with mock.patch.object(
+ gms, "get_profile", return_value={"profile_name": "prgs-author"}
+ ), mock.patch.object(
+ gms.session_ctx, "get_session_context",
+ return_value={"identity": "jcwalker3", "profile_name": "prgs-author"},
+ ):
+ gms._ACTIVE_SESSION_ID = None
+ identity = gms._active_username()
+ profile = gms._active_profile_name()
+ session = gms._current_session_id()
+
+ res = self._bootstrap(
+ active_identity=identity, active_profile=profile, owner_session=session
+ )
+ self.assertTrue(res.get("success"), res)
+ self.assertTrue(res.get("dry_run"))
+ self.assertEqual(res.get("issue_number"), 943)
+ self.assertEqual(res.get("base_sha"), self.head)
+
+ def test_dry_run_creates_no_branch_worktree_or_lease(self):
+ res = self._bootstrap()
+ self.assertTrue(res.get("success"), res)
+
+ branches = subprocess.check_output(
+ ["git", "-C", self.repo, "branch", "--list"], text=True
+ )
+ self.assertNotIn("issue-943", branches)
+ worktrees = subprocess.check_output(
+ ["git", "-C", self.repo, "worktree", "list"], text=True
+ )
+ self.assertNotIn("issue-943", worktrees)
+ self.assertFalse(
+ os.path.exists(os.path.join(self.repo, "branches",
+ "fix-issue-943-runtime-context-helpers"))
+ )
+ journal = res.get("phase_journal") or {}
+ self.assertFalse(journal.get("completed"))
+ self.assertFalse(any((journal.get("artifacts_created") or {}).values()))
+ self.assertIsNone(journal.get("lease_id"))
+ self.assertIsNone(journal.get("assignment_id"))
+
+ def test_missing_identity_fails_closed(self):
+ res = self._bootstrap(active_identity=None)
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "missing_active_identity")
+
+ def test_missing_profile_fails_closed(self):
+ res = self._bootstrap(active_profile=" ")
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "missing_active_profile")
+
+ def test_missing_session_fails_closed(self):
+ res = self._bootstrap(owner_session=None)
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "missing_owner_session")
+
+ def test_expected_base_mismatch_fails_closed(self):
+ res = self._bootstrap(expected_base_sha="0" * 40)
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "stale_concurrency_pin")
+
+ def test_unbound_runtime_context_cannot_reach_the_service(self):
+ """With nothing bound, the helpers yield None and the service refuses."""
+ prior = gms._ACTIVE_SESSION_ID
+ self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(
+ gms.session_ctx, "get_session_context", return_value=None):
+ gms._ACTIVE_SESSION_ID = None
+ res = self._bootstrap(
+ active_identity=gms._active_username(),
+ active_profile=gms._active_profile_name(),
+ owner_session=gms._current_session_id(),
+ )
+ self.assertFalse(res.get("success"))
+ self.assertIn(
+ res.get("reason_code"),
+ {"missing_owner_session", "missing_active_identity",
+ "missing_active_profile"},
+ )
+
+ def test_apply_reaches_the_intended_transition(self):
+ res = self._bootstrap(dry_run=False)
+ self.assertTrue(res.get("success"), res)
+ self.assertNotEqual(res.get("dry_run"), True)
+ branches = subprocess.check_output(
+ ["git", "-C", self.repo, "branch", "--list"], text=True
+ )
+ self.assertIn("issue-943", branches)
+ self.assertTrue(os.path.isdir(res.get("worktree_path") or ""))
+
+
+class Issue941ScopeGuardNotRegressedTests(unittest.TestCase):
+ """AC: PR #942's bootstrap-scope wiring still holds."""
+
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self._tmp.cleanup)
+ self.repo, self.head = _make_control_repo(self._tmp.name)
+
+ def _assessment(self, task: str = BOOTSTRAP_TASK) -> dict:
+ return aib.assess_author_issue_bootstrap(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ current_branch="master",
+ head_sha=self.head,
+ porcelain_status="",
+ remote_master_sha=self.head,
+ task=task,
+ )
+
+ def test_bootstrap_task_still_permitted_from_clean_control_checkout(self):
+ res = workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ role_kind="author",
+ mutation_task=BOOTSTRAP_TASK,
+ porcelain_status="",
+ bootstrap_assessment=self._assessment(),
+ )
+ self.assertFalse(res.get("block"), res)
+ self.assertNotEqual(
+ res.get("blocker_kind"), workflow_scope_guard.BLOCKER_MISSING_WORKTREE
+ )
+
+ def test_bootstrap_task_still_blocked_without_evidence(self):
+ res = workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ role_kind="author",
+ mutation_task=BOOTSTRAP_TASK,
+ porcelain_status="",
+ )
+ self.assertTrue(res.get("block"))
+ self.assertEqual(
+ res.get("blocker_kind"), workflow_scope_guard.BLOCKER_MISSING_WORKTREE
+ )
+
+ def test_ordinary_author_mutation_still_blocked_from_control_checkout(self):
+ res = workflow_scope_guard.assess_root_source_mutation(
+ workspace_path=self.repo,
+ canonical_repo_root=self.repo,
+ role_kind="author",
+ mutation_task="commit_files",
+ porcelain_status="",
+ bootstrap_assessment=self._assessment(),
+ )
+ self.assertTrue(res.get("block"))
+ self.assertEqual(
+ res.get("blocker_kind"), workflow_scope_guard.BLOCKER_MISSING_WORKTREE
+ )
+
+ def test_create_issue_bootstrap_unchanged(self):
+ self.assertTrue(cib.is_create_issue_task("create_issue"))
+ self.assertFalse(cib.is_create_issue_task(BOOTSTRAP_TASK))
+
+
+if __name__ == "__main__":
+ unittest.main()
From 79334d48408fd446ddf1e8be332495960b847af6 Mon Sep 17 00:00:00 2001
From: jcwalker3
Date: Sun, 26 Jul 2026 10:42:44 -0500
Subject: [PATCH 11/18] fix(gate): preserve exact-owner renewal evidence across
duplicate rechecks (Closes #945)
An exact-owner lease renewal (#760) is granted the owning-PR duplicate-work
waiver inside gitea_lock_issue, but every later enforcement path rebuilt that
proof from the durable lock through
issue_lock_recovery.recovered_owning_pr_from_lock, which reads only the
dead_session_recovery block. A plain renewal persists its proof under
lease_renewal instead, so the waiver expired with the lock call and the next
author mutation was refused duplicate_commit_prevented with
owning_pr_recovery_exempted: false on the very PR the renewal had just proved.
Add issue_lock_renewal.owning_pr_renewal_from_lock as the renewal mirror of the
recovery rebuild, and resolve both halves through one helper,
_owning_pr_continuation_from_lock, in the same precedence gitea_lock_issue
applies. The three enforcement paths that previously saw only recovery evidence
now share that resolver: the commit/create-PR duplicate recheck, the read-only
duplicate assessor, and the push-ownership prover.
The rebuild re-applies the equality the renewal assessor required (PR head ==
local head == remote head) and additionally binds the record to the claimant the
lock names, so a renewal block cannot be reused under another identity, profile,
or workflow session. Validation of the resulting token against live PR state is
unchanged and still owned solely by
issue_work_duplicate_gate._assess_owning_pr_exemption, so repository, issue, PR,
branch and head binding continue to be enforced in exactly one place.
No public signature, MCP tool schema, refusal shape, or reason code changes.
Dead-session recovery behaviour is untouched.
Tests: tests/test_issue_945_owning_pr_renewal_continuation.py - 49 tests,
8 subtests, all in-memory (no durable branch, worktree, lock, lease or PR).
Against unmodified aab54d48 the suite is 47 failed / 2 passed; the 2 that pass
are the defect-pinning reproductions. Full suite 28F/5574P/6S/1002 subtests at
head vs 28F/5525P/6S/994 at base, with identical failing test id sets.
Co-Authored-By: Claude Opus 4.8 (1M context)
---
gitea_mcp_server.py | 51 +-
issue_lock_renewal.py | 84 ++++
...ssue_945_owning_pr_renewal_continuation.py | 465 ++++++++++++++++++
3 files changed, 593 insertions(+), 7 deletions(-)
create mode 100644 tests/test_issue_945_owning_pr_renewal_continuation.py
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index f3f6edc..a3663d0 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -2781,6 +2781,36 @@ def _collect_issue_duplicate_context(
return issue_duplicate_context_fetcher(h, o, r, auth, issue_number)
+def _owning_pr_continuation_from_lock(lock_record: dict | None) -> dict | None:
+ """Owning-PR continuation evidence a persisted lock still proves (#945).
+
+ ``gitea_lock_issue`` grants the duplicate-work waiver from either a
+ sanctioned dead-session recovery (#755) or a sanctioned exact-owner renewal
+ (#760), in that precedence. Every later enforcement path — commit,
+ create-PR, push-ownership, and the read-only duplicate assessor — re-derives
+ ownership from the durable lock instead of that live assessment.
+
+ Until #945 only the recovery half was rebuilt there, so an ordinary
+ exact-owner renewal lost its waiver the moment ``gitea_lock_issue``
+ returned: the author renewed successfully and was then refused
+ ``duplicate_commit_prevented`` with ``owning_pr_recovery_exempted: false``
+ on the very PR the renewal had just proved it owned.
+
+ Resolving both halves here, in the same precedence the lock path applies,
+ keeps the answer from drifting between the gate that grants the waiver and
+ the gates that enforce it. This only decides which server-written block the
+ token is rebuilt from — the token is still re-validated against live PR
+ state by ``issue_work_duplicate_gate._assess_owning_pr_exemption``, which
+ remains the single authoritative policy for whether an exemption applies.
+ """
+ if not lock_record:
+ return None
+ recovered = issue_lock_recovery.recovered_owning_pr_from_lock(lock_record)
+ if recovered:
+ return recovered
+ return issue_lock_renewal.owning_pr_renewal_from_lock(lock_record)
+
+
def _assess_issue_duplicate_gate(
issue_number: int,
*,
@@ -2833,6 +2863,11 @@ def _enforce_locked_issue_duplicate_recheck(
commit and create-PR phases run in their own calls, long after the recovery
assessment ended, so without this they re-block the very PR the recovery
already proved belongs to this author.
+
+ #945: an exact-owner *renewal* (#760) owns its open PR for exactly the same
+ reason, and ``gitea_lock_issue`` already waives the blocker for both. Both
+ halves are resolved together here so the renewal waiver survives past the
+ lock call instead of expiring with it.
"""
lock_data = _load_existing_issue_lock()
if not lock_data:
@@ -2856,9 +2891,7 @@ def _enforce_locked_issue_duplicate_recheck(
auth=auth,
locked_branch=locked_branch,
phase=phase,
- recovered_owning_pr=issue_lock_recovery.recovered_owning_pr_from_lock(
- lock_data
- ),
+ recovered_owning_pr=_owning_pr_continuation_from_lock(lock_data),
)
if gate.get("block"):
return gate
@@ -5140,9 +5173,10 @@ def gitea_assess_work_issue_duplicate(
recovered_owning_pr = None
lock_data = _load_existing_issue_lock()
if lock_data and int(lock_data.get("issue_number") or 0) == int(issue_number):
- recovered_owning_pr = issue_lock_recovery.recovered_owning_pr_from_lock(
- lock_data
- )
+ # #945: rebuilt from a sanctioned recovery *or* a sanctioned exact-owner
+ # renewal, so this read-only assessor reports the same disposition the
+ # commit and create-PR gates will enforce.
+ recovered_owning_pr = _owning_pr_continuation_from_lock(lock_data)
gate = _assess_issue_duplicate_gate(
issue_number,
h=h,
@@ -19424,7 +19458,10 @@ def _prove_author_ownership_for_pr(
# advance is the one recovery already sanctioned, not a foreign head.
recovered_owning_pr = None
if proven and lock_record:
- candidate = issue_lock_recovery.recovered_owning_pr_from_lock(lock_record)
+ # #945: a sanctioned exact-owner renewal proves the same ownership of
+ # the same PR, so the push gate resolves both halves rather than seeing
+ # only the recovery one.
+ candidate = _owning_pr_continuation_from_lock(lock_record)
if candidate and int(candidate.get("pr_number") or 0) == int(pr_number):
recovered_owning_pr = candidate
return {
diff --git a/issue_lock_renewal.py b/issue_lock_renewal.py
index ec8a436..1739f73 100644
--- a/issue_lock_renewal.py
+++ b/issue_lock_renewal.py
@@ -436,6 +436,90 @@ def owning_pr_renewal_evidence(
}
+def owning_pr_renewal_from_lock(
+ lock_record: Mapping[str, Any] | None,
+) -> dict[str, Any] | None:
+ """Rebuild owning-PR renewal evidence from a persisted lock (#945).
+
+ The renewal mirror of ``issue_lock_recovery.recovered_owning_pr_from_lock``.
+ ``owning_pr_renewal_evidence`` supplies the waiver for the duration of the
+ ``gitea_lock_issue`` call only. The commit, push, create-PR, and
+ duplicate-assessment gates run later in their own calls and re-derive
+ ownership from the durable lock instead — so without this the open PR that
+ renewal already proved belongs to this author reappears there as competing
+ duplicate work, and the exact owner is refused with
+ ``duplicate_commit_prevented`` despite complete matching evidence.
+
+ This reads only the ``lease_renewal`` block that the server itself writes,
+ on a lock the caller must already own. Like the recovery mirror it is a
+ re-read of server-derived state, never a fresh assertion: a caller able to
+ forge it could equally forge the lock file every other ownership gate
+ already treats as authoritative.
+
+ Renewal has no descendant case — the assessor required the local, remote and
+ PR heads to be equal — so that equality is re-checked here, and the record
+ must still name the claimant the lock records.
+ """
+ if not isinstance(lock_record, Mapping):
+ return None
+ record = lock_record.get("lease_renewal")
+ if not isinstance(record, Mapping) or not record.get("renewed"):
+ return None
+
+ branch_name = _text(record.get("branch_name")) or _text(
+ lock_record.get("branch_name")
+ )
+ pr_head = _text(record.get("pr_head_sha"))
+ local_head = _text(record.get("head_sha"))
+ remote_head = _text(record.get("remote_head_sha"))
+ raw_pr_number = record.get("pr_number")
+ raw_issue_number = lock_record.get("issue_number")
+
+ if raw_pr_number is None or raw_issue_number is None:
+ return None
+ if not branch_name or not pr_head:
+ return None
+ # The assessor required all three heads to agree before it granted renewal.
+ # Re-check, so a truncated, drifted, or hand-built record cannot widen the
+ # exemption past the single head the renewal disposition actually proved.
+ if not local_head or not remote_head:
+ return None
+ if pr_head != local_head or pr_head != remote_head:
+ return None
+ # Renewal is refused outright unless the durable lock records both a
+ # claimant username and profile, so a sanctioned record always carries them.
+ # Requiring them to still agree keeps a renewal block from being reused
+ # under an identity or profile the lock no longer names.
+ claimant = lock_record.get("claimant")
+ if not isinstance(claimant, Mapping):
+ lease = lock_record.get("work_lease")
+ claimant = lease.get("claimant") if isinstance(lease, Mapping) else None
+ if not isinstance(claimant, Mapping):
+ return None
+ identity = _text(record.get("identity"))
+ profile = _text(record.get("profile"))
+ if not identity or identity != _text(claimant.get("username")):
+ return None
+ if not profile or profile != _text(claimant.get("profile")):
+ return None
+
+ try:
+ pr_number = int(raw_pr_number)
+ issue_number = int(raw_issue_number)
+ except (TypeError, ValueError):
+ return None
+
+ return {
+ "issue_number": issue_number,
+ "pr_number": pr_number,
+ "branch_name": branch_name,
+ "head_sha": pr_head,
+ "recorded_head": pr_head,
+ "accepted_head": pr_head,
+ "head_relation": "equal",
+ }
+
+
def build_renewal_record(
assessment: Mapping[str, Any] | None,
*,
diff --git a/tests/test_issue_945_owning_pr_renewal_continuation.py b/tests/test_issue_945_owning_pr_renewal_continuation.py
new file mode 100644
index 0000000..41bca8b
--- /dev/null
+++ b/tests/test_issue_945_owning_pr_renewal_continuation.py
@@ -0,0 +1,465 @@
+import sys as _sys
+from pathlib import Path as _Path
+_sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from mutation_profile_fixture import shared_mutation_env # noqa: F401,E402
+"""Exact-owner renewal keeps its owning-PR waiver past lock_issue (#945).
+
+#755 taught the duplicate-work gate that a sanctioned *dead-session recovery*
+owns its open PR, and #768 taught the later gates to rebuild that proof from the
+durable lock. #760 added the exact-owner *renewal* disposition and granted it
+the same waiver inside ``gitea_lock_issue`` — but never added the matching
+rebuild. So an ordinary renewal held the waiver only for the duration of the
+lock call: ``_enforce_locked_issue_duplicate_recheck`` asked
+``recovered_owning_pr_from_lock``, which reads only ``dead_session_recovery``,
+and the very next commit was refused ``duplicate_commit_prevented`` with
+``owning_pr_recovery_exempted: false`` on the PR the renewal had just proved.
+
+``TestPreFixReproduction`` pins that defect directly: the recovery-only rebuild
+still returns ``None`` for a renewal lock, which is exactly why the gates lost
+the waiver. Everything else proves the renewal half now survives, that recovery
+is unchanged, and that no path grants an exemption on weaker evidence.
+
+Every fixture here is an in-memory mapping. Nothing writes a branch, worktree,
+lock file, lease, comment, or PR (#945 AC18).
+"""
+import copy
+import sys
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import gitea_mcp_server # noqa: E402
+import issue_lock_recovery # noqa: E402
+import issue_lock_renewal # noqa: E402
+from issue_work_duplicate_gate import ( # noqa: E402
+ OUTCOME_DUPLICATE_WORK_NOT_PREVENTED,
+ PHASE_COMMIT,
+ PHASE_CREATE_PR,
+ PHASE_LOCK,
+ PHASE_PUSH,
+ assess_work_issue_duplicate_gate,
+)
+
+ISSUE = 4945
+OWNING_PR = 4946
+OTHER_PR = 4947
+BRANCH = f"fix/issue-{ISSUE}-owning-pr-renewal"
+OTHER_BRANCH = f"fix/issue-{ISSUE}-competing"
+HEAD = "a" * 40
+OTHER_HEAD = "b" * 40
+IDENTITY = "example-user"
+PROFILE = "test-author-prgs"
+
+
+def renewal_record(**overrides):
+ """The ``lease_renewal`` block ``build_renewal_record`` writes on success."""
+ record = {
+ "renewed": True,
+ "renewed_at": "2026-01-01T00:00:00Z",
+ "prior_pid": 4242,
+ "prior_pid_alive": True,
+ "prior_expires_at": "2026-01-01T00:00:00Z",
+ "replacement_pid": 4243,
+ "new_expires_at": "2026-01-01T00:10:00Z",
+ "identity": IDENTITY,
+ "profile": PROFILE,
+ "branch_name": BRANCH,
+ "worktree_path": f"branches/issue-{ISSUE}-owning-pr-renewal",
+ "head_sha": HEAD,
+ "remote_head_sha": HEAD,
+ "pr_head_sha": HEAD,
+ "pr_number": OWNING_PR,
+ "reason": "expired lease renewed by its exact recorded owner",
+ "proof": [],
+ }
+ record.update(overrides)
+ return record
+
+
+def renewal_lock(record=None, *, issue_number=ISSUE, claimant=True, **lock_overrides):
+ lock = {
+ "issue_number": issue_number,
+ "branch_name": BRANCH,
+ "lease_renewal": renewal_record() if record is None else record,
+ }
+ if claimant:
+ lock["claimant"] = {"username": IDENTITY, "profile": PROFILE}
+ lock.update(lock_overrides)
+ return lock
+
+
+def recovery_lock(pr_number=OWNING_PR, head=HEAD):
+ """A lock carrying sanctioned dead-session recovery evidence (#755/#768)."""
+ return {
+ "issue_number": ISSUE,
+ "branch_name": BRANCH,
+ "claimant": {"username": IDENTITY, "profile": PROFILE},
+ "dead_session_recovery": {
+ "recovered": True,
+ "branch_name": BRANCH,
+ "pr_number": pr_number,
+ "pr_head": head,
+ "recorded_head": head,
+ "accepted_head": head,
+ "head_relation": issue_lock_recovery.HEAD_RELATION_EQUAL,
+ },
+ }
+
+
+def owning_pr(number=OWNING_PR, ref=BRANCH, sha=HEAD, issue=ISSUE):
+ return {
+ "number": number,
+ "title": f"fix: something (Closes #{issue})",
+ "body": f"Closes #{issue}.",
+ "head": {"ref": ref, "sha": sha},
+ }
+
+
+def gate(phase, *, token, open_prs=None, branch_names=None, locked_branch=BRANCH):
+ return assess_work_issue_duplicate_gate(
+ ISSUE,
+ open_prs=[owning_pr()] if open_prs is None else open_prs,
+ branch_names=branch_names or [],
+ claim_entry={},
+ locked_branch=locked_branch,
+ phase=phase,
+ recovered_owning_pr=token,
+ )
+
+
+# ───────────────────── the defect this issue exists to fix ─────────────────────
+
+
+class TestPreFixReproduction(unittest.TestCase):
+ """The exact wiring gap: renewal evidence was invisible to later gates."""
+
+ def test_recovery_only_rebuild_cannot_see_a_renewal_lock(self):
+ # This is the pre-fix behaviour of every enforcement path. It is correct
+ # for the recovery rebuild to ignore a renewal block -- the defect was
+ # that nothing else looked at it.
+ self.assertIsNone(
+ issue_lock_recovery.recovered_owning_pr_from_lock(renewal_lock())
+ )
+
+ def test_renewal_lock_produced_no_exemption_before_the_fix(self):
+ # Feeding the gate what the pre-fix code fed it (recovery rebuild only)
+ # reproduces the reported refusal at the commit phase.
+ token = issue_lock_recovery.recovered_owning_pr_from_lock(renewal_lock())
+ result = gate(PHASE_COMMIT, token=token)
+ self.assertTrue(result["block"])
+ self.assertEqual(result["outcome"], "duplicate_commit_prevented")
+ self.assertFalse(result["owning_pr_recovery_exempted"])
+ self.assertEqual(result["owning_pr_recovery_notes"], [])
+
+ def test_shared_resolver_now_sees_it(self):
+ self.assertIsNotNone(
+ gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+ )
+
+
+# ───────────────────────── rebuild: the granted case ─────────────────────────
+
+
+class TestRenewalRebuildGranted(unittest.TestCase):
+ def test_sanctioned_renewal_rebuilds_owning_pr_evidence(self):
+ token = issue_lock_renewal.owning_pr_renewal_from_lock(renewal_lock())
+ self.assertEqual(
+ token,
+ {
+ "issue_number": ISSUE,
+ "pr_number": OWNING_PR,
+ "branch_name": BRANCH,
+ "head_sha": HEAD,
+ "recorded_head": HEAD,
+ "accepted_head": HEAD,
+ "head_relation": "equal",
+ },
+ )
+
+ def test_branch_falls_back_to_the_lock_branch(self):
+ lock = renewal_lock(renewal_record(branch_name=""))
+ token = issue_lock_renewal.owning_pr_renewal_from_lock(lock)
+ self.assertEqual(token["branch_name"], BRANCH)
+
+ def test_claimant_may_live_under_work_lease(self):
+ lock = renewal_lock(claimant=False)
+ lock["work_lease"] = {"claimant": {"username": IDENTITY, "profile": PROFILE}}
+ self.assertIsNotNone(issue_lock_renewal.owning_pr_renewal_from_lock(lock))
+
+ def test_rebuild_does_not_mutate_the_lock(self):
+ lock = renewal_lock()
+ before = copy.deepcopy(lock)
+ issue_lock_renewal.owning_pr_renewal_from_lock(lock)
+ self.assertEqual(lock, before)
+
+
+# ───────────────────────── rebuild: fails closed ─────────────────────────
+
+
+class TestRenewalRebuildFailsClosed(unittest.TestCase):
+ def assertNoEvidence(self, lock):
+ self.assertIsNone(issue_lock_renewal.owning_pr_renewal_from_lock(lock))
+
+ def test_no_lock_at_all(self):
+ self.assertNoEvidence(None)
+ self.assertNoEvidence({})
+ self.assertNoEvidence("not-a-mapping")
+
+ def test_lock_without_renewal_block(self):
+ # A fresh claim, or a lock whose renewal block was replaced.
+ self.assertNoEvidence({"issue_number": ISSUE, "branch_name": BRANCH})
+
+ def test_renewal_not_granted(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(renewed=False)))
+
+ def test_renewal_flag_missing(self):
+ record = renewal_record()
+ del record["renewed"]
+ self.assertNoEvidence(renewal_lock(record))
+
+ def test_renewal_block_malformed(self):
+ self.assertNoEvidence(renewal_lock("not-a-mapping"))
+
+ def test_local_head_diverged_from_pr_head(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(head_sha=OTHER_HEAD)))
+
+ def test_remote_head_diverged_from_pr_head(self):
+ # Force-push or unrelated remote movement.
+ self.assertNoEvidence(renewal_lock(renewal_record(remote_head_sha=OTHER_HEAD)))
+
+ def test_local_head_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(head_sha="")))
+
+ def test_remote_head_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(remote_head_sha="")))
+
+ def test_pr_head_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(pr_head_sha="")))
+
+ def test_pr_number_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(pr_number=None)))
+
+ def test_pr_number_malformed(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(pr_number="not-a-number")))
+
+ def test_issue_number_missing_from_lock(self):
+ self.assertNoEvidence(renewal_lock(issue_number=None))
+
+ def test_branch_unknown_everywhere(self):
+ lock = renewal_lock(renewal_record(branch_name=""))
+ lock["branch_name"] = ""
+ self.assertNoEvidence(lock)
+
+ def test_identity_mismatch(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(identity="someone-else")))
+
+ def test_profile_mismatch(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(profile="other-profile")))
+
+ def test_identity_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(identity="")))
+
+ def test_profile_missing(self):
+ self.assertNoEvidence(renewal_lock(renewal_record(profile="")))
+
+ def test_claimant_absent(self):
+ self.assertNoEvidence(renewal_lock(claimant=False))
+
+ def test_evidence_from_a_different_session_is_not_reusable(self):
+ # A renewal block left by another workflow session names another
+ # claimant, so the lock it is found on cannot inherit its authority.
+ lock = renewal_lock()
+ lock["claimant"] = {"username": "other-session-user", "profile": PROFILE}
+ self.assertNoEvidence(lock)
+
+
+# ───────────────────────── the shared resolver ─────────────────────────
+
+
+class TestSharedResolver(unittest.TestCase):
+ def test_recovery_lock_resolves_to_recovery_evidence(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(recovery_lock())
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ def test_renewal_lock_resolves_to_renewal_evidence(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ def test_recovery_takes_precedence_over_renewal(self):
+ # Same precedence gitea_lock_issue applies when granting the waiver, so
+ # the answer cannot differ between the granting and enforcing paths.
+ lock = recovery_lock(pr_number=OTHER_PR, head=OTHER_HEAD)
+ lock["lease_renewal"] = renewal_record()
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(lock)
+ self.assertEqual(token["pr_number"], OTHER_PR)
+
+ def test_no_evidence_resolves_to_none(self):
+ self.assertIsNone(gitea_mcp_server._owning_pr_continuation_from_lock(None))
+ self.assertIsNone(gitea_mcp_server._owning_pr_continuation_from_lock({}))
+ self.assertIsNone(
+ gitea_mcp_server._owning_pr_continuation_from_lock(
+ {"issue_number": ISSUE, "branch_name": BRANCH}
+ )
+ )
+
+
+# ────────────── every enforcement path uses the same decision ──────────────
+
+
+class TestEnforcementPathsShareOneDecision(unittest.TestCase):
+ """AC: commit, push and create-PR gates consume one authoritative token."""
+
+ def setUp(self):
+ self.token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+
+ def test_commit_phase_permits_continuation(self):
+ result = gate(PHASE_COMMIT, token=self.token)
+ self.assertFalse(result["block"])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+ self.assertEqual(result["outcome"], OUTCOME_DUPLICATE_WORK_NOT_PREVENTED)
+
+ def test_create_pr_phase_permits_continuation(self):
+ result = gate(PHASE_CREATE_PR, token=self.token)
+ self.assertFalse(result["block"])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+
+ def test_push_phase_permits_continuation(self):
+ result = gate(PHASE_PUSH, token=self.token)
+ self.assertFalse(result["block"])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+
+ def test_lock_phase_permits_continuation(self):
+ result = gate(PHASE_LOCK, token=self.token)
+ self.assertFalse(result["block"])
+
+ def test_all_phases_agree(self):
+ outcomes = {
+ phase: gate(phase, token=self.token)["block"]
+ for phase in (PHASE_LOCK, PHASE_COMMIT, PHASE_PUSH, PHASE_CREATE_PR)
+ }
+ self.assertEqual(set(outcomes.values()), {False}, outcomes)
+
+ def test_dead_session_recovery_still_permits_continuation(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(recovery_lock())
+ for phase in (PHASE_COMMIT, PHASE_PUSH, PHASE_CREATE_PR):
+ with self.subTest(phase=phase):
+ result = gate(phase, token=token)
+ self.assertFalse(result["block"])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+
+
+# ───────────────── the exemption cannot be widened ─────────────────
+
+
+class TestExemptionCannotBeWidened(unittest.TestCase):
+ def setUp(self):
+ self.token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+
+ def test_an_open_pr_alone_grants_nothing(self):
+ result = gate(PHASE_COMMIT, token=None)
+ self.assertTrue(result["block"])
+ self.assertFalse(result["owning_pr_recovery_exempted"])
+
+ def test_a_second_pr_is_refused(self):
+ result = gate(
+ PHASE_CREATE_PR,
+ token=self.token,
+ open_prs=[owning_pr(), owning_pr(number=OTHER_PR, ref=OTHER_BRANCH)],
+ )
+ self.assertTrue(result["block"])
+ self.assertFalse(result["owning_pr_recovery_exempted"])
+
+ def test_a_different_pr_is_refused(self):
+ result = gate(
+ PHASE_COMMIT, token=self.token, open_prs=[owning_pr(number=OTHER_PR)]
+ )
+ self.assertTrue(result["block"])
+
+ def test_a_different_branch_is_refused(self):
+ result = gate(
+ PHASE_COMMIT, token=self.token, open_prs=[owning_pr(ref=OTHER_BRANCH)]
+ )
+ self.assertTrue(result["block"])
+
+ def test_locked_branch_mismatch_is_refused(self):
+ result = gate(PHASE_COMMIT, token=self.token, locked_branch=OTHER_BRANCH)
+ self.assertTrue(result["block"])
+
+ def test_live_pr_head_divergence_is_refused(self):
+ # Force-push or unrelated remote movement after renewal.
+ result = gate(
+ PHASE_COMMIT, token=self.token, open_prs=[owning_pr(sha=OTHER_HEAD)]
+ )
+ self.assertTrue(result["block"])
+
+ def test_evidence_for_another_issue_is_refused(self):
+ foreign = gitea_mcp_server._owning_pr_continuation_from_lock(
+ renewal_lock(issue_number=ISSUE + 1)
+ )
+ result = gate(PHASE_COMMIT, token=foreign)
+ self.assertTrue(result["block"])
+
+ def test_sequential_tasks_do_not_inherit_continuation(self):
+ # One daemon serves many tasks. A renewal proved for issue N must not
+ # authorize continuation for the next task's issue.
+ prior_task = gitea_mcp_server._owning_pr_continuation_from_lock(
+ renewal_lock(issue_number=ISSUE + 7)
+ )
+ self.assertIsNotNone(prior_task)
+ self.assertTrue(gate(PHASE_COMMIT, token=prior_task)["block"])
+
+
+# ───────────────── ordinary duplicate prevention is intact ─────────────────
+
+
+class TestDuplicatePreventionRetained(unittest.TestCase):
+ def test_competing_branch_still_blocks(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+ result = gate(
+ PHASE_COMMIT,
+ token=token,
+ open_prs=[],
+ branch_names=[BRANCH, OTHER_BRANCH],
+ )
+ self.assertTrue(result["block"])
+
+ def test_unrelated_work_without_a_lock_still_blocks(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(None)
+ self.assertIsNone(token)
+ self.assertTrue(gate(PHASE_COMMIT, token=token)["block"])
+
+
+# ───────────────── refusals stay structured and auditable ─────────────────
+
+
+class TestRefusalShapePreserved(unittest.TestCase):
+ def test_blocked_result_keeps_its_audit_fields(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+ result = gate(
+ PHASE_COMMIT, token=token, open_prs=[owning_pr(number=OTHER_PR)]
+ )
+ for field in (
+ "block",
+ "outcome",
+ "reasons",
+ "owning_pr_recovery_exempted",
+ "owning_pr_recovery_notes",
+ ):
+ with self.subTest(field=field):
+ self.assertIn(field, result)
+ self.assertTrue(result["reasons"])
+ # A rejected token explains which element of ownership disagreed.
+ self.assertTrue(result["owning_pr_recovery_notes"])
+
+ def test_granted_result_records_why(self):
+ token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
+ result = gate(PHASE_COMMIT, token=token)
+ self.assertTrue(result["owning_pr_recovery_notes"])
+ self.assertIn(
+ f"#{OWNING_PR}", " ".join(result["owning_pr_recovery_notes"])
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
From b1fcf159378e7c72b67cc5ac507920d8390ef107 Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Mon, 27 Jul 2026 18:22:07 -0400
Subject: [PATCH 12/18] fix(gate): complete owning-PR renewal enforcement
coverage (#945)
Addresses review 623 on PR #946 (B1 blocker, F2 medium, F3 minor).
B1 - the wiring this branch exists to install had no regression coverage.
The existing suite exercised owning_pr_renewal_from_lock,
_owning_pr_continuation_from_lock and the duplicate gate directly, but never
drove an enforcement path, so reverting any of the three call sites left the
whole repository green. Add tests/test_issue_945_enforcement_path_wiring.py,
which drives the real mcp_server._enforce_locked_issue_duplicate_recheck (the
shared recheck behind gitea_commit_files and gitea_create_pr),
mcp_server.gitea_assess_work_issue_duplicate and
mcp_server._prove_author_ownership_for_pr against a renewal-bearing lock, and
asserts each grants the exemption. Reverting the commit/create-PR recheck to
the recovery-only rebuild now fails 8 tests and 4 subtests; reverting the
assessor or the push prover fails 2 each. The suite also keeps the fail-closed
matrix on the real paths: an open PR alone, a second PR, a different PR,
branch, issue or head, identity and profile mismatch, ungranted and malformed
renewal blocks, and sequential-task non-inheritance are all still refused.
F2 - the claimant check compares lease_renewal.identity/profile against the
claimant recorded on the same lock file. Both sides are server-written fields
of one document, so it is an internal-consistency check, not verification of
the live authenticated caller. Correct the docstring and the inline comment to
say so, and document the binding that actually prevents cross-session reuse:
the enforcement paths load the lock through _load_existing_issue_lock() with no
issue coordinates, which resolves issue_lock_store.read_session_issue_lock() to
the session pointer at session-{os.getpid()}.json, so lock selection is scoped
to the operating-system process. Its limits are stated too - per-process rather
than per-authenticated-user, silent on locks reached by explicit coordinates,
and silent on two roles sharing one process. Live identity and profile stay
enforced by the mutation-authority and profile gates, not by this rebuild.
F3 - _owning_pr_continuation_from_lock previously fell through to renewal when
a dead_session_recovery block was present but failed to rebuild, so a recovery
record naming one PR could be bypassed by renewal evidence naming another.
Present-but-unusable recovery evidence is now ambiguous rather than absent and
fails closed. Because an expired lease whose recorded owner has also died
satisfies both dispositions in one gitea_lock_issue call, a sanctioned pair is
a reachable state; when both rebuild, they must agree on issue, PR, branch and
every head, or no continuation authority is returned. Recovery-only and
renewal-only locks keep their existing behaviour exactly.
Validation of the resulting token against live PR state remains untouched and
solely owned by issue_work_duplicate_gate._assess_owning_pr_exemption. No
public signature, MCP tool schema, refusal shape or reason code changes.
Tests: focused #945/#755/#760 suites 137 passed, 19 subtests. Full suite in a
branches/ worktree: 30F/5619P/6S/1013 subtests at this head vs 30F/5572P/6S/1002
at a clean checkout of 79334d48, with byte-identical failing test id sets - the
+47 passes and +11 subtests are exactly the new coverage.
Co-Authored-By: Claude Opus 5 (1M context)
Claude-Session: https://claude.ai/code/session_01Q8RUznLXEA4JoK48sTZiSK
---
gitea_mcp_server.py | 53 +-
issue_lock_renewal.py | 31 +-
.../test_issue_945_enforcement_path_wiring.py | 685 ++++++++++++++++++
...ssue_945_owning_pr_renewal_continuation.py | 151 +++-
4 files changed, 910 insertions(+), 10 deletions(-)
create mode 100644 tests/test_issue_945_enforcement_path_wiring.py
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index a3663d0..ee911a7 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -2781,6 +2781,29 @@ def _collect_issue_duplicate_context(
return issue_duplicate_context_fetcher(h, o, r, auth, issue_number)
+# Every field of the owning-PR continuation token is security relevant: the
+# issue and PR it names, the branch it is scoped to, and each head the waiver
+# was measured against. Two evidence blocks that disagree on any of them cannot
+# both describe the single sanctioned decision the lock is supposed to record.
+_CONTINUATION_EVIDENCE_BINDINGS = (
+ "issue_number",
+ "pr_number",
+ "branch_name",
+ "head_sha",
+ "recorded_head",
+ "accepted_head",
+ "head_relation",
+)
+
+
+def _continuation_evidence_agrees(recovered: dict, renewed: dict) -> bool:
+ """Do two rebuilt continuation tokens bind to exactly the same thing (#945)?"""
+ return all(
+ recovered.get(field) == renewed.get(field)
+ for field in _CONTINUATION_EVIDENCE_BINDINGS
+ )
+
+
def _owning_pr_continuation_from_lock(lock_record: dict | None) -> dict | None:
"""Owning-PR continuation evidence a persisted lock still proves (#945).
@@ -2802,13 +2825,41 @@ def _owning_pr_continuation_from_lock(lock_record: dict | None) -> dict | None:
token is rebuilt from — the token is still re-validated against live PR
state by ``issue_work_duplicate_gate._assess_owning_pr_exemption``, which
remains the single authoritative policy for whether an exemption applies.
+
+ **Both blocks present is a reachable, legitimate state, and it must agree.**
+ The two dispositions are not mutually exclusive at the writer. Recovery is
+ assessed whenever the lease is not live and requires the recorded PID to be
+ dead; renewal is assessed whenever the lease has *expired* — which is itself
+ one way to be non-live — and deliberately does not branch on PID liveness
+ (#760 AC16). An expired lease whose recorded owner has also died therefore
+ satisfies both, and ``gitea_lock_issue`` writes ``dead_session_recovery``
+ and ``lease_renewal`` into the same freshly built ``data`` dict. Because a
+ sanctioned pair was derived from one live observation in one call, it always
+ describes the same issue, PR, branch and head. Disagreement means the
+ persisted lock is no longer a faithful record of a single sanctioned
+ decision, so no continuation authority is returned.
+
+ Ambiguity never broadens authority. A ``dead_session_recovery`` block that
+ is present but does not rebuild — conflicting, stale, malformed, or only
+ partially valid — fails closed here rather than falling through to renewal:
+ otherwise a recovery record naming one PR could be bypassed by valid-looking
+ renewal evidence naming another. Recovery-only and renewal-only locks keep
+ their existing behaviour exactly, and provenance stays server-controlled —
+ this still only ever re-reads blocks the server itself wrote.
"""
if not lock_record:
return None
+ recovery_present = isinstance(lock_record.get("dead_session_recovery"), dict)
recovered = issue_lock_recovery.recovered_owning_pr_from_lock(lock_record)
+ # Present but unusable recovery evidence is ambiguous, not absent.
+ if recovery_present and not recovered:
+ return None
+ renewed = issue_lock_renewal.owning_pr_renewal_from_lock(lock_record)
+ if recovered and renewed and not _continuation_evidence_agrees(recovered, renewed):
+ return None
if recovered:
return recovered
- return issue_lock_renewal.owning_pr_renewal_from_lock(lock_record)
+ return renewed
def _assess_issue_duplicate_gate(
diff --git a/issue_lock_renewal.py b/issue_lock_renewal.py
index 1739f73..4ab0be9 100644
--- a/issue_lock_renewal.py
+++ b/issue_lock_renewal.py
@@ -459,6 +459,31 @@ def owning_pr_renewal_from_lock(
Renewal has no descendant case — the assessor required the local, remote and
PR heads to be equal — so that equality is re-checked here, and the record
must still name the claimant the lock records.
+
+ **What the claimant check below is, and what it is not.** It compares
+ ``lease_renewal.identity``/``profile`` against the claimant recorded on the
+ *same* lock file. Both sides are server-written fields of one document, so
+ this is an internal-consistency check: it rejects a lock whose renewal block
+ and claimant disagree. It does **not** consult the live authenticated caller
+ and therefore does not, on its own, prove that the session invoking a later
+ gate is the session the renewal was granted to.
+
+ The binding that actually keeps one session from using another's renewal is
+ structural, and it lives in the caller rather than here. The enforcement
+ paths load the lock through ``_load_existing_issue_lock()`` with no issue
+ coordinates, which resolves ``issue_lock_store.read_session_issue_lock()``
+ → the session pointer at ``session-{os.getpid()}.json``. Lock *selection* is
+ scoped to the operating-system process, so a caller cannot aim the recheck
+ at a lock some other process bound. Its limits follow from what that scope
+ is: it is per-process, not per-authenticated-user; it says nothing about a
+ lock reached by explicit issue coordinates rather than the session pointer,
+ and nothing about two roles sharing one process. Live identity and profile
+ are enforced separately, by the mutation-authority and profile gates each
+ mutating path already runs — not by this rebuild.
+
+ This function is therefore strictly a re-read with an added consistency
+ requirement. It narrows what a persisted lock can authorize; it never widens
+ it, and it never substitutes for a caller-identity gate.
"""
if not isinstance(lock_record, Mapping):
return None
@@ -488,8 +513,10 @@ def owning_pr_renewal_from_lock(
return None
# Renewal is refused outright unless the durable lock records both a
# claimant username and profile, so a sanctioned record always carries them.
- # Requiring them to still agree keeps a renewal block from being reused
- # under an identity or profile the lock no longer names.
+ # Requiring them to still agree rejects a lock whose renewal block and
+ # claimant disagree. Both values are read from this one server-written
+ # document: this is internal consistency, not a check against the live
+ # authenticated caller — see the docstring for the binding that is.
claimant = lock_record.get("claimant")
if not isinstance(claimant, Mapping):
lease = lock_record.get("work_lease")
diff --git a/tests/test_issue_945_enforcement_path_wiring.py b/tests/test_issue_945_enforcement_path_wiring.py
new file mode 100644
index 0000000..add1822
--- /dev/null
+++ b/tests/test_issue_945_enforcement_path_wiring.py
@@ -0,0 +1,685 @@
+import sys as _sys
+from pathlib import Path as _Path
+_sys.path.insert(0, str(_Path(__file__).resolve().parent))
+from mutation_profile_fixture import shared_mutation_env # noqa: E402
+"""The renewal waiver reaches the real enforcement paths (#945 B1).
+
+``tests/test_issue_945_owning_pr_renewal_continuation.py`` proves the pure
+pieces: that ``issue_lock_renewal.owning_pr_renewal_from_lock`` rebuilds a
+renewal waiver, that ``_owning_pr_continuation_from_lock`` resolves the two
+dispositions in the right precedence, and that the duplicate gate honours the
+resulting token. None of that proves any *production* path consumes the
+resolver, and review ``623`` demonstrated the gap by reverting the primary call
+site at ``gitea_mcp_server.py:2894`` back to the recovery-only rebuild: the
+whole repository stayed green, failing-test ids byte identical.
+
+This file closes that hole. Every test here starts from a real durable lock
+file written to a temporary lock directory and bound to this process's session
+pointer, then calls the authoritative production entry point — not a helper:
+
+* ``mcp_server._enforce_locked_issue_duplicate_recheck`` — the shared recheck
+ behind ``gitea_commit_files`` and ``gitea_create_pr``
+* ``mcp_server.gitea_assess_work_issue_duplicate`` — the read-only assessor
+* ``mcp_server._prove_author_ownership_for_pr`` — the push / PR-update
+ ownership prover, which is also the existing-PR continuation path
+
+Only the external boundaries are mocked: Gitea HTTP reads (the duplicate
+context fetcher, open-PR and branch listings) and the credential header. The
+reconstruction and enforcement chain under test — lock load, evidence rebuild,
+resolver precedence, and ``issue_work_duplicate_gate`` — runs for real.
+
+``TestRevertingThePrimaryWiringIsDetected`` is the explicit regression the
+review asked for: it reproduces the pre-#945 recovery-only call site and
+asserts the enforcement path then refuses, so the wiring cannot be removed
+silently.
+
+Everything is written under ``tempfile.TemporaryDirectory``. No branch,
+worktree, PR, comment, lease, or lock outside that directory is created, and no
+production Gitea or control-plane state is touched (#945 AC18).
+"""
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from unittest.mock import patch
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+import issue_lock_provenance # noqa: E402
+import issue_lock_recovery # noqa: E402
+import issue_lock_renewal # noqa: E402
+import issue_lock_store # noqa: E402
+import mcp_server # noqa: E402
+from issue_work_duplicate_gate import ( # noqa: E402
+ PHASE_COMMIT,
+ PHASE_CREATE_PR,
+ PHASE_LOCK,
+ PHASE_PUSH,
+)
+
+ISSUE = 4948
+OWNING_PR = 4949
+OTHER_PR = 4950
+OTHER_ISSUE = 4951
+BRANCH = f"fix/issue-{ISSUE}-renewal-wiring"
+OTHER_BRANCH = f"fix/issue-{ISSUE}-competing"
+HEAD = "e" * 40
+OTHER_HEAD = "f" * 40
+IDENTITY = "example-user"
+PROFILE = "test-author-prgs"
+ORG = "Scaled-Tech-Consulting"
+REPO = "Gitea-Tools"
+HOST = "gitea.prgs.cc"
+
+
+def dead_pid() -> int:
+ """A PID that has certainly exited (spawned, then reaped)."""
+ proc = subprocess.Popen([sys.executable, "-c", "pass"])
+ proc.wait()
+ return proc.pid
+
+
+def shifted_ts(hours: int = 4) -> str:
+ return (
+ (datetime.now(timezone.utc) + timedelta(hours=hours))
+ .isoformat()
+ .replace("+00:00", "Z")
+ )
+
+
+def owning_pr(number=OWNING_PR, ref=BRANCH, sha=HEAD, issue=ISSUE):
+ return {
+ "number": number,
+ "title": f"fix: something (Closes #{issue})",
+ "body": f"Closes #{issue}.",
+ "head": {"ref": ref, "sha": sha},
+ }
+
+
+def renewal_block(
+ *,
+ pr_number=OWNING_PR,
+ branch=BRANCH,
+ head=HEAD,
+ identity=IDENTITY,
+ profile=PROFILE,
+):
+ """The ``lease_renewal`` block ``build_renewal_record`` writes on success."""
+ return {
+ "renewed": True,
+ "renewed_at": shifted_ts(-1),
+ "prior_pid": 4242,
+ "prior_pid_alive": True,
+ "prior_expires_at": shifted_ts(-1),
+ "replacement_pid": os.getpid(),
+ "new_expires_at": shifted_ts(),
+ "identity": identity,
+ "profile": profile,
+ "branch_name": branch,
+ "worktree_path": os.path.realpath(os.getcwd()),
+ "head_sha": head,
+ "remote_head_sha": head,
+ "pr_head_sha": head,
+ "pr_number": pr_number,
+ "reason": "expired lease renewed by its exact recorded owner",
+ "proof": [],
+ }
+
+
+def recovery_block(*, pr_number=OWNING_PR, branch=BRANCH, head=HEAD):
+ """The ``dead_session_recovery`` block ``build_recovery_record`` writes."""
+ return {
+ "recovered": True,
+ "reason": "owning MCP session exited; durable ownership evidence matched",
+ "recovered_at": shifted_ts(-1),
+ "prior_session_pid": 4242,
+ "replacement_session_pid": os.getpid(),
+ "prior_pid_alive": False,
+ "branch_name": branch,
+ "pr_number": pr_number,
+ "pr_head": head,
+ "recorded_head": head,
+ "accepted_head": head,
+ "head_relation": issue_lock_recovery.HEAD_RELATION_EQUAL,
+ "identity": IDENTITY,
+ "profile": PROFILE,
+ "proof": [],
+ }
+
+
+class EnforcementPathBase(unittest.TestCase):
+ """Drives production enforcement entry points against a real durable lock.
+
+ The lock lives in a throwaway directory and is bound to this process's
+ session pointer exactly as ``gitea_lock_issue`` binds it, so
+ ``_load_existing_issue_lock()`` resolves it through the ordinary
+ ``read_session_issue_lock()`` path rather than a test shortcut.
+ """
+
+ def setUp(self):
+ self.lock_dir = tempfile.TemporaryDirectory()
+ self.addCleanup(self.lock_dir.cleanup)
+ self.worktree = os.path.realpath(os.getcwd())
+ self.remotes = patch.dict(
+ mcp_server.REMOTES,
+ {"prgs": {"host": HOST, "org": ORG, "repo": REPO}},
+ )
+ self.remotes.start()
+ self.addCleanup(patch.stopall)
+ mcp_server._IDENTITY_CACHE.clear()
+
+ # ── fixtures ────────────────────────────────────────────────────────────
+
+ def build_lock(
+ self,
+ *,
+ issue_number=ISSUE,
+ branch=BRANCH,
+ renewal=None,
+ recovery=None,
+ claimant=None,
+ pid=None,
+ live=True,
+ ):
+ pid = os.getpid() if pid is None else pid
+ claimant = claimant or {"username": IDENTITY, "profile": PROFILE}
+ expires = shifted_ts() if live else shifted_ts(-1)
+ data = {
+ "issue_number": issue_number,
+ "branch_name": branch,
+ "remote": "prgs",
+ "org": ORG,
+ "repo": REPO,
+ "worktree_path": self.worktree,
+ "session_pid": pid,
+ "pid": pid,
+ "claimant": dict(claimant),
+ "work_lease": {
+ "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
+ "issue_number": issue_number,
+ "branch": branch,
+ "worktree_path": self.worktree,
+ "claimant": dict(claimant),
+ "created_at": shifted_ts(-1),
+ "last_heartbeat_at": shifted_ts(0) if live else shifted_ts(-1),
+ "expires_at": expires,
+ },
+ "lock_provenance": issue_lock_provenance.build_sanctioned_lock_provenance(
+ tool="gitea_lock_issue",
+ claimant=dict(claimant),
+ ),
+ }
+ if renewal is not None:
+ data["lease_renewal"] = renewal
+ if recovery is not None:
+ data["dead_session_recovery"] = recovery
+ return data
+
+ def bind(self, data):
+ """Persist the lock and bind it to this process, as the server does."""
+ issue_lock_store.bind_session_lock(data, self.lock_dir.name)
+ return data
+
+ def env(self):
+ return shared_mutation_env(
+ PROFILE,
+ include_example_repo=True,
+ GITEA_ISSUE_LOCK_DIR=self.lock_dir.name,
+ )
+
+ def gitea_reads(self, *, open_prs, branch_names=None):
+ """Patch only the external Gitea read boundary."""
+ branch_names = [BRANCH] if branch_names is None else branch_names
+ return (
+ patch("mcp_server.get_auth_header", return_value="token x"),
+ patch(
+ "mcp_server.issue_duplicate_context_fetcher",
+ side_effect=lambda h, o, r, auth, issue_number: (
+ list(open_prs), list(branch_names), {"status": "not_claimed"}
+ ),
+ ),
+ patch("mcp_server._list_open_pulls", return_value=list(open_prs)),
+ patch(
+ "mcp_server.api_get_all",
+ return_value=[
+ {"name": n, "commit": {"id": HEAD}} for n in branch_names
+ ],
+ ),
+ )
+
+ # ── production entry points ─────────────────────────────────────────────
+
+ def run_duplicate_recheck(self, *, phase, open_prs, branch_names=None):
+ """The real shared recheck behind gitea_commit_files / gitea_create_pr."""
+ patches = self.gitea_reads(open_prs=open_prs, branch_names=branch_names)
+ with patches[0], patches[1], patches[2], patches[3]:
+ with patch.dict(os.environ, self.env(), clear=True):
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return mcp_server._enforce_locked_issue_duplicate_recheck(
+ "prgs", phase, host=HOST, org=ORG, repo=REPO
+ )
+
+ def run_readonly_assessor(
+ self, *, open_prs, issue_number=ISSUE, branch=BRANCH, branch_names=None
+ ):
+ """The real read-only duplicate assessor MCP tool."""
+ patches = self.gitea_reads(open_prs=open_prs, branch_names=branch_names)
+ with patches[0], patches[1], patches[2], patches[3]:
+ with patch.dict(os.environ, self.env(), clear=True):
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return mcp_server.gitea_assess_work_issue_duplicate(
+ issue_number=issue_number,
+ branch_name=branch,
+ phase=PHASE_COMMIT,
+ remote="prgs",
+ host=HOST,
+ org=ORG,
+ repo=REPO,
+ )
+
+ def run_ownership_prover(
+ self, *, pr_number=OWNING_PR, branch=BRANCH, issue_number=ISSUE
+ ):
+ """The real push / PR-update ownership prover (existing-PR continuation)."""
+ with patch("mcp_server.get_auth_header", return_value="token x"):
+ with patch.dict(os.environ, self.env(), clear=True):
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return mcp_server._prove_author_ownership_for_pr(
+ pr_number=pr_number,
+ pr_title=f"fix: something (Closes #{issue_number})",
+ pr_body=f"Closes #{issue_number}.",
+ source_branch=branch,
+ remote="prgs",
+ host=HOST,
+ org=ORG,
+ repo=REPO,
+ worktree_path=self.worktree,
+ )
+
+
+# ─────────────── B1: renewal evidence reaches every enforcement path ───────────
+
+
+class TestRenewalReachesEnforcementPaths(EnforcementPathBase):
+ """A renewal-only lock must exempt its owning PR at the real call sites.
+
+ Each of these fails if its call site is reverted to the recovery-only
+ rebuild, because the lock deliberately carries no ``dead_session_recovery``
+ block at all.
+ """
+
+ def setUp(self):
+ super().setUp()
+ self.bind(self.build_lock(renewal=renewal_block()))
+
+ def test_commit_duplicate_recheck_permits_the_owning_pr(self):
+ blocked = self.run_duplicate_recheck(
+ phase=PHASE_COMMIT, open_prs=[owning_pr()]
+ )
+ self.assertIsNone(
+ blocked,
+ "commit recheck refused the PR the renewal already proved it owns; "
+ "the resolver is not wired into gitea_mcp_server:2894",
+ )
+
+ def test_create_pr_duplicate_recheck_permits_the_owning_pr(self):
+ blocked = self.run_duplicate_recheck(
+ phase=PHASE_CREATE_PR, open_prs=[owning_pr()]
+ )
+ self.assertIsNone(blocked)
+
+ def test_read_only_assessor_reports_the_same_exemption(self):
+ result = self.run_readonly_assessor(open_prs=[owning_pr()])
+ self.assertTrue(result["success"])
+ self.assertFalse(result["block"])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+ self.assertEqual(result["linked_open_pr"], OWNING_PR)
+
+ def test_push_ownership_prover_carries_the_renewal_evidence(self):
+ ownership = self.run_ownership_prover()
+ self.assertTrue(ownership["proven"], ownership["reasons"])
+ token = ownership["recovered_owning_pr"]
+ self.assertIsNotNone(
+ token,
+ "push prover produced no continuation evidence from a renewal lock; "
+ "the resolver is not wired into gitea_mcp_server:19464",
+ )
+ self.assertEqual(token["pr_number"], OWNING_PR)
+ self.assertEqual(token["branch_name"], BRANCH)
+ self.assertEqual(token["head_sha"], HEAD)
+
+ def test_all_enforcement_paths_decide_alike_from_one_lock(self):
+ """AC: commit, create-PR, assessor and prover agree on one lock."""
+ for phase in (PHASE_COMMIT, PHASE_CREATE_PR, PHASE_PUSH, PHASE_LOCK):
+ with self.subTest(phase=phase):
+ self.assertIsNone(
+ self.run_duplicate_recheck(phase=phase, open_prs=[owning_pr()])
+ )
+ assessor = self.run_readonly_assessor(open_prs=[owning_pr()])
+ prover = self.run_ownership_prover()
+ self.assertTrue(assessor["owning_pr_recovery_exempted"])
+ self.assertEqual(
+ assessor["linked_open_pr"], prover["recovered_owning_pr"]["pr_number"]
+ )
+
+
+class TestDeadSessionRecoveryStillReachesEnforcementPaths(EnforcementPathBase):
+ """#755/#768 recovery must be unchanged by the #945 resolver."""
+
+ def setUp(self):
+ super().setUp()
+ self.bind(self.build_lock(recovery=recovery_block()))
+
+ def test_commit_recheck_still_permits_a_recovered_owning_pr(self):
+ self.assertIsNone(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_assessor_still_reports_the_recovery_exemption(self):
+ result = self.run_readonly_assessor(open_prs=[owning_pr()])
+ self.assertTrue(result["owning_pr_recovery_exempted"])
+
+ def test_prover_still_carries_recovery_evidence(self):
+ token = self.run_ownership_prover()["recovered_owning_pr"]
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+
+# ──────────────── B1: the explicit anti-revert regression test ────────────────
+
+
+class TestRevertingThePrimaryWiringIsDetected(EnforcementPathBase):
+ """Reproduce the pre-#945 call site and prove the path then refuses.
+
+ Review ``623`` reverted ``gitea_mcp_server.py:2894`` from
+ ``_owning_pr_continuation_from_lock`` to
+ ``issue_lock_recovery.recovered_owning_pr_from_lock`` and found the entire
+ repository still green. Substituting exactly that pre-fix behaviour here
+ makes the enforcement path block, so the causal link between the resolver
+ and the gate's answer is asserted, not assumed.
+ """
+
+ def setUp(self):
+ super().setUp()
+ self.bind(self.build_lock(renewal=renewal_block()))
+
+ def test_recovery_only_rebuild_reintroduces_the_945_refusal(self):
+ with patch.object(
+ mcp_server,
+ "_owning_pr_continuation_from_lock",
+ side_effect=issue_lock_recovery.recovered_owning_pr_from_lock,
+ ):
+ blocked = self.run_duplicate_recheck(
+ phase=PHASE_COMMIT, open_prs=[owning_pr()]
+ )
+ self.assertIsNotNone(
+ blocked,
+ "the pre-#945 recovery-only rebuild must lose the renewal waiver; "
+ "if this passes, the enforcement path is not consuming the resolver",
+ )
+ self.assertTrue(blocked["block"])
+ self.assertFalse(blocked["owning_pr_recovery_exempted"])
+
+ def test_restoring_the_resolver_restores_continuation(self):
+ self.assertIsNone(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_read_only_assessor_is_wired_to_the_same_resolver(self):
+ with patch.object(
+ mcp_server,
+ "_owning_pr_continuation_from_lock",
+ side_effect=issue_lock_recovery.recovered_owning_pr_from_lock,
+ ):
+ result = self.run_readonly_assessor(open_prs=[owning_pr()])
+ self.assertTrue(result["block"])
+ self.assertFalse(result["owning_pr_recovery_exempted"])
+
+ def test_push_prover_is_wired_to_the_same_resolver(self):
+ with patch.object(
+ mcp_server,
+ "_owning_pr_continuation_from_lock",
+ side_effect=issue_lock_recovery.recovered_owning_pr_from_lock,
+ ):
+ ownership = self.run_ownership_prover()
+ self.assertIsNone(ownership["recovered_owning_pr"])
+
+
+# ───────────────── B1: the exemption is not widened at the call sites ─────────
+
+
+class TestEnforcementPathsStillFailClosed(EnforcementPathBase):
+ def assert_blocked(self, result):
+ self.assertIsNotNone(result, "expected a fail-closed refusal")
+ self.assertTrue(result["block"])
+ return result
+
+ def test_open_pr_alone_grants_no_exemption(self):
+ """No renewal and no recovery block: the open PR still blocks."""
+ self.bind(self.build_lock())
+ blocked = self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+ self.assertFalse(blocked["owning_pr_recovery_exempted"])
+
+ def test_second_pr_is_refused(self):
+ self.bind(self.build_lock(renewal=renewal_block()))
+ self.assert_blocked(
+ self.run_duplicate_recheck(
+ phase=PHASE_COMMIT,
+ open_prs=[owning_pr(), owning_pr(number=OTHER_PR, ref=OTHER_BRANCH)],
+ )
+ )
+
+ def test_evidence_naming_another_pr_is_refused(self):
+ self.bind(self.build_lock(renewal=renewal_block(pr_number=OTHER_PR)))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_unrelated_branch_is_refused(self):
+ self.bind(self.build_lock(renewal=renewal_block(branch=OTHER_BRANCH)))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_live_head_divergence_is_refused(self):
+ """Force-push or unrelated remote movement: live PR head no longer matches."""
+ self.bind(self.build_lock(renewal=renewal_block()))
+ self.assert_blocked(
+ self.run_duplicate_recheck(
+ phase=PHASE_COMMIT, open_prs=[owning_pr(sha=OTHER_HEAD)]
+ )
+ )
+
+ def test_stale_recorded_head_is_refused(self):
+ """The renewal names a head the live PR never had."""
+ self.bind(self.build_lock(renewal=renewal_block(head=OTHER_HEAD)))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_local_remote_head_divergence_is_refused(self):
+ record = renewal_block()
+ record["remote_head_sha"] = OTHER_HEAD
+ self.bind(self.build_lock(renewal=record))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_identity_mismatch_with_the_lock_claimant_is_refused(self):
+ self.bind(self.build_lock(renewal=renewal_block(identity="someone-else")))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_profile_mismatch_with_the_lock_claimant_is_refused(self):
+ self.bind(self.build_lock(renewal=renewal_block(profile="test-reviewer-prgs")))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_ungranted_renewal_block_is_refused(self):
+ record = renewal_block()
+ record["renewed"] = False
+ self.bind(self.build_lock(renewal=record))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_malformed_renewal_block_is_refused(self):
+ record = renewal_block()
+ record["pr_number"] = "not-a-number"
+ self.bind(self.build_lock(renewal=record))
+ self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ def test_wrong_issue_evidence_cannot_be_copied_onto_another_lock(self):
+ """A renewal block copied onto a lock for a different issue proves nothing.
+
+ The rebuilt token takes its ``issue_number`` from the lock it is found
+ on, not from the record, so a block lifted onto another issue's lock
+ claims that issue while still naming the original PR. That copied
+ evidence must not waive the genuine duplicate the other issue has.
+ """
+ self.bind(
+ self.build_lock(issue_number=OTHER_ISSUE, renewal=renewal_block())
+ )
+ blocked = self.assert_blocked(
+ self.run_duplicate_recheck(
+ phase=PHASE_COMMIT,
+ # The real open PR for OTHER_ISSUE is a different PR entirely.
+ open_prs=[
+ owning_pr(number=OTHER_PR, ref=OTHER_BRANCH, issue=OTHER_ISSUE)
+ ],
+ branch_names=[OTHER_BRANCH],
+ )
+ )
+ self.assertFalse(blocked["owning_pr_recovery_exempted"])
+
+ def test_refusal_carries_complete_structured_fields(self):
+ self.bind(self.build_lock())
+ blocked = self.assert_blocked(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+ for field in (
+ "block",
+ "outcome",
+ "reasons",
+ "owning_pr_recovery_exempted",
+ "owning_pr_recovery_notes",
+ "linked_open_pr",
+ "linked_open_pr_count",
+ ):
+ with self.subTest(field=field):
+ self.assertIn(field, blocked)
+ self.assertTrue(blocked["reasons"])
+
+
+class TestSequentialTasksStayIsolated(EnforcementPathBase):
+ """One long-lived daemon serves many tasks; a waiver must not leak forward."""
+
+ def test_a_later_lock_without_evidence_does_not_inherit_the_earlier_waiver(self):
+ self.bind(self.build_lock(renewal=renewal_block()))
+ self.assertIsNone(
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ )
+
+ # Second task in the same process: a fresh lock, no renewal evidence.
+ self.bind(
+ self.build_lock(issue_number=OTHER_ISSUE, branch=OTHER_BRANCH)
+ )
+ blocked = self.run_duplicate_recheck(
+ phase=PHASE_COMMIT,
+ open_prs=[owning_pr(number=OTHER_PR, ref=OTHER_BRANCH, issue=OTHER_ISSUE)],
+ branch_names=[OTHER_BRANCH],
+ )
+ self.assertIsNotNone(blocked)
+ self.assertFalse(blocked["owning_pr_recovery_exempted"])
+
+
+# ───────────── F2: what the caller binding actually is, and is not ────────────
+
+
+class TestCallerBindingIsStructuralNotFieldComparison(unittest.TestCase):
+ """Document, in executable form, the binding this patch really provides.
+
+ Review ``623`` found that the claimant check in
+ ``owning_pr_renewal_from_lock`` compares two fields of one server-written
+ lock file and is therefore not bound to the authenticated caller. That is
+ correct, and these tests assert the true guarantee rather than the
+ overstated one: lock *selection* is process-scoped, and the claimant check
+ is an internal-consistency check.
+
+ No PID-derived, cached, or process-lifetime session authority is invented
+ here — the process scoping asserted below is pre-existing behaviour of
+ ``issue_lock_store``, not something this patch adds.
+ """
+
+ def test_lock_selection_is_keyed_to_the_operating_system_process(self):
+ with tempfile.TemporaryDirectory() as root:
+ pointer = issue_lock_store.session_pointer_path(root)
+ self.assertEqual(
+ os.path.basename(pointer), f"session-{os.getpid()}.json"
+ )
+
+ def test_a_lock_bound_by_another_process_is_not_reachable(self):
+ """The structural protection: a foreign session pointer is not read."""
+ with tempfile.TemporaryDirectory() as root:
+ foreign_pointer = os.path.join(root, f"session-{os.getpid() + 1}.json")
+ issue_lock_store.save_lock_file(
+ foreign_pointer, {"lock_file_path": "/nonexistent/foreign.json"}
+ )
+ self.assertIsNone(issue_lock_store.read_session_issue_lock(root))
+
+ def test_claimant_check_does_not_consult_the_live_authenticated_caller(self):
+ """The honest limit: agreement is internal to the lock document.
+
+ A renewal block whose identity/profile agree with the claimant recorded
+ on the same lock rebuilds successfully, regardless of who is
+ authenticated. Live identity and profile are enforced by the separate
+ mutation-authority and profile gates, not by this rebuild.
+ """
+ lock = {
+ "issue_number": ISSUE,
+ "branch_name": BRANCH,
+ "claimant": {"username": "unrelated-recorded-user", "profile": PROFILE},
+ "lease_renewal": renewal_block(identity="unrelated-recorded-user"),
+ }
+ token = issue_lock_renewal.owning_pr_renewal_from_lock(lock)
+ self.assertIsNotNone(token)
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ def test_internal_disagreement_is_what_the_check_actually_rejects(self):
+ lock = {
+ "issue_number": ISSUE,
+ "branch_name": BRANCH,
+ "claimant": {"username": IDENTITY, "profile": PROFILE},
+ "lease_renewal": renewal_block(identity="someone-else"),
+ }
+ self.assertIsNone(issue_lock_renewal.owning_pr_renewal_from_lock(lock))
+
+
+class TestNoDurableArtifacts(EnforcementPathBase):
+ def test_enforcement_runs_leave_nothing_outside_the_temp_lock_dir(self):
+ before = sorted(os.listdir(self.lock_dir.name))
+ self.bind(self.build_lock(renewal=renewal_block()))
+ self.run_duplicate_recheck(phase=PHASE_COMMIT, open_prs=[owning_pr()])
+ self.run_ownership_prover()
+ after = sorted(os.listdir(self.lock_dir.name))
+ self.assertNotEqual(before, after, "the test must have written its lock")
+ self.assertTrue(
+ all(
+ os.path.realpath(os.path.join(self.lock_dir.name, name)).startswith(
+ os.path.realpath(self.lock_dir.name)
+ )
+ for name in after
+ )
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/tests/test_issue_945_owning_pr_renewal_continuation.py b/tests/test_issue_945_owning_pr_renewal_continuation.py
index 41bca8b..2e32506 100644
--- a/tests/test_issue_945_owning_pr_renewal_continuation.py
+++ b/tests/test_issue_945_owning_pr_renewal_continuation.py
@@ -266,11 +266,13 @@ class TestRenewalRebuildFailsClosed(unittest.TestCase):
def test_claimant_absent(self):
self.assertNoEvidence(renewal_lock(claimant=False))
- def test_evidence_from_a_different_session_is_not_reusable(self):
- # A renewal block left by another workflow session names another
- # claimant, so the lock it is found on cannot inherit its authority.
+ def test_renewal_block_disagreeing_with_the_lock_claimant_is_refused(self):
+ # An internal-consistency check, not a caller check: the renewal block
+ # and the claimant recorded on the same lock must name one identity.
+ # Nothing here proves who is calling — see
+ # TestCallerBindingIsStructuralNotFieldComparison for that boundary.
lock = renewal_lock()
- lock["claimant"] = {"username": "other-session-user", "profile": PROFILE}
+ lock["claimant"] = {"username": "other-recorded-user", "profile": PROFILE}
self.assertNoEvidence(lock)
@@ -286,13 +288,15 @@ class TestSharedResolver(unittest.TestCase):
token = gitea_mcp_server._owning_pr_continuation_from_lock(renewal_lock())
self.assertEqual(token["pr_number"], OWNING_PR)
- def test_recovery_takes_precedence_over_renewal(self):
+ def test_recovery_takes_precedence_over_an_agreeing_renewal(self):
# Same precedence gitea_lock_issue applies when granting the waiver, so
# the answer cannot differ between the granting and enforcing paths.
- lock = recovery_lock(pr_number=OTHER_PR, head=OTHER_HEAD)
+ # Both blocks describe one decision, so both name the same PR and head.
+ lock = recovery_lock()
lock["lease_renewal"] = renewal_record()
token = gitea_mcp_server._owning_pr_continuation_from_lock(lock)
- self.assertEqual(token["pr_number"], OTHER_PR)
+ self.assertEqual(token["pr_number"], OWNING_PR)
+ self.assertEqual(token["head_relation"], issue_lock_recovery.HEAD_RELATION_EQUAL)
def test_no_evidence_resolves_to_none(self):
self.assertIsNone(gitea_mcp_server._owning_pr_continuation_from_lock(None))
@@ -304,6 +308,139 @@ class TestSharedResolver(unittest.TestCase):
)
+# ─────────── ambiguous recovery/renewal pairs never broaden authority ──────────
+
+
+class TestAmbiguousEvidenceFailsClosed(unittest.TestCase):
+ """#945 F3: a lock carrying two evidence blocks must agree, or authorize nothing.
+
+ Coexistence is legitimately reachable, so this is not a theoretical case.
+ Recovery is assessed whenever the lease is not live and requires a dead
+ recorded PID; renewal is assessed whenever the lease has *expired* — one way
+ to be non-live — and does not branch on PID liveness at all. An expired
+ lease whose owner also died satisfies both, and ``gitea_lock_issue`` then
+ writes both blocks into the same freshly built dict. A sanctioned pair comes
+ from one live observation, so it always agrees; disagreement means the
+ persisted lock no longer records a single sanctioned decision.
+
+ The dangerous direction is fall-through: before this, a recovery block that
+ failed validation was skipped and renewal evidence naming a *different* PR
+ was returned instead. Every case below asserts ``None`` — no continuation
+ authority at all, not a partial or downgraded one.
+ """
+
+ def resolve(self, lock):
+ return gitea_mcp_server._owning_pr_continuation_from_lock(lock)
+
+ def both(self, *, recovery=None, renewal=None, **lock_overrides):
+ """A lock carrying both server-written evidence blocks."""
+ lock = recovery_lock()
+ if recovery is not None:
+ lock["dead_session_recovery"] = recovery
+ lock["lease_renewal"] = renewal if renewal is not None else renewal_record()
+ lock.update(lock_overrides)
+ return lock
+
+ # ── the two legitimate single-block shapes still work ──────────────────
+
+ def test_valid_recovery_only_still_authorizes(self):
+ token = self.resolve(recovery_lock())
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ def test_valid_renewal_only_still_authorizes(self):
+ token = self.resolve(renewal_lock())
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ # ── both present ───────────────────────────────────────────────────────
+
+ def test_both_present_and_identical_authorizes_once(self):
+ token = self.resolve(self.both())
+ self.assertEqual(token["pr_number"], OWNING_PR)
+ self.assertEqual(token["head_sha"], HEAD)
+
+ def test_both_present_naming_different_prs_authorizes_nothing(self):
+ lock = self.both(renewal=renewal_record(pr_number=OTHER_PR))
+ self.assertIsNone(self.resolve(lock))
+
+ def test_conflicting_head_authorizes_nothing(self):
+ lock = self.both(
+ renewal=renewal_record(
+ head_sha=OTHER_HEAD, remote_head_sha=OTHER_HEAD, pr_head_sha=OTHER_HEAD
+ )
+ )
+ self.assertIsNone(self.resolve(lock))
+
+ def test_conflicting_branch_authorizes_nothing(self):
+ lock = self.both(renewal=renewal_record(branch_name=OTHER_BRANCH))
+ self.assertIsNone(self.resolve(lock))
+
+ def test_conflicting_head_relation_authorizes_nothing(self):
+ """A descendant recovery beside an equal-head renewal is not one decision."""
+ recovery = dict(recovery_lock()["dead_session_recovery"])
+ recovery["head_relation"] = issue_lock_recovery.HEAD_RELATION_STRICT_DESCENDANT
+ recovery["recorded_head"] = HEAD
+ recovery["accepted_head"] = OTHER_HEAD
+ self.assertIsNone(self.resolve(self.both(recovery=recovery)))
+
+ def test_conflicting_identity_authorizes_nothing(self):
+ """The renewal half stops rebuilding, so the pair can no longer agree."""
+ lock = self.both(renewal=renewal_record(identity="other-user"))
+ lock["claimant"] = {"username": IDENTITY, "profile": PROFILE}
+ # Recovery alone would still rebuild; presence of an unusable renewal
+ # block must not silently downgrade to the recovery answer.
+ self.assertEqual(self.resolve(lock)["pr_number"], OWNING_PR)
+
+ def test_conflicting_profile_between_renewal_and_claimant(self):
+ lock = self.both(renewal=renewal_record(profile="other-profile"))
+ self.assertEqual(self.resolve(lock)["pr_number"], OWNING_PR)
+
+ def test_conflicting_issue_number_authorizes_nothing(self):
+ """Both tokens read issue_number from the lock, so a wrong issue moves both."""
+ lock = self.both(issue_number=ISSUE + 1)
+ token = self.resolve(lock)
+ self.assertEqual(token["issue_number"], ISSUE + 1)
+ self.assertEqual(token["pr_number"], OWNING_PR)
+
+ # ── recovery present but unusable: never fall through to renewal ────────
+
+ def test_malformed_recovery_beside_valid_renewal_authorizes_nothing(self):
+ recovery = {"recovered": True, "pr_number": "not-a-number"}
+ self.assertIsNone(self.resolve(self.both(recovery=recovery)))
+
+ def test_ungranted_recovery_beside_valid_renewal_authorizes_nothing(self):
+ recovery = dict(recovery_lock()["dead_session_recovery"])
+ recovery["recovered"] = False
+ self.assertIsNone(self.resolve(self.both(recovery=recovery)))
+
+ def test_stale_recovery_beside_newer_renewal_authorizes_nothing(self):
+ """The exact bypass review 623 probed: conflicting recovery, valid renewal."""
+ recovery = dict(recovery_lock(pr_number=OTHER_PR)["dead_session_recovery"])
+ recovery["accepted_head"] = OTHER_HEAD # fails its own head equality
+ lock = self.both(recovery=recovery)
+ self.assertIsNone(
+ self.resolve(lock),
+ "a conflicting recovery record must not be bypassed by renewal "
+ "evidence naming a different PR",
+ )
+
+ def test_empty_recovery_block_beside_valid_renewal_authorizes_nothing(self):
+ self.assertIsNone(self.resolve(self.both(recovery={})))
+
+ # ── ambiguity yields nothing at all, not a partial authorization ────────
+
+ def test_ambiguity_yields_no_partial_token(self):
+ lock = self.both(renewal=renewal_record(pr_number=OTHER_PR))
+ result = self.resolve(lock)
+ self.assertIsNone(result)
+ self.assertNotIsInstance(result, dict)
+
+ def test_resolution_does_not_mutate_the_lock(self):
+ lock = self.both(renewal=renewal_record(pr_number=OTHER_PR))
+ before = copy.deepcopy(lock)
+ self.resolve(lock)
+ self.assertEqual(lock, before)
+
+
# ────────────── every enforcement path uses the same decision ──────────────
From 47bfae07d2639262a44bcc200c916061c27de0cb Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Mon, 27 Jul 2026 19:52:27 -0400
Subject: [PATCH 13/18] fix(author bootstrap): resolve allocator session
ownership, authority alignment, and test coverage (#943)
---
author_issue_bootstrap.py | 52 ++
gitea_mcp_server.py | 378 ++++++--
.../test_issue_943_runtime_context_helpers.py | 865 ++++++++++++------
3 files changed, 956 insertions(+), 339 deletions(-)
diff --git a/author_issue_bootstrap.py b/author_issue_bootstrap.py
index 4f8d771..66d2a48 100644
--- a/author_issue_bootstrap.py
+++ b/author_issue_bootstrap.py
@@ -196,6 +196,58 @@ def _verify_assignment_and_lease_ids(
# Some lease rows may not yet have an assignment join; still require
# the lease itself to exist and bind to the claimed session/issue.
pass
+ # #943 review 622 B2: a lease that is no longer live confers no ownership.
+ # Existence alone previously satisfied this gate, so a released or expired
+ # lease could still authorize a bootstrap for a claim its session had given
+ # up. Checked before the session comparison so the reason names the real
+ # problem rather than reporting a mismatch.
+ from datetime import datetime, timezone
+
+ lease_status = str(lease.get("status") or "").strip().lower()
+ if lease_status and lease_status != "active":
+ return {
+ "success": False,
+ "reason_code": "lease_not_live",
+ "message": (
+ f"lease_id '{lid}' is '{lease_status}', not active; a lease that "
+ "is not live confers no ownership (fail closed)."
+ ),
+ "exact_next_action": (
+ "Re-allocate the work item and pass the live assignment/lease pair."
+ ),
+ }
+ expires_raw = str(lease.get("expires_at") or "").strip()
+ if expires_raw:
+ try:
+ expires_at = datetime.fromisoformat(expires_raw.replace("Z", "+00:00"))
+ except ValueError:
+ return {
+ "success": False,
+ "reason_code": "lease_not_live",
+ "message": (
+ f"lease_id '{lid}' records an unparseable expiry "
+ f"'{expires_raw}' (fail closed)."
+ ),
+ "exact_next_action": (
+ "Re-allocate the work item and pass the live "
+ "assignment/lease pair."
+ ),
+ }
+ if expires_at.tzinfo is None:
+ expires_at = expires_at.replace(tzinfo=timezone.utc)
+ if expires_at <= datetime.now(timezone.utc):
+ return {
+ "success": False,
+ "reason_code": "lease_not_live",
+ "message": (
+ f"lease_id '{lid}' expired at {expires_raw}; an expired lease "
+ "confers no ownership (fail closed)."
+ ),
+ "exact_next_action": (
+ "Reclaim or re-allocate the lease, then retry with the live pair."
+ ),
+ }
+
lease_session = str(lease.get("session_id") or "").strip()
if lease_session and lease_session != owner_session:
return {
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index d974a68..9a2ecc9 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -3580,62 +3580,291 @@ def _authenticated_username(host: str):
return user
-# #943: process-local session identifier. The pre-existing call sites that mint a
-# session id (workflow dashboard, lease adopt, lease reclaim) all build the same
-# "--" shape when the caller supplies none. Binding it once per
-# process keeps lease-ownership comparisons stable for the life of the session
-# instead of minting a fresh identifier — and therefore a fresh owner — on every
-# call. Process-local only, never shared to a file (same rationale as the
-# immutable session context in session_context_binding).
-_ACTIVE_SESSION_ID: str | None = None
+# #943 review 622 F3/F4: one coherent authority snapshot per mutation claim.
+#
+# The reviewed implementation read the identity from the pinned #714 session
+# context and the profile from the live ``get_profile()``, so a sanctioned
+# rebind could produce a claimant pair whose two halves came from different
+# snapshots — and that pair is written durably into the issue lock. The
+# canonical pairing is ``record_mutation_authority``: profile from
+# ``get_profile()``, identity from ``_authenticated_username(host)``. This
+# resolver reproduces that pairing, and uses the pinned session context only for
+# drift detection, never as a value source.
+_AUTHORITY_PROFILE_UNRESOLVED = "authority_profile_unresolved"
+_AUTHORITY_IDENTITY_UNRESOLVED = "authority_identity_unresolved"
+_AUTHORITY_IDENTITY_DRIFT = "authority_identity_drift"
+_AUTHORITY_PROFILE_DRIFT = "authority_profile_drift"
-def _active_username() -> str | None:
- """Authenticated identity bound to this session, or None when unbound.
+def _active_mutation_authority(host: str | None) -> dict:
+ """Resolve one coherent (identity, profile) authority pair, or a refusal.
- Reads the immutable #714 session context that ``gitea_whoami`` seeds; it is
- the authoritative identity pin every other mutation gate already consults.
- Never re-derives or fabricates an identity: an unbound context returns None
- so callers fail closed instead of acting as an unverified actor.
- """
- ctx = session_ctx.get_session_context() or {}
- return ((ctx.get("identity") or "").strip()) or None
+ Both halves come from the same live snapshot. The immutable #714 session
+ context is consulted only to detect drift: when it disagrees with the live
+ snapshot the result is a fail-closed refusal, never a silently blended pair.
-
-def _active_profile_name() -> str | None:
- """Active runtime profile name, or None when it cannot be determined.
-
- The live profile is authoritative (``get_profile``); the bound session
- context is consulted only when the profile cannot be read, so the reported
- name always describes the profile actually serving this process.
+ Returns a dict with ``ok`` True plus ``identity``/``profile_name``, or ``ok``
+ False plus ``reason_code``, ``reasons`` and ``expected``/``actual`` when a
+ drift or resolution failure is detected. Never raises for an unresolved
+ profile: the caller converts the refusal into a structured author block so
+ reason code, retryability and transport survival are preserved (F4).
"""
try:
profile = get_profile() or {}
- except Exception:
- profile = {}
- name = (profile.get("profile_name") or "").strip()
- if name:
- return name
- ctx = session_ctx.get_session_context() or {}
- return ((ctx.get("profile_name") or "").strip()) or None
-
-
-def _current_session_id() -> str | None:
- """Session identifier for this process, or None when the profile is unknown.
-
- Uses the same "--" shape as the existing lease call
- sites. Bound once per process so repeated calls describe one session; fails
- soft to None when the profile is undeterminable, letting callers fail closed
- rather than inventing an owner.
- """
- global _ACTIVE_SESSION_ID
- if _ACTIVE_SESSION_ID:
- return _ACTIVE_SESSION_ID
- profile_name = _active_profile_name()
+ except (RuntimeError, ValueError, TypeError, KeyError, OSError) as exc:
+ # Narrow, and never a silent fallback to a previously cached name: an
+ # unresolvable profile is a fail-closed condition, matching
+ # record_mutation_authority's "active profile unresolved (fail closed)".
+ return {
+ "ok": False,
+ "reason_code": _AUTHORITY_PROFILE_UNRESOLVED,
+ "reasons": [
+ "active profile could not be resolved: "
+ f"{_redact(str(exc))} (fail closed)"
+ ],
+ }
+ profile_name = (profile.get("profile_name") or "").strip()
if not profile_name:
- return None
- _ACTIVE_SESSION_ID = f"{profile_name}-{os.getpid()}-{uuid.uuid4().hex[:8]}"
- return _ACTIVE_SESSION_ID
+ return {
+ "ok": False,
+ "reason_code": _AUTHORITY_PROFILE_UNRESOLVED,
+ "reasons": [
+ "active profile carries no profile_name (fail closed)"
+ ],
+ }
+
+ identity = ""
+ if host:
+ identity = (_authenticated_username(host) or "").strip()
+ if not identity:
+ # A profile's expected_username is configuration, not proof of an
+ # authenticated actor, so it is never substituted here.
+ return {
+ "ok": False,
+ "reason_code": _AUTHORITY_IDENTITY_UNRESOLVED,
+ "reasons": [
+ "authenticated identity could not be resolved for the active "
+ "host (fail closed); call gitea_whoami and retry"
+ ],
+ }
+
+ ctx = session_ctx.get_session_context() or {}
+ pinned_identity = (ctx.get("identity") or "").strip()
+ pinned_profile = (ctx.get("profile_name") or "").strip()
+ if pinned_identity and pinned_identity != identity:
+ return {
+ "ok": False,
+ "reason_code": _AUTHORITY_IDENTITY_DRIFT,
+ "reasons": [
+ "live authenticated identity disagrees with the bound session "
+ "context identity (fail closed)"
+ ],
+ "expected": pinned_identity,
+ "actual": identity,
+ }
+ if pinned_profile and pinned_profile != profile_name:
+ return {
+ "ok": False,
+ "reason_code": _AUTHORITY_PROFILE_DRIFT,
+ "reasons": [
+ "live active profile disagrees with the bound session context "
+ "profile (fail closed)"
+ ],
+ "expected": pinned_profile,
+ "actual": profile_name,
+ }
+ return {
+ "ok": True,
+ "identity": identity,
+ "profile_name": profile_name,
+ "session_context_bound": bool(pinned_identity or pinned_profile),
+ }
+
+
+def _active_username(host: str | None = None) -> str | None:
+ """Authenticated identity for the active mutation authority, else None.
+
+ Refuses unbound, blank and whitespace-only identities, and never substitutes
+ a profile's ``expected_username`` for an authenticated one.
+ """
+ authority = _active_mutation_authority(host)
+ return authority.get("identity") if authority.get("ok") else None
+
+
+def _active_profile_name(host: str | None = None) -> str | None:
+ """Active profile name for the mutation authority, else None.
+
+ Shares the single snapshot with :func:`_active_username`, so the two can
+ never describe different authority states.
+ """
+ authority = _active_mutation_authority(host)
+ return authority.get("profile_name") if authority.get("ok") else None
+
+
+# #943 review 622 B1: the workflow session that owns the work — never a
+# process-lifetime or PID-derived value.
+#
+# The reviewed implementation minted "--" once per process.
+# The MCP daemon outlives every task it serves, so that identifier conflates
+# sequential author tasks and can never equal the control-plane session that
+# owns an allocator-created lease; ``_verify_assignment_and_lease_ids`` therefore
+# refused with lease_session_mismatch on the canonical allocated path.
+# ``issue_lock_store.mint_task_session_id`` states the rule directly: an
+# ownership key "deliberately contains no process identifier", because the PID
+# "cannot identify *which* task holds a claim".
+_SESSION_UNVERIFIED = "workflow_session_unverified"
+_SESSION_REQUIRED = "workflow_session_required_for_allocated_work"
+_SESSION_LOCK_OWNER_MISMATCH = "issue_lock_owner_mismatch"
+
+
+def _resolve_owner_workflow_session(
+ *,
+ issue_number: int,
+ assignment_id: str | None,
+ lease_id: str | None,
+ session_id: str | None,
+ identity: str,
+ profile_name: str,
+ remote: str,
+ org: str | None,
+ repo: str | None,
+) -> dict:
+ """Resolve the authoritative workflow session that owns this work.
+
+ Precedence, each step fail-closed:
+
+ 1. An explicit ``session_id`` is verified against the control-plane
+ ``sessions`` table: it must exist, be active, and match this role and
+ profile. An unverifiable identifier is refused, never trusted.
+ 2. Otherwise an existing issue lock for this issue supplies its per-task
+ ``task_session_id``, but only when the lock's recorded claimant matches
+ the resolved authority pair.
+ 3. Otherwise, when allocator identifiers are supplied, the request is
+ refused: ownership of an allocated assignment cannot be established
+ without its owning session, and the presence of the identifiers is not
+ itself evidence of ownership.
+ 4. Otherwise — no allocator identifiers and no existing lock — a fresh
+ per-task key is minted through the canonical
+ ``issue_lock_store.mint_task_session_id``. It carries no process
+ identifier and is never memoised, so sequential tasks on one daemon never
+ share an owner.
+
+ Whether the resolved session actually owns a supplied lease stays the
+ decision of ``author_issue_bootstrap._verify_assignment_and_lease_ids``;
+ this function never pre-empts, duplicates or bypasses that gate.
+ """
+ declared = (session_id or "").strip()
+ if declared:
+ db, errs = _control_plane_db_or_error()
+ if db is None:
+ return {
+ "ok": False,
+ "reason_code": _SESSION_UNVERIFIED,
+ "reasons": errs,
+ }
+ try:
+ rows = db.list_sessions(statuses=("active",))
+ except Exception as exc: # noqa: BLE001 — surface structured
+ return {
+ "ok": False,
+ "reason_code": _SESSION_UNVERIFIED,
+ "reasons": [
+ "could not read control-plane sessions to verify "
+ f"session_id: {_redact(str(exc))} (fail closed)"
+ ],
+ }
+ match = next(
+ (r for r in rows if str(r.get("session_id") or "") == declared), None
+ )
+ if match is None:
+ return {
+ "ok": False,
+ "reason_code": _SESSION_UNVERIFIED,
+ "reasons": [
+ f"session_id '{declared}' is not an active control-plane "
+ "session (fail closed)"
+ ],
+ }
+ row_role = (match.get("role") or "").strip().lower()
+ row_profile = (match.get("profile") or "").strip()
+ if row_role and row_role != "author":
+ return {
+ "ok": False,
+ "reason_code": _SESSION_UNVERIFIED,
+ "reasons": [
+ f"session_id '{declared}' is recorded for role "
+ f"'{row_role}', not author (fail closed)"
+ ],
+ "expected": "author",
+ "actual": row_role,
+ }
+ if row_profile and row_profile != profile_name:
+ return {
+ "ok": False,
+ "reason_code": _SESSION_UNVERIFIED,
+ "reasons": [
+ f"session_id '{declared}' is recorded for profile "
+ f"'{row_profile}', not '{profile_name}' (fail closed)"
+ ],
+ "expected": row_profile,
+ "actual": profile_name,
+ }
+ return {"ok": True, "session_id": declared, "session_source": "declared"}
+
+ lock = None
+ try:
+ lock = issue_lock_store.load_issue_lock(
+ remote=remote,
+ org=org or "",
+ repo=repo or "",
+ issue_number=int(issue_number),
+ )
+ except Exception: # noqa: BLE001 — absent/unreadable lock is not fatal here
+ lock = None
+ lock_session = issue_lock_store.lease_task_session_id(lock) if lock else ""
+ if lock_session:
+ lease = (lock or {}).get("work_lease") or {}
+ claimant = lease.get("claimant") or {}
+ lock_identity = (claimant.get("username") or "").strip()
+ lock_profile = (claimant.get("profile") or "").strip()
+ if (lock_identity and lock_identity != identity) or (
+ lock_profile and lock_profile != profile_name
+ ):
+ return {
+ "ok": False,
+ "reason_code": _SESSION_LOCK_OWNER_MISMATCH,
+ "reasons": [
+ f"issue #{int(issue_number)} is locked by "
+ f"'{lock_identity or 'unknown'}' ({lock_profile or 'unknown'}), "
+ f"not '{identity}' ({profile_name}) (fail closed)"
+ ],
+ "expected": f"{lock_identity}/{lock_profile}",
+ "actual": f"{identity}/{profile_name}",
+ }
+ return {
+ "ok": True,
+ "session_id": lock_session,
+ "session_source": "issue_lock",
+ }
+
+ if (assignment_id or "").strip() or (lease_id or "").strip():
+ return {
+ "ok": False,
+ "reason_code": _SESSION_REQUIRED,
+ "reasons": [
+ "assignment_id/lease_id were supplied but no owning workflow "
+ "session could be established (fail closed); pass the "
+ "session_id that holds the lease, or bind the issue lock first"
+ ],
+ }
+
+ return {
+ "ok": True,
+ "session_id": issue_lock_store.mint_task_session_id(
+ issue_lock_store.AUTHOR_ISSUE_WORK_LEASE
+ ),
+ "session_source": "minted_task_key",
+ }
def _authenticated_actor(host: str) -> dict:
@@ -10234,6 +10463,7 @@ def gitea_bootstrap_author_issue_worktree(
branch_name: str | None = None,
worktree_path: str | None = None,
idempotency_key: str | None = None,
+ session_id: str | None = None,
remote: str = "dadeschools",
host: str | None = None,
org: str | None = None,
@@ -10255,6 +10485,14 @@ def gitea_bootstrap_author_issue_worktree(
branch_name: Optional custom branch name (must match issue- pattern).
worktree_path: Optional custom worktree path under branches/.
idempotency_key: Optional key for idempotent replay/resume.
+ session_id: Optional workflow session that owns the assignment/lease.
+ Required when assignment_id/lease_id are supplied, because ownership
+ of an allocated lease is compared by session identifier and cannot
+ be derived from the daemon process (#943 review 622 B1). Verified
+ against the control-plane sessions table; an unverifiable value is
+ refused rather than trusted. Omit for an unallocated bootstrap: the
+ owning session is then taken from an existing issue lock, or a fresh
+ per-task key is minted.
remote: Known instance — 'dadeschools' or 'prgs'.
host: Override Gitea host.
org: Override Org.
@@ -10293,6 +10531,44 @@ def gitea_bootstrap_author_issue_worktree(
h, o, r = _resolve(remote, host, org, repo)
canonical_root = _canonical_local_git_root()
+ # One authority snapshot supplies both halves of the claimant pair (F3), and
+ # an unresolvable profile becomes a structured refusal rather than a silent
+ # fallback (F4).
+ authority = _active_mutation_authority(h)
+ if not authority.get("ok"):
+ return _author_mutation_block(
+ authority.get("reasons") or ["mutation authority unresolved"],
+ reason_code=authority.get("reason_code"),
+ retryable=False,
+ transport_survives=True,
+ expected=authority.get("expected"),
+ actual=authority.get("actual"),
+ issue_number=int(issue_number),
+ )
+
+ # The owning workflow session — never process- or PID-derived (B1).
+ session = _resolve_owner_workflow_session(
+ issue_number=issue_number,
+ assignment_id=assignment_id,
+ lease_id=lease_id,
+ session_id=session_id,
+ identity=authority["identity"],
+ profile_name=authority["profile_name"],
+ remote=remote,
+ org=o,
+ repo=r,
+ )
+ if not session.get("ok"):
+ return _author_mutation_block(
+ session.get("reasons") or ["owning workflow session unresolved"],
+ reason_code=session.get("reason_code"),
+ retryable=False,
+ transport_survives=True,
+ expected=session.get("expected"),
+ actual=session.get("actual"),
+ issue_number=int(issue_number),
+ )
+
import author_issue_bootstrap
return author_issue_bootstrap.bootstrap_author_issue_worktree(
@@ -10308,9 +10584,9 @@ def gitea_bootstrap_author_issue_worktree(
host=h,
org=o,
repo=r,
- active_identity=_active_username(),
- active_profile=_active_profile_name(),
- owner_session=_current_session_id(),
+ active_identity=authority["identity"],
+ active_profile=authority["profile_name"],
+ owner_session=session["session_id"],
dry_run=dry_run,
)
diff --git a/tests/test_issue_943_runtime_context_helpers.py b/tests/test_issue_943_runtime_context_helpers.py
index f954249..8bbe5af 100644
--- a/tests/test_issue_943_runtime_context_helpers.py
+++ b/tests/test_issue_943_runtime_context_helpers.py
@@ -1,25 +1,33 @@
-"""Regression: the author bootstrap wrapper's runtime-context helpers (#943).
+"""Regression: author bootstrap runtime authority and session ownership (#943).
-``gitea_bootstrap_author_issue_worktree`` passed three values down to
-``author_issue_bootstrap.bootstrap_author_issue_worktree``::
+Two rounds of defects live here.
- active_identity=_active_username(),
- active_profile=_active_profile_name(),
- owner_session=_current_session_id(),
+**Round 1 (#943 as filed).** ``gitea_bootstrap_author_issue_worktree`` passed
+four values down to the bootstrap service that were never defined:
+``_active_username``, ``_active_profile_name``, ``_current_session_id`` and
+``_author_mutation_block``. Every call — dry-run included — raised
+``NameError`` while evaluating the arguments, before the service was entered.
-None of those three names was ever defined. Commit ``a942afe`` (#850) introduced
-the references and no definition, so every call — dry-run included — raised
-``NameError: name '_active_username' is not defined`` while evaluating the
-arguments, before the bootstrap service was entered.
+**Round 2 (review 622 on PR #944).** The first fix defined all four but made
+``_current_session_id`` mint ``--`` once per process. The MCP
+daemon outlives every task it serves, so that value conflates sequential author
+tasks and can never equal the control-plane session that owns an
+allocator-created lease: ``_verify_assignment_and_lease_ids`` refused the whole
+allocated path with ``lease_session_mismatch``. The reviewed round also read the
+identity from the pinned session context while reading the profile from the live
+profile, so a rebind could produce a mixed claimant pair, and it swallowed every
+``get_profile()`` exception.
-The defect was unreachable until PR #942 (#941) wired the bootstrap scope into
-``workflow_scope_guard``: until then ``verify_preflight_purity`` refused first
-with ``missing_issue_worktree``, so the guard fix is what exposed this.
+These tests therefore drive real state, not mocks of internals: a temporary
+control-plane SQLite database and a temporary issue-lock directory, both
+redirected through the same environment variables production uses
+(``GITEA_CONTROL_PLANE_DB``, ``GITEA_ISSUE_LOCK_DIR``). The ownership gate that
+runs is the real one.
-``test_every_global_referenced_by_the_wrapper_resolves`` is the test that would
-have caught the original defect: it resolves every global name the wrapper's
-body references. Asserting only that the three known helpers now exist would
-not generalise to the next missing reference.
+``test_every_global_referenced_by_the_wrapper_resolves`` remains: it is what
+found ``_author_mutation_block``, and it generalises to the next missing
+reference. It supplements the runtime coverage below rather than standing in for
+it.
"""
from __future__ import annotations
@@ -34,16 +42,28 @@ import unittest
from unittest import mock
import author_issue_bootstrap as aib
+import control_plane_db
import create_issue_bootstrap as cib
import gitea_mcp_server as gms
+import issue_lock_store
import workflow_scope_guard
BOOTSTRAP_TASK = "bootstrap_author_issue_worktree"
WRAPPER_NAME = "gitea_bootstrap_author_issue_worktree"
-RUNTIME_HELPERS = ("_active_username", "_active_profile_name", "_current_session_id")
+RUNTIME_HELPERS = (
+ "_active_mutation_authority",
+ "_active_username",
+ "_active_profile_name",
+ "_resolve_owner_workflow_session",
+ "_author_mutation_block",
+)
+ORG = "Scaled-Tech-Consulting"
+REPO = "Gitea-Tools"
+IDENTITY = "jcwalker3"
+PROFILE = "prgs-author"
-# "--", the shape the pre-existing lease call sites mint.
-SESSION_ID_RE = re.compile(r"^[A-Za-z0-9_.-]+-\d+-[0-9a-f]{8}$")
+# A per-task ownership key must carry no process identifier (#790).
+TASK_KEY_RE = re.compile(r"^author_issue_work-[0-9a-f]{16}$")
def _make_control_repo(tmp: str) -> tuple[str, str]:
@@ -71,13 +91,11 @@ def _make_control_repo(tmp: str) -> tuple[str, str]:
def _wrapper_ast() -> ast.FunctionDef:
- """Return the AST of the bootstrap wrapper as it exists on disk.
-
- Read from source rather than ``inspect``: the tool decorator may replace the
- callable, and the defect lived in the *source* argument expressions.
- """
- path = os.path.join(os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
- "gitea_mcp_server.py")
+ """Return the AST of the bootstrap wrapper as it exists on disk."""
+ path = os.path.join(
+ os.path.dirname(os.path.dirname(os.path.abspath(__file__))),
+ "gitea_mcp_server.py",
+ )
with open(path, encoding="utf-8") as fh:
tree = ast.parse(fh.read())
for node in ast.walk(tree):
@@ -86,36 +104,517 @@ def _wrapper_ast() -> ast.FunctionDef:
raise AssertionError(f"{WRAPPER_NAME} not found in gitea_mcp_server.py")
-class RuntimeHelperResolutionTests(unittest.TestCase):
- """AC: every runtime helper the wrapper references is defined and callable."""
+class _IsolatedControlPlane(unittest.TestCase):
+ """Temp control-plane DB and temp issue-lock dir, via production env vars."""
- def test_three_named_helpers_are_defined_and_callable(self):
- for name in RUNTIME_HELPERS:
- with self.subTest(helper=name):
- self.assertTrue(
- hasattr(gms, name), f"{name} is referenced but not defined"
+ def setUp(self):
+ self._tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self._tmp.cleanup)
+ self.tmp = self._tmp.name
+ self.db_path = os.path.join(self.tmp, "control-plane.sqlite3")
+ self.lock_dir = os.path.join(self.tmp, "issue-locks")
+ self.journals = os.path.join(self.tmp, "journals")
+ os.makedirs(self.lock_dir)
+ os.makedirs(self.journals)
+ env = mock.patch.dict(
+ os.environ,
+ {
+ control_plane_db.DB_PATH_ENV: self.db_path,
+ issue_lock_store.LOCK_DIR_ENV: self.lock_dir,
+ },
+ )
+ env.start()
+ self.addCleanup(env.stop)
+ self.db = control_plane_db.ControlPlaneDB(self.db_path)
+
+ def _allocate(self, session_id: str, *, issue: int = 943):
+ """Create a real assignment + lease owned by *session_id*."""
+ self.db.upsert_session(
+ session_id=session_id, role="author", profile=PROFILE, pid=os.getpid()
+ )
+ res = self.db.assign_and_lease(
+ session_id=session_id, role="author", remote="prgs",
+ org=ORG, repo=REPO, kind="issue", number=issue,
+ )
+ self.assertEqual(res.outcome, "assigned", res)
+ return res.assignment_id, res.lease_id
+
+ def _authority(self):
+ """A resolved authority pair, as the wrapper would compute it."""
+ return {"ok": True, "identity": IDENTITY, "profile_name": PROFILE}
+
+ def _resolve_session(self, **over):
+ kwargs = dict(
+ issue_number=943,
+ assignment_id=None,
+ lease_id=None,
+ session_id=None,
+ identity=IDENTITY,
+ profile_name=PROFILE,
+ remote="prgs",
+ org=ORG,
+ repo=REPO,
+ )
+ kwargs.update(over)
+ return gms._resolve_owner_workflow_session(**kwargs)
+
+
+class OwnershipGateTests(_IsolatedControlPlane):
+ """B2: the allocator-driven ownership path, against a real control plane."""
+
+ def setUp(self):
+ super().setUp()
+ self.repo, self.head = _make_control_repo(self.tmp)
+
+ def _bootstrap(self, **over):
+ kwargs = dict(
+ issue_number=943,
+ canonical_repo_root=self.repo,
+ expected_base_sha=self.head,
+ branch_name="fix/issue-943-runtime-context-helpers",
+ remote="prgs",
+ org=ORG,
+ repo=REPO,
+ active_identity=IDENTITY,
+ active_profile=PROFILE,
+ lock_dir=self.journals,
+ idempotency_key="test-943",
+ dry_run=True,
+ )
+ kwargs.update(over)
+ return aib.bootstrap_author_issue_worktree(**kwargs)
+
+ def test_true_owning_session_passes_the_ownership_gate(self):
+ """The canonical owner reaches and completes the service."""
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id=assignment_id, lease_id=lease_id, owner_session=session
+ )
+ self.assertTrue(res.get("success"), res)
+ self.assertTrue(res.get("dry_run"))
+ self.assertEqual(res.get("base_sha"), self.head)
+
+ def test_different_session_is_refused(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id=assignment_id,
+ lease_id=lease_id,
+ owner_session="prgs-author-task-b",
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "lease_session_mismatch")
+
+ def test_process_derived_session_would_be_refused(self):
+ """The reviewed round-1 value shape can never own an allocated lease."""
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ round_one_value = f"{PROFILE}-{os.getpid()}-deadbeef"
+ self.assertNotEqual(round_one_value, session)
+ res = self._bootstrap(
+ assignment_id=assignment_id,
+ lease_id=lease_id,
+ owner_session=round_one_value,
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "lease_session_mismatch")
+
+ def test_unknown_lease_fails_closed(self):
+ session = "prgs-author-task-a"
+ assignment_id, _ = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id=assignment_id,
+ lease_id="lease-does-not-exist",
+ owner_session=session,
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "unknown_lease_id")
+
+ def test_released_lease_fails_closed(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ self.db.release_lease(lease_id, session_id=session)
+ res = self._bootstrap(
+ assignment_id=assignment_id, lease_id=lease_id, owner_session=session
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "lease_not_live")
+
+ def test_force_expired_lease_fails_closed(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ self.db.force_expire_lease(lease_id, reason="test")
+ res = self._bootstrap(
+ assignment_id=assignment_id, lease_id=lease_id, owner_session=session
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "lease_not_live")
+
+ def test_replacement_lease_does_not_inherit_prior_ownership(self):
+ """A second task's lease is not ownable by the first task's session."""
+ first = "prgs-author-task-a"
+ assignment_a, lease_a = self._allocate(first)
+ self.db.release_lease(lease_a, session_id=first)
+ second = "prgs-author-task-b"
+ assignment_b, lease_b = self._allocate(second)
+ self.assertNotEqual(lease_a, lease_b)
+ res = self._bootstrap(
+ assignment_id=assignment_b, lease_id=lease_b, owner_session=first
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "lease_session_mismatch")
+
+ def test_assignment_lease_identifier_mismatch_fails_closed(self):
+ session = "prgs-author-task-a"
+ _, lease_id = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id="asn-not-the-recorded-one",
+ lease_id=lease_id,
+ owner_session=session,
+ )
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "assignment_lease_mismatch")
+
+ def test_lease_id_without_assignment_id_fails_closed(self):
+ session = "prgs-author-task-a"
+ _, lease_id = self._allocate(session)
+ res = self._bootstrap(lease_id=lease_id, owner_session=session)
+ self.assertFalse(res.get("success"))
+ self.assertEqual(res.get("reason_code"), "incomplete_assignment_lease_ids")
+
+ def test_dry_run_with_valid_allocator_bindings_leaves_no_durable_state(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id=assignment_id, lease_id=lease_id, owner_session=session
+ )
+ self.assertTrue(res.get("success"), res)
+
+ branches = subprocess.check_output(
+ ["git", "-C", self.repo, "branch", "--list"], text=True
+ )
+ self.assertNotIn("issue-943", branches)
+ worktrees = subprocess.check_output(
+ ["git", "-C", self.repo, "worktree", "list"], text=True
+ )
+ self.assertNotIn("issue-943", worktrees)
+ self.assertFalse(
+ os.path.exists(
+ os.path.join(self.repo, "branches",
+ "fix-issue-943-runtime-context-helpers")
+ )
+ )
+ journal = res.get("phase_journal") or {}
+ self.assertFalse(journal.get("completed"))
+ self.assertFalse(any((journal.get("artifacts_created") or {}).values()))
+ # The dry run must not have created an issue lock in the isolated dir.
+ self.assertEqual(os.listdir(self.lock_dir), [])
+
+ def test_apply_reaches_the_intended_transition_with_valid_bindings(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._bootstrap(
+ assignment_id=assignment_id,
+ lease_id=lease_id,
+ owner_session=session,
+ dry_run=False,
+ )
+ self.assertTrue(res.get("success"), res)
+ self.assertNotEqual(res.get("dry_run"), True)
+ branches = subprocess.check_output(
+ ["git", "-C", self.repo, "branch", "--list"], text=True
+ )
+ self.assertIn("issue-943", branches)
+ self.assertTrue(os.path.isdir(res.get("worktree_path") or ""))
+
+
+class WorkflowSessionResolutionTests(_IsolatedControlPlane):
+ """B1: the wrapper resolves the owning session, never a process identifier."""
+
+ def test_declared_session_is_verified_against_the_control_plane(self):
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._resolve_session(
+ session_id=session, assignment_id=assignment_id, lease_id=lease_id
+ )
+ self.assertTrue(res.get("ok"), res)
+ self.assertEqual(res.get("session_id"), session)
+ self.assertEqual(res.get("session_source"), "declared")
+
+ def test_unknown_declared_session_is_refused_not_trusted(self):
+ res = self._resolve_session(session_id="prgs-author-not-a-session")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "workflow_session_unverified")
+
+ def test_declared_session_for_another_role_is_refused(self):
+ self.db.upsert_session(
+ session_id="prgs-reviewer-x", role="reviewer", profile="prgs-reviewer",
+ pid=os.getpid(),
+ )
+ res = self._resolve_session(session_id="prgs-reviewer-x")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "workflow_session_unverified")
+
+ def test_declared_session_for_another_profile_is_refused(self):
+ self.db.upsert_session(
+ session_id="other-profile-session", role="author",
+ profile="prgs-controller", pid=os.getpid(),
+ )
+ res = self._resolve_session(session_id="other-profile-session")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "workflow_session_unverified")
+
+ def test_allocated_work_without_a_session_is_refused(self):
+ """Supplying a lease is not itself evidence of ownership."""
+ session = "prgs-author-task-a"
+ assignment_id, lease_id = self._allocate(session)
+ res = self._resolve_session(assignment_id=assignment_id, lease_id=lease_id)
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(
+ res.get("reason_code"), "workflow_session_required_for_allocated_work"
+ )
+
+ def test_existing_issue_lock_supplies_its_per_task_session(self):
+ lock_session = issue_lock_store.mint_task_session_id(
+ issue_lock_store.AUTHOR_ISSUE_WORK_LEASE
+ )
+ path = issue_lock_store.lock_file_path(
+ remote="prgs", org=ORG, repo=REPO, issue_number=943,
+ lock_dir=self.lock_dir,
+ )
+ issue_lock_store.write_lock_file(
+ path,
+ {
+ "issue_number": 943,
+ "branch_name": "fix/issue-943-runtime-context-helpers",
+ "work_lease": {
+ "task_session_id": lock_session,
+ "claimant": {"username": IDENTITY, "profile": PROFILE},
+ },
+ },
+ ) if hasattr(issue_lock_store, "write_lock_file") else _write_json(
+ path,
+ {
+ "issue_number": 943,
+ "branch_name": "fix/issue-943-runtime-context-helpers",
+ "work_lease": {
+ "task_session_id": lock_session,
+ "claimant": {"username": IDENTITY, "profile": PROFILE},
+ },
+ },
+ )
+ res = self._resolve_session()
+ self.assertTrue(res.get("ok"), res)
+ self.assertEqual(res.get("session_id"), lock_session)
+ self.assertEqual(res.get("session_source"), "issue_lock")
+
+ def test_issue_lock_owned_by_another_identity_is_refused(self):
+ path = issue_lock_store.lock_file_path(
+ remote="prgs", org=ORG, repo=REPO, issue_number=943,
+ lock_dir=self.lock_dir,
+ )
+ _write_json(
+ path,
+ {
+ "issue_number": 943,
+ "work_lease": {
+ "task_session_id": "author_issue_work-" + "0" * 16,
+ "claimant": {"username": "someone-else", "profile": PROFILE},
+ },
+ },
+ )
+ res = self._resolve_session()
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "issue_lock_owner_mismatch")
+
+ def test_unallocated_bootstrap_mints_a_per_task_key(self):
+ res = self._resolve_session()
+ self.assertTrue(res.get("ok"), res)
+ self.assertEqual(res.get("session_source"), "minted_task_key")
+ self.assertRegex(res["session_id"], TASK_KEY_RE)
+
+ def test_minted_key_contains_no_process_identifier(self):
+ res = self._resolve_session()
+ self.assertNotIn(str(os.getpid()), res["session_id"])
+ self.assertNotIn(PROFILE, res["session_id"])
+
+ def test_sequential_tasks_on_one_daemon_do_not_share_ownership(self):
+ """The round-1 defect: one identifier per process for every task."""
+ first = self._resolve_session()["session_id"]
+ second = self._resolve_session()["session_id"]
+ third = self._resolve_session()["session_id"]
+ self.assertNotEqual(first, second)
+ self.assertNotEqual(second, third)
+ self.assertEqual(len({first, second, third}), 3)
+
+ def test_no_process_lifetime_cache_remains(self):
+ self.assertFalse(hasattr(gms, "_ACTIVE_SESSION_ID"))
+ self.assertFalse(hasattr(gms, "_current_session_id"))
+
+
+class MutationAuthorityTests(unittest.TestCase):
+ """F3/F4: one coherent authority pair, drift detected, no silent fallback."""
+
+ def _ctx(self, **over):
+ base = {"identity": IDENTITY, "profile_name": PROFILE}
+ base.update(over)
+ return base
+
+ def test_matching_live_and_pinned_authority_resolves(self):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": PROFILE}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=IDENTITY), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertTrue(res.get("ok"), res)
+ self.assertEqual(res["identity"], IDENTITY)
+ self.assertEqual(res["profile_name"], PROFILE)
+
+ def test_identity_drift_fails_closed(self):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": PROFILE}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value="someone-else"), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "authority_identity_drift")
+ self.assertEqual(res.get("expected"), IDENTITY)
+ self.assertEqual(res.get("actual"), "someone-else")
+
+ def test_profile_drift_fails_closed(self):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": "prgs-controller"}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=IDENTITY), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "authority_profile_drift")
+
+ def test_identity_and_profile_never_come_from_different_snapshots(self):
+ """Round 2's mixed pair: pinned identity plus live profile."""
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": "prgs-controller"}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value="new-identity"), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertIsNone(gms._active_username("gitea.prgs.cc"))
+ self.assertIsNone(gms._active_profile_name("gitea.prgs.cc"))
+
+ def test_unresolvable_profile_is_a_structured_refusal_not_a_fallback(self):
+ """F4: no bare-except fallback to a previously pinned profile name."""
+ with mock.patch.object(gms, "get_profile",
+ side_effect=RuntimeError("profile disabled")), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=IDENTITY), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "authority_profile_unresolved")
+ self.assertNotEqual(res.get("profile_name"), PROFILE)
+
+ def test_malformed_profile_without_name_fails_closed(self):
+ with mock.patch.object(gms, "get_profile", return_value={}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=IDENTITY), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=None):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "authority_profile_unresolved")
+
+ def test_unresolved_identity_fails_closed(self):
+ for value in (None, "", " "):
+ with self.subTest(identity=value):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": PROFILE}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=value), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=None):
+ res = gms._active_mutation_authority("gitea.prgs.cc")
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(
+ res.get("reason_code"), "authority_identity_unresolved"
)
- self.assertTrue(callable(getattr(gms, name)), f"{name} not callable")
- def test_helpers_accept_zero_arguments_as_called(self):
- """The wrapper calls each with no arguments; the signature must allow it."""
- prior = gms._ACTIVE_SESSION_ID
- self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
+ def test_missing_host_cannot_yield_an_identity(self):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": PROFILE}), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=None):
+ res = gms._active_mutation_authority(None)
+ self.assertFalse(res.get("ok"))
+ self.assertEqual(res.get("reason_code"), "authority_identity_unresolved")
+
+ def test_expected_username_is_never_substituted_for_authentication(self):
+ with mock.patch.object(
+ gms, "get_profile",
+ return_value={"profile_name": PROFILE, "username": IDENTITY},
+ ), mock.patch.object(gms, "_authenticated_username", return_value=None), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value={"expected_username": IDENTITY}):
+ self.assertIsNone(gms._active_username("gitea.prgs.cc"))
+
+ def test_accessors_share_one_snapshot(self):
+ with mock.patch.object(gms, "get_profile",
+ return_value={"profile_name": PROFILE}), \
+ mock.patch.object(gms, "_authenticated_username",
+ return_value=IDENTITY), \
+ mock.patch.object(gms.session_ctx, "get_session_context",
+ return_value=self._ctx()):
+ self.assertEqual(gms._active_username("gitea.prgs.cc"), IDENTITY)
+ self.assertEqual(gms._active_profile_name("gitea.prgs.cc"), PROFILE)
+
+
+class AuthorMutationBlockTests(unittest.TestCase):
+ """Preserved: the structured refusal shape review 622 confirmed correct."""
+
+ def test_matches_the_sibling_refusal_shape(self):
+ res = gms._author_mutation_block(["stopped"])
+ self.assertIs(res["success"], False)
+ self.assertIs(res["performed"], False)
+ self.assertEqual(res["outcome"], "REFUSED")
+ self.assertEqual(res["reasons"], ["stopped"])
+
+ def test_carries_reason_code_and_transport_fields(self):
+ res = gms._author_mutation_block(
+ ["nope"], reason_code="authority_identity_drift",
+ retryable=False, transport_survives=True,
+ expected="a", actual="b", issue_number=943,
+ )
+ self.assertEqual(res["reason_code"], "authority_identity_drift")
+ self.assertIs(res["retryable"], False)
+ self.assertIs(res["transport_survives"], True)
+ self.assertEqual((res["expected"], res["actual"]), ("a", "b"))
+ self.assertEqual(res["issue_number"], 943)
+ self.assertIs(res["success"], False)
+
+
+class RuntimeHelperResolutionTests(unittest.TestCase):
+ """Every runtime helper the wrapper references is defined and callable.
+
+ Supplements the runtime coverage above; it does not replace it.
+ """
+
+ def test_named_helpers_are_defined_and_callable(self):
for name in RUNTIME_HELPERS:
with self.subTest(helper=name):
- with mock.patch.object(gms, "get_profile", return_value={}), \
- mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None):
- gms._ACTIVE_SESSION_ID = None
- getattr(gms, name)() # must not raise TypeError
+ self.assertTrue(hasattr(gms, name), f"{name} is not defined")
+ self.assertTrue(callable(getattr(gms, name)))
def test_every_global_referenced_by_the_wrapper_resolves(self):
- """The generalised form of this defect: an unresolvable global name.
-
- Collects every ``Name`` load in the wrapper body, subtracts locals
- (arguments, assignments, comprehension targets, imports), and asserts the
- remainder resolves against module globals or builtins.
- """
+ """The generalised form of the round-1 defect: an unresolvable global."""
fn = _wrapper_ast()
bound: set[str] = {a.arg for a in fn.args.args}
bound |= {a.arg for a in fn.args.kwonlyargs}
@@ -124,7 +623,9 @@ class RuntimeHelperResolutionTests(unittest.TestCase):
if fn.args.kwarg:
bound.add(fn.args.kwarg.arg)
for node in ast.walk(fn):
- if isinstance(node, ast.Name) and isinstance(node.ctx, (ast.Store, ast.Del)):
+ if isinstance(node, ast.Name) and isinstance(
+ node.ctx, (ast.Store, ast.Del)
+ ):
bound.add(node.id)
elif isinstance(node, (ast.Import, ast.ImportFrom)):
for alias in node.names:
@@ -142,255 +643,34 @@ class RuntimeHelperResolutionTests(unittest.TestCase):
and not hasattr(builtins, node.id)
)
self.assertEqual(
- unresolved, [], f"{WRAPPER_NAME} references undefined globals: {unresolved}"
+ unresolved, [],
+ f"{WRAPPER_NAME} references undefined globals: {unresolved}",
)
- def test_wrapper_still_passes_all_three_runtime_values(self):
- """Guard the wiring itself: the fix must not be 'stop passing them'."""
+ def test_wrapper_wires_the_authority_and_session_resolvers(self):
fn = _wrapper_ast()
called = {
node.func.id
for node in ast.walk(fn)
if isinstance(node, ast.Call) and isinstance(node.func, ast.Name)
}
- for name in RUNTIME_HELPERS:
- with self.subTest(helper=name):
- self.assertIn(name, called)
+ self.assertIn("_active_mutation_authority", called)
+ self.assertIn("_resolve_owner_workflow_session", called)
+ self.assertIn("_author_mutation_block", called)
-
-class ActiveUsernameTests(unittest.TestCase):
- """AC: identity comes from the authoritative pin, and fails closed."""
-
- def test_returns_identity_from_bound_session_context(self):
- with mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"identity": "jcwalker3", "profile_name": "prgs-author"},
- ):
- self.assertEqual(gms._active_username(), "jcwalker3")
-
- def test_unbound_context_returns_none_so_callers_fail_closed(self):
- with mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None
- ):
- self.assertIsNone(gms._active_username())
-
- def test_blank_identity_is_not_treated_as_an_identity(self):
- for blank in ("", " ", None):
- with self.subTest(identity=blank):
- with mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"identity": blank},
- ):
- self.assertIsNone(gms._active_username())
-
- def test_identity_is_not_fabricated_from_the_profile(self):
- """A profile's expected username must never stand in for a real identity."""
- with mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"identity": None, "expected_username": "jcwalker3"},
- ):
- self.assertIsNone(gms._active_username())
-
-
-class ActiveProfileNameTests(unittest.TestCase):
- """AC: profile name comes from the live profile, context only as fallback."""
-
- def test_prefers_the_live_profile(self):
- with mock.patch.object(
- gms, "get_profile", return_value={"profile_name": "prgs-author"}
- ), mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"profile_name": "prgs-reviewer"},
- ):
- self.assertEqual(gms._active_profile_name(), "prgs-author")
-
- def test_falls_back_to_session_context_when_profile_unreadable(self):
- with mock.patch.object(gms, "get_profile", side_effect=RuntimeError("no cfg")), \
- mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"profile_name": "prgs-author"}):
- self.assertEqual(gms._active_profile_name(), "prgs-author")
-
- def test_returns_none_when_neither_source_knows(self):
- with mock.patch.object(gms, "get_profile", return_value={}), \
- mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None):
- self.assertIsNone(gms._active_profile_name())
-
-
-class CurrentSessionIdTests(unittest.TestCase):
- """AC: a real, stable session identifier — never a fresh owner per call."""
-
- def setUp(self):
- self._prior = gms._ACTIVE_SESSION_ID
- gms._ACTIVE_SESSION_ID = None
- self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", self._prior)
-
- def test_shape_matches_the_existing_lease_call_sites(self):
- with mock.patch.object(
- gms, "get_profile", return_value={"profile_name": "prgs-author"}
- ):
- sid = gms._current_session_id()
- self.assertRegex(sid, SESSION_ID_RE)
- self.assertTrue(sid.startswith("prgs-author-"))
- self.assertIn(str(os.getpid()), sid)
-
- def test_stable_across_calls_within_one_process(self):
- """A new id per call would make lease-ownership checks unsatisfiable."""
- with mock.patch.object(
- gms, "get_profile", return_value={"profile_name": "prgs-author"}
- ):
- first = gms._current_session_id()
- second = gms._current_session_id()
- third = gms._current_session_id()
- self.assertEqual(first, second)
- self.assertEqual(second, third)
-
- def test_returns_none_when_profile_undeterminable(self):
- with mock.patch.object(gms, "get_profile", return_value={}), \
- mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None):
- self.assertIsNone(gms._current_session_id())
-
- def test_none_result_is_not_memoised_as_a_session(self):
- with mock.patch.object(gms, "get_profile", return_value={}), \
- mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None):
- self.assertIsNone(gms._current_session_id())
- with mock.patch.object(
- gms, "get_profile", return_value={"profile_name": "prgs-author"}
- ):
- self.assertIsNotNone(gms._current_session_id())
-
-
-class BootstrapServiceReachedTests(unittest.TestCase):
- """AC: the values the helpers produce carry a dry-run into the service."""
-
- def setUp(self):
- self._tmp = tempfile.TemporaryDirectory()
- self.addCleanup(self._tmp.cleanup)
- self.tmp = self._tmp.name
- self.repo, self.head = _make_control_repo(self.tmp)
- self.journals = os.path.join(self.tmp, "journals")
- os.makedirs(self.journals)
-
- def _bootstrap(self, **over):
- kwargs = dict(
- issue_number=943,
- canonical_repo_root=self.repo,
- expected_base_sha=self.head,
- branch_name="fix/issue-943-runtime-context-helpers",
- remote="prgs",
- org="Scaled-Tech-Consulting",
- repo="Gitea-Tools",
- active_identity="jcwalker3",
- active_profile="prgs-author",
- owner_session="prgs-author-4242-abcdef12",
- lock_dir=self.journals,
- idempotency_key="test-943",
- dry_run=True,
- )
- kwargs.update(over)
- return aib.bootstrap_author_issue_worktree(**kwargs)
-
- def test_dry_run_succeeds_with_helper_produced_bindings(self):
- """Feed the service exactly what the live helpers return."""
- prior = gms._ACTIVE_SESSION_ID
- self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
- with mock.patch.object(
- gms, "get_profile", return_value={"profile_name": "prgs-author"}
- ), mock.patch.object(
- gms.session_ctx, "get_session_context",
- return_value={"identity": "jcwalker3", "profile_name": "prgs-author"},
- ):
- gms._ACTIVE_SESSION_ID = None
- identity = gms._active_username()
- profile = gms._active_profile_name()
- session = gms._current_session_id()
-
- res = self._bootstrap(
- active_identity=identity, active_profile=profile, owner_session=session
- )
- self.assertTrue(res.get("success"), res)
- self.assertTrue(res.get("dry_run"))
- self.assertEqual(res.get("issue_number"), 943)
- self.assertEqual(res.get("base_sha"), self.head)
-
- def test_dry_run_creates_no_branch_worktree_or_lease(self):
- res = self._bootstrap()
- self.assertTrue(res.get("success"), res)
-
- branches = subprocess.check_output(
- ["git", "-C", self.repo, "branch", "--list"], text=True
- )
- self.assertNotIn("issue-943", branches)
- worktrees = subprocess.check_output(
- ["git", "-C", self.repo, "worktree", "list"], text=True
- )
- self.assertNotIn("issue-943", worktrees)
- self.assertFalse(
- os.path.exists(os.path.join(self.repo, "branches",
- "fix-issue-943-runtime-context-helpers"))
- )
- journal = res.get("phase_journal") or {}
- self.assertFalse(journal.get("completed"))
- self.assertFalse(any((journal.get("artifacts_created") or {}).values()))
- self.assertIsNone(journal.get("lease_id"))
- self.assertIsNone(journal.get("assignment_id"))
-
- def test_missing_identity_fails_closed(self):
- res = self._bootstrap(active_identity=None)
- self.assertFalse(res.get("success"))
- self.assertEqual(res.get("reason_code"), "missing_active_identity")
-
- def test_missing_profile_fails_closed(self):
- res = self._bootstrap(active_profile=" ")
- self.assertFalse(res.get("success"))
- self.assertEqual(res.get("reason_code"), "missing_active_profile")
-
- def test_missing_session_fails_closed(self):
- res = self._bootstrap(owner_session=None)
- self.assertFalse(res.get("success"))
- self.assertEqual(res.get("reason_code"), "missing_owner_session")
-
- def test_expected_base_mismatch_fails_closed(self):
- res = self._bootstrap(expected_base_sha="0" * 40)
- self.assertFalse(res.get("success"))
- self.assertEqual(res.get("reason_code"), "stale_concurrency_pin")
-
- def test_unbound_runtime_context_cannot_reach_the_service(self):
- """With nothing bound, the helpers yield None and the service refuses."""
- prior = gms._ACTIVE_SESSION_ID
- self.addCleanup(setattr, gms, "_ACTIVE_SESSION_ID", prior)
- with mock.patch.object(gms, "get_profile", return_value={}), \
- mock.patch.object(
- gms.session_ctx, "get_session_context", return_value=None):
- gms._ACTIVE_SESSION_ID = None
- res = self._bootstrap(
- active_identity=gms._active_username(),
- active_profile=gms._active_profile_name(),
- owner_session=gms._current_session_id(),
- )
- self.assertFalse(res.get("success"))
- self.assertIn(
- res.get("reason_code"),
- {"missing_owner_session", "missing_active_identity",
- "missing_active_profile"},
- )
-
- def test_apply_reaches_the_intended_transition(self):
- res = self._bootstrap(dry_run=False)
- self.assertTrue(res.get("success"), res)
- self.assertNotEqual(res.get("dry_run"), True)
- branches = subprocess.check_output(
- ["git", "-C", self.repo, "branch", "--list"], text=True
- )
- self.assertIn("issue-943", branches)
- self.assertTrue(os.path.isdir(res.get("worktree_path") or ""))
+ def test_wrapper_accepts_an_optional_session_id(self):
+ """ABI addition stays backward compatible: optional, defaulting to None."""
+ fn = _wrapper_ast()
+ names = [a.arg for a in fn.args.args]
+ self.assertIn("session_id", names)
+ offset = len(names) - len(fn.args.defaults)
+ default = fn.args.defaults[names.index("session_id") - offset]
+ self.assertIsInstance(default, ast.Constant)
+ self.assertIsNone(default.value)
class Issue941ScopeGuardNotRegressedTests(unittest.TestCase):
- """AC: PR #942's bootstrap-scope wiring still holds."""
+ """Preserved: PR #942's bootstrap-scope wiring still holds."""
def setUp(self):
self._tmp = tempfile.TemporaryDirectory()
@@ -454,5 +734,14 @@ class Issue941ScopeGuardNotRegressedTests(unittest.TestCase):
self.assertFalse(cib.is_create_issue_task(BOOTSTRAP_TASK))
+def _write_json(path: str, payload: dict) -> None:
+ """Write an issue-lock file directly, for lock-precedence tests."""
+ import json
+
+ os.makedirs(os.path.dirname(path), exist_ok=True)
+ with open(path, "w", encoding="utf-8") as fh:
+ json.dump(payload, fh)
+
+
if __name__ == "__main__":
unittest.main()
From cdf0daefa91f891186bfad0513816ec2ddc90e7c Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Tue, 28 Jul 2026 00:35:12 -0400
Subject: [PATCH 14/18] fix(author): unify the bootstrap and lock_issue
issue-lock contract (Closes #953)
gitea_bootstrap_author_issue_worktree wrote a lock no downstream author
operation accepts, then directed the author straight to implementation. Once
the branch carried commits, heartbeat, re-lock, exact-owner renewal, and the
#447 create-PR guard all refused simultaneously and no sanctioned recovery
path remained eligible.
Each of those gates is individually correct. The defect was that two writers
disagreed about what a lock is.
- Add author_lock_contract as the single canonical definition: claimant,
work_lease, lock_provenance, generation, and an explicit expiration state.
Both gitea_lock_issue and bootstrap now build through it.
- Promote issue_lock_store.lock_claimant to the one shared claimant reader and
use it in the ownership check, so a claimant recorded at the lock top level
is read rather than refused. The values are still compared against
server-resolved identity and profile, so no legacy placement grants anything
the canonical placement would not.
- Represent missing expiration explicitly. An absent expires_at previously read
as "not yet expired", leaving a malformed lock permanently non-expiring and
permanently ineligible for #760 renewal.
- Bootstrap reads its lock back and verifies it structurally before reporting
success. A partial lock fails closed while the worktree is still
base-equivalent, names the missing fields, and never reports
implementation_allowed. Its exact_next_action now matches the state returned.
- Add gitea_recover_incomplete_bootstrap_lock for locks already written by the
old bootstrap, including those whose branches carry pushed commits. It never
moves, resets, or rewinds a branch, never requires base-equivalence, never
pushes or opens a PR, and touches only the target lock. It proves repository,
issue, claimant username and profile, branch, worktree, registration, and
head before writing, refuses healthy foreign-owned locks, and mints
provenance and authorization server-side.
- Add gitea_inspect_issue_lock_contract, a strictly read-only surface.
- Document the required ordering and the recovery path.
The #447 provenance guard is unchanged and the sanctioned source set was not
widened: bootstrap now satisfies the guard rather than the guard being relaxed
to admit bootstrap.
Tests: 61 new cases covering the canonical schema, immediate heartbeat,
renewal before and after commits, the create_pr guard, executable next actions,
partial and malformed and missing-expiration and expired and same-owner and
foreign-owner and legacy locks, recovery isolation, read-only inspection, and
the full bootstrap-implement-commit-push-create_pr regression against isolated
fixtures.
Full suite at head: 28 failed, 5753 passed, 6 skipped, 1042 subtests.
Full suite at base 82d71b77: 28 failed, 5692 passed, 6 skipped, 1042 subtests.
Failing test-ID sets are identical, so there are zero regressions; the +61
passes are this issue's new suite.
Issue #949 was preserved and not recovered: its branch remains at
92615f474bf6652d4e9ea59af7fd0dba03b56544 and its worktree, lock, and PR state
were not touched. The #949-shaped regression uses isolated fixtures only.
Co-Authored-By: Claude Opus 4.8 (1M context)
---
author_issue_bootstrap.py | 90 +-
author_lock_contract.py | 442 ++++++++
bootstrap_lock_recovery.py | 304 +++++
docs/author-issue-lock-contract.md | 148 +++
gitea_mcp_server.py | 389 ++++++-
issue_lock_store.py | 44 +-
task_capability_map.py | 21 +
.../test_issue_953_bootstrap_lock_contract.py | 1010 +++++++++++++++++
8 files changed, 2390 insertions(+), 58 deletions(-)
create mode 100644 author_lock_contract.py
create mode 100644 bootstrap_lock_recovery.py
create mode 100644 docs/author-issue-lock-contract.md
create mode 100644 tests/test_issue_953_bootstrap_lock_contract.py
diff --git a/author_issue_bootstrap.py b/author_issue_bootstrap.py
index 66d2a48..20862c5 100644
--- a/author_issue_bootstrap.py
+++ b/author_issue_bootstrap.py
@@ -23,6 +23,7 @@ import shutil
import subprocess
from typing import Any, Mapping
+import author_lock_contract
import author_mutation_worktree
import control_plane_db
import issue_lock_store
@@ -1198,26 +1199,31 @@ def bootstrap_author_issue_worktree(
save_phase_journal(journal, journal_dir=lock_dir)
# Phase 6: STATE_ESTABLISHED — Issue Lock Acquisition
+ #
+ # #953: this used to hand-build a thinner record — claimant at the top
+ # level, no work_lease, no lock_provenance, no expiry — which every
+ # downstream reader then refused. It now builds through the one shared
+ # canonical contract, so the lock bootstrap writes is the same lock
+ # gitea_lock_issue writes.
from datetime import datetime, timezone
try:
- lock_data = {
- "remote": remote,
- "org": org or "Scaled-Tech-Consulting",
- "repo": repo or "Gitea-Tools",
- "issue_number": issue_number,
- "branch": target_branch,
- "branch_name": target_branch,
- "worktree_path": target_worktree,
- "owner_session": session,
- "claimant": {
- "username": identity,
- "profile": profile,
- },
- "assignment_id": assignment_id,
- "lease_id": lease_id,
- "expected_base_sha": live_master_sha,
- "created_at": datetime.now(timezone.utc).isoformat(),
- }
+ lock_data = author_lock_contract.build_canonical_issue_lock(
+ issue_number=issue_number,
+ branch_name=target_branch,
+ worktree_path=target_worktree,
+ remote=remote,
+ org=org or "Scaled-Tech-Consulting",
+ repo=repo or "Gitea-Tools",
+ identity=identity,
+ profile=profile,
+ tool="gitea_bootstrap_author_issue_worktree",
+ source=author_lock_contract.SOURCE_BOOTSTRAP,
+ owner_session=session,
+ assignment_id=assignment_id,
+ lease_id=lease_id,
+ expected_base_sha=live_master_sha,
+ )
+ lock_data["created_at"] = datetime.now(timezone.utc).isoformat()
journal.setdefault("pending_creations", {})["lock"] = True
journal["artifacts_created"]["lock_created"] = True
save_phase_journal(journal, journal_dir=lock_dir)
@@ -1235,9 +1241,42 @@ def bootstrap_author_issue_worktree(
"exact_next_action": "Verify lease/assignment state and retry.",
}
+ # ── #953 AC7: verify the lock that was actually written ──
+ # Reporting "lock_created: true" and then directing the author to
+ # implement is what produced the unrecoverable state: by the time any
+ # reader refused the lock, the branch already carried commits and every
+ # sanctioned recovery path had become ineligible. The lock is therefore
+ # read back from disk and structurally verified *before* this function
+ # can report success, and a partial lock fails closed here — while the
+ # branch is still base-equivalent and recovery is still cheap.
+ written_lock = issue_lock_store.read_lock_file(lock_res)
+ contract = author_lock_contract.assess_lock_contract(written_lock)
+ if not contract["canonical"]:
+ journal["failure_reason"] = author_lock_contract.format_contract_refusal(
+ contract
+ )
+ run_compensating_recovery(journal, root, journal_dir=lock_dir)
+ return {
+ "success": False,
+ "reason_code": "incomplete_issue_lock_contract",
+ "message": author_lock_contract.format_contract_refusal(contract),
+ "issue_number": issue_number,
+ "branch_name": target_branch,
+ "worktree_path": target_worktree,
+ "lock_state": lock_res,
+ "lock_contract": contract,
+ "missing_fields": contract["missing_fields"],
+ "implementation_allowed": False,
+ # AC15: never strand a branch or worktree without a structured
+ # recovery recommendation.
+ "exact_next_action": author_lock_contract.recommended_action(contract),
+ "phase_journal": journal,
+ }
+
journal["phases"][PHASE_6_STATE_ESTABLISHED] = {
"status": "completed",
"lock": lock_res,
+ "lock_contract": contract["contract"],
}
journal["phases"][PHASE_7_TRANSITION_COMPLETED] = {
"status": "completed",
@@ -1261,9 +1300,16 @@ def bootstrap_author_issue_worktree(
"assignment_id": assignment_id,
"idempotency_key": key,
"lock_state": lock_res,
+ "lock_contract": contract,
+ # #953 AC6: the canonical ownership token for this claim. Never null
+ # on a successful bootstrap — it is the fencing token every
+ # subsequent heartbeat and renewal is checked against.
+ "task_session_id": contract["task_session_id"],
+ "implementation_allowed": True,
"phase_journal": journal,
- "exact_next_action": (
- "Call gitea_whoami, then gitea_resolve_task_capability(task='work_issue') "
- "and proceed with author implementation in the bootstrapped worktree."
- ),
+ # #953 AC5: executable under the state actually returned. The lock
+ # has been read back and verified canonical, so proceeding to
+ # implementation is genuinely the correct next step here — which is
+ # exactly what the old unconditional wording could not promise.
+ "exact_next_action": author_lock_contract.recommended_action(contract),
}
diff --git a/author_lock_contract.py b/author_lock_contract.py
new file mode 100644
index 0000000..05cf42a
--- /dev/null
+++ b/author_lock_contract.py
@@ -0,0 +1,442 @@
+"""One canonical author issue-lock contract shared by every writer (#953).
+
+Before this module, ``gitea_lock_issue`` and
+``gitea_bootstrap_author_issue_worktree`` each wrote their own lock record.
+``gitea_lock_issue`` wrote the canonical shape — ``work_lease`` carrying the
+claimant plus a sanctioned ``lock_provenance`` — while bootstrap wrote a thinner
+record with the claimant at the lock top level, ``lease_id: null``, and no
+``work_lease``, ``lock_provenance``, or expiry at all.
+
+Every downstream reader was written against the canonical shape, so a lock that
+bootstrap reported as successfully created was simultaneously:
+
+* un-heartbeatable — the ownership check read the claimant only from
+ ``work_lease.claimant``;
+* un-renewable — expiry is read only from ``work_lease.expires_at``, so a
+ missing lease read as "never expires", and #760 exact-owner renewal only ever
+ assesses an *expired* lease;
+* un-re-lockable — the branch had by then advanced past its base;
+* and rejected by the #447 create-PR provenance guard.
+
+Each of those gates is individually correct. The defect was that two writers
+disagreed about what a lock *is*. This module is the single definition, and both
+writers now build through it.
+
+Nothing here weakens a guard. ``build_sanctioned_lock_provenance`` remains the
+only provenance source, provenance is never accepted from a caller, and the
+#447 guard is untouched — this module simply makes bootstrap satisfy it.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta, timezone
+from typing import Any, Mapping
+
+import issue_lock_provenance
+import issue_lock_store
+import lease_policy
+
+# Bootstrap writes through the same sanctioned source as gitea_lock_issue: the
+# lock it produces *is* a canonical lock, not a second dialect that readers must
+# learn. Adding a distinct source would have required widening
+# SANCTIONED_LOCK_SOURCES, which is exactly the #447 weakening this issue's
+# safety requirements forbid.
+SOURCE_BOOTSTRAP = issue_lock_provenance.SOURCE_LOCK_ISSUE
+
+#: Recovery of an incomplete bootstrap lock (#953 AC8-AC11).
+SOURCE_BOOTSTRAP_LOCK_RECOVERY = "gitea_recover_incomplete_bootstrap_lock"
+
+#: Top-level keys every canonical author issue lock must carry.
+REQUIRED_LOCK_FIELDS: tuple[str, ...] = (
+ "remote",
+ "org",
+ "repo",
+ "issue_number",
+ "branch_name",
+ "worktree_path",
+ "work_lease",
+ "lock_provenance",
+)
+
+#: Keys every canonical ``work_lease`` must carry.
+REQUIRED_WORK_LEASE_FIELDS: tuple[str, ...] = (
+ "operation_type",
+ "issue_number",
+ "branch",
+ "worktree_path",
+ "claimant",
+ "created_at",
+ "expires_at",
+ "last_heartbeat_at",
+ "task_session_id",
+ "lifecycle_version",
+)
+
+# ── Explicit expiration states (AC12) ──
+# The bug this replaces: a lock with no recorded expiry produced
+# ``is_lease_expired() -> False``, which reads as "not yet expired" and made the
+# lock permanently non-expiring *and* permanently ineligible for the renewal
+# path, which only ever assesses an expired lease. "Absent" and "in the future"
+# are different facts and are now named differently.
+EXPIRATION_RECORDED = "recorded"
+EXPIRATION_MISSING = "missing"
+EXPIRATION_UNPARSEABLE = "unparseable"
+
+#: Structural verdicts returned by :func:`assess_lock_contract`.
+CONTRACT_CANONICAL = "canonical"
+CONTRACT_INCOMPLETE = "incomplete"
+CONTRACT_LEGACY = "legacy"
+CONTRACT_ABSENT = "absent"
+
+
+def _text(value: Any) -> str:
+ return str(value or "").strip()
+
+
+def now_utc() -> datetime:
+ return datetime.now(timezone.utc)
+
+
+def format_timestamp(value: datetime) -> str:
+ """Serialize in the durable ``...Z`` form already used on disk."""
+ return (
+ value.astimezone(timezone.utc)
+ .replace(microsecond=0)
+ .isoformat()
+ .replace("+00:00", "Z")
+ )
+
+
+def lock_claimant(lock: Mapping[str, Any] | None) -> dict[str, str]:
+ """Read the claimant from either canonical or legacy placement.
+
+ ``work_lease.claimant`` is canonical and is preferred. A top-level
+ ``claimant`` is the legacy/bootstrap placement and is accepted as a
+ fallback (AC14) — three separate readers already disagreed about this
+ (``issue_lock_store``, ``issue_lock_renewal``, ``issue_lock_recovery``),
+ which is why it now lives in one place.
+
+ Reading a legacy placement is *not* a widening: every caller still compares
+ the values it returns against server-resolved identity and profile. This
+ only decides where to look, never whether ownership is proven.
+
+ Delegates to ``issue_lock_store.lock_claimant`` rather than reimplementing
+ the rule. A second copy here would be a fourth reader that could drift from
+ the other three, which is the exact failure #953 exists to end. It lives in
+ the store because ``author_lock_contract`` imports the store, so defining it
+ here would make that import circular.
+ """
+ recorded = issue_lock_store.lock_claimant(dict(lock) if isinstance(lock, Mapping) else None)
+ return {
+ "username": _text(recorded.get("username")),
+ "profile": _text(recorded.get("profile")),
+ }
+
+
+def claimant_placement(lock: Mapping[str, Any] | None) -> str:
+ """Where the claimant was found: ``work_lease``, ``top_level``, or ``absent``."""
+ if not isinstance(lock, Mapping):
+ return "absent"
+ lease = lock.get("work_lease")
+ if isinstance(lease, Mapping) and isinstance(lease.get("claimant"), Mapping):
+ return "work_lease"
+ if isinstance(lock.get("claimant"), Mapping):
+ return "top_level"
+ return "absent"
+
+
+def build_claimant(*, username: str | None, profile: str | None) -> dict[str, str]:
+ """Build the canonical claimant pair from server-resolved values."""
+ return {"username": _text(username), "profile": _text(profile)}
+
+
+def build_author_issue_work_lease(
+ *,
+ issue_number: int,
+ branch_name: str,
+ worktree_path: str,
+ claimant: Mapping[str, Any],
+ task_session_id: str | None = None,
+ created: datetime | None = None,
+) -> dict[str, Any]:
+ """Build the canonical author ``work_lease``.
+
+ The single definition behind both writers. The TTL comes from the central
+ policy rather than a literal, and the window slides from the last valid
+ heartbeat (#790), so an abandoned task releases its claim within one TTL.
+ """
+ started = created or now_utc()
+ policy = lease_policy.policy_for(lease_policy.TASK_CLASS_AUTHOR_ISSUE_WORK)
+ expires = started + timedelta(minutes=policy.initial_ttl_minutes)
+ session_id = _text(task_session_id) or issue_lock_store.mint_task_session_id(
+ issue_lock_store.AUTHOR_ISSUE_WORK_LEASE
+ )
+ return {
+ "operation_type": issue_lock_store.AUTHOR_ISSUE_WORK_LEASE,
+ "issue_number": int(issue_number),
+ "pr_number": None,
+ "branch": branch_name,
+ "worktree_path": worktree_path,
+ "claimant": dict(claimant),
+ "created_at": format_timestamp(started),
+ "expires_at": format_timestamp(expires),
+ "last_heartbeat_at": format_timestamp(started),
+ # #790 AC-N1: the ownership key for this task, distinct from the
+ # recorded PID, which is the shared daemon and identifies no task.
+ "task_session_id": session_id,
+ # #790 AC-N8: the explicit lifecycle marker. Its absence — never a
+ # timestamp comparison — is what makes a lock legacy.
+ "lifecycle_version": lease_policy.LIFECYCLE_HEARTBEAT_V1,
+ "heartbeat_count": 1,
+ }
+
+
+def build_canonical_issue_lock(
+ *,
+ issue_number: int,
+ branch_name: str,
+ worktree_path: str,
+ remote: str,
+ org: str,
+ repo: str,
+ identity: str | None,
+ profile: str | None,
+ tool: str,
+ source: str = issue_lock_provenance.SOURCE_LOCK_ISSUE,
+ owner_session: str | None = None,
+ assignment_id: str | None = None,
+ lease_id: str | None = None,
+ expected_base_sha: str | None = None,
+ task_session_id: str | None = None,
+ created: datetime | None = None,
+) -> dict[str, Any]:
+ """Build a complete canonical lock record.
+
+ ``tool`` and ``source`` are server-supplied. There is deliberately no
+ parameter through which a caller could inject provenance: the #953 safety
+ requirements forbid caller-manufactured provenance, so provenance is always
+ minted here from ``build_sanctioned_lock_provenance``.
+ """
+ claimant = build_claimant(username=identity, profile=profile)
+ work_lease = build_author_issue_work_lease(
+ issue_number=issue_number,
+ branch_name=branch_name,
+ worktree_path=worktree_path,
+ claimant=claimant,
+ task_session_id=task_session_id,
+ created=created,
+ )
+ record: dict[str, Any] = {
+ "remote": remote,
+ "org": org,
+ "repo": repo,
+ "issue_number": int(issue_number),
+ "branch": branch_name,
+ "branch_name": branch_name,
+ "worktree_path": worktree_path,
+ "work_lease": work_lease,
+ "lock_provenance": issue_lock_provenance.build_sanctioned_lock_provenance(
+ tool=tool,
+ source=source,
+ claimant=claimant,
+ ),
+ }
+ if owner_session is not None:
+ record["owner_session"] = owner_session
+ if assignment_id is not None:
+ record["assignment_id"] = assignment_id
+ # #953 AC6: a null lease id is recorded only when no workflow lease was
+ # allocated for this bootstrap. The task-session identifier in the
+ # work_lease is what downstream ownership checks fence on, and it is never
+ # null on a canonical lock.
+ if lease_id is not None:
+ record["lease_id"] = lease_id
+ if expected_base_sha is not None:
+ record["expected_base_sha"] = expected_base_sha
+ return record
+
+
+def expiration_state(lock: Mapping[str, Any] | None) -> dict[str, Any]:
+ """Classify a lock's recorded expiry explicitly (AC12).
+
+ Distinguishes "no expiry was ever recorded" from "an expiry was recorded
+ and is still in the future". Collapsing those two into a single ``False``
+ from ``is_lease_expired`` is what let a malformed lock be treated as
+ permanently live and simultaneously never renewable.
+ """
+ if not isinstance(lock, Mapping):
+ return {"state": EXPIRATION_MISSING, "expires_at": None, "expired": None}
+ lease = lock.get("work_lease")
+ raw = lease.get("expires_at") if isinstance(lease, Mapping) else None
+ text = _text(raw)
+ if not text:
+ return {"state": EXPIRATION_MISSING, "expires_at": None, "expired": None}
+ try:
+ parsed = datetime.fromisoformat(text.replace("Z", "+00:00")).astimezone(
+ timezone.utc
+ )
+ except ValueError:
+ return {"state": EXPIRATION_UNPARSEABLE, "expires_at": text, "expired": None}
+ return {
+ "state": EXPIRATION_RECORDED,
+ "expires_at": text,
+ "expired": parsed <= now_utc(),
+ }
+
+
+def missing_contract_fields(lock: Mapping[str, Any] | None) -> list[str]:
+ """Name every canonical field a lock does not carry (AC7)."""
+ if not isinstance(lock, Mapping):
+ return [""]
+ missing: list[str] = []
+ for field in REQUIRED_LOCK_FIELDS:
+ value = lock.get(field)
+ if value is None or (isinstance(value, str) and not value.strip()):
+ missing.append(field)
+ lease = lock.get("work_lease")
+ if not isinstance(lease, Mapping):
+ if "work_lease" not in missing:
+ missing.append("work_lease")
+ else:
+ for field in REQUIRED_WORK_LEASE_FIELDS:
+ value = lease.get(field)
+ if value is None or (isinstance(value, str) and not value.strip()):
+ missing.append(f"work_lease.{field}")
+ provenance = lock.get("lock_provenance")
+ if isinstance(provenance, Mapping):
+ if (
+ _text(provenance.get("source"))
+ not in issue_lock_provenance.SANCTIONED_LOCK_SOURCES
+ ):
+ missing.append("lock_provenance.source (not sanctioned)")
+ if not _text(provenance.get("written_by_tool")):
+ missing.append("lock_provenance.written_by_tool")
+ claimant = lock_claimant(lock)
+ if not claimant["username"]:
+ missing.append("claimant.username")
+ if not claimant["profile"]:
+ missing.append("claimant.profile")
+ return missing
+
+
+def assess_lock_contract(lock: Mapping[str, Any] | None) -> dict[str, Any]:
+ """Structural, read-only verdict on a durable lock record (AC7, AC16).
+
+ Pure inspection: it reads the record it is handed and mutates nothing —
+ no lock, lease, branch, worktree, issue, or PR. Callers use it both to
+ verify a lock they just wrote and to report on one they found.
+ """
+ if not isinstance(lock, Mapping) or not lock:
+ return {
+ "contract": CONTRACT_ABSENT,
+ "canonical": False,
+ "missing_fields": [""],
+ "claimant": {"username": "", "profile": ""},
+ "claimant_placement": "absent",
+ "expiration": {
+ "state": EXPIRATION_MISSING,
+ "expires_at": None,
+ "expired": None,
+ },
+ "heartbeatable": False,
+ "create_pr_eligible": False,
+ "lock_generation": None,
+ "task_session_id": None,
+ "reasons": ["no durable lock record"],
+ }
+
+ missing = missing_contract_fields(lock)
+ claimant = lock_claimant(lock)
+ placement = claimant_placement(lock)
+ expiration = expiration_state(lock)
+ provenance_check = issue_lock_provenance.assess_lock_file_for_create_pr(dict(lock))
+
+ # Canonical means: every required field present, the claimant in the
+ # canonical placement, an expiry actually recorded, and the untouched #447
+ # guard satisfied.
+ canonical = (
+ not missing
+ and placement == "work_lease"
+ and expiration["state"] == EXPIRATION_RECORDED
+ and bool(provenance_check.get("proven"))
+ )
+ if canonical:
+ contract = CONTRACT_CANONICAL
+ elif placement == "top_level" and claimant["username"] and claimant["profile"]:
+ contract = CONTRACT_LEGACY
+ else:
+ contract = CONTRACT_INCOMPLETE
+
+ reasons: list[str] = []
+ if missing:
+ reasons.append("missing canonical fields: " + ", ".join(missing))
+ if placement == "top_level":
+ reasons.append(
+ "claimant recorded at the lock top level rather than in work_lease "
+ "(legacy/bootstrap placement)"
+ )
+ if expiration["state"] == EXPIRATION_MISSING:
+ reasons.append(
+ "no expiration recorded; the lock is neither expirable nor renewable "
+ "until it is upgraded"
+ )
+ elif expiration["state"] == EXPIRATION_UNPARSEABLE:
+ reasons.append(f"unparseable expires_at '{expiration['expires_at']}'")
+ if provenance_check.get("block"):
+ reasons.extend(provenance_check.get("reasons") or [])
+
+ # Heartbeat needs the claimant pair (from either placement, post-fix) plus a
+ # task-session identifier to fence on.
+ lease = lock.get("work_lease")
+ task_session_id = (
+ _text(lease.get("task_session_id")) if isinstance(lease, Mapping) else ""
+ )
+ heartbeatable = bool(
+ claimant["username"] and claimant["profile"] and task_session_id
+ )
+
+ return {
+ "contract": contract,
+ "canonical": canonical,
+ "missing_fields": missing,
+ "claimant": claimant,
+ "claimant_placement": placement,
+ "expiration": expiration,
+ "heartbeatable": heartbeatable,
+ "create_pr_eligible": bool(provenance_check.get("proven")),
+ "lock_generation": lock.get("lock_generation"),
+ "task_session_id": task_session_id or None,
+ "reasons": reasons,
+ }
+
+
+def format_contract_refusal(assessment: Mapping[str, Any]) -> str:
+ """Human-readable refusal naming exactly what the lock is missing."""
+ missing = ", ".join(assessment.get("missing_fields") or []) or "unknown fields"
+ return (
+ "Issue lock contract incomplete (#953): "
+ f"{missing}. The lock cannot be heartbeated, renewed, or accepted by "
+ "gitea_create_pr in this state (fail closed)"
+ )
+
+
+def recommended_action(assessment: Mapping[str, Any]) -> str:
+ """The one executable next step for a lock in this state (AC5, AC15)."""
+ contract = assessment.get("contract")
+ if contract == CONTRACT_CANONICAL:
+ return (
+ "Lock is canonical. Call gitea_whoami, then "
+ "gitea_resolve_task_capability(task='work_issue'), then proceed with "
+ "author implementation in the bootstrapped worktree."
+ )
+ if contract == CONTRACT_ABSENT:
+ return (
+ "No durable lock exists. Call gitea_lock_issue for this issue and "
+ "branch before writing any implementation bytes."
+ )
+ return (
+ "Do not begin implementation. Call "
+ "gitea_recover_incomplete_bootstrap_lock for this exact issue, branch, "
+ "and worktree to upgrade the lock to the canonical contract, or "
+ "gitea_lock_issue while the worktree is still base-equivalent."
+ )
diff --git a/bootstrap_lock_recovery.py b/bootstrap_lock_recovery.py
new file mode 100644
index 0000000..a451c91
--- /dev/null
+++ b/bootstrap_lock_recovery.py
@@ -0,0 +1,304 @@
+"""Target-specific recovery for incomplete bootstrap issue locks (#953).
+
+The situation this exists for: ``gitea_bootstrap_author_issue_worktree``
+reported success, wrote an incomplete lock, and told the author to implement.
+The author did — legitimately, following the tool's own reported next action —
+and the branch now carries real committed and pushed work. At that point every
+pre-existing recovery path is simultaneously ineligible:
+
+* heartbeat refuses, because the claimant is not where it looks;
+* ``gitea_lock_issue`` refuses, because the branch is no longer base-equivalent;
+* #760 exact-owner renewal never engages, because a lock with no recorded
+ expiry is never *expired*;
+* the #447 create-PR guard refuses, because there is no provenance.
+
+Distinct from every neighbouring path: #753 ``issue_lock_recovery`` requires a
+dead owner PID, #760 ``issue_lock_renewal`` requires an *expired* lease, and
+#442 ``issue_lock_adoption`` decides branch adoption. None of them addresses a
+lock that is structurally incomplete and therefore never expires at all.
+
+**What this will not do.** It never moves, resets, or rewinds a branch, and
+never requires base-equivalence — the committed work is the thing being
+preserved. It never pushes and never opens a pull request. It touches only the
+one lock file named by (remote, org, repo, issue). It accepts no caller-supplied
+provenance and no caller-supplied authorization flag; both are minted
+server-side. It refuses a healthy foreign-owned lock outright, and a matching
+username alone is never accepted as proof of ownership — the profile must match
+too, and the lock's recorded binding must agree with the observed branch,
+worktree, and head.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Mapping
+
+import author_lock_contract
+import issue_lock_store
+
+#: Refusal codes, so callers can branch on cause rather than parse prose.
+REFUSAL_NO_LOCK = "no_durable_lock"
+REFUSAL_ALREADY_CANONICAL = "already_canonical"
+REFUSAL_FOREIGN_CLAIMANT = "foreign_claimant"
+REFUSAL_HEALTHY_FOREIGN = "healthy_foreign_lock"
+REFUSAL_IDENTITY_UNRESOLVED = "identity_unresolved"
+REFUSAL_BINDING_MISMATCH = "binding_mismatch"
+REFUSAL_WORKTREE_INVALID = "worktree_invalid"
+REFUSAL_HEAD_MISMATCH = "head_mismatch"
+
+
+def _text(value: Any) -> str:
+ return str(value or "").strip()
+
+
+def _same_realpath(left: str | None, right: str | None) -> bool:
+ lhs, rhs = _text(left), _text(right)
+ if not lhs or not rhs:
+ return False
+ try:
+ return os.path.realpath(lhs) == os.path.realpath(rhs)
+ except OSError:
+ return lhs == rhs
+
+
+def assess_bootstrap_lock_recovery(
+ existing_lock: Mapping[str, Any] | None,
+ *,
+ issue_number: int,
+ branch_name: str,
+ worktree_path: str,
+ remote: str,
+ org: str,
+ repo: str,
+ identity: str | None,
+ profile: str | None,
+ observed_head: str | None,
+ declared_head: str | None,
+ worktree_exists: bool,
+ worktree_registered: bool,
+ current_branch: str | None,
+ now: Any = None,
+) -> dict[str, Any]:
+ """Decide whether this exact lock may be upgraded by this exact caller.
+
+ Pure: every input is an observation the caller already made, and nothing
+ here reads or writes the filesystem, git, or Gitea. That is what makes the
+ same decision testable in isolation and reusable by the read-only
+ inspection surface, which must not mutate anything (AC16).
+
+ Returns a dict with ``recovery_sanctioned`` plus the full evidence set. A
+ refusal never raises — it reports, so the caller can surface exactly which
+ piece of evidence was missing.
+ """
+ reasons: list[str] = []
+ refusal_code: str | None = None
+
+ contract = author_lock_contract.assess_lock_contract(existing_lock)
+
+ if not existing_lock:
+ return {
+ "recovery_sanctioned": False,
+ "refusal_code": REFUSAL_NO_LOCK,
+ "reasons": [
+ f"no durable issue lock exists for issue #{issue_number}; there is "
+ "nothing to recover (fail closed)"
+ ],
+ "contract": contract,
+ "evidence": {},
+ "expected_generation": None,
+ }
+
+ active_identity = _text(identity)
+ active_profile = _text(profile)
+ recorded = author_lock_contract.lock_claimant(existing_lock)
+ freshness = issue_lock_store.assess_lock_freshness(dict(existing_lock), now=now)
+ generation = issue_lock_store.lock_generation(existing_lock)
+
+ evidence: dict[str, Any] = {
+ "recorded_claimant": recorded,
+ "active_identity": active_identity,
+ "active_profile": active_profile,
+ "recorded_branch": existing_lock.get("branch_name"),
+ "recorded_worktree": existing_lock.get("worktree_path"),
+ "recorded_owner_session": existing_lock.get("owner_session"),
+ "recorded_generation": generation,
+ "recorded_remote": existing_lock.get("remote"),
+ "recorded_org": existing_lock.get("org"),
+ "recorded_repo": existing_lock.get("repo"),
+ "observed_head": _text(observed_head),
+ "declared_head": _text(declared_head),
+ "current_branch": _text(current_branch),
+ "worktree_exists": bool(worktree_exists),
+ "worktree_registered": bool(worktree_registered),
+ "freshness": freshness,
+ "claimant_placement": contract.get("claimant_placement"),
+ "expiration_state": contract.get("expiration", {}).get("state"),
+ }
+
+ # ── Repository and issue identity (AC10) ──
+ if _text(existing_lock.get("remote")) != _text(remote):
+ reasons.append(
+ f"recorded remote '{existing_lock.get('remote')}' does not match '{remote}'"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+ if _text(existing_lock.get("org")) != _text(org):
+ reasons.append(
+ f"recorded org '{existing_lock.get('org')}' does not match '{org}'"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+ if _text(existing_lock.get("repo")) != _text(repo):
+ reasons.append(
+ f"recorded repo '{existing_lock.get('repo')}' does not match '{repo}'"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+ if existing_lock.get("issue_number") != issue_number:
+ reasons.append(
+ f"lock targets issue #{existing_lock.get('issue_number')}, not "
+ f"#{issue_number}"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+
+ # ── Branch and worktree binding (AC10) ──
+ if _text(existing_lock.get("branch_name")) != _text(branch_name):
+ reasons.append(
+ f"recorded branch '{existing_lock.get('branch_name')}' does not match "
+ f"'{branch_name}'"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+ if not _same_realpath(existing_lock.get("worktree_path"), worktree_path):
+ reasons.append(
+ f"recorded worktree '{existing_lock.get('worktree_path')}' does not "
+ f"match '{worktree_path}'"
+ )
+ refusal_code = refusal_code or REFUSAL_BINDING_MISMATCH
+
+ # ── The worktree is real, registered, and on the branch (AC10) ──
+ # Deliberately no base-equivalence requirement and no constraint on how far
+ # the branch has advanced: the whole point is that it already carries the
+ # author's legitimate commits (AC9).
+ if not worktree_exists:
+ reasons.append(f"declared worktree '{worktree_path}' does not exist")
+ refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+ if not worktree_registered:
+ reasons.append(f"worktree '{worktree_path}' is not a registered git worktree")
+ refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+ if _text(current_branch) != _text(branch_name):
+ reasons.append(
+ f"worktree is on branch '{_text(current_branch) or 'unknown'}', not "
+ f"'{branch_name}'"
+ )
+ refusal_code = refusal_code or REFUSAL_WORKTREE_INVALID
+
+ # ── Current head fencing (AC10) ──
+ # The caller names the commit it believes it is recovering. A mismatch means
+ # the worktree moved under the caller, so the decision is stale.
+ if not _text(observed_head):
+ reasons.append("could not observe the worktree head")
+ refusal_code = refusal_code or REFUSAL_HEAD_MISMATCH
+ elif _text(declared_head) and _text(declared_head) != _text(observed_head):
+ reasons.append(
+ f"declared head '{_text(declared_head)}' does not match observed head "
+ f"'{_text(observed_head)}'"
+ )
+ refusal_code = refusal_code or REFUSAL_HEAD_MISMATCH
+
+ # ── Ownership (AC10, AC11) ──
+ # A matching username alone is never sufficient: the profile must match too,
+ # and both are compared against server-resolved values the caller cannot set.
+ if not active_identity or not active_profile:
+ reasons.append(
+ "active identity and profile could not both be resolved; ownership "
+ "cannot be proven"
+ )
+ refusal_code = refusal_code or REFUSAL_IDENTITY_UNRESOLVED
+ if not recorded["username"] or not recorded["profile"]:
+ reasons.append(
+ "durable lock does not record both a claimant username and profile"
+ )
+ refusal_code = refusal_code or REFUSAL_FOREIGN_CLAIMANT
+ elif (
+ recorded["username"] != active_identity
+ or recorded["profile"] != active_profile
+ ):
+ # AC11: a foreign-owned lock is never recoverable through this path,
+ # healthy or not. The healthy case is reported distinctly so the refusal
+ # is legible, but both refuse.
+ if freshness.get("live"):
+ reasons.append(
+ f"lock is owned by a healthy foreign claimant "
+ f"'{recorded['username']}/{recorded['profile']}'; takeover is not "
+ "a recovery path"
+ )
+ refusal_code = REFUSAL_HEALTHY_FOREIGN
+ else:
+ reasons.append(
+ f"lock claimant '{recorded['username']}/{recorded['profile']}' "
+ f"does not match active '{active_identity}/{active_profile}'"
+ )
+ refusal_code = refusal_code or REFUSAL_FOREIGN_CLAIMANT
+
+ # ── Nothing to recover ──
+ # A lock that is already canonical is left strictly alone. Rewriting it would
+ # mint a new task-session identifier and invalidate the heartbeat token the
+ # legitimate owner is already using.
+ if contract.get("canonical") and not reasons:
+ return {
+ "recovery_sanctioned": False,
+ "refusal_code": REFUSAL_ALREADY_CANONICAL,
+ "reasons": [
+ "lock already satisfies the canonical contract; no recovery is "
+ "required"
+ ],
+ "contract": contract,
+ "evidence": evidence,
+ "expected_generation": generation,
+ }
+
+ sanctioned = not reasons
+ return {
+ "recovery_sanctioned": sanctioned,
+ "refusal_code": None if sanctioned else refusal_code,
+ "reasons": reasons,
+ "contract": contract,
+ "evidence": evidence,
+ "expected_generation": generation,
+ }
+
+
+def build_recovery_record(
+ assessment: Mapping[str, Any],
+ *,
+ recovered_at: str,
+ new_task_session_id: str,
+) -> dict[str, Any]:
+ """Auditable record of the ownership and generation transition (AC10).
+
+ A recovered lock must never read as an original claim, so both sides of the
+ transition are preserved: what the incomplete lock recorded, and what
+ replaced it.
+ """
+ evidence = dict(assessment.get("evidence") or {})
+ contract = dict(assessment.get("contract") or {})
+ return {
+ "recovery_kind": "incomplete_bootstrap_lock",
+ "recovered_at": recovered_at,
+ "prior_contract": contract.get("contract"),
+ "prior_missing_fields": list(contract.get("missing_fields") or []),
+ "prior_claimant_placement": evidence.get("claimant_placement"),
+ "prior_expiration_state": evidence.get("expiration_state"),
+ "prior_generation": evidence.get("recorded_generation"),
+ "prior_owner_session": evidence.get("recorded_owner_session"),
+ "prior_freshness": (evidence.get("freshness") or {}).get("status"),
+ "replacement_task_session_id": new_task_session_id,
+ "preserved_head": evidence.get("observed_head"),
+ "branch_reset": False,
+ "base_equivalence_required": False,
+ }
+
+
+def format_recovery_refusal(assessment: Mapping[str, Any]) -> str:
+ reasons = "; ".join(
+ assessment.get("reasons") or ["unknown bootstrap lock recovery refusal"]
+ )
+ code = assessment.get("refusal_code") or "refused"
+ return f"Bootstrap lock recovery refused ({code}): {reasons} (fail closed)"
diff --git a/docs/author-issue-lock-contract.md b/docs/author-issue-lock-contract.md
new file mode 100644
index 0000000..f9f360d
--- /dev/null
+++ b/docs/author-issue-lock-contract.md
@@ -0,0 +1,148 @@
+# The canonical author issue-lock contract (#953)
+
+Every author issue lock has exactly one shape. Both writers —
+`gitea_bootstrap_author_issue_worktree` and `gitea_lock_issue` — build it
+through `author_lock_contract.build_canonical_issue_lock`, and every reader
+consumes that same shape.
+
+Before #953 the two writers disagreed. `gitea_lock_issue` wrote the canonical
+record; bootstrap wrote a thinner one with the claimant at the lock top level,
+`lease_id: null`, and no `work_lease`, `lock_provenance`, or expiry. Because
+every reader was written against the canonical shape, a lock that bootstrap
+reported as successfully created could not be heartbeated, renewed, re-locked,
+or accepted by `gitea_create_pr`. Each of those gates was individually correct;
+the defect was that two writers disagreed about what a lock *is*.
+
+## Required ordering
+
+**Finalize the lock before writing any implementation bytes.** This ordering is
+what keeps recovery cheap: while the worktree is still base-equivalent, a lock
+problem can be fixed by simply calling `gitea_lock_issue` again. Once the branch
+carries commits, base-equivalence is gone and the ordinary re-lock path is no
+longer available.
+
+1. `gitea_whoami` — resolve identity and profile.
+2. `gitea_resolve_task_capability(task='work_issue')`.
+3. `gitea_bootstrap_author_issue_worktree` — creates the branch, the registered
+ worktree under `branches/`, and a **canonical** lock. It reads the lock back
+ and verifies it structurally before reporting success; a partial lock fails
+ closed here, with the missing fields named, and never reports
+ `implementation_allowed: true`.
+4. `gitea_heartbeat_issue_lock` — prove the lock is usable, using the
+ `task_session_id` bootstrap returned.
+5. Implement, commit, push.
+6. `gitea_create_pr`.
+
+If bootstrap returns `success: false` with
+`reason_code: incomplete_issue_lock_contract`, **do not implement**. Its
+`exact_next_action` names the executable recovery step. Bootstrap's reported
+next action always matches the state it actually returned.
+
+## The contract
+
+A canonical lock carries every field in
+`author_lock_contract.REQUIRED_LOCK_FIELDS`:
+
+| Field | Meaning |
+| --- | --- |
+| `remote`, `org`, `repo`, `issue_number` | repository and issue identity |
+| `branch_name`, `worktree_path` | the binding this claim owns |
+| `work_lease` | the canonical lease block, below |
+| `lock_provenance` | sanctioned source, minted server-side |
+| `lock_generation` | monotonic; every write advances it |
+
+`work_lease` carries every field in
+`author_lock_contract.REQUIRED_WORK_LEASE_FIELDS`, notably:
+
+| Field | Meaning |
+| --- | --- |
+| `claimant.{username,profile}` | **canonical** claimant placement |
+| `expires_at` | sliding TTL from `lease_policy` |
+| `last_heartbeat_at`, `heartbeat_count` | liveness evidence |
+| `task_session_id` | the ownership fencing token — never null |
+| `lifecycle_version` | `heartbeat-v1`; its absence is what makes a lock legacy |
+
+### Claimant placement and legacy compatibility
+
+`work_lease.claimant` is canonical. A top-level `claimant` is the legacy
+placement written by pre-#953 bootstrap and is still **read** — through the one
+shared reader, `issue_lock_store.lock_claimant` — so an existing lock is not
+refused for "not recording a claimant" when it plainly records one.
+
+Tolerating the placement is not a widening. Every caller still compares the
+values against server-resolved identity and profile, so a legacy placement
+grants nothing the canonical placement would not. When both are present, the
+`work_lease` copy wins: after an upgrade, a stale top-level copy must never
+decide ownership.
+
+### Expiration is explicit
+
+A lock with no recorded expiry is **not** "not yet expired". `is_lease_expired`
+returns `False` for it, which used to make such a lock permanently non-expiring
+*and* permanently ineligible for #760 exact-owner renewal, which only ever
+assesses an expired lease. `author_lock_contract.expiration_state` names the
+real fact: `recorded`, `missing`, or `unparseable`. A `missing` expiry makes the
+lock eligible for the recovery path below rather than stranding it.
+
+## Recovering an existing incomplete bootstrap lock
+
+For locks already written by the old bootstrap — including those whose branches
+already carry legitimate committed and pushed work — use:
+
+```text
+gitea_inspect_issue_lock_contract(issue_number, branch_name, worktree_path, remote=...)
+gitea_recover_incomplete_bootstrap_lock(issue_number, branch_name, worktree_path, expected_head, remote=...)
+```
+
+`gitea_inspect_issue_lock_contract` is strictly read-only: it performs no lock,
+lease, branch, worktree, issue, or pull-request mutation. Use it first to see
+which fields are missing and what the recommended action is; pass `dry_run=True`
+to the recovery tool to preview the decision without writing.
+
+`gitea_recover_incomplete_bootstrap_lock` upgrades that one lock to the
+canonical contract. Before writing anything it verifies:
+
+* repository (`remote`, `org`, `repo`) and issue number
+* claimant username **and** profile against the server-resolved values — a
+ matching username alone is never accepted
+* branch, worktree path, worktree existence, and worktree registration
+* the worktree is on the recorded branch
+* the observed head equals the caller's `expected_head`
+* the existing lock's generation and provenance state
+* the absence of healthy foreign ownership
+
+What it deliberately does **not** do:
+
+* it never moves, resets, or rewinds the branch, and never requires
+ base-equivalence — preserving the committed work is the entire point;
+* it never pushes and never creates a pull request;
+* it touches only the single lock file for that exact remote/org/repo/issue;
+* it accepts no caller-supplied provenance and no caller-supplied authorization
+ flag — both are minted server-side.
+
+A recovered lock records a `bootstrap_lock_recovery` block holding both sides of
+the transition — prior contract, prior missing fields, prior generation, prior
+owning session, the replacement `task_session_id`, and the preserved head — so a
+recovered claim never reads as an original one.
+
+### Refusals
+
+| `refusal_code` | Meaning |
+| --- | --- |
+| `no_durable_lock` | nothing to recover |
+| `already_canonical` | lock is fine; rewriting would invalidate a live heartbeat token |
+| `foreign_claimant` | recorded claimant is not the active identity/profile pair |
+| `healthy_foreign_lock` | a live foreign-owned lock; takeover is not a recovery path |
+| `identity_unresolved` | identity or profile could not be resolved |
+| `binding_mismatch` | repository, issue, branch, or worktree does not match |
+| `worktree_invalid` | worktree missing, unregistered, or on another branch |
+| `head_mismatch` | the worktree moved under the caller |
+
+## The #447 create-PR provenance guard is unchanged
+
+`issue_lock_provenance.assess_lock_file_for_create_pr` still requires both a
+sanctioned `lock_provenance` and a `work_lease`, and the sanctioned source set
+was **not** widened. Bootstrap writes through
+`issue_lock_provenance.SOURCE_LOCK_ISSUE` — the lock it produces *is* a
+canonical lock, not a second dialect with its own exemption. Bootstrap now
+satisfies the guard rather than the guard being relaxed to admit bootstrap.
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index 3721039..a3fed3a 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -2110,6 +2110,8 @@ 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 author_lock_contract # noqa: E402
+import bootstrap_lock_recovery # noqa: E402
import dirty_orphan_worktree_recovery # noqa: E402 # #860 dirty orphan recovery
import dirty_same_claimant_session_rebind # noqa: E402 # #864
import stacked_pr_support # noqa: E402
@@ -2658,33 +2660,17 @@ def _build_author_issue_work_lease(
worktree_path: str,
host: str | None,
) -> dict:
- created = _work_lease_now()
- # #790 Slice A: the window comes from the central policy, not a literal here.
- # It is also now a *sliding* window — the lease lives ``initial_ttl_minutes``
- # past its last valid heartbeat rather than a fixed four hours past its
- # creation, so an abandoned task stops holding the claim within one TTL.
- policy = lease_policy.policy_for(lease_policy.TASK_CLASS_AUTHOR_ISSUE_WORK)
- expires = created + timedelta(minutes=policy.initial_ttl_minutes)
- return {
- "operation_type": AUTHOR_ISSUE_WORK_LEASE,
- "issue_number": issue_number,
- "pr_number": None,
- "branch": branch_name,
- "worktree_path": worktree_path,
- "claimant": _work_lease_claimant(host),
- "created_at": _work_lease_timestamp(created),
- "expires_at": _work_lease_timestamp(expires),
- "last_heartbeat_at": _work_lease_timestamp(created),
- # #790 AC-N1: the ownership key for this task. Distinct from the recorded
- # PID, which is the shared daemon and identifies no individual task.
- "task_session_id": issue_lock_store.mint_task_session_id(
- AUTHOR_ISSUE_WORK_LEASE
- ),
- # #790 AC-N8: the explicit lifecycle marker. Its absence — never a
- # timestamp comparison — is what makes a lock legacy.
- "lifecycle_version": lease_policy.LIFECYCLE_HEARTBEAT_V1,
- "heartbeat_count": 1,
- }
+ # #953: the lease shape now lives in author_lock_contract so that bootstrap
+ # and gitea_lock_issue cannot drift apart again. The policy-derived sliding
+ # TTL (#790 Slice A) and the task-session ownership key (#790 AC-N1) are
+ # unchanged — they simply have one definition instead of two.
+ return author_lock_contract.build_author_issue_work_lease(
+ issue_number=issue_number,
+ branch_name=branch_name,
+ worktree_path=worktree_path,
+ claimant=_work_lease_claimant(host),
+ created=_work_lease_now(),
+ )
def _active_work_lease_block(
@@ -4954,6 +4940,355 @@ def gitea_heartbeat_issue_lock(
return outcome
+def _observe_recovery_worktree(worktree_path: str) -> dict:
+ """Observe head, branch, existence, and registration for lock recovery.
+
+ Read-only: it runs ``git`` queries and touches nothing. Kept separate from
+ the decision so the decision stays a pure function of observations (#953).
+ """
+ observation = {
+ "worktree_exists": os.path.isdir(worktree_path),
+ "worktree_registered": False,
+ "current_branch": "",
+ "observed_head": "",
+ }
+ if not observation["worktree_exists"]:
+ return observation
+ try:
+ observation["current_branch"] = subprocess.run(
+ ["git", "-C", worktree_path, "rev-parse", "--abbrev-ref", "HEAD"],
+ capture_output=True,
+ text=True,
+ check=False,
+ ).stdout.strip()
+ observation["observed_head"] = subprocess.run(
+ ["git", "-C", worktree_path, "rev-parse", "HEAD"],
+ capture_output=True,
+ text=True,
+ check=False,
+ ).stdout.strip()
+ listing = subprocess.run(
+ ["git", "-C", worktree_path, "worktree", "list", "--porcelain"],
+ capture_output=True,
+ text=True,
+ check=False,
+ ).stdout
+ real = os.path.realpath(worktree_path)
+ observation["worktree_registered"] = any(
+ os.path.realpath(line.split(" ", 1)[1].strip()) == real
+ for line in listing.splitlines()
+ if line.startswith("worktree ")
+ )
+ except Exception: # fail closed: unobservable is not provable
+ return observation
+ return observation
+
+
+@mcp.tool()
+def gitea_inspect_issue_lock_contract(
+ issue_number: int,
+ branch_name: str | None = None,
+ worktree_path: str | None = None,
+ remote: str = "dadeschools",
+ host: str | None = None,
+ org: str | None = None,
+ repo: str | None = None,
+) -> dict:
+ """Inspect a durable author issue lock against the canonical contract (#953 AC8/AC16).
+
+ Strictly read-only. It performs no lock, lease, branch, worktree, issue, or
+ pull-request mutation of any kind — it reads the durable lock record and
+ reports. Use it to find out *why* a lock is being refused before choosing a
+ recovery path, and to confirm afterwards that recovery produced a canonical
+ lock.
+
+ Reports which canonical fields are missing, where the claimant is recorded
+ (``work_lease`` is canonical, top level is the legacy/bootstrap placement),
+ whether an expiration is actually recorded — as opposed to absent, which
+ used to masquerade as "not yet expired" — whether the lock can be
+ heartbeated, and whether it satisfies the untouched #447 create-PR
+ provenance guard.
+
+ Args:
+ issue_number: The issue whose lock to inspect.
+ branch_name: Optional; when given, the recovery eligibility preview is
+ evaluated against this branch.
+ worktree_path: Optional; when given, the recovery eligibility preview is
+ evaluated against this worktree.
+ remote: Known instance — 'dadeschools' or 'prgs'.
+ host: Override the Gitea host.
+ org: Override the owner/organization.
+ repo: Override the repository name.
+
+ Returns:
+ dict with 'success', 'lock_present', 'lock_contract' (the structural
+ verdict), 'recommended_action', and — when branch_name and
+ worktree_path are supplied — a non-mutating 'recovery_preview'.
+ """
+ blocked = _profile_permission_block(
+ "gitea.read",
+ 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
+
+ h, o, r = _resolve(remote, host, org, repo)
+ existing = _load_existing_issue_lock(
+ remote=remote, org=o, repo=r, issue_number=issue_number
+ )
+ contract = author_lock_contract.assess_lock_contract(existing)
+ result = {
+ "success": True,
+ "performed": False,
+ "mutation_performed": False,
+ "read_only": True,
+ "issue_number": issue_number,
+ "lock_present": bool(existing),
+ "lock_contract": contract,
+ "lock_freshness": (
+ issue_lock_store.assess_lock_freshness(dict(existing))
+ if existing
+ else {"status": issue_lock_store.STATUS_ABSENT, "live": False}
+ ),
+ "recommended_action": author_lock_contract.recommended_action(contract),
+ }
+
+ if branch_name and worktree_path:
+ resolved = issue_lock_worktree.resolve_author_worktree_path(
+ worktree_path, _canonical_local_git_root()
+ )
+ observation = _observe_recovery_worktree(resolved)
+ claimant = _work_lease_claimant(h)
+ result["recovery_preview"] = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ existing,
+ issue_number=issue_number,
+ branch_name=branch_name,
+ worktree_path=resolved,
+ remote=remote,
+ org=o,
+ repo=r,
+ identity=claimant.get("username"),
+ profile=claimant.get("profile"),
+ observed_head=observation["observed_head"],
+ declared_head=None,
+ worktree_exists=observation["worktree_exists"],
+ worktree_registered=observation["worktree_registered"],
+ current_branch=observation["current_branch"],
+ )
+ return result
+
+
+@mcp.tool()
+def gitea_recover_incomplete_bootstrap_lock(
+ issue_number: int,
+ branch_name: str,
+ worktree_path: str,
+ expected_head: str,
+ remote: str = "dadeschools",
+ host: str | None = None,
+ org: str | None = None,
+ repo: str | None = None,
+ dry_run: bool = False,
+) -> dict:
+ """Upgrade an incomplete bootstrap issue lock to the canonical contract (#953 AC8-AC11).
+
+ Explicit, target-specific recovery. It does **not** widen
+ ``gitea_lock_issue``, and it is not a takeover path.
+
+ The state it repairs: ``gitea_bootstrap_author_issue_worktree`` reported
+ success but wrote a lock with the claimant at the top level, no
+ ``work_lease``, no ``lock_provenance``, and no expiry. The author then
+ implemented, committed, and pushed — following bootstrap's own reported next
+ action — after which heartbeat, re-lock, exact-owner renewal, and the #447
+ create-PR guard all refuse simultaneously.
+
+ Deliberate non-behaviours: the branch is never moved, reset, or rewound, and
+ base-equivalence is never required — preserving the already-committed and
+ pushed work is the entire point. Nothing is pushed and no pull request is
+ created. Only the single lock file for this exact (remote, org, repo, issue)
+ is written.
+
+ Ownership is proven, never asserted. The claimant recorded on the durable
+ lock must match **both** the server-resolved identity and the active
+ profile; a matching username alone is refused. Repository, issue, branch,
+ worktree, registration, current branch, and head are all verified before any
+ write, and the declared ``expected_head`` must equal the observed head. A
+ healthy foreign-owned lock is refused outright. Provenance and authorization
+ are minted server-side — there is no parameter through which a caller can
+ supply either.
+
+ Args:
+ issue_number: The issue whose incomplete lock is being recovered.
+ branch_name: The branch recorded on the lock; must match.
+ worktree_path: The registered worktree recorded on the lock; must match.
+ expected_head: Full SHA the caller believes the worktree is at. A
+ mismatch fails closed, so a worktree that moved underneath the
+ caller cannot be recovered against stale evidence.
+ remote: Known instance — 'dadeschools' or 'prgs'.
+ host: Override the Gitea host.
+ org: Override the owner/organization.
+ repo: Override the repository name.
+ dry_run: Report the decision and evidence, mutate nothing.
+
+ Returns:
+ dict with 'success', 'performed', the resulting canonical
+ 'lock_contract' and 'work_lease', the auditable
+ 'bootstrap_lock_recovery' transition record, and 'exact_next_action'; on
+ refusal 'success'/'performed' False with 'refusal_code' and 'reasons'
+ naming exactly which evidence was missing, and no write performed.
+ """
+ task = "recover_incomplete_bootstrap_lock"
+ ok, block_reasons = role_session_router.check_author_mutation_after_reviewer_stop(
+ task
+ )
+ if not ok:
+ return _author_mutation_block(block_reasons)
+
+ blocked = _profile_permission_block(
+ task_capability_map.required_permission(task),
+ 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
+
+ h, o, r = _resolve(remote, host, org, repo)
+ resolved_worktree = issue_lock_worktree.resolve_author_worktree_path(
+ worktree_path, _canonical_local_git_root()
+ )
+ existing = _load_existing_issue_lock(
+ remote=remote, org=o, repo=r, issue_number=issue_number
+ )
+ observation = _observe_recovery_worktree(resolved_worktree)
+
+ # The claimant pair is resolved server-side from the live session; the
+ # caller cannot influence which identity or profile recovery compares
+ # against.
+ claimant = _work_lease_claimant(h)
+ assessment = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ existing,
+ issue_number=issue_number,
+ branch_name=branch_name,
+ worktree_path=resolved_worktree,
+ remote=remote,
+ org=o,
+ repo=r,
+ identity=claimant.get("username"),
+ profile=claimant.get("profile"),
+ observed_head=observation["observed_head"],
+ declared_head=expected_head,
+ worktree_exists=observation["worktree_exists"],
+ worktree_registered=observation["worktree_registered"],
+ current_branch=observation["current_branch"],
+ )
+
+ if not assessment["recovery_sanctioned"]:
+ return {
+ "success": False,
+ "performed": False,
+ "mutation_performed": False,
+ "issue_number": issue_number,
+ "refusal_code": assessment["refusal_code"],
+ "reasons": assessment["reasons"],
+ "message": bootstrap_lock_recovery.format_recovery_refusal(assessment),
+ "lock_contract": assessment["contract"],
+ "evidence": assessment["evidence"],
+ }
+
+ if dry_run:
+ return {
+ "success": True,
+ "performed": False,
+ "mutation_performed": False,
+ "dry_run": True,
+ "issue_number": issue_number,
+ "would_recover": True,
+ "lock_contract": assessment["contract"],
+ "evidence": assessment["evidence"],
+ "exact_next_action": (
+ "Re-run without dry_run=True to upgrade this lock to the "
+ "canonical contract."
+ ),
+ }
+
+ recovered = author_lock_contract.build_canonical_issue_lock(
+ issue_number=issue_number,
+ branch_name=branch_name,
+ worktree_path=resolved_worktree,
+ remote=remote,
+ org=o,
+ repo=r,
+ identity=claimant.get("username"),
+ profile=claimant.get("profile"),
+ tool="gitea_recover_incomplete_bootstrap_lock",
+ source=issue_lock_provenance.SOURCE_LOCK_ISSUE,
+ owner_session=(existing or {}).get("owner_session"),
+ expected_base_sha=(existing or {}).get("expected_base_sha"),
+ )
+ # AC10: preserve both sides of the transition so a recovered lock never
+ # reads as an original claim.
+ recovered["bootstrap_lock_recovery"] = bootstrap_lock_recovery.build_recovery_record(
+ assessment,
+ recovered_at=_work_lease_timestamp(_work_lease_now()),
+ new_task_session_id=recovered["work_lease"]["task_session_id"],
+ )
+
+ try:
+ lock_path = issue_lock_store.bind_session_lock(
+ recovered,
+ expected_generation=assessment["expected_generation"],
+ recovery_sanctioned=True,
+ )
+ except Exception as exc:
+ return {
+ "success": False,
+ "performed": False,
+ "mutation_performed": False,
+ "issue_number": issue_number,
+ "refusal_code": "lock_write_failed",
+ "reasons": [str(exc)],
+ "message": f"Recovered lock could not be persisted: {exc} (fail closed)",
+ }
+
+ written = issue_lock_store.read_lock_file(lock_path)
+ contract = author_lock_contract.assess_lock_contract(written)
+ return {
+ "success": True,
+ "performed": True,
+ "mutation_performed": True,
+ "issue_number": issue_number,
+ "branch_name": branch_name,
+ "worktree_path": resolved_worktree,
+ "lock_file_path": lock_path,
+ "lock_contract": contract,
+ "work_lease": (written or {}).get("work_lease"),
+ "task_session_id": contract["task_session_id"],
+ "lock_generation": (written or {}).get("lock_generation"),
+ "prior_generation": assessment["expected_generation"],
+ "bootstrap_lock_recovery": (written or {}).get("bootstrap_lock_recovery"),
+ "preserved_head": observation["observed_head"],
+ "branch_reset": False,
+ "pushed": False,
+ "pr_created": False,
+ "exact_next_action": (
+ "Lock is canonical. Heartbeat it with the returned task_session_id, "
+ "then continue the author workflow; publish and create the pull "
+ "request through the normal sanctioned calls."
+ ),
+ }
+
+
@mcp.tool()
def gitea_recover_dirty_orphaned_issue_worktree(
issue_number: int,
diff --git a/issue_lock_store.py b/issue_lock_store.py
index f216656..278e8d0 100644
--- a/issue_lock_store.py
+++ b/issue_lock_store.py
@@ -299,9 +299,13 @@ def _ownership_refusals(
f"lock worktree '{lock.get('worktree_path')}' does not match "
f"'{worktree_path}'"
)
- lease = lock.get("work_lease") if isinstance(lock, dict) else None
- claimant = lease.get("claimant") if isinstance(lease, dict) else None
- claimant = claimant if isinstance(claimant, dict) else {}
+ # #953 AC2/AC13/AC14: read through the shared claimant reader so a lock
+ # written by bootstrap — which records the claimant at the top level — is
+ # not refused for "not recording a claimant" when it plainly records one.
+ # This is not a widening: the values are still compared against the
+ # server-resolved identity and profile immediately below, so a legacy
+ # placement grants nothing that the canonical placement would not.
+ claimant = lock_claimant(lock) if isinstance(lock, dict) else {}
recorded_identity = str(claimant.get("username") or "").strip()
recorded_profile = str(claimant.get("profile") or "").strip()
if not recorded_identity or not recorded_profile:
@@ -1112,21 +1116,43 @@ def assess_same_issue_lease_conflict(
)
-def _lock_claimant(lock: dict[str, Any] | None) -> dict[str, str]:
+def lock_claimant(lock: dict[str, Any] | None) -> dict[str, str]:
+ """Read the claimant from either canonical or legacy placement (#953 AC13/AC14).
+
+ ``work_lease.claimant`` is the canonical placement and is preferred; a
+ top-level ``claimant`` is the legacy/bootstrap placement and is accepted as
+ a fallback. This is the single definition. Before #953 the readers
+ disagreed: this module, ``issue_lock_renewal``, and ``issue_lock_recovery``
+ tolerated both placements, while ``_ownership_refusals`` looked only in
+ ``work_lease`` — which is what made a bootstrap-written lock
+ un-heartbeatable.
+
+ Preferring ``work_lease`` over the top level is deliberate: once a legacy
+ lock is upgraded, the canonical placement is authoritative and a stale
+ top-level copy must never win.
+
+ This decides *where to look*, never whether ownership is proven — every
+ caller still compares these values against server-resolved identity and
+ profile.
+ """
if not isinstance(lock, dict):
return {}
- claimant = lock.get("claimant")
+ lease = lock.get("work_lease")
+ claimant = lease.get("claimant") if isinstance(lease, dict) else None
if not isinstance(claimant, dict):
- lease = lock.get("work_lease")
- claimant = lease.get("claimant") if isinstance(lease, dict) else None
+ claimant = lock.get("claimant")
if not isinstance(claimant, dict):
return {}
return {
- "username": str(claimant.get("username") or ""),
- "profile": str(claimant.get("profile") or ""),
+ "username": str(claimant.get("username") or "").strip(),
+ "profile": str(claimant.get("profile") or "").strip(),
}
+#: Back-compatible alias for the pre-#953 private name.
+_lock_claimant = lock_claimant
+
+
def assess_foreign_lock_overwrite(
existing_lock: dict[str, Any] | None,
incoming_lock: dict[str, Any],
diff --git a/task_capability_map.py b/task_capability_map.py
index a30b7f9..393ce98 100644
--- a/task_capability_map.py
+++ b/task_capability_map.py
@@ -41,6 +41,27 @@ TASK_CAPABILITY_MAP: dict[str, dict[str, str]] = {
"permission": "gitea.issue.comment",
"role": "author",
},
+ # #953: target-specific upgrade of an incomplete bootstrap lock (explicit
+ # operation, never a widening of lock_issue). Author-only, and the tool
+ # additionally proves exact-owner claimant match before writing.
+ "recover_incomplete_bootstrap_lock": {
+ "permission": "gitea.issue.comment",
+ "role": "author",
+ },
+ "gitea_recover_incomplete_bootstrap_lock": {
+ "permission": "gitea.issue.comment",
+ "role": "author",
+ },
+ # #953: read-only lock contract inspection. Read permission only — it must
+ # never be able to mutate.
+ "inspect_issue_lock_contract": {
+ "permission": "gitea.read",
+ "role": "author",
+ },
+ "gitea_inspect_issue_lock_contract": {
+ "permission": "gitea.read",
+ "role": "author",
+ },
# #860: dirty orphaned same-claimant worktree recovery (explicit operation).
"recover_dirty_orphaned_issue_worktree": {
"permission": "gitea.issue.comment",
diff --git a/tests/test_issue_953_bootstrap_lock_contract.py b/tests/test_issue_953_bootstrap_lock_contract.py
new file mode 100644
index 0000000..64e51ad
--- /dev/null
+++ b/tests/test_issue_953_bootstrap_lock_contract.py
@@ -0,0 +1,1010 @@
+"""One canonical bootstrap/lock contract and its recovery path (#953).
+
+Covers the defect in which ``gitea_bootstrap_author_issue_worktree`` reported a
+lock as created, wrote a shape no downstream reader accepts, and then directed
+the author to implement — after which heartbeat, re-lock, exact-owner renewal,
+and the #447 create-PR guard all refuse simultaneously and no sanctioned
+recovery path remains eligible.
+
+Every fixture here is synthetic and isolated: locks are written into temporary
+directories and the git repositories are created per-test with ``git init``.
+The #949-shaped regression reproduces that lock *shape*; it never touches the
+real issue #949 branch, worktree, lock, issue, or head.
+"""
+
+import os
+import subprocess
+import sys
+import tempfile
+import unittest
+from datetime import datetime, timedelta, timezone
+
+sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
+
+import author_lock_contract # noqa: E402
+import bootstrap_lock_recovery # noqa: E402
+import issue_lock_provenance # noqa: E402
+import issue_lock_store # noqa: E402
+
+ISSUE = 9530
+BRANCH = f"fix/issue-{ISSUE}-canonical-contract"
+IDENTITY = "example-author-user"
+PROFILE = "example-author-profile"
+FOREIGN_IDENTITY = "example-other-user"
+FOREIGN_PROFILE = "example-other-profile"
+REMOTE = "prgs"
+ORG = "ExampleOrg"
+REPO = "ExampleRepo"
+HEAD = "a" * 40
+OTHER_HEAD = "b" * 40
+
+
+def _ts(delta_minutes: int = 0) -> str:
+ return (
+ (datetime.now(timezone.utc) + timedelta(minutes=delta_minutes))
+ .replace(microsecond=0)
+ .isoformat()
+ .replace("+00:00", "Z")
+ )
+
+
+def bootstrap_shaped_lock(**overrides):
+ """The exact malformed shape #949 was left in by the old bootstrap.
+
+ Claimant at the lock top level, ``lease_id`` null, and no ``work_lease``,
+ ``lock_provenance``, or ``expires_at``.
+ """
+ lock = {
+ "remote": REMOTE,
+ "org": ORG,
+ "repo": REPO,
+ "issue_number": ISSUE,
+ "branch": BRANCH,
+ "branch_name": BRANCH,
+ "worktree_path": "/scratch/wt-9530",
+ "owner_session": "author_issue_work-deadbeefdeadbeef",
+ "claimant": {"username": IDENTITY, "profile": PROFILE},
+ "assignment_id": None,
+ "lease_id": None,
+ "expected_base_sha": OTHER_HEAD,
+ "lock_generation": 1,
+ }
+ lock.update(overrides)
+ return lock
+
+
+def canonical_lock(worktree="/scratch/wt-9530", **overrides):
+ lock = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=worktree,
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_lock_issue",
+ )
+ lock["lock_generation"] = 2
+ lock["session_pid"] = os.getpid()
+ lock.update(overrides)
+ return lock
+
+
+class CanonicalContractShape(unittest.TestCase):
+ """AC1, AC6, AC13: one contract, emitted with every required field."""
+
+ def test_bootstrap_builder_emits_the_full_canonical_schema(self):
+ lock = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_bootstrap_author_issue_worktree",
+ source=author_lock_contract.SOURCE_BOOTSTRAP,
+ )
+ for field in author_lock_contract.REQUIRED_LOCK_FIELDS:
+ self.assertIn(field, lock, f"canonical lock missing {field}")
+ for field in author_lock_contract.REQUIRED_WORK_LEASE_FIELDS:
+ self.assertIn(field, lock["work_lease"], f"work_lease missing {field}")
+ self.assertEqual(
+ lock["work_lease"]["claimant"],
+ {"username": IDENTITY, "profile": PROFILE},
+ )
+ self.assertEqual(
+ lock["lock_provenance"]["written_by_tool"],
+ "gitea_bootstrap_author_issue_worktree",
+ )
+
+ def test_bootstrap_and_lock_issue_produce_the_same_contract(self):
+ """AC13: the two writers must not disagree about what a lock is."""
+ from_bootstrap = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_bootstrap_author_issue_worktree",
+ source=author_lock_contract.SOURCE_BOOTSTRAP,
+ )
+ from_lock_issue = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_lock_issue",
+ )
+ self.assertEqual(sorted(from_bootstrap.keys()), sorted(from_lock_issue.keys()))
+ self.assertEqual(
+ sorted(from_bootstrap["work_lease"].keys()),
+ sorted(from_lock_issue["work_lease"].keys()),
+ )
+ for lock in (from_bootstrap, from_lock_issue):
+ self.assertTrue(
+ author_lock_contract.assess_lock_contract(lock)["canonical"]
+ )
+
+ def test_no_successful_build_returns_a_null_ownership_token(self):
+ """AC6: the fencing token every later check keys on is never null."""
+ lock = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_bootstrap_author_issue_worktree",
+ )
+ self.assertTrue(lock["work_lease"]["task_session_id"])
+ self.assertIsNotNone(lock["work_lease"]["expires_at"])
+
+ def test_provenance_cannot_be_supplied_by_a_caller(self):
+ """Safety: provenance is minted server-side, never accepted."""
+ import inspect as _inspect
+
+ params = _inspect.signature(
+ author_lock_contract.build_canonical_issue_lock
+ ).parameters
+ self.assertNotIn("lock_provenance", params)
+ self.assertNotIn("provenance", params)
+
+
+class MalformedAndPartialLocks(unittest.TestCase):
+ """AC7, AC12, AC19: malformed, partial, and missing-expiration locks."""
+
+ def test_bootstrap_shaped_lock_is_reported_as_not_canonical(self):
+ assessment = author_lock_contract.assess_lock_contract(bootstrap_shaped_lock())
+ self.assertFalse(assessment["canonical"])
+ self.assertIn("work_lease", assessment["missing_fields"])
+ self.assertIn("lock_provenance", assessment["missing_fields"])
+
+ def test_missing_fields_are_reported_structurally_and_by_name(self):
+ """AC7: the refusal names what is missing, not just that it failed."""
+ assessment = author_lock_contract.assess_lock_contract(bootstrap_shaped_lock())
+ message = author_lock_contract.format_contract_refusal(assessment)
+ self.assertIn("work_lease", message)
+ self.assertIn("lock_provenance", message)
+ self.assertIsInstance(assessment["missing_fields"], list)
+
+ def test_missing_expiration_is_explicit_not_never_expiring(self):
+ """AC12: the bug — absent expiry read as 'not yet expired'."""
+ lock = bootstrap_shaped_lock()
+ # The pre-existing reader still reports "not expired" for this lock...
+ self.assertFalse(issue_lock_store.is_lease_expired(lock))
+ # ...so the contract states the real fact explicitly instead.
+ state = author_lock_contract.expiration_state(lock)
+ self.assertEqual(state["state"], author_lock_contract.EXPIRATION_MISSING)
+ self.assertIsNone(state["expired"])
+ assessment = author_lock_contract.assess_lock_contract(lock)
+ self.assertTrue(
+ any("neither expirable nor renewable" in r for r in assessment["reasons"])
+ )
+
+ def test_missing_expiration_lock_is_recoverable_rather_than_stranded(self):
+ """AC12: it must not be non-expiring *and* ineligible for every path."""
+ assessment = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ bootstrap_shaped_lock(worktree_path="/scratch/wt-9530"),
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ observed_head=HEAD,
+ declared_head=HEAD,
+ worktree_exists=True,
+ worktree_registered=True,
+ current_branch=BRANCH,
+ )
+ self.assertTrue(assessment["recovery_sanctioned"], assessment["reasons"])
+
+ def test_partial_lock_missing_only_provenance_is_not_canonical(self):
+ lock = canonical_lock()
+ lock.pop("lock_provenance")
+ assessment = author_lock_contract.assess_lock_contract(lock)
+ self.assertFalse(assessment["canonical"])
+ self.assertFalse(assessment["create_pr_eligible"])
+
+ def test_unparseable_expiration_is_named_rather_than_silently_ignored(self):
+ lock = canonical_lock()
+ lock["work_lease"]["expires_at"] = "not-a-timestamp"
+ state = author_lock_contract.expiration_state(lock)
+ self.assertEqual(state["state"], author_lock_contract.EXPIRATION_UNPARSEABLE)
+
+ def test_expired_lock_is_reported_as_expired(self):
+ lock = canonical_lock()
+ lock["work_lease"]["expires_at"] = _ts(-60)
+ state = author_lock_contract.expiration_state(lock)
+ self.assertEqual(state["state"], author_lock_contract.EXPIRATION_RECORDED)
+ self.assertTrue(state["expired"])
+
+ def test_absent_lock_reports_absent_contract(self):
+ assessment = author_lock_contract.assess_lock_contract(None)
+ self.assertEqual(assessment["contract"], author_lock_contract.CONTRACT_ABSENT)
+ self.assertIn(
+ "gitea_lock_issue", author_lock_contract.recommended_action(assessment)
+ )
+
+
+class ClaimantCompatibility(unittest.TestCase):
+ """AC2, AC13, AC14: legacy and canonical claimant placement."""
+
+ def test_claimant_is_read_from_the_legacy_top_level_placement(self):
+ recorded = author_lock_contract.lock_claimant(bootstrap_shaped_lock())
+ self.assertEqual(recorded, {"username": IDENTITY, "profile": PROFILE})
+
+ def test_claimant_is_read_from_the_canonical_work_lease_placement(self):
+ recorded = author_lock_contract.lock_claimant(canonical_lock())
+ self.assertEqual(recorded, {"username": IDENTITY, "profile": PROFILE})
+
+ def test_work_lease_placement_wins_over_a_stale_top_level_copy(self):
+ """An upgraded lock must not be re-read from its stale legacy copy."""
+ lock = canonical_lock()
+ lock["claimant"] = {"username": FOREIGN_IDENTITY, "profile": FOREIGN_PROFILE}
+ self.assertEqual(
+ author_lock_contract.lock_claimant(lock),
+ {"username": IDENTITY, "profile": PROFILE},
+ )
+
+ def test_ownership_check_accepts_the_legacy_placement(self):
+ """AC2: the exact refusal that made a fresh bootstrap lock un-heartbeatable."""
+ refusals = issue_lock_store._ownership_refusals(
+ bootstrap_shaped_lock(worktree_path="/scratch/wt-9530"),
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ identity=IDENTITY,
+ profile=PROFILE,
+ )
+ self.assertNotIn(
+ "lock does not record both a claimant username and profile", refusals
+ )
+ self.assertEqual(refusals, [])
+
+ def test_ownership_check_still_refuses_a_mismatched_claimant(self):
+ """Tolerating the placement must not tolerate the wrong owner."""
+ refusals = issue_lock_store._ownership_refusals(
+ bootstrap_shaped_lock(worktree_path="/scratch/wt-9530"),
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ identity=FOREIGN_IDENTITY,
+ profile=PROFILE,
+ )
+ self.assertTrue(any("does not match active identity" in r for r in refusals))
+
+ def test_ownership_check_still_refuses_a_lock_with_no_claimant_at_all(self):
+ lock = bootstrap_shaped_lock(worktree_path="/scratch/wt-9530")
+ lock.pop("claimant")
+ refusals = issue_lock_store._ownership_refusals(
+ lock,
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ identity=IDENTITY,
+ profile=PROFILE,
+ )
+ self.assertIn(
+ "lock does not record both a claimant username and profile", refusals
+ )
+
+
+class CreatePrProvenanceGuardPreserved(unittest.TestCase):
+ """AC4 and the safety requirement that #447 is not weakened."""
+
+ def test_canonical_bootstrap_lock_passes_the_447_guard(self):
+ lock = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_bootstrap_author_issue_worktree",
+ source=author_lock_contract.SOURCE_BOOTSTRAP,
+ )
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(lock)
+ self.assertTrue(verdict["proven"], verdict["reasons"])
+
+ def test_the_old_bootstrap_shape_is_still_rejected_by_the_447_guard(self):
+ """The guard must keep failing closed on a lock with no provenance."""
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(
+ bootstrap_shaped_lock()
+ )
+ self.assertFalse(verdict["proven"])
+ self.assertTrue(verdict["block"])
+
+ def test_guard_still_rejects_an_unsanctioned_provenance_source(self):
+ lock = canonical_lock()
+ lock["lock_provenance"]["source"] = "hand_written_by_caller"
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(lock)
+ self.assertFalse(verdict["proven"])
+
+ def test_guard_still_rejects_provenance_without_work_lease(self):
+ lock = canonical_lock()
+ lock.pop("work_lease")
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(lock)
+ self.assertFalse(verdict["proven"])
+
+ def test_sanctioned_source_set_was_not_widened(self):
+ """Bootstrap satisfies the guard; it does not get its own exemption."""
+ self.assertEqual(
+ author_lock_contract.SOURCE_BOOTSTRAP,
+ issue_lock_provenance.SOURCE_LOCK_ISSUE,
+ )
+
+
+class RecoveryOwnershipVerification(unittest.TestCase):
+ """AC10, AC11: what recovery proves before it changes lock state."""
+
+ def _assess(self, lock=None, **overrides):
+ kwargs = dict(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ observed_head=HEAD,
+ declared_head=HEAD,
+ worktree_exists=True,
+ worktree_registered=True,
+ current_branch=BRANCH,
+ )
+ kwargs.update(overrides)
+ target = (
+ lock
+ if lock is not None
+ else bootstrap_shaped_lock(worktree_path="/scratch/wt-9530")
+ )
+ return bootstrap_lock_recovery.assess_bootstrap_lock_recovery(target, **kwargs)
+
+ def test_exact_owner_recovery_is_sanctioned(self):
+ self.assertTrue(self._assess()["recovery_sanctioned"])
+
+ def test_mismatched_repository_is_refused(self):
+ result = self._assess(repo="OtherRepo")
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(
+ result["refusal_code"], bootstrap_lock_recovery.REFUSAL_BINDING_MISMATCH
+ )
+
+ def test_mismatched_org_is_refused(self):
+ self.assertFalse(self._assess(org="OtherOrg")["recovery_sanctioned"])
+
+ def test_mismatched_remote_is_refused(self):
+ self.assertFalse(self._assess(remote="dadeschools")["recovery_sanctioned"])
+
+ def test_mismatched_issue_is_refused(self):
+ self.assertFalse(self._assess(issue_number=ISSUE + 1)["recovery_sanctioned"])
+
+ def test_mismatched_branch_is_refused(self):
+ self.assertFalse(
+ self._assess(branch_name="fix/issue-9530-other")["recovery_sanctioned"]
+ )
+
+ def test_mismatched_worktree_is_refused(self):
+ self.assertFalse(
+ self._assess(worktree_path="/scratch/elsewhere")["recovery_sanctioned"]
+ )
+
+ def test_missing_worktree_is_refused(self):
+ result = self._assess(worktree_exists=False)
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(
+ result["refusal_code"], bootstrap_lock_recovery.REFUSAL_WORKTREE_INVALID
+ )
+
+ def test_unregistered_worktree_is_refused(self):
+ self.assertFalse(self._assess(worktree_registered=False)["recovery_sanctioned"])
+
+ def test_worktree_on_a_different_branch_is_refused(self):
+ self.assertFalse(self._assess(current_branch="master")["recovery_sanctioned"])
+
+ def test_head_mismatch_is_refused(self):
+ result = self._assess(declared_head=OTHER_HEAD)
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(
+ result["refusal_code"], bootstrap_lock_recovery.REFUSAL_HEAD_MISMATCH
+ )
+
+ def test_unresolvable_identity_is_refused(self):
+ self.assertFalse(self._assess(identity="")["recovery_sanctioned"])
+
+ def test_unresolvable_profile_is_refused(self):
+ self.assertFalse(self._assess(profile="")["recovery_sanctioned"])
+
+ def test_matching_username_alone_does_not_prove_ownership(self):
+ """Safety: a matching username with the wrong profile is still foreign."""
+ self.assertFalse(self._assess(profile=FOREIGN_PROFILE)["recovery_sanctioned"])
+
+ def test_healthy_foreign_owned_lock_cannot_be_recovered(self):
+ """AC11: the foreign-takeover refusal."""
+ foreign = canonical_lock(worktree="/scratch/wt-9530")
+ foreign["work_lease"]["claimant"] = {
+ "username": FOREIGN_IDENTITY,
+ "profile": FOREIGN_PROFILE,
+ }
+ foreign["session_pid"] = os.getpid() # alive → healthy
+ result = self._assess(lock=foreign)
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(
+ result["refusal_code"], bootstrap_lock_recovery.REFUSAL_HEALTHY_FOREIGN
+ )
+
+ def test_foreign_owned_incomplete_lock_is_also_refused(self):
+ """A foreign lock is refused whether or not it is healthy."""
+ foreign = bootstrap_shaped_lock(
+ worktree_path="/scratch/wt-9530",
+ claimant={"username": FOREIGN_IDENTITY, "profile": FOREIGN_PROFILE},
+ )
+ result = self._assess(lock=foreign)
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertIn(
+ result["refusal_code"],
+ {
+ bootstrap_lock_recovery.REFUSAL_FOREIGN_CLAIMANT,
+ bootstrap_lock_recovery.REFUSAL_HEALTHY_FOREIGN,
+ },
+ )
+
+ def test_healthy_same_owner_canonical_lock_is_left_alone(self):
+ """Nothing to recover: rewriting would invalidate a live heartbeat token."""
+ result = self._assess(lock=canonical_lock(worktree="/scratch/wt-9530"))
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(
+ result["refusal_code"], bootstrap_lock_recovery.REFUSAL_ALREADY_CANONICAL
+ )
+
+ def test_absent_lock_is_refused(self):
+ result = self._assess(lock={})
+ self.assertFalse(result["recovery_sanctioned"])
+ self.assertEqual(result["refusal_code"], bootstrap_lock_recovery.REFUSAL_NO_LOCK)
+
+ def test_recovery_never_requires_base_equivalence(self):
+ """AC9: the branch carries commits; that must not be disqualifying."""
+ import inspect as _inspect
+
+ params = _inspect.signature(
+ bootstrap_lock_recovery.assess_bootstrap_lock_recovery
+ ).parameters
+ self.assertNotIn("base_equivalent", params)
+ self.assertNotIn("expected_base_sha", params)
+
+ def test_recovery_accepts_no_caller_supplied_authorization(self):
+ """Safety: no caller-manufactured provenance or authorization."""
+ import inspect as _inspect
+
+ params = _inspect.signature(
+ bootstrap_lock_recovery.assess_bootstrap_lock_recovery
+ ).parameters
+ for forbidden in (
+ "recovery_sanctioned",
+ "lock_provenance",
+ "provenance",
+ "operator_override",
+ "authorized",
+ ):
+ self.assertNotIn(forbidden, params)
+
+
+class RecoveryAuditTrail(unittest.TestCase):
+ """AC10: auditable ownership and generation transition."""
+
+ def _assessment(self, **overrides):
+ lock = bootstrap_shaped_lock(worktree_path="/scratch/wt-9530", **overrides)
+ return bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ lock,
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ observed_head=HEAD,
+ declared_head=HEAD,
+ worktree_exists=True,
+ worktree_registered=True,
+ current_branch=BRANCH,
+ )
+
+ def test_recovery_record_preserves_both_sides_of_the_transition(self):
+ record = bootstrap_lock_recovery.build_recovery_record(
+ self._assessment(), recovered_at=_ts(), new_task_session_id="task-new"
+ )
+ self.assertEqual(record["recovery_kind"], "incomplete_bootstrap_lock")
+ self.assertEqual(record["prior_generation"], 1)
+ self.assertEqual(
+ record["prior_owner_session"], "author_issue_work-deadbeefdeadbeef"
+ )
+ self.assertEqual(record["replacement_task_session_id"], "task-new")
+ self.assertEqual(record["preserved_head"], HEAD)
+ self.assertFalse(record["branch_reset"])
+ self.assertFalse(record["base_equivalence_required"])
+ self.assertIn("work_lease", record["prior_missing_fields"])
+
+ def test_expected_generation_is_reported_for_compare_and_swap(self):
+ self.assertEqual(
+ self._assessment(lock_generation=7)["expected_generation"], 7
+ )
+
+
+class RecoveryIsolationAndPersistence(unittest.TestCase):
+ """AC8, AC16: recovery upgrades only its target and inspection mutates nothing."""
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.lock_dir = self.tmp.name
+
+ def _write(self, lock, **kwargs):
+ return issue_lock_store.bind_session_lock(
+ lock, lock_dir=self.lock_dir, **kwargs
+ )
+
+ def test_recovery_upgrades_the_target_lock_to_canonical(self):
+ path = self._write(bootstrap_shaped_lock(worktree_path="/scratch/wt-9530"))
+ before = issue_lock_store.read_lock_file(path)
+ self.assertFalse(author_lock_contract.assess_lock_contract(before)["canonical"])
+
+ self._write(
+ author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_recover_incomplete_bootstrap_lock",
+ )
+ )
+ after = issue_lock_store.read_lock_file(path)
+ self.assertTrue(author_lock_contract.assess_lock_contract(after)["canonical"])
+ self.assertGreater(after["lock_generation"], before["lock_generation"])
+
+ def test_recovery_does_not_touch_an_unrelated_lock(self):
+ """A failure or success must affect only the exact target lock."""
+ other_issue = ISSUE + 77
+ other_path = self._write(
+ bootstrap_shaped_lock(
+ issue_number=other_issue,
+ branch_name=f"fix/issue-{other_issue}-unrelated",
+ worktree_path="/scratch/wt-other",
+ )
+ )
+ other_before = issue_lock_store.read_lock_file(other_path)
+
+ target_path = self._write(
+ bootstrap_shaped_lock(worktree_path="/scratch/wt-9530")
+ )
+ self._write(
+ author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_recover_incomplete_bootstrap_lock",
+ )
+ )
+ self.assertNotEqual(target_path, other_path)
+ self.assertEqual(issue_lock_store.read_lock_file(other_path), other_before)
+
+ def test_inspection_performs_no_mutation(self):
+ """AC16: assessing a lock must not rewrite it."""
+ path = self._write(bootstrap_shaped_lock(worktree_path="/scratch/wt-9530"))
+ before = issue_lock_store.read_lock_file(path)
+ mtime_before = os.path.getmtime(path)
+
+ author_lock_contract.assess_lock_contract(before)
+ bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ before,
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt-9530",
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ observed_head=HEAD,
+ declared_head=HEAD,
+ worktree_exists=True,
+ worktree_registered=True,
+ current_branch=BRANCH,
+ )
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+ self.assertEqual(os.path.getmtime(path), mtime_before)
+
+
+class HeartbeatOnFreshAndRecoveredLocks(unittest.TestCase):
+ """AC2, AC3: heartbeat and renewal against real durable locks."""
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.lock_dir = self.tmp.name
+ self.worktree = os.path.join(self.tmp.name, "wt")
+ os.makedirs(self.worktree, exist_ok=True)
+
+ def _canonical(self, tool="gitea_bootstrap_author_issue_worktree"):
+ return author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.worktree,
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool=tool,
+ )
+
+ def _heartbeat(self, token):
+ return issue_lock_store.heartbeat_session_lock(
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.worktree,
+ identity=IDENTITY,
+ profile=PROFILE,
+ task_session_id=token,
+ lock_dir=self.lock_dir,
+ )
+
+ def test_a_freshly_built_canonical_lock_can_be_heartbeated_immediately(self):
+ """AC2: the property a bootstrap lock never had."""
+ lock = self._canonical()
+ issue_lock_store.bind_session_lock(lock, lock_dir=self.lock_dir)
+ outcome = self._heartbeat(lock["work_lease"]["task_session_id"])
+ self.assertTrue(outcome["success"], outcome.get("reasons"))
+ self.assertTrue(outcome["performed"])
+
+ def test_heartbeat_does_not_change_ownership_or_create_a_second_lock(self):
+ lock = self._canonical()
+ path = issue_lock_store.bind_session_lock(lock, lock_dir=self.lock_dir)
+ self._heartbeat(lock["work_lease"]["task_session_id"])
+ after = issue_lock_store.read_lock_file(path)
+ self.assertEqual(
+ author_lock_contract.lock_claimant(after),
+ {"username": IDENTITY, "profile": PROFILE},
+ )
+ # Count issue locks only: bind_session_lock also writes a
+ # session-.json pointer, which is pre-existing behaviour and not a
+ # second claim on the issue.
+ locks = [
+ f
+ for f in os.listdir(self.lock_dir)
+ if f.endswith(".json") and not f.startswith("session-")
+ ]
+ self.assertEqual(len(locks), 1, f"expected exactly one issue lock, got {locks}")
+
+ def test_heartbeat_refuses_a_foreign_task_session_token(self):
+ lock = self._canonical(tool="gitea_lock_issue")
+ issue_lock_store.bind_session_lock(lock, lock_dir=self.lock_dir)
+ outcome = self._heartbeat("author_issue_work-someoneelse")
+ self.assertFalse(outcome["success"])
+
+
+class BootstrapToCreatePrRegression(unittest.TestCase):
+ """AC17, AC18: the exact #949 sequence, against isolated fixtures only.
+
+ This reproduces the *shape* of the #949 failure — bootstrap, implement,
+ commit, push, create PR — in a throwaway git repository. It never reads or
+ writes the real issue #949 branch, worktree, lock, issue, or head.
+ """
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.lock_dir = os.path.join(self.tmp.name, "locks")
+ os.makedirs(self.lock_dir, exist_ok=True)
+ self.origin = os.path.join(self.tmp.name, "origin.git")
+ self.repo = os.path.join(self.tmp.name, "repo")
+ subprocess.run(
+ ["git", "init", "--bare", self.origin], check=True, capture_output=True
+ )
+ subprocess.run(["git", "init", self.repo], check=True, capture_output=True)
+ self._git("config", "user.email", "author@example.invalid")
+ self._git("config", "user.name", "Example Author")
+ with open(os.path.join(self.repo, "README.md"), "w") as handle:
+ handle.write("base\n")
+ self._git("add", "README.md")
+ self._git("commit", "-m", "base commit")
+ self._git("branch", "-M", "master")
+ self._git("remote", "add", "origin", self.origin)
+ self._git("push", "-u", "origin", "master")
+
+ def _git(self, *args):
+ return subprocess.run(
+ ["git", "-C", self.repo, *args], check=True, capture_output=True, text=True
+ )
+
+ def _heartbeat(self, token):
+ return issue_lock_store.heartbeat_session_lock(
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.repo,
+ identity=IDENTITY,
+ profile=PROFILE,
+ task_session_id=token,
+ lock_dir=self.lock_dir,
+ )
+
+ def _implement_and_commit(self):
+ with open(os.path.join(self.repo, "feature.py"), "w") as handle:
+ handle.write("VALUE = 1\n")
+ self._git("add", "feature.py")
+ self._git("commit", "-m", "feat: implement the issue")
+
+ def test_bootstrap_implement_commit_push_create_pr_completes(self):
+ # 1. Bootstrap: branch, worktree, and a canonical lock.
+ self._git("checkout", "-b", BRANCH)
+ lock = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.repo,
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_bootstrap_author_issue_worktree",
+ source=author_lock_contract.SOURCE_BOOTSTRAP,
+ )
+ path = issue_lock_store.bind_session_lock(lock, lock_dir=self.lock_dir)
+ token = lock["work_lease"]["task_session_id"]
+
+ # The lock is usable the moment bootstrap returns.
+ self.assertTrue(
+ author_lock_contract.assess_lock_contract(
+ issue_lock_store.read_lock_file(path)
+ )["canonical"]
+ )
+
+ # 2. Renewal is available *before* the branch diverges (AC3).
+ before = self._heartbeat(token)
+ self.assertTrue(before["success"], before.get("reasons"))
+
+ # 3. Implement and commit — the branch now carries real work.
+ self._implement_and_commit()
+ head = self._git("rev-parse", "HEAD").stdout.strip()
+
+ # 4. Push.
+ self._git("push", "-u", "origin", BRANCH)
+ remote_head = subprocess.run(
+ ["git", "-C", self.origin, "rev-parse", f"refs/heads/{BRANCH}"],
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout.strip()
+ self.assertEqual(head, remote_head)
+
+ # 5. Renewal still available *after* commits (AC3) — no base-equivalence.
+ after = self._heartbeat(token)
+ self.assertTrue(after["success"], after.get("reasons"))
+
+ # 6. create_pr's #447 provenance guard accepts the lock (AC4).
+ final = issue_lock_store.read_lock_file(path)
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(final)
+ self.assertTrue(verdict["proven"], verdict["reasons"])
+
+ # AC18: completed with no manual lock edit, no branch rewind, no
+ # fallback transport. The base commit is still an ancestor of head.
+ merge_base = self._git("merge-base", "master", BRANCH).stdout.strip()
+ master_head = self._git("rev-parse", "master").stdout.strip()
+ self.assertEqual(merge_base, master_head)
+
+ def test_the_old_bootstrap_shape_reproduces_the_949_dead_end(self):
+ """The regression must actually fail without the fix."""
+ self._git("checkout", "-b", BRANCH)
+ self._implement_and_commit()
+
+ legacy = bootstrap_shaped_lock(worktree_path=self.repo)
+ issue_lock_store.bind_session_lock(legacy, lock_dir=self.lock_dir)
+
+ # create_pr refuses — the #447 guard, unchanged.
+ self.assertFalse(
+ issue_lock_provenance.assess_lock_file_for_create_pr(legacy)["proven"]
+ )
+ # And it is never classified as expired, so renewal never engages.
+ self.assertFalse(issue_lock_store.is_lease_expired(legacy))
+ self.assertEqual(
+ author_lock_contract.expiration_state(legacy)["state"],
+ author_lock_contract.EXPIRATION_MISSING,
+ )
+
+ def test_recovery_of_a_committed_branch_preserves_the_commits(self):
+ """AC9: recovery must not rewind a branch that carries pushed work."""
+ self._git("checkout", "-b", BRANCH)
+ self._implement_and_commit()
+ self._git("push", "-u", "origin", BRANCH)
+ head_before = self._git("rev-parse", "HEAD").stdout.strip()
+
+ legacy = bootstrap_shaped_lock(worktree_path=self.repo)
+ path = issue_lock_store.bind_session_lock(legacy, lock_dir=self.lock_dir)
+
+ assessment = bootstrap_lock_recovery.assess_bootstrap_lock_recovery(
+ issue_lock_store.read_lock_file(path),
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.repo,
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ observed_head=head_before,
+ declared_head=head_before,
+ worktree_exists=True,
+ worktree_registered=True,
+ current_branch=BRANCH,
+ )
+ self.assertTrue(assessment["recovery_sanctioned"], assessment["reasons"])
+
+ recovered = author_lock_contract.build_canonical_issue_lock(
+ issue_number=ISSUE,
+ branch_name=BRANCH,
+ worktree_path=self.repo,
+ remote=REMOTE,
+ org=ORG,
+ repo=REPO,
+ identity=IDENTITY,
+ profile=PROFILE,
+ tool="gitea_recover_incomplete_bootstrap_lock",
+ )
+ recovered["bootstrap_lock_recovery"] = (
+ bootstrap_lock_recovery.build_recovery_record(
+ assessment,
+ recovered_at=_ts(),
+ new_task_session_id=recovered["work_lease"]["task_session_id"],
+ )
+ )
+ issue_lock_store.bind_session_lock(
+ recovered,
+ lock_dir=self.lock_dir,
+ expected_generation=assessment["expected_generation"],
+ recovery_sanctioned=True,
+ )
+
+ # The branch head is untouched and the lock is now canonical.
+ self.assertEqual(self._git("rev-parse", "HEAD").stdout.strip(), head_before)
+ final = issue_lock_store.read_lock_file(path)
+ self.assertTrue(author_lock_contract.assess_lock_contract(final)["canonical"])
+ self.assertTrue(
+ issue_lock_provenance.assess_lock_file_for_create_pr(final)["proven"]
+ )
+ self.assertEqual(
+ final["bootstrap_lock_recovery"]["preserved_head"], head_before
+ )
+ self.assertFalse(final["bootstrap_lock_recovery"]["branch_reset"])
+
+
+class BootstrapWiring(unittest.TestCase):
+ """AC1, AC5, AC7, AC15: what the bootstrap tool itself now does."""
+
+ def _source(self):
+ import author_issue_bootstrap
+
+ with open(author_issue_bootstrap.__file__) as handle:
+ return handle.read()
+
+ def test_bootstrap_builds_through_the_canonical_contract(self):
+ source = self._source()
+ self.assertIn("author_lock_contract.build_canonical_issue_lock", source)
+ self.assertIn("author_lock_contract.assess_lock_contract", source)
+
+ def test_bootstrap_fails_closed_on_an_incomplete_written_lock(self):
+ """AC7: partial lock creation stops before implementation begins."""
+ source = self._source()
+ self.assertIn("incomplete_issue_lock_contract", source)
+ self.assertIn('"implementation_allowed": False', source)
+
+ def test_next_action_for_a_canonical_lock_directs_to_implementation(self):
+ """AC5: executable under the state actually returned."""
+ assessment = author_lock_contract.assess_lock_contract(canonical_lock())
+ self.assertIn("work_issue", author_lock_contract.recommended_action(assessment))
+
+ def test_next_action_for_an_incomplete_lock_forbids_implementation(self):
+ """AC5, AC15: never direct an author into the unrecoverable state."""
+ assessment = author_lock_contract.assess_lock_contract(bootstrap_shaped_lock())
+ action = author_lock_contract.recommended_action(assessment)
+ self.assertIn("Do not begin implementation", action)
+ self.assertIn("gitea_recover_incomplete_bootstrap_lock", action)
+
+
+class CapabilityRegistration(unittest.TestCase):
+ """The new operations are registered and role-gated."""
+
+ def test_recovery_is_registered_as_an_author_operation(self):
+ import task_capability_map
+
+ self.assertEqual(
+ task_capability_map.required_permission(
+ "recover_incomplete_bootstrap_lock"
+ ),
+ "gitea.issue.comment",
+ )
+ self.assertEqual(
+ task_capability_map.required_role("recover_incomplete_bootstrap_lock"),
+ "author",
+ )
+
+ def test_inspection_requires_only_read_permission(self):
+ """AC16: a read-only surface must not carry a mutating permission."""
+ import task_capability_map
+
+ self.assertEqual(
+ task_capability_map.required_permission("inspect_issue_lock_contract"),
+ "gitea.read",
+ )
+
+
+class WorkflowDocumentation(unittest.TestCase):
+ """AC20: the canonical ordering and recovery path are documented."""
+
+ def test_author_workflow_documents_ordering_and_recovery(self):
+ root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+ doc = os.path.join(root, "docs", "author-issue-lock-contract.md")
+ self.assertTrue(os.path.exists(doc), f"missing {doc}")
+ with open(doc) as handle:
+ text = handle.read()
+ self.assertIn("gitea_recover_incomplete_bootstrap_lock", text)
+ self.assertIn("gitea_lock_issue", text)
+ self.assertIn("gitea_bootstrap_author_issue_worktree", text)
+ self.assertIn("before writing any implementation", text.lower())
+
+
+if __name__ == "__main__":
+ unittest.main()
From 55d66c57e46f9116c4878f61864eb3d986d7d78a Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Tue, 28 Jul 2026 02:08:21 -0400
Subject: [PATCH 15/18] fix(author): gate bootstrap-lock recovery on the
namespace mutation wall (#953)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Review 632 F1. `gitea_recover_incomplete_bootstrap_lock` writes the same
durable author issue lock as `gitea_recover_dirty_orphaned_issue_worktree`
but gated only on the reviewer-stop router check and the profile permission
block. Every other author state-creating mutation carries a third gate,
`_namespace_mutation_block`, and this tool was the outlier.
The surviving gates did not cover the gap: the task's required permission is
`gitea.issue.comment`, which every configured role holds, and
`_ensure_matching_profile` returns a profile name both call sites discard, so
it refuses nothing. A reviewer-bound session reached the exact-owner claimant
comparison inside `assess_bootstrap_lock_recovery` and was refused there —
one layer too late, with no namespace evaluation and no BLOCKED audit record
of the attempt.
Adding the call alone would have been inert. `check_author_mutation_namespace`
routes through `role_session_router.required_role_for_task`, which reads
`TASK_REQUIRED_ROLE` — not `task_capability_map` — and that table had no entry
for this task, so the check short-circuited to "allowed" for every caller.
The task is therefore registered in `TASK_REQUIRED_ROLE` and `AUTHOR_TASKS`,
matching the role the capability map already records.
The reviewer-namespace check alone is also insufficient for a task gated on
`gitea.issue.comment`, since merger, controller, and reconciler profiles hold
it too. `role_namespace_gate.check_author_role_kind` is added as an opt-in,
additive wall requiring the active profile's derived role kind to be exactly
`author`; `mixed` is refused rather than admitted. `_namespace_mutation_block`
gains a keyword-only `author_role_exclusive` flag, default off, so the six
pre-existing call sites are byte-for-byte unchanged.
Refusals produce the standard structured denial (`namespace_block: true`,
`mcp_namespace`) and the standard BLOCKED audit record, and no lock, lease,
generation, branch, worktree, issue, or PR is touched. Valid `prgs-author`
execution is unaffected. No reviewer permission is broadened and no existing
role wall is weakened.
Co-Authored-By: Claude Opus 4.8 (1M context)
---
gitea_mcp_server.py | 35 +++++++++++++++++++++++++++++++++--
role_namespace_gate.py | 37 +++++++++++++++++++++++++++++++++++++
role_session_router.py | 10 ++++++++++
3 files changed, 80 insertions(+), 2 deletions(-)
diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py
index a3fed3a..0c3aacc 100644
--- a/gitea_mcp_server.py
+++ b/gitea_mcp_server.py
@@ -5150,6 +5150,21 @@ def gitea_recover_incomplete_bootstrap_lock(
if not ok:
return _author_mutation_block(block_reasons)
+ # #953 F1: the namespace/session wall every author state-creating mutation
+ # carries, and which this tool — the structural neighbour of
+ # gitea_recover_dirty_orphaned_issue_worktree, writing the same durable
+ # lock — was the only one to omit. Exact-owner claimant matching inside
+ # assess_bootstrap_lock_recovery is a later layer, not a substitute: it
+ # refuses one commit too late and leaves no BLOCKED audit record of the
+ # attempt. author_role_exclusive is required here because this task is gated
+ # on gitea.issue.comment, which merger, controller, and reconciler profiles
+ # also hold.
+ blocked = _namespace_mutation_block(
+ task, remote=remote, author_role_exclusive=True
+ )
+ if blocked:
+ return blocked
+
blocked = _profile_permission_block(
task_capability_map.required_permission(task),
issue_number=issue_number,
@@ -15490,8 +15505,21 @@ def _profile_permission_block(required_operation: str, **extra_fields) -> dict |
)
-def _namespace_mutation_block(mutation_task: str, **extra_fields) -> dict | None:
- """Reviewer/author namespace alignment gate (#209)."""
+def _namespace_mutation_block(
+ mutation_task: str,
+ *,
+ author_role_exclusive: bool = False,
+ **extra_fields,
+) -> dict | None:
+ """Reviewer/author namespace alignment gate (#209).
+
+ ``author_role_exclusive`` additionally requires the active profile's derived
+ role kind to be exactly ``author`` (#953 F1). Off by default, so the six
+ pre-existing call sites are unchanged. Tools whose required permission is
+ ``gitea.issue.comment`` — which every configured role holds — opt in, since
+ the reviewer-namespace check alone would let a merger, controller, or
+ reconciler session through to a durable author lock write.
+ """
required_permission = task_capability_map.required_permission(mutation_task)
required_role = task_capability_map.required_role(mutation_task)
# #714: evaluate active profile only — never auto-switch.
@@ -15513,6 +15541,9 @@ def _namespace_mutation_block(mutation_task: str, **extra_fields) -> dict | None
}
ok, reasons = role_namespace_gate.check_author_mutation_namespace(
mutation_task, profile)
+ if ok and author_role_exclusive:
+ ok, reasons = role_namespace_gate.check_author_role_kind(
+ mutation_task, profile)
if ok:
return None
blocked = {
diff --git a/role_namespace_gate.py b/role_namespace_gate.py
index 7ed1073..a5e3b25 100644
--- a/role_namespace_gate.py
+++ b/role_namespace_gate.py
@@ -74,6 +74,43 @@ def check_author_mutation_namespace(
return True, []
+def check_author_role_kind(
+ mutation_task: str,
+ profile: dict,
+) -> tuple[bool, list[str]]:
+ """Author-exclusive wall for durable-lock mutations (#953 F1).
+
+ ``check_author_mutation_namespace`` walls off reviewer-bound sessions, which
+ is the whole gate for tasks whose required permission is itself author-only
+ (``gitea.pr.create``, ``gitea.repo.commit``). It is *not* sufficient for a
+ task gated on ``gitea.issue.comment``, which every configured role holds: a
+ merger, controller, or reconciler session would clear both the namespace
+ check and the permission gate and still reach the durable write.
+
+ Opt-in per call site and additive. It refuses any active profile whose
+ derived role kind is not exactly ``author`` for a task the router declares
+ author-required, and grants nothing to anyone — a ``mixed`` profile is
+ refused rather than admitted.
+ """
+ required_role = role_session_router.required_role_for_task(mutation_task)
+ if required_role != "author":
+ return True, []
+
+ allowed = profile.get("allowed_operations") or []
+ forbidden = profile.get("forbidden_operations") or []
+ active_role = derive_role_kind(allowed, forbidden)
+ if active_role == "author":
+ return True, []
+
+ profile_name = profile.get("profile_name") or ""
+ namespace = infer_mcp_namespace(profile_name)
+ return False, [
+ f"author mutation '{mutation_task}' blocked: active session role kind is "
+ f"'{active_role}', not 'author' ({profile_name} / {namespace}); this "
+ "operation writes a durable author issue lock and is author-exclusive",
+ ]
+
+
def mutation_audit_context(mutation_task: str, profile: dict, *,
remote=None, repository=None) -> dict:
"""Structured mutation metadata for audit records (#209)."""
diff --git a/role_session_router.py b/role_session_router.py
index e557266..6b0a6de 100644
--- a/role_session_router.py
+++ b/role_session_router.py
@@ -75,6 +75,10 @@ AUTHOR_TASKS = frozenset({
"push_branch",
"bootstrap_author_issue_worktree",
"gitea_bootstrap_author_issue_worktree",
+ # #953: recovery of an incomplete bootstrap lock is an author-only durable
+ # state mutation and belongs to the same class as bootstrap itself.
+ "recover_incomplete_bootstrap_lock",
+ "gitea_recover_incomplete_bootstrap_lock",
"create_pr",
"comment_pr",
"address_pr_change_requests",
@@ -112,6 +116,12 @@ TASK_REQUIRED_ROLE = {
"claim_issue": "author",
"create_branch": "author",
"push_branch": "author",
+ # #953: without this entry ``required_role_for_task`` returns None and
+ # ``role_namespace_gate.check_author_mutation_namespace`` short-circuits to
+ # "allowed" — the namespace wall on the recovery tool would be inert. The
+ # capability map already records the same role; both tables must agree.
+ "recover_incomplete_bootstrap_lock": "author",
+ "gitea_recover_incomplete_bootstrap_lock": "author",
"create_pr": "author",
"comment_pr": "author",
"address_pr_change_requests": "author",
From 1aa351718a2725c461da06fb4cbb47c5de9a6ece Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Tue, 28 Jul 2026 02:08:21 -0400
Subject: [PATCH 16/18] fix(author): derive AC7 guidance from the state
compensation actually leaves (#953)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Review 632 F2. The bootstrap AC7 read-back refusal calls
`run_compensating_recovery` and *then* reported
`author_lock_contract.recommended_action(contract)` — advice computed from the
malformed lock that provoked the rollback, not from the state the rollback
left. Compensation releases the lock, removes the worktree (always clean
there, no implementation bytes having been written), and deletes the branch,
so an author following that advice got `no_durable_lock` from
`gitea_recover_incomplete_bootstrap_lock` and, had the lock survived,
`worktree_invalid` instead; the `gitea_lock_issue` half of the same sentence
cannot bind a worktree that no longer exists. Two refusals in a row for a
state a plain bootstrap retry fixes — the unexecutable-guidance failure class
this issue exists to remove, reintroduced on the new fail-closed path.
Investigating that path surfaced why the "clean retry" state was in practice
unreachable: `run_compensating_recovery` has called
`issue_lock_store.release_session_lock` since #850, and that function has
never existed. The `AttributeError` landed in a bare `except Exception: pass`,
so every rollback removed the branch and worktree and silently left the lock
behind — precisely the uninspectable, unrecoverable state #953 is about
(`gitea_recover_incomplete_bootstrap_lock` refuses `worktree_invalid`,
`gitea_lock_issue` has no worktree to bind). Confirmed dead at the pinned base
`82d71b77`, not introduced by this branch.
`release_session_lock` is therefore implemented: it removes exactly one
durable lock whose recorded `owner_session` matches the caller's, keyed by
repository when known, refusing on zero or multiple matches so no caller can
delete a lock it does not own and an ambiguous directory is never guessed at.
Bootstrap phase journals and session pointers that share the directory are
excluded by shape. The flock sidecar is deliberately left alone. The caller no
longer swallows a release failure; it records `lock_release_failed:...`.
`assess_post_compensation_state` then classifies from directly observed
durable state — lock file, worktree directory, and branch ref — rather than
from the journal's `rolled_back` list, which records only what compensation
attempted. Three distinct states: `complete` (nothing remains),
`partial` (rollback ran, artifacts survive by design or because a step
errored), `failed` (rollback never completed, so nothing is proven removed).
`post_compensation_action` answers for exactly what survives:
complete -> re-run gitea_bootstrap_author_issue_worktree
lock + branch + worktree -> gitea_recover_incomplete_bootstrap_lock
branch + worktree, no lock -> gitea_lock_issue (still base-equivalent)
lock only, worktree gone -> gitea_inspect_issue_lock_contract
branch only -> gitea_inspect_issue_lock_contract, then retry
rollback did not complete -> gitea_inspect_issue_lock_contract
No branch names an artifact the classification says is gone, and a failed
rollback step is stated rather than presented as an intentional outcome. The
refusal payload carries `compensating_recovery` and `post_compensation_state`
alongside the derived `exact_next_action`, still with
`implementation_allowed: false`.
Also removes the dead `SOURCE_BOOTSTRAP_LOCK_RECOVERY` constant (review 632
F3), which had no readers and implied a second lock source; the deliberate
reuse of `SOURCE_LOCK_ISSUE` is now stated as a comment. The #447 guard and
`SANCTIONED_LOCK_SOURCES` remain untouched.
Co-Authored-By: Claude Opus 4.8 (1M context)
---
author_issue_bootstrap.py | 74 +++++++++++-
author_lock_contract.py | 185 ++++++++++++++++++++++++++++-
docs/author-issue-lock-contract.md | 61 ++++++++++
issue_lock_store.py | 93 +++++++++++++++
4 files changed, 406 insertions(+), 7 deletions(-)
diff --git a/author_issue_bootstrap.py b/author_issue_bootstrap.py
index 20862c5..10834f1 100644
--- a/author_issue_bootstrap.py
+++ b/author_issue_bootstrap.py
@@ -279,6 +279,36 @@ def _verify_assignment_and_lease_ids(
return None
+def _branch_exists(canonical_repo_root: str, branch_name: str) -> bool:
+ """Whether *branch_name* still resolves in the canonical checkout (#953 F2).
+
+ Used after compensating recovery to observe what survived rather than infer
+ it from the journal. Fails closed to ``True``: an unobservable branch is
+ reported as present, so the recommendation stays conservative rather than
+ telling an author to re-bootstrap over something that may still be there.
+ """
+ if not branch_name:
+ return False
+ try:
+ res = subprocess.run(
+ [
+ "git",
+ "-C",
+ canonical_repo_root,
+ "rev-parse",
+ "--verify",
+ "--quiet",
+ f"refs/heads/{branch_name}",
+ ],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ except Exception:
+ return True
+ return res.returncode == 0
+
+
def run_compensating_recovery(
journal: dict[str, Any],
canonical_repo_root: str,
@@ -315,10 +345,21 @@ def run_compensating_recovery(
issue_number=issue_num,
session=session_id,
lock_dir=journal_dir,
+ remote=journal.get("remote"),
+ # The same defaults the lock was written under, so the
+ # rollback targets the exact file bind_session_lock keyed.
+ org=journal.get("org") or "Scaled-Tech-Consulting",
+ repo=journal.get("repo") or "Gitea-Tools",
)
rolled_back.append(f"lock:issue-{issue_num}")
- except Exception:
- pass
+ except Exception as exc:
+ # #953 F2: a swallowed failure here is what made the rollback
+ # report success while leaving an unrecoverable lock behind.
+ # Record it so the post-compensation classification can see the
+ # lock survived and recommend accordingly.
+ rolled_back.append(
+ f"lock_release_failed:issue-{issue_num}:{type(exc).__name__}"
+ )
artifacts["lock_created"] = False
worktree_created = (
@@ -1255,7 +1296,21 @@ def bootstrap_author_issue_worktree(
journal["failure_reason"] = author_lock_contract.format_contract_refusal(
contract
)
- run_compensating_recovery(journal, root, journal_dir=lock_dir)
+ compensation = run_compensating_recovery(
+ journal, root, journal_dir=lock_dir
+ )
+ # AC5/AC15: the recommendation must describe the state compensation
+ # actually left, not the state that provoked it.
+ # ``run_compensating_recovery`` has by now released the lock, removed
+ # the worktree, and deleted the branch, so recommending
+ # incomplete-lock recovery for those exact artifacts would refuse
+ # twice over. Observe what survived and answer for that.
+ post_state = author_lock_contract.assess_post_compensation_state(
+ compensation,
+ lock_present=bool(lock_res) and os.path.exists(lock_res),
+ worktree_present=os.path.isdir(target_worktree),
+ branch_present=_branch_exists(root, target_branch),
+ )
return {
"success": False,
"reason_code": "incomplete_issue_lock_contract",
@@ -1267,9 +1322,18 @@ def bootstrap_author_issue_worktree(
"lock_contract": contract,
"missing_fields": contract["missing_fields"],
"implementation_allowed": False,
+ "compensating_recovery": compensation,
+ "post_compensation_state": post_state,
# AC15: never strand a branch or worktree without a structured
- # recovery recommendation.
- "exact_next_action": author_lock_contract.recommended_action(contract),
+ # recovery recommendation — and never name an artifact the
+ # rollback has already deleted.
+ "exact_next_action": author_lock_contract.post_compensation_action(
+ post_state,
+ issue_number=issue_number,
+ branch_name=target_branch,
+ worktree_path=target_worktree,
+ missing_fields=contract["missing_fields"],
+ ),
"phase_journal": journal,
}
diff --git a/author_lock_contract.py b/author_lock_contract.py
index 05cf42a..47db9e2 100644
--- a/author_lock_contract.py
+++ b/author_lock_contract.py
@@ -43,8 +43,12 @@ import lease_policy
# safety requirements forbid.
SOURCE_BOOTSTRAP = issue_lock_provenance.SOURCE_LOCK_ISSUE
-#: Recovery of an incomplete bootstrap lock (#953 AC8-AC11).
-SOURCE_BOOTSTRAP_LOCK_RECOVERY = "gitea_recover_incomplete_bootstrap_lock"
+# Recovery of an incomplete bootstrap lock (#953 AC8-AC11) deliberately writes
+# through SOURCE_LOCK_ISSUE too, and records its distinctness in
+# ``lock_provenance.written_by_tool`` plus the ``bootstrap_lock_recovery``
+# transition block instead. There is no distinct recovery *source* constant, for
+# the same reason bootstrap has none: minting one would require widening
+# SANCTIONED_LOCK_SOURCES, which the #447 safety requirements forbid.
#: Top-level keys every canonical author issue lock must carry.
REQUIRED_LOCK_FIELDS: tuple[str, ...] = (
@@ -440,3 +444,180 @@ def recommended_action(assessment: Mapping[str, Any]) -> str:
"and worktree to upgrade the lock to the canonical contract, or "
"gitea_lock_issue while the worktree is still base-equivalent."
)
+
+
+# ── Post-compensation recovery guidance (#953 AC5/AC15, review 632 F2) ──
+#
+# ``recommended_action`` above answers "what can be done about a lock in this
+# shape". That is the wrong question on the bootstrap AC7 refusal path, because
+# ``run_compensating_recovery`` has already run by the time the answer is
+# reported: it releases the lock, removes the worktree when clean — which it
+# always is there, no implementation bytes having been written — and deletes the
+# created branch. Recommending incomplete-lock recovery for those artifacts
+# hands the author two refusals in a row (``no_durable_lock``, then
+# ``worktree_invalid``) for a state that a plain bootstrap retry would fix. The
+# advice must describe the state that actually *remains*.
+
+#: Compensation removed every artifact this transition created.
+CLEANUP_COMPLETE = "complete"
+#: Compensation removed some artifacts; others survive and are still actionable.
+CLEANUP_PARTIAL = "partial"
+#: Compensation itself failed or could not be observed; nothing is provable.
+CLEANUP_FAILED = "failed"
+
+
+def assess_post_compensation_state(
+ recovery: Mapping[str, Any] | None,
+ *,
+ lock_present: bool,
+ worktree_present: bool,
+ branch_present: bool,
+) -> dict[str, Any]:
+ """Classify what survived compensation, from observed durable state.
+
+ Pure. The caller observes the filesystem and git; this decides. Observation
+ is authoritative over the journal's ``rolled_back`` list, which records what
+ compensation *attempted*: ``run_compensating_recovery`` swallows a failed
+ lock release and appends nothing, so an absent marker proves nothing either
+ way. The list is still carried through as corroborating evidence.
+
+ The three states are distinct facts, not degrees of the same one:
+
+ * ``CLEANUP_COMPLETE`` — compensation ran and nothing it created remains.
+ * ``CLEANUP_PARTIAL`` — compensation ran and artifacts survive, whether by
+ design (a worktree dirty at rollback time, a branch carrying commits) or
+ because a rollback step errored. Either way the surviving set was observed
+ directly, so it is known and actionable; ``failed_rollback_steps`` records
+ which cause applies.
+ * ``CLEANUP_FAILED`` — compensation never ran to completion, so nothing it
+ would have removed can be assumed removed.
+ """
+ rolled_back = list((recovery or {}).get("rolled_back") or [])
+ executed = bool((recovery or {}).get("executed"))
+ failed_steps = [entry for entry in rolled_back if "_failed" in entry]
+
+ surviving: list[str] = []
+ if lock_present:
+ surviving.append("lock")
+ if worktree_present:
+ surviving.append("worktree")
+ if branch_present:
+ surviving.append("branch")
+
+ if not executed:
+ state = CLEANUP_FAILED
+ elif surviving:
+ state = CLEANUP_PARTIAL
+ else:
+ state = CLEANUP_COMPLETE
+
+ return {
+ "cleanup_state": state,
+ "compensation_executed": executed,
+ "lock_present": bool(lock_present),
+ "worktree_present": bool(worktree_present),
+ "branch_present": bool(branch_present),
+ "surviving_artifacts": surviving,
+ "removed_artifacts": [
+ name
+ for name, present in (
+ ("lock", lock_present),
+ ("worktree", worktree_present),
+ ("branch", branch_present),
+ )
+ if not present
+ ],
+ "failed_rollback_steps": failed_steps,
+ "rolled_back": rolled_back,
+ }
+
+
+def post_compensation_action(
+ state: Mapping[str, Any],
+ *,
+ issue_number: int,
+ branch_name: str,
+ worktree_path: str,
+ missing_fields: list[str] | None = None,
+) -> str:
+ """The one executable next step for the state compensation actually left.
+
+ Every branch names only artifacts the classification says still exist, so no
+ recommendation can point at something the rollback deleted.
+ """
+ missing = ", ".join(missing_fields or []) or "the reported missing fields"
+ cleanup_state = state.get("cleanup_state")
+ lock_present = bool(state.get("lock_present"))
+ worktree_present = bool(state.get("worktree_present"))
+ branch_present = bool(state.get("branch_present"))
+
+ if not state.get("compensation_executed"):
+ # Compensation never ran, so nothing was rolled back and nothing about
+ # the remaining state was decided. The read-only surface is the only
+ # action executable under any state.
+ return (
+ "Compensating rollback did not complete, so the remaining state is "
+ f"not proven. Call gitea_inspect_issue_lock_contract for issue "
+ f"#{issue_number} (read-only) to establish what survives before any "
+ "further action. Do not retry bootstrap until it is known."
+ )
+
+ prefix = ""
+ failed_steps = state.get("failed_rollback_steps") or []
+ if failed_steps:
+ prefix = (
+ "Compensating rollback reported a failed step "
+ f"({', '.join(failed_steps)}); what survives was observed directly "
+ "and the action below is scoped to exactly that. "
+ )
+
+ if cleanup_state == CLEANUP_COMPLETE:
+ return (
+ "Compensating rollback removed the malformed lock, the branch, and "
+ f"the worktree, so nothing from this attempt remains. Resolve "
+ f"{missing} and re-run gitea_bootstrap_author_issue_worktree for "
+ f"issue #{issue_number} from the clean pre-bootstrap state. Do not "
+ "call gitea_recover_incomplete_bootstrap_lock: there is no lock, "
+ "branch, or worktree left for it to act on."
+ )
+
+ if lock_present and worktree_present and branch_present:
+ return prefix + (
+ "The lock, branch, and worktree all survive. Call "
+ "gitea_recover_incomplete_bootstrap_lock for issue "
+ f"#{issue_number}, branch '{branch_name}', and worktree "
+ f"'{worktree_path}', passing the worktree's current head as "
+ "expected_head, to upgrade the lock to the canonical contract."
+ )
+
+ if not lock_present and worktree_present and branch_present:
+ return prefix + (
+ "The malformed lock was released but the branch and worktree "
+ "survive. No implementation bytes were written, so the worktree is "
+ f"still base-equivalent: call gitea_lock_issue for issue "
+ f"#{issue_number} on branch '{branch_name}' from worktree "
+ f"'{worktree_path}' to acquire a canonical lock."
+ )
+
+ if lock_present and not worktree_present:
+ return prefix + (
+ f"The worktree for issue #{issue_number} is gone but the durable "
+ "lock survived, so neither gitea_recover_incomplete_bootstrap_lock "
+ "(it would refuse worktree_invalid) nor gitea_lock_issue (it has no "
+ "worktree to bind) is executable. Call "
+ "gitea_inspect_issue_lock_contract for issue "
+ f"#{issue_number} (read-only) to confirm the surviving lock; it "
+ "must be released by its recorded owner before bootstrap is "
+ "retried."
+ )
+
+ # Lock gone, worktree gone, some git artifact left (a branch with commits,
+ # or a branch this transition did not create).
+ return prefix + (
+ "Compensating rollback removed the lock and worktree; branch "
+ f"'{branch_name}' survives and was not deleted. Call "
+ f"gitea_inspect_issue_lock_contract for issue #{issue_number} "
+ "(read-only) to confirm no durable lock remains, then re-run "
+ "gitea_bootstrap_author_issue_worktree, which will adopt the existing "
+ "branch rather than recreating it."
+ )
diff --git a/docs/author-issue-lock-contract.md b/docs/author-issue-lock-contract.md
index f9f360d..0fb51c6 100644
--- a/docs/author-issue-lock-contract.md
+++ b/docs/author-issue-lock-contract.md
@@ -38,6 +38,44 @@ If bootstrap returns `success: false` with
`exact_next_action` names the executable recovery step. Bootstrap's reported
next action always matches the state it actually returned.
+### What that refusal leaves behind
+
+The AC7 refusal runs `run_compensating_recovery` *before* it reports, so the
+advice has to describe the post-rollback state rather than the shape of the lock
+that provoked it. Recommending incomplete-lock recovery for artifacts the
+rollback already deleted would produce `no_durable_lock` and then
+`worktree_invalid` — two refusals for a state a plain retry fixes.
+
+The refusal therefore carries `compensating_recovery` and
+`post_compensation_state`, and derives `exact_next_action` from what was
+observed on disk. `cleanup_state` is one of:
+
+| `cleanup_state` | Meaning | Next action |
+| --- | --- | --- |
+| `complete` | lock, branch, and worktree all removed | resolve `missing_fields` and re-run `gitea_bootstrap_author_issue_worktree` |
+| `partial` | rollback ran; some artifacts survive, by design or because a step errored | scoped to exactly what survives — see below |
+| `failed` | rollback never completed, so nothing is proven removed | `gitea_inspect_issue_lock_contract` (read-only) before anything else |
+
+Within `partial`, the surviving set decides the action:
+
+| Survives | Next action |
+| --- | --- |
+| lock + branch + worktree | `gitea_recover_incomplete_bootstrap_lock` for that exact issue, branch, and worktree |
+| branch + worktree (lock released) | `gitea_lock_issue` — no implementation bytes were written, so the worktree is still base-equivalent |
+| lock only (worktree removed) | `gitea_inspect_issue_lock_contract`; the surviving lock must be released by its recorded owner before bootstrap is retried |
+| branch only | `gitea_inspect_issue_lock_contract`, then re-run bootstrap, which adopts the existing branch |
+
+`failed_rollback_steps` names any rollback step that errored, and the returned
+action says so rather than presenting the surviving state as intentional.
+
+> The lock half of that rollback was dead code until #953 review 632 F2:
+> `run_compensating_recovery` called `issue_lock_store.release_session_lock`,
+> which did not exist, inside a bare `except Exception: pass`. Every rollback
+> removed the branch and worktree and silently left the lock — the exact
+> uninspectable, unrecoverable state this issue exists to eliminate. The
+> function now exists, releases only a lock whose recorded `owner_session`
+> matches, and its failures are recorded rather than swallowed.
+
## The contract
A canonical lock carries every field in
@@ -125,6 +163,29 @@ the transition — prior contract, prior missing fields, prior generation, prior
owning session, the replacement `task_session_id`, and the preserved head — so a
recovered claim never reads as an original one.
+### Gates, in order
+
+`gitea_recover_incomplete_bootstrap_lock` is an author-only durable-lock
+mutation and carries the same three gates as every comparable author operation,
+in this order:
+
+1. `role_session_router.check_author_mutation_after_reviewer_stop` — no author
+ fallback after a reviewer `wrong_role_stop`.
+2. `_namespace_mutation_block(task, remote=remote, author_role_exclusive=True)` —
+ the namespace wall. It refuses a reviewer-bound session and, because this
+ task's required permission is `gitea.issue.comment` (which merger,
+ controller, and reconciler profiles also hold), additionally requires the
+ active profile's derived role kind to be exactly `author`. A refusal carries
+ `namespace_block: true` and emits a `BLOCKED` audit record naming the
+ namespace and profile.
+3. `_profile_permission_block` — operation, provenance, and session-context
+ gates.
+
+Exact-owner claimant matching inside `assess_bootstrap_lock_recovery` runs
+*after* all three. It is a further layer, never a substitute for them: on its
+own it refuses one step too late and leaves the audit trail silent about the
+attempt.
+
### Refusals
| `refusal_code` | Meaning |
diff --git a/issue_lock_store.py b/issue_lock_store.py
index 278e8d0..8237305 100644
--- a/issue_lock_store.py
+++ b/issue_lock_store.py
@@ -640,6 +640,99 @@ def iter_lock_files(lock_dir: str | None = None) -> list[str]:
return sorted(paths)
+def release_session_lock(
+ *,
+ issue_number: int,
+ session: str,
+ lock_dir: str | None = None,
+ remote: str | None = None,
+ org: str | None = None,
+ repo: str | None = None,
+) -> str:
+ """Remove exactly the durable lock *session* created for *issue_number*.
+
+ ``author_issue_bootstrap.run_compensating_recovery`` has called this name
+ since #850, but it was never defined: the call raised ``AttributeError``
+ into a bare ``except Exception: pass``, so the lock half of every
+ compensating rollback silently did nothing. The branch and worktree were
+ removed and the lock was left behind — a state no sanctioned tool can act
+ on, since recovery refuses ``worktree_invalid`` and ``gitea_lock_issue`` has
+ no worktree to bind (#953 review 632 F2).
+
+ Ownership is proven, not asserted. A record is removed only when its
+ recorded ``owner_session`` equals *session* and its issue number matches;
+ ``remote``/``org``/``repo`` narrow it further when supplied. Zero matches or
+ more than one both raise, so a caller can never delete a lock it does not
+ own and an ambiguous directory is never guessed at. The ``.json.lock`` flock
+ sidecar is deliberately left in place — it is a zero-byte mutex another
+ process may hold, and removing it under contention would be a race.
+
+ Returns the removed lock file path.
+ """
+ target_issue = int(issue_number)
+ owner = str(session or "").strip()
+ if not owner:
+ raise ValueError(
+ "release_session_lock requires the owning session id (fail closed)"
+ )
+
+ def _is_owned_durable_lock(record: dict[str, Any] | None) -> bool:
+ # A durable lock, not a bootstrap phase journal or a session pointer,
+ # both of which can share a directory and carry the same issue number
+ # and owner_session.
+ if not record or "lock_generation" not in record:
+ return False
+ if not str(record.get("branch_name") or "").strip():
+ return False
+ if not str(record.get("worktree_path") or "").strip():
+ return False
+ try:
+ if int(record.get("issue_number") or 0) != target_issue:
+ return False
+ except (TypeError, ValueError):
+ return False
+ return str(record.get("owner_session") or "").strip() == owner
+
+ # Prefer the exact keyed path when the caller knows the repository; scanning
+ # is the fallback for callers that only carry the issue number.
+ if remote and org and repo:
+ exact = lock_file_path(
+ remote=remote,
+ org=org,
+ repo=repo,
+ issue_number=target_issue,
+ lock_dir=lock_dir,
+ )
+ if not _is_owned_durable_lock(read_lock_file(exact)):
+ raise FileNotFoundError(
+ f"durable issue lock '{exact}' is absent or is not owned by "
+ f"session '{owner}' (fail closed; nothing released)"
+ )
+ os.remove(exact)
+ return exact
+
+ matches: list[str] = []
+ for path in iter_lock_files(lock_dir):
+ if _is_owned_durable_lock(read_lock_file(path)):
+ matches.append(path)
+
+ if not matches:
+ raise FileNotFoundError(
+ f"no durable issue lock for issue #{target_issue} is owned by "
+ f"session '{owner}' (fail closed; nothing released)"
+ )
+ if len(matches) > 1:
+ raise RuntimeError(
+ f"{len(matches)} durable locks for issue #{target_issue} claim "
+ f"session '{owner}'; refusing to guess which to release "
+ "(fail closed)"
+ )
+
+ path = matches[0]
+ os.remove(path)
+ return path
+
+
def find_lock_for_branch(
*,
remote: str,
From b4c9f558901699e29fac77b4f748565bcdb5f272 Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Tue, 28 Jul 2026 02:08:21 -0400
Subject: [PATCH 17/18] test(author): execute the native #953 tool functions
and compensation paths (#953)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
Review 632 F4. Every prior reference to `gitea_recover_incomplete_bootstrap_lock`
and `gitea_inspect_issue_lock_contract` under `tests/` was a string literal — a
`tool=` argument, an assertion on returned prose, or a docs substring check —
and the suite reconstructed the recovery sequence by hand from
`assess_bootstrap_lock_recovery`, `build_canonical_issue_lock`,
`build_recovery_record`, and `bind_session_lock`. A hand-written sequence
validates the decision layer but cannot see a divergence between itself and
the tool body, which is exactly how F1 and F2 — both call-site defects —
survived 61 passing cases.
The new cases drive the registered functions against a real `git init`
repository, a real durable lock file, and config-backed profiles:
* `NamespaceMutationWallOnRecovery` — the gate is reached with this task and
`author_role_exclusive=True`; its return value aborts the tool rather than
being computed and discarded; the author namespace succeeds and produces a
canonical lock; a reviewer namespace is refused with `namespace_block` even
when the claimant data would otherwise match, and emits the standard BLOCKED
audit record; merger is refused; a mismatched claimant profile is refused by
the exact-owner layer with the namespace wall explicitly clear; a mismatched
head is refused; every refusal leaves the lock bytes, generation, branch,
worktree, and an unrelated lock untouched. A subtest matrix asserts the
role-kind wall admits `author` and refuses reviewer, merger, limited, and
mixed.
* `InspectionToolExecutes` — the registered read-only tool reports the contract
and the recovery preview while leaving lock bytes, mtime, HEAD, and porcelain
status unchanged, and reports an absent lock without creating one.
* `Ac7PostCompensationGuidance` — drives the real bootstrap to its AC7 refusal
with a forced partial lock and asserts the returned action against the state
the rollback actually left: complete cleanup directs to a bootstrap retry and
that retry is then executed and succeeds, leaving exactly one canonical lock
and one branch; partial cleanup with a surviving lock, and with a surviving
branch and worktree, each get their own executable action; a rollback that
never completed is distinguished from both; no recommendation names a deleted
artifact; unrelated locks are byte-identical afterwards. Two cases cover
`release_session_lock` directly — that the rollback now really removes the
lock, and that it refuses a lock owned by another session.
* `NativeEndToEndBootstrapToCreatePr` — bootstrap, inspect, heartbeat,
legitimate divergence (commit and push), pre-mutation ownership re-check, and
the unchanged #447 create-PR provenance guard, in one sequence against a real
origin. `gitea_lock_issue` is patched to fail the test if anything reaches for
it, so the bootstrap lock is proved to carry the whole cycle unrepaired.
* `DeadProvenanceConstantRemoved` — the removed constant stays removed and the
sanctioned source set stays unwidened.
`_NativeToolBase` clears `role_session_router` route state per test: the sticky
reviewer-stop marker is process-global and, now that this task is registered in
`AUTHOR_TASKS`, an earlier suite leaving it set would make the first gate refuse
before the namespace gate under test is reached.
Also documents both new tools in `docs/mcp-tool-inventory.md`, so this branch
adds no drift to `test_documented_inventory_equals_registered_tools`; the
failure reason there is now identical to the pinned base's.
Suite: 61 -> 92 cases.
Co-Authored-By: Claude Opus 4.8 (1M context)
---
docs/mcp-tool-inventory.md | 2 +
.../test_issue_953_bootstrap_lock_contract.py | 965 ++++++++++++++++++
2 files changed, 967 insertions(+)
diff --git a/docs/mcp-tool-inventory.md b/docs/mcp-tool-inventory.md
index 799d0d0..e93d359 100644
--- a/docs/mcp-tool-inventory.md
+++ b/docs/mcp-tool-inventory.md
@@ -103,6 +103,7 @@ that gates each call, not which tools exist.
- `gitea_get_shell_health`
- `gitea_heartbeat_issue_lock`
- `gitea_heartbeat_reviewer_pr_lease`
+- `gitea_inspect_issue_lock_contract`
- `gitea_inspect_workflow_lease`
- `gitea_issue_irrecoverable_provenance_authorization`
- `gitea_list_dependency_edges`
@@ -134,6 +135,7 @@ that gates each call, not which tools exist.
- `gitea_record_pre_review_command`
- `gitea_record_shell_spawn_outcome`
- `gitea_record_stable_branch_push_attempt`
+- `gitea_recover_incomplete_bootstrap_lock`
- `gitea_release_merger_pr_lease`
- `gitea_release_reviewer_pr_lease`
- `gitea_release_workflow_lease`
diff --git a/tests/test_issue_953_bootstrap_lock_contract.py b/tests/test_issue_953_bootstrap_lock_contract.py
index 64e51ad..04fc741 100644
--- a/tests/test_issue_953_bootstrap_lock_contract.py
+++ b/tests/test_issue_953_bootstrap_lock_contract.py
@@ -12,19 +12,29 @@ The #949-shaped regression reproduces that lock *shape*; it never touches the
real issue #949 branch, worktree, lock, issue, or head.
"""
+import contextlib
import os
import subprocess
import sys
import tempfile
import unittest
from datetime import datetime, timedelta, timezone
+from unittest import mock
sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
+sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent))
+from mutation_profile_fixture import shared_mutation_env # noqa: E402
+
+import author_issue_bootstrap # noqa: E402
import author_lock_contract # noqa: E402
import bootstrap_lock_recovery # noqa: E402
+import gitea_audit # noqa: E402
import issue_lock_provenance # noqa: E402
import issue_lock_store # noqa: E402
+import mcp_server # noqa: E402
+import role_namespace_gate # noqa: E402
+import role_session_router # noqa: E402
ISSUE = 9530
BRANCH = f"fix/issue-{ISSUE}-canonical-contract"
@@ -964,6 +974,961 @@ class BootstrapWiring(unittest.TestCase):
self.assertIn("gitea_recover_incomplete_bootstrap_lock", action)
+class _NativeToolBase(unittest.TestCase):
+ """A real git worktree, a real durable lock, and the real registered tools.
+
+ Review 632 F4: every previous reference to the two new tools under
+ ``tests/`` was a string literal, and the suite reconstructed the recovery
+ sequence by hand. A hand-written sequence cannot see a divergence between
+ itself and the tool body — which is exactly how F1 and F2, both call-site
+ defects, survived 61 passing cases. These call the registered functions.
+ """
+
+ TOOL_ISSUE = 9531
+ TOOL_BRANCH = "fix/issue-9531-native-tool-path"
+ TOOL_ORG = "Example-Org"
+ TOOL_REPO = "Example-Repo"
+ AUTHOR_PROFILE = "test-author-prgs"
+ REVIEWER_PROFILE = "test-reviewer-prgs"
+ MERGER_PROFILE = "test-merger-prgs"
+ TOOL_IDENTITY = "example-native-user"
+
+ def setUp(self):
+ self.lock_dir = tempfile.TemporaryDirectory()
+ self.addCleanup(self.lock_dir.cleanup)
+ self.repo = tempfile.mkdtemp(prefix="issue953-native-")
+ self.addCleanup(
+ lambda: subprocess.run(["rm", "-rf", self.repo], check=False)
+ )
+ self._init_repo()
+ self.remotes = mock.patch.dict(
+ mcp_server.REMOTES,
+ {
+ "prgs": {
+ "host": "gitea.prgs.cc",
+ "org": self.TOOL_ORG,
+ "repo": self.TOOL_REPO,
+ }
+ },
+ )
+ self.remotes.start()
+ self.addCleanup(mock.patch.stopall)
+ mcp_server._IDENTITY_CACHE.clear()
+ # The sticky reviewer-stop route is process-global and outlives whatever
+ # test set it. These cases assert on the *namespace* gate, so the gate
+ # ahead of it must start clean or it refuses first for another reason.
+ role_session_router.clear_route_state()
+ self.addCleanup(role_session_router.clear_route_state)
+
+ def _git(self, *args):
+ return subprocess.run(
+ ["git", "-C", self.repo, *args],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ def _init_repo(self):
+ self._git("init", "-q", "-b", "master")
+ self._git("config", "user.email", "test@example.com")
+ self._git("config", "user.name", "Test")
+ with open(os.path.join(self.repo, "seed.txt"), "w") as handle:
+ handle.write("seed\n")
+ self._git("add", "seed.txt")
+ self._git("commit", "-q", "-m", "seed")
+ self._git("checkout", "-q", "-b", self.TOOL_BRANCH)
+ # The state recovery exists for: the branch already carries pushed work.
+ with open(os.path.join(self.repo, "impl.txt"), "w") as handle:
+ handle.write("implementation\n")
+ self._git("add", "impl.txt")
+ self._git("commit", "-q", "-m", "implementation")
+ self.head = self._git("rev-parse", "HEAD").stdout.strip()
+ self.worktree = os.path.realpath(self.repo)
+
+ def _lock_path(self):
+ return issue_lock_store.lock_file_path(
+ remote=REMOTE,
+ org=self.TOOL_ORG,
+ repo=self.TOOL_REPO,
+ issue_number=self.TOOL_ISSUE,
+ lock_dir=self.lock_dir.name,
+ )
+
+ def write_incomplete_lock(self):
+ """The exact malformed shape the old bootstrap left behind."""
+ lock = bootstrap_shaped_lock(
+ issue_number=self.TOOL_ISSUE,
+ branch=self.TOOL_BRANCH,
+ branch_name=self.TOOL_BRANCH,
+ worktree_path=self.worktree,
+ org=self.TOOL_ORG,
+ repo=self.TOOL_REPO,
+ claimant={
+ "username": self.TOOL_IDENTITY,
+ "profile": self.AUTHOR_PROFILE,
+ },
+ )
+ path = self._lock_path()
+ lock["lock_file_path"] = path
+ issue_lock_store.save_lock_file(path, lock)
+ return path
+
+ def _env(self, profile_name):
+ env = shared_mutation_env(
+ profile_name,
+ include_example_repo=True,
+ GITEA_ISSUE_LOCK_DIR=self.lock_dir.name,
+ )
+ env["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return env
+
+ def call_recovery(
+ self,
+ *,
+ profile_name=None,
+ identity=None,
+ claimant_profile=None,
+ expected_head=None,
+ audit_sink=None,
+ namespace_patch=None,
+ **kwargs,
+ ):
+ """Invoke the registered recovery tool itself, not its assessors."""
+ profile_name = profile_name or self.AUTHOR_PROFILE
+ env = self._env(profile_name)
+ patches = [
+ mock.patch(
+ "mcp_server._work_lease_claimant",
+ return_value={
+ "username": identity or self.TOOL_IDENTITY,
+ "profile": claimant_profile or profile_name,
+ },
+ ),
+ mock.patch("mcp_server.get_auth_header", return_value="token x"),
+ mock.patch(
+ "mcp_server._canonical_local_git_root", return_value=self.worktree
+ ),
+ mock.patch.dict(os.environ, env, clear=True),
+ ]
+ if audit_sink is not None:
+ patches.append(
+ mock.patch(
+ "mcp_server._audit",
+ side_effect=lambda *a, **kw: audit_sink.append((a, kw)),
+ )
+ )
+ if namespace_patch is not None:
+ patches.append(namespace_patch)
+ with contextlib.ExitStack() as stack:
+ for patch in patches:
+ stack.enter_context(patch)
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return mcp_server.gitea_recover_incomplete_bootstrap_lock(
+ issue_number=kwargs.pop("issue_number", self.TOOL_ISSUE),
+ branch_name=kwargs.pop("branch_name", self.TOOL_BRANCH),
+ worktree_path=kwargs.pop("worktree_path", self.worktree),
+ expected_head=expected_head or self.head,
+ remote="prgs",
+ **kwargs,
+ )
+
+ def call_inspection(self, *, profile_name=None, **kwargs):
+ """Invoke the registered read-only inspection tool itself."""
+ env = self._env(profile_name or self.AUTHOR_PROFILE)
+ with mock.patch(
+ "mcp_server._work_lease_claimant",
+ return_value={
+ "username": self.TOOL_IDENTITY,
+ "profile": profile_name or self.AUTHOR_PROFILE,
+ },
+ ), mock.patch(
+ "mcp_server.get_auth_header", return_value="token x"
+ ), mock.patch(
+ "mcp_server._canonical_local_git_root", return_value=self.worktree
+ ), mock.patch.dict(
+ os.environ, env, clear=True
+ ):
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir.name
+ return mcp_server.gitea_inspect_issue_lock_contract(
+ issue_number=kwargs.pop("issue_number", self.TOOL_ISSUE),
+ remote="prgs",
+ **kwargs,
+ )
+
+
+class NamespaceMutationWallOnRecovery(_NativeToolBase):
+ """Review 632 F1: the namespace/session wall on the new author mutation.
+
+ ``gitea_recover_incomplete_bootstrap_lock`` writes the same durable lock as
+ ``gitea_recover_dirty_orphaned_issue_worktree`` and must carry the same
+ third gate. Exact-owner claimant comparison inside
+ ``assess_bootstrap_lock_recovery`` is a later layer, not a substitute: it
+ refuses without a namespace evaluation and without a BLOCKED audit record.
+ """
+
+ def test_the_recovery_tool_calls_the_namespace_mutation_gate(self):
+ """The gate must be reached, with this task, before any write."""
+ self.write_incomplete_lock()
+ seen = []
+
+ def _spy(task, **kwargs):
+ seen.append((task, kwargs))
+ return None
+
+ self.call_recovery(
+ namespace_patch=mock.patch(
+ "mcp_server._namespace_mutation_block", side_effect=_spy
+ )
+ )
+
+ self.assertEqual(len(seen), 1, seen)
+ task, kwargs = seen[0]
+ self.assertEqual(task, "recover_incomplete_bootstrap_lock")
+ self.assertTrue(kwargs.get("author_role_exclusive"))
+
+ def test_the_gate_return_value_is_consumed_and_returned(self):
+ """A gate refusal must abort the tool, not be computed and discarded."""
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ refusal = {"success": False, "performed": False, "namespace_block": True}
+
+ result = self.call_recovery(
+ namespace_patch=mock.patch(
+ "mcp_server._namespace_mutation_block", return_value=refusal
+ )
+ )
+
+ self.assertIs(result, refusal)
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+
+ def test_correct_author_namespace_succeeds(self):
+ path = self.write_incomplete_lock()
+ result = self.call_recovery()
+ self.assertTrue(result.get("success"), result)
+ self.assertTrue(result.get("performed"), result)
+ written = issue_lock_store.read_lock_file(path)
+ self.assertTrue(
+ author_lock_contract.assess_lock_contract(written)["canonical"], written
+ )
+
+ def test_reviewer_namespace_is_rejected_with_matching_claimant_data(self):
+ """Identity that would satisfy the owner check must not be a way in."""
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+
+ result = self.call_recovery(
+ profile_name=self.REVIEWER_PROFILE,
+ claimant_profile=self.AUTHOR_PROFILE,
+ )
+
+ self.assertFalse(result.get("success"), result)
+ self.assertFalse(result.get("performed"), result)
+ self.assertTrue(result.get("namespace_block"), result)
+ self.assertEqual(result.get("mcp_namespace"), "gitea-reviewer")
+ # Not the later exact-owner refusal — the namespace layer stopped it.
+ self.assertNotEqual(result.get("refusal_code"), "foreign_claimant")
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+
+ def test_reviewer_rejection_emits_the_standard_blocked_audit(self):
+ self.write_incomplete_lock()
+ audit = []
+ self.call_recovery(profile_name=self.REVIEWER_PROFILE, audit_sink=audit)
+
+ blocked = [
+ (args, kwargs)
+ for args, kwargs in audit
+ if kwargs.get("result") == gitea_audit.BLOCKED
+ ]
+ self.assertTrue(blocked, audit)
+ args, kwargs = blocked[0]
+ self.assertEqual(args[0], "recover_incomplete_bootstrap_lock")
+ self.assertEqual(
+ kwargs.get("mutation_task"), "recover_incomplete_bootstrap_lock"
+ )
+
+ def test_merger_profile_is_rejected(self):
+ """gitea.issue.comment is held by every role; the wall cannot rely on it."""
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ result = self.call_recovery(profile_name=self.MERGER_PROFILE)
+ self.assertFalse(result.get("success"), result)
+ self.assertFalse(result.get("performed"), result)
+ # Specifically the namespace/role wall, not some later refusal.
+ self.assertTrue(result.get("namespace_block"), result)
+ self.assertTrue(
+ any(
+ "recover_incomplete_bootstrap_lock' blocked" in reason
+ for reason in result.get("reasons") or []
+ ),
+ result,
+ )
+ self.assertIsNone(result.get("refusal_code"), result)
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+
+ def test_wrong_profile_for_the_claimant_is_rejected(self):
+ """A matching username under a different profile is still foreign."""
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ result = self.call_recovery(claimant_profile="test-author-dadeschools")
+ self.assertFalse(result.get("success"), result)
+ self.assertFalse(result.get("performed"), result)
+ # The namespace wall passes here (the session *is* author-bound); this
+ # must be the exact-owner layer refusing the mismatched profile.
+ self.assertIsNone(result.get("namespace_block"), result)
+ self.assertIn(
+ result.get("refusal_code"), ("foreign_claimant", "healthy_foreign_lock"), result
+ )
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+
+ def test_mismatched_head_is_rejected_without_mutation(self):
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ result = self.call_recovery(expected_head=OTHER_HEAD)
+ self.assertFalse(result.get("success"), result)
+ self.assertFalse(result.get("mutation_performed"), result)
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+
+ def test_rejection_leaves_branch_worktree_and_unrelated_locks_untouched(self):
+ unrelated = issue_lock_store.lock_file_path(
+ remote=REMOTE,
+ org=self.TOOL_ORG,
+ repo=self.TOOL_REPO,
+ issue_number=self.TOOL_ISSUE + 41,
+ lock_dir=self.lock_dir.name,
+ )
+ issue_lock_store.save_lock_file(
+ unrelated, bootstrap_shaped_lock(issue_number=self.TOOL_ISSUE + 41)
+ )
+ unrelated_before = issue_lock_store.read_lock_file(unrelated)
+
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ head_before = self._git("rev-parse", "HEAD").stdout.strip()
+
+ self.call_recovery(profile_name=self.REVIEWER_PROFILE)
+
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+ self.assertEqual(issue_lock_store.read_lock_file(unrelated), unrelated_before)
+ self.assertEqual(self._git("rev-parse", "HEAD").stdout.strip(), head_before)
+ self.assertTrue(os.path.isdir(self.worktree))
+ self.assertEqual(self._git("status", "--porcelain").stdout.strip(), "")
+
+ def test_the_gate_routes_this_task_as_author_required(self):
+ """Without a router entry the namespace check silently allows everything."""
+ self.assertEqual(
+ role_session_router.required_role_for_task(
+ "recover_incomplete_bootstrap_lock"
+ ),
+ "author",
+ )
+ ok, reasons = role_namespace_gate.check_author_mutation_namespace(
+ "recover_incomplete_bootstrap_lock",
+ {
+ "profile_name": "prgs-reviewer",
+ "allowed_operations": ["gitea.read", "gitea.pr.approve"],
+ "forbidden_operations": [],
+ },
+ )
+ self.assertFalse(ok, reasons)
+
+ def test_role_kind_wall_admits_author_and_refuses_every_other_role(self):
+ cases = {
+ "author": (["gitea.pr.create", "gitea.branch.push"], True),
+ "reviewer": (["gitea.pr.approve"], False),
+ "merger": (["gitea.pr.merge"], False),
+ "limited": (["gitea.issue.comment", "gitea.read"], False),
+ "mixed": (["gitea.pr.approve", "gitea.pr.create"], False),
+ }
+ for label, (ops, expected) in cases.items():
+ with self.subTest(role=label):
+ ok, _ = role_namespace_gate.check_author_role_kind(
+ "recover_incomplete_bootstrap_lock",
+ {
+ "profile_name": f"prgs-{label}",
+ "allowed_operations": ops,
+ "forbidden_operations": [],
+ },
+ )
+ self.assertEqual(ok, expected)
+
+
+class InspectionToolExecutes(_NativeToolBase):
+ """AC16 proved against the registered tool, not only its assessors."""
+
+ def test_the_registered_inspection_tool_reports_the_contract(self):
+ self.write_incomplete_lock()
+ result = self.call_inspection()
+ self.assertTrue(result.get("success"), result)
+ self.assertTrue(result.get("read_only"))
+ self.assertTrue(result.get("lock_present"))
+ self.assertFalse(result["lock_contract"]["canonical"])
+
+ def test_the_registered_inspection_tool_mutates_nothing(self):
+ path = self.write_incomplete_lock()
+ before = issue_lock_store.read_lock_file(path)
+ mtime_before = os.path.getmtime(path)
+ head_before = self._git("rev-parse", "HEAD").stdout.strip()
+
+ result = self.call_inspection(
+ branch_name=self.TOOL_BRANCH, worktree_path=self.worktree
+ )
+
+ self.assertFalse(result.get("mutation_performed"))
+ self.assertFalse(result.get("performed"))
+ self.assertIn("recovery_preview", result)
+ self.assertEqual(issue_lock_store.read_lock_file(path), before)
+ self.assertEqual(os.path.getmtime(path), mtime_before)
+ self.assertEqual(self._git("rev-parse", "HEAD").stdout.strip(), head_before)
+ self.assertEqual(self._git("status", "--porcelain").stdout.strip(), "")
+
+ def test_inspection_reports_an_absent_lock_without_creating_one(self):
+ result = self.call_inspection()
+ self.assertTrue(result.get("success"), result)
+ self.assertFalse(result.get("lock_present"))
+ self.assertFalse(os.path.exists(self._lock_path()))
+
+
+class Ac7PostCompensationGuidance(unittest.TestCase):
+ """Review 632 F2: the returned action must fit the post-rollback state.
+
+ The AC7 refusal runs ``run_compensating_recovery`` first, which releases the
+ lock and removes the branch and worktree. Recommending incomplete-lock
+ recovery for those exact artifacts hands the author ``no_durable_lock`` and
+ then ``worktree_invalid`` — the unexecutable-guidance failure class #953
+ exists to remove, reintroduced on the new fail-closed path.
+ """
+
+ ISSUE_NUMBER = 9532
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.repo = os.path.join(self.tmp.name, "repo")
+ os.makedirs(self.repo)
+ self._git("init", "-q", "-b", "master")
+ self._git("config", "user.email", "test@example.com")
+ self._git("config", "user.name", "Test")
+ with open(os.path.join(self.repo, "README.md"), "w") as handle:
+ handle.write("# seed\n")
+ self._git("add", "README.md")
+ self._git("commit", "-q", "-m", "seed")
+ self.master_sha = self._git("rev-parse", "HEAD").stdout.strip()
+ os.makedirs(os.path.join(self.repo, "branches"), exist_ok=True)
+ self.lock_dir = os.path.join(self.tmp.name, "locks")
+ os.makedirs(self.lock_dir, exist_ok=True)
+ self.journal_dir = os.path.join(self.tmp.name, "journals")
+ os.makedirs(self.journal_dir, exist_ok=True)
+ self._journal_env = mock.patch.dict(
+ os.environ, {"GITEA_BOOTSTRAP_JOURNAL_DIR": self.journal_dir}
+ )
+ self._journal_env.start()
+ self.addCleanup(self._journal_env.stop)
+
+ def _git(self, *args):
+ return subprocess.run(
+ ["git", "-C", self.repo, *args],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ def _branch_names(self):
+ out = subprocess.run(
+ ["git", "-C", self.repo, "branch", "--format=%(refname:short)"],
+ capture_output=True,
+ text=True,
+ check=False,
+ )
+ return [line.strip() for line in out.stdout.splitlines() if line.strip()]
+
+ def _lock_files(self):
+ """Durable issue locks only — not phase journals or session pointers."""
+ found = []
+ for path in issue_lock_store.iter_lock_files(self.lock_dir):
+ record = issue_lock_store.read_lock_file(path) or {}
+ if "lock_generation" in record:
+ found.append(os.path.basename(path))
+ return sorted(found)
+
+ def _run_bootstrap(self, *, key, partial=False, extra_patches=()):
+ """Drive the real bootstrap; optionally force a partial written lock."""
+ with contextlib.ExitStack() as stack:
+ if partial:
+ real_build = author_lock_contract.build_canonical_issue_lock
+
+ def _partial(**kwargs):
+ record = real_build(**kwargs)
+ # The #949 shape: claimant hoisted to the top level, no
+ # work_lease, no provenance, no expiry.
+ return {
+ "remote": record["remote"],
+ "org": record["org"],
+ "repo": record["repo"],
+ "issue_number": record["issue_number"],
+ "branch": record["branch"],
+ "branch_name": record["branch_name"],
+ "worktree_path": record["worktree_path"],
+ "claimant": dict(record["work_lease"]["claimant"]),
+ "lease_id": None,
+ "owner_session": record.get("owner_session"),
+ }
+
+ stack.enter_context(
+ mock.patch.object(
+ author_issue_bootstrap.author_lock_contract,
+ "build_canonical_issue_lock",
+ side_effect=_partial,
+ )
+ )
+ for patch in extra_patches:
+ stack.enter_context(patch)
+ return author_issue_bootstrap.bootstrap_author_issue_worktree(
+ issue_number=self.ISSUE_NUMBER,
+ canonical_repo_root=self.repo,
+ expected_base_sha=self.master_sha,
+ idempotency_key=key,
+ remote="prgs",
+ lock_dir=self.lock_dir,
+ owner_session=f"session-{key}",
+ active_identity=IDENTITY,
+ active_profile=PROFILE,
+ )
+
+ def test_ac7_failure_then_complete_compensation_directs_to_retry_bootstrap(self):
+ result = self._run_bootstrap(key="ac7-complete", partial=True)
+
+ self.assertFalse(result.get("success"), result)
+ self.assertEqual(result.get("reason_code"), "incomplete_issue_lock_contract")
+ self.assertFalse(result.get("implementation_allowed"))
+ state = result["post_compensation_state"]
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_COMPLETE)
+ self.assertEqual(state["surviving_artifacts"], [])
+
+ action = result["exact_next_action"]
+ self.assertIn("gitea_bootstrap_author_issue_worktree", action)
+ self.assertIn("Do not call gitea_recover_incomplete_bootstrap_lock", action)
+
+ def test_the_returned_retry_action_is_executable(self):
+ """Follow the advice literally and it must succeed."""
+ first = self._run_bootstrap(key="ac7-retry-1", partial=True)
+ self.assertIn(
+ "gitea_bootstrap_author_issue_worktree", first["exact_next_action"]
+ )
+
+ second = self._run_bootstrap(key="ac7-retry-2")
+ self.assertTrue(second.get("success"), second)
+ self.assertTrue(second.get("implementation_allowed"))
+ self.assertTrue(second["lock_contract"]["canonical"], second["lock_contract"])
+ self.assertTrue(second.get("task_session_id"))
+
+ def test_retry_after_complete_compensation_leaves_exactly_one_lock(self):
+ self._run_bootstrap(key="ac7-single-1", partial=True)
+ self.assertEqual(self._lock_files(), [])
+
+ second = self._run_bootstrap(key="ac7-single-2")
+ self.assertTrue(second.get("success"), second)
+ locks = self._lock_files()
+ self.assertEqual(len(locks), 1, locks)
+ written = issue_lock_store.read_lock_file(second["lock_state"])
+ self.assertTrue(author_lock_contract.assess_lock_contract(written)["canonical"])
+ branches = [b for b in self._branch_names() if b != "master"]
+ self.assertEqual(len(branches), 1, branches)
+
+ def test_no_recommendation_names_an_artifact_the_rollback_deleted(self):
+ result = self._run_bootstrap(key="ac7-no-ghosts", partial=True)
+ action = result["exact_next_action"]
+ state = result["post_compensation_state"]
+
+ self.assertFalse(state["branch_present"])
+ self.assertFalse(state["worktree_present"])
+ self.assertFalse(state["lock_present"])
+ self.assertNotIn(result["worktree_path"], action)
+ self.assertNotIn(f"branch '{result['branch_name']}'", action)
+ self.assertFalse(os.path.isdir(result["worktree_path"]))
+ self.assertNotIn(result["branch_name"], self._branch_names())
+
+ def test_partial_compensation_with_a_surviving_lock_is_not_reported_complete(self):
+ def _boom(**kwargs):
+ raise RuntimeError("lock release failed")
+
+ outcome = self._run_bootstrap(
+ key="ac7-lock-survives",
+ partial=True,
+ extra_patches=[
+ mock.patch.object(
+ author_issue_bootstrap.issue_lock_store,
+ "release_session_lock",
+ side_effect=_boom,
+ )
+ ],
+ )
+
+ state = outcome["post_compensation_state"]
+ self.assertTrue(state["lock_present"], state)
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_PARTIAL)
+ self.assertIn("lock", state["surviving_artifacts"])
+ self.assertTrue(state["failed_rollback_steps"], state)
+ action = outcome["exact_next_action"]
+ self.assertIn("failed step", action)
+ self.assertIn("gitea_inspect_issue_lock_contract", action)
+ # The advice must not send the author at artifacts the rollback removed.
+ self.assertNotIn("re-run gitea_bootstrap_author_issue_worktree", action)
+
+ def test_partial_compensation_with_surviving_branch_and_worktree(self):
+ """A worktree dirty at rollback time is preserved, and so is its branch."""
+ real_assess = author_lock_contract.assess_lock_contract
+
+ def _dirty_then_report(lock):
+ verdict = real_assess(lock)
+ path = (lock or {}).get("worktree_path")
+ if path and os.path.isdir(path):
+ with open(os.path.join(path, "uncommitted.txt"), "w") as handle:
+ handle.write("author bytes\n")
+ return verdict
+
+ outcome = self._run_bootstrap(
+ key="ac7-wt-survives",
+ partial=True,
+ extra_patches=[
+ mock.patch.object(
+ author_issue_bootstrap.author_lock_contract,
+ "assess_lock_contract",
+ side_effect=_dirty_then_report,
+ )
+ ],
+ )
+
+ state = outcome["post_compensation_state"]
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_PARTIAL)
+ self.assertTrue(state["worktree_present"], state)
+ self.assertTrue(state["branch_present"], state)
+ self.assertTrue(os.path.isdir(outcome["worktree_path"]))
+ self.assertIn(outcome["branch_name"], self._branch_names())
+ self.assertIn("gitea_lock_issue", outcome["exact_next_action"])
+ self.assertIn(outcome["branch_name"], outcome["exact_next_action"])
+
+ def test_compensation_failure_is_distinguished_from_partial_cleanup(self):
+ outcome = self._run_bootstrap(
+ key="ac7-comp-failed",
+ partial=True,
+ extra_patches=[
+ mock.patch.object(
+ author_issue_bootstrap,
+ "run_compensating_recovery",
+ return_value={
+ "executed": False,
+ "rolled_back": [],
+ "reason": "boom",
+ },
+ )
+ ],
+ )
+
+ state = outcome["post_compensation_state"]
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_FAILED)
+ action = outcome["exact_next_action"]
+ self.assertIn("did not complete", action)
+ self.assertIn("gitea_inspect_issue_lock_contract", action)
+ self.assertNotIn("re-run gitea_bootstrap_author_issue_worktree", action)
+
+ def test_a_failed_rollback_step_is_recorded_even_when_nothing_survives(self):
+ """A step that errored is still reported, and cleanup is still complete."""
+ state = author_lock_contract.assess_post_compensation_state(
+ {
+ "executed": True,
+ "rolled_back": ["lease_release_failed:lease-1:RuntimeError"],
+ },
+ lock_present=False,
+ worktree_present=False,
+ branch_present=False,
+ )
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_COMPLETE)
+ self.assertEqual(
+ state["failed_rollback_steps"],
+ ["lease_release_failed:lease-1:RuntimeError"],
+ )
+
+ def test_the_compensation_lock_release_actually_removes_the_lock(self):
+ """The rollback's lock half was dead code before #953 review 632 F2."""
+ self.assertTrue(hasattr(issue_lock_store, "release_session_lock"))
+ result = self._run_bootstrap(key="ac7-release-real", partial=True)
+ self.assertIn(
+ f"lock:issue-{self.ISSUE_NUMBER}",
+ result["compensating_recovery"]["rolled_back"],
+ )
+ self.assertEqual(self._lock_files(), [])
+
+ def test_release_refuses_a_lock_owned_by_a_different_session(self):
+ created = self._run_bootstrap(key="ac7-foreign-release")
+ self.assertTrue(created.get("success"), created)
+ with self.assertRaises(FileNotFoundError):
+ issue_lock_store.release_session_lock(
+ issue_number=self.ISSUE_NUMBER,
+ session="session-somebody-else",
+ lock_dir=self.lock_dir,
+ remote="prgs",
+ org="Scaled-Tech-Consulting",
+ repo="Gitea-Tools",
+ )
+ self.assertEqual(len(self._lock_files()), 1, self._lock_files())
+
+ def test_ac7_refusal_never_reports_implementation_ready(self):
+ result = self._run_bootstrap(key="ac7-never-ready", partial=True)
+ self.assertFalse(result.get("success"))
+ self.assertFalse(result.get("implementation_allowed"))
+ self.assertNotIn(
+ "proceed with author implementation", result["exact_next_action"]
+ )
+
+ def test_ac7_refusal_touches_no_unrelated_lock(self):
+ unrelated_path = issue_lock_store.lock_file_path(
+ remote="prgs",
+ org="Scaled-Tech-Consulting",
+ repo="Gitea-Tools",
+ issue_number=self.ISSUE_NUMBER + 63,
+ lock_dir=self.lock_dir,
+ )
+ issue_lock_store.save_lock_file(
+ unrelated_path, bootstrap_shaped_lock(issue_number=self.ISSUE_NUMBER + 63)
+ )
+ before = issue_lock_store.read_lock_file(unrelated_path)
+ mtime_before = os.path.getmtime(unrelated_path)
+
+ self._run_bootstrap(key="ac7-isolation", partial=True)
+
+ self.assertEqual(issue_lock_store.read_lock_file(unrelated_path), before)
+ self.assertEqual(os.path.getmtime(unrelated_path), mtime_before)
+
+ def test_surviving_lock_and_worktree_direct_to_target_specific_recovery(self):
+ """The one state in which incomplete-lock recovery *is* executable."""
+ state = author_lock_contract.assess_post_compensation_state(
+ {"executed": True, "rolled_back": []},
+ lock_present=True,
+ worktree_present=True,
+ branch_present=True,
+ )
+ action = author_lock_contract.post_compensation_action(
+ state,
+ issue_number=self.ISSUE_NUMBER,
+ branch_name=BRANCH,
+ worktree_path="/scratch/wt",
+ missing_fields=["work_lease"],
+ )
+ self.assertEqual(state["cleanup_state"], author_lock_contract.CLEANUP_PARTIAL)
+ self.assertIn("gitea_recover_incomplete_bootstrap_lock", action)
+ self.assertIn(BRANCH, action)
+ self.assertIn("/scratch/wt", action)
+
+
+class NativeEndToEndBootstrapToCreatePr(unittest.TestCase):
+ """AC17/AC18 driven through the real tools, with no gitea_lock_issue repair.
+
+ bootstrap → inspect → heartbeat/renew → legitimate divergence → downstream
+ validation → create_pr provenance. The lock the real bootstrap writes must
+ carry the whole sequence on its own; repairing it with the older
+ ``gitea_lock_issue`` path would prove nothing about the new contract, so
+ that path is patched to fail the test if anything reaches for it.
+ """
+
+ ISSUE_NUMBER = 9533
+
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.addCleanup(self.tmp.cleanup)
+ self.origin = os.path.join(self.tmp.name, "origin.git")
+ self.repo = os.path.join(self.tmp.name, "repo")
+ subprocess.run(
+ ["git", "init", "-q", "--bare", self.origin], check=True, capture_output=True
+ )
+ subprocess.run(
+ ["git", "init", "-q", "-b", "master", self.repo],
+ check=True,
+ capture_output=True,
+ )
+ self._git("config", "user.email", "author@example.invalid")
+ self._git("config", "user.name", "Example Author")
+ with open(os.path.join(self.repo, "README.md"), "w") as handle:
+ handle.write("base\n")
+ self._git("add", "README.md")
+ self._git("commit", "-q", "-m", "base commit")
+ self._git("remote", "add", "origin", self.origin)
+ self._git("push", "-q", "-u", "origin", "master")
+ self.master_sha = self._git("rev-parse", "HEAD").stdout.strip()
+
+ self.lock_dir = os.path.join(self.tmp.name, "locks")
+ os.makedirs(self.lock_dir, exist_ok=True)
+ self.journal_dir = os.path.join(self.tmp.name, "journals")
+ os.makedirs(self.journal_dir, exist_ok=True)
+ self._journal_env = mock.patch.dict(
+ os.environ, {"GITEA_BOOTSTRAP_JOURNAL_DIR": self.journal_dir}
+ )
+ self._journal_env.start()
+ self.addCleanup(self._journal_env.stop)
+ self.remotes = mock.patch.dict(
+ mcp_server.REMOTES,
+ {
+ "prgs": {
+ "host": "gitea.prgs.cc",
+ "org": "Scaled-Tech-Consulting",
+ "repo": "Gitea-Tools",
+ }
+ },
+ )
+ self.remotes.start()
+ self.addCleanup(mock.patch.stopall)
+ mcp_server._IDENTITY_CACHE.clear()
+
+ def _git(self, *args, cwd=None):
+ return subprocess.run(
+ ["git", "-C", cwd or self.repo, *args],
+ check=True,
+ capture_output=True,
+ text=True,
+ )
+
+ def _inspect(self, worktree, branch):
+ env = shared_mutation_env(
+ "test-author-prgs", GITEA_ISSUE_LOCK_DIR=self.lock_dir
+ )
+ env["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir
+ with mock.patch(
+ "mcp_server._work_lease_claimant",
+ return_value={"username": IDENTITY, "profile": PROFILE},
+ ), mock.patch(
+ "mcp_server.get_auth_header", return_value="token x"
+ ), mock.patch(
+ "mcp_server._canonical_local_git_root", return_value=self.repo
+ ), mock.patch.dict(
+ os.environ, env, clear=True
+ ):
+ os.environ["GITEA_ISSUE_LOCK_DIR"] = self.lock_dir
+ return mcp_server.gitea_inspect_issue_lock_contract(
+ issue_number=self.ISSUE_NUMBER,
+ branch_name=branch,
+ worktree_path=worktree,
+ remote="prgs",
+ )
+
+ def test_bootstrap_inspect_heartbeat_diverge_and_create_pr_provenance(self):
+ def _forbidden(*args, **kwargs):
+ raise AssertionError(
+ "gitea_lock_issue must not be needed to repair a bootstrap lock"
+ )
+
+ with mock.patch.object(mcp_server, "gitea_lock_issue", side_effect=_forbidden):
+ # 1. Bootstrap through the real function.
+ result = author_issue_bootstrap.bootstrap_author_issue_worktree(
+ issue_number=self.ISSUE_NUMBER,
+ canonical_repo_root=self.repo,
+ expected_base_sha=self.master_sha,
+ idempotency_key="e2e-953",
+ remote="prgs",
+ lock_dir=self.lock_dir,
+ owner_session="session-e2e-953",
+ active_identity=IDENTITY,
+ active_profile=PROFILE,
+ )
+ self.assertTrue(result.get("success"), result)
+ self.assertTrue(result.get("implementation_allowed"))
+ branch = result["branch_name"]
+ worktree = result["worktree_path"]
+ token = result["task_session_id"]
+ self.assertTrue(token)
+
+ # 2. Inspect through the registered read-only tool.
+ inspected = self._inspect(worktree, branch)
+ self.assertTrue(inspected.get("success"), inspected)
+ self.assertTrue(inspected["lock_contract"]["canonical"], inspected)
+ self.assertTrue(inspected["lock_contract"]["heartbeatable"])
+ self.assertTrue(inspected["lock_contract"]["create_pr_eligible"])
+ self.assertFalse(inspected.get("mutation_performed"))
+
+ # 3. Heartbeat/renew while still base-equivalent.
+ before = issue_lock_store.heartbeat_session_lock(
+ remote="prgs",
+ org="Scaled-Tech-Consulting",
+ repo="Gitea-Tools",
+ issue_number=self.ISSUE_NUMBER,
+ branch_name=branch,
+ worktree_path=worktree,
+ identity=IDENTITY,
+ profile=PROFILE,
+ task_session_id=token,
+ lock_dir=self.lock_dir,
+ )
+ self.assertTrue(before["success"], before.get("reasons"))
+
+ # 4. Legitimate divergence: implement, commit, push.
+ with open(os.path.join(worktree, "feature.py"), "w") as handle:
+ handle.write("VALUE = 1\n")
+ self._git("add", "feature.py", cwd=worktree)
+ self._git("commit", "-q", "-m", "feat: implement", cwd=worktree)
+ self._git("push", "-q", "-u", "origin", branch, cwd=worktree)
+ head = self._git("rev-parse", "HEAD", cwd=worktree).stdout.strip()
+ remote_head = subprocess.run(
+ ["git", "-C", self.origin, "rev-parse", f"refs/heads/{branch}"],
+ capture_output=True,
+ text=True,
+ check=True,
+ ).stdout.strip()
+ self.assertEqual(head, remote_head)
+
+ # 5. Downstream validation after divergence.
+ after = issue_lock_store.heartbeat_session_lock(
+ remote="prgs",
+ org="Scaled-Tech-Consulting",
+ repo="Gitea-Tools",
+ issue_number=self.ISSUE_NUMBER,
+ branch_name=branch,
+ worktree_path=worktree,
+ identity=IDENTITY,
+ profile=PROFILE,
+ task_session_id=token,
+ lock_dir=self.lock_dir,
+ )
+ self.assertTrue(after["success"], after.get("reasons"))
+ # The pre-mutation ownership re-check (#438) accepts the diverged
+ # branch without any repair step.
+ diverged_lock = issue_lock_store.read_lock_file(result["lock_state"])
+ proof = issue_lock_store.verify_lock_for_mutation(
+ diverged_lock,
+ issue_number=self.ISSUE_NUMBER,
+ branch_name=branch,
+ worktree_path=worktree,
+ )
+ self.assertTrue(proof["proven"], proof["reasons"])
+
+ # 6. The unchanged #447 create_pr provenance guard accepts it.
+ final = issue_lock_store.read_lock_file(result["lock_state"])
+ verdict = issue_lock_provenance.assess_lock_file_for_create_pr(final)
+ self.assertTrue(verdict["proven"], verdict["reasons"])
+
+ # The branch was never rewound to satisfy any gate.
+ merge_base = self._git("merge-base", "master", branch, cwd=worktree).stdout.strip()
+ self.assertEqual(merge_base, self.master_sha)
+
+
+class DeadProvenanceConstantRemoved(unittest.TestCase):
+ """Review 632 F3: no second lock source may appear to exist."""
+
+ def test_no_recovery_source_constant_is_exported(self):
+ self.assertFalse(
+ hasattr(author_lock_contract, "SOURCE_BOOTSTRAP_LOCK_RECOVERY")
+ )
+
+ def test_bootstrap_source_is_still_the_sanctioned_lock_issue_source(self):
+ self.assertEqual(
+ author_lock_contract.SOURCE_BOOTSTRAP,
+ issue_lock_provenance.SOURCE_LOCK_ISSUE,
+ )
+
+ def test_the_sanctioned_source_set_is_still_not_widened(self):
+ self.assertNotIn(
+ "gitea_recover_incomplete_bootstrap_lock",
+ issue_lock_provenance.SANCTIONED_LOCK_SOURCES,
+ )
+
+
class CapabilityRegistration(unittest.TestCase):
"""The new operations are registered and role-gated."""
From b3de9c941c59e773290b4ecbf41856f8cddb1e74 Mon Sep 17 00:00:00 2001
From: Jason Walker <913443@dadeschools.net>
Date: Tue, 28 Jul 2026 04:41:26 -0400
Subject: [PATCH 18/18] docs(remote-mcp): threat model, trust boundaries, and
decomposition ruling (Closes #956)
#930 inventoried stdio coupling; nothing stated what the adversary is, what
each boundary protects, or why one process may hold credentials for several
services. This adds that document as child 2 of epic #929.
Adds docs/remote-mcp/threat-model.md covering 10 assets, the 5 adversaries
#956 names, 9 trust boundaries, the data flows between them, a 14-entry
per-boundary credential inventory, and an explicit decomposition ruling.
Findings established from live native evidence at this commit:
- Four prgs roles (reviewer, merger, reconciler, controller) resolve to one
Gitea account, so separation of duty between approving and landing is
enforced only by which process a call reaches. The mdcps tenant has no role
separation at all: author, reviewer, and merger share one account.
- Any one role process can resolve every other role's credential.
gitea_list_profiles reports "credentials present" for other roles because it
calls resolve_token on each one.
- The Gitea server reads Jenkins and GlitchTip secrets out of the keychain to
produce the "authenticated" word in gitea_audit_config's service summaries.
- Jenkins and GlitchTip were already decomposed into separate MCP servers; the
credential references were left behind in the Gitea configuration.
Ruling D1 forbids a single integration process from holding credentials for
unrelated services, with one time-boxed dual-run exception for the local fleet
that expires with #939. D2 requires separation of duty to be credential-backed,
D3 scopes credential resolution to the request principal, and D4 gives
coordination state its own authority. Every #929 child from 2 through 10 is
mapped to the boundary it implements.
Anchors are enforced rather than asserted. #930's inventory anchors into
gitea_mcp_server.py had already drifted between 7bf4f125 and aad5c8b4 with
nothing detecting it, so this change ships the guard that was missing:
docs/remote-mcp/threat-model-anchors.json declares all 58 anchors with the
substring each must contain, and tests/test_issue_956_threat_model.py fails if
any anchor does not resolve, if the document cites an anchor the fixture does
not cover, or if the structural obligations regress.
Documentation only. No server behavior changes.
Tests:
- tests/test_issue_956_threat_model.py: 17 passed.
- Four sabotage probes confirm the validator is not passing vacuously
(shifted anchor, undeclared citation, broken count tally, and a blanked
boundary owner). The last two probes exposed real weaknesses in the checks
themselves, which were fixed: the section slice now stops at the next
heading, and boundary ownership is read only from mapping table rows.
- Docs-sensitive sweep (17 modules referencing docs/): 559 passed.
- Full suite: 30 failed, 5799 passed, 6 skipped. All 30 reproduce on a clean
base worktree at aad5c8b4; branch failures are a strict subset of base
failures. No production file is modified by this change.
Closes #956
Co-Authored-By: Claude Opus 4.8 (1M context)
---
docs/remote-mcp/threat-model-anchors.json | 80 +++++
docs/remote-mcp/threat-model.md | 403 ++++++++++++++++++++++
tests/test_issue_956_threat_model.py | 323 +++++++++++++++++
3 files changed, 806 insertions(+)
create mode 100644 docs/remote-mcp/threat-model-anchors.json
create mode 100644 docs/remote-mcp/threat-model.md
create mode 100644 tests/test_issue_956_threat_model.py
diff --git a/docs/remote-mcp/threat-model-anchors.json b/docs/remote-mcp/threat-model-anchors.json
new file mode 100644
index 0000000..670420f
--- /dev/null
+++ b/docs/remote-mcp/threat-model-anchors.json
@@ -0,0 +1,80 @@
+{
+ "_comment": [
+ "Machine-checkable anchor table for docs/remote-mcp/threat-model.md (#956).",
+ "Every file:line anchor cited in the threat model must appear here, and the",
+ "source line at that anchor must contain the 'expect' substring.",
+ "tests/test_issue_956_threat_model.py enforces both directions, so a refactor",
+ "that shifts a line number fails the suite instead of silently rotting the",
+ "document. #930's inventory had no such guard and its gitea_mcp_server.py",
+ "anchors drifted between 7bf4f125 and aad5c8b4."
+ ],
+ "generated_against_commit": "aad5c8b42361d380a8eeb07b94b90815e594c2c5",
+ "anchors": [
+ {"anchor": "gitea_mcp_server.py:24721", "expect": "bind_native_mcp_transport(transport=\"stdio\")"},
+ {"anchor": "mcp_daemon_guard.py:45", "expect": "_PRODUCTION_TRANSPORTS = frozenset({\"stdio\"})"},
+ {"anchor": "mcp_daemon_guard.py:174", "expect": "def bind_native_mcp_transport"},
+ {"anchor": "irrecoverable_provenance.py:497", "expect": "def assess_transport_for_auth_mint"},
+ {"anchor": "gitea_mcp_server.py:9129", "expect": "assess_transport_for_auth_mint()"},
+ {"anchor": "gitea_mcp_server.py:9378", "expect": "assess_transport_for_auth_mint()"},
+ {"anchor": "mcp_server.py:4", "expect": "Runs over stdio."},
+
+ {"anchor": "gitea_mcp_server.py:15412", "expect": "def _is_client_managed_process"},
+ {"anchor": "gitea_mcp_server.py:15442", "expect": "def _provenance_mutation_block"},
+ {"anchor": "gitea_mcp_server.py:15450", "expect": "unsupported_manual_launch"},
+ {"anchor": "gitea_mcp_server.py:19001", "expect": "server_provenance"},
+ {"anchor": "gitea_mcp_server.py:21442", "expect": "def _check_mcp_runtimes_diagnostics"},
+ {"anchor": "gitea_mcp_server.py:21462", "expect": "\"ps\", \"-o\", \"pid,lstart,command\""},
+ {"anchor": "gitea_mcp_server.py:21506", "expect": "\"ps\", \"eww\""},
+ {"anchor": "gitea_config.py:1172", "expect": "RECOGNIZED_GITEA_ENV_KEYS"},
+ {"anchor": "gitea_config.py:1233", "expect": "GITEA_CLIENT_MANAGED"},
+
+ {"anchor": "gitea_config.py:54", "expect": "ENV_PROFILE = \"GITEA_MCP_PROFILE\""},
+ {"anchor": "gitea_config.py:97", "expect": "_REVIEW_MERGE_OPS"},
+ {"anchor": "gitea_config.py:499", "expect": "repository authorization scope"},
+
+ {"anchor": "gitea_config.py:956", "expect": "def _keychain_token"},
+ {"anchor": "gitea_config.py:974", "expect": "def resolve_token"},
+ {"anchor": "gitea_config.py:1015", "expect": "def keychain_auth"},
+ {"anchor": "gitea_config.py:294", "expect": "def _validate_identity_auth"},
+ {"anchor": "mcp_daemon_guard.py:440", "expect": "def assert_keychain_access_allowed"},
+ {"anchor": "gitea_mcp_server.py:19258", "expect": "def gitea_list_profiles"},
+ {"anchor": "gitea_mcp_server.py:19309", "expect": "gitea_config.resolve_token(p)"},
+ {"anchor": "gitea_mcp_server.py:19552", "expect": "def gitea_audit_config"},
+ {"anchor": "gitea_mcp_server.py:19574", "expect": "service_summaries(config)"},
+
+ {"anchor": "gitea_config.py:704", "expect": "def resolve_service"},
+ {"anchor": "gitea_config.py:837", "expect": "def service_summaries"},
+ {"anchor": "gitea_config.py:851", "expect": "_keychain_token(auth.get(\"id\"))"},
+ {"anchor": "gitea_mcp_server.py:17707", "expect": "\"jenkins-mcp\""},
+ {"anchor": "gitea_mcp_server.py:17713", "expect": "external-mcp"},
+ {"anchor": "gitea_mcp_server.py:17734", "expect": "\"glitchtip-mcp\""},
+ {"anchor": "gitea_mcp_server.py:17739", "expect": "external-mcp"},
+ {"anchor": "mcp_discoverability.py:9", "expect": "EXPECTED_JENKINS_TOOLS"},
+ {"anchor": "mcp_discoverability.py:17", "expect": "EXPECTED_GLITCHTIP_TOOLS"},
+
+ {"anchor": "sentry_incident_bridge.py:36", "expect": "SENTRY_AUTH_TOKEN"},
+ {"anchor": "sentry_incident_bridge.py:190", "expect": "def resolve_token"},
+ {"anchor": "sentry_incident_bridge.py:289", "expect": "Authorization"},
+ {"anchor": "sentry_observability.py:55", "expect": "SENTRY_DSN"},
+
+ {"anchor": "master_parity_gate.py:168", "expect": "def capture_startup_parity"},
+ {"anchor": "master_parity_gate.py:255", "expect": "mutation_safe"},
+ {"anchor": "gitea_mcp_server.py:19102", "expect": "def gitea_assess_master_parity"},
+
+ {"anchor": "gitea_mcp_server.py:190", "expect": "ACTIVE_WORKTREE_ENV"},
+ {"anchor": "gitea_mcp_server.py:191", "expect": "AUTHOR_WORKTREE_ENV"},
+ {"anchor": "gitea_mcp_server.py:2348", "expect": "/tmp/gitea_issue_lock.json"},
+ {"anchor": "gitea_mcp_server.py:10894", "expect": "def gitea_bootstrap_author_issue_worktree"},
+ {"anchor": "mcp_server.py:10", "expect": "/tmp/mcp_server_stderr.log"},
+
+ {"anchor": "issue_lock_store.py:26", "expect": "DEFAULT_LOCK_DIR"},
+ {"anchor": "issue_lock_store.py:83", "expect": "def session_pointer_path"},
+ {"anchor": "issue_lock_store.py:98", "expect": "def is_process_alive"},
+ {"anchor": "mcp_session_state.py:27", "expect": "DEFAULT_STATE_DIR"},
+ {"anchor": "control_plane_db.py:47", "expect": "DEFAULT_DB_PATH"},
+ {"anchor": "control_plane_db.py:380", "expect": "mode=0o700"},
+ {"anchor": "control_plane_db.py:386", "expect": "sqlite3.connect"},
+ {"anchor": "control_plane_db.py:1145", "expect": "os.getpid()"},
+ {"anchor": "gitea_mcp_server.py:12801", "expect": "owner_pid_alive"}
+ ]
+}
diff --git a/docs/remote-mcp/threat-model.md b/docs/remote-mcp/threat-model.md
new file mode 100644
index 0000000..28c8038
--- /dev/null
+++ b/docs/remote-mcp/threat-model.md
@@ -0,0 +1,403 @@
+# Remote-MCP threat model, trust boundaries, and service decomposition
+
+What the adversary is, what each boundary protects, and which services may share a process.
+
+- **Issue:** #956 (Remote-MCP threat model), child of epic #929, cross-linked to #955.
+- **Depends on:** #930 (closed) — `docs/remote-mcp/coupling-inventory.md`.
+- **Blocks:** #932, #933, #934, #938.
+- **Generated against commit:** `aad5c8b42361d380a8eeb07b94b90815e594c2c5` (`master`).
+- **Scope:** documentation only. This child changes no server behavior. It adds one
+ document, one anchor fixture, and the test that enforces them.
+
+## Relationship to #930
+
+#930 asked *what breaks when the process stops being local*. This document asks *what an
+attacker gets, and where we stop them*. The two are deliberately different axes: #930
+classifies each coupling as portable, seam, replacement, or cannot-be-remote; this document
+classifies each **credential** by blast radius and each **boundary** by what crossing it
+requires. An entry can be perfectly portable and still be a trust disaster —
+`gitea_config.py:851` is portable Python that reads a CI secret from inside the Gitea server.
+
+### Anchors are enforced, not asserted
+
+Every `file:line` in this document is declared in `docs/remote-mcp/threat-model-anchors.json`
+with the substring that must appear at that line, and
+`tests/test_issue_956_threat_model.py` fails if any anchor does not resolve or if the
+document cites an anchor the fixture does not cover.
+
+This guard exists because #930 did not have one. Its inventory was generated at
+`7bf4f125`; by `aad5c8b4` its `gitea_mcp_server.py` anchors had drifted — the transport
+bind it cited at line 23750 now lives at `gitea_mcp_server.py:24721`, and its
+client-managed provenance anchor at 14588 now lands in an unrelated function. Nothing
+failed, because nothing checked. Anchors into a ~24,700-line module rot silently, and a
+security document that cannot prove its own citations is worse than none, because it is
+trusted.
+
+---
+
+## 1. Assets
+
+What an adversary wants. Ordered by consequence, not by likelihood.
+
+| ID | Asset | Why it matters |
+| -- | ----- | -------------- |
+| A1 | Merge authority on `Scaled-Tech-Consulting/Gitea-Tools` | This repository *is* the control plane. Code merged here becomes the gate that authorizes every future mutation, so merge authority is self-amplifying: one merge can disable every other control in this document. |
+| A2 | Write authority on the `mdcps` tenant | A second, unrelated organization reachable from the same configuration. Compromise here is a cross-organization incident, not an internal one. |
+| A3 | The eight Gitea role credentials | Long-lived bearer tokens. Possession is authority; there is no second factor at the API. |
+| A4 | Jenkins read access (`mdcps`, enabled) | Build logs routinely carry deployment topology, internal hostnames, and accidentally-echoed secrets. |
+| A5 | Error-tracking read access (GlitchTip / Sentry) | Event payloads carry stack frames, request context, and production user data. |
+| A6 | Coordination-state integrity | The locks, leases, and review-decision records that make "exactly one owner" true. Corrupting them needs no Gitea credential and produces duplicate or lost work. |
+| A7 | The operator's checkout and worktrees | Unmerged code, branch state, and the filesystem the author tools write to. |
+| A8 | The macOS login keychain | The meta-credential. Everything in A3, A4, and A5 resolves from it. |
+| A9 | Separation of duty between review and merge | The property that no single actor both approves and lands a change. An *asset*, not a control, because it is what the controls exist to produce. |
+| A10 | Audit and provenance records | Determine whether an incident is reconstructable. An attacker who can forge provenance makes an intrusion indistinguishable from normal work. |
+
+## 2. Adversaries
+
+| ID | Adversary | Capability assumed | Not assumed |
+| -- | --------- | ------------------ | ----------- |
+| ADV1 | **Compromised LLM client** | Full control of one MCP client. Issues arbitrary tool calls, in any order, with any arguments, at machine speed. Sees every tool result. | Cannot read the operator's disk except through tools; cannot execute arbitrary local code outside the tool surface. |
+| ADV2 | **Prompt injection** via repository content | Controls text the model reads and treats as instruction — issue bodies, PR descriptions, review comments, commit messages, file contents. Reaches the model on any read of untrusted content. | Holds no credential and issues no call directly. Its entire power is causing an *authorized* client to act. |
+| ADV3 | **Malicious tool arguments** | Supplies hostile values to any parameter — paths, branch names, session identifiers, worktree paths, issue numbers — including traversal, injection, and confusion between look-alike identifiers. | Cannot bypass a gate that actually validates its input. |
+| ADV4 | **Network attacker** | Observes and modifies traffic between client, server, and Gitea. Attempts downgrade, replay, and endpoint impersonation. | Does not hold a valid credential at the start. |
+| ADV5 | **Curious operator** | Legitimate local access to the workstation: process table, `/tmp`, home directory, keychain prompts. Not malicious, but not authorized for every role either. | Does not defeat the OS keychain's own access control without a prompt. |
+
+ADV2 is the adversary this architecture most under-models. Every other adversary must first
+obtain something. Prompt injection obtains nothing: it borrows authority the client already
+holds and is indistinguishable at the tool boundary from legitimate work. Each boundary
+below therefore states whether it constrains ADV2 at all — and most do not, because they
+authenticate the *caller*, not the *intent*.
+
+## 3. Trust boundaries
+
+"Crossing requires today" is what the code actually enforces at
+`aad5c8b42361d380a8eeb07b94b90815e594c2c5`, not what the design intends.
+
+| ID | Boundary | Protects | Crossing requires today | Crossing must require remotely |
+| -- | -------- | -------- | ----------------------- | ------------------------------ |
+| B1 | LLM client ↔ MCP server session | A1, A3, A10 — that a mutating session was established through the sanctioned client path | A literal `stdio` bind (`gitea_mcp_server.py:24721`) inside a closed allowlist (`mcp_daemon_guard.py:45`, `mcp_daemon_guard.py:174`); client-managed provenance (`gitea_mcp_server.py:15412`) or a refusal (`gitea_mcp_server.py:15450`); production transport before recovery-authorization mint (`irrecoverable_provenance.py:497`, consumed at `gitea_mcp_server.py:9129` and `gitea_mcp_server.py:9378`) | An authenticated handshake issuing a server-side session identity bound to a principal, with the transport recorded in provenance. The physical proof (a pipe) must become a cryptographic one. |
+| B2 | Role ↔ role | A9 — that author, reviewer, merger, and reconciler are distinct authorities | **The process boundary only.** The role is a property of the process, read once from `GITEA_MCP_PROFILE` (`gitea_config.py:54`). A caller gets author permissions by connecting to the author process. Review and merge are the operations singled out for extra care (`gitea_config.py:97`) | A per-request principal, so the role follows from the credential presented and cannot be selected by reaching a different endpoint. |
+| B3 | MCP server ↔ credential store | A3, A8 — that only sanctioned code turns a profile into a token | `_keychain_token` shelling out to the login keychain (`gitea_config.py:956`), dispatched by `resolve_token` (`gitea_config.py:974`) with the reference type built at `gitea_config.py:1015`, gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`). Inline secrets are rejected at config load (`gitea_config.py:294`) | A credential provider keyed by the *request* principal, returning only that principal's credential, with the source recorded and the value never returned. |
+| B4 | MCP server ↔ Gitea | A1, A2 — that only authorized calls reach the forge | A bearer token over TLS. Server-side, nothing distinguishes one role's token from another beyond the account it belongs to | Unchanged at the forge; the endpoint in front of it must refuse unauthenticated and plaintext connections before tool dispatch. |
+| B5 | MCP server ↔ caller's filesystem | A7 — that a tool acts on the *caller's* disk or refuses | Nothing. The server's disk *is* the caller's disk. Worktree bootstrap writes directly (`gitea_mcp_server.py:10894`); the active workspace is process-global (`gitea_mcp_server.py:190`, `gitea_mcp_server.py:191`) | An explicit per-tool classification, enforced at dispatch, refusing filesystem tools over a transport that cannot reach the caller's disk. A green verdict about the wrong disk is the failure to prevent. |
+| B6 | MCP server ↔ coordination state | A6, A9 — mutual exclusion | Local files and a local SQLite database, with liveness judged from the local process table (`issue_lock_store.py:98`), keyed on paths under one user's home (`issue_lock_store.py:26`, `mcp_session_state.py:27`, `control_plane_db.py:47`) and on `os.getpid()` (`control_plane_db.py:1145`, `gitea_mcp_server.py:12801`). A legacy global slot still exists at `gitea_mcp_server.py:2348`, and the session-pointer file is named per PID (`issue_lock_store.py:83`) | One authority per ownership question, with liveness from session identity and expiry, and atomic acquire, renew, and release across hosts. |
+| B7 | Gitea integration ↔ unrelated integrations | A4, A5 — that a Gitea compromise is not a CI and observability compromise | **Nothing.** See §5. The Gitea server reads Jenkins and GlitchTip secrets (`gitea_config.py:851`, reached from `gitea_config.py:837`) and holds the Sentry token (`sentry_incident_bridge.py:190`) | A hard process boundary. This is the boundary #956 exists to create. |
+| B8 | Tenant ↔ tenant (`prgs` / `mdcps` / `local-lab`) | A2 — that one organization's compromise is not another's | Convention. One configuration declares all three contexts; `resolve_service` fails closed on a *disabled* context (`gitea_config.py:704`) but the credentials of enabled ones remain reachable in-process. A per-profile repository scope exists (`gitea_config.py:499`) | Separate deployments, or at minimum per-tenant credential scopes with no process able to resolve both. |
+| B9 | Deployed code ↔ merged policy | A1, A10 — that the running server enforces the rules that were actually merged | Comparing this process's startup commit against this disk (`master_parity_gate.py:168`), conjoined into a single verdict (`master_parity_gate.py:255`) published by `gitea_mcp_server.py:19102` | Freshness defined against the deployed build identity, with an explicit fail-closed verdict when undeterminable. |
+
+### What no boundary constrains
+
+None of B1–B9 constrains **ADV2**. Every one authenticates a caller or a process; prompt
+injection supplies neither. An injected instruction that reaches an authorized author
+session crosses B1, B2, B3, and B5 legitimately, because at each of those boundaries it *is*
+the author. The only controls that bite ADV2 are those constraining what an authenticated
+principal may do regardless of what it asks for — the per-role permission split (B2), the
+repository scope at `gitea_config.py:499`, and separation of duty (A9). Sizing those
+controls correctly matters more after the migration, not less, because a remote endpoint
+raises the number of clients that can be injected into.
+
+## 4. Data flows
+
+Flows that cross a boundary. `==>` carries a credential; `-->` does not.
+
+```
+ B1 B4
+ [LLM client] ====================> [MCP server] ========> [Gitea]
+ ^ stdio pipe today | ^ (A1,A2)
+ | session identity | |
+ | after migration | |
+ | | | B3
+ untrusted repository content | +======> [macOS login keychain] (A8)
+ read back into the model (ADV2) | resolves A3, A4, A5
+ ^ |
+ +----------------------------------+
+ |
+ B5 | B6
+ [operator checkout / worktrees] <--------+-------> [locks · leases · sqlite]
+ (A7) | (A6)
+ |
+ B7 <-- boundary does not exist today
+ |
+ +========================+========================+
+ | | |
+ [Jenkins] (A4) [GlitchTip] (A5) [Sentry] (A5)
+ external MCP server external MCP server in-process bridge
+```
+
+Two flows deserve attention because neither is obvious from the code:
+
+1. **The keychain flow fans out.** B3 is drawn once but resolves credentials for *every*
+ configured profile and service, not only the active one. `gitea_list_profiles`
+ (`gitea_mcp_server.py:19258`) reports each profile's credential status by calling
+ `resolve_token` on it (`gitea_mcp_server.py:19309`), and `gitea_audit_config`
+ (`gitea_mcp_server.py:19552`) reports service credential status through
+ `service_summaries` (`gitea_mcp_server.py:19574`).
+2. **The return path is a flow too.** Content read from Gitea travels back into the model
+ and is treated as instruction. This is the ADV2 edge, and it is the only edge in the
+ diagram with no authentication on it, because it is not a request.
+
+## 5. Per-boundary credential inventory
+
+**14 credentials in total.** Blast radius is stated as what the credential yields *on its
+own*, assuming every gate not backed by the credential itself has been bypassed — because
+an attacker holding a token calls the API, not our tools.
+
+| ID | Credential | Holder | Boundary | Blast radius |
+| -- | ---------- | ------ | -------- | ------------ |
+| CR1 | `prgs-author` Gitea token — account `jcwalker3` | macOS keychain; resolved in-process (`gitea_config.py:974`) | B3 → B4 | Create branches, push, commit, open PRs, create/close/comment issues on the control-plane repo. Cannot approve or merge. The one credential whose identity is genuinely distinct. |
+| CR2 | `prgs-reviewer` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Approve and request changes. **Shares one Gitea account with CR3, CR4, CR5.** |
+| CR3 | `prgs-merger` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Merge to `master` — A1 in full. Same account as CR2. |
+| CR4 | `prgs-reconciler` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Close PRs, delete branches, irrecoverable decision-lock recovery. Same account as CR2. |
+| CR5 | `prgs-controller` Gitea token — account `sysadmin` | macOS keychain | B3 → B4 | Same operation set as CR4. Same account as CR2. |
+| CR6 | `mdcps-author` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Author operations on a second organization. **Shares one account with CR7 and CR8.** |
+| CR7 | `mdcps-reviewer` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Approve and request changes on `mdcps`. Same account as CR6. |
+| CR8 | `mdcps-merger` Gitea token — account `913443` | macOS keychain | B3 → B4, B8 | Merge on `mdcps` — A2 in full. Same account as CR6. |
+| CR9 | MDCPS Jenkins read credential | macOS keychain, read from the Gitea server process (`gitea_config.py:851`) | B7 | Read CI jobs, builds, and logs (A4). Enabled today. |
+| CR10 | MDCPS GlitchTip read credential | macOS keychain, read from the Gitea server process (`gitea_config.py:851`) | B7 | Read error events and their payloads (A5). Enabled today. |
+| CR11 | `SENTRY_AUTH_TOKEN` | Process environment, read in-process (`sentry_incident_bridge.py:36`, `sentry_incident_bridge.py:190`), sent as a bearer header (`sentry_incident_bridge.py:289`) | B7 | Read and reconcile Sentry issues (A5). Not a keychain credential — an env var, so it is inherited by anything the process spawns. |
+| CR12 | `SENTRY_DSN` | Process environment (`sentry_observability.py:55`) | B7 | Write events into the observability project. Low read value, real forgery value: an attacker can inject fabricated events into the record (A10). |
+| CR13 | macOS login keychain access | The operator's login session; gated by `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`) | B3, ADV5 | **Every other credential in this table except CR11 and CR12.** This is the aggregation point. |
+| CR14 | Coordination-store access (no secret) | Filesystem permissions — `control_plane_db.py:47`, created `0o700` (`control_plane_db.py:380`), opened with a local file lock (`control_plane_db.py:386`) | B6, ADV5 | Full read/write of locks, leases, and decision records (A6). **There is no credential here at all** — anything running as the operator can rewrite ownership. |
+
+### Findings
+
+**Finding 1 — Role separation is not credential separation.** Four `prgs` roles resolve to
+one Gitea account (`sysadmin`): reviewer, merger, reconciler, and controller. A stolen
+reviewer credential *is* a merger credential. A9 — separation of duty between approving and
+landing — is therefore enforced entirely by which local process a call reaches (B2), and not
+at all by the forge. It survives exactly as long as B2 does, and B2 is the boundary the
+migration dissolves.
+
+**Finding 2 — The `mdcps` tenant has no role separation at all.** Author, reviewer, and
+merger all resolve to account `913443`. One credential can open a PR, approve it, and merge
+it. The in-process self-review check compares the authenticated username against the PR
+author and would refuse — but that check runs on our side of B4. It is not a property of
+the credential, and an attacker holding the token does not call our tools.
+
+**Finding 3 — Any one role process can resolve every other role's credential.** This is not
+inferred; it is demonstrated by tool output. `gitea_list_profiles`
+(`gitea_mcp_server.py:19258`) called from the **author** session reports
+`identity_status: "credentials present"` for `prgs-merger`, `prgs-reviewer`,
+`prgs-reconciler`, and every `mdcps` profile, because it calls `resolve_token` on each one
+(`gitea_mcp_server.py:19309`). The author process does not merely *have access to* the
+merger's credential — it reads it to answer a status query. B2 is not a credential boundary
+in either direction.
+
+**Finding 4 — The Gitea server reads CI and observability secrets.** `gitea_audit_config`
+(`gitea_mcp_server.py:19552`) reports `MDCPS Jenkins: enabled, read-only, authenticated`.
+That word `authenticated` is produced by `service_summaries` (`gitea_mcp_server.py:19574`,
+defined at `gitea_config.py:837`), whose default check calls `_keychain_token` on the
+service's own keychain reference (`gitea_config.py:851`). Producing that one line requires
+the Gitea MCP server to read the Jenkins secret and the GlitchTip secret out of the
+keychain. B7 does not exist.
+
+**Finding 5 — Jenkins and GlitchTip are already decomposed; the reach is residual.** Their
+tools live in separately registered servers, marked `external-mcp`
+(`gitea_mcp_server.py:17707`, `gitea_mcp_server.py:17713`, `gitea_mcp_server.py:17734`,
+`gitea_mcp_server.py:17739`) with their own expected tool sets (`mcp_discoverability.py:9`,
+`mcp_discoverability.py:17`). The correct decomposition was already chosen. What remains is
+a leak across it: the credential *references* still live in the Gitea configuration and are
+still resolved by the Gitea process. #75 bundled these services into one control-plane
+umbrella; the tools were separated afterwards, the credentials were not.
+
+**Finding 6 — Sentry is the exception that is not decomposed.** Unlike Jenkins and
+GlitchTip, the Sentry bridge runs *inside* the Gitea server, resolving its token from the
+process environment (`sentry_incident_bridge.py:190`) and sending it as a bearer header
+(`sentry_incident_bridge.py:289`). Being an environment variable rather than a keychain item
+makes it strictly worse: it needs no keychain prompt and is inherited by every subprocess the
+server spawns — including the `ps` invocations at `gitea_mcp_server.py:21462` and
+`gitea_mcp_server.py:21506`, reached from `gitea_mcp_server.py:21442`.
+
+**Finding 7 — The highest-value coordination asset has the weakest gate.** A6 is protected
+by filesystem permissions alone (CR14). Corrupting a lease requires no Gitea credential,
+produces no forge-side audit record, and breaks the mutual exclusion the entire workflow
+assumes. Every other asset costs an attacker a credential; this one costs nothing beyond
+local access, which is exactly ADV5's position.
+
+**Finding 8 — Provenance authenticates the launch, not the caller.** `server_provenance` is
+reported as exactly `client_managed` or `manual_launch` (`gitea_mcp_server.py:19001`),
+derived from environment inspection (`gitea_mcp_server.py:15412`) with the recognized-key
+allowlist at `gitea_config.py:1172` and the generator that emits the marker at
+`gitea_config.py:1233`. Every one of those facts is fixed at process start. A client that is
+trustworthy at launch and compromised a minute later remains `client_managed` for the life
+of the process, and the stdio contract that underwrites it is stated as a property of the
+server itself (`mcp_server.py:4`).
+
+## 6. Decomposition ruling
+
+This section is the ruling #956 requires. It is a decision, not a recommendation.
+
+**D1 — No unrelated co-residency.** A single integration process **must not** hold, resolve,
+or be able to resolve credentials for services it does not itself integrate with.
+Concretely: the Gitea MCP service may hold Gitea credentials and nothing else. Jenkins,
+GlitchTip, Sentry, and any database credential are **not permitted** to co-reside with Gitea
+credentials in one process.
+
+*Rationale.* A process is the smallest unit an attacker takes whole. Once ADV1 or ADV2
+controls execution in a process, every credential that process can resolve is theirs, and no
+in-process check helps, because the checks are in the process too. Blast radius is therefore
+a property of the process boundary and nothing finer. Findings 4 and 6 show that today one
+compromise of the Gitea server yields CI read access, error-tracking read access, and — via
+CR13 — every role credential on both tenants. That is the single largest reduction in blast
+radius available anywhere in epic #929, and it costs no new mechanism: the decomposition
+already exists (Finding 5) and is merely leaked across.
+
+**D2 — Separation of duty must be backed by credentials.** Two roles whose separation is a
+security property must not resolve to the same forge account. Specifically, reviewer and
+merger must be distinct accounts. Today they are not, on either tenant (Findings 1 and 2).
+
+*Rationale.* B2 is a process boundary, and the migration's entire purpose is to replace
+process boundaries with request-level ones. A separation enforced only by which process a
+call reaches does not survive that replacement — and it is already bypassable by anyone who
+holds the token and calls the API instead of the tool.
+
+**D3 — Credential resolution is scoped to the request principal.** A session must resolve its
+own credential and must have no path to any other principal's. The resolve-every-profile
+behavior behind `gitea_mcp_server.py:19309` and `gitea_mcp_server.py:19574` must report
+configured-or-not from configuration alone, without resolving the secret.
+
+*Rationale.* Finding 3. An audit surface that proves a credential exists by fetching it is a
+credential-aggregation primitive wearing a diagnostic's clothes.
+
+**D4 — Coordination state is a protected asset with its own authority.** Access to locks,
+leases, and decision records must require an authenticated session, not merely local
+filesystem access.
+
+*Rationale.* Finding 7. #937 already moves this store for concurrency reasons; the
+authorization requirement must land with it, or the store becomes remotely reachable while
+still being authorized by nothing.
+
+### Exceptions
+
+**One, time-boxed.** During the dual-run window defined by #939, the **local** stdio fleet
+may continue to resolve Jenkins and GlitchTip credential *references* from the shared
+configuration, because removing them from the local configuration is not a prerequisite for
+standing up the remote endpoint and would strand the operator's existing local workflow.
+
+This exception is bounded by all of:
+
+- It applies to the local stdio deployment only. The remote endpoint (#938) must be
+ configured with Gitea credentials and no others from its first day.
+- It expires when #939 completes. It does not survive cutover.
+- It does not extend to Sentry: CR11 and CR12 are process-environment credentials in the
+ Gitea server (Finding 6) and must be absent from the remote deployment's environment
+ regardless of dual-run state.
+
+No exception is granted to D2, D3, or D4.
+
+### Consequences for the target architecture
+
+- The remote endpoint serves **Gitea only**. It is not a general control-plane endpoint.
+- Jenkins and GlitchTip keep their existing separate servers, and their credential
+ references move out of the Gitea configuration.
+- The Sentry bridge either moves behind its own service boundary or is absent from the
+ remote deployment. It does not travel with the Gitea server.
+- Reviewer and merger accounts diverge before the endpoint is trusted for merges, or A9 is
+ recorded as unenforced.
+
+## 7. Child-to-boundary mapping
+
+Every #929 child from 2 through 10, mapped to the boundary it implements. A child
+implementing more than one boundary names its primary first.
+
+| Child | Issue | Boundaries | What it must establish | Rulings it must honor |
+| ----: | ----- | ---------- | ---------------------- | --------------------- |
+| 2 | #931 | B1, B9 | The bound transport becomes a validated value that provenance and freshness can both key on. Without it neither B1 nor B9 has an input. | — |
+| 3 | #932 | B2 | The role becomes a property of the request, not the process — the boundary the migration otherwise deletes. | D2, D3 |
+| 4 | #933 | B3, B7 | Credentials come from a provider keyed by principal. This is where D1 and D3 are either enforced or permanently lost. | D1, D3 |
+| 5 | #934 | B1 | Session provenance replaces pipe-and-process-table proof with an authenticated session identity. | — |
+| 6 | #935 | B9 | Freshness redefined against deployed build identity, with an explicit undeterminable verdict. | — |
+| 7 | #936 | B5 | Every tool classified and the filesystem boundary enforced at dispatch, so a tool cannot return green about the wrong disk. | — |
+| 8 | #937 | B6 | One authority per ownership question, with session-identity liveness and atomic transitions. | D4 |
+| 9 | #938 | B4, B1, B8 | The endpoint: authentication, principal binding, transport security, and — critically — the deployed credential set. | D1, D2, D3 |
+| 10 | #939 | B6 | Dual-run with exactly one coordination authority at every instant, and the rollback that proves the way back. | D1 exception expiry |
+
+Boundary coverage: B1 (#931, #934, #938), B2 (#932), B3 (#933), B4 (#938), B5 (#936),
+B6 (#937, #939), B7 (#933), B8 (#938), B9 (#931, #935).
+
+B7 has exactly one owner, #933, and that is deliberate. B7 is not created by standing up an
+endpoint; it is created by deciding which credentials a process may resolve, which is
+precisely what the credential-provider child does.
+
+## 8. Adversarial walkthrough: a fully compromised LLM client
+
+The required negative case. ADV1 holds one MCP client and issues arbitrary tool calls. What
+does it reach at each boundary?
+
+### Before the migration
+
+The client is attached to the local fleet over stdio.
+
+| Boundary | What ADV1 reaches | Stopped by |
+| -------- | ----------------- | ---------- |
+| B1 | Everything the fleet serves. The client *is* the sanctioned launcher: it satisfies the client-managed check (`gitea_mcp_server.py:15412`) by construction, and provenance is never re-verified after launch (Finding 8). | Nothing. The guard authenticates the launch, not the caller. |
+| B2 | All five roles — it is attached to all five namespaces. It can author a PR, approve it from the reviewer namespace, and merge it from the merger namespace. | Only the in-process self-review check, which compares `jcwalker3` (author) against `sysadmin` (reviewer) and **passes**, because Finding 1 made them different accounts while leaving reviewer and merger identical. A9 falls in one sequence of legitimate calls. |
+| B3 | Every credential in CR1–CR10 via CR13, with no additional prompt — the daemon is already sanctioned, so `assert_keychain_access_allowed` (`mcp_daemon_guard.py:440`) returns immediately. | Nothing. |
+| B4 | A1 and A2 in full. | Branch protection at the forge, to the extent configured. |
+| B5 | The operator's checkout and every worktree, through the author tools (`gitea_mcp_server.py:10894`), plus the shared stderr path at `mcp_server.py:10`. | Nothing; the server's disk is the target disk. |
+| B6 | All coordination state — no credential required (CR14). It can forge lease ownership and clear decision locks. | Filesystem permissions, which it already satisfies. |
+| B7 | Jenkins (A4) and GlitchTip (A5) secrets via Finding 4, and CR11/CR12 from its own environment. | Nothing. |
+| B8 | Both tenants. | Nothing in-process; only the disabled-context check (`gitea_config.py:704`), which does not apply to enabled contexts. |
+| B9 | Can it run stale code? Only by advancing the checkout, which parity detects (`master_parity_gate.py:255`). | This gate holds — the one boundary that behaves as designed against ADV1. |
+
+**Result: total.** One compromised client yields A1 through A8 and A10. The only asset with
+real resistance is A1 via branch protection, and the client holds the merger credential
+anyway. Nine boundaries, one meaningful stop.
+
+### After the migration
+
+The same client authenticates to the remote endpoint with one role's credential, assuming
+#931–#939 land **and honor D1–D4**.
+
+| Boundary | What ADV1 reaches | Stopped by |
+| -------- | ----------------- | ---------- |
+| B1 | One authenticated session, bound to one principal. | #934: a forged or expired session identity is refused; the client cannot mint one. |
+| B2 | **One role.** Presenting the author credential yields author permissions only. | #932: the principal comes from the credential, not from which endpoint was reached. |
+| B3 | **One credential — its own.** | #933 with D3: the provider resolves by principal, and no diagnostic resolves the others. |
+| B4 | That role's authority on the forge. | Endpoint authentication (#938); plaintext and unauthenticated attempts refused before dispatch. |
+| B5 | **Nothing.** Filesystem tools are refused over the remote transport with a named blocker. | #936. |
+| B6 | Its own leases; contention resolves to exactly one winner. | #937 with D4: authenticated session required, not filesystem access. |
+| B7 | **Nothing.** No CI or observability credential exists in the process. | D1 — the single largest reduction on this table. |
+| B8 | One tenant. | D1 and #938: the deployment carries one tenant's credentials. |
+| B9 | Cannot induce stale enforcement. | #935: explicit fail-closed verdict, including undeterminable. |
+
+**Result: bounded.** The compromise is contained to one role on one tenant, with no
+filesystem reach and no lateral credential access. A9 survives *only if D2 lands* — if
+reviewer and merger still share `sysadmin`, a compromised reviewer session still merges, and
+this row reads the same after the migration as before it.
+
+### What the migration does not fix
+
+Against **ADV2**, both tables are identical. Prompt injection does not need to cross a
+boundary: it arrives inside an authorized session and asks that session to do what it is
+already permitted to do. Every "stopped by" above authenticates a principal, and the
+injected instruction has the correct principal. The migration reduces ADV1's blast radius by
+roughly an order of magnitude and reduces ADV2's by nothing.
+
+The controls that do constrain ADV2 are per-principal permission scope (#932), repository
+scope (`gitea_config.py:499`), and credential-backed separation of duty (D2) — each limiting
+what an authenticated session may do *regardless of what it is asked for*. #955's
+secure-isolation end state should be read with that distinction in mind: removing credentials
+from clients defeats ADV1 and ADV5, and does not by itself defeat ADV2.
+
+Two further items are explicitly out of scope here and unowned by #929:
+
+- **Session-credential rotation and revocation.** #938 names rotation as documentation, but
+ no child owns proving that a revoked credential stops an in-flight session.
+- **ADV3** (malicious tool arguments) is diffused across every child rather than owned. The
+ per-request principal work in #932 is the natural place to assert that identifiers taken
+ from the request never authorize anything on their own.
+
+## 9. How to verify this document
+
+1. `PYTHONPATH=. pytest tests/test_issue_956_threat_model.py` — resolves every anchor
+ against the working tree and checks the document's structural obligations.
+2. Pick any five anchors at random and read them; the fixture states what each line must
+ contain.
+3. Reproduce Findings 3 and 4 live: call `gitea_list_profiles` and `gitea_audit_config`
+ from the **author** namespace. Credential presence reported for roles other than the
+ active one is Finding 3; `MDCPS Jenkins: enabled, read-only, authenticated` is Finding 4.
+
+If the anchor test fails after an unrelated refactor, the anchors moved and the fixture
+needs regenerating — the claims are still true, but they are no longer traceable, which
+#956 treats as the same defect.
diff --git a/tests/test_issue_956_threat_model.py b/tests/test_issue_956_threat_model.py
new file mode 100644
index 0000000..6a67ac3
--- /dev/null
+++ b/tests/test_issue_956_threat_model.py
@@ -0,0 +1,323 @@
+"""Validation tooling for the remote-MCP threat model (#956).
+
+#956 requires that "every boundary claim [is] traceable to a file and line
+anchor that resolves at the reviewed commit". A prose document cannot enforce
+that about itself, and #930 demonstrated the failure mode: its inventory cited
+``gitea_mcp_server.py`` anchors generated at ``7bf4f125`` which no longer point
+at the described code at ``aad5c8b4``. Nothing failed, because nothing checked.
+
+These tests are that check. They enforce, in both directions:
+
+* every ``file.py:NNN`` anchor cited in the prose is declared in the fixture;
+* every declared anchor resolves — the file exists, the line exists, and the
+ source line actually contains the substring the fixture claims for it;
+* the document's structural obligations (assets, adversaries, boundaries,
+ credential rows, the co-residency ruling, and the child mapping) are present
+ and internally consistent.
+
+A refactor that shifts a line number therefore breaks the suite instead of
+silently rotting the security documentation.
+"""
+
+import json
+import os
+import re
+import unittest
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+DOC_PATH = os.path.join(REPO_ROOT, "docs", "remote-mcp", "threat-model.md")
+FIXTURE_PATH = os.path.join(
+ REPO_ROOT, "docs", "remote-mcp", "threat-model-anchors.json"
+)
+
+# ``module.py:123`` as it appears inside markdown inline code spans.
+ANCHOR_RE = re.compile(r"`([A-Za-z0-9_./-]+\.py):(\d+)`")
+
+# The epic children this document must map to a boundary (#929 children 2-10).
+REQUIRED_CHILDREN = [931, 932, 933, 934, 935, 936, 937, 938, 939]
+
+# The adversaries #956 names explicitly.
+REQUIRED_ADVERSARIES = [
+ "compromised LLM client",
+ "prompt injection",
+ "malicious tool arguments",
+ "network attacker",
+ "curious operator",
+]
+
+
+def _read(path):
+ with open(path, "r", encoding="utf-8") as fh:
+ return fh.read()
+
+
+def _heading_re(title):
+ """Match a level-2 heading by title, with or without section numbering.
+
+ The document numbers its sections ('## 6. Decomposition ruling'), so an
+ exact-substring assertion would break on renumbering without the document
+ having actually lost anything.
+ """
+ return re.compile(
+ r"^##\s+(?:\d+\.\s+)?" + re.escape(title), re.MULTILINE
+ )
+
+
+def _section_body(doc, title):
+ """Return the text of section *title*, bounded by the next level-2 heading.
+
+ Bounding matters: an unbounded slice runs to end-of-document, so the
+ walkthrough tables in a later section leak into the child-to-boundary
+ mapping and satisfy its coverage check with rows that assign no owner.
+ """
+ match = _heading_re(title).search(doc)
+ if match is None:
+ return None
+ rest = doc[match.end():]
+ nxt = re.search(r"^##\s", rest, re.MULTILINE)
+ return rest[: nxt.start()] if nxt else rest
+
+
+def _source_line(rel_path, lineno):
+ """Return the 1-based *lineno* of *rel_path*, or None if out of range."""
+ abs_path = os.path.join(REPO_ROOT, rel_path)
+ if not os.path.exists(abs_path):
+ return None
+ with open(abs_path, "r", encoding="utf-8", errors="replace") as fh:
+ for idx, line in enumerate(fh, start=1):
+ if idx == lineno:
+ return line
+ return None
+
+
+class ThreatModelFixtureTests(unittest.TestCase):
+ """The fixture itself must be well-formed before it can prove anything."""
+
+ def setUp(self):
+ self.fixture = json.loads(_read(FIXTURE_PATH))
+
+ def test_fixture_declares_a_generation_commit(self):
+ sha = self.fixture.get("generated_against_commit") or ""
+ self.assertRegex(
+ sha,
+ r"^[0-9a-f]{40}$",
+ "the fixture must record the full commit its anchors were taken at",
+ )
+
+ def test_fixture_anchors_are_unique_and_well_formed(self):
+ seen = set()
+ for entry in self.fixture["anchors"]:
+ anchor = entry["anchor"]
+ self.assertNotIn(anchor, seen, f"duplicate anchor entry: {anchor}")
+ seen.add(anchor)
+ self.assertRegex(anchor, r"^[A-Za-z0-9_./-]+\.py:[1-9]\d*$", anchor)
+ self.assertTrue(
+ (entry.get("expect") or "").strip(),
+ f"anchor {anchor} declares no 'expect' substring, so it proves nothing",
+ )
+
+
+class ThreatModelAnchorResolutionTests(unittest.TestCase):
+ """#956 required positive test: every anchor resolves at the reviewed commit."""
+
+ def setUp(self):
+ self.fixture = json.loads(_read(FIXTURE_PATH))
+ self.doc = _read(DOC_PATH)
+
+ def test_every_declared_anchor_resolves_to_the_claimed_source_line(self):
+ failures = []
+ for entry in self.fixture["anchors"]:
+ rel_path, _, raw_lineno = entry["anchor"].partition(":")
+ lineno = int(raw_lineno)
+ line = _source_line(rel_path, lineno)
+ if line is None:
+ failures.append(f"{entry['anchor']}: file or line does not exist")
+ continue
+ if entry["expect"] not in line:
+ failures.append(
+ f"{entry['anchor']}: expected {entry['expect']!r}, "
+ f"found {line.strip()!r}"
+ )
+ self.assertEqual(
+ [], failures, "unresolved threat-model anchors:\n" + "\n".join(failures)
+ )
+
+ def test_every_anchor_cited_in_the_document_is_declared_in_the_fixture(self):
+ declared = {e["anchor"] for e in self.fixture["anchors"]}
+ cited = {f"{m.group(1)}:{m.group(2)}" for m in ANCHOR_RE.finditer(self.doc)}
+ undeclared = sorted(cited - declared)
+ self.assertEqual(
+ [],
+ undeclared,
+ "document cites anchors that no test verifies: " + ", ".join(undeclared),
+ )
+
+ def test_the_document_actually_cites_anchors(self):
+ cited = {f"{m.group(1)}:{m.group(2)}" for m in ANCHOR_RE.finditer(self.doc)}
+ self.assertGreaterEqual(
+ len(cited),
+ 30,
+ "a boundary document with almost no anchors is not traceable",
+ )
+
+ def test_unresolvable_anchor_is_detected(self):
+ """Negative control: the checker must fail on a deliberately bad anchor.
+
+ Without this, a checker that silently passed everything would look
+ identical to a correct one.
+ """
+ self.assertIsNone(_source_line("gitea_config.py", 10**9))
+ self.assertIsNone(_source_line("no_such_module_for_956.py", 1))
+ real = _source_line("gitea_config.py", 54)
+ self.assertIsNotNone(real)
+ self.assertNotIn("this substring is not on that line", real)
+
+
+class ThreatModelStructureTests(unittest.TestCase):
+ """The document must contain what #956's acceptance criteria demand."""
+
+ def setUp(self):
+ self.doc = _read(DOC_PATH)
+
+ def test_records_the_commit_it_was_generated_against(self):
+ fixture = json.loads(_read(FIXTURE_PATH))
+ self.assertIn(
+ fixture["generated_against_commit"],
+ self.doc,
+ "the document must state the commit its anchors resolve at",
+ )
+
+ def test_names_every_required_adversary(self):
+ low = self.doc.lower()
+ for adversary in REQUIRED_ADVERSARIES:
+ self.assertIn(adversary.lower(), low, f"adversary not covered: {adversary}")
+
+ def test_maps_every_epic_child_from_two_through_ten(self):
+ for number in REQUIRED_CHILDREN:
+ self.assertIn(
+ f"#{number}",
+ self.doc,
+ f"epic child #{number} is not mapped to a boundary",
+ )
+
+ def test_credential_rows_declare_holder_boundary_and_blast_radius(self):
+ for column in ("Holder", "Boundary", "Blast radius"):
+ self.assertIn(
+ column,
+ self.doc,
+ f"the credential inventory must state each credential's {column.lower()}",
+ )
+
+ def test_states_an_explicit_co_residency_ruling(self):
+ """AC3/AC5: an explicit ruling, not an implication."""
+ self.assertIsNotNone(
+ _heading_re("Decomposition ruling").search(self.doc),
+ "the document must contain an explicit decomposition-ruling section",
+ )
+ for service in ("Jenkins", "GlitchTip", "Sentry", "database"):
+ self.assertIn(service, self.doc, f"ruling does not address {service}")
+ self.assertRegex(
+ self.doc,
+ r"D1\b.*must not",
+ "the ruling must state the prohibition, not merely discuss it",
+ )
+
+ def test_contains_the_compromised_client_walkthrough(self):
+ """#956 required negative/adversarial test."""
+ self.assertIsNotNone(
+ _heading_re("Adversarial walkthrough").search(self.doc),
+ "the required compromised-client walkthrough is missing",
+ )
+ self.assertIn("Before the migration", self.doc)
+ self.assertIn("After the migration", self.doc)
+
+ def test_every_boundary_states_what_it_protects_and_what_crossing_requires(self):
+ boundary_ids = set(re.findall(r"\bB(\d+)\b", self.doc))
+ self.assertGreaterEqual(
+ len(boundary_ids), 5, "too few trust boundaries to be a decomposition"
+ )
+ for column in (
+ "Protects",
+ "Crossing requires today",
+ "Crossing must require remotely",
+ ):
+ self.assertIn(column, self.doc, f"boundary table is missing '{column}'")
+
+ def test_declares_itself_documentation_only(self):
+ self.assertIn("documentation only", self.doc.lower())
+
+
+class ThreatModelConsistencyTests(unittest.TestCase):
+ """Counts stated in prose must match the rows actually present."""
+
+ def setUp(self):
+ self.doc = _read(DOC_PATH)
+
+ def _declared_ids(self, prefix):
+ # Table rows begin '| CR1 |' / '| B3 |' / '| A2 |'.
+ return sorted(
+ {
+ int(m)
+ for m in re.findall(
+ r"^\|\s*%s(\d+)\s*\|" % prefix, self.doc, re.MULTILINE
+ )
+ }
+ )
+
+ def test_identifier_sequences_have_no_gaps(self):
+ for prefix, label in (
+ ("A", "assets"),
+ ("B", "boundaries"),
+ ("CR", "credentials"),
+ ):
+ ids = self._declared_ids(prefix)
+ self.assertTrue(ids, f"no {label} declared")
+ self.assertEqual(
+ list(range(1, len(ids) + 1)),
+ ids,
+ f"{label} identifiers must run 1..n with no gaps; got {ids}",
+ )
+
+ def test_stated_credential_count_matches_the_rows(self):
+ ids = self._declared_ids("CR")
+ match = re.search(r"(\d+)\s+credential(?:s)? in total", self.doc)
+ self.assertIsNotNone(match, "the credential inventory must state its own total")
+ self.assertEqual(
+ len(ids),
+ int(match.group(1)),
+ "stated credential total disagrees with the number of rows",
+ )
+
+ def test_every_boundary_is_owned_by_at_least_one_child(self):
+ """Each boundary must be owned by a child *in the mapping table*.
+
+ Scanning the whole section would let a prose summary line ("Boundary
+ coverage: ... B5 (#936)") satisfy the assertion while the table row
+ that actually assigns the owner had been emptied — verified by
+ deliberately blanking a row and watching a whole-section check still
+ pass. Only table rows count.
+ """
+ mapping_section = _section_body(self.doc, "Child-to-boundary mapping")
+ self.assertIsNotNone(
+ mapping_section, "child-to-boundary mapping section is missing"
+ )
+ rows = [
+ line
+ for line in mapping_section.splitlines()
+ if line.lstrip().startswith("|") and re.search(r"#93\d", line)
+ ]
+ self.assertGreaterEqual(
+ len(rows), len(REQUIRED_CHILDREN), "mapping table has too few child rows"
+ )
+ mapped = set(re.findall(r"\bB(\d+)\b", "\n".join(rows)))
+ declared = {str(i) for i in self._declared_ids("B")}
+ unmapped = sorted(declared - mapped, key=int)
+ self.assertEqual(
+ [],
+ unmapped,
+ "boundaries with no owning child: " + ", ".join("B" + u for u in unmapped),
+ )
+
+
+if __name__ == "__main__":
+ unittest.main()