kandev/docs/plans/plugin-reliability/task-01-backend-diagnostics.md

status

status
done

Task 01: Persist plugin failure diagnostics

Objective

Carry failure causes through the supervised runtime and persist them on plugin records so operators can recover an errored plugin with a useful explanation.

Scope

• apps/backend/internal/plugins/store/
• apps/backend/internal/plugins/registry.go
• apps/backend/internal/plugins/service.go
• apps/backend/internal/plugins/service_sync.go
• apps/backend/internal/plugins/runtime/
• Related backend tests.

Requirements

• Add nullable last_error and last_error_at record fields with backward- compatible load/save behavior.
• Normalize stored diagnostics to one line and at most 2048 bytes; redact PATs, bearer tokens, labeled passwords/tokens/secrets/API keys, and the host home path before persistence. Do not store arbitrary plugin stdout or configuration.
• Propagate the triggering error through unhealthy runtime callbacks.
• Persist diagnostics for activation, boot/config restart, health failure, restart exhaustion, and missing install paths.
• Clear diagnostics on successful activation/recovery and retain them across an explicit disable.
• Preserve the existing error -> active transition and rollback guarantees.
• Never hold Manager.mu while waiting for process.stop(), so restart exhaustion and concurrent manual Enable cannot wait on each other.

Test-first acceptance

• Store round-trips fields and loads records written before the fields existed.
• Newline and overlong errors are normalized deterministically.
• PAT, bearer, labeled-secret, and home-path values are absent from persisted diagnostics while safe host error context remains.
• Service tests cover failed enable, successful retry, failed retry replacement, health failure, recovery, and missing install path.
• Runtime tests prove ping/crash causes reach the manager callback and healthy recovery carries no error; a barrier-based concurrent Enable/restart-exhaustion test proves both operations complete.

Dependencies

None. This is the API contract consumed by task 03.