Workspace cleanup

[lazabogdan]

Summary

• Refactors agent conversation archiving to return both the archived conversation payload and a terminal cleanup result, instead of treating archive as a single boolean outcome.
• Adds terminal workspace cleanup plumbing in the backend so archive/recovery paths can claim, finalize, and report local cleanup state for agent workspaces.
• Updates the frontend archive flow to surface local cleanup status, including warnings when cleanup is pending or refused as unsafe.
• Changes bulk archive behavior so conversations with open remote pull requests are still eligible for selection and archival, while the UI makes the local-deletion and remote-PR behavior explicit.
• Extends startup and recovery cleanup paths, repo implementations, and CI coverage/configuration to account for the new cleanup lifecycle.

User Impact

• Archiving now makes the local workspace removal behavior explicit in the UI, including the fact that uncommitted changes and ignored build or test artifacts are deleted locally.
• Bulk archive no longer treats open pull requests as a hard exclusion; selected sessions can be archived while the remote pull request remains open.
• When local cleanup cannot complete immediately or is rejected as unsafe, the archive flow can still succeed and surface that status to the user.

Technical Context

• archive_agent_conversation_for_state now returns a terminal workspace outcome that includes runtime shutdown status, cleanup claim state, and local cleanup result.
• archiveConversation in the frontend now parses a structured archive response with nested conversation and cleanup fields, and the React action layer maps cleanup states to warning toasts.
• Bulk archive eligibility is now based on archive state rather than pull-request presence, and the bulk archive result shape now carries separate cleanup-pending and cleanup-unsafe ID lists.
• New backend cleanup code covers terminal workspace cleanup, orphan worktree cleanup cadence, startup recovery, PR supervision recovery, and Git artifact cleanup so these flows share the same cleanup state model.
• CI support was updated with a heartbeat guard for the Rust full integration job, and coverage exclusions were adjusted for cleanup/recovery surfaces whose behavior is exercised through their helpers.

Risks / Follow-Ups

• The archive and cleanup flows now span more repositories and recovery paths, so regressions are most likely where workspace state, PR state, and cleanup state interact.
• Bulk archive semantics changed for sessions with open remote pull requests; reviewers should verify that the new behavior matches the intended product contract across archive, recovery, and restart paths.
• The new cleanup result plumbing introduces additional status handling in both backend and frontend code paths, so any mismatch in status mapping could affect user-facing warnings or recovery behavior.

View full plan

Goal

“Normally when an agent workspace associated PR gets merged or closed or archived … as soon as we get that terminal state confirmation [we should] have the workspace cleaned up, branch removed and worktree deleted.”

Implement one reliable terminal-workspace cleanup lifecycle that runs during the current app process for merged PRs, remotely closed PRs, explicit PR closure, and conversation archive. “Cleaned up” means the verified RalphX-owned local artifact target is force-removed, including uncommitted and ignored build/test artifacts, and the verified RalphX-owned local branch for that target is force-deleted. For direct workspace PRs this target is the agent workspace worktree/branch; for linked ideation plan PRs it is the linked plan-branch worktree/branch, not an unrelated conversation row path.

Assumptions:

• The user selected Force delete everything for terminal workspaces. Dirty files, ignored artifacts, and local-only commits on the verified cleanup target are intentionally discarded after terminal authority is established.
• Force applies only to a workspace or linked plan-branch target with authoritative merged, closed, or archived state. It does not authorize deleting an unknown orphan merely because its DB row is missing.
• Path containment, canonical workspace identity, project-root exclusion, valid-ref validation, and RalphX branch ownership remain mandatory and cannot be bypassed by the force policy.
• Remote branches are outside scope; only the local worktree and local branch are deleted.

Repository Evidence

• Live PR polling already marks merged/closed status and calls terminalization immediately in src-tauri/src/application/services/pr_merge_poller.rs.
• Shared terminalization currently also serves external reconciliation, supervision recovery, and automation, but is physically owned by pr_merge_poller.rs and has no cross-entry single-flight guard.
• src-tauri/src/application/git_artifact_cleanup.rs validates the expected workspace path, refuses the project root, removes only clean worktrees, and deletes branches only for merged/content-equivalent cases.
• GitService::delete_worktree already uses double-force removal plus a path-safe fallback, and GitService::delete_branch(..., true) already performs git branch -D; no new raw Git subprocess path is needed.
• archive_agent_conversation_for_state and close_agent_workspace_pr_for_state update terminal state but do not invoke local cleanup.
• Periodic terminal cleanup runs every 900 seconds but pauses when any agent is running. Orphan cleanup runs once at startup and uses the same global pause.
• RunningAgentInfo.worktree_path provides the established evidence needed to replace the global pause with candidate-local busy checks.
• The archive dialog currently promises cleanup “on next app restart,” which will become incorrect.

