Improve CLI reconnection handling

Author: brandonkachen

cli/knowledge.md

@@ -671,3 +671,116 @@ When implementing automatic retry on reconnection, scheduling retries in both SD
 - Network failures with pending operations
 - Error cascades
 - Rapid state transitions
+
+## Logging Strategy and Best Practices
+
+The CLI uses Pino for structured logging with multiple severity levels. Proper log level selection is critical for debugging without creating noise in production.
+
+### Log Levels
+
+1. **debug** - Detailed diagnostic information for troubleshooting
+   - Connection state changes (initial connection, reconnection, disconnection)
+   - Retry scheduling and execution
+   - State transitions and effect triggers
+   - Internal operation details
+   - **Use when**: Information is only needed for debugging specific issues
+
+2. **info** - General informational messages about normal operations
+   - User-initiated actions completing successfully
+   - Significant application state changes visible to users
+   - Major workflow milestones
+   - **Use when**: Information is useful for understanding normal application flow
+
+3. **warn** - Potentially harmful situations that don't prevent operation
+   - Deprecated API usage
+   - Approaching retry limits
+   - Degraded functionality
+   - Recoverable errors
+   - **Use when**: Something unexpected happened but the application can continue
+
+4. **error** - Error events that might still allow the application to continue
+   - Failed API calls
+   - Failed message sends
+   - Validation errors
+   - **Use when**: An operation failed but the application remains functional
+
+5. **fatal** - Severe errors that cause the application to abort
+   - Unrecoverable crashes
+   - Critical resource failures
+   - **Use when**: The application must terminate
+
+### Best Practices
+
+1. **Avoid Verbose Logging in Hot Paths**
+   - Connection/reconnection events should use `debug` level
+   - Frequent state updates should use `debug` level
+   - Only log user-facing actions at `info` level
+
+2. **Structured Logging**
+   - Always include context data as the first parameter
+   - Use consistent field names across the codebase
+   - Example: `logger.debug({ userId, messageId }, 'Processing message')`
+
+3. **Log Message Format**
+   - Use clear, concise descriptions
+   - Include relevant identifiers in brackets: `[Connection]`, `[RETRY-EFFECT]`
+   - Avoid overly verbose messages
+
+4. **Production vs Development**
+   - Debug logs are automatically filtered in production based on log level
+   - In development, all logs go to `debug/cli.log`
+   - In production, logs go to the chat directory as `log.jsonl`
+
+5. **Analytics Integration**
+   - Setting `data.eventId` to an `AnalyticsEvent` sends the log to PostHog
+   - Only use for user-facing actions, not internal debugging
+
+### Example Usage
+
+```typescript
+// Debug level - internal state changes
+logger.debug(
+  { isInitialConnection, timestamp: Date.now() },
+  '[Connection] Reconnection callback triggered'
+)
+
+// Info level - user-visible actions
+logger.info(
+  { userId, messageCount },
+  'Chat session started successfully'
+)
+
+// Warn level - recoverable issues
+logger.warn(
+  { messageId, attemptCount },
+  'Message retry attempt failed, will retry'
+)
+
+// Error level - operation failures
+logger.error(
+  { error: err.message, apiEndpoint },
+  'API request failed'
+)
+```
+
+### Logging Anti-Patterns
+
+❌ **Don't**: Log at `info` level for every state change
+```typescript
+logger.info('[State] Counter incremented') // Too noisy!
+```
+
+✅ **Do**: Use `debug` for internal state changes
+```typescript
+logger.debug({ counter }, '[State] Counter updated')
+```
+
+❌ **Don't**: Include sensitive information in logs
+```typescript
+logger.info({ apiKey, password }, 'User authenticated') // Security risk!
+```
+
+✅ **Do**: Sanitize or omit sensitive data
+```typescript
+logger.info({ userId }, 'User authenticated')
+```