feat: add resource management types and utilities for memory optimization

- Add Disposable, BufferConfig, MemoryMetrics, CleanupRegistration types
- Create src/config/buffer-limits.ts with consolidated buffer size constants
- Create src/config/map-limits.ts with Map size limits to prevent unbounded growth
- Implement BufferAccumulator utility with configurable trim and onTrim callback
- Implement LRUMap with automatic eviction and O(1) operations
- Implement CleanupManager for unified resource cleanup with isStopped guard
- Add comprehensive tests for all new utilities

This lays the foundation for memory leak prevention and performance improvements.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/config/buffer-limits.ts

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview Centralized buffer size limits for memory management.
+ *
+ * These constants define the maximum sizes for various buffers throughout
+ * Claudeman. Consolidating them here ensures consistent limits and makes
+ * it easy to tune memory usage.
+ *
+ * Memory Budget Rationale (for 20 concurrent sessions):
+ * - Terminal buffer: 2MB max × 20 = 40MB worst case
+ * - Text output: 1MB max × 20 = 20MB worst case
+ * - Messages: ~1KB each × 1000 × 20 = 20MB worst case
+ * - Total buffer overhead: ~80MB (acceptable for long-running server)
+ *
+ * @module config/buffer-limits
+ */
+
+// ============================================================================
+// Terminal Buffer Limits
+// ============================================================================
+
+/**
+ * Maximum terminal buffer size in characters.
+ * Contains raw terminal output with ANSI escape sequences.
+ * Reduced from 5MB to 2MB for better render performance.
+ */
+export const MAX_TERMINAL_BUFFER_SIZE = 2 * 1024 * 1024; // 2MB
+
+/**
+ * Size to trim terminal buffer to when max is exceeded.
+ * Keeps the most recent portion to preserve context.
+ */
+export const TRIM_TERMINAL_TO = 1.5 * 1024 * 1024; // 1.5MB
+
+// ============================================================================
+// Text Output Buffer Limits
+// ============================================================================
+
+/**
+ * Maximum text output buffer size in characters.
+ * Contains ANSI-stripped text for search and analysis.
+ */
+export const MAX_TEXT_OUTPUT_SIZE = 1 * 1024 * 1024; // 1MB
+
+/**
+ * Size to trim text output buffer to when max is exceeded.
+ */
+export const TRIM_TEXT_TO = 768 * 1024; // 768KB
+
+// ============================================================================
+// Message Buffer Limits
+// ============================================================================
+
+/**
+ * Maximum number of Claude JSON messages to keep in memory per session.
+ * Older messages are discarded when limit is exceeded.
+ */
+export const MAX_MESSAGES = 1000;
+
+/**
+ * Number of messages to keep when trimming (80% of max).
+ */
+export const TRIM_MESSAGES_TO = 800;
+
+// ============================================================================
+// Line Buffer Limits
+// ============================================================================
+
+/**
+ * Maximum line buffer size in characters.
+ * Prevents unbounded growth for extremely long lines without newlines.
+ */
+export const MAX_LINE_BUFFER_SIZE = 64 * 1024; // 64KB
+
+// ============================================================================
+// Respawn Controller Buffer Limits
+// ============================================================================
+
+/**
+ * Maximum respawn controller buffer size.
+ * Smaller than session buffer since it's only used for idle detection.
+ */
+export const MAX_RESPAWN_BUFFER_SIZE = 1 * 1024 * 1024; // 1MB
+
+/**
+ * Size to trim respawn buffer to when max is exceeded.
+ */
+export const TRIM_RESPAWN_BUFFER_TO = 512 * 1024; // 512KB
+
+// ============================================================================
+// Run Summary Limits
+// ============================================================================
+
+/**
+ * Maximum number of events to keep in run summary.
+ */
+export const MAX_RUN_SUMMARY_EVENTS = 1000;
+
+/**
+ * Number of events to keep when trimming run summary.
+ */
+export const TRIM_RUN_SUMMARY_TO = 800;
+
+// ============================================================================
+// Spawn Message Limits
+// ============================================================================
+
+/**
+ * Maximum messages per spawn communication channel.
+ */
+export const MAX_MESSAGES_PER_CHANNEL = 100;

src/config/map-limits.ts

