test(session): characterize lifecycle interleavings

[benvinegar]

Summary

• characterize repeated and concurrent client startup settlement
• freeze manual-start behavior while an automatic retry retains its original deadline
• cover generic connection restart after synchronous construction failure and natural generation completion
• cover terminal shutdown while startup or reconnect preparation settles late
• record the known Hunk client retained-connection regression as a focused test.todo for the next stacked PR

Stack

1. This PR: lifecycle characterization
2. Next: recover from synchronous socket construction failure
3. Then: explicit startup states, lifecycle clock, generation fences, runtime exit fixtures, and bounded defect reporting

Non-goals

• no production behavior changes
• no Effect adoption or lifecycle runtime
• no fix for the retained failed connection in this PR

Validation

• bun test packages/session-broker/src/connection.test.ts src/session/broker/brokerClient.test.ts — 38 pass, 1 intentional todo
• bunx oxfmt --check packages/session-broker/src/connection.test.ts src/session/broker/brokerClient.test.ts .changeset/quiet-lifecycles-characterize.md
• bun run typecheck
• bun run lint
• bun run deps:check
• two independent reviewer passes; no remaining blocker/high/medium findings after removing implementation-specific assertions

The repository-wide format command also scanned ignored .pi-subagents handoff artifacts created during review and reported only those files; the changed files pass the targeted formatter check.

This PR description was generated by Pi using gpt-5.6-sol

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 31, 2026 7:44pm

[greptile-apps]

Greptile Summary

This PR adds characterization coverage for session connection and client lifecycle interleavings without changing production behavior.

• Covers repeated and concurrent startup, manual starts during scheduled retries, restart after natural completion, and terminal shutdown during pending preparation.
• Adds deterministic timer, deferred-promise, and WebSocket-observer fixtures.
• Records the known retained-connection regression as an intentional follow-up todo.

Confidence Score: 4/5

The PR appears safe to merge, with non-blocking test-maintainability issues around unchecked partial mocks and cleanup of process-wide replacements.

The lifecycle assertions align with the current production guards, while the accepted concerns are limited to fixture type safety and preventing cascading test contamination if setup fails.

Files Needing Attention: src/session/broker/brokerClient.test.ts

Important Files Changed

Filename	Overview
packages/session-broker/src/connection.test.ts	Adds focused connection-level lifecycle characterization for synchronous construction failure, natural completion, and late reconnect preparation.
src/session/broker/brokerClient.test.ts	Adds client lifecycle race coverage, but its partial mocks bypass repository typing conventions and its global replacements are installed before cleanup is protected.
.changeset/quiet-lifecycles-characterize.md	Adds an intentionally empty changeset for the test-only change.

Prompt To Fix All With AI

### Issue 1
src/session/broker/brokerClient.test.ts:164
**Unchecked partial test doubles**

The new credentials, timer, WebSocket, and client fixtures use `as any` or `as unknown as`, contrary to the repository convention of using `@total-typescript/shoehorn` for partial mocks. These casts suppress structural checks, so production interface changes can leave the lifecycle tests compiling against stale or incomplete fixture shapes.

### Issue 2
src/session/broker/brokerClient.test.ts:719
**Global mocks precede cleanup guard**

The deterministic clock is installed before the restoring `try/finally` begins, and the later test repeats this pattern for both timers and WebSocket. A setup exception in that gap leaves process-wide replacements active because `afterEach` does not restore them, causing cascading hangs or misleading failures in subsequent tests.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "test(session): characterize lifecycle in..." | Re-trigger Greptile}