How should stateful cleanup failures be surfaced?

[PierrunoYT]

Policy question

Several ownership boundaries currently represent cleanup as func() or discard terminal errors, so callers cannot distinguish best-effort hygiene from teardown that may leave locks, processes, policy grants, or transports behind.

Examples at audited main revision 1b5db1765672820caac1684b168c9898b5ba3593 include:

• MCP permission-store unlock/close is returned as func() and both errors are ignored (internal/mcp/permissions.go, lockStateFile);
• execution preparation/transport cleanup callbacks are func(), so adapter/PTY teardown cannot contribute to the process result (internal/execution/process_manager.go);
• daemon pool drain logs a straggler and discards WorkerHandle.Kill() errors (internal/daemon/pool.go);
• agent permission cleanup is a stack of func() callbacks with no result (internal/agent/loop.go).

Routine response-body closes and temporary-file removal should not automatically fail successful operations. The question is which cleanup failures change durable or externally observable state and therefore must be returned, joined, or recorded.

Audit context: finding REL-01. No single user-visible failure was reproduced, so this is a design/ownership discussion rather than one bundled bug report.

Proposed classification

1. Stateful/actionable: unlock failure, failed process termination, failed revocation of a permission/resource, failed durable flush or atomic publication. Return or join this error when the caller can act.
2. Advisory but operationally important: transport close after the result is already final, redundant cleanup, temporary artifact removal. Emit bounded, structured, redaction-safe diagnostics.
3. Expected/idempotent: already closed, already absent, cancellation superseded by a primary result. Suppress only when the exact error is known to be benign.

Questions

• Which existing cleanup callbacks need to become func() error, and which should remain best-effort?
• Should process results carry a separate cleanup/adapter error field, use errors.Join, or preserve a primary error plus diagnostics?
• Where should terminal cleanup diagnostics go in TUI/headless/daemon modes without exposing paths or secrets?
• How should repeated close/drain calls report prior failure while remaining idempotent?
• Which failure injectors are acceptable for deterministic tests on Unix and Windows?

Acceptance properties for later scoped work

• one issue/PR per concrete ownership boundary, not a repository-wide signature rewrite;
• tests inject the exact cleanup failure and prove the old behavior loses it;
• multiple actionable errors remain inspectable with errors.Is/errors.As;
• success is not reported if required durable unlock/publication/termination failed;
• advisory cleanup cannot overwrite the primary result or leak credentials; and
• existing idempotent close and cancellation behavior remains.

Full audit detail: https://github.com/PierrunoYT/zero/blob/audit/codebase-audit-2026-09-08/docs/audit/CONCURRENCY_AUDIT.md#rel-01--stateful-cleanup-errors-are-inconsistently-observable