code-graph-context 2.6.1 → 2.7.0

package/dist/core/utils/graph-factory.js

@@ -3,7 +3,7 @@
  * Shared utilities for creating/converting graph nodes and edges
  */
 import crypto from 'crypto';
-import { CoreEdgeType, CORE_TYPESCRIPT_SCHEMA } from '../config/schema.js';
+import { CoreEdgeType, CORE_TYPESCRIPT_SCHEMA, } from '../config/schema.js';
 // ============================================
 // Node ID Generation
 // ============================================

package/dist/mcp/constants.js

@@ -39,6 +39,10 @@ export const TOOL_NAMES = {
     swarmCompleteTask: 'swarm_complete_task',
     swarmGetTasks: 'swarm_get_tasks',
     swarmOrchestrate: 'swarm_orchestrate',
+    saveSessionBookmark: 'save_session_bookmark',
+    restoreSessionBookmark: 'restore_session_bookmark',
+    saveSessionNote: 'save_session_note',
+    recallSessionNotes: 'recall_session_notes',
 };
 // Tool Metadata
 export const TOOL_METADATA = {
@@ -205,9 +209,9 @@ Parameters:
     },
     [TOOL_NAMES.swarmPheromone]: {
         title: 'Swarm Pheromone',
-        description: `Mark a code node with a pheromone for coordination. Types: exploring (2min), modifying (10min), claiming (1hr), completed (24hr), warning (permanent), blocked (5min), proposal (1hr), needs_review (30min).
+        description: `Mark a code node with a pheromone for coordination. Types: exploring (2min), modifying (10min), claiming (1hr), completed (24hr), warning (permanent), blocked (5min), proposal (1hr), needs_review (30min), session_context (8hr).
 
-Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Use remove:true to delete. Pheromones decay automatically.`,
+Workflow states (exploring/claiming/modifying/completed/blocked) are mutually exclusive per agent+node. Flag types (warning/proposal/needs_review/session_context) can coexist. Use remove:true to delete. Pheromones decay automatically.`,
     },
     [TOOL_NAMES.swarmSense]: {
         title: 'Swarm Sense',
@@ -261,6 +265,75 @@ Sort by: priority (default), created, updated. Add includeStats:true for aggrega
 
 Use dryRun:true to preview plan. maxAgents controls parallelism (default: 3). Failed tasks auto-retry via pheromone decay.`,
     },
+    [TOOL_NAMES.saveSessionBookmark]: {
+        title: 'Save Session Bookmark',
+        description: `Save current session context as a bookmark for cross-session continuity.
+
+Records your working set (code node IDs), task context, findings, and next steps so a future session can resume exactly where you left off.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId (required): Unique session/conversation ID for recovery
+- agentId (required): Your agent identifier
+- summary (required, min 10 chars): Brief description of current work state
+- workingSetNodeIds (required): Code node IDs you are focused on
+- taskContext (required): High-level task being worked on
+- findings: Key discoveries or decisions made so far
+- nextSteps: What to do next when resuming
+- metadata: Additional structured data
+
+Returns bookmarkId for use with restore_session_bookmark.`,
+    },
+    [TOOL_NAMES.restoreSessionBookmark]: {
+        title: 'Restore Session Bookmark',
+        description: `Restore a previously saved session bookmark to resume work.
+
+Retrieves the bookmark, fetches working set code nodes (with source), and returns any session notes. Use after conversation compaction or when resuming a task in a new session.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId: Specific session to restore (latest bookmark if omitted)
+- agentId: Filter by agent ID (any agent if omitted)
+- includeCode (default: true): Include source code for working set nodes
+- snippetLength (default: 500): Max characters per code snippet
+
+Returns: bookmark data, working set nodes, session notes, and staleNodeIds (nodes no longer in graph after re-parse).`,
+    },
+    [TOOL_NAMES.saveSessionNote]: {
+        title: 'Save Session Note',
+        description: `Save an observation, decision, insight, or risk as a durable session note linked to code nodes.
+
+Notes survive session compaction and are recalled by restore_session_bookmark or recall_session_notes.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- sessionId (required): Session/conversation identifier
+- agentId (required): Your agent identifier
+- topic (required, 3-100 chars): Short topic label
+- content (required, min 10 chars): Full observation text
+- category (required): architectural, bug, insight, decision, risk, or todo
+- severity (default: info): info, warning, or critical
+- aboutNodeIds: Code node IDs this note is about (creates [:ABOUT] links)
+- expiresInHours: Auto-expire after N hours (omit for permanent)
+
+Returns noteId, hasEmbedding (enables semantic recall), and expiresAt.`,
+    },
+    [TOOL_NAMES.recallSessionNotes]: {
+        title: 'Recall Session Notes',
+        description: `Search and retrieve saved session notes. Supports semantic vector search (when query provided) or filter-based search.
+
+Parameters:
+- projectId (required): Project ID, name, or path
+- query: Natural language search — triggers semantic vector search when provided
+- category: Filter by architectural, bug, insight, decision, risk, todo
+- severity: Filter by info, warning, or critical
+- sessionId: Filter by session ID
+- agentId: Filter by agent ID
+- limit (default: 10, max: 50): Maximum notes to return
+- minSimilarity (default: 0.3): Minimum similarity for vector search
+
+Returns notes with topic, content, category, severity, relevance score (vector mode), and linked aboutNodes.`,
+    },
 };
 // Default Values
 export const DEFAULTS = {

package/dist/mcp/handlers/graph-generator.handler.js

@@ -180,6 +180,7 @@ export class GraphGeneratorHandler {
     async createVectorIndexes() {
         console.error('Creating vector indexes...');
         await this.neo4jService.run(QUERIES.CREATE_EMBEDDED_VECTOR_INDEX);
+        await this.neo4jService.run(QUERIES.CREATE_SESSION_NOTES_VECTOR_INDEX);
         await debugLog('Vector indexes created');
     }
     flattenProperties(properties) {

package/dist/mcp/mcp.server.js

@@ -24,8 +24,8 @@ import { registerAllTools } from './tools/index.js';
 import { debugLog } from './utils.js';
 // Track server state for debugging
 let serverStartTime;
-let toolCallCount = 0;
-let lastToolCall = null;
+const toolCallCount = 0;
+const lastToolCall = null;
 /**
  * Log memory usage and server stats
  */

package/dist/mcp/service-init.js

@@ -4,7 +4,7 @@
  */
 import fs from 'fs/promises';
 import { join } from 'path';
-import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning, } from '../cli/neo4j-docker.js';
+import { ensureNeo4jRunning, isDockerInstalled, isDockerRunning } from '../cli/neo4j-docker.js';
 import { Neo4jService, QUERIES } from '../storage/neo4j/neo4j.service.js';
 import { FILE_PATHS, LOG_CONFIG } from './constants.js';
 import { initializeNaturalLanguageService } from './tools/natural-language-to-cypher.tool.js';

package/dist/mcp/services/watch-manager.js

@@ -47,7 +47,7 @@ class WatchManager {
             // This is expected if the client doesn't support logging capability
             debugLog('sendNotification: MCP message failed (expected if client lacks logging)', {
                 type: notification.type,
-                error: String(error)
+                error: String(error),
             });
         });
     }
@@ -62,7 +62,8 @@ class WatchManager {
         }
         // Enforce maximum watcher limit
         if (this.watchers.size >= WATCH.maxWatchers) {
-            throw new Error(`Maximum watcher limit (${WATCH.maxWatchers}) reached. ` + `Stop an existing watcher before starting a new one.`);
+            throw new Error(`Maximum watcher limit (${WATCH.maxWatchers}) reached. ` +
+                `Stop an existing watcher before starting a new one.`);
         }
         const fullConfig = {
             projectPath: config.projectPath,
@@ -138,7 +139,13 @@ class WatchManager {
      * Handle a file system event
      */
     handleFileEvent(state, type, filePath) {
-        debugLog('handleFileEvent START', { type, filePath, projectId: state.projectId, status: state.status, isStopping: state.isStopping });
+        debugLog('handleFileEvent START', {
+            type,
+            filePath,
+            projectId: state.projectId,
+            status: state.status,
+            isStopping: state.isStopping,
+        });
         // Ignore events if watcher is stopping or not active
         if (state.isStopping || state.status !== 'active') {
             debugLog('Ignoring event - watcher not active or stopping', {
@@ -194,12 +201,12 @@ class WatchManager {
             projectId: state.projectId,
             isProcessing: state.isProcessing,
             pendingCount: state.pendingEvents.length,
-            isStopping: state.isStopping
+            isStopping: state.isStopping,
         });
         // Don't process if already processing, no events, or watcher is stopping
         if (state.isProcessing || state.pendingEvents.length === 0 || state.isStopping) {
             await debugLog('processEvents: early return', {
-                reason: state.isProcessing ? 'already processing' : state.pendingEvents.length === 0 ? 'no events' : 'stopping'
+                reason: state.isProcessing ? 'already processing' : state.pendingEvents.length === 0 ? 'no events' : 'stopping',
             });
             return;
         }
@@ -226,12 +233,12 @@ class WatchManager {
             }
             await debugLog('processEvents: calling incrementalParseHandler', {
                 projectPath: state.projectPath,
-                projectId: state.projectId
+                projectId: state.projectId,
             });
             const result = await this.incrementalParseHandler(state.projectPath, state.projectId, state.tsconfigPath);
             await debugLog('processEvents: incrementalParseHandler returned', {
                 nodesUpdated: result.nodesUpdated,
-                edgesUpdated: result.edgesUpdated
+                edgesUpdated: result.edgesUpdated,
             });
             state.lastUpdateTime = new Date();
             const elapsedMs = Date.now() - startTime;
@@ -285,7 +292,10 @@ class WatchManager {
             debugLog('handleWatcherError: cleanup succeeded', { projectId: state.projectId });
         })
             .catch((cleanupError) => {
-            debugLog('handleWatcherError: cleanup failed', { projectId: state.projectId, cleanupError: String(cleanupError) });
+            debugLog('handleWatcherError: cleanup failed', {
+                projectId: state.projectId,
+                cleanupError: String(cleanupError),
+            });
             console.error(`[WatchManager] Failed to cleanup errored watcher ${state.projectId}:`, cleanupError);
         });
     }
@@ -306,7 +316,7 @@ class WatchManager {
             debugLog('syncMissedChanges: completed', {
                 projectId: state.projectId,
                 nodesUpdated: result.nodesUpdated,
-                edgesUpdated: result.edgesUpdated
+                edgesUpdated: result.edgesUpdated,
             });
             if (result.nodesUpdated > 0 || result.edgesUpdated > 0) {
                 console.error(`[WatchManager] Synced missed changes for ${state.projectId}: ` +
@@ -314,7 +324,11 @@ class WatchManager {
             }
         })
             .catch((error) => {
-            debugLog('syncMissedChanges: error', { projectId: state.projectId, error: String(error), isStopping: state.isStopping });
+            debugLog('syncMissedChanges: error', {
+                projectId: state.projectId,
+                error: String(error),
+                isStopping: state.isStopping,
+            });
             // Only log if watcher hasn't been stopped
             if (!state.isStopping) {
                 console.error(`[WatchManager] Failed to sync missed changes for ${state.projectId}:`, error);

package/dist/mcp/tools/index.js

@@ -12,6 +12,8 @@ import { createListWatchersTool } from './list-watchers.tool.js';
 import { createNaturalLanguageToCypherTool } from './natural-language-to-cypher.tool.js';
 import { createParseTypescriptProjectTool } from './parse-typescript-project.tool.js';
 import { createSearchCodebaseTool } from './search-codebase.tool.js';
+import { createRestoreSessionBookmarkTool, createSaveSessionBookmarkTool } from './session-bookmark.tool.js';
+import { createRecallSessionNotesTool, createSaveSessionNoteTool } from './session-note.tool.js';
 import { createStartWatchProjectTool } from './start-watch-project.tool.js';
 import { createStopWatchProjectTool } from './stop-watch-project.tool.js';
 import { createSwarmClaimTaskTool } from './swarm-claim-task.tool.js';
@@ -73,4 +75,10 @@ export const registerAllTools = (server) => {
     createSwarmGetTasksTool(server);
     // Register swarm orchestration tool (meta-tool for coordinating multi-agent work)
     createSwarmOrchestrateTool(server);
+    // Register session bookmark tools (cross-session context continuity)
+    createSaveSessionBookmarkTool(server);
+    createRestoreSessionBookmarkTool(server);
+    // Register session note tools (durable observations and decisions)
+    createSaveSessionNoteTool(server);
+    createRecallSessionNotesTool(server);
 };

package/dist/mcp/tools/parse-typescript-project.tool.js

@@ -90,10 +90,10 @@ export const createParseTypescriptProjectTool = (server) => {
                 .optional()
                 .default('auto')
                 .describe('When to use streaming import: auto (>100 files), always, or never'),
-            async: z
+            async: z.coerce
                 .boolean()
                 .optional()
-                .default(false)
+                .default(true)
                 .describe('Run parsing in background and return job ID immediately. Use check_parse_status to monitor.'),
             watch: z
                 .boolean()
@@ -224,7 +224,8 @@ export const createParseTypescriptProjectTool = (server) => {
                 });
             const discoveredFiles = await parser.discoverSourceFiles();
             const totalFiles = discoveredFiles.length;
-            const shouldUseStreaming = useStreaming === 'always' || (useStreaming === 'auto' && totalFiles > PARSING.streamingThreshold && chunkSize > 0);
+            const shouldUseStreaming = useStreaming === 'always' ||
+                (useStreaming === 'auto' && totalFiles > PARSING.streamingThreshold && chunkSize > 0);
             console.error(`📊 Project has ${totalFiles} files. Streaming: ${shouldUseStreaming ? 'enabled' : 'disabled'}`);
             if (shouldUseStreaming && clearExisting !== false) {
                 // Use streaming import for large projects

package/dist/mcp/tools/session-bookmark.tool.js

@@ -0,0 +1,314 @@
+/**
+ * Session Bookmark Tools
+ * Save and restore session context for cross-session continuity
+ */
+import { z } from 'zod';
+import { Neo4jService } from '../../storage/neo4j/neo4j.service.js';
+import { TOOL_NAMES, TOOL_METADATA } from '../constants.js';
+import { createErrorResponse, createSuccessResponse, resolveProjectIdOrError, debugLog } from '../utils.js';
+/**
+ * Neo4j query to create a SessionBookmark node and link to code nodes
+ */
+const CREATE_BOOKMARK_QUERY = `
+  CREATE (b:SessionBookmark {
+    id: $bookmarkId,
+    projectId: $projectId,
+    sessionId: $sessionId,
+    agentId: $agentId,
+    summary: $summary,
+    workingSetNodeIds: $workingSetNodeIds,
+    taskContext: $taskContext,
+    findings: $findings,
+    nextSteps: $nextSteps,
+    metadata: $metadata,
+    createdAt: timestamp(),
+    updatedAt: timestamp()
+  })
+
+  // Link to referenced code nodes (exclude coordination nodes)
+  WITH b
+  OPTIONAL MATCH (target)
+  WHERE target.id IN $workingSetNodeIds
+    AND target.projectId = $projectId
+    AND NOT target:Pheromone
+    AND NOT target:SwarmTask
+    AND NOT target:SessionBookmark
+    AND NOT target:SessionNote
+  WITH b, collect(DISTINCT target) AS targets
+  FOREACH (t IN targets | MERGE (b)-[:REFERENCES]->(t))
+
+  RETURN b.id AS id,
+         b.sessionId AS sessionId,
+         b.agentId AS agentId,
+         b.summary AS summary,
+         b.taskContext AS taskContext,
+         b.createdAt AS createdAt,
+         size(targets) AS linkedNodes
+`;
+/**
+ * Neo4j query to find the most recent SessionBookmark matching filters
+ */
+const FIND_BOOKMARK_QUERY = `
+  MATCH (b:SessionBookmark)
+  WHERE b.projectId = $projectId
+    AND ($sessionId IS NULL OR b.sessionId = $sessionId)
+    AND ($agentId IS NULL OR b.agentId = $agentId)
+  RETURN b.id AS id,
+         b.projectId AS projectId,
+         b.sessionId AS sessionId,
+         b.agentId AS agentId,
+         b.summary AS summary,
+         b.workingSetNodeIds AS workingSetNodeIds,
+         b.taskContext AS taskContext,
+         b.findings AS findings,
+         b.nextSteps AS nextSteps,
+         b.metadata AS metadata,
+         b.createdAt AS createdAt,
+         b.updatedAt AS updatedAt
+  ORDER BY b.createdAt DESC
+  LIMIT 1
+`;
+/**
+ * Neo4j query to get code nodes referenced by a bookmark
+ */
+const GET_BOOKMARK_WORKING_SET_QUERY = `
+  MATCH (b:SessionBookmark {id: $bookmarkId, projectId: $projectId})-[:REFERENCES]->(target)
+  WHERE NOT target:Pheromone
+    AND NOT target:SwarmTask
+    AND NOT target:SessionBookmark
+    AND NOT target:SessionNote
+  RETURN target.id AS id,
+         target.projectId AS projectId,
+         labels(target)[0] AS type,
+         target.name AS name,
+         target.filePath AS filePath,
+         CASE WHEN $includeCode THEN target.sourceCode ELSE null END AS sourceCode,
+         target.coreType AS coreType,
+         target.semanticType AS semanticType,
+         target.startLine AS startLine,
+         target.endLine AS endLine
+  ORDER BY target.filePath, target.startLine
+`;
+/**
+ * Neo4j query to get SessionNote nodes linked to a bookmark's session
+ */
+const GET_SESSION_NOTES_QUERY = `
+  MATCH (n:SessionNote)
+  WHERE n.projectId = $projectId
+    AND n.sessionId = $sessionId
+  RETURN n.id AS id,
+         n.sessionId AS sessionId,
+         n.agentId AS agentId,
+         n.content AS content,
+         n.createdAt AS createdAt
+  ORDER BY n.createdAt ASC
+  LIMIT 50
+`;
+export const createSaveSessionBookmarkTool = (server) => {
+    server.registerTool(TOOL_NAMES.saveSessionBookmark, {
+        title: TOOL_METADATA[TOOL_NAMES.saveSessionBookmark].title,
+        description: TOOL_METADATA[TOOL_NAMES.saveSessionBookmark].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            sessionId: z.string().describe('Unique session identifier (e.g., conversation ID) for cross-session recovery'),
+            agentId: z.string().describe('Agent identifier for this bookmark'),
+            summary: z.string().min(10).describe('Brief summary of current work state (min 10 characters)'),
+            workingSetNodeIds: z
+                .array(z.string())
+                .describe('Code node IDs currently being focused on (from search_codebase or traverse_from_node)'),
+            taskContext: z.string().describe('High-level task currently being worked on'),
+            findings: z.string().optional().default('').describe('Key discoveries or decisions made so far'),
+            nextSteps: z.string().optional().default('').describe('What to do next when resuming this session'),
+            metadata: z.record(z.unknown()).optional().describe('Additional structured data to store with the bookmark'),
+        },
+    }, async ({ projectId, sessionId, agentId, summary, workingSetNodeIds, taskContext, findings = '', nextSteps = '', metadata, }) => {
+        const neo4jService = new Neo4jService();
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            const bookmarkId = `bookmark_${Date.now().toString(36)}_${Math.random().toString(36).substring(2, 8)}`;
+            const metadataJson = metadata ? JSON.stringify(metadata) : null;
+            const result = await neo4jService.run(CREATE_BOOKMARK_QUERY, {
+                bookmarkId,
+                projectId: resolvedProjectId,
+                sessionId,
+                agentId,
+                summary,
+                workingSetNodeIds,
+                taskContext,
+                findings,
+                nextSteps,
+                metadata: metadataJson,
+            });
+            if (result.length === 0) {
+                return createErrorResponse('Failed to create session bookmark');
+            }
+            const bookmark = result[0];
+            const linkedNodes = typeof bookmark.linkedNodes === 'object' && bookmark.linkedNodes?.toNumber
+                ? bookmark.linkedNodes.toNumber()
+                : (bookmark.linkedNodes ?? 0);
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                bookmarkId: bookmark.id,
+                sessionId: bookmark.sessionId,
+                agentId: bookmark.agentId,
+                projectId: resolvedProjectId,
+                summary: bookmark.summary,
+                taskContext: bookmark.taskContext,
+                workingSetSize: workingSetNodeIds.length,
+                linkedNodes,
+                createdAt: typeof bookmark.createdAt === 'object' && bookmark.createdAt?.toNumber
+                    ? bookmark.createdAt.toNumber()
+                    : bookmark.createdAt,
+                message: `Session bookmark saved. ${linkedNodes} of ${workingSetNodeIds.length} working set nodes linked in graph.`,
+            }));
+        }
+        catch (error) {
+            await debugLog('Save session bookmark error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};
+export const createRestoreSessionBookmarkTool = (server) => {
+    server.registerTool(TOOL_NAMES.restoreSessionBookmark, {
+        title: TOOL_METADATA[TOOL_NAMES.restoreSessionBookmark].title,
+        description: TOOL_METADATA[TOOL_NAMES.restoreSessionBookmark].description,
+        inputSchema: {
+            projectId: z.string().describe('Project ID, name, or path (e.g., "backend" or "proj_a1b2c3d4e5f6")'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Specific session ID to restore. If omitted, restores the most recent bookmark.'),
+            agentId: z
+                .string()
+                .optional()
+                .describe('Filter bookmarks by agent ID. If omitted, returns bookmarks from any agent.'),
+            includeCode: z
+                .boolean()
+                .optional()
+                .default(true)
+                .describe('Include source code snippets for working set nodes (default: true)'),
+            snippetLength: z
+                .number()
+                .int()
+                .min(50)
+                .max(5000)
+                .optional()
+                .default(500)
+                .describe('Maximum characters per code snippet (default: 500)'),
+        },
+    }, async ({ projectId, sessionId, agentId, includeCode = true, snippetLength = 500 }) => {
+        const neo4jService = new Neo4jService();
+        const projectResult = await resolveProjectIdOrError(projectId, neo4jService);
+        if (!projectResult.success) {
+            await neo4jService.close();
+            return projectResult.error;
+        }
+        const resolvedProjectId = projectResult.projectId;
+        try {
+            // Find the most recent matching bookmark
+            const bookmarkRows = await neo4jService.run(FIND_BOOKMARK_QUERY, {
+                projectId: resolvedProjectId,
+                sessionId: sessionId ?? null,
+                agentId: agentId ?? null,
+            });
+            if (bookmarkRows.length === 0) {
+                return createSuccessResponse(JSON.stringify({
+                    success: false,
+                    message: sessionId
+                        ? `No bookmark found for session "${sessionId}"${agentId ? ` and agent "${agentId}"` : ''}`
+                        : `No bookmarks found for this project${agentId ? ` and agent "${agentId}"` : ''}`,
+                    projectId: resolvedProjectId,
+                }));
+            }
+            const bm = bookmarkRows[0];
+            // Fetch working set nodes linked in the graph
+            const workingSetRows = await neo4jService.run(GET_BOOKMARK_WORKING_SET_QUERY, {
+                bookmarkId: bm.id,
+                projectId: resolvedProjectId,
+                includeCode,
+            });
+            // Fetch any session notes for this session
+            const noteRows = await neo4jService.run(GET_SESSION_NOTES_QUERY, {
+                projectId: resolvedProjectId,
+                sessionId: bm.sessionId,
+            });
+            // Build working set with optional code truncation
+            const workingSet = workingSetRows.map((row) => {
+                const node = {
+                    id: row.id,
+                    type: row.type,
+                    name: row.name,
+                    filePath: row.filePath,
+                    coreType: row.coreType,
+                    semanticType: row.semanticType,
+                    startLine: typeof row.startLine === 'object' && row.startLine?.toNumber ? row.startLine.toNumber() : row.startLine,
+                    endLine: typeof row.endLine === 'object' && row.endLine?.toNumber ? row.endLine.toNumber() : row.endLine,
+                };
+                if (includeCode && row.sourceCode) {
+                    const code = row.sourceCode;
+                    if (code.length <= snippetLength) {
+                        node.sourceCode = code;
+                    }
+                    else {
+                        const half = Math.floor(snippetLength / 2);
+                        node.sourceCode =
+                            code.substring(0, half) + '\n\n... [truncated] ...\n\n' + code.substring(code.length - half);
+                        node.truncated = true;
+                    }
+                }
+                return node;
+            });
+            const notes = noteRows.map((n) => ({
+                id: n.id,
+                sessionId: n.sessionId,
+                agentId: n.agentId,
+                content: n.content,
+                createdAt: typeof n.createdAt === 'object' && n.createdAt?.toNumber ? n.createdAt.toNumber() : n.createdAt,
+            }));
+            // Identify working set nodes not found in the graph (stale IDs after re-parse)
+            const foundIds = new Set(workingSetRows.map((r) => r.id));
+            const storedIds = Array.isArray(bm.workingSetNodeIds) ? bm.workingSetNodeIds : [];
+            const staleNodeIds = storedIds.filter((id) => !foundIds.has(id));
+            return createSuccessResponse(JSON.stringify({
+                success: true,
+                bookmark: {
+                    id: bm.id,
+                    projectId: resolvedProjectId,
+                    sessionId: bm.sessionId,
+                    agentId: bm.agentId,
+                    summary: bm.summary,
+                    taskContext: bm.taskContext,
+                    findings: bm.findings,
+                    nextSteps: bm.nextSteps,
+                    metadata: bm.metadata ? JSON.parse(bm.metadata) : null,
+                    createdAt: typeof bm.createdAt === 'object' && bm.createdAt?.toNumber ? bm.createdAt.toNumber() : bm.createdAt,
+                    updatedAt: typeof bm.updatedAt === 'object' && bm.updatedAt?.toNumber ? bm.updatedAt.toNumber() : bm.updatedAt,
+                },
+                workingSet,
+                notes,
+                staleNodeIds,
+                stats: {
+                    workingSetTotal: storedIds.length,
+                    workingSetFound: workingSet.length,
+                    workingSetStale: staleNodeIds.length,
+                    notesCount: notes.length,
+                },
+            }));
+        }
+        catch (error) {
+            await debugLog('Restore session bookmark error', { error: String(error) });
+            return createErrorResponse(error instanceof Error ? error : String(error));
+        }
+        finally {
+            await neo4jService.close();
+        }
+    });
+};