refactor(session): model startup lifecycle states

[benvinegar]

Summary

• replace separate startup Promise, retry timer, and stopped flag ownership with one discriminated lifecycle state
• explicitly model idle, one attempting state with optional retained-retry ownership, waiting, and stopped transitions
• retain original retry deadlines during manual startup and fence stale timer/Promise callbacks by identity
• preserve synchronous terminal stop, connection rollback, and existing protocol/auth/session behavior
• guard terminal stop against synchronous warning-side reentrancy

Stack

1. test(session): characterize lifecycle interleavings #949 — lifecycle characterization
2. fix(session): recover from socket startup failures #950 — synchronous socket-start rollback
3. This PR: explicit startup lifecycle states
4. Next: plain TypeScript lifecycle clock
5. Then: generation fences, runtime exit fixtures, and bounded defect reporting

Base branch: fix/session-socket-start-rollback. Review only the third commit for this PR.

Validation

• focused connection/client lifecycle tests — 43 pass
• full direct unit suite — 3,636 pass, 12 skip
• bun run typecheck
• changed-file formatting
• bun run lint
• bun run deps:check
• Node broker conformance
• two review rounds; a reentrant-stop defect and deadline-test weakness were fixed, then a duplication audit collapsed the paired active states and centralized warning capture; final review approved with no blocker/high/medium findings

The repository test wrapper is locally blocked because the installed node_modules/bun package lacks its postinstall artifact; equivalent system-Bun test invocations passed.

Non-goals

• no lifecycle clock injection yet
• no Effect or task runtime
• no protocol, authentication, stored-state, or public API migration

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:49pm

[greptile-apps]

Greptile Summary

This PR replaces separate startup promise, retry timer, and stopped fields with an explicit broker-client lifecycle state machine.

• Models idle, active-attempt, retained-retry, waiting, and terminal states.
• Preserves retry identity and deadlines across overlapping manual startup attempts.
• Fences stale promise and timer callbacks and adds regression coverage for retry and stop races.

Confidence Score: 4/5

The PR appears safe to merge, with only a non-blocking type-safety issue in the new tests.

The lifecycle transitions preserve retry ownership, callback fencing, and terminal stop behavior; the remaining concern is that four test overrides bypass compile-time contract checking through explicit any casts.

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

Important Files Changed

Filename	Overview
src/session/broker/brokerClient.ts	Replaces independently owned startup fields with identity-fenced lifecycle transitions for attempts, retries, and terminal stop.
src/session/broker/brokerClient.test.ts	Adds extensive retry-deadline and reentrant-stop regression coverage, but four new mocks use explicit any casts.
.changeset/tidy-startup-states.md	Adds an intentionally empty changeset for the internal lifecycle refactor.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Idle[idle] -->|start| Attempting[attempting]
    Attempting -->|success| Idle
    Attempting -->|failure: create retry| AttemptingRetry[attempting-with-retry]
    Waiting[waiting] -->|manual start: retain retry| AttemptingRetry
    AttemptingRetry -->|attempt settles| Waiting
    Waiting -->|retry deadline| Idle
    AttemptingRetry -->|retry deadline: consume retry| Attempting
    Idle -->|stop| Stopped[stopped]
    Attempting -->|stop| Stopped
    AttemptingRetry -->|stop and clear retry| Stopped
    Waiting -->|stop and clear retry| Stopped

Loading

Prompt To Fix All With AI

### Issue 1
src/session/broker/brokerClient.test.ts:774
**Lifecycle mocks bypass type checking**

The four new lifecycle tests replace `ensureDaemonAndConnect` through `(client as any)`, so method renames or signature changes can leave these mocks compiling against a stale contract. Use a typed test seam or narrowly typed override to preserve compile-time checking; the same pattern occurs at lines 816, 855, and 889.

---

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

_{Reviews (1): Last reviewed commit: "refactor(session): model startup lifecyc..." | Re-trigger Greptile}