Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
  sysadminandClaude Opus 4.8
|
fe259e6d38 |
@@ -1,223 +0,0 @@
|
||||
# ADR: MCP restart governance and authorization policy
|
||||
|
||||
- **Status:** Accepted (policy effective immediately for LLM and operator sessions; enforcement tooling may lag)
|
||||
- **Date:** 2026-07-23
|
||||
- **Tracking issue:** [#656](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/656)
|
||||
- **Policy version:** `restart-governance/v1`
|
||||
- **Related:**
|
||||
- Umbrella: [#655](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/655) — governed MCP restart coordination and zero-disruption recovery
|
||||
- Vision: [#652](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/652) — MCP Control Plane Web Console product vision (§A system health and process control)
|
||||
- Roadmap: [#653](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/653) — Control Plane Web Console phased delivery (Phase 2 restart controls)
|
||||
- Contamination guard: [#630](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/630) — blocks manual process-kill recovery
|
||||
- Console restart UX: [#642](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/642) — sanctioned restart and graceful reload
|
||||
- Existing restart / reconnect paths to inventory: [#591](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/591) — auto-restart on master advance (closed); [#584](https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/issues/584) — host auto-reconnect on transport flap
|
||||
- Stable-control runtime split: `docs/architecture/mcp-stable-control-runtime-policy-adr.md` (#615)
|
||||
- Client-namespace health: `docs/mcp-namespace-health.md` (#543)
|
||||
- Reconnect-only EOF recovery: `docs/mcp-namespace-eof-recovery.md`
|
||||
|
||||
## 1. Context
|
||||
|
||||
The Gitea MCP server is the **control plane** for real issue and PR mutations
|
||||
(create, comment, lock, review, merge, reconcile). The same process serves every
|
||||
role namespace (`gitea-author`, `gitea-reviewer`, `gitea-merger`,
|
||||
`gitea-reconciler`, `gitea-controller`) and holds the in-memory capability-gate
|
||||
code loaded at startup.
|
||||
|
||||
Restarting that process is destructive to concurrent work:
|
||||
|
||||
- It resets every session's identity, preflight, and capability-lease binding.
|
||||
- It can interrupt a mutation mid-critical-section (a lock acquire, a review
|
||||
submit, a merge), leaving durable state half-written.
|
||||
- Relaunching from the wrong checkout or worktree silently changes which code
|
||||
the control plane runs, defeating master-parity gates (#420 / #615).
|
||||
|
||||
Today there is **no durable written policy** stating who may restart MCP, under
|
||||
what conditions, that restart is a last resort, and how controller approval,
|
||||
automated safety gates, and break-glass interact. Operators and LLM sessions
|
||||
therefore invent restart behavior ad hoc, which makes concurrent multi-role work
|
||||
unsafe. #630 and #642 need this policy as their backbone.
|
||||
|
||||
This ADR defines that policy. It does **not** implement coordinator code or HA
|
||||
multi-instance restart (those are later children of #655).
|
||||
|
||||
## 2. Decision
|
||||
|
||||
### 2.1 v1 decision (recorded)
|
||||
|
||||
**Restart authority in v1 is `controller approval + automated safety gates`.**
|
||||
|
||||
A restart of the stable control runtime is authorized only when **both** hold:
|
||||
|
||||
1. A **controller** role explicitly approves the restart, recording an audit
|
||||
entry (who, why, scope, affected sessions), **and**
|
||||
2. The **automated safety gates** pass: a completed drain acknowledgement (no
|
||||
affected session is mid-critical-section) or a declared break-glass incident
|
||||
(§2.5).
|
||||
|
||||
Quorum among multiple controllers is **not** required day-one. It is deferred
|
||||
unless a later investigation (tracked under #653) proves single-controller
|
||||
approval is insufficient. This ADR records the v1 decision so enforcement code
|
||||
(#630) has a fixed target; changing it requires a superseding ADR.
|
||||
|
||||
### 2.2 Restart is a last resort — the recovery ladder
|
||||
|
||||
Restart is the **last** rung. Before any restart, exhaust the narrower
|
||||
recoveries, in order:
|
||||
|
||||
1. **Reconnect** the IDE/client MCP namespace (transport EOF, `client is
|
||||
closing: EOF`, transient `#584` flap). No process change. See
|
||||
`docs/mcp-namespace-eof-recovery.md`.
|
||||
2. **Refresh / rebind** the session workspace: re-run `gitea_whoami`,
|
||||
`gitea_resolve_task_capability`, and pass an explicit validated
|
||||
`worktree_path`. Fixes stale session context without touching the process.
|
||||
3. **Scoped restart** of a single misbehaving namespace/service (where the
|
||||
deployment supports per-service restart) rather than the whole control plane.
|
||||
4. **Full restart** of the stable control runtime process — operator-owned,
|
||||
controller-approved, drained.
|
||||
5. **Host / infrastructure restart** — the broadest action; same authorization
|
||||
as a full restart plus infrastructure ownership.
|
||||
|
||||
A session **must** try rungs 1–2 and record why they were insufficient before
|
||||
requesting a restart at rung 3 or above. Skipping straight to restart is a
|
||||
policy violation.
|
||||
|
||||
### 2.3 Authorization matrix
|
||||
|
||||
| Role | Reconnect (1) | Refresh/rebind (2) | Scoped restart (3) | Full restart (4) | Host restart (5) |
|
||||
|---|---|---|---|---|---|
|
||||
| **author** | self | self | request only | **forbidden** | forbidden |
|
||||
| **reviewer** | self | self | request only | **forbidden** | forbidden |
|
||||
| **merger** | self | self | request only | **forbidden** | forbidden |
|
||||
| **reconciler** | self | self | request only | **forbidden** | forbidden |
|
||||
| **controller** | self | self | **approve** (+gates) | **approve** (+gates) | request to operator |
|
||||
| **operator** | self | self | execute (controller-approved) | execute (controller-approved) | execute (controller-approved) |
|
||||
| **admin** | self | self | execute | execute | execute (break-glass) |
|
||||
|
||||
Legend: *self* = may perform for its own client session; *request only* = may
|
||||
raise a restart request but not authorize or execute it; *approve* = may
|
||||
authorize under §2.1 gates; *execute* = may perform the process action after the
|
||||
authorization is recorded.
|
||||
|
||||
Key invariants:
|
||||
|
||||
- **No LLM worker role (author/reviewer/merger/reconciler) may perform or
|
||||
authorize a full or host restart.** They may only reconnect/rebind their own
|
||||
client and file a restart request.
|
||||
- **Controller approval authorizes; operator/admin executes.** The approving
|
||||
controller and the executing operator may be the same human, but both the
|
||||
approval and the execution are audited.
|
||||
- Privileged process actions (full restart, host restart) are reserved to
|
||||
**operator/admin**, never to an automated worker.
|
||||
|
||||
### 2.4 Approved conditions
|
||||
|
||||
A restart at rung 3+ is approved only under one of these recorded conditions:
|
||||
|
||||
- **No affected sessions:** the control plane has no live session that would be
|
||||
interrupted (verified, not assumed).
|
||||
- **Full drain acknowledged:** every affected session has drained
|
||||
(no open critical section — no held mutation lease mid-write) and the drain is
|
||||
acknowledged in the audit record.
|
||||
- **Controller + gates:** controller approval plus passing automated safety
|
||||
gates (§2.1), the standard v1 path.
|
||||
- **Quorum:** not required in v1; reserved for a future superseding ADR.
|
||||
- **Break-glass:** an incident-backed emergency exception (§2.5).
|
||||
|
||||
Restart **never** bypasses mutation gates mid-critical-section. Drain before
|
||||
restart is mandatory except under break-glass with a declared incident.
|
||||
|
||||
### 2.5 Break-glass
|
||||
|
||||
Break-glass is a **separate, narrower** authorization path for emergencies where
|
||||
the normal drain-and-approve path cannot complete (e.g. the control plane is
|
||||
wedged and cannot drain).
|
||||
|
||||
Break-glass conditions:
|
||||
|
||||
- A declared incident record exists (id, timestamp, declarer) **before** the
|
||||
action.
|
||||
- The action is taken by **operator or admin** authority only — never by an LLM
|
||||
worker role, and never unilaterally by an operator with active peers when a
|
||||
controller is reachable.
|
||||
- The scope is the minimum necessary rung of the ladder.
|
||||
- A **mandatory post-hoc audit** entry is filed: what was restarted, why the
|
||||
normal path was impossible, which sessions were affected, and the incident id.
|
||||
|
||||
Break-glass suspends the drain requirement, not the audit requirement.
|
||||
|
||||
### 2.6 Explicit prohibitions
|
||||
|
||||
- **A unilateral LLM or operator full restart while active peer sessions
|
||||
exist is forbidden.** An LLM worker role must not kill, restart, or relaunch
|
||||
the MCP process; a lone operator must not full-restart over live peer work
|
||||
without controller approval or a break-glass incident.
|
||||
- Process-kill recovery is forbidden as a routine tool (#630). This ADR does not
|
||||
introduce a kill path.
|
||||
- Ambiguous policy state **denies** restart (§4).
|
||||
|
||||
## 3. Security requirements
|
||||
|
||||
- Full restart and host restart are **privileged**; only operator/admin execute
|
||||
them, only after a controller approval or break-glass incident is recorded.
|
||||
- Break-glass is a distinct authorization path with its own audit mandate; it is
|
||||
never the default and never silent.
|
||||
- **Every approval and every restart action is audited** (who approved, who
|
||||
executed, scope, affected sessions, condition, policy version). No restart is
|
||||
authorized without a durable audit entry.
|
||||
|
||||
## 4. Failure behavior
|
||||
|
||||
**Ambiguous policy → deny restart.** If it cannot be established that a
|
||||
restart is authorized under §2 — unknown affected-session state, missing
|
||||
controller approval, absent break-glass incident, or an unclassifiable request —
|
||||
the safe action is to **refuse** the restart and stop with a recovery report,
|
||||
never to restart on assumption.
|
||||
|
||||
## 5. Policy IDs (for enforcement code)
|
||||
|
||||
Enforcement code — the restart coordinator (a later child of #655), the #630
|
||||
contamination guard, and the #642 console restart UX — binds to these stable
|
||||
policy identifiers rather than to prose:
|
||||
|
||||
| Policy ID | Statement |
|
||||
|---|---|
|
||||
| `RG-01` | Restart is last resort; rungs 1–2 must be tried and recorded first (§2.2). |
|
||||
| `RG-02` | v1 authority = controller approval + automated safety gates (§2.1). |
|
||||
| `RG-03` | No LLM worker role performs or authorizes full/host restart (§2.3). |
|
||||
| `RG-04` | Full/host restart executed by operator/admin only, post approval (§2.3). |
|
||||
| `RG-05` | Drain before restart is mandatory except break-glass with incident (§2.4). |
|
||||
| `RG-06` | Break-glass requires a pre-declared incident and post-hoc audit (§2.5). |
|
||||
| `RG-07` | Unilateral LLM/operator full restart with active peers is forbidden (§2.6). |
|
||||
| `RG-08` | Ambiguous policy state denies restart (§4). |
|
||||
|
||||
The `restart-governance/v1` **policy version** field is emitted on future
|
||||
restart audit events so approvals can be reconciled against the policy revision
|
||||
in force.
|
||||
|
||||
## 6. Dogfooding
|
||||
|
||||
Gitea-Tools governs its own MCP control plane by this policy. Author, reviewer,
|
||||
merger, and reconciler sessions operating on this repository use the recovery
|
||||
ladder (§2.2) — reconnect and rebind, never self-restart — and any real restart
|
||||
of the Gitea-Tools stable control runtime follows the controller-approval +
|
||||
drain path defined here.
|
||||
|
||||
## 7. Acceptance and cross-links
|
||||
|
||||
This ADR is the authoritative restart-governance policy. It **must** stay
|
||||
cross-linked from the safety model and the web-console deployment boundary:
|
||||
|
||||
- `docs/safety-model.md` § Process restart governance references this ADR.
|
||||
- `docs/webui-deployment.md` references this ADR for restart/reload disposition.
|
||||
|
||||
It is linked to its issue lineage — umbrella **#655**, vision **#652**, roadmap
|
||||
**#653**, contamination guard **#630**, and console restart UX **#642** — in
|
||||
§ Related above.
|
||||
|
||||
## 8. Non-goals
|
||||
|
||||
- Implementing the restart coordinator or approval state machine (#630, later
|
||||
children of #655).
|
||||
- Implementing HA multi-instance restart or quorum machinery.
|
||||
- Introducing any process-kill or auto-restart tool; existing auto-restart
|
||||
behavior must be inventoried before any new restart tool is enabled.
|
||||
@@ -46,17 +46,3 @@ If shell helpers are unavailable and MCP commit cannot run, stop with a recovery
|
||||
report (restart session, clear hung terminals, use MCP-native commit). See
|
||||
[`llm-workflow-runbooks.md`](llm-workflow-runbooks.md) § MCP-native commit path
|
||||
(#260) and agent temp artifact cleanup (#261).
|
||||
|
||||
## 7. Process restart governance
|
||||
|
||||
Restarting the MCP control-plane process is destructive to concurrent multi-role
|
||||
work and is governed by a dedicated policy. Restart is a **last resort** behind
|
||||
narrower recoveries (reconnect, rebind), full/host restart is reserved to
|
||||
operator/admin under **controller approval + automated safety gates**, a
|
||||
unilateral LLM or operator full restart with active peers is **forbidden**, and
|
||||
ambiguous policy state **denies** restart. Break-glass is a separate,
|
||||
incident-backed path with a mandatory audit.
|
||||
|
||||
See [`architecture/mcp-restart-governance.md`](architecture/mcp-restart-governance.md)
|
||||
(#656) for the authorization matrix, the recovery ladder, break-glass
|
||||
conditions, and the `RG-01`–`RG-08` policy IDs.
|
||||
|
||||
@@ -55,15 +55,6 @@ shipped to the browser.
|
||||
assumption paths, and the client-secret policy. Use it to verify an instance is
|
||||
configured for internal-only operation.
|
||||
|
||||
## Process restart / reload disposition
|
||||
|
||||
The console never exposes a restart or reload control; process restart of the
|
||||
MCP control-plane runtime is governed separately. Restart is a last resort behind
|
||||
reconnect/rebind, full restart is operator/admin-only under controller approval
|
||||
plus safety gates, and break-glass is an incident-backed path. See
|
||||
[`architecture/mcp-restart-governance.md`](architecture/mcp-restart-governance.md)
|
||||
(#656).
|
||||
|
||||
## Non-goals (MVP)
|
||||
|
||||
- Full SSO or session login in the UI
|
||||
|
||||
+77
-5
@@ -11634,6 +11634,7 @@ def gitea_audit_worktree_cleanup(
|
||||
org: str | None = None,
|
||||
repo: str | None = None,
|
||||
ttl_hours: float = worktree_cleanup_audit.DEFAULT_TTL_HOURS,
|
||||
merged_pr_limit: int = 200,
|
||||
) -> dict:
|
||||
"""Read-only: classify every session-owned worktree under ``branches/`` (#401).
|
||||
|
||||
@@ -11644,17 +11645,26 @@ def gitea_audit_worktree_cleanup(
|
||||
the active issue-lock branch is read from the local lock file and treated
|
||||
as active work. Deletes nothing and mutates no Gitea state.
|
||||
|
||||
Fails closed if the live open-PR list cannot be fetched: without it,
|
||||
removability cannot be proven, so no candidates are returned.
|
||||
Merged PRs are fetched as well, so an issue worktree can be linked to the
|
||||
PR that owns its branch (#858). Such a worktree only becomes removable
|
||||
when that owning PR is unambiguous and merged, the worktree head is
|
||||
already contained in authoritative master, and nothing else protects it —
|
||||
no open or competing PR, lease, issue lock, live session, dirty file, or
|
||||
protected/control checkout. Anything unproven keeps it classified as
|
||||
active issue work.
|
||||
|
||||
Fails closed if the live open-PR list, the merged-PR list, or the
|
||||
control-plane lease state cannot be read: without them removability
|
||||
cannot be proven, so no candidates are returned.
|
||||
|
||||
Args:
|
||||
remote: Known instance — 'dadeschools' or 'prgs'.
|
||||
host: Override the Gitea host.
|
||||
org: Override the owner/organization.
|
||||
repo: Override the repository name.
|
||||
ttl_hours: Age (hours) after which a clean issue/conflict-fix
|
||||
worktree becomes stale-removable (default from
|
||||
GITEA_WORKTREE_TTL_HOURS).
|
||||
ttl_hours: Age (hours) after which a clean conflict-fix worktree
|
||||
becomes stale-removable (default from GITEA_WORKTREE_TTL_HOURS).
|
||||
merged_pr_limit: Max closed PRs scanned for merged-PR ownership.
|
||||
|
||||
Returns:
|
||||
dict with per-worktree classifications, counts, removable
|
||||
@@ -11690,22 +11700,84 @@ def gitea_audit_worktree_cleanup(
|
||||
if (pr.get("head") or {}).get("ref")
|
||||
}
|
||||
|
||||
# #858: merged PRs are the ownership evidence that lets a landed issue
|
||||
# worktree stop being reported as active work. Without them the audit can
|
||||
# never agree with the PR-scoped reconciler, so treat a fetch failure the
|
||||
# same way an open-PR fetch failure is treated: fail closed.
|
||||
try:
|
||||
closed_prs = api_get_all(
|
||||
f"{repo_api_url(h, o, r)}/pulls?state=closed", auth, limit=merged_pr_limit
|
||||
)
|
||||
except Exception as exc:
|
||||
return {
|
||||
"success": False,
|
||||
"performed": False,
|
||||
"open_pr_state_verified": True,
|
||||
"merged_pr_state_verified": False,
|
||||
"reasons": [
|
||||
"could not fetch merged PRs; worktree ownership unverified "
|
||||
f"(fail closed): {_redact(str(exc))}"
|
||||
],
|
||||
}
|
||||
merged_prs = [pr for pr in closed_prs if (pr.get("merged") or pr.get("merged_at"))]
|
||||
pr_index = worktree_cleanup_audit.build_pr_index(list(open_prs) + merged_prs)
|
||||
|
||||
# #858: the auditor already accepted lease evidence but nothing ever
|
||||
# supplied it, so every worktree looked unleased. Removability is now
|
||||
# reachable for issue worktrees, so authoritative control-plane leases
|
||||
# must be readable or the audit fails closed.
|
||||
db, lease_errs = _control_plane_db_or_error()
|
||||
if db is None:
|
||||
return {
|
||||
"success": False,
|
||||
"performed": False,
|
||||
"open_pr_state_verified": True,
|
||||
"merged_pr_state_verified": True,
|
||||
"lease_state_verified": False,
|
||||
"reasons": [
|
||||
"could not read control-plane leases; worktree protection "
|
||||
"unverified (fail closed)",
|
||||
*lease_errs,
|
||||
],
|
||||
}
|
||||
lease_result = lease_lifecycle.list_active_leases(
|
||||
db, remote=remote, org=o, repo=r, include_non_active=False, limit=500
|
||||
)
|
||||
leased_issue_numbers: set[int] = set()
|
||||
live_session_paths: set[str] = set()
|
||||
for lease in lease_result.get("leases") or []:
|
||||
if lease.get("work_kind") == "issue" and lease.get("work_number") is not None:
|
||||
try:
|
||||
leased_issue_numbers.add(int(lease["work_number"]))
|
||||
except (TypeError, ValueError):
|
||||
pass
|
||||
if lease.get("worktree_path"):
|
||||
live_session_paths.add(str(lease["worktree_path"]))
|
||||
|
||||
active_issue_branches: set[str] = set()
|
||||
lock = merged_cleanup_reconcile.read_issue_lock(ISSUE_LOCK_FILE)
|
||||
if lock and lock.get("branch_name"):
|
||||
active_issue_branches.add(str(lock["branch_name"]).strip())
|
||||
|
||||
master_ref = f"{remote}/master" if remote in REMOTES else "origin/master"
|
||||
report = worktree_cleanup_audit.audit_branches_directory(
|
||||
_canonical_local_git_root(),
|
||||
open_pr_branches=open_pr_branches,
|
||||
active_issue_branches=active_issue_branches,
|
||||
now=datetime.now(timezone.utc),
|
||||
ttl_hours=ttl_hours,
|
||||
pr_index=pr_index,
|
||||
leased_issue_numbers=leased_issue_numbers,
|
||||
live_session_paths=live_session_paths,
|
||||
master_ref=master_ref,
|
||||
)
|
||||
return {
|
||||
"success": True,
|
||||
"performed": False,
|
||||
"open_pr_state_verified": True,
|
||||
"merged_pr_state_verified": True,
|
||||
"lease_state_verified": True,
|
||||
"master_ref": master_ref,
|
||||
"task_mode": "work-issue",
|
||||
**report,
|
||||
}
|
||||
|
||||
@@ -0,0 +1,551 @@
|
||||
"""Merged-PR awareness for the worktree cleanup audit (#858).
|
||||
|
||||
Before #858 an ``issue_work`` worktree could never leave ``active_issue_work``:
|
||||
the audit had no PR linkage at all (``pr_number`` was structurally ``None``)
|
||||
and its only route to ``clean_stale_removable`` was a TTL derived from a
|
||||
``last_used_at`` that nothing ever populated. A merged, clean, unprotected
|
||||
worktree was therefore reported as active work forever, disagreeing with the
|
||||
PR-scoped reconciler.
|
||||
|
||||
These tests use fabricated temporary repositories and synthetic PR records
|
||||
only. Nothing here removes a worktree or deletes a branch.
|
||||
"""
|
||||
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import unittest
|
||||
from unittest.mock import patch
|
||||
|
||||
sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent))
|
||||
|
||||
import merged_cleanup_reconcile as mcr # noqa: E402
|
||||
import worktree_cleanup_audit as wca # noqa: E402
|
||||
|
||||
|
||||
MERGED_BRANCH = "feat/issue-777-timeline"
|
||||
MERGED_PATH = "/repo/branches/issue-777-timeline"
|
||||
HEAD_SHA = "a" * 40
|
||||
|
||||
|
||||
def _pr(number, branch, *, merged=True, sha=HEAD_SHA, state=None):
|
||||
"""Synthetic Gitea PR payload."""
|
||||
return {
|
||||
"number": number,
|
||||
"head": {"ref": branch, "sha": sha},
|
||||
"merged_at": "2026-07-24T01:00:00Z" if merged else None,
|
||||
"state": state or ("closed" if merged else "open"),
|
||||
}
|
||||
|
||||
|
||||
def _porcelain(*entries):
|
||||
out = []
|
||||
for path, branch, sha in entries:
|
||||
out.append(f"worktree {path}")
|
||||
out.append(f"HEAD {sha}")
|
||||
if branch is None:
|
||||
out.append("detached")
|
||||
else:
|
||||
out.append(f"branch refs/heads/{branch}")
|
||||
out.append("")
|
||||
return "\n".join(out)
|
||||
|
||||
|
||||
class _AuditHarness(unittest.TestCase):
|
||||
"""Runs audit_branches_directory over a fabricated worktree listing."""
|
||||
|
||||
PORCELAIN = _porcelain(
|
||||
("/repo", "master", "f" * 40),
|
||||
(MERGED_PATH, MERGED_BRANCH, HEAD_SHA),
|
||||
)
|
||||
|
||||
def run_audit(self, *, dirty_paths=(), contained=True, **kwargs):
|
||||
def fake_dirty(path):
|
||||
if path in dirty_paths:
|
||||
return {"exists": True, "dirty": True, "dirty_files": [" M x.py"]}
|
||||
return {"exists": True, "dirty": False, "dirty_files": []}
|
||||
|
||||
with patch.object(
|
||||
wca, "list_worktrees",
|
||||
return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
|
||||
), patch.object(
|
||||
wca, "read_worktree_dirty", side_effect=fake_dirty
|
||||
), patch.object(
|
||||
wca, "git_worktree_list", return_value="(mocked)"
|
||||
), patch.object(
|
||||
wca, "is_head_ancestor_of_ref", return_value=contained
|
||||
):
|
||||
report = wca.audit_branches_directory("/repo", **kwargs)
|
||||
return {wt["path"]: wt for wt in report["worktrees"]}, report
|
||||
|
||||
def merged_audit(self, **kwargs):
|
||||
kwargs.setdefault("pr_index", wca.build_pr_index([_pr(849, MERGED_BRANCH)]))
|
||||
kwargs.setdefault("master_ref", "prgs/master")
|
||||
return self.run_audit(**kwargs)
|
||||
|
||||
|
||||
class TestMergedWorktreeBecomesRemovable(_AuditHarness):
|
||||
def test_clean_merged_issue_worktree_is_linked_and_removable(self):
|
||||
by_path, report = self.merged_audit()
|
||||
entry = by_path[MERGED_PATH]
|
||||
|
||||
self.assertEqual(entry["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE)
|
||||
self.assertTrue(entry["removable"])
|
||||
self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_MERGED)
|
||||
self.assertEqual(entry["merged_pr_cleanup"]["block_reasons"], [])
|
||||
self.assertIn(MERGED_PATH, [c["path"] for c in report["removable_candidates"]])
|
||||
|
||||
def test_pr_number_populated_from_authoritative_linkage(self):
|
||||
by_path, _ = self.merged_audit()
|
||||
self.assertEqual(by_path[MERGED_PATH]["pr_number"], 849)
|
||||
|
||||
def test_regression_without_pr_evidence_stays_active_issue_work(self):
|
||||
"""The pre-#858 behaviour, still correct when no PR state is supplied."""
|
||||
by_path, _ = self.run_audit()
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
self.assertIsNone(entry["pr_number"])
|
||||
|
||||
|
||||
class TestProtectiveSignalsSurvive(_AuditHarness):
|
||||
def test_open_pr_worktree_is_not_removable(self):
|
||||
index = wca.build_pr_index([_pr(900, MERGED_BRANCH, merged=False)])
|
||||
by_path, _ = self.run_audit(
|
||||
pr_index=index,
|
||||
master_ref="prgs/master",
|
||||
open_pr_branches={MERGED_BRANCH},
|
||||
)
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_OPEN_PR)
|
||||
self.assertFalse(entry["removable"])
|
||||
# linkage still reports the owning PR, it just is not merge proof
|
||||
self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_OPEN)
|
||||
self.assertEqual(entry["pr_number"], 900)
|
||||
|
||||
def test_dirty_tracked_worktree_is_not_removable(self):
|
||||
by_path, _ = self.merged_audit(dirty_paths=(MERGED_PATH,))
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL)
|
||||
self.assertFalse(entry["removable"])
|
||||
self.assertIn(
|
||||
"worktree has uncommitted changes",
|
||||
entry["merged_pr_cleanup"]["block_reasons"],
|
||||
)
|
||||
|
||||
def test_untracked_only_worktree_is_not_removable(self):
|
||||
"""``git status --porcelain`` reports untracked files as dirty too."""
|
||||
def untracked(path):
|
||||
if path == MERGED_PATH:
|
||||
return {"exists": True, "dirty": True, "dirty_files": ["?? scratch.txt"]}
|
||||
return {"exists": True, "dirty": False, "dirty_files": []}
|
||||
|
||||
with patch.object(
|
||||
wca, "list_worktrees",
|
||||
return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
|
||||
), patch.object(
|
||||
wca, "read_worktree_dirty", side_effect=untracked
|
||||
), patch.object(
|
||||
wca, "git_worktree_list", return_value="(mocked)"
|
||||
), patch.object(
|
||||
wca, "is_head_ancestor_of_ref", return_value=True
|
||||
):
|
||||
report = wca.audit_branches_directory(
|
||||
"/repo",
|
||||
pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
|
||||
master_ref="prgs/master",
|
||||
)
|
||||
entry = {wt["path"]: wt for wt in report["worktrees"]}[MERGED_PATH]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_active_lease_by_issue_number_is_protective(self):
|
||||
by_path, _ = self.merged_audit(leased_issue_numbers={777})
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertTrue(entry["has_active_lease"])
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_active_lease_by_branch_is_protective(self):
|
||||
by_path, _ = self.merged_audit(leased_branches={MERGED_BRANCH})
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertTrue(entry["has_active_lease"])
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_active_issue_lock_is_protective(self):
|
||||
by_path, _ = self.merged_audit(active_issue_branches={MERGED_BRANCH})
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertTrue(entry["has_active_issue_lock"])
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_live_session_worktree_is_protective(self):
|
||||
by_path, _ = self.merged_audit(live_session_paths={MERGED_PATH})
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertTrue(entry["has_live_session"])
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_head_not_contained_in_master_is_not_removable(self):
|
||||
by_path, _ = self.merged_audit(contained=False)
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
self.assertIn(
|
||||
"worktree head is not contained in authoritative master "
|
||||
"(unmerged commits remain)",
|
||||
entry["merged_pr_cleanup"]["block_reasons"],
|
||||
)
|
||||
|
||||
def test_unknown_containment_fails_closed(self):
|
||||
by_path, _ = self.merged_audit(contained=None)
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertFalse(entry["removable"])
|
||||
self.assertIn(
|
||||
"containment of the worktree head in master is unknown",
|
||||
entry["merged_pr_cleanup"]["block_reasons"],
|
||||
)
|
||||
|
||||
def test_missing_master_ref_fails_closed(self):
|
||||
by_path, _ = self.run_audit(
|
||||
pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)])
|
||||
)
|
||||
self.assertFalse(by_path[MERGED_PATH]["removable"])
|
||||
|
||||
def test_unmerged_owning_pr_is_not_removable(self):
|
||||
index = wca.build_pr_index([_pr(901, MERGED_BRANCH, merged=False)])
|
||||
by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertFalse(entry["removable"])
|
||||
self.assertIn(
|
||||
"owning PR #901 is not merged",
|
||||
entry["merged_pr_cleanup"]["block_reasons"],
|
||||
)
|
||||
|
||||
def test_control_checkout_is_never_removable(self):
|
||||
by_path, _ = self.merged_audit()
|
||||
control = by_path["/repo"]
|
||||
self.assertTrue(control["is_protected"])
|
||||
self.assertEqual(control["classification"], wca.CLASS_UNSAFE_UNKNOWN)
|
||||
self.assertFalse(control["removable"])
|
||||
|
||||
def test_control_checkout_not_removable_even_if_linked_and_merged(self):
|
||||
"""A merged PR on the control checkout must not unlock removal."""
|
||||
porcelain = _porcelain(("/repo", MERGED_BRANCH, HEAD_SHA))
|
||||
with patch.object(
|
||||
wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain)
|
||||
), patch.object(
|
||||
wca, "read_worktree_dirty",
|
||||
return_value={"exists": True, "dirty": False, "dirty_files": []},
|
||||
), patch.object(
|
||||
wca, "git_worktree_list", return_value="(mocked)"
|
||||
), patch.object(
|
||||
wca, "is_head_ancestor_of_ref", return_value=True
|
||||
):
|
||||
report = wca.audit_branches_directory(
|
||||
"/repo",
|
||||
pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
|
||||
master_ref="prgs/master",
|
||||
)
|
||||
entry = report["worktrees"][0]
|
||||
self.assertEqual(entry["classification"], wca.CLASS_UNSAFE_UNKNOWN)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
|
||||
class TestAmbiguousLinkageFailsClosed(_AuditHarness):
|
||||
def test_competing_prs_on_one_branch_fail_closed(self):
|
||||
index = wca.build_pr_index(
|
||||
[_pr(849, MERGED_BRANCH), _pr(860, MERGED_BRANCH)]
|
||||
)
|
||||
by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS)
|
||||
self.assertIsNone(entry["pr_number"])
|
||||
self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_merged_plus_open_pr_on_one_branch_fails_closed(self):
|
||||
index = wca.build_pr_index(
|
||||
[_pr(849, MERGED_BRANCH), _pr(861, MERGED_BRANCH, merged=False)]
|
||||
)
|
||||
by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master")
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_no_owning_pr_fails_closed(self):
|
||||
by_path, _ = self.run_audit(
|
||||
pr_index=wca.build_pr_index([_pr(849, "feat/other-branch")]),
|
||||
master_ref="prgs/master",
|
||||
)
|
||||
entry = by_path[MERGED_PATH]
|
||||
self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_NONE)
|
||||
self.assertFalse(entry["removable"])
|
||||
|
||||
def test_malformed_pr_records_are_dropped_not_guessed(self):
|
||||
index = wca.build_pr_index(
|
||||
[
|
||||
{"number": None, "head": {"ref": MERGED_BRANCH}},
|
||||
{"number": 5, "head": {}},
|
||||
{"number": "not-an-int", "head": {"ref": MERGED_BRANCH}},
|
||||
]
|
||||
)
|
||||
self.assertEqual(index, {})
|
||||
self.assertEqual(
|
||||
wca.resolve_owning_pr(branch=MERGED_BRANCH, pr_index=index)["status"],
|
||||
wca.LINKAGE_NONE,
|
||||
)
|
||||
|
||||
def test_detached_worktree_has_no_branch_linkage(self):
|
||||
self.assertEqual(
|
||||
wca.resolve_owning_pr(branch=None, pr_index={})["status"],
|
||||
wca.LINKAGE_UNKNOWN,
|
||||
)
|
||||
|
||||
|
||||
class TestUnrelatedClassificationsUnchanged(unittest.TestCase):
|
||||
"""Non-issue_work worktrees keep their pre-#858 classifications."""
|
||||
|
||||
PORCELAIN = _porcelain(
|
||||
("/repo", "master", "f" * 40),
|
||||
("/repo/branches/review-pr42", "review-pr42", "2" * 40),
|
||||
("/repo/branches/baseline-master-x", "baseline-master-x", "3" * 40),
|
||||
("/repo/branches/conflict-fix-pr50", "conflict-fix-pr50", "4" * 40),
|
||||
("/repo/branches/review-pr99", None, "5" * 40),
|
||||
)
|
||||
|
||||
def _audit(self, **kwargs):
|
||||
with patch.object(
|
||||
wca, "list_worktrees",
|
||||
return_value=wca.parse_worktree_porcelain(self.PORCELAIN),
|
||||
), patch.object(
|
||||
wca, "read_worktree_dirty",
|
||||
return_value={"exists": True, "dirty": False, "dirty_files": []},
|
||||
), patch.object(
|
||||
wca, "git_worktree_list", return_value="(mocked)"
|
||||
), patch.object(
|
||||
wca, "is_head_ancestor_of_ref", return_value=True
|
||||
):
|
||||
report = wca.audit_branches_directory("/repo", **kwargs)
|
||||
return {wt["path"]: wt for wt in report["worktrees"]}
|
||||
|
||||
def test_classifications_identical_with_and_without_pr_evidence(self):
|
||||
without = self._audit()
|
||||
with_evidence = self._audit(
|
||||
pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
|
||||
master_ref="prgs/master",
|
||||
)
|
||||
self.assertEqual(
|
||||
{p: e["classification"] for p, e in without.items()},
|
||||
{p: e["classification"] for p, e in with_evidence.items()},
|
||||
)
|
||||
|
||||
def test_lease_on_issue_does_not_capture_similarly_named_scratch_trees(self):
|
||||
"""A lease on issue 777 protects issue work, not baseline/review trees."""
|
||||
porcelain = _porcelain(
|
||||
("/repo/branches/baseline-master-issue-777", "baseline-issue-777", "7" * 40),
|
||||
("/repo/branches/issue-777-timeline", MERGED_BRANCH, HEAD_SHA),
|
||||
)
|
||||
with patch.object(
|
||||
wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain)
|
||||
), patch.object(
|
||||
wca, "read_worktree_dirty",
|
||||
return_value={"exists": True, "dirty": False, "dirty_files": []},
|
||||
), patch.object(
|
||||
wca, "git_worktree_list", return_value="(mocked)"
|
||||
), patch.object(
|
||||
wca, "is_head_ancestor_of_ref", return_value=True
|
||||
):
|
||||
report = wca.audit_branches_directory(
|
||||
"/repo",
|
||||
pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]),
|
||||
master_ref="prgs/master",
|
||||
leased_issue_numbers={777},
|
||||
)
|
||||
by_path = {wt["path"]: wt for wt in report["worktrees"]}
|
||||
|
||||
baseline = by_path["/repo/branches/baseline-master-issue-777"]
|
||||
self.assertFalse(baseline["has_active_lease"])
|
||||
self.assertEqual(baseline["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE)
|
||||
|
||||
issue_work = by_path["/repo/branches/issue-777-timeline"]
|
||||
self.assertTrue(issue_work["has_active_lease"])
|
||||
self.assertFalse(issue_work["removable"])
|
||||
|
||||
def test_review_and_baseline_still_removable(self):
|
||||
by_path = self._audit(
|
||||
pr_index=wca.build_pr_index([]), master_ref="prgs/master"
|
||||
)
|
||||
self.assertEqual(
|
||||
by_path["/repo/branches/review-pr42"]["classification"],
|
||||
wca.CLASS_CLEAN_STALE_REMOVABLE,
|
||||
)
|
||||
self.assertEqual(
|
||||
by_path["/repo/branches/baseline-master-x"]["classification"],
|
||||
wca.CLASS_CLEAN_STALE_REMOVABLE,
|
||||
)
|
||||
self.assertEqual(
|
||||
by_path["/repo/branches/review-pr99"]["classification"],
|
||||
wca.CLASS_DETACHED_REVIEW_LEFTOVER,
|
||||
)
|
||||
|
||||
def test_conflict_fix_ttl_behaviour_unchanged(self):
|
||||
"""conflict_fix still needs only TTL expiry; #858 did not touch it."""
|
||||
self.assertEqual(
|
||||
wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_CONFLICT_FIX,
|
||||
is_dirty=False,
|
||||
ttl_expired=True,
|
||||
),
|
||||
wca.CLASS_CLEAN_STALE_REMOVABLE,
|
||||
)
|
||||
self.assertEqual(
|
||||
wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_CONFLICT_FIX,
|
||||
is_dirty=False,
|
||||
ttl_expired=False,
|
||||
),
|
||||
wca.CLASS_ACTIVE_ISSUE_WORK,
|
||||
)
|
||||
|
||||
def test_issue_work_ttl_alone_no_longer_grants_removal(self):
|
||||
"""Age is not landing proof: TTL alone must not reclaim issue work."""
|
||||
self.assertEqual(
|
||||
wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_ISSUE_WORK,
|
||||
is_dirty=False,
|
||||
ttl_expired=True,
|
||||
),
|
||||
wca.CLASS_ACTIVE_ISSUE_WORK,
|
||||
)
|
||||
|
||||
|
||||
class TestAssessorPerformsNoDeletion(_AuditHarness):
|
||||
def test_audit_never_removes_a_worktree(self):
|
||||
with patch.object(wca, "remove_worktree") as removal:
|
||||
self.merged_audit()
|
||||
removal.assert_not_called()
|
||||
|
||||
def test_audit_shells_out_to_no_destructive_git_command(self):
|
||||
seen = []
|
||||
real_run = subprocess.run
|
||||
|
||||
def recording_run(cmd, *args, **kwargs):
|
||||
seen.append(cmd)
|
||||
return real_run(["true"], *args, **kwargs)
|
||||
|
||||
with patch.object(subprocess, "run", side_effect=recording_run):
|
||||
wca.audit_branches_directory("/nonexistent-repo-for-audit")
|
||||
|
||||
joined = [" ".join(c) if isinstance(c, list) else str(c) for c in seen]
|
||||
for cmd in joined:
|
||||
self.assertNotIn("worktree remove", cmd)
|
||||
self.assertNotIn("branch -D", cmd)
|
||||
self.assertNotIn("push", cmd)
|
||||
|
||||
|
||||
class TestAgreementWithPrScopedReconciler(unittest.TestCase):
|
||||
"""The audit and merged_cleanup_reconcile must agree on identical input.
|
||||
|
||||
Uses a real throwaway git repository so containment is computed by git
|
||||
rather than asserted. Nothing outside the temporary directory is touched.
|
||||
"""
|
||||
|
||||
def _git(self, *args):
|
||||
subprocess.run(
|
||||
["git", "-C", self.root, *args],
|
||||
check=True,
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
|
||||
def setUp(self):
|
||||
self._tmp = tempfile.TemporaryDirectory()
|
||||
self.root = os.path.realpath(self._tmp.name)
|
||||
self._git("init", "-b", "master", ".")
|
||||
self._git("config", "user.email", "[email protected]")
|
||||
self._git("config", "user.name", "Test")
|
||||
with open(os.path.join(self.root, "seed.txt"), "w") as fh:
|
||||
fh.write("seed\n")
|
||||
self._git("add", "seed.txt")
|
||||
self._git("commit", "-m", "seed")
|
||||
|
||||
self.branch = "feat/issue-777-timeline"
|
||||
self._git("checkout", "-b", self.branch)
|
||||
with open(os.path.join(self.root, "feature.txt"), "w") as fh:
|
||||
fh.write("feature\n")
|
||||
self._git("add", "feature.txt")
|
||||
self._git("commit", "-m", "feature")
|
||||
self.head_sha = subprocess.run(
|
||||
["git", "-C", self.root, "rev-parse", "HEAD"],
|
||||
capture_output=True, text=True, check=True,
|
||||
).stdout.strip()
|
||||
self._git("checkout", "master")
|
||||
self._git("merge", "--no-ff", "-m", "merge feature", self.branch)
|
||||
|
||||
self.worktree = os.path.join(self.root, "branches", "issue-777-timeline")
|
||||
self._git("worktree", "add", self.worktree, self.branch)
|
||||
|
||||
def tearDown(self):
|
||||
self._tmp.cleanup()
|
||||
|
||||
def _pr_index(self):
|
||||
return wca.build_pr_index(
|
||||
[
|
||||
{
|
||||
"number": 849,
|
||||
"head": {"ref": self.branch, "sha": self.head_sha},
|
||||
"merged_at": "2026-07-24T01:00:00Z",
|
||||
}
|
||||
]
|
||||
)
|
||||
|
||||
def _audit_entry(self):
|
||||
report = wca.audit_branches_directory(
|
||||
self.root, pr_index=self._pr_index(), master_ref="master"
|
||||
)
|
||||
return next(wt for wt in report["worktrees"] if wt["path"] == self.worktree)
|
||||
|
||||
def _reconciler_entry(self):
|
||||
return mcr.assess_local_worktree_cleanup(
|
||||
pr_number=849,
|
||||
head_branch=self.branch,
|
||||
merged=True,
|
||||
worktree_state=mcr.resolve_cleanup_worktree_state(
|
||||
project_root=self.root,
|
||||
head_branch=self.branch,
|
||||
issue_number=777,
|
||||
pr_head_sha=self.head_sha,
|
||||
target_ref="master",
|
||||
),
|
||||
active_lock=False,
|
||||
)
|
||||
|
||||
def test_both_assessors_agree_the_worktree_is_safe(self):
|
||||
audit_entry = self._audit_entry()
|
||||
reconciler = self._reconciler_entry()
|
||||
|
||||
self.assertTrue(reconciler["safe_to_remove_worktree"], reconciler)
|
||||
self.assertTrue(audit_entry["removable"], audit_entry)
|
||||
self.assertEqual(audit_entry["pr_number"], reconciler["pr_number"])
|
||||
self.assertEqual(audit_entry["merged_pr_cleanup"]["block_reasons"], [])
|
||||
self.assertEqual(reconciler["block_reasons"], [])
|
||||
|
||||
def test_both_assessors_agree_a_dirty_worktree_is_unsafe(self):
|
||||
with open(os.path.join(self.worktree, "feature.txt"), "a") as fh:
|
||||
fh.write("local edit\n")
|
||||
|
||||
audit_entry = self._audit_entry()
|
||||
reconciler = self._reconciler_entry()
|
||||
|
||||
self.assertFalse(audit_entry["removable"])
|
||||
self.assertFalse(reconciler["safe_to_remove_worktree"])
|
||||
|
||||
def test_worktree_still_present_after_audit(self):
|
||||
self._audit_entry()
|
||||
self.assertTrue(os.path.isdir(self.worktree))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -1,107 +0,0 @@
|
||||
"""Documentation acceptance for the MCP restart governance ADR (#656).
|
||||
|
||||
Enforces issue #656 acceptance criteria:
|
||||
|
||||
* AC1 — policy document exists with an authorization matrix and the recorded
|
||||
v1 decision (controller approval + automated safety gates).
|
||||
* AC2 — restart is stated as a last resort with enumerated narrower recoveries.
|
||||
* AC3 — a unilateral LLM full restart with affected sessions is forbidden.
|
||||
* AC4 — break-glass conditions are listed.
|
||||
* AC5 — the ADR is linked to #655, #652, #653, #630, #642, and is cross-linked
|
||||
from the safety model and the web-console deployment boundary docs.
|
||||
"""
|
||||
from pathlib import Path
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parent.parent
|
||||
ADR = REPO_ROOT / "docs" / "architecture" / "mcp-restart-governance.md"
|
||||
ADR_BASENAME = "mcp-restart-governance.md"
|
||||
|
||||
CROSS_LINK_DOCS = (
|
||||
REPO_ROOT / "docs" / "safety-model.md",
|
||||
REPO_ROOT / "docs" / "webui-deployment.md",
|
||||
)
|
||||
|
||||
LINKED_ISSUES = ("#655", "#652", "#653", "#630", "#642")
|
||||
POLICY_IDS = ("RG-01", "RG-02", "RG-03", "RG-04", "RG-05", "RG-06", "RG-07", "RG-08")
|
||||
|
||||
|
||||
def _read(path: Path) -> str:
|
||||
assert path.is_file(), f"missing {path.relative_to(REPO_ROOT)}"
|
||||
return path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def test_ac1_adr_exists_with_matrix_and_v1_decision():
|
||||
text = _read(ADR)
|
||||
lower = text.lower()
|
||||
assert text.lstrip().startswith("#"), "ADR lacks a title"
|
||||
assert "#656" in text
|
||||
assert "authorization matrix" in lower
|
||||
# The matrix is a real table with the worker and privileged roles.
|
||||
for role in ("author", "reviewer", "merger", "reconciler", "controller",
|
||||
"operator", "admin"):
|
||||
assert role in lower, f"authorization matrix missing role {role!r}"
|
||||
# Recorded v1 decision.
|
||||
assert "restart-governance/v1" in text
|
||||
assert "controller approval" in lower and "automated safety gates" in lower
|
||||
|
||||
|
||||
def test_ac2_restart_is_last_resort_with_narrower_recoveries():
|
||||
text = _read(ADR)
|
||||
lower = text.lower()
|
||||
assert "last resort" in lower
|
||||
# Enumerated narrower recoveries precede full restart on the ladder.
|
||||
for rung in ("reconnect", "rebind", "scoped restart", "full restart",
|
||||
"host"):
|
||||
assert rung in lower, f"recovery ladder missing rung {rung!r}"
|
||||
|
||||
|
||||
def test_ac3_forbids_unilateral_llm_full_restart_with_affected_sessions():
|
||||
text = _read(ADR)
|
||||
lower = text.lower()
|
||||
assert "forbidden" in lower
|
||||
assert "llm" in lower and "restart" in lower
|
||||
assert "unilateral" in lower
|
||||
# A worker role must not perform or authorize full/host restart.
|
||||
assert "must not" in lower
|
||||
|
||||
|
||||
def test_ac4_break_glass_conditions_listed():
|
||||
text = _read(ADR)
|
||||
lower = text.lower()
|
||||
assert "break-glass" in lower
|
||||
assert "incident" in lower
|
||||
assert "audit" in lower
|
||||
|
||||
|
||||
def test_ac5_adr_links_issue_lineage():
|
||||
text = _read(ADR)
|
||||
for issue in LINKED_ISSUES:
|
||||
assert issue in text, f"ADR must link issue {issue}"
|
||||
|
||||
|
||||
def test_ac5_safety_model_and_deployment_cross_link_adr():
|
||||
for path in CROSS_LINK_DOCS:
|
||||
text = _read(path)
|
||||
assert ADR_BASENAME in text, (
|
||||
f"{path.relative_to(REPO_ROOT)} must cross-link {ADR_BASENAME} "
|
||||
f"(issue #656 acceptance criterion 5)"
|
||||
)
|
||||
|
||||
|
||||
def test_policy_ids_present_for_enforcement_code():
|
||||
text = _read(ADR)
|
||||
for pid in POLICY_IDS:
|
||||
assert pid in text, f"policy id {pid} missing from ADR"
|
||||
|
||||
|
||||
def test_failure_behavior_denies_on_ambiguity():
|
||||
text = _read(ADR)
|
||||
lower = text.lower()
|
||||
assert "ambiguous" in lower and "deny" in lower
|
||||
|
||||
|
||||
def test_cross_links_do_not_embed_secrets():
|
||||
for path in (ADR,) + CROSS_LINK_DOCS:
|
||||
text = _read(path)
|
||||
for marker in ("ghp_", "BEGIN PRIVATE KEY", "Authorization: Bearer"):
|
||||
assert marker not in text, f"{path} contains {marker!r}"
|
||||
@@ -134,13 +134,35 @@ class TestClassification(unittest.TestCase):
|
||||
self.assertEqual(cls, wca.CLASS_ACTIVE_OPEN_PR)
|
||||
self.assertFalse(wca.is_removable(cls))
|
||||
|
||||
def test_stale_clean_issue_worktree_removable(self):
|
||||
# Scenario 5: clean issue worktree, TTL expired, no lock -> removable.
|
||||
def test_stale_clean_issue_worktree_needs_merged_pr_proof(self):
|
||||
# Scenario 5 (#858): age is not proof that the branch landed, so a
|
||||
# TTL-expired issue worktree stays active work. Only authoritative
|
||||
# merged-PR evidence makes it removable, which is what keeps a
|
||||
# worktree holding unmerged commits from being reclaimed by age.
|
||||
cls = wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_ISSUE_WORK,
|
||||
is_dirty=False,
|
||||
ttl_expired=True,
|
||||
)
|
||||
self.assertEqual(cls, wca.CLASS_ACTIVE_ISSUE_WORK)
|
||||
self.assertFalse(wca.is_removable(cls))
|
||||
|
||||
cls = wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_ISSUE_WORK,
|
||||
is_dirty=False,
|
||||
ttl_expired=True,
|
||||
merged_pr_cleanup={"proven": True},
|
||||
)
|
||||
self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE)
|
||||
self.assertTrue(wca.is_removable(cls))
|
||||
|
||||
def test_stale_clean_conflict_fix_worktree_removable(self):
|
||||
# conflict_fix keeps the original TTL rule; #858 changed issue work only.
|
||||
cls = wca.classify_worktree(
|
||||
workflow_type=wca.WORKFLOW_CONFLICT_FIX,
|
||||
is_dirty=False,
|
||||
ttl_expired=True,
|
||||
)
|
||||
self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE)
|
||||
self.assertTrue(wca.is_removable(cls))
|
||||
|
||||
|
||||
+271
-4
@@ -34,7 +34,11 @@ import subprocess
|
||||
from datetime import datetime, timezone
|
||||
from typing import Any
|
||||
|
||||
from merged_cleanup_reconcile import branch_worktree_folder, read_local_worktree_state
|
||||
from merged_cleanup_reconcile import (
|
||||
branch_worktree_folder,
|
||||
is_head_ancestor_of_ref,
|
||||
read_local_worktree_state,
|
||||
)
|
||||
from reviewer_worktree import parse_dirty_tracked_files, REVIEW_WORKTREE_RE
|
||||
|
||||
PROTECTED_BRANCHES = frozenset({"master", "main", "dev"})
|
||||
@@ -67,6 +71,14 @@ REMOVABLE_CLASSES = frozenset(
|
||||
{CLASS_CLEAN_STALE_REMOVABLE, CLASS_DETACHED_REVIEW_LEFTOVER}
|
||||
)
|
||||
|
||||
# Merged-PR linkage outcomes for issue worktrees (#858). Only ``LINKAGE_MERGED``
|
||||
# is ownership proof; every other outcome leaves the worktree protected.
|
||||
LINKAGE_MERGED = "merged_pr"
|
||||
LINKAGE_OPEN = "open_pr"
|
||||
LINKAGE_NONE = "no_owning_pr"
|
||||
LINKAGE_AMBIGUOUS = "ambiguous"
|
||||
LINKAGE_UNKNOWN = "unknown"
|
||||
|
||||
_ISSUE_REF_RE = re.compile(r"issue-(\d+)", re.IGNORECASE)
|
||||
_ISSUE_BRANCH_PREFIXES = ("feat/", "fix/", "docs/", "chore/")
|
||||
|
||||
@@ -169,6 +181,186 @@ def is_ttl_expired(
|
||||
return (now_dt - last).total_seconds() > ttl_hours * 3600.0
|
||||
|
||||
|
||||
def build_pr_index(prs: list[dict[str, Any]] | None) -> dict[str, list[dict[str, Any]]]:
|
||||
"""Index PR records by head branch for deterministic worktree linkage (#858).
|
||||
|
||||
Accepts Gitea PR payloads (``head`` as a dict) and pre-flattened records
|
||||
(``head_branch``/``head_sha``). Records without a usable head branch or
|
||||
number are dropped rather than guessed at, so a branch is only ever linked
|
||||
to a PR the caller actually proved.
|
||||
"""
|
||||
index: dict[str, list[dict[str, Any]]] = {}
|
||||
for pr in prs or []:
|
||||
head = pr.get("head")
|
||||
if isinstance(head, dict):
|
||||
head_branch = head.get("ref")
|
||||
head_sha = head.get("sha")
|
||||
else:
|
||||
head_branch = pr.get("head_branch") or (head if isinstance(head, str) else None)
|
||||
head_sha = pr.get("head_sha")
|
||||
number = pr.get("number")
|
||||
if not head_branch or number is None:
|
||||
continue
|
||||
try:
|
||||
pr_number = int(number)
|
||||
except (TypeError, ValueError):
|
||||
continue
|
||||
index.setdefault(str(head_branch).strip(), []).append(
|
||||
{
|
||||
"pr_number": pr_number,
|
||||
"head_branch": str(head_branch).strip(),
|
||||
"head_sha": head_sha,
|
||||
"merged": bool(pr.get("merged") or pr.get("merged_at")),
|
||||
"state": pr.get("state"),
|
||||
}
|
||||
)
|
||||
return index
|
||||
|
||||
|
||||
def resolve_owning_pr(
|
||||
*,
|
||||
branch: str | None,
|
||||
pr_index: dict[str, list[dict[str, Any]]] | None,
|
||||
) -> dict[str, Any]:
|
||||
"""Resolve the single PR that owns ``branch``, failing closed when unclear.
|
||||
|
||||
Ownership is only ``LINKAGE_MERGED`` when exactly one PR claims the branch
|
||||
and that PR is merged. Several distinct PRs on one branch is a competing
|
||||
claim (``LINKAGE_AMBIGUOUS``), and a still-open owner is reported as
|
||||
``LINKAGE_OPEN`` — both keep the worktree protected while still exposing
|
||||
the PR number the audit resolved.
|
||||
"""
|
||||
if pr_index is None:
|
||||
return {
|
||||
"status": LINKAGE_UNKNOWN,
|
||||
"pr_number": None,
|
||||
"candidate_pr_numbers": [],
|
||||
"reasons": ["live PR state was not supplied; ownership unproven"],
|
||||
}
|
||||
branch_name = (branch or "").strip()
|
||||
if not branch_name:
|
||||
return {
|
||||
"status": LINKAGE_UNKNOWN,
|
||||
"pr_number": None,
|
||||
"candidate_pr_numbers": [],
|
||||
"reasons": ["worktree has no attached branch; ownership unproven"],
|
||||
}
|
||||
|
||||
candidates = list(pr_index.get(branch_name) or [])
|
||||
numbers = sorted({c["pr_number"] for c in candidates})
|
||||
if not candidates:
|
||||
return {
|
||||
"status": LINKAGE_NONE,
|
||||
"pr_number": None,
|
||||
"candidate_pr_numbers": [],
|
||||
"reasons": [f"no PR claims branch '{branch_name}'"],
|
||||
}
|
||||
if len(numbers) > 1:
|
||||
return {
|
||||
"status": LINKAGE_AMBIGUOUS,
|
||||
"pr_number": None,
|
||||
"candidate_pr_numbers": numbers,
|
||||
"reasons": [
|
||||
f"branch '{branch_name}' is claimed by competing PRs {numbers}; "
|
||||
"ownership is ambiguous"
|
||||
],
|
||||
}
|
||||
|
||||
owner = candidates[0]
|
||||
pr_number = owner["pr_number"]
|
||||
if owner.get("head_branch") != branch_name:
|
||||
return {
|
||||
"status": LINKAGE_UNKNOWN,
|
||||
"pr_number": pr_number,
|
||||
"candidate_pr_numbers": numbers,
|
||||
"reasons": [
|
||||
f"PR #{pr_number} head branch '{owner.get('head_branch')}' does not "
|
||||
f"match worktree branch '{branch_name}'"
|
||||
],
|
||||
}
|
||||
if not owner.get("merged"):
|
||||
return {
|
||||
"status": LINKAGE_OPEN,
|
||||
"pr_number": pr_number,
|
||||
"candidate_pr_numbers": numbers,
|
||||
"pr_head_sha": owner.get("head_sha"),
|
||||
"reasons": [f"owning PR #{pr_number} is not merged"],
|
||||
}
|
||||
return {
|
||||
"status": LINKAGE_MERGED,
|
||||
"pr_number": pr_number,
|
||||
"candidate_pr_numbers": numbers,
|
||||
"pr_head_sha": owner.get("head_sha"),
|
||||
"reasons": [],
|
||||
}
|
||||
|
||||
|
||||
def assess_merged_pr_worktree_cleanup(
|
||||
*,
|
||||
linkage: dict[str, Any] | None,
|
||||
head_sha: str | None,
|
||||
head_in_master: bool | None,
|
||||
is_dirty: bool,
|
||||
has_open_pr: bool,
|
||||
has_active_lease: bool,
|
||||
has_active_issue_lock: bool,
|
||||
is_protected: bool,
|
||||
has_live_session: bool = False,
|
||||
) -> dict[str, Any]:
|
||||
"""Decide whether a merged issue worktree satisfies the full cleanup policy.
|
||||
|
||||
Every condition must be independently proven: conclusive merged-PR
|
||||
ownership, agreement between the worktree branch and the PR head branch,
|
||||
containment of the worktree head in authoritative master (which is what
|
||||
proves no unmerged commits remain), absence of any open/competing PR,
|
||||
lease, issue lock, or live session, a clean tree, and a worktree that is
|
||||
not the protected control checkout. Anything unknown blocks.
|
||||
"""
|
||||
link = linkage or {
|
||||
"status": LINKAGE_UNKNOWN,
|
||||
"pr_number": None,
|
||||
"reasons": ["no linkage assessment supplied"],
|
||||
}
|
||||
status = link.get("status")
|
||||
reasons: list[str] = []
|
||||
|
||||
if status != LINKAGE_MERGED:
|
||||
reasons.extend(
|
||||
link.get("reasons") or ["owning PR could not be conclusively identified"]
|
||||
)
|
||||
if is_protected:
|
||||
reasons.append("worktree is protected or the stable control checkout")
|
||||
if is_dirty:
|
||||
reasons.append("worktree has uncommitted changes")
|
||||
if has_open_pr:
|
||||
reasons.append("worktree branch has an open PR")
|
||||
if has_active_lease:
|
||||
reasons.append("worktree has an active lease")
|
||||
if has_active_issue_lock:
|
||||
reasons.append("an active issue lock references this branch")
|
||||
if has_live_session:
|
||||
reasons.append("a live process or session is using this worktree")
|
||||
if not head_sha:
|
||||
reasons.append("worktree head sha is unknown")
|
||||
if head_in_master is None:
|
||||
reasons.append("containment of the worktree head in master is unknown")
|
||||
elif not head_in_master:
|
||||
reasons.append(
|
||||
"worktree head is not contained in authoritative master "
|
||||
"(unmerged commits remain)"
|
||||
)
|
||||
|
||||
proven = not reasons
|
||||
return {
|
||||
"linkage_status": status,
|
||||
"pr_number": link.get("pr_number"),
|
||||
"pr_head_sha": link.get("pr_head_sha"),
|
||||
"head_in_master": head_in_master,
|
||||
"proven": proven,
|
||||
"block_reasons": reasons,
|
||||
}
|
||||
|
||||
|
||||
def classify_worktree(
|
||||
*,
|
||||
workflow_type: str,
|
||||
@@ -181,6 +373,8 @@ def classify_worktree(
|
||||
ttl_expired: bool = False,
|
||||
is_protected: bool = False,
|
||||
metadata_known: bool = True,
|
||||
merged_pr_cleanup: dict[str, Any] | None = None,
|
||||
has_live_session: bool = False,
|
||||
) -> str:
|
||||
"""Classify a worktree, safety-first: any preservation signal wins.
|
||||
|
||||
@@ -199,6 +393,8 @@ def classify_worktree(
|
||||
return CLASS_ACTIVE_ISSUE_WORK # never auto-deleted (criterion 8)
|
||||
if has_active_issue_lock:
|
||||
return CLASS_ACTIVE_ISSUE_WORK
|
||||
if has_live_session:
|
||||
return CLASS_ACTIVE_ISSUE_WORK # a live session still owns this tree
|
||||
if not metadata_known or workflow_type == WORKFLOW_UNKNOWN:
|
||||
return CLASS_UNSAFE_UNKNOWN # never auto-deleted without proof
|
||||
|
||||
@@ -207,7 +403,15 @@ def classify_worktree(
|
||||
if is_detached or branch_gone:
|
||||
return CLASS_DETACHED_REVIEW_LEFTOVER
|
||||
return CLASS_CLEAN_STALE_REMOVABLE
|
||||
# issue_work / conflict_fix: only removable once the TTL has expired.
|
||||
if workflow_type == WORKFLOW_ISSUE_WORK:
|
||||
# #858: an issue worktree becomes removable only on authoritative
|
||||
# merged-PR evidence satisfying the whole cleanup policy. Age alone
|
||||
# never proves the branch landed, so TTL cannot qualify one by itself
|
||||
# — otherwise a worktree holding unmerged commits would be reclaimed.
|
||||
if (merged_pr_cleanup or {}).get("proven"):
|
||||
return CLASS_CLEAN_STALE_REMOVABLE
|
||||
return CLASS_ACTIVE_ISSUE_WORK
|
||||
# conflict_fix: only removable once the TTL has expired.
|
||||
if ttl_expired:
|
||||
return CLASS_CLEAN_STALE_REMOVABLE
|
||||
return CLASS_ACTIVE_ISSUE_WORK
|
||||
@@ -400,6 +604,20 @@ def remove_worktree(project_root: str, path: str) -> dict[str, Any]:
|
||||
}
|
||||
|
||||
|
||||
def head_contained_in_ref(
|
||||
project_root: str, head_sha: str | None, ref: str | None
|
||||
) -> bool | None:
|
||||
"""Return True when ``head_sha`` is already contained in ``ref``.
|
||||
|
||||
Shares :mod:`merged_cleanup_reconcile`'s ancestry check so the audit and
|
||||
the PR-scoped reconciler agree on what "already landed" means (#858).
|
||||
Returns None when containment cannot be determined, which fails closed.
|
||||
"""
|
||||
if not head_sha or not ref:
|
||||
return None
|
||||
return is_head_ancestor_of_ref(project_root, head_sha, ref)
|
||||
|
||||
|
||||
def _is_under_branches(project_root: str, path: str) -> bool:
|
||||
branches_root = os.path.join(os.path.abspath(project_root), "branches")
|
||||
return os.path.abspath(path or "").startswith(branches_root + os.sep)
|
||||
@@ -413,16 +631,30 @@ def audit_branches_directory(
|
||||
active_issue_branches: set[str] | None = None,
|
||||
now: datetime | str | None = None,
|
||||
ttl_hours: float = DEFAULT_TTL_HOURS,
|
||||
pr_index: dict[str, list[dict[str, Any]]] | None = None,
|
||||
leased_issue_numbers: set[int] | None = None,
|
||||
live_session_paths: set[str] | None = None,
|
||||
master_ref: str | None = None,
|
||||
) -> dict[str, Any]:
|
||||
"""Classify every session-owned worktree under ``branches/``.
|
||||
|
||||
Read-only: shells out to git for discovery and dirty state, then applies
|
||||
the pure classifier. Returns per-worktree classifications, counts, the
|
||||
list of removable candidates, and the ``git worktree list`` proof.
|
||||
|
||||
``pr_index`` (see :func:`build_pr_index`) supplies the authoritative PR
|
||||
ownership used to link issue worktrees to their merged PR (#858).
|
||||
``master_ref`` is the ref a worktree head must be contained in before it
|
||||
can be considered landed. Both are optional and their absence only ever
|
||||
fails closed: without them no issue worktree becomes removable.
|
||||
"""
|
||||
open_pr_branches = open_pr_branches or set()
|
||||
leased_branches = leased_branches or set()
|
||||
active_issue_branches = active_issue_branches or set()
|
||||
leased_issue_numbers = leased_issue_numbers or set()
|
||||
live_session_paths = {
|
||||
os.path.abspath(p) for p in (live_session_paths or set()) if p
|
||||
}
|
||||
|
||||
worktrees: list[dict[str, Any]] = []
|
||||
for entry in list_worktrees(project_root):
|
||||
@@ -433,12 +665,42 @@ def audit_branches_directory(
|
||||
)
|
||||
dirty_state = read_worktree_dirty(path)
|
||||
is_dirty = bool(dirty_state.get("dirty"))
|
||||
head_sha = entry.get("head")
|
||||
linkage = resolve_owning_pr(branch=branch, pr_index=pr_index)
|
||||
metadata = build_worktree_metadata(
|
||||
path=path, branch=branch, head_sha=entry.get("head")
|
||||
path=path,
|
||||
branch=branch,
|
||||
head_sha=head_sha,
|
||||
pr_number=linkage.get("pr_number"),
|
||||
)
|
||||
has_open_pr = bool(branch) and branch in open_pr_branches
|
||||
has_active_lease = bool(branch) and branch in leased_branches
|
||||
# A lease on issue N protects that issue's own work worktree. It must
|
||||
# not incidentally protect a baseline/review scratch tree that merely
|
||||
# carries the same issue marker in its name, which would change the
|
||||
# classification of worktrees this policy does not own.
|
||||
has_active_lease = (bool(branch) and branch in leased_branches) or (
|
||||
metadata["workflow_type"] == WORKFLOW_ISSUE_WORK
|
||||
and metadata.get("issue_number") is not None
|
||||
and metadata["issue_number"] in leased_issue_numbers
|
||||
)
|
||||
has_active_lock = bool(branch) and branch in active_issue_branches
|
||||
has_live_session = bool(path) and os.path.abspath(path) in live_session_paths
|
||||
head_in_master = (
|
||||
head_contained_in_ref(project_root, head_sha, master_ref)
|
||||
if master_ref
|
||||
else None
|
||||
)
|
||||
merged_pr_cleanup = assess_merged_pr_worktree_cleanup(
|
||||
linkage=linkage,
|
||||
head_sha=head_sha,
|
||||
head_in_master=head_in_master,
|
||||
is_dirty=is_dirty,
|
||||
has_open_pr=has_open_pr,
|
||||
has_active_lease=has_active_lease,
|
||||
has_active_issue_lock=has_active_lock,
|
||||
is_protected=is_protected,
|
||||
has_live_session=has_live_session,
|
||||
)
|
||||
ttl_expired = is_ttl_expired(
|
||||
last_used_at=metadata.get("last_used_at"), now=now, ttl_hours=ttl_hours
|
||||
)
|
||||
@@ -452,6 +714,8 @@ def audit_branches_directory(
|
||||
branch_gone=branch is None and not entry.get("detached"),
|
||||
ttl_expired=ttl_expired,
|
||||
is_protected=is_protected,
|
||||
merged_pr_cleanup=merged_pr_cleanup,
|
||||
has_live_session=has_live_session,
|
||||
)
|
||||
metadata["cleanup_eligibility"] = classification
|
||||
worktrees.append(
|
||||
@@ -463,7 +727,10 @@ def audit_branches_directory(
|
||||
"has_open_pr": has_open_pr,
|
||||
"has_active_lease": has_active_lease,
|
||||
"has_active_issue_lock": has_active_lock,
|
||||
"has_live_session": has_live_session,
|
||||
"is_protected": is_protected,
|
||||
"merged_pr_linkage": linkage,
|
||||
"merged_pr_cleanup": merged_pr_cleanup,
|
||||
"classification": classification,
|
||||
"removable": is_removable(classification),
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user