gitmem-mcp 1.0.3 → 1.0.5

package/dist/services/agent-detection.js

@@ -48,33 +48,27 @@ export function detectAgent() {
     let agent;
     if (entrypoint === "cli") {
         if (docker) {
-            // CLI in Docker container
-            agent = "CLI";
+            agent = "cli";
         }
         else if (process.env.GITMEM_AGENT_HOSTNAME && (hostname === process.env.GITMEM_AGENT_HOSTNAME)) {
-            // CLI on configured server = CODA-1
-            agent = "CODA-1";
+            agent = "autonomous";
         }
         else {
-            // CLI elsewhere (fallback)
-            agent = "CLI";
+            agent = "cli";
         }
     }
     else if (entrypoint === "claude-desktop") {
-        // Desktop app code tab
-        agent = "DAC";
+        agent = "desktop";
     }
     else if (!entrypoint) {
-        // No entrypoint - could be Brain Local or Brain Cloud
         if (hasFilesystemAccess()) {
-            agent = "Brain_Local";
+            agent = "local";
         }
         else {
-            agent = "Brain_Cloud";
+            agent = "cloud";
         }
     }
     else {
-        // Unknown entrypoint
         agent = "Unknown";
     }
     return {
@@ -84,6 +78,21 @@ export function detectAgent() {
         agent,
     };
 }
+/**
+ * Normalize legacy agent names to new generic names.
+ * Accepts both old (CLI, DAC, CODA-1, Brain_Local, Brain_Cloud)
+ * and new (cli, desktop, autonomous, local, cloud) formats.
+ */
+const LEGACY_MAP = {
+    "CLI": "cli",
+    "DAC": "desktop",
+    "CODA-1": "autonomous",
+    "Brain_Local": "local",
+    "Brain_Cloud": "cloud",
+};
+export function normalizeAgent(input) {
+    return LEGACY_MAP[input] || input;
+}
 /**
  * Get just the agent identity (convenience function)
  */

package/dist/services/analytics.d.ts

@@ -1,5 +1,5 @@
 /**
- * Analytics Service (OD-567)
+ * Analytics Service
  *
  * Shared analytics engine for session insights. Powers both the
  * gitmem-analyze MCP tool (CLI) and the GitMem Console dashboard.

package/dist/services/analytics.js

@@ -1,12 +1,12 @@
 /**
- * Analytics Service (OD-567)
+ * Analytics Service
  *
  * Shared analytics engine for session insights. Powers both the
  * gitmem-analyze MCP tool (CLI) and the GitMem Console dashboard.
  *
  * Uses directQuery for raw Supabase REST access (no ww-mcp dependency).
  */
-import { directQuery, directQueryAll } from "./supabase-client.js";
+import { directQuery, directQueryAll, safeInFilter } from "./supabase-client.js";
 import { getCache } from "./cache.js";
 // --- Query Layer ---
 /**
@@ -97,7 +97,7 @@ export async function enrichScarUsageTitles(usages) {
     const learnings = await directQuery("orchestra_learnings", {
         select: "id,title,severity",
         filters: {
-            id: `in.(${ids.join(",")})`,
+            id: safeInFilter(ids),
         },
     });
     // Build lookup map

package/dist/services/behavioral-decay.js

@@ -10,7 +10,7 @@
  * 2. fetchDismissalCounts() — queries scar_usage for inline archival hints
  *    (called from recall to annotate frequently-dismissed scars)
  */
-import { isConfigured } from "./supabase-client.js";
+import { isConfigured, safeInFilter } from "./supabase-client.js";
 const SUPABASE_URL = process.env.SUPABASE_URL || "";
 const SUPABASE_KEY = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_KEY || "";
 const SUPABASE_REST_URL = SUPABASE_URL ? `${SUPABASE_URL}/rest/v1` : "";
@@ -76,7 +76,7 @@ export async function fetchDismissalCounts(scarIds) {
         // Query scar_usage for the given scar IDs (last 90 days)
         const url = new URL(`${SUPABASE_REST_URL}/scar_usage`);
         url.searchParams.set("select", "scar_id,reference_type");
-        url.searchParams.set("scar_id", `in.(${scarIds.join(",")})`);
+        url.searchParams.set("scar_id", safeInFilter(scarIds));
         url.searchParams.set("surfaced_at", `gte.${new Date(Date.now() - 90 * 86400000).toISOString()}`);
         url.searchParams.set("limit", "1000");
         const response = await fetch(url.toString(), {

package/dist/services/cache.d.ts

@@ -5,7 +5,7 @@
  * Caches search results to avoid repeated ww-mcp calls.
  *
  * Design: docs/systems/gitmem-caching.md
- * Issue: OD-473
+ *
  */
 declare const TTL: {
     readonly SCAR_SEARCH: number;

package/dist/services/cache.js

@@ -5,7 +5,7 @@
  * Caches search results to avoid repeated ww-mcp calls.
  *
  * Design: docs/systems/gitmem-caching.md
- * Issue: OD-473
+ *
  */
 import { createHash } from "crypto";
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, unlinkSync, statSync } from "fs";

package/dist/services/compliance-validator.d.ts

@@ -3,7 +3,7 @@
  *
  * Validates session close compliance based on close type.
  *
- * Standard close requires (OD-491):
+ * Standard close requires:
  * - task_completion object with timestamps proving each step was done
  * - All 6 closing questions answered
  * - human_corrections field present (even if empty string)

package/dist/services/compliance-validator.js

@@ -3,7 +3,7 @@
  *
  * Validates session close compliance based on close type.
  *
- * Standard close requires (OD-491):
+ * Standard close requires:
  * - task_completion object with timestamps proving each step was done
  * - All 6 closing questions answered
  * - human_corrections field present (even if empty string)
@@ -17,7 +17,7 @@ import { CLOSING_QUESTIONS } from "../constants/closing-questions.js";
 /** Minimum time (ms) between asking human and receiving response */
 const MIN_HUMAN_RESPONSE_GAP_MS = 3000;
 /**
- * Validate task_completion timestamps (OD-491)
+ * Validate task_completion timestamps
  *
  * Ensures:
  * 1. All timestamps are valid ISO strings
@@ -83,14 +83,14 @@ function validateTaskCompletion(tc) {
 /**
  * Validate standard close parameters
  *
- * OD-491: Now requires task_completion with timestamps proving each step was done.
+ * Now requires task_completion with timestamps proving each step was done.
  */
 function validateStandardClose(params) {
     const errors = [];
     const warnings = [];
-    // OD-491: task_completion is REQUIRED for standard close
+    // task_completion is REQUIRED for standard close
     if (!params.task_completion) {
-        errors.push("Standard close requires task_completion object (OD-491). " +
+        errors.push("Standard close requires task_completion object. " +
             "You must complete each step: display questions → answer → ask human → wait for response");
     }
     else {

package/dist/services/config.d.ts

@@ -10,7 +10,7 @@
  * - GITMEM_STALE_CHECK: "true" | "false" - Check for stale data (default: "true")
  * - SUPABASE_URL: Supabase project URL
  *
- * Issue: OD-473
+ *
  */
 import type { GitMemTier } from "./tier.js";
 export type SearchMode = "local" | "remote" | "auto";

package/dist/services/config.js

@@ -10,7 +10,7 @@
  * - GITMEM_STALE_CHECK: "true" | "false" - Check for stale data (default: "true")
  * - SUPABASE_URL: Supabase project URL
  *
- * Issue: OD-473
+ *
  */
 import { getTier, hasSupabase, getTablePrefix } from "./tier.js";
 // Private IP patterns for on-prem detection

package/dist/services/file-lock.js

@@ -66,6 +66,18 @@ export function acquireLockSync(lockPath, timeoutMs = DEFAULT_TIMEOUT_MS, retryM
             if (error.code !== "EEXIST") {
                 throw new Error(`[file-lock] Failed to create lock file ${lockPath}: ${error.message}`);
             }
+            // Lock file exists — check if we already hold it (reentrance detection)
+            try {
+                const raw = fs.readFileSync(lockPath, "utf-8");
+                const holder = JSON.parse(raw);
+                if (holder.pid === process.pid && holder.hostname === os.hostname()) {
+                    // Same process already holds the lock — reentrant call, allow through
+                    return;
+                }
+            }
+            catch {
+                // Can't read lock — fall through to stale check
+            }
             // Lock file exists — check if stale
             if (isLockStale(lockPath)) {
                 try {

package/dist/services/gitmem-dir.d.ts

@@ -2,20 +2,33 @@
  * Resolved .gitmem directory path
  *
  * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
- * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * but .gitmem/ was created in the project root.
  * The MCP server is long-running, so we resolve the path once and cache it.
  *
  * Resolution order:
- * 1. Cached path from session_start (most reliable — session_start created the directory)
- * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
- * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable — session_start created the directory)
+ * 3. Walk up from process.cwd() looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
+/**
+ * Validate a string intended for use as a single path component (directory name or filename).
+ * Rejects path traversal sequences, directory separators, and null bytes.
+ * Throws on invalid input — callers should validate before reaching this layer.
+ */
+export declare function sanitizePathComponent(value: string, label: string): string;
 /**
  * Set the .gitmem directory path (called by session_start after creating it)
  */
 export declare function setGitmemDir(dir: string): void;
 /**
  * Get the resolved .gitmem directory path
+ *
+ * Resolution order:
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable)
+ * 3. Walk up from CWD looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 export declare function getGitmemDir(): string;
 /**

package/dist/services/gitmem-dir.js

@@ -2,16 +2,32 @@
  * Resolved .gitmem directory path
  *
  * Solves: process.cwd() changes when agents cd into other repos (e.g., /workspace/gitmem),
- * but .gitmem/ was created in the project root (e.g., /workspace/orchestra/).
+ * but .gitmem/ was created in the project root.
  * The MCP server is long-running, so we resolve the path once and cache it.
  *
  * Resolution order:
- * 1. Cached path from session_start (most reliable — session_start created the directory)
- * 2. Walk up from process.cwd() looking for existing .gitmem/ sentinels
- * 3. Fall back to process.cwd()/.gitmem (original behavior)
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable — session_start created the directory)
+ * 3. Walk up from process.cwd() looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 import * as path from "path";
 import * as fs from "fs";
+import * as os from "os";
+/**
+ * Validate a string intended for use as a single path component (directory name or filename).
+ * Rejects path traversal sequences, directory separators, and null bytes.
+ * Throws on invalid input — callers should validate before reaching this layer.
+ */
+export function sanitizePathComponent(value, label) {
+    if (!value || typeof value !== "string") {
+        throw new Error(`${label} must be a non-empty string`);
+    }
+    if (value.includes("..") || value.includes("/") || value.includes("\\") || value.includes("\0")) {
+        throw new Error(`${label} contains invalid characters (path traversal rejected)`);
+    }
+    return value;
+}
 let cachedGitmemDir = null;
 /**
  * Set the .gitmem directory path (called by session_start after creating it)
@@ -22,13 +38,29 @@ export function setGitmemDir(dir) {
 }
 /**
  * Get the resolved .gitmem directory path
+ *
+ * Resolution order:
+ * 1. GITMEM_DIR env var (explicit override)
+ * 2. Cached path from session_start (most reliable)
+ * 3. Walk up from CWD looking for existing .gitmem/ sentinels (backward compat)
+ * 4. Fall back to ~/.gitmem (developer-scoped, survives across projects/containers)
  */
 export function getGitmemDir() {
-    // 1. Use cached path from session_start
+    // 1. GITMEM_DIR env var (explicit override, highest priority)
+    const envDir = process.env.GITMEM_DIR;
+    if (envDir) {
+        if (!cachedGitmemDir || cachedGitmemDir !== envDir) {
+            cachedGitmemDir = envDir;
+            console.error(`[gitmem-dir] Using GITMEM_DIR env var: ${envDir}`);
+        }
+        return envDir;
+    }
+    // 2. Use cached path from session_start
     if (cachedGitmemDir && fs.existsSync(cachedGitmemDir)) {
         return cachedGitmemDir;
     }
-    // 2. Walk up from CWD looking for existing .gitmem directory
+    // 3. Walk up from CWD looking for existing .gitmem directory
+    //    Backward compat: finds project-scoped .gitmem/ from older installations.
     //    Sentinel files checked in priority order:
     //    - active-sessions.json  (multi-session registry, GIT-19)
     //    - config.json           (project-level gitmem config)
@@ -46,9 +78,9 @@ export function getGitmemDir() {
         }
         dir = path.dirname(dir);
     }
-    // 3. Fall back to CWD (original behavior)
-    const fallback = path.join(process.cwd(), ".gitmem");
-    console.error(`[gitmem-dir] Falling back to CWD: ${fallback}`);
+    // 4. Fall back to ~/.gitmem (developer-scoped — survives across projects and containers)
+    const fallback = path.join(os.homedir(), ".gitmem");
+    console.error(`[gitmem-dir] Falling back to home dir: ${fallback}`);
     return fallback;
 }
 /**
@@ -62,6 +94,7 @@ export function getGitmemPath(filename) {
  * Creates the directory if it doesn't exist.
  */
 export function getSessionDir(sessionId) {
+    sanitizePathComponent(sessionId, "sessionId");
     const sessionsDir = path.join(getGitmemDir(), "sessions", sessionId);
     if (!fs.existsSync(sessionsDir)) {
         fs.mkdirSync(sessionsDir, { recursive: true });
@@ -73,6 +106,7 @@ export function getSessionDir(sessionId) {
  * Get a file path within a per-session directory.
  */
 export function getSessionPath(sessionId, filename) {
+    sanitizePathComponent(filename, "filename");
     return path.join(getSessionDir(sessionId), filename);
 }
 /**

package/dist/services/local-file-storage.d.ts

@@ -2,7 +2,7 @@
  * Local File Storage — Free Tier Backend
  *
  * Stores scars, sessions, decisions, and scar usage as JSON files
- * in the .gitmem/ directory of the current project.
+ * in the .gitmem/ directory (defaults to ~/.gitmem, overridable via GITMEM_DIR).
  *
  * Provides keyword-based search (no embeddings needed).
  */

package/dist/services/local-file-storage.js

@@ -2,19 +2,20 @@
  * Local File Storage — Free Tier Backend
  *
  * Stores scars, sessions, decisions, and scar usage as JSON files
- * in the .gitmem/ directory of the current project.
+ * in the .gitmem/ directory (defaults to ~/.gitmem, overridable via GITMEM_DIR).
  *
  * Provides keyword-based search (no embeddings needed).
  */
 import * as fs from "fs";
 import * as path from "path";
 import { bm25Search } from "./bm25.js";
+import { getGitmemDir } from "./gitmem-dir.js";
 const MAX_FILE_SIZE = 10 * 1024 * 1024; // 10MB
 const WARN_FILE_SIZE = 1 * 1024 * 1024; // 1MB
 export class LocalFileStorage {
     basePath;
     constructor(basePath) {
-        this.basePath = basePath || path.join(process.cwd(), ".gitmem");
+        this.basePath = basePath || getGitmemDir();
         this.ensureDir();
     }
     ensureDir() {
@@ -142,7 +143,7 @@ export class LocalFileStorage {
             const l = byId.get(r.id);
             if (!l)
                 continue;
-            // OD-684: Deprioritize starter scars (0.7x multiplier)
+            // Deprioritize starter scars (0.7x multiplier)
             const isStarter = !!l.is_starter;
             const adjustedSimilarity = isStarter ? r.similarity * 0.7 : r.similarity;
             mapped.push({

package/dist/services/local-vector-search.d.ts

@@ -11,7 +11,7 @@
  * - Deterministic results (same model + same data = same results)
  * - Per-container consistency (each loads same data)
  *
- * Issue: OD-473 (cache consistency)
+ * Cache consistency
  */
 import type { Project, RelevantScar } from "../types/index.js";
 interface ScarRecord {

package/dist/services/local-vector-search.js

@@ -11,7 +11,7 @@
  * - Deterministic results (same model + same data = same results)
  * - Per-container consistency (each loads same data)
  *
- * Issue: OD-473 (cache consistency)
+ * Cache consistency
  */
 import { embed as generateEmbedding, getEmbeddingDim, isEmbeddingAvailable } from "./embedding.js";
 // Embedding dimension — read from provider config at runtime
@@ -184,7 +184,7 @@ export class LocalVectorSearch {
             severity: scar.severity || "medium",
             counter_arguments: scar.counter_arguments || [],
             similarity: Math.round(similarity * 1000) / 1000, // 3 decimal places
-            // OD-508: Include enriched fields for LLM-cooperative enforcement
+            // Include enriched fields for LLM-cooperative enforcement
             why_this_matters: scar.why_this_matters,
             action_protocol: scar.action_protocol,
             self_check_criteria: scar.self_check_criteria,

package/dist/services/metrics.d.ts

@@ -2,7 +2,7 @@
  * GitMem Performance Metrics Service
  *
  * Tracks latency, result counts, and relevance signals for all GitMem tools.
- * Implements OD-429 instrumentation layer.
+ * Instrumentation layer for performance tracking.
  */
 /**
  * Tool names that can be tracked
@@ -15,7 +15,7 @@ export type PhaseTag = "session_start" | "session_refresh" | "session_close" | "
 /**
  * Agent identities
  */
-export type AgentIdentity = "CLI" | "DAC" | "CODA-1" | "Brain_Local" | "Brain_Cloud";
+export type AgentIdentity = "cli" | "desktop" | "autonomous" | "local" | "cloud";
 /**
  * Metrics data for a query
  */
@@ -36,7 +36,7 @@ export interface QueryMetrics {
     metadata?: Record<string, unknown>;
 }
 /**
- * Performance targets from OD-429
+ * Performance targets
  */
 export declare const PERFORMANCE_TARGETS: Record<ToolName, number>;
 /**
@@ -58,16 +58,16 @@ export declare class Timer {
 export declare function recordMetrics(metrics: QueryMetrics): Promise<void>;
 /**
  * Re-export performance types from types/index.ts
- * OD-489: Enhanced instrumentation for test harness validation
+ * Enhanced instrumentation for test harness validation
  */
 export type { PerformanceData, PerformanceBreakdown, ComponentPerformance, DataSource, CacheStatus, } from "../types/index.js";
 import type { PerformanceData, PerformanceBreakdown, ComponentPerformance, DataSource, CacheStatus } from "../types/index.js";
 /**
- * Build component performance data (OD-489)
+ * Build component performance data
  */
 export declare function buildComponentPerformance(latencyMs: number, source: DataSource, networkCall: boolean, cacheStatus?: CacheStatus): ComponentPerformance;
 /**
- * Count network calls from breakdown (OD-489)
+ * Count network calls from breakdown
  */
 export declare function countNetworkCalls(breakdown?: PerformanceBreakdown): number;
 export declare function buildPerformanceData(toolName: ToolName, latencyMs: number, resultCount: number, options?: {

package/dist/services/metrics.js

@@ -2,22 +2,22 @@
  * GitMem Performance Metrics Service
  *
  * Tracks latency, result counts, and relevance signals for all GitMem tools.
- * Implements OD-429 instrumentation layer.
+ * Instrumentation layer for performance tracking.
  */
 import { v4 as uuidv4 } from "uuid";
 import * as supabase from "./supabase-client.js";
 import { getEffectTracker } from "./effect-tracker.js";
 import { hasSupabase } from "./tier.js";
 /**
- * Performance targets from OD-429
+ * Performance targets
  */
 export const PERFORMANCE_TARGETS = {
     recall: 2000,
     search: 500,
     log: 500,
-    session_start: 750, // OD-645: Lean start (was 1500)
-    session_refresh: 750, // OD-645: Lean refresh (was 1500)
-    session_close: 1500, // OD-645: Tightened (was 3000)
+    session_start: 750, // Lean start (was 1500)
+    session_refresh: 750, // Lean refresh (was 1500)
+    session_close: 1500, // Tightened (was 3000)
     create_learning: 3000,
     create_decision: 3000,
     record_scar_usage: 1000,
@@ -84,7 +84,7 @@ export async function recordMetrics(metrics) {
     await tracker.track("metrics", metrics.tool_name, () => supabase.directUpsert("gitmem_query_metrics", record));
 }
 /**
- * Build component performance data (OD-489)
+ * Build component performance data
  */
 export function buildComponentPerformance(latencyMs, source, networkCall, cacheStatus = networkCall ? "miss" : "hit") {
     return {
@@ -95,7 +95,7 @@ export function buildComponentPerformance(latencyMs, source, networkCall, cacheS
     };
 }
 /**
- * Count network calls from breakdown (OD-489)
+ * Count network calls from breakdown
  */
 export function countNetworkCalls(breakdown) {
     if (!breakdown)
@@ -136,7 +136,7 @@ export function buildPerformanceData(toolName, latencyMs, resultCount, options)
         cache_hit: options?.cache_hit ?? fullyLocal,
         cache_age_ms: options?.cache_age_ms,
         search_mode: options?.search_mode,
-        // OD-489: Detailed instrumentation for test harness
+        // Detailed instrumentation for test harness
         total_latency_ms: latencyMs,
         network_calls_made: networkCallsMade,
         fully_local: fullyLocal,

package/dist/services/session-state.d.ts

@@ -1,7 +1,7 @@
 /**
  * Session State Management
- * OD-547: Track current session context for auto-injecting into recall calls
- * OD-552: Track surfaced scars for auto-bridging Q6 answers to scar_usage records
+ * Track current session context for auto-injecting into recall calls
+ * Track surfaced scars for auto-bridging Q6 answers to scar_usage records
  *
  * Maintains in-memory state of the current active session including:
  * - session_id from session_start
@@ -54,12 +54,12 @@ export declare function getProject(): string | null;
  */
 export declare function hasActiveIssue(): boolean;
 /**
- * OD-552: Add surfaced scars to tracking (deduplicates by scar_id)
+ * Add surfaced scars to tracking (deduplicates by scar_id)
  * Called by session_start and recall when scars are surfaced.
  */
 export declare function addSurfacedScars(scars: SurfacedScar[]): void;
 /**
- * OD-552: Get all surfaced scars for the current session
+ * Get all surfaced scars for the current session
  */
 export declare function getSurfacedScars(): SurfacedScar[];
 /**
@@ -105,15 +105,15 @@ export interface SessionActivity {
 }
 export declare function getSessionActivity(): SessionActivity | null;
 /**
- * OD-thread-lifecycle: Set threads for the current session
+ * : Set threads for the current session
  */
 export declare function setThreads(threads: ThreadObject[]): void;
 /**
- * OD-thread-lifecycle: Get threads for the current session
+ * : Get threads for the current session
  */
 export declare function getThreads(): ThreadObject[];
 /**
- * OD-thread-lifecycle: Resolve a thread in session state by ID.
+ * : Resolve a thread in session state by ID.
  * Returns the resolved thread or null if not found.
  */
 export declare function resolveThreadInState(threadId: string, resolutionNote?: string): ThreadObject | null;

package/dist/services/session-state.js

@@ -1,7 +1,7 @@
 /**
  * Session State Management
- * OD-547: Track current session context for auto-injecting into recall calls
- * OD-552: Track surfaced scars for auto-bridging Q6 answers to scar_usage records
+ * Track current session context for auto-injecting into recall calls
+ * Track surfaced scars for auto-bridging Q6 answers to scar_usage records
  *
  * Maintains in-memory state of the current active session including:
  * - session_id from session_start
@@ -59,7 +59,7 @@ export function hasActiveIssue() {
     return !!(currentSession?.linearIssue);
 }
 /**
- * OD-552: Add surfaced scars to tracking (deduplicates by scar_id)
+ * Add surfaced scars to tracking (deduplicates by scar_id)
  * Called by session_start and recall when scars are surfaced.
  */
 export function addSurfacedScars(scars) {
@@ -76,7 +76,7 @@ export function addSurfacedScars(scars) {
     console.error(`[session-state] Surfaced scars tracked: ${currentSession.surfacedScars.length} total`);
 }
 /**
- * OD-552: Get all surfaced scars for the current session
+ * Get all surfaced scars for the current session
  */
 export function getSurfacedScars() {
     return currentSession?.surfacedScars || [];
@@ -121,6 +121,9 @@ export function hasUnconfirmedScars() {
     const confirmedIds = new Set(currentSession.confirmations.map(c => c.scar_id));
     return recallScars.some(s => !confirmedIds.has(s.scar_id));
 }
+// Security: cap unbounded arrays to prevent memory exhaustion in long sessions
+const MAX_OBSERVATIONS = 500;
+const MAX_CHILDREN = 100;
 /**
  * v2 Phase 2: Add observations from sub-agents/teammates
  */
@@ -134,6 +137,10 @@ export function addObservations(newObs) {
         absorbed_at: o.absorbed_at || new Date().toISOString(),
     }));
     currentSession.observations.push(...timestamped);
+    // Cap to prevent memory exhaustion — keep most recent
+    if (currentSession.observations.length > MAX_OBSERVATIONS) {
+        currentSession.observations = currentSession.observations.slice(-MAX_OBSERVATIONS);
+    }
     console.error(`[session-state] Observations tracked: ${currentSession.observations.length} total`);
     return timestamped.length;
 }
@@ -151,6 +158,11 @@ export function addChild(child) {
         console.warn("[session-state] Cannot add child: no active session");
         return;
     }
+    // Cap to prevent memory exhaustion — reject silently beyond limit
+    if (currentSession.children.length >= MAX_CHILDREN) {
+        console.warn(`[session-state] Children cap reached (${MAX_CHILDREN}), ignoring new child: ${child.role}`);
+        return;
+    }
     currentSession.children.push(child);
     console.error(`[session-state] Child registered: ${child.role} (${child.type}), total: ${currentSession.children.length}`);
 }
@@ -173,7 +185,7 @@ export function getSessionActivity() {
     };
 }
 /**
- * OD-thread-lifecycle: Set threads for the current session
+ * : Set threads for the current session
  */
 export function setThreads(threads) {
     if (!currentSession) {
@@ -184,13 +196,13 @@ export function setThreads(threads) {
     console.error(`[session-state] Threads set: ${threads.length} total`);
 }
 /**
- * OD-thread-lifecycle: Get threads for the current session
+ * : Get threads for the current session
  */
 export function getThreads() {
     return currentSession?.threads || [];
 }
 /**
- * OD-thread-lifecycle: Resolve a thread in session state by ID.
+ * : Resolve a thread in session state by ID.
  * Returns the resolved thread or null if not found.
  */
 export function resolveThreadInState(threadId, resolutionNote) {