Architecture

1. Extract one terminal cleanup coordinator

Mechanically extract the existing terminalize_agent_workspace_after_pr and cleanup_terminal_agent_workspace_after_pr behavior from application/services/pr_merge_poller.rs into application/agent_workspace_terminal_cleanup.rs. Register it through application/mod.rs; do not leave a forwarding copy or parallel implementation.

The coordinator accepts a typed terminal cause:

• MergedPr
• ClosedPr
• ArchivedConversation

It returns a typed outcome separating:

• runtime shutdown success/failure;
• cleanup claim state (claimed, already_in_progress, already_cleaned);
• local cleanup result (cleaned, failed_unsafe, failed_operational).

Runtime shutdown failure remains blocking. Filesystem cleanup failure becomes durable and retryable; it must not reactivate the workspace or let another workflow continue as if the PR were open.

2. Establish terminal authority before destructive effects

Each entry path must persist or verify terminal authority before cleanup:

• Poller/external reconciliation/supervision: persist publication_pr_status=merged|closed.
• Explicit close: complete the existing remote-close attempt and persist closed.
• Archive: persist the chat archive timestamp and workspace status=archived; whether the remote PR remains open is controlled by the existing checkbox.
• Automation: use the already-confirmed merged state.

After authority is persisted, the coordinator stops the target conversation runtime, fails any still-active run with the terminal reason, verifies no active run remains, kills lingering processes whose CWD is the verified worktree using the established worktree-process cleanup seam, then performs local deletion.

Do not delete first and attempt to persist terminal state afterward.

3. Add durable single-flight cleanup state

Extend AgentConversationWorkspaceRepository with an atomic claim operation backed by SQLite compare-and-set and mirrored by the memory repository:

• Eligible: no marker, legacy retryable markers, pending, failed, or stale cleaning.
• Claim: atomically set local_cleanup_status='cleaning' and local_cleanup_checked_at=now; exactly one caller succeeds.
• Success: set cleaned.
• Failure: set failed_unsafe or failed_operational.
• Duplicate callers observing cleaning or cleaned perform no Git operations and cannot overwrite the terminal marker with branch_missing.

Reuse the existing columns; no schema migration is required. Update terminal-candidate queries so stale cleaning, both failure states, and legacy unsafe|target_ref_missing|workspace_dirty markers are retryable. Treat an already-missing verified worktree and branch as successful cleaned, making crash recovery idempotent.

4. Resolve and validate the exact local artifact target

Add a typed cleanup target resolver before any destructive Git operation:

• DirectAgentWorkspace for direct edit/review workspace PRs, backed by the conversation workspace worktree and expected agent-conversation branch.
• LinkedPlanBranch for ideation/plan PRs backed by a linked PlanBranch, using the plan branch worktree and plan branch name.

Do not route a linked plan-branch PR through the direct agent-workspace branch guard; that can either skip the real plan branch or delete the wrong local target.

Refactor git_artifact_cleanup.rs to expose force-owned terminal cleanup for both target kinds:

1. project checkout is an absolute non-root path;
2. recomputed canonical cleanup target path equals the stored/resolved target path;
3. cleanup target path is under the configured RalphX worktree parent/project workspace directory;
4. cleanup target path is not the project checkout or the worktree parent itself;
5. local branch name is exactly the expected branch for this target kind;
6. branch name passes git check-ref-format.

After these checks, skip the current dirty-worktree and merged/content-equivalence gates, call the existing forced worktree deletion, and force-delete the local branch when present. Missing worktree/branch components count as idempotent success. Any path/ownership mismatch fails closed and is persisted as failed_unsafe.

Keep non-terminal plan-branch cleanup and unknown-orphan cleanup on their existing conservative containment policy.

5. Wire every terminal entry path

Route these callers through the coordinator:

• live merged/closed PR polling;
• external linked-PR reconciliation;
• PR supervision recovery;
• automation merged-run finalization;
• explicit workspace PR close;
• single conversation archive;
• bulk archive, via the same archive backend path.

