[bandzalkin]

Summary

run_forever() now says why it ended. A host stop() or disconnect() returns normally, including when the platform drops the socket during shutdown. A terminal platform disconnect, such as another connection with the same agent key superseding this one, raises AgentDisconnectedError carrying the typed WebSocketDisconnectReason. Agent.last_disconnect_reason stays readable after stop(), and a fresh connect() clears it.

Changes

• AgentDisconnectedError(reason) subclasses BandConnectionError and is exported from band.
• BandLink.run_forever() raises it when a terminal reason is recorded and the host did not ask to disconnect. disconnect() records that request before teardown.
• connect() clears both the reason and the host-request flag.
• PlatformRuntime.last_disconnect_reason and Agent.last_disconnect_reason expose the link's reason (None before the link exists).
• Real-wire tests: supersede raises with reason.reason == "session.already_connected"; an explicit stop returns even if a supersede landed first; reconnect clears the reason.
• Docs: disconnect section in docs/adapters/managed-host-adapters.md, including the compatibility note that a supersede used to return quietly.

Related Issues

Split out of #666 (S-7). Stacked on #697 (feat/host-signal-ownership); review and merge that first.

Testing

• Unit tests pass (uv run --all-packages pytest tests/ --ignore=tests/integration/ --ignore=tests/e2e/ -q -p no:cacheprovider) — 5926 passed, 156 skipped
• uv run ruff check . and uv run ruff format --check .
• uv run --all-packages pyrefly check — 0 errors
• uv run pytest --markdown-docs docs -q -p no:cacheprovider — 25 passed

Checklist

• PR title follows Conventional Commits format
• Code follows project style guidelines
• Tests added/updated as needed
• Documentation updated as needed

[bandzalkin]

Superseded by #843, refreshed on current upstream main with a fork-owned maintenance branch. The replacement records the corrected behavior, actual dependencies, own-delta review/replay base, local verification, and the private-core coverage limitation for fork PRs. This closes the superseded proposal only: no merge, fork-main integration, or source-branch deletion. Original PR history and branch are retained.