# Session Resilience Design

**Date:** 2026-03-13
**Status:** Approved
**Branch:** feat/multi-workspace

## Problem

Multi-workspace mode introduces long-lived, concurrent Claude Code sessions that are reaped on idle and resumed on demand. Several failure modes cause silent context loss ("context rot"):

1. **CWD mismatch** — workspace paths that differ by trailing slash, symlink, or relative segment map to different Claude Code session directories, causing resume to silently start a fresh session
2. **Resume failure** — when a session's context is too large, `--resume` fails with "Prompt is too long" and the session becomes permanently broken until manual `!new`
3. **Invisible context degradation** — users have no signal that context is filling up until Claude starts forgetting things
4. **Silent failures** — session lifecycle events (spawn, resume, reap, failure) lack diagnostic logging

## Design

### 1. Path Normalization

**Helper:** `normalizeWorkspacePath(path string) string` in `workspace_state.go`

```
filepath.Clean(path) → filepath.EvalSymlinks(cleanedPath)
```

If `EvalSymlinks` fails (path doesn't exist yet), fall back to `filepath.Clean` only.

**Applied at two sites:**
- `workspacePool.GetOrCreate(workspace)` — normalize the key before map lookup/insert
- Workspace binding resolution — normalize before the workspace string enters the system

**Logging:** `slog.Debug("workspace path normalized", "original", path, "normalized", result)` when normalization changes the input.

### 2. Resume Failure → Fresh Session Fallback

**Location:** `getOrCreateInteractiveStateWith()` in engine.go

**Current behavior:** `StartSession` failure → state with nil `agentSession` → broken until `!new`.

**New behavior:**

1. If `StartSession` fails AND `session.AgentSessionID != ""` (resume attempt):
   - Log failure with diagnostics: session ID, error message, cwd
   - Clear `session.AgentSessionID` and save
   - Retry `agent.StartSession(ctx, "")` for a fresh session
   - Post platform notification: *"Session context was too large to resume — starting fresh. Project context is preserved in CLAUDE.md."*
2. If fresh retry also fails → fall through to existing nil-state behavior
3. If original call was already fresh (`AgentSessionID == ""`) → no retry, fall through as today

**Notification:** Send via `p.Send(ctx, replyCtx, msg)` — both are available on the `interactiveState` being constructed.

### 3. Context Consumption Indicator

**Dual-track approach with logging to compare accuracy over time.**

#### Track A: SDK token counts (accurate, cc-connect-owned)

- In `processInteractiveEvents`, parse `result` events for `input_tokens` usage
- Store cumulative `input_tokens` on the `interactiveState` (updated each turn)
- Compute percentage: `input_tokens / 200_000 * 100` (model context window)
- Append `[ctx: XX%]` to every message relayed to the platform

#### Track B: Claude self-report (approximate, for comparison)

- Add to system prompt via `--append-system-prompt`: instruction to append `[ctx: ~XX%]` to every response
- Parse the self-reported value from Claude's output before relaying

#### Logging

On every turn that has both values:
```
slog.Info("context_usage",
    "sdk_pct", sdkPct,
    "self_reported_pct", selfReportedPct,
    "session_key", sessionKey,
    "input_tokens", inputTokens)
```

Over time, compare drift to decide whether the system prompt instruction adds value.

#### Display

Appended to every visible message relayed to the platform:
```
Here's the refactored auth module...
[ctx: 62%]
```

If no token data available yet (first message), skip the indicator.

### 4. Diagnostic Logging

Structured `slog` logging at key lifecycle points:

| Event | Level | Fields |
|-------|-------|--------|
| Session spawn | Info | normalized cwd, session ID (or "new"), model |
| Session resume | Info | session ID, JSONL file path, file size |
| Resume failure | Error | session ID, error, stderr, cwd, JSONL file size |
| Fresh fallback | Warn | original session ID, new session ID, cwd |
| Idle reap | Info | session key, workspace path, idle duration, token count at reap |
| Context per-turn | Info | session key, input_tokens, sdk_pct, self_reported_pct |
| Path normalization | Debug | original path, normalized path (only when changed) |

**JSONL file size:** Resolve via `findProjectDir` + stat at resume time. Log even if file not found (indicates cwd mismatch).

## Non-Goals

- **Proactive compaction** — likely to cause more trouble than it's worth; the context indicator gives users agency to compact manually
- **Session summary → new session pattern** — more robust but significantly more implementation work; revisit if resume-with-fallback proves insufficient
- **Disk/memory monitoring** — out of scope; can be added as operational tooling later

## Implementation Order

1. Path normalization (prerequisite for everything else being reliable)
2. Diagnostic logging (needed to verify the other changes work)
3. Resume failure fallback (highest-value fix)
4. Context consumption indicator (most complex, benefits from logging already being in place)