# Session Management

OpenClaw employs a centralized, file-based session management system that handles persistence, lifecycle events, and automated store maintenance. Unlike simple memory-only stores, this system is designed for high-concurrency environments with atomic write guarantees and strict disk budget enforcement.

***

## SessionEntry type

The `SessionEntry` structure in `src/config/sessions/types.ts` is the core data model, containing nearly 80 fields that track everything from model overrides to granular token usage and skill snapshots.

```typescript
export type SessionEntry = {
  sessionId: string;
  updatedAt: number;
  sessionFile?: string;
  
  // Model and Provider Overrides
  modelProvider?: string;
  model?: string;
  providerOverride?: string;
  modelOverride?: string;
  thinkingLevel?: string;
  
  // Token Tracking and Context
  inputTokens?: number;
  outputTokens?: number;
  totalTokens?: number;
  totalTokensFresh?: boolean;
  compactionCount?: number;
  
  // Delivery and Origin
  deliveryContext?: DeliveryContext;
  lastChannel?: SessionChannelId;
  origin?: SessionOrigin;
  
  // Meta and Snapshots
  skillsSnapshot?: SessionSkillSnapshot;
  systemPromptReport?: SessionSystemPromptReport;
  acp?: SessionAcpMeta; // Agent Control Plane metadata
  queueMode?: "steer" | "followup" | "collect" | "queue" | "interrupt";
};
```

Key features of the type system:
* **Model Overrides**: Allows per-session binding to specific models or providers, bypassing global defaults.
* **Token Intelligence**: Tracks `totalTokensFresh` to determine if usage displays need a refresh.
* **ACP Meta**: Preserves state for the Agent Control Plane, ensuring persistent agent behaviors across turns.
* **Skill Snapshots**: Captures the state of available [[Skills]] at the time of the session turn.

***

## Store Maintenance

Automated maintenance is handled in `src/config/sessions/store-maintenance.ts` to prevent unbounded growth of the session file and ensure performance.

### Pruning and Capping
* **`pruneStaleEntries()`**: Removes sessions older than a configured threshold (default: 30 days). It iterates through the store and deletes entries where `updatedAt` is before the cutoff.
* **`capEntryCount()`**: Enforces a maximum number of sessions (default: 500). It sorts sessions by `updatedAt` descending and keeps only the most recent $N$ entries.

### File Rotation
The `rotateSessionFile()` function monitors the `sessions.json` file size. If it exceeds the limit (default: 10MB), the system:
1. Renames the current file to `sessions.json.bak.{timestamp}`.
2. Maintains a maximum of 3 rotation backups, unlinking older ones.

### Maintenance Configuration
The `resolveMaintenanceConfig()` function aggregates parameters from [[Configuration]]:
* `pruneAfterMs`: Max age before eviction.
* `maxEntries`: Hard limit on session count.
* `rotateBytes`: File size trigger for rotation.
* `maxDiskBytes`: Total disk budget for session transcripts.

***

## Session Store

The `SessionStore` in `src/config/sessions/store.ts` manages the I/O layer with a focus on reliability and cross-platform compatibility.

### Key Features
* **Atomic Writes**: Uses `writeTextAtomic` to prevent file corruption during crashes.
* **Write Locks**: Implements a `withSessionStoreLock` mechanism using a file-based lock to prevent race conditions between concurrent agent turns.
* **Normalization**: Session keys are case-insensitive and trimmed via `normalizeStoreSessionKey()`. Legacy keys are automatically migrated to the normalized format on load.
* **Windows Retry Semantics**: Includes specialized retry logic for Windows to handle transient file locks during the "truncate and write" phase.
* **ACP Metadata Preservation**: Specifically protects `acp` metadata during updates, ensuring agent state isn't lost if a partial patch is applied.

```typescript
export async function updateSessionStore<T>(
  storePath: string,
  mutator: (store: Record<string, SessionEntry>) => Promise<T> | T,
  opts?: SaveSessionStoreOptions,
): Promise<T> {
  return await withSessionStoreLock(storePath, async () => {
    const store = loadSessionStore(storePath, { skipCache: true });
    const previousAcpByKey = collectAcpMetadataSnapshot(store);
    const result = await mutator(store);
    preserveExistingAcpMetadata({
      previousAcpByKey,
      nextStore: store,
    });
    await saveSessionStoreUnlocked(storePath, store, opts);
    return result;
  });
}
```

***

## Session Lifecycle Events

A lightweight pub/sub system in `src/sessions/session-lifecycle-events.ts` allows other subsystems to react to session changes.

```typescript
export type SessionLifecycleEvent = {
  sessionKey: string;
  reason: string;
  parentSessionKey?: string;
  label?: string;
};

export function onSessionLifecycleEvent(listener: SessionLifecycleListener): () => void {
  SESSION_LIFECYCLE_LISTENERS.add(listener);
  return () => { SESSION_LIFECYCLE_LISTENERS.delete(listener); };
}

export function emitSessionLifecycleEvent(event: SessionLifecycleEvent): void {
  for (const listener of SESSION_LIFECYCLE_LISTENERS) {
    listener(event);
  }
}
```

This system is used to trigger [[Memory]] indexing, update [[Channels]] status, or log audit trails when sessions are created or deleted.

***

## Relevance to Luna

Luna's current `SessionManager` is a basic dictionary-backed store that lacks persistence and maintenance. To reach parity with OpenClaw, Luna should adopt several patterns:

1. **Atomic Persistence**: Implement a background saver for [[Core]] sessions that uses atomic file swaps to prevent data loss.
2. **Maintenance Tasks**: Add a background service to prune old sessions and cap the total count to prevent memory leaks in the .NET runtime.
3. **Locking**: Use a `SemaphoreSlim` or file-system lock for session updates to support concurrent requests from different [[Channels]].
4. **Detailed Metadata**: Expand Luna's session objects to include token tracking and model overrides, allowing for better cost management and user customization.

Refer to [[Core]] for the current implementation status of Luna's session handling.