Redesign lifecycle event registration in BoundDestinationLifecycle

[couimet]

Summary

Redesign lifecycle event registration in BoundDestinationLifecycle from hard-coded per-type listener methods to a LifecycleEvent interface / hook-based abstraction that destination types implement. Currently each lifecycle event (terminal close, document close) is wired as a separate private method with destination-type branching. A generic LifecycleEvent interface with hooks (e.g., onClose, onDelete) that destination types implement would make adding new destination types and new lifecycle events trivial without modifying the lifecycle module itself.

Motivation

The initial BoundDestinationLifecycle extraction (see separate issue) is a pure extraction — moving existing listener logic out of PasteDestinationManager without changing behavior. The current design has each listener as a separate method (setupTerminalCloseListener, setupDocumentCloseListener) with switch-on-type logic inside. Adding a new destination type (e.g., file-picker output channel) or a new lifecycle event (e.g., file deletion) requires adding a new method and new branching. A hook-based design means you just implement the relevant interface on the destination class.

Proposed Design

• Define a LifecycleEvent interface (or set of interfaces) that exposes hooks like onClose(lifecycleContext): Disposable, onDelete(lifecycleContext): Disposable, etc.
• Destination types (TerminalDestination, TextEditorDestination) implement the hooks relevant to their lifecycle. Terminal implements onClose. TextEditor implements onClose and can optionally implement onDelete.
• BoundDestinationLifecycle iterates registered destinations and collects their hooks at bind time. When an event fires (e.g., VS Code onDidCloseTerminal), the lifecycle module dispatches to the relevant hook implementations instead of running hard-coded per-type listeners.
• The lifecycleContext parameter provides each hook with the unbind function, logger, and VS Code adapter so hooks can perform their cleanup without importing PasteDestinationManager directly.

Relevant Code

• Terminal close listener: PasteDestinationManager.ts lines 382-404 — checks isTerminalDestination, compares terminal identity, calls unbind
• Document close listener: PasteDestinationManager.ts lines 658-697 — checks isEditorDestination, compares URI, handles isClosed=false for language-mode transitions, calls unbind
• Both follow the same structural pattern: guard → compare identity → handle edge case → log → unbind → status bar message

Backward Compatibility

All existing behavior must be preserved:

• Terminal auto-unbind on terminal close (silent unbind + status bar message)
• Text editor auto-unbind on document close (with isClosed=false language-mode transition guard)
• Lazy unbind strategy (unbind only on actual close, not tab switch)
• Status bar messages (STATUS_BAR_DESTINATION_UNBOUND_TERMINAL_CLOSED, STATUS_BAR_DESTINATION_UNBOUND_EDITOR_CLOSED)

Tasks

1. Design and define LifecycleEvent interface(s) with hook signatures
2. Implement hooks on TerminalDestination and TextEditorDestination
3. Refactor BoundDestinationLifecycle to collect hooks at bind time and dispatch events
4. Remove the two private listener setup methods after migration
5. Add unit tests for: hook registration, event dispatch routing, edge cases (language-mode transition, unmatched terminal/editor), and the contract that adding a new destination type with hooks works without modifying BoundaryDestinationLifecycle
6. Verify backward compatibility via existing integration tests

Dependencies

Depends on: BoundDestinationLifecycle extraction (#610). This redesign should not begin until that extraction is merged, as it builds on the extracted module.

Non-goals

• No new lifecycle events beyond what currently exists (close is the only one); the interface should be extensible but this issue only refactors existing events
• No changes to PasteDestinationManager's bind/unbind flow
• No changes to status bar messages or logging format

[couimet]

Parking this for 2.1.0+. Capturing the assessment from planning so it's not rediscovered later.

Honest read on the refactor

Sits between "real architectural win" and "moderate gold-plating." The dispatch-via-handler pattern is better than guard-branching, but the issue body's framing (LifecycleEvent interface / hooks / contexts) pulls toward more abstraction than the problem warrants.

Real wins worth keeping

• BoundSession stops needing isTerminalDestination / isEditorDestination guards and stops knowing about terminal-identity comparison, URI comparison, and the isClosed=false language-mode gotcha. Genuine concern split.
• isInDuplicateTabState moves from class field (reset in clear()) to closure variable (reset by re-registration). Unambiguously cleaner.
• Per-handler tests can be much more focused than BoundSession.test.ts setting up the whole dispatch machinery to test one event path.

Gold-plating tells in the original plan

• Creating a file for a 5-line interface and a 6-line context type. Keep both inline in BoundSession.ts (or one lifecycle.ts next to it) until a second consumer appears.
• Handler classes add nothing over closures. Every handler is stateless except one let isInDuplicateTabState that wants to be a closure variable anyway. Prefer type LifecycleEventHandler = (ctx) => vscode.Disposable over interface { register(ctx) } + new TerminalCloseLifecycleHandler().
• The "extensibility contract" test (verify a test-defined handler can register without modifying BoundSession) is testing the framework, not the code. Drop it.

Claims to scrutinize

• "Open/closed" is real but smaller than the issue implies. Adding a new destination type today already requires editing the discriminated union, the factory, and the type guards — touching BoundSession is one more line among many. The framework saves that one line, not a whole class of churn.
• Subscription lifetime changes from "once at construction" to "per-bind." Functionally equivalent (the current listeners no-op when nothing is bound) but a real semantic shift worth flagging in the commit message.

Timing rationale

• Pure refactor with no user-visible behavior — defers cleanly out of a major release. Doing risky cleanup right before 2.0.0 trades real risk for zero user benefit.
• The dependents (file-delete, file-rename auto-unbind per Extract BoundDestinationLifecycle from PasteDestinationManager #610) are user-visible and decided independently. They can ship on the current setupXxxListener pattern without this refactor.
• The refactor is cheapest when bundled with the next two events: writing them as handlers from the start avoids the write-then-refactor cycle. So bundling Redesign lifecycle event registration in BoundDestinationLifecycle #612 with file-delete/rename in 2.1.0 is the highest-leverage ordering.
• Also: by the time there are 5 listeners, the branching pattern will either still look fine or clearly look like a mess. That signal is worth more than guessing now.

When revisiting

Apply the simplifications above: handlers as functions, types inline until a second module needs them, drop the contract test. That cuts ~3 new files and ~50 lines of test ceremony without losing any decoupling.