Context

PR #2191 wholesale-restored src/commands/agent.ts from pre-v2026.3.1. This discarded several robustness and code quality improvements from v2026.3.1/v2026.3.2.

Audit report: hq/engineering/notes/post-remediation-audit-b3b4.md

Findings

Robustness (HIGH priority)

1. Session-expired retry flow (v2026.3.1): Full FailoverError + session_expired handling. When a CLI session ID is stale (gateway returns session_expired), the flow clears the stale ID via setCliSessionId(null) and retries with a new session. Prevents cryptic errors on session expiry.

2. mergeSessionEntry with OverrideFieldClearedByDelete (v2026.3.1): Session store uses merge-then-persist instead of direct overwrite. OVERRIDE_FIELDS_CLEARED_BY_DELETE is a typed array of fields that should be removed (not just nulled) when a session is deleted. Prevents race conditions where concurrent session updates clobber each other.

Code Quality (MEDIUM priority)

3. runAgentAttempt extraction (v2026.3.1): The agent run logic was inline spaghetti. v2026.3.1 extracted it into a standalone function with typed params. Improves readability and testability.

4. Subsystem logger (v2026.3.1): createSubsystemLogger("commands/agent") for structured logging. Enables per-subsystem log filtering.

5. trigger: "user" field (v2026.3.2): Tracks what triggered the session update (user action vs system). Useful for session audit/debugging.

6. runCliWithSession closure (v2026.3.2): Extracts runCliAgent call args into a reusable closure. DRY — the same args were duplicated for initial call and retry.

Exit Criterion

Session-expired retry flow and mergeSessionEntry are the must-haves. Code quality items are nice-to-have. All changes must preserve ChannelBridge dispatch (RemoteClaw's middleware architecture).