Each caller supplies or reloads enough state for the coordinator to resolve the cleanup target as direct workspace vs linked plan branch. Remove caller-local cleanup decisions such as “delete branch only when merged” or “skip ideation plan targets.” The typed cause is for state/audit semantics; the selected product policy force-deletes the verified local branch for all terminal causes after the correct target is resolved.

6. Make fallback cleanup progress during the same process

Keep the periodic terminal sweep as crash/error recovery, but replace the global “any agent running” pause with a candidate-local check:

• skip only a candidate whose canonical path equals a live RunningAgentInfo.worktree_path;
• unrelated agents and projects must not block cleanup;
• repo or registry read errors fail closed for the affected candidate and leave it retryable.

Add a periodic orphan cleanup loop with a runtime-configured cadence. For each orphan candidate:

• skip only an exact live worktree-path match;
• retain conservative dirty and content-containment checks because no terminal DB authority exists;
• remove clean, contained orphans and their RalphX-owned branch;
• retry dirty/unsafe markers using the existing marker retry window.

Do not couple orphan cleanup to the terminal cleanup CAS because there is no workspace row to claim.

Affected Files

Backend application flow

• src-tauri/src/application/agent_workspace_terminal_cleanup.rs — mechanically extracted coordinator, typed causes/outcomes, runtime shutdown, CAS claim, process teardown, and cleanup orchestration.
• src-tauri/src/application/agent_workspace_terminal_cleanup_tests.rs — production-entry behavioral tests; no inline test module.
• src-tauri/src/application/mod.rs — module/test registration.
• src-tauri/src/application/services/pr_merge_poller.rs and its test surface — replace embedded terminalization with coordinator calls; mechanically move only the relevant existing tests/helpers.
• src-tauri/src/application/agent_workspace_external_pr_reconciliation.rs
• src-tauri/src/application/agent_workspace_pr_supervision_recovery.rs
• src-tauri/src/application/automation/merged_run_finalizer.rs
• src-tauri/src/application/agent_conversation_archive.rs — archive and explicit-close integration, typed archive result, and direct-vs-linked-plan cleanup target resolution.
• src-tauri/src/application/git_artifact_cleanup.rs and git_artifact_cleanup_tests.rs — force-owned terminal policy for direct workspace and linked plan-branch targets, plus path/branch guards.
• src-tauri/src/application/orphan_worktree_cleanup.rs and orphan_worktree_cleanup_tests.rs — candidate-local busy guard and periodic runner.
• src-tauri/src/application/startup_pipeline.rs — start the periodic orphan runner alongside terminal recovery.
• src-tauri/src/infrastructure/agents/claude/agent_config/runtime_config.rs, its tests, and config/ralphx.yaml — orphan cleanup interval.

Persistence

• src-tauri/crates/ralphx-domain/src/repositories/agent_conversation_workspace_repository.rs and tests — atomic claim/finalize contract.
• src-tauri/src/infrastructure/sqlite/sqlite_agent_conversation_workspace_repo.rs and tests — SQLite CAS and retry-candidate query.
• src-tauri/src/infrastructure/memory/memory_agent_conversation_workspace_repo.rs and tests — behaviorally equivalent test implementation.

IPC and frontend

