[AlaeddineMessadi]

Description of the Change

Problem

The installer considers PentAGI installed only when the pentagi container exists. After docker rm/docker rmi, the pentagi-postgres-data volume survives, and the installer's own PentagiVolumesExist check detects it (checker.go#L434-L442). Only credential hardening reads that flag, though. So the main menu offers Install as if the host were clean, Apply Changes says "PentAGI is not currently installed", and the new stack silently starts on the old database, with the old admin password. That is the situation in #432.

In the same state, Purge PentAGI and Factory Reset are hidden, because CanPurgeAll/CanFactoryReset only look at installed containers. Until the stack is installed again, the only way to clear that database is docker volume rm by hand.

Solution

This implements what I proposed in the comment on #432:

• When PentagiVolumesExist is set and the container is missing, the Install screen and the Apply Changes screen show a warning: "The existing PentAGI database will be reused, with its accounts, passwords and flows. Purge PentAGI or Factory Reset removes it".
• CanFactoryReset and CanPurgeAll also accept leftover PentAGI volumes, so Maintenance lists both in that state. Both run docker compose down -v, which removes the declared volumes without needing a container. I checked this against Docker Engine 29.7.2 and Compose v5.5.0 with a throwaway project: removing the container and image first, then running down --rmi all -v, printed "Volume … Removed". Remove PentAGI is still listed only for an installed stack, since its plain down leaves the volumes behind.

Refs #432

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• 🚀 New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🔧 Configuration change
• 🧪 Test update
• 🛡️ Security update

Areas Affected

• Core Services (Frontend UI/Backend API)
• AI Agents (Researcher/Developer/Executor)
• Security Tools Integration
• Memory System (Vector Store/Knowledge Base)
• Monitoring Stack (Grafana/OpenTelemetry)
• Analytics Platform (Langfuse)
• External Integrations (LLM/Search APIs)
• Documentation
• Infrastructure/DevOps (the installer TUI)

Testing and Verification

Test Configuration

PentAGI Version: main @ cffed94
Docker Version: 29.7.2 (Compose v5.5.0) for the down -v check; unit tests need none
Host OS: Linux
LLM Provider: n/a
Enabled Features: n/a
Go: 1.26.5

Test Steps

1. cd backend && go generate ./cmd/installer/files/
2. go test ./cmd/installer/... -race -count=1
3. go vet and golangci-lint v2.12.2 on the touched packages

Test Results

All installer packages pass with -race; go vet and golangci-lint report nothing. New tests, each with rows for volumes left behind, volumes with a running container, and a clean host:

• TestChecker_CanFactoryReset_OffersToRemoveVolumesThatOutlivedTheirContainer
• TestChecker_CanPurgeAll_OffersToRemoveVolumesThatOutlivedTheirContainer
• TestChecker_CanRemoveAll_IgnoresVolumesThatOutlivedTheirContainer
• TestApplyChanges_GetHelpContent_WarnsThatInstallReusesALeftoverDatabase
• TestProcessorOperationForm_GetHelpContent_WarnsThatInstallReusesALeftoverDatabase, which also checks that the Purge and Factory Reset screens do not show the warning

With the production files reverted to main and the tests kept:

--- FAIL: TestChecker_CanFactoryReset_OffersToRemoveVolumesThatOutlivedTheirContainer/volumes_left_behind_by_a_removed_container
--- FAIL: TestChecker_CanPurgeAll_OffersToRemoveVolumesThatOutlivedTheirContainer/volumes_left_behind_by_a_removed_container
--- FAIL: TestApplyChanges_GetHelpContent_WarnsThatInstallReusesALeftoverDatabase/volumes_left_behind_by_a_removed_container
--- FAIL: TestProcessorOperationForm_GetHelpContent_WarnsThatInstallReusesALeftoverDatabase/volumes_left_behind_by_a_removed_container

Removing the operation == Install condition fails the Purge and Factory Reset rows.

Security Considerations

None new. Purge and Factory Reset keep their existing confirmation; they are only listed in one more state.

Performance Impact

None.

Documentation Updates

• README.md updates
• API documentation updates
• Configuration documentation updates
• GraphQL schema updates
• Other:

Deployment Notes

None.

Checklist

Code Quality

• My code follows the project's coding standards
• I have added/updated necessary documentation
• I have added tests to cover my changes
• All new and existing tests pass
• I have run go fmt and go vet (for Go code)
• I have run pnpm run lint (for TypeScript/JavaScript code)

Security

• I have considered security implications
• Changes maintain or improve the security model
• Sensitive information has been properly handled

Compatibility

• Changes are backward compatible
• Breaking changes are clearly marked and documented
• Dependencies are properly updated

Documentation

• Documentation is clear and complete
• Comments are added for non-obvious code
• API changes are documented

Additional Notes

Two limits come from code that is already on main and are left as they are:

• If docker-compose.yml was deleted as well, performStackOperation skips the PentAGI stack (processor/compose.go). Purge then reports success but leaves the volumes.
• PentagiVolumesExist matches the volume names by suffix, and it also counts pentagi-ssl and scraper-ssl. If only those are left, the warning about the database overstates the case.