paseo/docs/daemon-session-connection-architecture-review.md

Daemon Session and Connection Plan Review

Date: 2026-02-20 Plan reviewed: docs/daemon-session-connection-architecture-spec.md Change set reviewed: current uncommitted workspace changes

Verdict

Partial alignment.

The local changes implement major parts of the plan (runtime-owned host connectivity, disposed terminal state in DaemonClient, connect timeout path, relay multi-socket handling, and first-open UX gating). However, there are still blocking gaps against non-negotiable invariants and migration requirements.

Findings

1. clientSessionKey is still optional, with silent fallback identity generation (Blocking)

Plan requirements impacted:

• Invariant 1: daemon session keyed by clientSessionKey
• Invariant 9: no silent fallback identities
• Migration steps 1-2: introduce/persist and require session key on direct + relay

Evidence:

• packages/server/src/client/daemon-client.ts:148 keeps clientSessionKey optional.
• packages/server/src/client/daemon-client.ts:373-packages/server/src/client/daemon-client.ts:377 silently generates clt_${safeRandomId()} when missing.
• packages/app/src/hooks/use-daemon-client.ts:23-packages/app/src/hooks/use-daemon-client.ts:35 creates DaemonClient without providing clientSessionKey.
• packages/app/src/utils/test-daemon-connection.ts:51-packages/app/src/utils/test-daemon-connection.ts:63 builds probe clients/URLs without clientSessionKey.

Impact:

• Session continuity is not uniformly guaranteed for all app->daemon paths.
• Identity fallback remains implicit instead of failing fast.

Coding-standards impact:

• Violates “prefer explicit error over fallback” for identity-critical behavior.

2. Host runtime async generation guards are incomplete for probe-side effects (High)

Plan requirements impacted:

• HostRuntime machine rule: all async side effects generation-guarded; stale async completions must not patch current state.

Evidence:

• packages/app/src/runtime/host-runtime.ts:506-packages/app/src/runtime/host-runtime.ts:611 (runProbeCycleNow) performs async probes and then mutates snapshot/switches connection, but has no request-generation guard equivalent to switchRequestVersion.
• Generation checks exist only in switch flow (packages/app/src/runtime/host-runtime.ts:627-packages/app/src/runtime/host-runtime.ts:764).

Impact:

• Overlapping probe cycles can apply stale probe snapshots or stale switching decisions.

3. Directory sync machine is only partially modeled (Medium)

Plan requirements impacted:

• Section 7.3 machine shape (initial_loading, revalidating, error_before_first_success, error_after_ready).

Evidence:

• Runtime exposes "idle" | "loading" | "ready" | "error" only (packages/app/src/runtime/host-runtime.ts:25-packages/app/src/runtime/host-runtime.ts:29).
• “Revalidating” and both error phases are inferred indirectly via hasEverLoadedAgentDirectory rather than explicit machine states (packages/app/src/runtime/host-runtime.ts:41, packages/app/src/runtime/host-runtime.ts:480-packages/app/src/runtime/host-runtime.ts:493).

Impact:

• Current behavior can work, but the plan’s explicit state model and transition clarity are not fully realized.

4. React still triggers connection lifecycle operations outside explicit user intent (Medium)

Plan requirements impacted:

• React integration contract: React should not coordinate connection lifecycle except explicit user intent.

Evidence:

• packages/app/src/components/multi-daemon-session-host.tsx:36-packages/app/src/components/multi-daemon-session-host.tsx:44 calls runtime.ensureConnectedAll() and runtime.runProbeCycleNow() on app foreground transitions.

Impact:

• Lifecycle policy remains partly driven by React effect orchestration.

5. Loading/refresh policy remains distributed across multiple hooks (Low)

Plan + coding-standards impact:

• Plan favors machine-driven, centralized state decisions.
• Coding standards call out “distributed decisions and conditional accretion”.

Evidence:

• Similar refresh/sync logic appears in:
  • packages/app/src/hooks/use-sidebar-agents-list.ts
  • packages/app/src/hooks/use-all-agents-list.ts
  • packages/app/src/hooks/use-aggregated-agents.ts:45-packages/app/src/hooks/use-aggregated-agents.ts:81
• useAggregatedAgents.refreshAll writes store directly without runtime sync state markers (packages/app/src/hooks/use-aggregated-agents.ts:70-packages/app/src/hooks/use-aggregated-agents.ts:76).

Impact:

• Greater risk of state drift and inconsistent loading semantics between surfaces.

What is aligned well

• DaemonClient now has terminal disposed state and no-op ensureConnected in disposed state (packages/server/src/client/daemon-client.ts).
• Connect timeout path is explicit (packages/server/src/client/daemon-client.ts:473-packages/server/src/client/daemon-client.ts:484).
• Direct websocket URLs now support clientSessionKey (packages/server/src/shared/daemon-endpoints.ts:64-packages/server/src/shared/daemon-endpoints.ts:77).
• Relay and server now use session-style external keys and allow multi-socket client presence (packages/server/src/server/relay-transport.ts:325, packages/server/src/server/websocket-server.ts, packages/relay/src/cloudflare-adapter.ts).
• App-side host runtime is now the primary connectivity source for context/session wiring (packages/app/src/contexts/daemon-connections-context.tsx, packages/app/src/components/multi-daemon-session-host.tsx).
• Agent first-open vs revalidation UX behavior is substantially closer to plan (packages/app/src/hooks/use-agent-screen-state-machine.ts, packages/app/src/screens/agent/agent-ready-screen.tsx).

Recommended next steps

1. Make clientSessionKey mandatory for app/runtime DaemonClient creation paths and throw explicit errors when missing.
2. Add probe-cycle generation tokens so stale probe results cannot update snapshots or trigger switches.
3. Promote directory sync to an explicit machine (or equivalent discriminated state) matching planned transition semantics.
4. Consolidate agent-directory refresh policy into one runtime-owned path and remove duplicate hook-level logic.
5. Add structured transition logging fields from section 12 (serverId, clientSessionKey/hash, from/to/event, connection path, generation, typed reason).