• src-tauri/src/commands/unified_chat_commands/** — return an archive result that distinguishes logical archive success from cleanup outcome.
• frontend/src/api/chat.ts — zod snake_case response schema and camelCase transform for the archive result.
• frontend/src/components/agents/ArchiveConversationDialog.tsx — replace restart wording with an explicit irreversible local deletion warning covering uncommitted and ignored artifacts.
• frontend/src/components/agents/BulkArchiveConversationControls.tsx, bulkConversationArchive.ts, and useAgentConversationActions.ts — allow bulk archive to use archive-as-local-terminal-authority with closePullRequest=false, and show equivalent destructive warning/copy.
• Existing action tests plus new focused dialog tests — assert request options, cache invalidation, success/warning toast behavior, and user-visible copy.

Data / State

No migration is planned because local_cleanup_status and local_cleanup_checked_at are nullable text/timestamp columns.

State progression:

terminal authority persisted -> cleaning (CAS) -> cleaned | failed_unsafe | failed_operational

The CAS is keyed by the retained conversation workspace row even when the resolved local artifact target is a linked plan branch.

Recovery:

• stale cleaning -> eligible for retry after the configured terminal retry window;
• failed_operational -> retry periodically;
• failed_unsafe -> retry only after metadata changes or the retry window, while continuing to fail closed;
• legacy workspace_dirty|unsafe|target_ref_missing -> eligible under the new force-owned policy;
• missing verified worktree and branch -> cleaned.

The logical workspace row remains for history/UI. Cleanup must not delete conversation or workspace records.

Agent And MCP Surface

• No model-facing MCP schema or prompt changes.
• No run/orchestration IDs are added to any tool schema.
• Existing workspace publish/status tools continue reading the retained terminal workspace row.
• Terminal cleanup identity comes from the backend caller and persisted conversation/workspace state, never from model input.
• Archive IPC may return richer cleanup outcome data, but this is a Tauri/frontend contract change, not an agent tool change.

UI / UX

• Archive confirmation must say that archiving permanently deletes the local RalphX workspace, including uncommitted changes, ignored build/test artifacts, and the local workspace branch.
• Preserve the existing checkbox semantics: leaving “Close pull request” unchecked keeps the remote PR open, but still deletes the local workspace after archive authority is recorded.
• On cleaned, show the normal archive success behavior.
• On logical archive success plus retryable cleanup failure, remove the conversation from the active list, show a warning toast that local cleanup is pending automatic retry, and do not misreport the archive itself as failed.
• On unsafe metadata/path rejection, show a stronger warning with no raw filesystem deletion attempt.
• Bulk archive should stop pre-rejecting rows solely because they have a potential open PR. It should call the same archive backend path with closePullRequest=false, warn that local workspace artifacts will be deleted, leave remote PRs open by default, and summarize cleanup failures without restoring successfully archived rows.

Progression Scenarios

1. Merged while app remains open: poller persists merged -> one caller claims cleanup -> target runtime/processes stop -> dirty worktree is force-removed -> local branch is force-deleted -> marker becomes cleaned.
2. Remote PR closed: poller or reconciliation persists closed -> same forced local cleanup; unlike current behavior, the local branch is deleted.
3. Explicit close action: remote close is attempted and closed status persisted -> immediate coordinator call -> local workspace and branch removed without waiting for polling/restart.
4. Archive with remote PR left open: archive authority is persisted -> local workspace and branch are force-deleted -> remote PR remains open by explicit user choice.
5. Archive and close: remote close attempt and local closed state precede archive -> archive authority -> one local cleanup.
6. Duplicate poller/reconciliation observation: CAS winner performs cleanup; losers return already-in-progress/already-cleaned and cannot emit ENOENT failures or downgrade the marker.
7. Crash after claim: stale cleaning marker becomes retryable; missing worktree/branch normalize to cleaned.
8. Unrelated agent running: terminal/orphan cleanup continues; only the exact live worktree path is skipped.
9. Tampered DB path or branch: ownership/path validation fails closed, the project checkout is untouched, and the durable outcome is failed_unsafe.
10. Unknown orphan: periodic orphan cleanup remains conservative; dirty or uncontained orphan data is retained because no terminal authority exists.

Constraints

• TDD-first for terminal, archive, concurrency, and recovery regressions.
• Use the established GitService and path-safety sinks; no raw remove_dir_all or direct Git command in orchestration code.
• Preserve target-project vs RalphX runtime-root separation.
• Stop the target runtime and worktree processes before filesystem deletion.
• Use DbConnection::run/transactional SQLite paths; CAS must be atomic.
• Fail closed on repository, registry, path, or ownership read errors.
• Keep legacy persisted cleanup markers additive/derivable.
• Mechanical extraction only for moving terminalization and its existing tests.
• No direct task state writes; this work concerns agent workspace lifecycle, not the task state machine.
• Format only touched Rust leaf files and follow the selective Rust test commands.

Avoid

• No second cleanup manager alongside the extracted coordinator.
• No global “any agent running” pause.
• No status-only terminal update that waits for restart/periodic cleanup when an immediate caller exists.
• No force deletion based only on a stored DB path or branch string.
• No deletion of the main checkout, configured worktree parent, non-RalphX branch, remote branch, or unknown dirty orphan.
• No cleanup-success marker written before worktree and branch deletion both settle.
• No duplicate caller allowed to overwrite cleaned with branch_missing.
• No frontend message claiming restart is required.
• No broad formatter churn or unrelated worktree reclamation feature.

Proof Obligations

1. A merged, closed, explicitly closed, or archived workspace is locally removed during the triggering app process.
2. A dirty worktree with ignored test/build artifacts is removed after terminal authority, matching the selected force policy.
3. The associated verified local branch is absent for merged, closed, and archived causes, including linked plan-branch PR targets.
4. Project root, worktree parent, mismatched stored path, malformed branch, and non-owned branch are never deleted.
5. Two concurrent terminal observers cause at most one destructive cleanup attempt and leave a monotonic cleaned outcome.
6. Runtime stop/fail authority is verified before deletion; an active target run blocks cleanup.
7. Cleanup failure is durable, visible to the caller where applicable, and retryable without false archive failure.
8. A crash/retry with one or both local artifacts already absent converges to cleaned.
9. An unrelated running agent does not prevent terminal or orphan progress; an exact matching live worktree does.
10. Unknown orphan cleanup remains conservative and cannot inherit terminal force authority.
11. All entry paths use the coordinator; no old poller-local terminalization remains.
12. UI warning copy accurately describes irreversible local deletion and remote-PR checkbox semantics.

Decisions

• Chosen by user: force-delete dirty local artifacts and local-only branch commits after authoritative merge, close, or archive; path containment and branch ownership remain non-bypassable.
• Use one extracted application coordinator and atomic repository claim.
• Keep workspace/conversation rows for history.
• Force-delete local branches for all terminal causes, not only merged PRs.
• Keep remote branch deletion out of scope.
• Keep unknown-orphan cleanup safe rather than forced.
• Archive remains logically successful when local cleanup needs retry; return and surface the cleanup outcome separately.
• Periodic terminal/orphan passes are recovery mechanisms, not the normal archive/close path.

Testing Strategy

Write failing tests before production changes:

Backend behavioral tests

• Poller merged path force-removes a dirty worktree, ignored artifact directory, and local branch.
• Poller closed path now removes both worktree and branch.
• Explicit-close production entry removes both immediately.
• Archive without remote close removes local state while leaving remote-close call count at zero for direct workspace and linked plan-branch targets.
• Archive with close invokes remote close once and local cleanup once.
• Concurrent poller/external reconciliation calls yield one CAS winner and one Git deletion.
• Duplicate cleanup after success leaves cleaned, not branch_missing.
• Stale cleaning and failed_operational candidates retry; already-missing artifacts converge to cleaned.
• Active target runtime blocks deletion; unrelated runtime does not.
• Dirty unknown orphan remains; clean contained orphan is removed by the periodic runner in the same process.
• Stored project-root path, mismatched path, traversal/malformed ref, and non-owned branch produce failed_unsafe with absence assertions for destructive Git calls.
• SQLite and memory repositories both prove CAS wrong-from leaves state untouched and only one concurrent claim succeeds.

Frontend tests

• Archive dialog renders the irreversible deletion warning.
• Bulk archive confirmation renders equivalent warning and no longer pre-rejects an otherwise eligible workspace solely because the remote PR may remain open.
• Archive action sends the existing close-PR option.
• Cleaned result follows normal success/cache invalidation.
• Archived-plus-pending-cleanup result shows warning and does not restore the conversation.
• Unsafe cleanup result has distinct user-visible copy.

Validation commands

• Focused Rust filters for the new coordinator, artifact cleanup, archive, repository CAS, and orphan runner.
• cargo nextest run --manifest-path src-tauri/Cargo.toml --lib --features test-utils for the broader backend library surface.
• rustfmt --edition 2021 --check on every touched Rust leaf file only.
• Both required cargo clippy gates and python3 scripts/check-layering.py.
• cd frontend && npm run test:run -- <touched test files>.
• Frontend typecheck/lint through configured npm run scripts.
• Review the final diff against HEAD, then run the stateful false-success lens: stale claim, read failure, duplicate event, event ordering, and path sink checks.

---

Generated by RalphX

[codecov]

Codecov Report

❌ Patch coverage is 92.72468% with 51 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src-tauri/src/application/git_artifact_cleanup.rs	85.71%	17 Missing ⚠️
...rc/application/agent_workspace_terminal_cleanup.rs	95.29%	15 Missing ⚠️
...c/components/agents/useAgentConversationActions.ts	66.66%	7 Missing ⚠️
...auri/src/application/agent_conversation_archive.rs	91.30%	6 Missing ⚠️
...sqlite/sqlite_agent_conversation_workspace_repo.rs	91.30%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!