@@ -0,0 +1,137 @@
+/**
+ * @fileoverview Centralized Map size limits for memory management.
+ *
+ * These constants define maximum sizes for Maps that track ephemeral data.
+ * Without limits, long-running sessions can accumulate unbounded entries
+ * leading to memory leaks.
+ *
+ * Memory Budget Rationale:
+ * - Assuming average entry size of ~1KB
+ * - MAX_TRACKED_AGENTS=500 × 1KB = ~500KB for agent tracking
+ * - Activity/results per agent × agents = bounded by these limits
+ * - Total Map overhead: <50MB even under heavy load
+ *
+ * @module config/map-limits
+ */
+
+// ============================================================================
+// Agent Tracking Limits
+// ============================================================================
+
+/**
+ * Maximum number of agents to track across all sessions.
+ * Oldest agents are evicted when limit is exceeded (LRU policy).
+ */
+export const MAX_TRACKED_AGENTS = 500;
+
+/**
+ * Maximum activity entries to keep per agent.
+ * Includes tool calls, status updates, progress reports.
+ */
+export const MAX_SUBAGENT_ACTIVITY_PER_AGENT = 100;
+
+/**
+ * Maximum tool results to keep per agent.
+ * Prevents memory growth from long-running agents with many tool calls.
+ */
+export const MAX_TOOL_RESULTS_PER_AGENT = 200;
+
+// ============================================================================
+// Hook Event Limits
+// ============================================================================
+
+/**
+ * Maximum pending hook events to queue.
+ * Prevents unbounded growth if hook processing is slow.
+ */
+export const MAX_PENDING_HOOKS = 50;
+
+// ============================================================================
+// Session Tracking Limits
+// ============================================================================
+
+/**
+ * Maximum concurrent sessions allowed.
+ * Each session consumes significant resources (PTY, buffers, watchers).
+ */
+export const MAX_CONCURRENT_SESSIONS = 50;
+
+/**
+ * Maximum session history entries to keep (for analytics).
+ */
+export const MAX_SESSION_HISTORY = 100;
+
+// ============================================================================
+// SSE Client Limits
+// ============================================================================
+
+/**
+ * Maximum SSE clients per session.
+ * Prevents resource exhaustion from many browser tabs.
+ */
+export const MAX_SSE_CLIENTS_PER_SESSION = 10;
+
+/**
+ * Maximum total SSE clients across all sessions.
+ */
+export const MAX_TOTAL_SSE_CLIENTS = 100;
+
+// ============================================================================
+// File Watcher Limits
+// ============================================================================
+
+/**
+ * Maximum file watchers (FSWatcher) to allow.
+ * Linux default max_user_watches is 8192-65536.
+ * We warn at 80% capacity and evict idle watchers.
+ */
+export const MAX_FILE_WATCHERS = 500;
+
+/**
+ * Warning threshold as percentage of max watchers.
+ */
+export const FILE_WATCHER_WARNING_THRESHOLD = 0.8;
+
+// ============================================================================
+// Task Tracking Limits
+// ============================================================================
+
+/**
+ * Maximum tasks to keep in the task queue.
+ */
+export const MAX_QUEUED_TASKS = 100;
+
+/**
+ * Maximum completed tasks to keep for history.
+ */
+export const MAX_COMPLETED_TASKS_HISTORY = 50;
+
+// ============================================================================
+// Todo Item Limits (Ralph Tracker)
+// ============================================================================
+
+/**
+ * Maximum todo items to track per session.
+ */
+export const MAX_TODOS_PER_SESSION = 500;
+
+/**
+ * TTL for completed todo items before cleanup (1 hour).
+ */
+export const COMPLETED_TODO_TTL_MS = 60 * 60 * 1000;
+
+// ============================================================================
+// Pending Tool Calls Limits
+// ============================================================================
+
+/**
+ * Maximum pending tool calls to track per subagent.
+ * Entries should be cleaned up on tool_result, but this prevents leaks.
+ */
+export const MAX_PENDING_TOOL_CALLS = 100;
+
+/**
+ * TTL for orphaned pending tool calls (5 minutes).
+ * If no tool_result received, entry is cleaned up.
+ */
+export const PENDING_TOOL_CALL_TTL_MS = 5 * 60 * 1000;