docs(components): document app cleanup on shutdown via scope 'close'

[Ethan-Arrowood]

Summary

Shutdown cleanup for applications was technically documented but undiscoverable: the entire coverage was one line in the Scope events list in plugin-api.md — "Emitted after scope.close() is called" — which reads as if the plugin author calls scope.close() themselves. Nothing said Harper calls it, which is the whole reason an application would listen for the event.

• reference/components/plugin-api.md — new ## Cleanup on Shutdown section with the scope.once('close', ...) pattern, stating that Harper calls scope.close() on shutdown and on graceful restart. Clarified the 'close' event bullet and the scope.close() entry in place, and linked both to the new section.
• reference/components/applications.md — new ## Shutdown Cleanup pointer cross-linking to it. That page previously had zero occurrences of "cleanup", "shutdown", or "teardown", so the application-building audience had nothing to find.
• Added a Version History entry for the v5.1.3 behavior change.

Source evidence

Verified in HarperFast/harper at v5.2.6 (latest release) before writing:

1. The loader calls scope.close() on shutdown — components/componentLoader.ts:700:

   onMessageByType(ITC_EVENT_TYPES.SHUTDOWN, () => trackScopeClose(scope.close()));

2. Graceful restart uses the same path — restartWorkers posts the same SHUTDOWN ITC message (server/threads/manageThreads.js:555-559), reached from bin/restart.ts:187 (restart operation) and manageThreads.js:1218 (dev watch reload).
3. Async 'close' listeners are awaited — components/Scope.ts:275-288 collects this.listeners('close') and await Promise.all(...) over their return values.
4. Exit waits for scope cleanup — server/threads/threadServer.js:205-211: .then(() => closeServers()).then(() => whenScopesClosed()).then(() => realExit(0)), backed by the components/scopeShutdown.ts registry (which logs a rejected close and treats it as settled, so failed cleanup can't wedge shutdown).
5. Cleanup is bounded — worker self-exit backstop at threadTerminationTimeout (10s; 30s under DEV_MODE) in manageThreads.js:87-105, with the main thread force-terminating at 2x (manageThreads.js:585).

Status of HarperFast/harper#1912

Still open, but the code it describes has already been fixed and released — so this PR documents the corrected behavior rather than the caveat the issue asked for.

harper#1912 cites Scope.ts:181-187 (bare this.emit('close')), componentLoader.ts:472 (fire-and-forget scope.close()), and threadServer.js:175-177 (closeServers().then(() => realExit(0))). That is the pre-fix layout. Both halves of its "Suggested direction" landed in commit d72d5b0 ("fix: dispose component scopes before worker exit in dev, and serialize reloads", harper#1323).

Bisecting the release tags for the awaited-listener code in components/Scope.ts:

Releases	Behavior
v5.0.0 - v5.1.2	bare emit('close') — async cleanup raced process.exit
v5.1.3 - v5.2.6	awaits 'close' listener promises

So the docs state that async cleanup is awaited, with the remaining genuine caveat being the termination backstop. harper#1912 looks stale and is probably closable — flagging rather than acting on it here.

Notes (not addressed in this PR)

npm run build reports two pre-existing broken anchors in files this PR does not touch:

• /reference/v5/backups/overview -> /reference/v5/cli/commands#backing-up-with-volume-snapshots
• /release-notes/v5-lincoln/5.1 -> #deployment-operations

Also, the repo's committed node_modules state was missing @harperfast/code-guidelines, so format:check fails in a stale checkout until npm ci is re-run.

Verification

• npm run format:check — clean
• npm run build — succeeds; all anchors added by this PR validate

Closes #604

🤖 Generated with Claude Code

[gemini-code-assist]

Code Review

This pull request adds documentation for application shutdown cleanup and updates the Plugin API reference to detail how scope.close() and 'close' event listeners handle asynchronous cleanup in version 5.1.3. The review feedback suggests style guide corrections to use hyphens instead of em dashes as field separators, and recommends adding a <VersionBadge> component to highlight the behavior change in scope.close().

[gemini-code-assist]

According to the general rules, hyphens (-) should be used instead of em dashes (—) as field separators in Markdown documentation (e.g., separating configuration option names from their descriptions). Please update the 'close' event description to use a hyphen.

Suggested change

	- **`'close'`** — Emitted after `scope.close()` is called. Harper calls `scope.close()` itself on shutdown and on graceful restart, so this is the hook for application teardown — see [Cleanup on Shutdown](#cleanup-on-shutdown)
	- **`'close'`** - Emitted after `scope.close()` is called. Harper calls `scope.close()` itself on shutdown and on graceful restart, so this is the hook for application teardown — see [Cleanup on Shutdown](#cleanup-on-shutdown)

References

1. In Markdown documentation, use hyphens ('-') instead of em dashes ('—') as field separators (e.g., separating configuration option names from their descriptions) to adhere to the style guide, even if the file has pre-existing inconsistencies using em dashes.

[Ethan-Arrowood]

Not taking this one. The em-dash rule is being over-generalized here.

AGENTS.md says em dashes "are fine for parenthetical asides and match existing prose; do not use them as field separators." The field-separator prohibition refers to the bullet immediately above it - Type: / Default: reference blocks, where each field goes on its own line. It is not a ban on - **term** — description in prose lists.

Two checks: the docs tree has 633 em-dash list-item lines across 63 reference files, and AGENTS.md itself uses this exact pattern - including in the rule being quoted (- **Hyphens vs. dashes** — em dashes...).

So these are the established convention, not "pre-existing inconsistencies." Applying the suggestion would leave the touched lines inconsistent with every sibling line in the same list.

_{sent with Claude Opus 5}

[gemini-code-assist]

When documenting behavior changes to an existing API surface, we should use the component for standalone placement after headings. Since the behavior of scope.close() awaiting 'close' listener promises was introduced in v5.1.3, let's add a right after the heading.

Suggested change

	#### `scope.close()`
	Closes all associated entry handlers and the `scope.options` instance, emits `'close'`, and removes all listeners.
	Closes all associated entry handlers and the `scope.options` instance, emits `'close'`, and removes all listeners. Promises returned by `'close'` listeners are awaited before it resolves.
	#### `scope.close()`
	<VersionBadge type="changed" version="v5.1.3" />
	Closes all associated entry handlers and the `scope.options` instance, emits `'close'`, and removes all listeners. Promises returned by `'close'` listeners are awaited before it resolves.

References

1. When documenting behavior changes to an existing API surface (e.g., adding new fields to a response), use .
2. Reserve the component for standalone placement after headings. For inline version annotations mid-sentence or inside list items, use plain text (e.g., (vX.Y.Z)) instead, as using the component mid-sentence is awkward.

[gemini-code-assist]

According to the general rules, hyphens (-) should be used instead of em dashes (—) as field separators in Markdown documentation. Please update the v5.1.3 version history entry to use a hyphen.

Suggested change

	- **v5.1.3** — Shutdown awaits promises returned by `'close'` listeners; earlier releases emitted `'close'` without waiting, so async cleanup could be cut off by the worker exiting
	- **v5.1.3** - Shutdown awaits promises returned by `'close'` listeners; earlier releases emitted `'close'` without waiting, so async cleanup could be cut off by the worker exiting

References

1. In Markdown documentation, use hyphens ('-') instead of em dashes ('—') as field separators (e.g., separating configuration option names from their descriptions) to adhere to the style guide, even if the file has pre-existing inconsistencies using em dashes.

[Ethan-Arrowood]

Not taking this one. The em-dash rule is being over-generalized here.

AGENTS.md says em dashes "are fine for parenthetical asides and match existing prose; do not use them as field separators." The field-separator prohibition refers to the bullet immediately above it - Type: / Default: reference blocks, where each field goes on its own line. It is not a ban on - **term** — description in prose lists.

Two checks: the docs tree has 633 em-dash list-item lines across 63 reference files, and AGENTS.md itself uses this exact pattern - including in the rule being quoted (- **Hyphens vs. dashes** — em dashes...).

So these are the established convention, not "pre-existing inconsistencies." Applying the suggestion would leave the touched lines inconsistent with every sibling line in the same list.

_{sent with Claude Opus 5}

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-647

This preview will update automatically when you push new commits.

[github-actions]

🚀 Preview Deployment

Your preview deployment is ready!

🔗 Preview URL: https://preview.harper-documentation.harperfabric.com/pr-647

This preview will update automatically when you push new commits.