docs(components): scope shutdown cleanup to what needs an explicit hook

Address review feedback on the new shutdown cleanup coverage.

The section listed timers and open connections as things an application
is responsible for tearing down. Node closes timers and sockets itself
when a thread exits, so presenting them as the app's job is misleading.
Reframe both the plugin-api.md section and the applications.md pointer
around work that genuinely needs a hook: flushing buffered writes,
deregistering from an external service, releasing a distributed lock,
or closing a connection whose remote side expects a graceful goodbye.

Also drop the incorrect justification for `scope.once()`. It claimed
`once` avoids leaving a listener behind during a reload, but
`Scope.close()` detaches its `'close'` listeners as part of closing and
a reload builds a new Scope, so `on()` cannot strand a listener on a
closed scope either. Recommend `once()` on the honest grounds that
closing is a one-time lifecycle event.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: Ethan-Arrowood

reference/components/applications.md

@@ -68,7 +68,7 @@ harper deploy \
 
 ## Shutdown Cleanup
 
-Applications that start background work — a service, a timer, a connection pool, a buffer that needs flushing — should tear it down when Harper stops or restarts. Restarts are frequent during local development, since `harper dev` restarts worker threads on every file change, and deploying with `restart=true` does the same on a running instance.
+Applications with work that must complete, or be acknowledged outside the process, before a thread exits — buffered writes to flush, a registration to withdraw from an external service, a distributed lock to release — need a hook to do it when Harper stops or restarts. Restarts are frequent during local development, since `harper dev` restarts worker threads on every file change, and deploying with `restart=true` does the same on a running instance.
 
 Harper signals this by calling `scope.close()` on each worker thread, which emits a `'close'` event on the plugin API [`Scope`](./plugin-api.md#class-scope). Listen for it to run cleanup:
 

reference/components/plugin-api.md

@@ -387,7 +387,7 @@ Function signature for the `'all'` event handler passed to `scope.handleEntry()`
 
 Harper calls `scope.close()` on every application scope when a worker thread shuts down, which emits the [`'close'`](#events) event. This happens both when Harper is stopping and on a graceful restart — including the automatic worker restarts triggered by `harper dev` file watching and by the `restart` operation.
 
-Listen for `'close'` to release anything the plugin or application acquired at load time: background services, timers, open connections, or buffered work that needs flushing.
+Listen for `'close'` to finish work that must complete, or be acknowledged outside the process, before the thread goes away: flushing buffered writes, deregistering from an external service or registry, releasing a distributed lock or lease, or closing a connection whose remote side expects a graceful goodbye. Node tears down timers and sockets on its own when a thread exits, so purely in-process resources need no `'close'` listener.
 
 ```js
 export function handleApplication(scope) {
@@ -398,7 +398,7 @@ export function handleApplication(scope) {
 }
 ```
 
-Use `scope.once()` rather than `scope.on()` — the scope is closed once per worker lifetime, and `once` avoids leaving a listener behind if the plugin registers during a reload.
+Use `scope.once()` rather than `scope.on()` — closing is a one-time lifecycle event, so `once()` expresses that intent.
 
 Notes on the shutdown sequence: