diff --git a/canonical_thread_handoff.py b/canonical_thread_handoff.py index aa0a85b..6d262c2 100644 --- a/canonical_thread_handoff.py +++ b/canonical_thread_handoff.py @@ -46,6 +46,17 @@ _FIELD_RE = re.compile( ) +def is_known_cth_type(value: str | None) -> bool: + """True when *value* is a declared member of the :data:`CTH_TYPES` contract. + + ``CTH_TYPES`` is the single authority for what a CTH type may be. The + heading a comment carries is free text, so a *read* path that turns a parsed + type into something durable — a serialized field, a routing decision — must + check membership here rather than trust the parse or keep a list of its own. + """ + return (value or "").strip() in CTH_TYPES + + def format_cth_body( *, cth_type: str, @@ -60,7 +71,7 @@ def format_cth_body( ) -> str: """Render a canonical CTH comment body.""" normalized_type = (cth_type or "").strip() - if normalized_type not in CTH_TYPES: + if not is_known_cth_type(normalized_type): raise ValueError( f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}" ) @@ -101,6 +112,12 @@ def parse_cth_comment(body: str) -> dict[str, Any] | None: fields[key] = match.group(2).strip() return { "cth_type": cth_type, + # The heading capture is unconstrained free text, so the parse states + # whether it satisfies the CTH_TYPES contract instead of leaving every + # reader to decide (or forget). Parsing stays total — an unknown type is + # still parsed and reported, never raised on — but a reader that turns + # the type into a durable value can now tell the two apart. + "cth_type_known": is_known_cth_type(cth_type), "fields": fields, "raw_body": text, } @@ -119,7 +136,7 @@ def assess_cth_comment(body: str) -> dict[str, Any]: } cth_type = parsed.get("cth_type") or "" - if cth_type not in CTH_TYPES: + if not is_known_cth_type(cth_type): reasons.append( f"unknown CTH type '{cth_type}'; expected one of {sorted(CTH_TYPES)}" ) diff --git a/docs/webui-local-dev.md b/docs/webui-local-dev.md index 33dbf61..b37d53a 100644 --- a/docs/webui-local-dev.md +++ b/docs/webui-local-dev.md @@ -74,6 +74,11 @@ status, onboarding checklist state, and the fail-closed error payloads (#635). | `/api/actions/{id}/preview` | Mutation ledger preview (GET, read-only) | | `/leases` | Lease and collision visibility (#433) | | `/api/leases` | JSON lease/collision export | +| `/sessions` | Phase 1 shell stub — session inventory (backed by #636) | +| `/inventory` | Phase 1 shell stub — unified inventory (backed by #636) | +| `/timeline` | Phase 1 shell stub — workflow event timeline | +| `/policy` | Phase 1 shell stub — capability/role policy placeholder | +| `/insights` | Phase 1 shell stub — operational insights placeholder | Most routes are GET-only. POST/PUT/PATCH/DELETE return `405` with `read-only-mvp`, except `/audit` and `/api/audit` which accept POST for @@ -233,6 +238,26 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the checkout is behind merged safety-gate changes. Restart guidance links to #420; no tokens or MCP restart actions are exposed. +## Application shell — Phase 1 (#638) + +The console shell (`webui/layout.py`) renders a grouped navigation driven by a +single nav-config module, `webui/nav.py`. Nav groups follow the epic #631 +Phase 1 information architecture: **Health, Traffic, Runtime/Sessions, +Projects, Inventory, Timeline, Policy** (placeholder), and **Insights** +(placeholder). Live views and Phase 1 placeholders (`stub`) are declared in one +place so the layout and the route table cannot drift. + +The header carries two read-only status badges — an **environment** badge +(`local` for loopback binds, `remote` otherwise, derived from `WEBUI_HOST`) and +a **mode: read-only** badge — plus a **Docs** link to this document. No +privileged action controls are present in the Phase 1 shell. + +Not-yet-implemented surfaces (`/sessions`, `/inventory`, `/timeline`, +`/policy`, `/insights`) resolve to graceful read-only stub pages instead of +404s; their backing views land in later child issues of #631 (the inventory +surfaces are backed by #636). Mutating methods on stub routes still fail closed +with `read-only-mvp`. + ## Deployment boundary (#435) MVP serves on loopback by default. Binding `0.0.0.0` or `::` is **refused** @@ -292,6 +317,108 @@ health, workflow/schema SHA-256 hashes, and stale-runtime warnings when the checkout is behind merged safety-gate changes. Restart guidance links to #420; no tokens or MCP restart actions are exposed. +## Workflow-event timeline (#637) + +`GET /api/v1/timeline` is a read-only, versioned aggregation of workflow +events from every available source into one normalised, filterable stream. It +is the model layer for the Phase 1 timeline console view (a later child issue +of #631); this issue ships the schema, adapters, and read API only. + +### Schema (versioned) + +`webui/timeline.py` declares `TIMELINE_SCHEMA_VERSION` (currently `1`) and the +frozen `WorkflowEvent` record. Every response carries `schema_version` so a +consumer can branch on shape. One event: + +```json +{ + "source": "control_plane", + "event_type": "lease.renew", + "event_key": "cp:1421", + "timestamp": "2026-07-23T02:00:00Z", + "actor": null, + "role": null, + "issue_number": 637, + "pr_number": null, + "session_id": null, + "tool_name": null, + "decision": null, + "message": "lease renewed", + "correlation_id": "issue#637", + "evidence_refs": [], + "sensitive": true +} +``` + +`event_key` is stable and unique per source (`cp:`, +`cth:::`), so pagination and dedup are deterministic. + +### Sources and field authority + +| Source | Adapter | Authority | +|---|---|---| +| Control-plane `events` ⋈ `work_items` | `adapt_cp_events` | `event_type`, `message`, `timestamp`, issue/PR scope come from the CP database, read through a `mode=ro` URI (never creates the DB or runs migrations) | +| Gitea Canonical Thread Handoff comments | `adapt_cth_comments` | `actor`, `role` (next owner), `decision`, `evidence_refs`, `timestamp` come from the parsed CTH comment body (`canonical_thread_handoff`) | + +Handoff comments are thread-scoped: they are only read when the request filters +by a single `issue` or `pr`. Otherwise the handoff source reports `not run` +with a reason — it is never rendered as empty-and-healthy. Each source degrades +independently: an unavailable control-plane DB or a failed comment fetch is a +`sources[]` entry with `ok:false` and a `reason`, never a dropped timeline. + +### Query parameters + +`issue`, `pr`, `session` (conjunctive filters); `limit` (default 50, max 500) +and `offset` for pagination; `remote`, `org`, `repo` to override the default +registry-project scope. Events sort ascending by +`(timestamp, source_rank, event_key)`; missing timestamps sort last. + +### Filter authority, and refusing what cannot be answered + +A filter dimension is only meaningful for a source whose records carry it. +Each source declares its own support in `_SOURCE_FILTER_SUPPORT` and reports it +per response as `supported_filters` / `unsupported_filters`: + +| Source | issue | pr | session | +|---|---|---|---| +| `control_plane` | yes | yes | **no** — the `events` table is `(event_id, work_item_id, event_type, message, created_at)` and records no session | +| `gitea_handoff` | yes | yes | yes — a CTH comment declares its own `Session:` field | + +`session_id` is read only from that declared CTH field. It is never inferred +from a work item, an actor, or message text, and a value that is +redaction-altering or bare-secret-shaped is dropped rather than emitted. + +When **no source that ran** can carry a requested dimension, the request is +refused rather than answered: the response is `422` with `ok:false` and a +structured `error` naming `unsupported_filters` and the per-source reason. A +`200` with zero events would tell an operator that no such activity exists, +which is a stronger — and false — claim than "this cannot be answered here". +A source that *can* answer the dimension and simply matched nothing still +returns `200` with `ok:true` and an empty page. + +### Redaction + +Every free-text field (event messages, decision/proof text, roles, actors) is +passed through the console redaction policy (`webui.console_redaction`, backed +by `gitea_audit.redact`) before it leaves the module, failing closed to the +placeholder. No unredacted tool arguments or secrets are ever emitted, and a +generation error never drops raw data to a caller or a log. + +Redaction also runs *before* any structured value is derived from free text. +`evidence_refs` are extracted from already-redacted proof/decision text, and a +commit reference is recognised only where the text declares one (`commit`, +`head`, `base`, `sha`, …). An undeclared 40-character hex run has the exact +shape of a Gitea access token, so it is never lifted out of prose into a +structured field. Every reference is then independently revalidated against an +allowed shape and a second redaction pass immediately before serialization; +anything unproven is dropped and the event is flagged `sensitive`. + +### Tests + +```bash +pytest tests/test_webui_timeline.py -q +``` + ## Tests ```bash diff --git a/gitea_mcp_server.py b/gitea_mcp_server.py index 87360bf..04edea9 100644 --- a/gitea_mcp_server.py +++ b/gitea_mcp_server.py @@ -11242,127 +11242,163 @@ def gitea_reconcile_merged_cleanups( if dry_run: report["dry_run"] = True report["executed"] = False + # #851: surface planned lifecycle order so dry-run matches execute. + report["planned_execution_orders"] = { + str(entry.get("pr_number")): entry.get("planned_execution_order") or [] + for entry in (report.get("entries") or []) + } return {"success": True, "performed": False, **report} verify_preflight_purity( remote, task="reconcile_merged_cleanups", org=org, repo=repo ) actions: list[dict] = [] + project_root = _canonical_local_git_root() + + def _ownership_records_for_branch( + head_branch: str, pr_num_int: int | None + ) -> list[dict]: + ownership_bundle = _collect_branch_ownership_records( + remote=remote, + host=h, + org=o, + repo=r, + branch=head_branch, + pr_number=pr_num_int, + project_root=project_root, + auth=auth, + base_api=base, + ) + ownership_records = list(ownership_bundle.get("records") or []) + if ownership_bundle.get("inventory_error"): + ownership_records.append( + { + "category": ( + branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR + ), + "status": "unknown", + "remote": remote, + "host": h, + "org": o, + "repo": r, + "branch": head_branch, + "reclaim_allowed": False, + "role": "inventory", + } + ) + return ownership_records + + def _attempt_owned_remote_delete( + *, + head_branch: str, + pr_num_int: int | None, + after_worktree_removal: bool = False, + ) -> dict: + """Fail-closed remote delete with live ownership reassessment (#851).""" + import urllib.parse + + ownership_records = _ownership_records_for_branch(head_branch, pr_num_int) + ownership = branch_cleanup_guard.assess_active_branch_ownership( + remote=remote, + org=o, + repo=r, + branch=head_branch, + host=h, + records=ownership_records, + ) + if ownership.get("block"): + return { + "action": "delete_remote_branch", + "branch": head_branch, + "success": False, + "performed": False, + "delete_acknowledged": False, + "verified_absent": False, + "blocker_kind": "active_branch_ownership", + "reasons": ownership.get("reasons") or [], + "blocking_categories": ownership.get("blocking_categories") or [], + "after_worktree_removal": after_worktree_removal, + "ownership_reassessed": after_worktree_removal, + } + + encoded = urllib.parse.quote(head_branch, safe="") + url = f"{base}/branches/{encoded}" + with _audited( + "delete_branch", + host=h, + remote=remote, + org=o, + repo=r, + target_branch=head_branch, + request_metadata={ + "branch": head_branch, + "source": "reconcile_merged_cleanups", + "ownership_checked": True, + "after_worktree_removal": after_worktree_removal, + }, + ): + api_request("DELETE", url, auth) + readback = _probe_remote_branch(h, o, r, auth, head_branch) + readback_assessment = branch_cleanup_guard.assess_post_delete_readback( + readback + ) + verified = bool(readback_assessment.get("verified_absent")) + return { + "action": "delete_remote_branch", + "branch": head_branch, + "success": bool(readback_assessment.get("ok")), + "performed": True, + "delete_acknowledged": True, + "verified_absent": verified, + "readback": readback_assessment.get("readback"), + "reasons": readback_assessment.get("reasons") or [], + "after_worktree_removal": after_worktree_removal, + "ownership_reassessed": after_worktree_removal, + } + for entry in report.get("entries") or []: head_branch = entry.get("head_branch") or "" remote_assessment = entry.get("remote_branch") or {} local_assessment = entry.get("local_worktree") or {} + pr_num = entry.get("pr_number") + try: + pr_num_int = int(pr_num) if pr_num is not None else None + except (TypeError, ValueError): + pr_num_int = None - if remote_assessment.get("safe_to_delete_remote"): - import urllib.parse - - pr_num = entry.get("pr_number") - try: - pr_num_int = int(pr_num) if pr_num is not None else None - except (TypeError, ValueError): - pr_num_int = None - ownership_bundle = _collect_branch_ownership_records( - remote=remote, - host=h, - org=o, - repo=r, - branch=head_branch, - pr_number=pr_num_int, - project_root=_canonical_local_git_root(), - auth=auth, - base_api=base, - ) - ownership_records = list(ownership_bundle.get("records") or []) - if ownership_bundle.get("inventory_error"): - ownership_records.append( - { - "category": ( - branch_cleanup_guard.OWNERSHIP_CATEGORY_INVENTORY_ERROR - ), - "status": "unknown", - "remote": remote, - "host": h, - "org": o, - "repo": r, - "branch": head_branch, - "reclaim_allowed": False, - "role": "inventory", - } - ) - ownership = branch_cleanup_guard.assess_active_branch_ownership( - remote=remote, - org=o, - repo=r, - branch=head_branch, - host=h, - records=ownership_records, - ) - if ownership.get("block"): - actions.append( - { - "action": "delete_remote_branch", - "branch": head_branch, - "success": False, - "performed": False, - "delete_acknowledged": False, - "verified_absent": False, - "blocker_kind": "active_branch_ownership", - "reasons": ownership.get("reasons") or [], - "blocking_categories": ownership.get( - "blocking_categories" - ) - or [], - } - ) - continue - - encoded = urllib.parse.quote(head_branch, safe="") - url = f"{base}/branches/{encoded}" - with _audited( - "delete_branch", - host=h, - remote=remote, - org=o, - repo=r, - target_branch=head_branch, - request_metadata={ - "branch": head_branch, - "source": "reconcile_merged_cleanups", - "ownership_checked": True, - }, - ): - api_request("DELETE", url, auth) - readback = _probe_remote_branch(h, o, r, auth, head_branch) - readback_assessment = branch_cleanup_guard.assess_post_delete_readback( - readback - ) - verified = bool(readback_assessment.get("verified_absent")) - actions.append( - { - "action": "delete_remote_branch", - "branch": head_branch, - "success": bool(readback_assessment.get("ok")), - "performed": True, - "delete_acknowledged": True, - "verified_absent": verified, - "readback": readback_assessment.get("readback"), - "reasons": readback_assessment.get("reasons") or [], - } - ) - + # #851 lifecycle: when the target worktree is independently safe, remove + # it first so worktree_binding ownership does not permanently strand + # both the worktree and the remote branch. Never skip worktree removal + # merely because remote delete would be blocked by that binding. + # Ownership protection for remote delete remains fail-closed below. + worktree_removed = False if local_assessment.get("safe_to_remove_worktree"): result = merged_cleanup_reconcile.remove_local_worktree( - _canonical_local_git_root(), + project_root, head_branch, worktree_path=local_assessment.get("worktree_path"), ) actions.append({"action": "remove_local_worktree", **result}) + # Idempotent resume: absent worktree is already gone. + msg = (result.get("message") or "").lower() + worktree_removed = bool(result.get("success")) or ( + "not found" in msg + ) + + if remote_assessment.get("safe_to_delete_remote"): + actions.append( + _attempt_owned_remote_delete( + head_branch=head_branch, + pr_num_int=pr_num_int, + after_worktree_removal=worktree_removed, + ) + ) for scratch in report.get("reviewer_scratch_entries") or []: if not scratch.get("safe_to_remove_worktree"): continue result = merged_cleanup_reconcile.remove_reviewer_scratch_worktree( - _canonical_local_git_root(), scratch.get("worktree_path") or "" + project_root, scratch.get("worktree_path") or "" ) actions.append({"action": "remove_reviewer_scratch_worktree", **result}) @@ -11598,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). @@ -11608,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 @@ -11654,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, } diff --git a/merged_cleanup_reconcile.py b/merged_cleanup_reconcile.py index 4a7299a..b436750 100644 --- a/merged_cleanup_reconcile.py +++ b/merged_cleanup_reconcile.py @@ -566,6 +566,10 @@ def build_pr_cleanup_entry( worktree_state=worktree_state, active_lock=active_lock, ) + planned = plan_cleanup_execution_order( + remote_assessment=remote, + local_assessment=local, + ) return { "pr_number": pr_number, "issue_number": issue_number, @@ -576,9 +580,63 @@ def build_pr_cleanup_entry( "merged": merged, "remote_branch": remote, "local_worktree": local, + # #851: dry-run and execute share the same lifecycle order description. + "planned_execution_order": planned, } +def plan_cleanup_execution_order( + *, + remote_assessment: dict[str, Any] | None, + local_assessment: dict[str, Any] | None, +) -> list[dict[str, Any]]: + """Describe independent worktree-then-reassess-then-remote cleanup order (#851). + + Remote ownership protection remains fail-closed at execute time. A worktree + that is independently safe to remove is never skipped merely because remote + deletion may be blocked by that same ``worktree_binding``. + """ + remote = remote_assessment or {} + local = local_assessment or {} + steps: list[dict[str, Any]] = [] + worktree_safe = bool(local.get("safe_to_remove_worktree")) + remote_safe = bool(remote.get("safe_to_delete_remote")) + + if worktree_safe: + steps.append( + { + "action": "remove_local_worktree", + "reason": "independently_safe_to_remove", + "phase": 1, + } + ) + if remote_safe: + if worktree_safe: + steps.append( + { + "action": "reassess_branch_ownership", + "reason": "after_worktree_removal_clear_worktree_binding", + "phase": 2, + } + ) + steps.append( + { + "action": "delete_remote_branch", + "reason": "only_if_independently_safe_after_reassessment", + "phase": 3, + } + ) + else: + steps.append( + { + "action": "delete_remote_branch", + "reason": "safe_to_delete_and_no_independent_worktree_removal", + "phase": 1, + } + ) + return steps + + def build_reconciliation_report( *, project_root: str, diff --git a/tests/test_branch_cleanup_guard.py b/tests/test_branch_cleanup_guard.py index 7a78998..0bd1fda 100644 --- a/tests/test_branch_cleanup_guard.py +++ b/tests/test_branch_cleanup_guard.py @@ -1266,6 +1266,378 @@ class TestSecondRemediationIntegration(unittest.TestCase): self.assertIn("delete_acknowledged", delete_actions[0]) self.assertTrue(delete_actions[0].get("verified_absent")) + def test_issue_851_worktree_removed_when_remote_blocked_only_by_worktree_binding(self): + """#851: remote blocked by worktree_binding must not skip safe worktree removal. + + Lifecycle: remove clean owned worktree → reassess ownership → delete + remote only if independently safe. Unrelated entries stay untouched. + """ + from mcp_server import gitea_reconcile_merged_cleanups + + target_branch = "fix/issue-844-exclude-epic-containers" + foreign_branch = "fix/issue-999-unrelated-active" + worktree_path = "/tmp/branches/fix-issue-844-exclude-epic-containers" + ownership_calls = [] + remove_calls = [] + delete_api_calls = [] + + def fake_collect(**kwargs): + ownership_calls.append(dict(kwargs)) + # Ownership is reassessed *after* independent worktree removal (#851). + # Target worktree is already gone → no worktree_binding remains. + # Foreign branch keeps an active author lease → remote delete blocked. + if kwargs.get("branch") == foreign_branch: + # Match session-bound org/repo + host used by the tool resolve path. + return { + "records": [ + { + "category": guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE, + "status": "active", + "remote": kwargs.get("remote") or "prgs", + "host": kwargs.get("host") or "gitea.example.com", + "org": kwargs.get("org") or "Scaled-Tech-Consulting", + "repo": kwargs.get("repo") or "Gitea-Tools", + "branch": foreign_branch, + "reclaim_allowed": False, + } + ], + "inventory_error": False, + } + return {"records": [], "inventory_error": False} + + def fake_remove(project_root, branch, worktree_path=None): + remove_calls.append( + {"branch": branch, "worktree_path": worktree_path} + ) + return { + "success": True, + "performed": True, + "message": f"removed worktree {worktree_path}", + "worktree_path": worktree_path, + } + + def fake_probe(h, o, r, auth, br): + return guard.classify_branch_readback_http_status( + 404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH + ) + + def fake_api(method, url, auth, **kwargs): + if method == "DELETE": + delete_api_calls.append(url) + return {} + + report = { + "entries": [ + { + "pr_number": 848, + "head_branch": target_branch, + "remote_branch": {"safe_to_delete_remote": True}, + "local_worktree": { + "safe_to_remove_worktree": True, + "worktree_path": worktree_path, + }, + }, + { + "pr_number": 999, + "head_branch": foreign_branch, + "remote_branch": {"safe_to_delete_remote": True}, + "local_worktree": { + "safe_to_remove_worktree": False, + "worktree_path": None, + }, + }, + ], + "reviewer_scratch_entries": [], + } + patch( + "mcp_server.get_profile", + return_value={ + "profile_name": "prgs-reconciler", + "role": "reconciler", + "allowed_operations": [ + "gitea.read", + "gitea.branch.delete", + "gitea.pr.close", + ], + "forbidden_operations": [], + }, + ).start() + patch("mcp_server.api_get_all", return_value=[]).start() + patch( + "mcp_server.merged_cleanup_reconcile.build_reconciliation_report", + return_value=report, + ).start() + patch( + "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees", + return_value=[], + ).start() + patch( + "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed", + return_value=(True, []), + ).start() + patch("mcp_server.verify_preflight_purity", return_value=None).start() + patch( + "mcp_server._collect_branch_ownership_records", + side_effect=fake_collect, + ).start() + patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start() + patch( + "mcp_server.merged_cleanup_reconcile.remove_local_worktree", + side_effect=fake_remove, + ).start() + self.mock_api.side_effect = fake_api + + res = gitea_reconcile_merged_cleanups( + dry_run=False, + execute_confirmed=True, + remote="prgs", + ) + self.assertTrue(res.get("performed") or res.get("executed")) + actions = res.get("actions") or [] + + remove_actions = [ + a for a in actions if a.get("action") == "remove_local_worktree" + ] + self.assertEqual(len(remove_actions), 1, actions) + self.assertTrue(remove_actions[0].get("success")) + self.assertEqual(remove_calls[0]["branch"], target_branch) + self.assertEqual(remove_calls[0]["worktree_path"], worktree_path) + + # Target remote delete succeeds after worktree removal + reassessment. + target_deletes = [ + a + for a in actions + if a.get("action") == "delete_remote_branch" + and a.get("branch") == target_branch + ] + self.assertEqual(len(target_deletes), 1, actions) + self.assertTrue(target_deletes[0].get("success")) + self.assertTrue(target_deletes[0].get("after_worktree_removal")) + self.assertTrue(target_deletes[0].get("ownership_reassessed")) + self.assertTrue(target_deletes[0].get("verified_absent")) + + # Foreign branch remains protected (author lease) and is not deleted. + foreign_deletes = [ + a + for a in actions + if a.get("action") == "delete_remote_branch" + and a.get("branch") == foreign_branch + ] + self.assertEqual(len(foreign_deletes), 1, actions) + self.assertFalse(foreign_deletes[0].get("success")) + self.assertEqual( + foreign_deletes[0].get("blocker_kind"), "active_branch_ownership" + ) + self.assertIn( + guard.OWNERSHIP_CATEGORY_AUTHOR_LEASE, + foreign_deletes[0].get("blocking_categories") or [], + ) + # Only the target branch should hit the DELETE API. + self.assertEqual(len(delete_api_calls), 1) + + # Ownership collected for target (post-removal) and foreign; worktree + # removal happened before target remote delete in the action log. + target_idx = next( + i + for i, a in enumerate(actions) + if a.get("action") == "remove_local_worktree" + ) + delete_idx = next( + i + for i, a in enumerate(actions) + if a.get("action") == "delete_remote_branch" + and a.get("branch") == target_branch + and a.get("success") + ) + self.assertLess(target_idx, delete_idx) + + def test_issue_851_dirty_worktree_not_removed_and_remote_stays_protected(self): + """#851: dirty/foreign worktrees remain protected; no unsafe cleanup.""" + from mcp_server import gitea_reconcile_merged_cleanups + + branch = "fix/issue-851-dirty" + remove_calls = [] + + def fake_collect(**kwargs): + return { + "records": [ + { + "category": guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING, + "status": "active", + "remote": kwargs.get("remote") or "prgs", + "host": kwargs.get("host") or "gitea.example.com", + "org": kwargs.get("org") or "Scaled-Tech-Consulting", + "repo": kwargs.get("repo") or "Gitea-Tools", + "branch": branch, + "reclaim_allowed": False, + } + ], + "inventory_error": False, + } + + report = { + "entries": [ + { + "pr_number": 851, + "head_branch": branch, + "remote_branch": {"safe_to_delete_remote": True}, + "local_worktree": { + "safe_to_remove_worktree": False, + "worktree_path": "/tmp/dirty-wt", + }, + } + ], + "reviewer_scratch_entries": [], + } + patch( + "mcp_server.get_profile", + return_value={ + "profile_name": "prgs-reconciler", + "role": "reconciler", + "allowed_operations": [ + "gitea.read", + "gitea.branch.delete", + ], + "forbidden_operations": [], + }, + ).start() + patch("mcp_server.api_get_all", return_value=[]).start() + patch( + "mcp_server.merged_cleanup_reconcile.build_reconciliation_report", + return_value=report, + ).start() + patch( + "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees", + return_value=[], + ).start() + patch( + "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed", + return_value=(True, []), + ).start() + patch("mcp_server.verify_preflight_purity", return_value=None).start() + patch( + "mcp_server._collect_branch_ownership_records", + side_effect=fake_collect, + ).start() + patch( + "mcp_server.merged_cleanup_reconcile.remove_local_worktree", + side_effect=lambda *a, **k: remove_calls.append(k) or { + "success": True, + "performed": True, + }, + ).start() + self.mock_api.side_effect = lambda *a, **k: {} + + res = gitea_reconcile_merged_cleanups( + dry_run=False, + execute_confirmed=True, + remote="prgs", + ) + actions = res.get("actions") or [] + self.assertEqual(remove_calls, []) + self.assertFalse( + any(a.get("action") == "remove_local_worktree" for a in actions) + ) + deletes = [ + a for a in actions if a.get("action") == "delete_remote_branch" + ] + self.assertEqual(len(deletes), 1) + self.assertFalse(deletes[0].get("success")) + self.assertEqual(deletes[0].get("blocker_kind"), "active_branch_ownership") + self.assertIn( + guard.OWNERSHIP_CATEGORY_WORKTREE_BINDING, + deletes[0].get("blocking_categories") or [], + ) + + def test_issue_851_idempotent_resume_when_worktree_already_absent(self): + """#851: partial failures remain resumable and idempotent.""" + from mcp_server import gitea_reconcile_merged_cleanups + + branch = "fix/issue-851-resume" + ownership_calls = [] + + def fake_collect(**kwargs): + ownership_calls.append(kwargs) + return {"records": [], "inventory_error": False} + + def fake_remove(project_root, branch, worktree_path=None): + return { + "success": False, + "performed": False, + "message": f"worktree not found: {worktree_path}", + } + + def fake_probe(h, o, r, auth, br): + return guard.classify_branch_readback_http_status( + 404, not_found_scope=guard.NOT_FOUND_SCOPE_BRANCH + ) + + report = { + "entries": [ + { + "pr_number": 851, + "head_branch": branch, + "remote_branch": {"safe_to_delete_remote": True}, + "local_worktree": { + "safe_to_remove_worktree": True, + "worktree_path": "/tmp/already-gone", + }, + } + ], + "reviewer_scratch_entries": [], + } + patch( + "mcp_server.get_profile", + return_value={ + "profile_name": "prgs-reconciler", + "role": "reconciler", + "allowed_operations": [ + "gitea.read", + "gitea.branch.delete", + ], + "forbidden_operations": [], + }, + ).start() + patch("mcp_server.api_get_all", return_value=[]).start() + patch( + "mcp_server.merged_cleanup_reconcile.build_reconciliation_report", + return_value=report, + ).start() + patch( + "mcp_server.merged_cleanup_reconcile.discover_reviewer_scratch_worktrees", + return_value=[], + ).start() + patch( + "mcp_server.audit_reconciliation_mode.check_cleanup_execution_allowed", + return_value=(True, []), + ).start() + patch("mcp_server.verify_preflight_purity", return_value=None).start() + patch( + "mcp_server._collect_branch_ownership_records", + side_effect=fake_collect, + ).start() + patch("mcp_server._probe_remote_branch", side_effect=fake_probe).start() + patch( + "mcp_server.merged_cleanup_reconcile.remove_local_worktree", + side_effect=fake_remove, + ).start() + self.mock_api.side_effect = lambda *a, **k: {} + + res = gitea_reconcile_merged_cleanups( + dry_run=False, + execute_confirmed=True, + remote="prgs", + ) + actions = res.get("actions") or [] + removes = [a for a in actions if a.get("action") == "remove_local_worktree"] + deletes = [a for a in actions if a.get("action") == "delete_remote_branch"] + self.assertEqual(len(removes), 1) + self.assertFalse(removes[0].get("success")) + self.assertEqual(len(deletes), 1) + self.assertTrue(deletes[0].get("success")) + self.assertTrue(deletes[0].get("after_worktree_removal")) + self.assertTrue(ownership_calls) + if __name__ == "__main__": diff --git a/tests/test_issue_858_audit_merged_pr_aware.py b/tests/test_issue_858_audit_merged_pr_aware.py new file mode 100644 index 0000000..3232318 --- /dev/null +++ b/tests/test_issue_858_audit_merged_pr_aware.py @@ -0,0 +1,551 @@ +"""Merged-PR awareness for the worktree cleanup audit (#858). + +Before #858 an ``issue_work`` worktree could never leave ``active_issue_work``: +the audit had no PR linkage at all (``pr_number`` was structurally ``None``) +and its only route to ``clean_stale_removable`` was a TTL derived from a +``last_used_at`` that nothing ever populated. A merged, clean, unprotected +worktree was therefore reported as active work forever, disagreeing with the +PR-scoped reconciler. + +These tests use fabricated temporary repositories and synthetic PR records +only. Nothing here removes a worktree or deletes a branch. +""" + +import os +import subprocess +import sys +import tempfile +import unittest +from unittest.mock import patch + +sys.path.insert(0, str(__import__("pathlib").Path(__file__).resolve().parent.parent)) + +import merged_cleanup_reconcile as mcr # noqa: E402 +import worktree_cleanup_audit as wca # noqa: E402 + + +MERGED_BRANCH = "feat/issue-777-timeline" +MERGED_PATH = "/repo/branches/issue-777-timeline" +HEAD_SHA = "a" * 40 + + +def _pr(number, branch, *, merged=True, sha=HEAD_SHA, state=None): + """Synthetic Gitea PR payload.""" + return { + "number": number, + "head": {"ref": branch, "sha": sha}, + "merged_at": "2026-07-24T01:00:00Z" if merged else None, + "state": state or ("closed" if merged else "open"), + } + + +def _porcelain(*entries): + out = [] + for path, branch, sha in entries: + out.append(f"worktree {path}") + out.append(f"HEAD {sha}") + if branch is None: + out.append("detached") + else: + out.append(f"branch refs/heads/{branch}") + out.append("") + return "\n".join(out) + + +class _AuditHarness(unittest.TestCase): + """Runs audit_branches_directory over a fabricated worktree listing.""" + + PORCELAIN = _porcelain( + ("/repo", "master", "f" * 40), + (MERGED_PATH, MERGED_BRANCH, HEAD_SHA), + ) + + def run_audit(self, *, dirty_paths=(), contained=True, **kwargs): + def fake_dirty(path): + if path in dirty_paths: + return {"exists": True, "dirty": True, "dirty_files": [" M x.py"]} + return {"exists": True, "dirty": False, "dirty_files": []} + + with patch.object( + wca, "list_worktrees", + return_value=wca.parse_worktree_porcelain(self.PORCELAIN), + ), patch.object( + wca, "read_worktree_dirty", side_effect=fake_dirty + ), patch.object( + wca, "git_worktree_list", return_value="(mocked)" + ), patch.object( + wca, "is_head_ancestor_of_ref", return_value=contained + ): + report = wca.audit_branches_directory("/repo", **kwargs) + return {wt["path"]: wt for wt in report["worktrees"]}, report + + def merged_audit(self, **kwargs): + kwargs.setdefault("pr_index", wca.build_pr_index([_pr(849, MERGED_BRANCH)])) + kwargs.setdefault("master_ref", "prgs/master") + return self.run_audit(**kwargs) + + +class TestMergedWorktreeBecomesRemovable(_AuditHarness): + def test_clean_merged_issue_worktree_is_linked_and_removable(self): + by_path, report = self.merged_audit() + entry = by_path[MERGED_PATH] + + self.assertEqual(entry["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE) + self.assertTrue(entry["removable"]) + self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_MERGED) + self.assertEqual(entry["merged_pr_cleanup"]["block_reasons"], []) + self.assertIn(MERGED_PATH, [c["path"] for c in report["removable_candidates"]]) + + def test_pr_number_populated_from_authoritative_linkage(self): + by_path, _ = self.merged_audit() + self.assertEqual(by_path[MERGED_PATH]["pr_number"], 849) + + def test_regression_without_pr_evidence_stays_active_issue_work(self): + """The pre-#858 behaviour, still correct when no PR state is supplied.""" + by_path, _ = self.run_audit() + entry = by_path[MERGED_PATH] + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + self.assertIsNone(entry["pr_number"]) + + +class TestProtectiveSignalsSurvive(_AuditHarness): + def test_open_pr_worktree_is_not_removable(self): + index = wca.build_pr_index([_pr(900, MERGED_BRANCH, merged=False)]) + by_path, _ = self.run_audit( + pr_index=index, + master_ref="prgs/master", + open_pr_branches={MERGED_BRANCH}, + ) + entry = by_path[MERGED_PATH] + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_OPEN_PR) + self.assertFalse(entry["removable"]) + # linkage still reports the owning PR, it just is not merge proof + self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_OPEN) + self.assertEqual(entry["pr_number"], 900) + + def test_dirty_tracked_worktree_is_not_removable(self): + by_path, _ = self.merged_audit(dirty_paths=(MERGED_PATH,)) + entry = by_path[MERGED_PATH] + self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL) + self.assertFalse(entry["removable"]) + self.assertIn( + "worktree has uncommitted changes", + entry["merged_pr_cleanup"]["block_reasons"], + ) + + def test_untracked_only_worktree_is_not_removable(self): + """``git status --porcelain`` reports untracked files as dirty too.""" + def untracked(path): + if path == MERGED_PATH: + return {"exists": True, "dirty": True, "dirty_files": ["?? scratch.txt"]} + return {"exists": True, "dirty": False, "dirty_files": []} + + with patch.object( + wca, "list_worktrees", + return_value=wca.parse_worktree_porcelain(self.PORCELAIN), + ), patch.object( + wca, "read_worktree_dirty", side_effect=untracked + ), patch.object( + wca, "git_worktree_list", return_value="(mocked)" + ), patch.object( + wca, "is_head_ancestor_of_ref", return_value=True + ): + report = wca.audit_branches_directory( + "/repo", + pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]), + master_ref="prgs/master", + ) + entry = {wt["path"]: wt for wt in report["worktrees"]}[MERGED_PATH] + self.assertEqual(entry["classification"], wca.CLASS_DIRTY_LOCAL) + self.assertFalse(entry["removable"]) + + def test_active_lease_by_issue_number_is_protective(self): + by_path, _ = self.merged_audit(leased_issue_numbers={777}) + entry = by_path[MERGED_PATH] + self.assertTrue(entry["has_active_lease"]) + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + + def test_active_lease_by_branch_is_protective(self): + by_path, _ = self.merged_audit(leased_branches={MERGED_BRANCH}) + entry = by_path[MERGED_PATH] + self.assertTrue(entry["has_active_lease"]) + self.assertFalse(entry["removable"]) + + def test_active_issue_lock_is_protective(self): + by_path, _ = self.merged_audit(active_issue_branches={MERGED_BRANCH}) + entry = by_path[MERGED_PATH] + self.assertTrue(entry["has_active_issue_lock"]) + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + + def test_live_session_worktree_is_protective(self): + by_path, _ = self.merged_audit(live_session_paths={MERGED_PATH}) + entry = by_path[MERGED_PATH] + self.assertTrue(entry["has_live_session"]) + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + + def test_head_not_contained_in_master_is_not_removable(self): + by_path, _ = self.merged_audit(contained=False) + entry = by_path[MERGED_PATH] + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + self.assertIn( + "worktree head is not contained in authoritative master " + "(unmerged commits remain)", + entry["merged_pr_cleanup"]["block_reasons"], + ) + + def test_unknown_containment_fails_closed(self): + by_path, _ = self.merged_audit(contained=None) + entry = by_path[MERGED_PATH] + self.assertFalse(entry["removable"]) + self.assertIn( + "containment of the worktree head in master is unknown", + entry["merged_pr_cleanup"]["block_reasons"], + ) + + def test_missing_master_ref_fails_closed(self): + by_path, _ = self.run_audit( + pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]) + ) + self.assertFalse(by_path[MERGED_PATH]["removable"]) + + def test_unmerged_owning_pr_is_not_removable(self): + index = wca.build_pr_index([_pr(901, MERGED_BRANCH, merged=False)]) + by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master") + entry = by_path[MERGED_PATH] + self.assertFalse(entry["removable"]) + self.assertIn( + "owning PR #901 is not merged", + entry["merged_pr_cleanup"]["block_reasons"], + ) + + def test_control_checkout_is_never_removable(self): + by_path, _ = self.merged_audit() + control = by_path["/repo"] + self.assertTrue(control["is_protected"]) + self.assertEqual(control["classification"], wca.CLASS_UNSAFE_UNKNOWN) + self.assertFalse(control["removable"]) + + def test_control_checkout_not_removable_even_if_linked_and_merged(self): + """A merged PR on the control checkout must not unlock removal.""" + porcelain = _porcelain(("/repo", MERGED_BRANCH, HEAD_SHA)) + with patch.object( + wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain) + ), patch.object( + wca, "read_worktree_dirty", + return_value={"exists": True, "dirty": False, "dirty_files": []}, + ), patch.object( + wca, "git_worktree_list", return_value="(mocked)" + ), patch.object( + wca, "is_head_ancestor_of_ref", return_value=True + ): + report = wca.audit_branches_directory( + "/repo", + pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]), + master_ref="prgs/master", + ) + entry = report["worktrees"][0] + self.assertEqual(entry["classification"], wca.CLASS_UNSAFE_UNKNOWN) + self.assertFalse(entry["removable"]) + + +class TestAmbiguousLinkageFailsClosed(_AuditHarness): + def test_competing_prs_on_one_branch_fail_closed(self): + index = wca.build_pr_index( + [_pr(849, MERGED_BRANCH), _pr(860, MERGED_BRANCH)] + ) + by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master") + entry = by_path[MERGED_PATH] + self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS) + self.assertIsNone(entry["pr_number"]) + self.assertEqual(entry["classification"], wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(entry["removable"]) + + def test_merged_plus_open_pr_on_one_branch_fails_closed(self): + index = wca.build_pr_index( + [_pr(849, MERGED_BRANCH), _pr(861, MERGED_BRANCH, merged=False)] + ) + by_path, _ = self.run_audit(pr_index=index, master_ref="prgs/master") + entry = by_path[MERGED_PATH] + self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_AMBIGUOUS) + self.assertFalse(entry["removable"]) + + def test_no_owning_pr_fails_closed(self): + by_path, _ = self.run_audit( + pr_index=wca.build_pr_index([_pr(849, "feat/other-branch")]), + master_ref="prgs/master", + ) + entry = by_path[MERGED_PATH] + self.assertEqual(entry["merged_pr_linkage"]["status"], wca.LINKAGE_NONE) + self.assertFalse(entry["removable"]) + + def test_malformed_pr_records_are_dropped_not_guessed(self): + index = wca.build_pr_index( + [ + {"number": None, "head": {"ref": MERGED_BRANCH}}, + {"number": 5, "head": {}}, + {"number": "not-an-int", "head": {"ref": MERGED_BRANCH}}, + ] + ) + self.assertEqual(index, {}) + self.assertEqual( + wca.resolve_owning_pr(branch=MERGED_BRANCH, pr_index=index)["status"], + wca.LINKAGE_NONE, + ) + + def test_detached_worktree_has_no_branch_linkage(self): + self.assertEqual( + wca.resolve_owning_pr(branch=None, pr_index={})["status"], + wca.LINKAGE_UNKNOWN, + ) + + +class TestUnrelatedClassificationsUnchanged(unittest.TestCase): + """Non-issue_work worktrees keep their pre-#858 classifications.""" + + PORCELAIN = _porcelain( + ("/repo", "master", "f" * 40), + ("/repo/branches/review-pr42", "review-pr42", "2" * 40), + ("/repo/branches/baseline-master-x", "baseline-master-x", "3" * 40), + ("/repo/branches/conflict-fix-pr50", "conflict-fix-pr50", "4" * 40), + ("/repo/branches/review-pr99", None, "5" * 40), + ) + + def _audit(self, **kwargs): + with patch.object( + wca, "list_worktrees", + return_value=wca.parse_worktree_porcelain(self.PORCELAIN), + ), patch.object( + wca, "read_worktree_dirty", + return_value={"exists": True, "dirty": False, "dirty_files": []}, + ), patch.object( + wca, "git_worktree_list", return_value="(mocked)" + ), patch.object( + wca, "is_head_ancestor_of_ref", return_value=True + ): + report = wca.audit_branches_directory("/repo", **kwargs) + return {wt["path"]: wt for wt in report["worktrees"]} + + def test_classifications_identical_with_and_without_pr_evidence(self): + without = self._audit() + with_evidence = self._audit( + pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]), + master_ref="prgs/master", + ) + self.assertEqual( + {p: e["classification"] for p, e in without.items()}, + {p: e["classification"] for p, e in with_evidence.items()}, + ) + + def test_lease_on_issue_does_not_capture_similarly_named_scratch_trees(self): + """A lease on issue 777 protects issue work, not baseline/review trees.""" + porcelain = _porcelain( + ("/repo/branches/baseline-master-issue-777", "baseline-issue-777", "7" * 40), + ("/repo/branches/issue-777-timeline", MERGED_BRANCH, HEAD_SHA), + ) + with patch.object( + wca, "list_worktrees", return_value=wca.parse_worktree_porcelain(porcelain) + ), patch.object( + wca, "read_worktree_dirty", + return_value={"exists": True, "dirty": False, "dirty_files": []}, + ), patch.object( + wca, "git_worktree_list", return_value="(mocked)" + ), patch.object( + wca, "is_head_ancestor_of_ref", return_value=True + ): + report = wca.audit_branches_directory( + "/repo", + pr_index=wca.build_pr_index([_pr(849, MERGED_BRANCH)]), + master_ref="prgs/master", + leased_issue_numbers={777}, + ) + by_path = {wt["path"]: wt for wt in report["worktrees"]} + + baseline = by_path["/repo/branches/baseline-master-issue-777"] + self.assertFalse(baseline["has_active_lease"]) + self.assertEqual(baseline["classification"], wca.CLASS_CLEAN_STALE_REMOVABLE) + + issue_work = by_path["/repo/branches/issue-777-timeline"] + self.assertTrue(issue_work["has_active_lease"]) + self.assertFalse(issue_work["removable"]) + + def test_review_and_baseline_still_removable(self): + by_path = self._audit( + pr_index=wca.build_pr_index([]), master_ref="prgs/master" + ) + self.assertEqual( + by_path["/repo/branches/review-pr42"]["classification"], + wca.CLASS_CLEAN_STALE_REMOVABLE, + ) + self.assertEqual( + by_path["/repo/branches/baseline-master-x"]["classification"], + wca.CLASS_CLEAN_STALE_REMOVABLE, + ) + self.assertEqual( + by_path["/repo/branches/review-pr99"]["classification"], + wca.CLASS_DETACHED_REVIEW_LEFTOVER, + ) + + def test_conflict_fix_ttl_behaviour_unchanged(self): + """conflict_fix still needs only TTL expiry; #858 did not touch it.""" + self.assertEqual( + wca.classify_worktree( + workflow_type=wca.WORKFLOW_CONFLICT_FIX, + is_dirty=False, + ttl_expired=True, + ), + wca.CLASS_CLEAN_STALE_REMOVABLE, + ) + self.assertEqual( + wca.classify_worktree( + workflow_type=wca.WORKFLOW_CONFLICT_FIX, + is_dirty=False, + ttl_expired=False, + ), + wca.CLASS_ACTIVE_ISSUE_WORK, + ) + + def test_issue_work_ttl_alone_no_longer_grants_removal(self): + """Age is not landing proof: TTL alone must not reclaim issue work.""" + self.assertEqual( + wca.classify_worktree( + workflow_type=wca.WORKFLOW_ISSUE_WORK, + is_dirty=False, + ttl_expired=True, + ), + wca.CLASS_ACTIVE_ISSUE_WORK, + ) + + +class TestAssessorPerformsNoDeletion(_AuditHarness): + def test_audit_never_removes_a_worktree(self): + with patch.object(wca, "remove_worktree") as removal: + self.merged_audit() + removal.assert_not_called() + + def test_audit_shells_out_to_no_destructive_git_command(self): + seen = [] + real_run = subprocess.run + + def recording_run(cmd, *args, **kwargs): + seen.append(cmd) + return real_run(["true"], *args, **kwargs) + + with patch.object(subprocess, "run", side_effect=recording_run): + wca.audit_branches_directory("/nonexistent-repo-for-audit") + + joined = [" ".join(c) if isinstance(c, list) else str(c) for c in seen] + for cmd in joined: + self.assertNotIn("worktree remove", cmd) + self.assertNotIn("branch -D", cmd) + self.assertNotIn("push", cmd) + + +class TestAgreementWithPrScopedReconciler(unittest.TestCase): + """The audit and merged_cleanup_reconcile must agree on identical input. + + Uses a real throwaway git repository so containment is computed by git + rather than asserted. Nothing outside the temporary directory is touched. + """ + + def _git(self, *args): + subprocess.run( + ["git", "-C", self.root, *args], + check=True, + capture_output=True, + text=True, + ) + + def setUp(self): + self._tmp = tempfile.TemporaryDirectory() + self.root = os.path.realpath(self._tmp.name) + self._git("init", "-b", "master", ".") + self._git("config", "user.email", "test@example.invalid") + self._git("config", "user.name", "Test") + with open(os.path.join(self.root, "seed.txt"), "w") as fh: + fh.write("seed\n") + self._git("add", "seed.txt") + self._git("commit", "-m", "seed") + + self.branch = "feat/issue-777-timeline" + self._git("checkout", "-b", self.branch) + with open(os.path.join(self.root, "feature.txt"), "w") as fh: + fh.write("feature\n") + self._git("add", "feature.txt") + self._git("commit", "-m", "feature") + self.head_sha = subprocess.run( + ["git", "-C", self.root, "rev-parse", "HEAD"], + capture_output=True, text=True, check=True, + ).stdout.strip() + self._git("checkout", "master") + self._git("merge", "--no-ff", "-m", "merge feature", self.branch) + + self.worktree = os.path.join(self.root, "branches", "issue-777-timeline") + self._git("worktree", "add", self.worktree, self.branch) + + def tearDown(self): + self._tmp.cleanup() + + def _pr_index(self): + return wca.build_pr_index( + [ + { + "number": 849, + "head": {"ref": self.branch, "sha": self.head_sha}, + "merged_at": "2026-07-24T01:00:00Z", + } + ] + ) + + def _audit_entry(self): + report = wca.audit_branches_directory( + self.root, pr_index=self._pr_index(), master_ref="master" + ) + return next(wt for wt in report["worktrees"] if wt["path"] == self.worktree) + + def _reconciler_entry(self): + return mcr.assess_local_worktree_cleanup( + pr_number=849, + head_branch=self.branch, + merged=True, + worktree_state=mcr.resolve_cleanup_worktree_state( + project_root=self.root, + head_branch=self.branch, + issue_number=777, + pr_head_sha=self.head_sha, + target_ref="master", + ), + active_lock=False, + ) + + def test_both_assessors_agree_the_worktree_is_safe(self): + audit_entry = self._audit_entry() + reconciler = self._reconciler_entry() + + self.assertTrue(reconciler["safe_to_remove_worktree"], reconciler) + self.assertTrue(audit_entry["removable"], audit_entry) + self.assertEqual(audit_entry["pr_number"], reconciler["pr_number"]) + self.assertEqual(audit_entry["merged_pr_cleanup"]["block_reasons"], []) + self.assertEqual(reconciler["block_reasons"], []) + + def test_both_assessors_agree_a_dirty_worktree_is_unsafe(self): + with open(os.path.join(self.worktree, "feature.txt"), "a") as fh: + fh.write("local edit\n") + + audit_entry = self._audit_entry() + reconciler = self._reconciler_entry() + + self.assertFalse(audit_entry["removable"]) + self.assertFalse(reconciler["safe_to_remove_worktree"]) + + def test_worktree_still_present_after_audit(self): + self._audit_entry() + self.assertTrue(os.path.isdir(self.worktree)) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_merged_cleanup_reconcile.py b/tests/test_merged_cleanup_reconcile.py index 284ad37..e9a8709 100644 --- a/tests/test_merged_cleanup_reconcile.py +++ b/tests/test_merged_cleanup_reconcile.py @@ -12,6 +12,59 @@ import merged_cleanup_reconcile as mcr # noqa: E402 class TestMergedCleanupAssessment(unittest.TestCase): + def test_issue_851_plan_order_worktree_then_reassess_then_remote(self): + """#851 dry-run plan: remove worktree, reassess ownership, then remote.""" + plan = mcr.plan_cleanup_execution_order( + remote_assessment={"safe_to_delete_remote": True}, + local_assessment={"safe_to_remove_worktree": True}, + ) + actions = [s["action"] for s in plan] + self.assertEqual( + actions, + [ + "remove_local_worktree", + "reassess_branch_ownership", + "delete_remote_branch", + ], + ) + self.assertEqual(plan[0]["phase"], 1) + self.assertEqual(plan[-1]["phase"], 3) + self.assertIn("independently_safe", plan[0]["reason"]) + self.assertIn("reassessment", plan[-1]["reason"]) + + def test_issue_851_plan_remote_only_when_worktree_not_safe(self): + plan = mcr.plan_cleanup_execution_order( + remote_assessment={"safe_to_delete_remote": True}, + local_assessment={"safe_to_remove_worktree": False}, + ) + self.assertEqual([s["action"] for s in plan], ["delete_remote_branch"]) + self.assertNotIn("reassess_branch_ownership", [s["action"] for s in plan]) + + def test_issue_851_plan_worktree_only_when_remote_not_safe(self): + plan = mcr.plan_cleanup_execution_order( + remote_assessment={"safe_to_delete_remote": False}, + local_assessment={"safe_to_remove_worktree": True}, + ) + self.assertEqual([s["action"] for s in plan], ["remove_local_worktree"]) + + def test_issue_851_entry_includes_planned_execution_order(self): + entry = mcr.build_pr_cleanup_entry( + pr={ + "number": 848, + "title": "Closes #844", + "body": "", + "merged_at": "2026-07-23T00:00:00Z", + "head": {"ref": "fix/issue-844-x", "sha": "a" * 40}, + }, + project_root="/tmp/not-a-real-root", + open_pr_heads=set(), + remote_branch_exists=True, + head_on_master=True, + delete_capability_allowed=True, + ) + self.assertIn("planned_execution_order", entry) + self.assertIsInstance(entry["planned_execution_order"], list) + def test_extract_linked_issue_from_closes(self): issue = mcr.extract_linked_issue( "feat: cleanup (Closes #269)", diff --git a/tests/test_webui_shell.py b/tests/test_webui_shell.py new file mode 100644 index 0000000..e3c117f --- /dev/null +++ b/tests/test_webui_shell.py @@ -0,0 +1,135 @@ +"""Tests for the Phase 1 operator console application shell (#638).""" +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from starlette.routing import Route +from starlette.testclient import TestClient + +from webui import layout +from webui.app import create_app +from webui.nav import NAV_GROUPS, STUB_PAGES, nav_hrefs + + +class TestShellNav(unittest.TestCase): + def setUp(self): + self.client = TestClient(create_app()) + + def test_nav_group_labels_present(self): + text = self.client.get("/").text + for group in NAV_GROUPS: + with self.subTest(group=group.label): + self.assertIn(f">{group.label}<", text) + + def test_phase1_group_labels_cover_expected_ia(self): + labels = {group.label for group in NAV_GROUPS} + for expected in ( + "Health", + "Traffic", + "Runtime/Sessions", + "Projects", + "Inventory", + "Timeline", + "Policy", + "Insights", + ): + with self.subTest(label=expected): + self.assertIn(expected, labels) + + def test_every_nav_href_resolves_to_a_get_route(self): + app = create_app() + get_paths = { + route.path + for route in app.routes + if isinstance(route, Route) and "GET" in route.methods + } + for href in nav_hrefs(): + with self.subTest(href=href): + self.assertIn(href, get_paths, f"nav href {href} has no GET route") + + def test_legacy_hrefs_still_navigable(self): + text = self.client.get("/").text + for href in ("/queue", "/projects", "/prompts", "/runtime", + "/audit", "/worktrees", "/leases", "/actions"): + with self.subTest(href=href): + self.assertIn(f'href="{href}"', text) + + +class TestShellBadges(unittest.TestCase): + def setUp(self): + self.client = TestClient(create_app()) + + def test_mode_badge_present(self): + self.assertIn("mode: read-only", self.client.get("/").text) + + def test_environment_badge_present(self): + self.assertIn("env:", self.client.get("/").text) + + def test_default_environment_is_local(self): + self.assertEqual(layout.environment_label(), "local") + + def test_remote_bind_reports_remote_environment(self): + import os + + prior = os.environ.get("WEBUI_HOST") + os.environ["WEBUI_HOST"] = "10.0.0.5" + try: + self.assertEqual(layout.environment_label(), "remote") + finally: + if prior is None: + os.environ.pop("WEBUI_HOST", None) + else: + os.environ["WEBUI_HOST"] = prior + + def test_docs_link_present(self): + text = self.client.get("/").text + self.assertIn(layout.DOCS_URL, text) + self.assertIn(">Docs<", text) + + +class TestShellStubs(unittest.TestCase): + def setUp(self): + self.client = TestClient(create_app()) + + def test_stub_routes_render_200(self): + for path, (title, _desc) in STUB_PAGES.items(): + with self.subTest(path=path): + response = self.client.get(path) + self.assertEqual(response.status_code, 200, path) + self.assertIn(title, response.text) + self.assertIn("placeholder", response.text) + + def test_stub_routes_are_read_only(self): + for path in STUB_PAGES: + with self.subTest(path=path): + response = self.client.post(path) + self.assertEqual(response.status_code, 405) + self.assertEqual(response.json()["error"], "read-only-mvp") + + def test_stub_pages_carry_nav_and_badges(self): + response = self.client.get("/inventory") + self.assertIn("mode: read-only", response.text) + self.assertIn('href="/queue"', response.text) + + +class TestShellHome(unittest.TestCase): + def setUp(self): + self.client = TestClient(create_app()) + + def test_home_summarizes_console(self): + text = self.client.get("/").text + self.assertIn("Operator console", text) + self.assertIn("Phase 1", text) + + def test_home_links_legacy_pages(self): + text = self.client.get("/").text + self.assertIn("MVP legacy pages", text) + for href in ("/queue", "/audit", "/leases"): + with self.subTest(href=href): + self.assertIn(f'href="{href}"', text) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_webui_timeline.py b/tests/test_webui_timeline.py new file mode 100644 index 0000000..39c7ea5 --- /dev/null +++ b/tests/test_webui_timeline.py @@ -0,0 +1,1021 @@ +"""Tests for the workflow-event timeline model and read API (#637). + +Covers the acceptance criteria: versioned schema, adaptation of control-plane +events and Gitea handoff comments, filter by issue/PR/session, redaction of +secret-like payloads, and stable pagination. +""" +import json +import os +import sqlite3 +import sys +import unittest +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) + +from starlette.testclient import TestClient + +import control_plane_db +from canonical_thread_handoff import ( + CTH_TYPES, + MARKER, + format_cth_body, + is_known_cth_type, + parse_cth_comment, +) +from webui import timeline +from webui.app import create_app + + +def _seed_db(path: str) -> None: + """Create a control-plane DB and seed scoped work_items + events.""" + # Constructing ControlPlaneDB runs the schema migration once. + control_plane_db.ControlPlaneDB(db_path=path) + conn = sqlite3.connect(path) + try: + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "issue", 637, "open", "2026-07-23T00:00:00Z"), + ) + issue_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("prgs", "Scaled-Tech-Consulting", "Gitea-Tools", "pr", 813, "open", "2026-07-23T00:00:00Z"), + ) + pr_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + # A work item for a different repo — must never appear in prgs/Gitea-Tools scope. + conn.execute( + "INSERT INTO work_items(remote, org, repo, kind, number, state, updated_at) " + "VALUES (?,?,?,?,?,?,?)", + ("dadeschools", "Other", "Elsewhere", "issue", 1, "open", "2026-07-23T00:00:00Z"), + ) + other_wid = conn.execute("SELECT last_insert_rowid()").fetchone()[0] + + rows = [ + (issue_wid, "allocation", "assigned author work", "2026-07-23T01:00:00Z"), + (issue_wid, "lease.renew", "token=ghs_ABCDEF1234567890abcdef lease renewed", "2026-07-23T02:00:00Z"), + (pr_wid, "pr.opened", "PR opened for review", "2026-07-23T03:00:00Z"), + (other_wid, "allocation", "off-scope event", "2026-07-23T04:00:00Z"), + ] + conn.executemany( + "INSERT INTO events(work_item_id, event_type, message, created_at) VALUES (?,?,?,?)", + rows, + ) + conn.commit() + finally: + conn.close() + + +class TestSchema(unittest.TestCase): + def test_schema_is_versioned(self): + self.assertIsInstance(timeline.TIMELINE_SCHEMA_VERSION, int) + self.assertGreaterEqual(timeline.TIMELINE_SCHEMA_VERSION, 1) + + def test_event_to_dict_shape(self): + ev = timeline.WorkflowEvent( + source=timeline.SOURCE_CONTROL_PLANE, + event_type="allocation", + event_key="cp:1", + timestamp="2026-07-23T01:00:00Z", + issue_number=637, + ) + d = ev.to_dict() + for key in ( + "source", "event_type", "event_key", "timestamp", "actor", "role", + "issue_number", "pr_number", "session_id", "tool_name", "decision", + "message", "correlation_id", "evidence_refs", "sensitive", + ): + self.assertIn(key, d) + self.assertEqual(d["evidence_refs"], []) + + +class TestCpAdapter(unittest.TestCase): + def test_issue_and_pr_mapping(self): + rows = [ + {"event_id": 1, "event_type": "allocation", "message": "x", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 637}, + {"event_id": 2, "event_type": "pr.opened", "message": "y", "created_at": "2026-07-23T02:00:00Z", "kind": "pr", "number": 813}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 2) + self.assertEqual(events[0].issue_number, 637) + self.assertIsNone(events[0].pr_number) + self.assertEqual(events[0].correlation_id, "issue#637") + self.assertIsNone(events[1].issue_number) + self.assertEqual(events[1].pr_number, 813) + + def test_malformed_rows_skipped(self): + rows = [ + {"event_id": None, "event_type": "x", "kind": "issue", "number": 1}, + {"event_id": 5, "event_type": "", "kind": "issue", "number": 1}, + {"event_id": 6, "event_type": "ok", "message": "m", "created_at": None, "kind": "issue", "number": 1}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 1) + self.assertIsNone(events[0].timestamp) + + def test_sensitive_event_flagged(self): + rows = [{"event_id": 1, "event_type": "lease.renew", "message": "m", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}] + events = timeline.adapt_cp_events(rows) + self.assertTrue(events[0].sensitive) + + +class TestCthAdapter(unittest.TestCase): + def test_cth_comment_becomes_event(self): + body = format_cth_body( + cth_type="Author Handoff", + status="ready", + next_owner="reviewer", + decision="implement timeline", + proof="commit abc1234 closes #637", + next_action="review PR", + ready_to_paste_prompt="Review PR #900 as reviewer", + ) + comments = [{"id": 42, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "jcwalker3"}}] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + ev = events[0] + self.assertEqual(ev.source, timeline.SOURCE_GITEA_HANDOFF) + self.assertEqual(ev.event_type, "handoff:Author Handoff") + self.assertEqual(ev.actor, "jcwalker3") + self.assertEqual(ev.issue_number, 637) + self.assertEqual(ev.event_key, "cth:issue:637:42") + self.assertIn("#637", ev.evidence_refs) + self.assertIn("abc1234", ev.evidence_refs) + + def test_non_cth_comment_ignored(self): + comments = [{"id": 1, "body": "just a normal comment", "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}] + self.assertEqual(timeline.adapt_cth_comments(comments, kind="issue", number=1), []) + + +class TestRedaction(unittest.TestCase): + def test_cp_message_redacted(self): + rows = [{"event_id": 1, "event_type": "lease", "message": "token=ghs_ABCDEF1234567890abcdef here", "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 1}] + events = timeline.adapt_cp_events(rows) + self.assertNotIn("ghs_ABCDEF1234567890abcdef", events[0].message or "") + + def test_handoff_decision_redacted(self): + body = format_cth_body( + cth_type="Blocker", + status="blocked", + next_owner="author", + decision="password=SuperSecret123! must rotate", + proof="none", + next_action="rotate", + ready_to_paste_prompt="Rotate the credential and retry", + ) + comments = [{"id": 7, "body": body, "created_at": "2026-07-23T05:00:00Z", "user": {"login": "x"}}] + events = timeline.adapt_cth_comments(comments, kind="issue", number=1) + self.assertNotIn("SuperSecret123!", events[0].decision or "") + + +class TestFilterSortPaginate(unittest.TestCase): + def _events(self): + return [ + timeline.WorkflowEvent(source="control_plane", event_type="a", event_key="cp:3", timestamp="2026-07-23T03:00:00Z", pr_number=813), + timeline.WorkflowEvent(source="control_plane", event_type="b", event_key="cp:1", timestamp="2026-07-23T01:00:00Z", issue_number=637), + timeline.WorkflowEvent(source="control_plane", event_type="c", event_key="cp:2", timestamp="2026-07-23T02:00:00Z", issue_number=637, session_id="sess-1"), + ] + + def test_filter_by_issue(self): + out = timeline.filter_events(self._events(), issue=637) + self.assertEqual({e.event_key for e in out}, {"cp:1", "cp:2"}) + + def test_filter_by_pr(self): + out = timeline.filter_events(self._events(), pr=813) + self.assertEqual([e.event_key for e in out], ["cp:3"]) + + def test_filter_by_session(self): + out = timeline.filter_events(self._events(), session="sess-1") + self.assertEqual([e.event_key for e in out], ["cp:2"]) + + def test_stable_sort_ascending(self): + out = timeline.sort_events(self._events()) + self.assertEqual([e.event_key for e in out], ["cp:1", "cp:2", "cp:3"]) + + def test_missing_timestamp_sorts_last(self): + evs = self._events() + [ + timeline.WorkflowEvent(source="control_plane", event_type="z", event_key="cp:9", timestamp=None) + ] + out = timeline.sort_events(evs) + self.assertEqual(out[-1].event_key, "cp:9") + + def test_pagination_windows_and_next_offset(self): + evs = timeline.sort_events(self._events()) + page1 = timeline.paginate(evs, limit=2, offset=0) + self.assertEqual(len(page1.events), 2) + self.assertEqual(page1.total, 3) + self.assertEqual(page1.next_offset, 2) + page2 = timeline.paginate(evs, limit=2, offset=2) + self.assertEqual(len(page2.events), 1) + self.assertIsNone(page2.next_offset) + + def test_pagination_bounds_coerced(self): + evs = self._events() + page = timeline.paginate(evs, limit=-5, offset=-3) + self.assertGreaterEqual(page.limit, 1) + self.assertEqual(page.offset, 0) + + +class TestCpReader(unittest.TestCase): + def test_reads_scoped_events_only(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + events, status = timeline.read_cp_events( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db + ) + self.assertTrue(status.ok) + # 3 scoped events; the dadeschools/Other event is excluded. + self.assertEqual(len(events), 3) + self.assertTrue(all(e.source == "control_plane" for e in events)) + # Redaction applied to the token-bearing message. + joined = " ".join(e.message or "" for e in events) + self.assertNotIn("ghs_ABCDEF1234567890abcdef", joined) + + def test_missing_db_degrades(self): + events, status = timeline.read_cp_events( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + db_path="/nonexistent/path/to/cp.sqlite3", + ) + self.assertEqual(events, []) + self.assertFalse(status.ok) + self.assertIsNotNone(status.reason) + + +class TestLoadTimeline(unittest.TestCase): + def test_handoff_not_run_without_thread_filter(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", db_path=db + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertFalse(handoff["ok"]) + self.assertIn("thread-scoped", handoff["reason"]) + self.assertEqual(d["schema_version"], timeline.TIMELINE_SCHEMA_VERSION) + + def test_handoff_included_via_injected_source(self): + import tempfile + + body = format_cth_body( + cth_type="Author Handoff", status="ready", next_owner="reviewer", + decision="d", proof="#637", next_action="review", ready_to_paste_prompt="Review PR #1 now", + ) + + def source(kind, number): + return [{"id": 1, "body": body, "created_at": "2026-07-23T09:00:00Z", "user": {"login": "jcwalker3"}}] + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=source, + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertTrue(handoff["ok"]) + self.assertEqual(handoff["count"], 1) + # Both a CP event and the handoff event for issue 637 appear, sorted. + kinds = {e["source"] for e in d["events"]} + self.assertEqual(kinds, {"control_plane", "gitea_handoff"}) + + def test_failing_comment_source_degrades_only_handoff(self): + import tempfile + + def boom(kind, number): + raise RuntimeError("network down") + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=boom, + ) + d = snap.to_dict() + cp = [s for s in d["sources"] if s["name"] == "control_plane"][0] + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertTrue(cp["ok"]) + self.assertFalse(handoff["ok"]) + self.assertIn("network down", handoff["reason"]) + + +# A fabricated 40-character lowercase hex value with the shape of a Gitea +# personal access token. Never a real credential — its only job is to prove it +# cannot reach any part of a serialized timeline payload. +SYNTHETIC_SECRET_40_HEX = "a3f9c17be44d2058e6b17c9d0f5321ab77c4e9d1" + + +def _cth_comment(comment_id, *, created_at, session=None, decision="d", proof="none", **kw): + """Build one real CTH comment record, optionally declaring a session.""" + extra = {"Session": session} if session is not None else None + body = format_cth_body( + cth_type=kw.pop("cth_type", "Author Handoff"), + status=kw.pop("status", "ready"), + next_owner=kw.pop("next_owner", "reviewer"), + decision=decision, + proof=proof, + next_action=kw.pop("next_action", "review"), + ready_to_paste_prompt=kw.pop("ready_to_paste_prompt", "Review PR #1 now"), + extra_fields=extra, + ) + return { + "id": comment_id, + "body": body, + "created_at": created_at, + "user": {"login": kw.pop("login", "jcwalker3")}, + } + + +class TestSessionFilterThroughAdapter(unittest.TestCase): + """F1: the session dimension must be real, or explicitly refused. + + These drive the filter through the CTH adapter and the composed + ``load_timeline``/API path, never through a hand-built ``WorkflowEvent``. + """ + + def _source(self, comments): + return lambda kind, number: list(comments) + + def test_adapter_populates_declared_session(self): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", session="sess-alpha")], + kind="issue", + number=637, + ) + self.assertEqual(len(events), 1) + self.assertEqual(events[0].session_id, "sess-alpha") + + def test_session_filter_matches_through_adapter(self): + import tempfile + + comments = [ + _cth_comment(1, created_at="2026-07-23T09:00:00Z", session="sess-alpha"), + _cth_comment(2, created_at="2026-07-23T08:00:00Z", session="sess-alpha"), + _cth_comment(3, created_at="2026-07-23T10:00:00Z", session="sess-beta"), + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source(comments), + ) + d = snap.to_dict() + self.assertTrue(d["ok"]) + self.assertIsNone(d["error"]) + keys = [e["event_key"] for e in d["events"]] + # Only the two sess-alpha events, still in ascending timestamp order. + self.assertEqual(keys, ["cth:issue:637:2", "cth:issue:637:1"]) + self.assertTrue(all(e["session_id"] == "sess-alpha" for e in d["events"])) + self.assertEqual(d["pagination"]["total"], 2) + + def test_session_filter_paginates_and_keeps_order(self): + import tempfile + + comments = [ + _cth_comment(i, created_at=f"2026-07-23T0{i}:00:00Z", session="sess-alpha") + for i in range(1, 4) + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + kwargs = dict( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source(comments), + ) + page1 = timeline.load_timeline(limit=2, offset=0, **kwargs).to_dict() + page2 = timeline.load_timeline(limit=2, offset=2, **kwargs).to_dict() + self.assertEqual( + [e["event_key"] for e in page1["events"]], + ["cth:issue:637:1", "cth:issue:637:2"], + ) + self.assertEqual(page1["pagination"]["next_offset"], 2) + self.assertEqual([e["event_key"] for e in page2["events"]], ["cth:issue:637:3"]) + self.assertIsNone(page2["pagination"]["next_offset"]) + + def test_unknown_session_is_honestly_empty_when_supported(self): + """A source that *can* answer the dimension may legitimately match nothing.""" + import tempfile + + comments = [_cth_comment(1, created_at="2026-07-23T09:00:00Z", session="sess-alpha")] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-nope", db_path=db, + comment_source=self._source(comments), + ).to_dict() + self.assertTrue(d["ok"]) + self.assertEqual(d["events"], []) + + def test_session_filter_refused_when_no_source_can_answer(self): + """The F1 defect: an empty-and-healthy page for an unanswerable filter.""" + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, comment_source=None, + ).to_dict() + self.assertFalse(d["ok"]) + self.assertEqual(d["error"]["code"], "filter_not_supported") + self.assertEqual(d["error"]["unsupported_filters"], ["session"]) + self.assertEqual(d["events"], []) + self.assertEqual(d["pagination"]["total"], 0) + # The refusal states which source could not answer, and why. + explained = {r["source"] for r in d["error"]["sources"]} + self.assertEqual(explained, {"control_plane", "gitea_handoff"}) + + def test_control_plane_declares_session_unsupported(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session="sess-alpha", db_path=db, + comment_source=self._source([]), + ).to_dict() + cp = [s for s in d["sources"] if s["name"] == "control_plane"][0] + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertNotIn("session", cp["supported_filters"]) + self.assertEqual(cp["unsupported_filters"], ["session"]) + self.assertIn("session", handoff["supported_filters"]) + self.assertEqual(handoff["unsupported_filters"], []) + + def test_secret_shaped_session_value_is_dropped(self): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", session=SYNTHETIC_SECRET_40_HEX)], + kind="issue", + number=637, + ) + self.assertIsNone(events[0].session_id) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(events[0].to_dict())) + + +class TestEvidenceRefRedaction(unittest.TestCase): + """F2: evidence_refs must not be a hole in the redaction boundary.""" + + def _refs_for(self, *, proof="none", decision="d"): + events = timeline.adapt_cth_comments( + [_cth_comment(1, created_at="2026-07-23T05:00:00Z", proof=proof, decision=decision)], + kind="issue", + number=637, + ) + self.assertEqual(len(events), 1) + return events[0] + + def test_assigned_secret_never_reaches_evidence_refs(self): + ev = self._refs_for(proof=f"authenticated with token={SYNTHETIC_SECRET_40_HEX}") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.evidence_refs) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_bare_secret_shaped_value_never_reaches_evidence_refs(self): + # An undeclared hex run in proof text is not evidence of anything, and + # proof itself is never serialized — so the value has no way out. + ev = self._refs_for(proof=f"proof {SYNTHETIC_SECRET_40_HEX}", decision="rotate the credential") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.evidence_refs) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_secret_absent_from_complete_serialized_payload(self): + import tempfile + + comments = [ + _cth_comment( + 1, + created_at="2026-07-23T09:00:00Z", + proof=f"lease token={SYNTHETIC_SECRET_40_HEX} and bare {SYNTHETIC_SECRET_40_HEX}", + decision=f"rotate api_key={SYNTHETIC_SECRET_40_HEX}", + ) + ] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + payload = json.dumps(snap.to_dict()) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, payload) + # And the surface is clean by the redaction policy's own detectors. + from webui import console_redaction + + self.assertEqual(console_redaction.scan_for_secrets(snap.to_dict()), []) + + def test_legitimate_references_still_usable(self): + head = "4f3a464a1c455b6ecaaae9b6eef496c8f8ed451a" + ev = self._refs_for( + proof=f"closes #637, PR #849, commit abc1234, at head {head}", + decision="none", + ) + for token in ("#637", "#849", "abc1234", head): + self.assertIn(token, ev.evidence_refs) + + def test_undeclared_hex_words_are_not_references(self): + ev = self._refs_for(proof="the record was defaced and the facade decayed") + self.assertEqual(ev.evidence_refs, ()) + + def test_refs_revalidated_independently_before_serialization(self): + """Extraction is not trusted: the validator drops anything unproven.""" + safe, dropped = timeline._validated_evidence_refs( + ["#637", "abc1234", "not-a-ref", f"token={SYNTHETIC_SECRET_40_HEX}", ""] + ) + self.assertEqual(safe, ("#637", "abc1234")) + self.assertTrue(dropped) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(list(safe))) + + def test_clean_event_is_not_marked_sensitive(self): + ev = self._refs_for(proof="closes #637") + self.assertEqual(ev.evidence_refs, ("#637",)) + self.assertFalse(ev.sensitive) + + +class TestTimelineApi(unittest.TestCase): + def setUp(self): + self._prev_db = os.environ.get(control_plane_db.DB_PATH_ENV) + self._prev_offline = os.environ.get("WEBUI_TEST_OFFLINE") + import tempfile + + self._tmpdir = tempfile.TemporaryDirectory() + self._db = os.path.join(self._tmpdir.name, "cp.sqlite3") + _seed_db(self._db) + os.environ[control_plane_db.DB_PATH_ENV] = self._db + os.environ["WEBUI_TEST_OFFLINE"] = "1" + self.client = TestClient(create_app()) + + def tearDown(self): + if self._prev_db is None: + os.environ.pop(control_plane_db.DB_PATH_ENV, None) + else: + os.environ[control_plane_db.DB_PATH_ENV] = self._prev_db + if self._prev_offline is None: + os.environ.pop("WEBUI_TEST_OFFLINE", None) + else: + os.environ["WEBUI_TEST_OFFLINE"] = self._prev_offline + self._tmpdir.cleanup() + + def test_api_returns_timeline(self): + resp = self.client.get("/api/v1/timeline") + self.assertEqual(resp.status_code, 200) + body = resp.json() + self.assertEqual(body["schema_version"], timeline.TIMELINE_SCHEMA_VERSION) + self.assertIn("events", body) + self.assertIn("pagination", body) + self.assertGreaterEqual(body["pagination"]["total"], 1) + + def test_api_filter_by_issue(self): + resp = self.client.get("/api/v1/timeline?issue=637") + self.assertEqual(resp.status_code, 200) + events = resp.json()["events"] + self.assertTrue(events) + self.assertTrue(all(e["issue_number"] == 637 for e in events)) + + def test_api_pagination(self): + resp = self.client.get("/api/v1/timeline?limit=1&offset=0") + self.assertEqual(resp.status_code, 200) + pg = resp.json()["pagination"] + self.assertEqual(pg["limit"], 1) + self.assertEqual(len(resp.json()["events"]), 1) + if pg["total"] > 1: + self.assertTrue(pg["has_more"]) + + def test_api_is_read_only(self): + resp = self.client.post("/api/v1/timeline") + self.assertIn(resp.status_code, (404, 405)) + + def test_api_no_secret_leak(self): + resp = self.client.get("/api/v1/timeline?issue=637") + self.assertNotIn("ghs_ABCDEF1234567890abcdef", resp.text) + + def test_api_refuses_unanswerable_session_filter(self): + """No handoff source is configured offline, so nothing can carry a session.""" + resp = self.client.get("/api/v1/timeline?issue=637&session=sess-alpha") + self.assertEqual(resp.status_code, 422) + body = resp.json() + self.assertFalse(body["ok"]) + self.assertEqual(body["error"]["code"], "filter_not_supported") + self.assertEqual(body["error"]["unsupported_filters"], ["session"]) + self.assertEqual(body["events"], []) + self.assertEqual(body["pagination"]["total"], 0) + + def test_api_unfiltered_read_stays_ok(self): + body = self.client.get("/api/v1/timeline?issue=637").json() + self.assertTrue(body["ok"]) + self.assertIsNone(body["error"]) + + +def _seed_event(path: str, *, event_type: str, message: str, created_at: str) -> None: + """Append one control-plane event with a caller-chosen ``event_type``. + + The ``events`` table stores whatever a producer writes, so this seeds the + adapter the way a hostile or buggy producer would. + """ + conn = sqlite3.connect(path) + try: + wid = conn.execute( + "SELECT work_item_id FROM work_items WHERE kind='issue' AND number=637" + ).fetchone()[0] + conn.execute( + "INSERT INTO events(work_item_id, event_type, message, created_at) VALUES (?,?,?,?)", + (wid, event_type, message, created_at), + ) + conn.commit() + finally: + conn.close() + + +def _raw_cth_body(heading: str, **fields) -> str: + """Build a CTH comment with an arbitrary heading. + + ``format_cth_body`` refuses an undeclared type, which is exactly the write + path already covered. The read path must cope with a body that never went + through it, so this writes the marker and heading directly. + """ + lines = [MARKER, f"## CTH: {heading}", ""] + base = { + "Status": "ready", + "Next owner": "reviewer", + "Current blocker": "none", + "Decision": "d", + "Proof": "none", + "Next action": "review", + "Ready-to-paste prompt": "Review PR #1 now", + } + base.update(fields) + lines.extend(f"{key}: {value}" for key, value in base.items()) + return "\n".join(lines) + + +class TestEventTypeBoundary(unittest.TestCase): + """F2 residual: event_type must cross the same boundary as every other field. + + The canary is seeded through ``event_type`` *only*, with a benign message, + so message redaction cannot be what makes these pass. Each case inspects + ``event_type`` explicitly and then the complete serialized payload. + """ + + # ---- control-plane stored event_type ---------------------------------- # + + def test_cp_event_type_canary_never_serialized(self): + rows = [{ + "event_id": 1, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": "deploy completed", # benign: no redaction happens here + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + events = timeline.adapt_cp_events(rows) + self.assertEqual(len(events), 1) + ev = events[0] + # The field itself, inspected directly. + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertEqual(ev.event_type, timeline.UNSAFE_EVENT_TYPE) + # Message redaction is provably not what saved us: it is untouched. + self.assertEqual(ev.message, "deploy completed") + # And nowhere in the serialized record. + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + # An unsafe value is a visible fact, not a silent substitution. + self.assertTrue(ev.sensitive) + + def test_cp_same_canary_in_message_and_event_type(self): + """The decisive case: one record, one value, two fields, one verdict.""" + rows = [{ + "event_id": 2, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": f"deploy token={SYNTHETIC_SECRET_40_HEX}", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.message or "") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cp_unsafe_event_type_is_not_rewritten_as_a_valid_one(self): + """A refused value must not be disguised as some other real event type.""" + rows = [{ + "event_id": 3, + "event_type": SYNTHETIC_SECRET_40_HEX, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + for legitimate in ("allocation", "pr.opened", "lease.renew", "assigned"): + self.assertNotEqual(ev.event_type, legitimate) + + def test_cp_assigned_secret_in_event_type_refused(self): + rows = [{ + "event_id": 4, + "event_type": f"token={SYNTHETIC_SECRET_40_HEX}", + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + ev = timeline.adapt_cp_events(rows)[0] + self.assertEqual(ev.event_type, timeline.UNSAFE_EVENT_TYPE) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cp_legitimate_event_types_preserved(self): + """Every real producer type in this repo must survive untouched.""" + legitimate = [ + "allocation", "pr.opened", "lease.renew", "assigned", + "lease_released", "lease_expired", "lease_abandoned", + "lease_adopted", "dependency_edge_state_change", + ] + rows = [ + { + "event_id": i, + "event_type": name, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + } + for i, name in enumerate(legitimate, start=1) + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual([e.event_type for e in events], legitimate) + + def test_cp_malformed_event_type_shapes_refused(self): + for bad in ("has space", "1leading-digit", "x" * 200, "semi;colon", "new\nline"): + with self.subTest(event_type=bad): + rows = [{ + "event_id": 1, + "event_type": bad, + "message": "m", + "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", + "number": 637, + }] + events = timeline.adapt_cp_events(rows) + self.assertEqual(events[0].event_type, timeline.UNSAFE_EVENT_TYPE) + self.assertNotIn(bad, json.dumps(events[0].to_dict())) + + # ---- CTH heading event_type ------------------------------------------- # + + def test_cth_heading_canary_never_serialized(self): + comments = [{ + "id": 11, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "jcwalker3"}, + }] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + ev = events[0] + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, ev.event_type) + self.assertEqual(ev.event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + # No message redaction is doing the work here — the message is benign. + self.assertEqual(ev.message, "review") + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + self.assertTrue(ev.sensitive) + + def test_cth_assigned_secret_heading_refused(self): + comments = [{ + "id": 12, + "body": _raw_cth_body(f"token={SYNTHETIC_SECRET_40_HEX}"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "jcwalker3"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(ev.to_dict())) + + def test_cth_unknown_and_whitespace_headings_normalized(self): + for heading in ("Totally Made Up", "Author Handoff", "author handoff"): + with self.subTest(heading=heading): + comments = [{ + "id": 13, + "body": _raw_cth_body(heading), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + events = timeline.adapt_cth_comments(comments, kind="issue", number=637) + self.assertEqual(len(events), 1) + self.assertEqual(events[0].event_type, timeline.UNKNOWN_HANDOFF_EVENT_TYPE) + + def test_cth_declared_types_all_preserved(self): + """Point 5: no legitimate declared type is lost to the new check.""" + for cth_type in sorted(CTH_TYPES): + with self.subTest(cth_type=cth_type): + comments = [{ + "id": 14, + "body": _raw_cth_body(cth_type), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, f"handoff:{cth_type}") + self.assertFalse(ev.sensitive) + + def test_cth_surrounding_whitespace_still_matches_contract(self): + comments = [{ + "id": 15, + "body": _raw_cth_body(" Author Handoff "), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + ev = timeline.adapt_cth_comments(comments, kind="issue", number=637)[0] + self.assertEqual(ev.event_type, "handoff:Author Handoff") + + # ---- complete serialized payload, both paths -------------------------- # + + def _payload_clean(self, snapshot): + payload = json.dumps(snapshot.to_dict()) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, payload) + from webui import console_redaction + + self.assertEqual(console_redaction.scan_for_secrets(snapshot.to_dict()), []) + return snapshot.to_dict() + + def test_canary_absent_from_full_payload_via_cp_event_type(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + _seed_event( + db, + event_type=SYNTHETIC_SECRET_40_HEX, + message="routine deploy", + created_at="2026-07-23T06:00:00Z", + ) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: [], + ) + d = self._payload_clean(snap) + types = [e["event_type"] for e in d["events"]] + self.assertIn(timeline.UNSAFE_EVENT_TYPE, types) + # The legitimate seeded types are still present and unchanged. + self.assertIn("allocation", types) + + def test_canary_absent_from_full_payload_via_cth_heading(self): + import tempfile + + comments = [{ + "id": 21, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T09:00:00Z", + "user": {"login": "jcwalker3"}, + }] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + d = self._payload_clean(snap) + self.assertIn( + timeline.UNKNOWN_HANDOFF_EVENT_TYPE, + [e["event_type"] for e in d["events"]], + ) + + def test_canary_absent_when_seeded_through_both_paths_at_once(self): + import tempfile + + comments = [{ + "id": 22, + "body": _raw_cth_body(SYNTHETIC_SECRET_40_HEX), + "created_at": "2026-07-23T09:00:00Z", + "user": {"login": "jcwalker3"}, + }] + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + _seed_event( + db, + event_type=SYNTHETIC_SECRET_40_HEX, + message=f"deploy token={SYNTHETIC_SECRET_40_HEX}", + created_at="2026-07-23T06:00:00Z", + ) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=lambda k, n: comments, + ) + self._payload_clean(snap) + + +class TestSerializedFieldAudit(unittest.TestCase): + """The remaining externally influenced strings that reach the payload.""" + + def test_event_key_ids_must_be_plain_identifiers(self): + rows = [ + {"event_id": SYNTHETIC_SECRET_40_HEX, "event_type": "allocation", + "message": "m", "created_at": "2026-07-23T01:00:00Z", + "kind": "issue", "number": 637}, + {"event_id": 8, "event_type": "allocation", "message": "m", + "created_at": "2026-07-23T01:00:00Z", "kind": "issue", "number": 637}, + ] + events = timeline.adapt_cp_events(rows) + self.assertEqual([e.event_key for e in events], ["cp:8"]) + + def test_comment_id_must_be_a_plain_identifier(self): + comments = [{ + "id": SYNTHETIC_SECRET_40_HEX, + "body": _raw_cth_body("Author Handoff"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + self.assertEqual(timeline.adapt_cth_comments(comments, kind="issue", number=637), []) + + def test_adapter_refuses_a_scope_it_cannot_express(self): + comments = [{ + "id": 1, + "body": _raw_cth_body("Author Handoff"), + "created_at": "2026-07-23T05:00:00Z", + "user": {"login": "x"}, + }] + self.assertEqual( + timeline.adapt_cth_comments(comments, kind="issue", number=SYNTHETIC_SECRET_40_HEX), + [], + ) + self.assertEqual( + timeline.adapt_cth_comments(comments, kind=SYNTHETIC_SECRET_40_HEX, number=1), + [], + ) + + def test_source_failure_reason_is_redacted(self): + def boom(kind, number): + raise RuntimeError(f"auth failed with token={SYNTHETIC_SECRET_40_HEX}") + + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + snap = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, db_path=db, comment_source=boom, + ) + d = snap.to_dict() + handoff = [s for s in d["sources"] if s["name"] == "gitea_handoff"][0] + self.assertFalse(handoff["ok"]) + self.assertIn("handoff source failed", handoff["reason"]) + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(d)) + + def test_echoed_scope_and_filters_are_guarded(self): + import tempfile + + with tempfile.TemporaryDirectory() as tmp: + db = os.path.join(tmp, "cp.sqlite3") + _seed_db(db) + d = timeline.load_timeline( + remote="prgs", org="Scaled-Tech-Consulting", repo="Gitea-Tools", + issue=637, session=SYNTHETIC_SECRET_40_HEX, db_path=db, + comment_source=lambda k, n: [], + ).to_dict() + self.assertNotIn(SYNTHETIC_SECRET_40_HEX, json.dumps(d)) + # Ordinary scope values are untouched, so the echo stays useful. + self.assertEqual( + d["scope"], + {"remote": "prgs", "org": "Scaled-Tech-Consulting", "repo": "Gitea-Tools"}, + ) + self.assertEqual(d["filters"]["issue"], 637) + + +class TestCthTypeContract(unittest.TestCase): + """The contract has one authority; the read path consults it.""" + + def test_declared_types_are_known(self): + for cth_type in CTH_TYPES: + self.assertTrue(is_known_cth_type(cth_type)) + + def test_undeclared_types_are_not_known(self): + for value in ("", None, "Made Up", SYNTHETIC_SECRET_40_HEX, "author handoff"): + self.assertFalse(is_known_cth_type(value)) + + def test_parse_reports_contract_membership(self): + known = parse_cth_comment(_raw_cth_body("Author Handoff")) + self.assertTrue(known["cth_type_known"]) + self.assertEqual(known["cth_type"], "Author Handoff") + unknown = parse_cth_comment(_raw_cth_body("Not A Real Type")) + # Parsing stays total: the type is still reported, just not endorsed. + self.assertEqual(unknown["cth_type"], "Not A Real Type") + self.assertFalse(unknown["cth_type_known"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_worktree_cleanup_audit.py b/tests/test_worktree_cleanup_audit.py index f55b652..f3fc510 100644 --- a/tests/test_worktree_cleanup_audit.py +++ b/tests/test_worktree_cleanup_audit.py @@ -134,13 +134,35 @@ class TestClassification(unittest.TestCase): self.assertEqual(cls, wca.CLASS_ACTIVE_OPEN_PR) self.assertFalse(wca.is_removable(cls)) - def test_stale_clean_issue_worktree_removable(self): - # Scenario 5: clean issue worktree, TTL expired, no lock -> removable. + def test_stale_clean_issue_worktree_needs_merged_pr_proof(self): + # Scenario 5 (#858): age is not proof that the branch landed, so a + # TTL-expired issue worktree stays active work. Only authoritative + # merged-PR evidence makes it removable, which is what keeps a + # worktree holding unmerged commits from being reclaimed by age. cls = wca.classify_worktree( workflow_type=wca.WORKFLOW_ISSUE_WORK, is_dirty=False, ttl_expired=True, ) + self.assertEqual(cls, wca.CLASS_ACTIVE_ISSUE_WORK) + self.assertFalse(wca.is_removable(cls)) + + cls = wca.classify_worktree( + workflow_type=wca.WORKFLOW_ISSUE_WORK, + is_dirty=False, + ttl_expired=True, + merged_pr_cleanup={"proven": True}, + ) + self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE) + self.assertTrue(wca.is_removable(cls)) + + def test_stale_clean_conflict_fix_worktree_removable(self): + # conflict_fix keeps the original TTL rule; #858 changed issue work only. + cls = wca.classify_worktree( + workflow_type=wca.WORKFLOW_CONFLICT_FIX, + is_dirty=False, + ttl_expired=True, + ) self.assertEqual(cls, wca.CLASS_CLEAN_STALE_REMOVABLE) self.assertTrue(wca.is_removable(cls)) diff --git a/webui/app.py b/webui/app.py index 2a79d6c..5fbb787 100644 --- a/webui/app.py +++ b/webui/app.py @@ -12,6 +12,7 @@ from starlette.routing import Route from webui.deployment_boundary import deployment_snapshot from webui.layout import render_page +from webui.nav import NAV_GROUPS, STUB_PAGES from webui.project_registry import ( ProjectRegistry, RegistryError, @@ -45,6 +46,7 @@ from webui.worktree_scanner import load_hygiene_snapshot, snapshot_to_dict as wo from webui.worktree_views import render_worktrees_page from webui.runtime_health import load_runtime_snapshot, snapshot_to_dict as runtime_snapshot_to_dict from webui.runtime_views import render_runtime_page +from webui.timeline import load_timeline, snapshot_to_dict as timeline_snapshot_to_dict from webui.system_health import ( API_PATH as SYSTEM_HEALTH_API_PATH, load_system_health, @@ -65,24 +67,62 @@ def _stub_page(title: str, description: str) -> HTMLResponse: return HTMLResponse(render_page(title=title, body_html=body)) +_LEGACY_PAGES = ( + ("/queue", "Queue", "live PR and issue dashboard (#429)"), + ("/projects", "Projects", "registry and onboarding (#427)"), + ("/prompts", "Prompts", "canonical workflow prompt library (#428)"), + ("/runtime", "Runtime", "MCP health and stale-runtime detection (#430)"), + ("/audit", "Audit", "final-report paste and validator preview (#431)"), + ("/worktrees", "Worktrees", "branch hygiene dashboard (#432)"), + ("/leases", "Leases", "collision and lease visibility (#433)"), + ("/actions", "Actions", "gated write-action framework (#434)"), +) + + +def _render_home_nav_groups() -> str: + groups = [] + for group in NAV_GROUPS: + items = "".join( + f'
  • {item.label}' + + ("" if item.status == "live" else " (stub)") + + "
    • " + for item in group.items + ) + groups.append(f"

    {group.label}

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

    Operator console

    " - "

    Local entry point for MCP Control Plane operational views.

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

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

    " + "

    Phase 1 surfaces

    " + + _render_home_nav_groups() + + "

    MVP legacy pages

    " + "
      " + legacy + "
    " ) return HTMLResponse(render_page(title="Home", body_html=body)) +async def phase_stub(request: Request) -> HTMLResponse: + """Graceful read-only placeholder for a not-yet-implemented Phase 1 surface.""" + title, description = STUB_PAGES[request.url.path] + body = ( + f"

    {title}

    " + f'

    {description}

    ' + "

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

    " + ) + return HTMLResponse(render_page(title=title, body_html=body)) + + async def health(_request: Request) -> JSONResponse: """Liveness only — deliberately cheap, runs no dependency probe (#634). @@ -410,6 +450,104 @@ async def api_console_security_model(_request: Request) -> JSONResponse: }) +def _query_int(request: Request, key: str) -> int | None: + """Parse an optional integer query parameter; None when absent/invalid.""" + raw = request.query_params.get(key) + if raw is None or not str(raw).strip(): + return None + try: + return int(str(raw).strip()) + except (TypeError, ValueError): + return None + + +def _derive_remote(host: str) -> str: + """Map a Gitea host to its known short remote name (control-plane scope key).""" + text = (host or "").lower() + if "prgs" in text: + return "prgs" + if "dadeschools" in text: + return "dadeschools" + return text.split(".")[0] if text else "" + + +def _timeline_comment_source(host: str, org: str, repo: str): + """Build a fail-soft CTH-comment fetcher for one repo, or None when offline. + + Returns a callable ``(kind, number) -> list[comment]``. Credentials or + network failures raise inside the callable so ``load_timeline`` degrades the + handoff source rather than the whole timeline. Offline test mode yields no + live source so the handoff section reports ``not run``. + """ + import os + + from gitea_auth import api_fetch_page, get_auth_header, repo_api_url + + offline = (os.environ.get("WEBUI_TEST_OFFLINE") or "").strip().lower() in {"1", "true", "yes"} + if offline: + return None + auth = get_auth_header(host) + if not auth: + return None + + def _fetch(kind: str, number: int) -> list: + segment = "pulls" if kind == "pr" else "issues" + url = f"{repo_api_url(host, org, repo)}/{segment}/{int(number)}/comments" + comments: list = [] + page = 1 + while page <= 20: + raw, meta = api_fetch_page(url, auth, page=page, limit=50) + comments.extend(raw) + if bool(meta["is_final_page"]): + break + page += 1 + return comments + + return _fetch + + +async def api_v1_timeline(request: Request) -> JSONResponse: + """Read-only workflow-event timeline (#637). Filter by issue/PR/session.""" + from webui.queue_loader import _host_from_url # host normalisation helper + + registry, error = _load_project_registry() + if error is not None: + return JSONResponse(error.to_dict(), status_code=500) + project = registry.projects[0] if registry.projects else None + + org = request.query_params.get("org") or (project.gitea_owner if project else "") + repo = request.query_params.get("repo") or (project.repo_name if project else "") + host = _host_from_url(project.remote_host) if project else "" + remote = request.query_params.get("remote") or _derive_remote(host) + + if not (remote and org and repo): + return JSONResponse( + { + "error": "timeline_scope_unresolved", + "detail": "no project in registry and no remote/org/repo query params provided", + }, + status_code=400, + ) + + comment_source = _timeline_comment_source(host, org, repo) if (host and org and repo) else None + + snapshot = load_timeline( + remote=remote, + org=org, + repo=repo, + issue=_query_int(request, "issue"), + pr=_query_int(request, "pr"), + session=(request.query_params.get("session") or None), + limit=_query_int(request, "limit"), + offset=_query_int(request, "offset"), + comment_source=comment_source, + ) + # A filter no surviving source can carry is refused, not answered empty: + # a 200 with zero events would tell the operator no such activity exists. + status_code = 200 if snapshot.ok else 422 + return JSONResponse(timeline_snapshot_to_dict(snapshot), status_code=status_code) + + async def method_not_allowed(request: Request, _exc: Exception) -> Response: path = request.url.path if path in _AUDIT_MUTATION_PATHS and request.method == "POST": @@ -449,6 +587,7 @@ def create_app(*, bind_host: str | None = None) -> Starlette: Route("/api/prompts", api_prompts, methods=["GET"]), Route("/runtime", runtime, methods=["GET"]), Route("/api/runtime", api_runtime, methods=["GET"]), + Route("/api/v1/timeline", api_v1_timeline, methods=["GET"]), Route("/audit", audit, methods=["GET", "POST"]), Route("/api/audit", api_audit, methods=["GET", "POST"]), Route("/worktrees", worktrees, methods=["GET"]), @@ -472,6 +611,10 @@ def create_app(*, bind_host: str | None = None) -> Starlette: api_console_security_model, methods=["GET"], ), + *[ + Route(path, phase_stub, methods=["GET"]) + for path in STUB_PAGES + ], ], exception_handlers={405: method_not_allowed}, ) diff --git a/webui/layout.py b/webui/layout.py index 47bedc1..4d62eca 100644 --- a/webui/layout.py +++ b/webui/layout.py @@ -2,28 +2,66 @@ from __future__ import annotations -NAV_ITEMS = ( - ("/", "Home"), - ("/queue", "Queue"), - ("/projects", "Projects"), - ("/prompts", "Prompts"), - ("/runtime", "Runtime"), - ("/audit", "Audit"), - ("/worktrees", "Worktrees"), - ("/leases", "Leases"), - ("/actions", "Actions"), -) +import os + +from webui.nav import NAV_GROUPS MVP_NOTICE = ( "Read-only MVP — Gitea, MCP tools, and canonical workflows remain the " "source of truth. No mutation endpoints." ) +# Canonical docs entry point surfaced from the shell header (#638). +DOCS_URL = ( + "https://gitea.prgs.cc/Scaled-Tech-Consulting/Gitea-Tools/src/branch/" + "master/docs/webui-local-dev.md" +) + +_LOCAL_HOSTS = frozenset({"", "127.0.0.1", "localhost", "::1"}) + + +def environment_label() -> str: + """Classify the serving environment as ``local`` or ``remote`` (#638). + + Derived from the same ``WEBUI_HOST`` default the app binds to; loopback + hosts are ``local``, anything else is ``remote``. Read-only signal only. + """ + host = (os.environ.get("WEBUI_HOST", "127.0.0.1") or "").strip().lower() + return "local" if host in _LOCAL_HOSTS else "remote" + + +def _render_nav() -> str: + groups_html = [] + for group in NAV_GROUPS: + links = "".join( + f'{item.label}' + for item in group.items + ) + groups_html.append( + '
    ' + f'{group.label}' + f'{links}' + "
    " + ) + return "".join(groups_html) + + +def _render_badges() -> str: + env = environment_label() + return ( + '
    ' + f'env: {env}' + 'mode: read-only' + f'Docs' + "
    " + ) + def render_page(*, title: str, body_html: str, extra_head: str = "") -> str: - nav_links = "".join( - f'{label}' for href, label in NAV_ITEMS - ) + nav_links = _render_nav() + header_badges = _render_badges() return f""" @@ -53,21 +91,58 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str: padding: 0.75rem 1.25rem; }} header h1 {{ - margin: 0 0 0.5rem; + margin: 0; font-size: 1.1rem; font-weight: 600; }} + .header-top {{ + display: flex; + flex-wrap: wrap; + align-items: center; + justify-content: space-between; + gap: 0.5rem 1rem; + margin-bottom: 0.6rem; + }} + .header-badges {{ display: inline-flex; flex-wrap: wrap; gap: 0.4rem; }} + .env-badge.env-local {{ color: #8fd19e; border-color: #3d6b4a; }} + .env-badge.env-remote {{ color: #e0c27a; border-color: #6b5730; }} + .mode-badge {{ color: #9ec8f0; border-color: #3d5f7a; }} + a.docs-link {{ + color: var(--accent); + border-color: var(--accent); + text-decoration: none; + text-transform: none; + }} + a.docs-link:hover {{ filter: brightness(1.12); }} nav {{ display: flex; flex-wrap: wrap; - gap: 0.75rem 1rem; + gap: 0.5rem 1.25rem; }} + .nav-group {{ + display: flex; + flex-direction: column; + gap: 0.15rem; + }} + .nav-group-label {{ + font-size: 0.68rem; + text-transform: uppercase; + letter-spacing: 0.04em; + color: var(--muted); + }} + .nav-group-links {{ display: inline-flex; flex-wrap: wrap; gap: 0.6rem; }} nav a {{ color: var(--accent); text-decoration: none; font-size: 0.9rem; }} nav a:hover {{ text-decoration: underline; }} + nav a.nav-stub {{ color: var(--muted); }} + nav a.nav-stub::after {{ + content: " ·stub"; + font-size: 0.7rem; + color: var(--muted); + }} main {{ max-width: 52rem; margin: 0 auto; @@ -166,7 +241,10 @@ def render_page(*, title: str, body_html: str, extra_head: str = "") -> str:
    -

    MCP Control Plane

    +
    +

    MCP Control Plane

    + {header_badges} +
    diff --git a/webui/nav.py b/webui/nav.py new file mode 100644 index 0000000..edb128c --- /dev/null +++ b/webui/nav.py @@ -0,0 +1,111 @@ +"""Navigation IA for the Phase 1 operator console shell (#638). + +Single source of truth for the console navigation so ``webui/layout.py`` and +the ``webui/app.py`` route table stay aligned with epic #631. Read-only: every +destination is a GET view or a Phase 1 placeholder. No mutation links. + +Nav groups follow the #631 Phase 1 information architecture: Health, Traffic, +Runtime/Sessions, Projects, Inventory, Timeline, Policy (placeholder), and +Insights (placeholder). Later-phase surfaces are declared as ``stub`` items and +backed by ``STUB_PAGES`` so their nav links resolve to a graceful placeholder +instead of a 404. +""" + +from __future__ import annotations + +from dataclasses import dataclass + + +@dataclass(frozen=True) +class NavItem: + """A single navigation destination. + + ``status`` is ``"live"`` for implemented views and ``"stub"`` for Phase 1 + placeholders whose backing view lands in a later child issue. + """ + + href: str + label: str + status: str = "live" + + +@dataclass(frozen=True) +class NavGroup: + label: str + items: tuple[NavItem, ...] + + +NAV_GROUPS: tuple[NavGroup, ...] = ( + NavGroup("Health", ( + NavItem("/health", "Liveness"), + )), + NavGroup("Traffic", ( + NavItem("/queue", "Queue"), + NavItem("/leases", "Leases"), + NavItem("/actions", "Actions"), + )), + NavGroup("Runtime/Sessions", ( + NavItem("/runtime", "Runtime health"), + NavItem("/sessions", "Sessions", "stub"), + )), + NavGroup("Projects", ( + NavItem("/projects", "Projects"), + )), + NavGroup("Inventory", ( + NavItem("/inventory", "Inventory", "stub"), + NavItem("/worktrees", "Worktrees"), + )), + NavGroup("Timeline", ( + NavItem("/timeline", "Timeline", "stub"), + )), + NavGroup("Policy", ( + NavItem("/policy", "Policy", "stub"), + NavItem("/prompts", "Prompts"), + )), + NavGroup("Insights", ( + NavItem("/insights", "Insights", "stub"), + NavItem("/audit", "Audit"), + )), +) + + +# Phase 1 placeholder destinations whose backing views land in later child +# issues of epic #631. Each maps a path to (title, description). Routes are +# registered so nav links resolve to a graceful, read-only stub page. +STUB_PAGES: dict[str, tuple[str, str]] = { + "/sessions": ( + "Sessions", + "Active session, capability, and role inventory. Backed by the unified " + "inventory API (#636) once it lands.", + ), + "/inventory": ( + "Inventory", + "Unified sessions, leases, locks, namespaces, and worktree inventory. " + "Backed by the Phase 1 inventory API (#636).", + ), + "/timeline": ( + "Timeline", + "Workflow event timeline across issues and PRs. A later Phase 1 surface.", + ), + "/policy": ( + "Policy", + "Capability and role policy surface. Placeholder until a later phase.", + ), + "/insights": ( + "Insights", + "Aggregate operational insights and trends. Placeholder until a later " + "phase.", + ), +} + + +def iter_nav_items(): + """Yield every ``NavItem`` across all groups in declared order.""" + for group in NAV_GROUPS: + for item in group.items: + yield item + + +def nav_hrefs() -> tuple[str, ...]: + """Return every navigation href in declared order.""" + return tuple(item.href for item in iter_nav_items()) diff --git a/webui/timeline.py b/webui/timeline.py new file mode 100644 index 0000000..1ec8284 --- /dev/null +++ b/webui/timeline.py @@ -0,0 +1,906 @@ +"""Workflow-event and conversation timeline model (#637, Phase 1). + +Operators cannot browse a unified timeline of workflow events, decisions, +tool calls, and handoffs: the evidence is scattered across control-plane +events, Gitea canonical handoff comments, and local logs. This module defines +one durable, versioned event schema and per-source adapters that normalise +those scattered records into a single ``WorkflowEvent`` stream, plus a +read-only query layer (filter by issue / PR / session, stable ordering, +pagination) that the ``/api/v1/timeline`` route serves. + +Design rules honoured here: + +- **Read-only.** Sources are read; nothing is mutated. The control-plane + database is opened through a ``mode=ro`` URI so a missing or unwritable DB + degrades to a reason instead of creating directories or running migrations. +- **Fail-soft per source.** An unavailable source degrades to a status with a + reason rather than raising, and a source that could not run is never + rendered as an empty-and-healthy timeline. +- **Answerable filters only.** Each source declares which filter dimensions it + can actually answer. A filter dimension no source that ran can carry is + refused with an explicit reason rather than silently matching nothing: an + empty page from an unanswerable filter reads to an operator as "no such + activity", which is a different — and false — statement. +- **Redaction at the boundary, fail closed.** Every free-text field (event + messages, redacted tool arguments, decision/proof text) is run through the + console redaction policy before it leaves this module, and *before* any + structured value is derived from it — evidence references are extracted from + redacted text, then independently revalidated before serialization. An + unredactable value becomes the placeholder, and a value that cannot be proven + safe is dropped — an unredacted payload is never emitted, and a generation + error never drops raw data to a caller or a log. +- **Stable ordering.** Events sort by ``(timestamp, source_rank, event_key)`` + with a deterministic tiebreak, so pagination is stable across calls and + events with equal or missing timestamps keep a fixed order. + +Non-goals (from the issue): no full chat replay, no mutation of historical +events, no unredacted tool-argument storage. +""" + +from __future__ import annotations + +import re +import sqlite3 +from dataclasses import dataclass, replace +from datetime import datetime, timezone +from typing import Any, Callable, Iterable + +import control_plane_db +from webui import console_redaction + +# The schema is versioned so consumers can branch on shape. Bump on any +# breaking change to WorkflowEvent's serialized form. +TIMELINE_SCHEMA_VERSION = 1 + +# Known event sources and their deterministic ordering rank. When two events +# carry the same timestamp, the source rank breaks the tie before the +# per-source event key, so a control-plane event and a handoff comment minted +# in the same second always sort in a fixed order. +SOURCE_CONTROL_PLANE = "control_plane" +SOURCE_GITEA_HANDOFF = "gitea_handoff" +_SOURCE_RANK = { + SOURCE_CONTROL_PLANE: 0, + SOURCE_GITEA_HANDOFF: 1, +} + +# The filter dimensions the query layer accepts. +FILTER_ISSUE = "issue" +FILTER_PR = "pr" +FILTER_SESSION = "session" + +# Which dimensions each source can actually answer. This is a property of the +# underlying records, not of the query code: the control-plane ``events`` table +# is (event_id, work_item_id, event_type, message, created_at) and carries no +# session identity at all, so no control-plane event can ever match a session +# filter. A CTH handoff comment can declare its session as a field, so the +# handoff source answers all three. Filtering on a dimension the surviving +# sources cannot carry is refused in ``load_timeline`` rather than answered +# with an empty page. +_SOURCE_FILTER_SUPPORT: dict[str, tuple[str, ...]] = { + SOURCE_CONTROL_PLANE: (FILTER_ISSUE, FILTER_PR), + SOURCE_GITEA_HANDOFF: (FILTER_ISSUE, FILTER_PR, FILTER_SESSION), +} + +# Why a source cannot answer a dimension, for the refusal reason an operator reads. +_SOURCE_FILTER_LIMITS: dict[tuple[str, str], str] = { + (SOURCE_CONTROL_PLANE, FILTER_SESSION): ( + "control-plane events carry no session identity " + "(the events table has no session column)" + ), +} + +# A timestamp far in the future so events with no parseable timestamp sort +# last (after everything real) instead of first, without raising. +_MISSING_TS_SORT = "9999-12-31T23:59:59Z" + + +def _parse_ts(value: str | None) -> str | None: + """Normalise a timestamp to ``...Z`` UTC, or None when unparseable.""" + if not value: + return None + text = str(value).strip() + if not text: + return None + candidate = text[:-1] + "+00:00" if text.endswith("Z") else text + try: + parsed = datetime.fromisoformat(candidate) + except ValueError: + return None + if parsed.tzinfo is None: + parsed = parsed.replace(tzinfo=timezone.utc) + return parsed.astimezone(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z") + + +def _redact(value: Any) -> Any: + """Redact a single free-text field, failing closed to the placeholder.""" + if value is None: + return None + return console_redaction.redact_text(str(value)) + + +@dataclass(frozen=True) +class WorkflowEvent: + """One normalised timeline event. + + Every field is optional except ``source``/``event_type``/``event_key`` + because sources carry different subsets. The class is frozen so an adapted + event is an immutable record; a consumer that needs a variant builds a new + one rather than mutating history. + """ + + source: str + event_type: str + event_key: str + timestamp: str | None = None + actor: str | None = None + role: str | None = None + issue_number: int | None = None + pr_number: int | None = None + session_id: str | None = None + tool_name: str | None = None + decision: str | None = None + message: str | None = None + correlation_id: str | None = None + evidence_refs: tuple[str, ...] = () + sensitive: bool = False + + def sort_key(self) -> tuple[str, int, str]: + return ( + self.timestamp or _MISSING_TS_SORT, + _SOURCE_RANK.get(self.source, 99), + self.event_key, + ) + + def to_dict(self) -> dict[str, Any]: + return { + "source": self.source, + "event_type": self.event_type, + "event_key": self.event_key, + "timestamp": self.timestamp, + "actor": self.actor, + "role": self.role, + "issue_number": self.issue_number, + "pr_number": self.pr_number, + "session_id": self.session_id, + "tool_name": self.tool_name, + "decision": self.decision, + "message": self.message, + "correlation_id": self.correlation_id, + "evidence_refs": list(self.evidence_refs), + "sensitive": self.sensitive, + } + + +# --------------------------------------------------------------------------- # +# Adapters — pure functions from a source's raw records to WorkflowEvents. # +# Each is total: a malformed record is skipped, never raised on. # +# --------------------------------------------------------------------------- # + +# Event types whose payload is treated as sensitive and always redaction-hard +# (they can carry lease/session provenance or tool arguments). +_SENSITIVE_EVENT_HINTS = ("lease", "capability", "token", "auth", "secret") + +# Reference tokens (issue/PR/comment ids) and SHAs parsed out of proof text. +_EVIDENCE_REF_RE = re.compile(r"(?:#|PR\s*#?|issue\s*#?|comment\s*#?)(\d+)", re.IGNORECASE) + +# A commit reference is only recognised when the text *declares* it as one. +# A bare lowercase hex run is not evidence of anything: at 40 characters it is +# exactly the shape of a Gitea personal access token, and at 7 it also matches +# ordinary words such as "defaced". Requiring an anchoring keyword keeps real +# references ("commit abc1234", "at head a209756...", "base caaae9b6") usable +# while refusing to lift an undeclared secret-shaped run out of free text. +_SHA_RE = re.compile( + r"(?i:\b(?:commit|sha|head|base|parent|revision|rev|merge[- ]base)\b[\s:=@#]*)" + r"([0-9a-f]{7,40})\b" +) + +# Shapes a serialized evidence reference is allowed to take. Anything else is +# dropped rather than emitted. +_REF_ISSUE_SHAPE = re.compile(r"^#[0-9]{1,9}$") +_REF_SHA_SHAPE = re.compile(r"^[0-9a-f]{7,40}$") + +# A long undelimited hex run with no declaring context is treated as credential +# material wherever it appears, never as an identifier. +_BARE_SECRET_SHAPE = re.compile(r"^[0-9a-f]{32,}$") + +# An event type reads like an identifier, but a stored one is externally +# influenced: any producer that writes the control-plane ``events`` table +# chooses the string. It reaches ``to_dict`` verbatim, so it is validated here +# rather than trusted because of where it came from. +_CP_EVENT_TYPE_SHAPE = re.compile(r"^[A-Za-z][A-Za-z0-9._:+-]{0,63}$") + +# Emitted in place of a value that cannot be proven safe. Deliberately not a +# plausible workflow type: an unsafe value is refused, never quietly rewritten +# into a different valid-looking one that would misdescribe the record. +UNSAFE_EVENT_TYPE = "unsafe:redacted" + +# Emitted for a CTH heading that is not a declared member of ``CTH_TYPES``. The +# contract is enforced on write (``format_cth_body``) and on assess; the read +# path the timeline uses enforces it too rather than assuming it was. +UNKNOWN_HANDOFF_EVENT_TYPE = "handoff:unrecognized" + +# A source record id is a plain integer in both sources it comes from: the +# control-plane ``events`` primary key and a Gitea comment id. ``event_key`` is +# serialized verbatim and is the pagination tiebreak, so anything else is +# refused rather than interpolated into it. +_RECORD_ID_SHAPE = re.compile(r"^[0-9]{1,19}$") + + +def _kind_to_numbers(kind: str | None, number: int | None) -> tuple[int | None, int | None]: + """Map a control-plane work-item (kind, number) to (issue_no, pr_no).""" + if number is None: + return (None, None) + if kind == "pr": + return (None, int(number)) + if kind == "issue": + return (int(number), None) + return (None, None) + + +def _correlation_for(kind: str | None, number: int | None) -> str | None: + if number is None or kind not in ("issue", "pr"): + return None + return f"{kind}#{number}" + + +def _extract_evidence_refs(*texts: str | None) -> tuple[str, ...]: + """Extract issue/PR and declared-commit references from **redacted** text. + + Callers must pass text that has already been through :func:`_redact`; this + function derives a structured field from its input, so extracting ahead of + redaction would republish whatever redaction was about to remove. Every + reference is revalidated by :func:`_validated_evidence_refs` before it is + serialized. + """ + refs: list[str] = [] + for text in texts: + if not text: + continue + for match in _EVIDENCE_REF_RE.finditer(text): + token = f"#{match.group(1)}" + if token not in refs: + refs.append(token) + for match in _SHA_RE.finditer(text): + token = match.group(1) + if token not in refs: + refs.append(token) + return tuple(refs) + + +def _validated_evidence_refs(refs: Iterable[str]) -> tuple[tuple[str, ...], bool]: + """Independently revalidate references immediately before serialization. + + Extraction is not trusted on its own. A reference survives only when it has + a known reference shape and is unchanged by a second redaction pass — a + value the redaction policy would alter is credential material that must not + be emitted as a structured field. A full 40-character SHA stays usable + because extraction only accepts a hex run the source text explicitly + declared as a commit. Returns ``(safe_refs, dropped_any)``; ``dropped_any`` + marks the event sensitive so the drop is visible rather than silent. + """ + safe: list[str] = [] + dropped = False + for ref in refs or (): + try: + token = str(ref).strip() + if not token: + continue + recognised = bool(_REF_ISSUE_SHAPE.match(token) or _REF_SHA_SHAPE.match(token)) + if not recognised: + dropped = True + continue + if _redact(token) != token: + dropped = True + continue + if token not in safe: + safe.append(token) + except Exception: + # Fail closed: a reference that cannot be proven safe is dropped. + dropped = True + continue + return (tuple(safe), dropped) + + +def _safe_session_id(value: Any) -> str | None: + """Return a session identifier only when it is safe to emit. + + The value is authoritative source data — a session the record names for + itself — but it is still free text. It is dropped when redaction alters it + or when it is a bare secret-shaped hex run, so a credential parked in a + session field can never reach the payload or be echoed back by a filter. + """ + if value is None: + return None + text = str(value).strip() + if not text: + return None + if _BARE_SECRET_SHAPE.match(text): + return None + return text if _redact(text) == text else None + + +def _safe_record_id(value: Any) -> str | None: + """Return a source record id only when it is a plain numeric identifier. + + ``event_key`` is serialized verbatim and is the deterministic pagination + tiebreak, so an id is interpolated into it only when it has the shape both + real sources actually produce. A record whose identity cannot be trusted is + refused by the caller rather than keyed on. + """ + if value is None or isinstance(value, bool): + return None + if isinstance(value, int): + return str(value) + text = str(value).strip() + return text if _RECORD_ID_SHAPE.match(text) else None + + +def _safe_cp_event_type(value: Any) -> tuple[str, bool]: + """Validate a stored control-plane event type. Returns ``(type, unsafe)``. + + The stored value is externally influenced — whichever producer wrote the + ``events`` row chose the string — and ``to_dict`` serializes it verbatim, so + it passes a boundary of its own instead of relying on the one ``message`` + passes. A value survives only when it is an ordinary identifier, is not a + bare secret-shaped hex run, and is unchanged by a redaction pass. Anything + else fails closed to :data:`UNSAFE_EVENT_TYPE`: the record stays visible as + an audit entry, but the value itself is never republished — not verbatim, + not partially sanitized, and not rewritten into some other valid-looking + type that would misdescribe what happened. + """ + text = ("" if value is None else str(value)).strip() + if not text: + return ("", False) + if _BARE_SECRET_SHAPE.match(text): + return (UNSAFE_EVENT_TYPE, True) + if not _CP_EVENT_TYPE_SHAPE.match(text): + return (UNSAFE_EVENT_TYPE, True) + if _redact(text) != text: + return (UNSAFE_EVENT_TYPE, True) + return (text, False) + + +def _safe_echo(value: Any) -> Any: + """Guard a scalar that is echoed back rather than derived from a record. + + Query scope and filter values are caller-supplied and are reflected in the + response so an operator can see what was asked. Reflection is still + emission: a value redaction would alter, or a bare secret-shaped hex run, is + replaced by the placeholder instead of being echoed verbatim. Ordinary + scope and filter values pass through untouched. + """ + if value is None or isinstance(value, (int, bool)): + return value + text = str(value) + if _BARE_SECRET_SHAPE.match(text.strip()): + return console_redaction.REDACTED + return _redact(text) + + +def adapt_cp_events(rows: Iterable[dict[str, Any]]) -> list[WorkflowEvent]: + """Adapt control-plane ``events`` rows (joined to work_items) into events. + + Each row is expected to carry ``event_id``, ``event_type``, ``message``, + ``created_at`` and the joined work-item ``kind``/``number``. Rows missing + an id or type are skipped so a partially written table never raises. + """ + events: list[WorkflowEvent] = [] + for row in rows or []: + try: + event_id = _safe_record_id(row.get("event_id")) + raw_event_type = (row.get("event_type") or "").strip() + if event_id is None or not raw_event_type: + continue + # The stored type is source data, not a trusted constant: validate + # it before it is serialized, exactly as `message` below is redacted + # before it is serialized. + event_type, event_type_unsafe = _safe_cp_event_type(raw_event_type) + kind = row.get("kind") + number = row.get("number") + issue_no, pr_no = _kind_to_numbers(kind, number) + sensitive = event_type_unsafe or any( + hint in raw_event_type.lower() for hint in _SENSITIVE_EVENT_HINTS + ) + events.append( + WorkflowEvent( + source=SOURCE_CONTROL_PLANE, + event_type=event_type, + event_key=f"cp:{event_id}", + timestamp=_parse_ts(row.get("created_at")), + issue_number=issue_no, + pr_number=pr_no, + # No session_id: the control-plane events table is + # (event_id, work_item_id, event_type, message, created_at) + # and records no session. Inventing one from the work item + # or the message text would be a guess, so this source + # declares the session dimension unsupported instead + # (_SOURCE_FILTER_SUPPORT) and the query layer refuses a + # session filter it cannot honestly answer. + message=_redact(row.get("message")), + correlation_id=_correlation_for(kind, number), + sensitive=sensitive, + ) + ) + except Exception: + # A single malformed row must not sink the whole adaptation. + continue + return events + + +def adapt_cth_comments( + comments: Iterable[dict[str, Any]], + *, + kind: str, + number: int, +) -> list[WorkflowEvent]: + """Adapt Gitea Canonical Thread Handoff (CTH) comments into events. + + Only comments that parse as a CTH (``canonical_thread_handoff.parse_cth_comment``) + become events; ordinary comments are ignored. ``kind``/``number`` scope the + events to the issue or PR the comments belong to. + """ + # Imported lazily so this module has no import-time dependency on the + # handoff parser when only the control-plane adapter is used. + from canonical_thread_handoff import is_known_cth_type, parse_cth_comment + + # ``kind``/``number`` are interpolated into event_key and correlation_id, so + # they are normalised once here. A scope this adapter cannot express is + # refused outright rather than serialized into an identifier. + kind = (kind or "").strip().lower() + if kind not in ("issue", "pr"): + return [] + try: + number = int(number) + except (TypeError, ValueError): + return [] + + issue_no, pr_no = _kind_to_numbers(kind, number) + correlation = _correlation_for(kind, number) + events: list[WorkflowEvent] = [] + for comment in comments or []: + try: + body = comment.get("body") or "" + parsed = parse_cth_comment(body) + if not parsed: + continue + fields = parsed.get("fields") or {} + cth_type = parsed.get("cth_type") or "" + comment_id = _safe_record_id(comment.get("id")) + if comment_id is None: + continue + # The CTH heading is free text: the parser accepts whatever follows + # "## CTH:", and only the write and assess paths check it against + # the contract. Check it here too — an unrecognised heading is + # reported as such rather than serialized into event_type, so + # arbitrary, malformed, or secret-shaped heading content has no way + # through. Declared types are preserved exactly. + cth_type_known = is_known_cth_type(cth_type) + # Redaction runs first, and every derived value is taken from the + # redacted text — deriving evidence refs from the raw proof would + # re-emit exactly what redaction was about to remove. + decision = _redact(fields.get("decision")) + proof = _redact(fields.get("proof")) + next_action = _redact(fields.get("next action")) + refs, refs_dropped = _validated_evidence_refs( + _extract_evidence_refs(proof, decision) + ) + events.append( + WorkflowEvent( + source=SOURCE_GITEA_HANDOFF, + event_type=( + f"handoff:{cth_type.strip()}" + if cth_type_known + else UNKNOWN_HANDOFF_EVENT_TYPE + ), + event_key=f"cth:{kind}:{number}:{comment_id}", + timestamp=_parse_ts(comment.get("created_at")), + actor=_redact((comment.get("user") or {}).get("login")), + role=_redact(fields.get("next owner")), + issue_number=issue_no, + pr_number=pr_no, + # A CTH names its own session when the producer records one; + # it is read from that declared field, never inferred from + # unrelated text. + session_id=_safe_session_id(fields.get("session")), + decision=decision, + message=next_action or _redact(fields.get("status")), + correlation_id=correlation, + evidence_refs=refs, + sensitive=refs_dropped or not cth_type_known, + ) + ) + except Exception: + continue + return events + + +# --------------------------------------------------------------------------- # +# Read-only control-plane event source. # +# --------------------------------------------------------------------------- # + +_CP_EVENTS_QUERY = """ +SELECT e.event_id AS event_id, + e.event_type AS event_type, + e.message AS message, + e.created_at AS created_at, + w.kind AS kind, + w.number AS number +FROM events e +JOIN work_items w ON e.work_item_id = w.work_item_id +WHERE w.remote = ? AND w.org = ? AND w.repo = ? +""" + + +@dataclass(frozen=True) +class SourceStatus: + """Fail-soft status for one timeline source. + + ``supported_filters`` states which filter dimensions this source's records + can carry; ``unsupported_filters`` names the requested dimensions it cannot, + so an operator can see *why* a source contributed nothing rather than being + left to read an empty list as an absence of activity. + """ + + name: str + ok: bool + reason: str | None = None + count: int = 0 + supported_filters: tuple[str, ...] = () + unsupported_filters: tuple[str, ...] = () + + def to_dict(self) -> dict[str, Any]: + return { + "name": self.name, + "ok": self.ok, + "reason": self.reason, + "count": self.count, + "supported_filters": list(self.supported_filters), + "unsupported_filters": list(self.unsupported_filters), + } + + +def _cp_status(*, ok: bool, reason: str | None = None, count: int = 0) -> SourceStatus: + return SourceStatus( + SOURCE_CONTROL_PLANE, + ok=ok, + # A failure reason is serialized like any other field and is often an + # exception string carrying a path or a transport error, so it crosses + # the redaction boundary too. Static reasons pass through unchanged. + reason=_redact(reason), + count=count, + supported_filters=_SOURCE_FILTER_SUPPORT[SOURCE_CONTROL_PLANE], + ) + + +def _handoff_status(*, ok: bool, reason: str | None = None, count: int = 0) -> SourceStatus: + return SourceStatus( + SOURCE_GITEA_HANDOFF, + ok=ok, + # Same boundary as the control-plane status: this reason can quote an + # error raised by a live authenticated fetch. + reason=_redact(reason), + count=count, + supported_filters=_SOURCE_FILTER_SUPPORT[SOURCE_GITEA_HANDOFF], + ) + + +def read_cp_events( + *, + remote: str, + org: str, + repo: str, + db_path: str | None = None, +) -> tuple[list[WorkflowEvent], SourceStatus]: + """Read scoped control-plane events read-only. Never creates the DB. + + Opens the SQLite file through a ``mode=ro`` URI: a health/timeline read + must never create directories or run the schema migration that + ``ControlPlaneDB()`` performs on construction. A missing or unreadable DB + degrades to a status with a reason. + """ + path = (db_path or control_plane_db.default_db_path()).strip() + conn: sqlite3.Connection | None = None + try: + conn = sqlite3.connect(f"file:{path}?mode=ro", uri=True) + conn.row_factory = sqlite3.Row + cursor = conn.execute(_CP_EVENTS_QUERY, (remote, org, repo)) + rows = [dict(r) for r in cursor.fetchall()] + except sqlite3.OperationalError as exc: + return ([], _cp_status(ok=False, reason=f"control-plane DB unavailable: {exc}")) + except sqlite3.Error as exc: + return ([], _cp_status(ok=False, reason=f"control-plane read failed: {exc}")) + finally: + if conn is not None: + conn.close() + events = adapt_cp_events(rows) + return (events, _cp_status(ok=True, count=len(events))) + + +# --------------------------------------------------------------------------- # +# Filter, sort, paginate. # +# --------------------------------------------------------------------------- # + + +def filter_events( + events: Iterable[WorkflowEvent], + *, + issue: int | None = None, + pr: int | None = None, + session: str | None = None, +) -> list[WorkflowEvent]: + """Filter events by issue number, PR number, and/or session id. + + Filters are conjunctive. A filter that names a dimension an event does not + carry excludes that event (an issue filter excludes PR-only events). + """ + out: list[WorkflowEvent] = [] + for ev in events: + if issue is not None and ev.issue_number != issue: + continue + if pr is not None and ev.pr_number != pr: + continue + if session is not None and ev.session_id != session: + continue + out.append(ev) + return out + + +def sort_events(events: Iterable[WorkflowEvent]) -> list[WorkflowEvent]: + """Return events in stable timeline order (ascending).""" + return sorted(events, key=lambda ev: ev.sort_key()) + + +@dataclass(frozen=True) +class TimelinePage: + """One page of the sorted, filtered timeline.""" + + events: tuple[WorkflowEvent, ...] + total: int + limit: int + offset: int + + @property + def next_offset(self) -> int | None: + nxt = self.offset + len(self.events) + return nxt if nxt < self.total else None + + def to_dict(self) -> dict[str, Any]: + return { + "events": [ev.to_dict() for ev in self.events], + "pagination": { + "total": self.total, + "limit": self.limit, + "offset": self.offset, + "returned": len(self.events), + "next_offset": self.next_offset, + "has_more": self.next_offset is not None, + }, + } + + +_MAX_LIMIT = 500 +_DEFAULT_LIMIT = 50 + + +def _coerce_bounds(limit: int | None, offset: int | None) -> tuple[int, int]: + try: + lim = int(limit) if limit is not None else _DEFAULT_LIMIT + except (TypeError, ValueError): + lim = _DEFAULT_LIMIT + try: + off = int(offset) if offset is not None else 0 + except (TypeError, ValueError): + off = 0 + lim = max(1, min(lim, _MAX_LIMIT)) + off = max(0, off) + return (lim, off) + + +def paginate(events: list[WorkflowEvent], *, limit: int | None, offset: int | None) -> TimelinePage: + lim, off = _coerce_bounds(limit, offset) + window = events[off : off + lim] + return TimelinePage(events=tuple(window), total=len(events), limit=lim, offset=off) + + +# --------------------------------------------------------------------------- # +# Composition — load_timeline aggregates all sources, fail-soft. # +# --------------------------------------------------------------------------- # + +# A comment source is a callable that, given (kind, number), returns the raw +# Gitea comment list for that issue/PR. The route supplies a live fail-soft +# fetcher; tests supply a fixture. When None, the handoff source is reported as +# not-run (never silently empty-and-healthy). +CommentSource = Callable[[str, int], list[dict[str, Any]]] + + +@dataclass(frozen=True) +class TimelineSnapshot: + """One answered timeline query. + + ``ok`` is False when the query could not be answered as asked — currently + when a requested filter dimension no surviving source can carry was + supplied. The page is then empty *and* the snapshot says so, because an + ``ok`` empty page is a claim that no such activity exists. + """ + + schema_version: int + remote: str + org: str + repo: str + filters: dict[str, Any] + page: TimelinePage + sources: tuple[SourceStatus, ...] + ok: bool = True + error: dict[str, Any] | None = None + + def to_dict(self) -> dict[str, Any]: + return { + "ok": self.ok, + "error": self.error, + "schema_version": self.schema_version, + # Scope and filters are echoed caller input, not derived record + # data. Reflecting a value is still emitting it, so both cross the + # same boundary; ordinary scope and filter values are unchanged. + "scope": { + "remote": _safe_echo(self.remote), + "org": _safe_echo(self.org), + "repo": _safe_echo(self.repo), + }, + "filters": {key: _safe_echo(value) for key, value in self.filters.items()}, + "sources": [s.to_dict() for s in self.sources], + **self.page.to_dict(), + } + + +def _unanswerable_reasons( + statuses: Iterable[SourceStatus], unanswerable: Iterable[str] +) -> list[dict[str, str]]: + """Explain, per source, why each unanswerable dimension went unanswered.""" + out: list[dict[str, str]] = [] + for status in statuses: + for dim in unanswerable: + if dim not in status.supported_filters: + reason = _SOURCE_FILTER_LIMITS.get( + (status.name, dim), f"this source's records carry no {dim} identity" + ) + elif not status.ok: + reason = ( + f"this source can carry {dim} but did not run: " + f"{status.reason or 'unavailable'}" + ) + else: + continue + out.append({"source": status.name, "filter": dim, "reason": reason}) + return out + + +def load_timeline( + *, + remote: str, + org: str, + repo: str, + issue: int | None = None, + pr: int | None = None, + session: str | None = None, + limit: int | None = None, + offset: int | None = None, + db_path: str | None = None, + comment_source: CommentSource | None = None, +) -> TimelineSnapshot: + """Aggregate every timeline source into one filtered, paginated snapshot. + + Sources are read independently and fail soft: an unavailable source + contributes a ``SourceStatus`` with ``ok=False`` and a reason, and never + collapses the whole timeline. The handoff source only runs when a specific + issue or PR is requested (a handoff comment belongs to one thread) and a + ``comment_source`` is available; otherwise it is reported as ``not run`` + rather than as an empty-and-healthy source. + + A filter dimension that no surviving source can carry — a ``session`` + filter when the only source that ran is the control plane, whose events + record no session — is refused with ``ok=False`` and a structured error + instead of being answered with an empty page. + """ + all_events: list[WorkflowEvent] = [] + statuses: list[SourceStatus] = [] + + cp_events, cp_status = read_cp_events(remote=remote, org=org, repo=repo, db_path=db_path) + all_events.extend(cp_events) + statuses.append(cp_status) + + # Gitea handoff comments are thread-scoped: only fetch when the caller + # narrowed to one issue or PR, and only when a source was provided. + handoff_target: tuple[str, int] | None = None + if pr is not None: + handoff_target = ("pr", pr) + elif issue is not None: + handoff_target = ("issue", issue) + + if handoff_target is None: + statuses.append( + _handoff_status( + ok=False, + reason="not run: handoff comments are thread-scoped; filter by issue or pr to include them", + ) + ) + elif comment_source is None: + statuses.append( + _handoff_status( + ok=False, + reason="not run: no comment source configured for this timeline read", + ) + ) + else: + kind, number = handoff_target + try: + comments = comment_source(kind, number) or [] + handoff_events = adapt_cth_comments(comments, kind=kind, number=number) + all_events.extend(handoff_events) + statuses.append(_handoff_status(ok=True, count=len(handoff_events))) + except Exception as exc: # fail soft: a fetch/parse error degrades this source only + statuses.append(_handoff_status(ok=False, reason=f"handoff source failed: {exc}")) + + requested = tuple( + name + for name, value in ((FILTER_ISSUE, issue), (FILTER_PR, pr), (FILTER_SESSION, session)) + if value is not None + ) + statuses = [ + replace( + status, + unsupported_filters=tuple( + dim for dim in requested if dim not in status.supported_filters + ), + ) + for status in statuses + ] + filters = {"issue": issue, "pr": pr, "session": session} + + # A dimension is answerable only if a source that actually ran can carry it. + # If none can, refuse: an empty page would assert "no such activity", which + # is a claim this timeline is not in a position to make. + answerable: set[str] = set() + for status in statuses: + if status.ok: + answerable.update(status.supported_filters) + unanswerable = tuple(dim for dim in requested if dim not in answerable) + + if unanswerable: + return TimelineSnapshot( + schema_version=TIMELINE_SCHEMA_VERSION, + remote=remote, + org=org, + repo=repo, + filters=filters, + page=paginate([], limit=limit, offset=offset), + sources=tuple(statuses), + ok=False, + error={ + "code": "filter_not_supported", + "unsupported_filters": list(unanswerable), + "detail": ( + "no timeline source that ran can answer " + + ", ".join(f"'{dim}'" for dim in unanswerable) + + "; the result is refused rather than returned empty" + ), + "sources": _unanswerable_reasons(statuses, unanswerable), + }, + ) + + filtered = filter_events(all_events, issue=issue, pr=pr, session=session) + ordered = sort_events(filtered) + page = paginate(ordered, limit=limit, offset=offset) + + return TimelineSnapshot( + schema_version=TIMELINE_SCHEMA_VERSION, + remote=remote, + org=org, + repo=repo, + filters=filters, + page=page, + sources=tuple(statuses), + ) + + +def snapshot_to_dict(snapshot: TimelineSnapshot) -> dict[str, Any]: + return snapshot.to_dict() diff --git a/worktree_cleanup_audit.py b/worktree_cleanup_audit.py index 261164a..9eb4b35 100644 --- a/worktree_cleanup_audit.py +++ b/worktree_cleanup_audit.py @@ -34,7 +34,11 @@ import subprocess from datetime import datetime, timezone from typing import Any -from merged_cleanup_reconcile import branch_worktree_folder, read_local_worktree_state +from merged_cleanup_reconcile import ( + branch_worktree_folder, + is_head_ancestor_of_ref, + read_local_worktree_state, +) from reviewer_worktree import parse_dirty_tracked_files, REVIEW_WORKTREE_RE PROTECTED_BRANCHES = frozenset({"master", "main", "dev"}) @@ -67,6 +71,14 @@ REMOVABLE_CLASSES = frozenset( {CLASS_CLEAN_STALE_REMOVABLE, CLASS_DETACHED_REVIEW_LEFTOVER} ) +# Merged-PR linkage outcomes for issue worktrees (#858). Only ``LINKAGE_MERGED`` +# is ownership proof; every other outcome leaves the worktree protected. +LINKAGE_MERGED = "merged_pr" +LINKAGE_OPEN = "open_pr" +LINKAGE_NONE = "no_owning_pr" +LINKAGE_AMBIGUOUS = "ambiguous" +LINKAGE_UNKNOWN = "unknown" + _ISSUE_REF_RE = re.compile(r"issue-(\d+)", re.IGNORECASE) _ISSUE_BRANCH_PREFIXES = ("feat/", "fix/", "docs/", "chore/") @@ -169,6 +181,186 @@ def is_ttl_expired( return (now_dt - last).total_seconds() > ttl_hours * 3600.0 +def build_pr_index(prs: list[dict[str, Any]] | None) -> dict[str, list[dict[str, Any]]]: + """Index PR records by head branch for deterministic worktree linkage (#858). + + Accepts Gitea PR payloads (``head`` as a dict) and pre-flattened records + (``head_branch``/``head_sha``). Records without a usable head branch or + number are dropped rather than guessed at, so a branch is only ever linked + to a PR the caller actually proved. + """ + index: dict[str, list[dict[str, Any]]] = {} + for pr in prs or []: + head = pr.get("head") + if isinstance(head, dict): + head_branch = head.get("ref") + head_sha = head.get("sha") + else: + head_branch = pr.get("head_branch") or (head if isinstance(head, str) else None) + head_sha = pr.get("head_sha") + number = pr.get("number") + if not head_branch or number is None: + continue + try: + pr_number = int(number) + except (TypeError, ValueError): + continue + index.setdefault(str(head_branch).strip(), []).append( + { + "pr_number": pr_number, + "head_branch": str(head_branch).strip(), + "head_sha": head_sha, + "merged": bool(pr.get("merged") or pr.get("merged_at")), + "state": pr.get("state"), + } + ) + return index + + +def resolve_owning_pr( + *, + branch: str | None, + pr_index: dict[str, list[dict[str, Any]]] | None, +) -> dict[str, Any]: + """Resolve the single PR that owns ``branch``, failing closed when unclear. + + Ownership is only ``LINKAGE_MERGED`` when exactly one PR claims the branch + and that PR is merged. Several distinct PRs on one branch is a competing + claim (``LINKAGE_AMBIGUOUS``), and a still-open owner is reported as + ``LINKAGE_OPEN`` — both keep the worktree protected while still exposing + the PR number the audit resolved. + """ + if pr_index is None: + return { + "status": LINKAGE_UNKNOWN, + "pr_number": None, + "candidate_pr_numbers": [], + "reasons": ["live PR state was not supplied; ownership unproven"], + } + branch_name = (branch or "").strip() + if not branch_name: + return { + "status": LINKAGE_UNKNOWN, + "pr_number": None, + "candidate_pr_numbers": [], + "reasons": ["worktree has no attached branch; ownership unproven"], + } + + candidates = list(pr_index.get(branch_name) or []) + numbers = sorted({c["pr_number"] for c in candidates}) + if not candidates: + return { + "status": LINKAGE_NONE, + "pr_number": None, + "candidate_pr_numbers": [], + "reasons": [f"no PR claims branch '{branch_name}'"], + } + if len(numbers) > 1: + return { + "status": LINKAGE_AMBIGUOUS, + "pr_number": None, + "candidate_pr_numbers": numbers, + "reasons": [ + f"branch '{branch_name}' is claimed by competing PRs {numbers}; " + "ownership is ambiguous" + ], + } + + owner = candidates[0] + pr_number = owner["pr_number"] + if owner.get("head_branch") != branch_name: + return { + "status": LINKAGE_UNKNOWN, + "pr_number": pr_number, + "candidate_pr_numbers": numbers, + "reasons": [ + f"PR #{pr_number} head branch '{owner.get('head_branch')}' does not " + f"match worktree branch '{branch_name}'" + ], + } + if not owner.get("merged"): + return { + "status": LINKAGE_OPEN, + "pr_number": pr_number, + "candidate_pr_numbers": numbers, + "pr_head_sha": owner.get("head_sha"), + "reasons": [f"owning PR #{pr_number} is not merged"], + } + return { + "status": LINKAGE_MERGED, + "pr_number": pr_number, + "candidate_pr_numbers": numbers, + "pr_head_sha": owner.get("head_sha"), + "reasons": [], + } + + +def assess_merged_pr_worktree_cleanup( + *, + linkage: dict[str, Any] | None, + head_sha: str | None, + head_in_master: bool | None, + is_dirty: bool, + has_open_pr: bool, + has_active_lease: bool, + has_active_issue_lock: bool, + is_protected: bool, + has_live_session: bool = False, +) -> dict[str, Any]: + """Decide whether a merged issue worktree satisfies the full cleanup policy. + + Every condition must be independently proven: conclusive merged-PR + ownership, agreement between the worktree branch and the PR head branch, + containment of the worktree head in authoritative master (which is what + proves no unmerged commits remain), absence of any open/competing PR, + lease, issue lock, or live session, a clean tree, and a worktree that is + not the protected control checkout. Anything unknown blocks. + """ + link = linkage or { + "status": LINKAGE_UNKNOWN, + "pr_number": None, + "reasons": ["no linkage assessment supplied"], + } + status = link.get("status") + reasons: list[str] = [] + + if status != LINKAGE_MERGED: + reasons.extend( + link.get("reasons") or ["owning PR could not be conclusively identified"] + ) + if is_protected: + reasons.append("worktree is protected or the stable control checkout") + if is_dirty: + reasons.append("worktree has uncommitted changes") + if has_open_pr: + reasons.append("worktree branch has an open PR") + if has_active_lease: + reasons.append("worktree has an active lease") + if has_active_issue_lock: + reasons.append("an active issue lock references this branch") + if has_live_session: + reasons.append("a live process or session is using this worktree") + if not head_sha: + reasons.append("worktree head sha is unknown") + if head_in_master is None: + reasons.append("containment of the worktree head in master is unknown") + elif not head_in_master: + reasons.append( + "worktree head is not contained in authoritative master " + "(unmerged commits remain)" + ) + + proven = not reasons + return { + "linkage_status": status, + "pr_number": link.get("pr_number"), + "pr_head_sha": link.get("pr_head_sha"), + "head_in_master": head_in_master, + "proven": proven, + "block_reasons": reasons, + } + + def classify_worktree( *, workflow_type: str, @@ -181,6 +373,8 @@ def classify_worktree( ttl_expired: bool = False, is_protected: bool = False, metadata_known: bool = True, + merged_pr_cleanup: dict[str, Any] | None = None, + has_live_session: bool = False, ) -> str: """Classify a worktree, safety-first: any preservation signal wins. @@ -199,6 +393,8 @@ def classify_worktree( return CLASS_ACTIVE_ISSUE_WORK # never auto-deleted (criterion 8) if has_active_issue_lock: return CLASS_ACTIVE_ISSUE_WORK + if has_live_session: + return CLASS_ACTIVE_ISSUE_WORK # a live session still owns this tree if not metadata_known or workflow_type == WORKFLOW_UNKNOWN: return CLASS_UNSAFE_UNKNOWN # never auto-deleted without proof @@ -207,7 +403,15 @@ def classify_worktree( if is_detached or branch_gone: return CLASS_DETACHED_REVIEW_LEFTOVER return CLASS_CLEAN_STALE_REMOVABLE - # issue_work / conflict_fix: only removable once the TTL has expired. + if workflow_type == WORKFLOW_ISSUE_WORK: + # #858: an issue worktree becomes removable only on authoritative + # merged-PR evidence satisfying the whole cleanup policy. Age alone + # never proves the branch landed, so TTL cannot qualify one by itself + # — otherwise a worktree holding unmerged commits would be reclaimed. + if (merged_pr_cleanup or {}).get("proven"): + return CLASS_CLEAN_STALE_REMOVABLE + return CLASS_ACTIVE_ISSUE_WORK + # conflict_fix: only removable once the TTL has expired. if ttl_expired: return CLASS_CLEAN_STALE_REMOVABLE return CLASS_ACTIVE_ISSUE_WORK @@ -400,6 +604,20 @@ def remove_worktree(project_root: str, path: str) -> dict[str, Any]: } +def head_contained_in_ref( + project_root: str, head_sha: str | None, ref: str | None +) -> bool | None: + """Return True when ``head_sha`` is already contained in ``ref``. + + Shares :mod:`merged_cleanup_reconcile`'s ancestry check so the audit and + the PR-scoped reconciler agree on what "already landed" means (#858). + Returns None when containment cannot be determined, which fails closed. + """ + if not head_sha or not ref: + return None + return is_head_ancestor_of_ref(project_root, head_sha, ref) + + def _is_under_branches(project_root: str, path: str) -> bool: branches_root = os.path.join(os.path.abspath(project_root), "branches") return os.path.abspath(path or "").startswith(branches_root + os.sep) @@ -413,16 +631,30 @@ def audit_branches_directory( active_issue_branches: set[str] | None = None, now: datetime | str | None = None, ttl_hours: float = DEFAULT_TTL_HOURS, + pr_index: dict[str, list[dict[str, Any]]] | None = None, + leased_issue_numbers: set[int] | None = None, + live_session_paths: set[str] | None = None, + master_ref: str | None = None, ) -> dict[str, Any]: """Classify every session-owned worktree under ``branches/``. Read-only: shells out to git for discovery and dirty state, then applies the pure classifier. Returns per-worktree classifications, counts, the list of removable candidates, and the ``git worktree list`` proof. + + ``pr_index`` (see :func:`build_pr_index`) supplies the authoritative PR + ownership used to link issue worktrees to their merged PR (#858). + ``master_ref`` is the ref a worktree head must be contained in before it + can be considered landed. Both are optional and their absence only ever + fails closed: without them no issue worktree becomes removable. """ open_pr_branches = open_pr_branches or set() leased_branches = leased_branches or set() active_issue_branches = active_issue_branches or set() + leased_issue_numbers = leased_issue_numbers or set() + live_session_paths = { + os.path.abspath(p) for p in (live_session_paths or set()) if p + } worktrees: list[dict[str, Any]] = [] for entry in list_worktrees(project_root): @@ -433,12 +665,42 @@ def audit_branches_directory( ) dirty_state = read_worktree_dirty(path) is_dirty = bool(dirty_state.get("dirty")) + head_sha = entry.get("head") + linkage = resolve_owning_pr(branch=branch, pr_index=pr_index) metadata = build_worktree_metadata( - path=path, branch=branch, head_sha=entry.get("head") + path=path, + branch=branch, + head_sha=head_sha, + pr_number=linkage.get("pr_number"), ) has_open_pr = bool(branch) and branch in open_pr_branches - has_active_lease = bool(branch) and branch in leased_branches + # A lease on issue N protects that issue's own work worktree. It must + # not incidentally protect a baseline/review scratch tree that merely + # carries the same issue marker in its name, which would change the + # classification of worktrees this policy does not own. + has_active_lease = (bool(branch) and branch in leased_branches) or ( + metadata["workflow_type"] == WORKFLOW_ISSUE_WORK + and metadata.get("issue_number") is not None + and metadata["issue_number"] in leased_issue_numbers + ) has_active_lock = bool(branch) and branch in active_issue_branches + has_live_session = bool(path) and os.path.abspath(path) in live_session_paths + head_in_master = ( + head_contained_in_ref(project_root, head_sha, master_ref) + if master_ref + else None + ) + merged_pr_cleanup = assess_merged_pr_worktree_cleanup( + linkage=linkage, + head_sha=head_sha, + head_in_master=head_in_master, + is_dirty=is_dirty, + has_open_pr=has_open_pr, + has_active_lease=has_active_lease, + has_active_issue_lock=has_active_lock, + is_protected=is_protected, + has_live_session=has_live_session, + ) ttl_expired = is_ttl_expired( last_used_at=metadata.get("last_used_at"), now=now, ttl_hours=ttl_hours ) @@ -452,6 +714,8 @@ def audit_branches_directory( branch_gone=branch is None and not entry.get("detached"), ttl_expired=ttl_expired, is_protected=is_protected, + merged_pr_cleanup=merged_pr_cleanup, + has_live_session=has_live_session, ) metadata["cleanup_eligibility"] = classification worktrees.append( @@ -463,7 +727,10 @@ def audit_branches_directory( "has_open_pr": has_open_pr, "has_active_lease": has_active_lease, "has_active_issue_lock": has_active_lock, + "has_live_session": has_live_session, "is_protected": is_protected, + "merged_pr_linkage": linkage, + "merged_pr_cleanup": merged_pr_cleanup, "classification": classification, "removable": is_removable(classification), }