@brutalist/mcp 0.6.0 → 0.6.2

package/dist/brutalist-server.js

@@ -2,6 +2,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { randomUUID } from "crypto";
+import { appendFileSync } from "fs";
 import express from "express";
 import { z } from "zod";
 import { CLIAgentOrchestrator } from './cli-agents.js';
@@ -18,11 +19,14 @@ export class BrutalistServer {
     cliOrchestrator;
     httpTransport;
     responseCache;
+    actualPort;
+    shutdownHandler;
+    // Session tracking for security
+    activeSessions = new Map();
     constructor(config = {}) {
         this.config = {
             workingDirectory: process.cwd(),
             defaultTimeout: 1500000, // 25 minutes for thorough CLI analysis
-            enableSandbox: true,
             transport: 'stdio', // Default to stdio for backward compatibility
             httpPort: 3000,
             ...config
@@ -41,46 +45,114 @@ export class BrutalistServer {
         logger.info(`📦 Response cache initialized with ${cacheTTLHours} hour TTL`);
         this.server = new McpServer({
             name: "brutalist-mcp",
-            version: PACKAGE_VERSION,
+            version: PACKAGE_VERSION
+        }, {
             capabilities: {
-                tools: {}
+                tools: {},
+                logging: {},
+                experimental: {
+                    streaming: true
+                }
             }
         });
         this.registerTools();
     }
     handleStreamingEvent = (event) => {
-        // Send streaming event via MCP server (works for both stdio and HTTP transports)
         try {
-            logger.debug(`🔄 Streaming event: ${event.type} from ${event.agent} - ${event.content?.substring(0, 100)}...`);
-            // Convert streaming event to MCP notification format
-            this.server.sendLoggingMessage({
-                level: 'info',
-                data: event,
-                logger: 'brutalist-mcp-streaming'
-            });
-            logger.debug(`✅ Sent logging message for ${event.type} event`);
+            if (!event.sessionId) {
+                logger.warn("⚠️ Streaming event without session ID - dropping for security");
+                return;
+            }
+            logger.debug(`🔄 Session-scoped streaming: ${event.type} from ${event.agent} to session ${event.sessionId.substring(0, 8)}...`);
+            // For HTTP transport: send session-specific notification if client supports it
+            if (this.httpTransport) {
+                try {
+                    // Debug: Check what capabilities the server has
+                    logger.debug(`🔍 Server capabilities check: logging=${!!this.server.server._capabilities?.logging}`);
+                    // Use MCP server's notification system with session context
+                    this.server.server.notification({
+                        method: "notifications/message",
+                        params: {
+                            level: 'info',
+                            data: {
+                                type: 'streaming_event',
+                                sessionId: event.sessionId,
+                                agent: event.agent,
+                                eventType: event.type,
+                                content: event.content?.substring(0, 1000), // Truncate for safety
+                                timestamp: event.timestamp
+                            },
+                            logger: 'brutalist-mcp-streaming'
+                        }
+                    });
+                }
+                catch (notificationError) {
+                    // Client doesn't support logging notifications - silently skip
+                    logger.debug("Client doesn't support logging notifications, skipping streaming event");
+                }
+            }
+            // For STDIO transport: still send but with session info
+            else {
+                try {
+                    this.server.sendLoggingMessage({
+                        level: 'info',
+                        data: {
+                            sessionId: event.sessionId,
+                            agent: event.agent,
+                            type: event.type,
+                            content: event.content?.substring(0, 500) // More restrictive for stdio
+                        },
+                        logger: 'brutalist-mcp-streaming'
+                    });
+                }
+                catch (loggingError) {
+                    // Client doesn't support logging - silently skip
+                    logger.debug("Client doesn't support logging, skipping streaming event");
+                }
+            }
+            // Update session activity
+            if (this.activeSessions.has(event.sessionId)) {
+                this.activeSessions.get(event.sessionId).lastActivity = Date.now();
+            }
         }
         catch (error) {
-            logger.error("Failed to send streaming event", error);
+            logger.error("💥 Failed to send session-scoped streaming event", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId: event.sessionId?.substring(0, 8)
+            });
         }
     };
-    handleProgressUpdate = (progressToken, progress, total, message) => {
+    handleProgressUpdate = (progressToken, progress, total, message, sessionId) => {
         try {
-            logger.debug(`📊 Progress update: ${progress}/${total} - ${message}`);
-            // Send progress notification via MCP server
-            this.server.server.notification({
-                method: "notifications/progress",
-                params: {
-                    progressToken,
-                    progress,
-                    total,
-                    message
-                }
-            });
-            logger.debug(`✅ Sent progress notification: ${progress}/${total}`);
+            if (!sessionId) {
+                logger.warn("⚠️ Progress update without session ID - dropping for security");
+                return;
+            }
+            logger.debug(`📊 Session progress: ${progress}/${total} for session ${sessionId.substring(0, 8)}...`);
+            // Send progress notification with session context if client supports it
+            try {
+                this.server.server.notification({
+                    method: "notifications/progress",
+                    params: {
+                        progressToken,
+                        progress,
+                        total,
+                        message: `[${sessionId.substring(0, 8)}] ${message}`, // Include session prefix
+                        sessionId // Include in notification data
+                    }
+                });
+                logger.debug(`✅ Sent session-scoped progress notification: ${progress}/${total}`);
+            }
+            catch (notificationError) {
+                // Client doesn't support progress notifications - silently skip
+                logger.debug("Client doesn't support progress notifications, skipping");
+            }
         }
         catch (error) {
-            logger.error("Failed to send progress notification", error);
+            logger.error("💥 Failed to send progress notification", {
+                error: error instanceof Error ? error.message : String(error),
+                sessionId: sessionId?.substring(0, 8)
+            });
         }
     };
     async start() {
@@ -118,13 +190,57 @@ export class BrutalistServer {
         // Create Express app for HTTP handling
         const app = express();
         app.use(express.json({ limit: '10mb' })); // Add JSON size limit for security
-        // Enable CORS for development
+        // Secure CORS implementation
         app.use((req, res, next) => {
-            res.header('Access-Control-Allow-Origin', '*');
-            res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS, DELETE');
-            res.header('Access-Control-Allow-Headers', 'Content-Type, Authorization, Mcp-Session-Id');
+            const origin = req.headers.origin;
+            const isProduction = process.env.NODE_ENV === 'production';
+            // Define safe default origins for development
+            const defaultDevOrigins = [
+                'http://localhost:3000',
+                'http://127.0.0.1:3000',
+                'http://localhost:8080',
+                'http://127.0.0.1:8080',
+                'http://localhost:3001',
+                'http://127.0.0.1:3001'
+            ];
+            // Get allowed origins from config or use defaults
+            const allowedOrigins = this.config.corsOrigins || defaultDevOrigins;
+            const allowWildcard = this.config.allowCORSWildcard === true && !isProduction;
+            // Determine if origin is allowed
+            let allowedOrigin = null;
+            if (allowWildcard) {
+                // Only in development with explicit opt-in
+                allowedOrigin = '*';
+                logger.warn("⚠️ Using wildcard CORS - only safe in development!");
+            }
+            else if (!origin) {
+                // No origin header (same-origin or direct server access)
+                allowedOrigin = defaultDevOrigins[0]; // Default fallback
+            }
+            else if (allowedOrigins.includes(origin)) {
+                // Explicitly allowed origin
+                allowedOrigin = origin;
+            }
+            else {
+                // Rejected origin
+                logger.warn(`🚫 CORS rejected origin: ${origin}`);
+                allowedOrigin = null;
+            }
+            // Set headers only if origin is allowed
+            if (allowedOrigin) {
+                res.header('Access-Control-Allow-Origin', allowedOrigin);
+                res.header('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+                res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+                // Removed Authorization header for security
+                res.header('Access-Control-Allow-Credentials', 'false'); // Explicit false
+            }
             if (req.method === 'OPTIONS') {
-                res.sendStatus(200);
+                if (allowedOrigin) {
+                    res.sendStatus(200);
+                }
+                else {
+                    res.sendStatus(403); // Forbidden for disallowed origins
+                }
                 return;
             }
             next();
@@ -146,21 +262,44 @@ export class BrutalistServer {
             res.json({ status: 'ok', transport: 'http-streaming', version: PACKAGE_VERSION });
         });
         // Start the HTTP server - bind to localhost only for security
-        const port = this.config.httpPort || 3000;
-        const server = app.listen(port, '127.0.0.1', () => {
-            logger.info(`HTTP server listening on port ${port}`);
-            logger.info(`MCP endpoint: http://localhost:${port}/mcp`);
-            logger.info(`Health check: http://localhost:${port}/health`);
-        });
-        // Handle graceful shutdown
-        process.on('SIGTERM', () => {
-            logger.info('Received SIGTERM, shutting down gracefully');
-            server.close(() => {
-                logger.info('HTTP server closed');
-                process.exit(0);
+        const port = this.config.httpPort ?? 3000;
+        return new Promise((resolve, reject) => {
+            const server = app.listen(port, '127.0.0.1', () => {
+                const actualPort = server.address()?.port || port;
+                this.actualPort = actualPort;
+                logger.info(`HTTP server listening on port ${actualPort}`);
+                logger.info(`MCP endpoint: http://localhost:${actualPort}/mcp`);
+                logger.info(`Health check: http://localhost:${actualPort}/health`);
+                resolve();
+            });
+            server.on('error', (error) => {
+                logger.error('HTTP server failed to start', error);
+                reject(error);
             });
+            // Handle graceful shutdown - avoid duplicate listeners
+            if (!this.shutdownHandler) {
+                this.shutdownHandler = () => {
+                    logger.info('Received SIGTERM, shutting down gracefully');
+                    server.close(() => {
+                        logger.info('HTTP server closed');
+                        process.exit(0);
+                    });
+                };
+                process.on('SIGTERM', this.shutdownHandler);
+            }
         });
     }
+    // Getter for actual listening port (useful for tests)
+    getActualPort() {
+        return this.actualPort;
+    }
+    // Cleanup method for tests - remove event listeners
+    cleanup() {
+        if (this.shutdownHandler) {
+            process.removeListener('SIGTERM', this.shutdownHandler);
+            this.shutdownHandler = undefined;
+        }
+    }
     registerTools() {
         // Register all roast tools using unified handler - DRY principle
         TOOL_CONFIGS.forEach(config => {
@@ -180,7 +319,6 @@ export class BrutalistServer {
             debateRounds: z.number().optional().describe("Number of debate rounds (default: 2, max: 10)"),
             context: z.string().optional().describe("Additional context for the debate"),
             workingDirectory: z.string().optional().describe("Working directory for analysis"),
-            enableSandbox: z.boolean().optional().describe("Enable sandbox mode for security"),
             models: z.object({
                 claude: z.string().optional().describe("Claude model: opus, sonnet, or full name like claude-opus-4-1-20250805"),
                 codex: z.string().optional().describe("Codex model: gpt-5, gpt-5-codex, o3, o3-mini, o3-pro, o4-mini"),
@@ -189,7 +327,7 @@ export class BrutalistServer {
         }, async (args) => {
             return this.handleToolExecution(async () => {
                 const debateRounds = Math.min(args.debateRounds || 2, 10); // Limit to max 10 rounds to prevent DoS
-                const responses = await this.executeCLIDebate(args.targetPath, debateRounds, args.context, args.workingDirectory, args.enableSandbox, args.models);
+                const responses = await this.executeCLIDebate(args.targetPath, debateRounds, args.context, args.workingDirectory, args.models);
                 return responses;
             });
         });
@@ -216,7 +354,7 @@ export class BrutalistServer {
                 roster += "- `cli_agent_roster` - This tool (show capabilities)\n\n";
                 roster += "## CLI Agent Capabilities\n";
                 roster += "**Claude Code** - Advanced analysis with direct system prompt injection\n";
-                roster += "**Codex** - Sandboxed execution with embedded brutal prompts\n";
+                roster += "**Codex** - Secure execution with embedded brutal prompts\n";
                 roster += "**Gemini CLI** - Workspace context with environment variable system prompts\n\n";
                 // Add CLI context information
                 const cliContext = await this.cliOrchestrator.detectCLIContext();
@@ -247,6 +385,38 @@ export class BrutalistServer {
     async handleRoastTool(config, args, extra) {
         try {
             const progressToken = extra._meta?.progressToken;
+            // Extract session context for security
+            // IMPORTANT: Use consistent "anonymous" for all anonymous users to enable cache sharing
+            const sessionId = extra?.sessionId ||
+                extra?._meta?.sessionId ||
+                extra?.headers?.['mcp-session-id'] ||
+                'anonymous'; // Consistent for cache sharing across pagination requests
+            const requestId = `${sessionId}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+            logger.debug(`🔐 Processing request with session: ${sessionId.substring(0, 8)}..., request: ${requestId.substring(0, 12)}...`);
+            // Track session activity
+            if (!this.activeSessions.has(sessionId)) {
+                this.activeSessions.set(sessionId, {
+                    startTime: Date.now(),
+                    requestCount: 0,
+                    lastActivity: Date.now()
+                });
+            }
+            const sessionInfo = this.activeSessions.get(sessionId);
+            sessionInfo.requestCount++;
+            sessionInfo.lastActivity = Date.now();
+            // Debug logging: Log the received arguments to file
+            const debugLog = `/tmp/brutalist-tool-debug-${Date.now()}.log`;
+            const logMessage = (msg) => {
+                try {
+                    appendFileSync(debugLog, `${new Date().toISOString()}: ${msg}\n`);
+                }
+                catch (e) {
+                    // Ignore filesystem errors
+                }
+            };
+            logMessage(`🔧 ROAST TOOL DEBUG: Tool=${config.name}, primaryArgField=${config.primaryArgField}`);
+            logMessage(`🔧 ROAST TOOL DEBUG: args=${JSON.stringify(args, null, 2)}`);
+            logMessage(`🔧 ROAST TOOL DEBUG: extra=${JSON.stringify(extra, null, 2)}`);
             // Extract pagination parameters
             const paginationParams = extractPaginationParams(args);
             if (args.cursor) {
@@ -255,9 +425,9 @@ export class BrutalistServer {
             }
             // Check cache if analysis_id provided
             if (args.analysis_id && !args.force_refresh) {
-                const cachedContent = await this.responseCache.get(args.analysis_id);
+                const cachedContent = await this.responseCache.get(args.analysis_id, sessionId);
                 if (cachedContent) {
-                    logger.info(`🎯 Using cached result for analysis_id: ${args.analysis_id}`);
+                    logger.info(`🎯 Cache HIT for analysis_id: ${args.analysis_id}`);
                     const cachedResult = {
                         success: true,
                         responses: [{
@@ -269,6 +439,13 @@ export class BrutalistServer {
                     };
                     return this.formatToolResponse(cachedResult, args.verbose, paginationParams, args.analysis_id);
                 }
+                else {
+                    logger.warn(`❌ Cache MISS for analysis_id: ${args.analysis_id}, session: ${sessionId}`);
+                    // Don't silently re-run - analysis_id should always hit cache or error
+                    throw new Error(`Analysis ID "${args.analysis_id}" not found in cache. ` +
+                        `It may have expired (2 hour TTL) or belong to a different session. ` +
+                        `Remove analysis_id parameter to run a new analysis.`);
+                }
             }
             // Generate cache key for this request
             const cacheKey = this.responseCache.generateCacheKey(config.cacheKeyFields.reduce((acc, field) => {
@@ -279,9 +456,13 @@ export class BrutalistServer {
             }, {}));
             // Check if we have a cached result (unless forcing refresh)
             if (!args.force_refresh) {
-                const cachedContent = await this.responseCache.get(cacheKey);
+                const cachedContent = await this.responseCache.get(cacheKey, sessionId);
                 if (cachedContent) {
-                    const analysisId = this.responseCache.generateAnalysisId(cacheKey);
+                    // Get existing analysis_id or create new alias
+                    const existingAnalysisId = this.responseCache.findAnalysisIdForKey(cacheKey);
+                    const analysisId = existingAnalysisId
+                        ? this.responseCache.createAlias(existingAnalysisId, cacheKey)
+                        : this.responseCache.generateAnalysisId(cacheKey);
                     logger.info(`🎯 Cache hit for new request, using analysis_id: ${analysisId}`);
                     const cachedResult = {
                         success: true,
@@ -299,8 +480,10 @@ export class BrutalistServer {
             const context = config.contextBuilder ? config.contextBuilder(args) : args.context;
             // Get the primary argument (targetPath, idea, architecture, etc.)
             const primaryArg = args[config.primaryArgField];
+            logMessage(`🔧 PRIMARY ARG DEBUG: primaryArgField=${config.primaryArgField}, primaryArg="${primaryArg}"`);
+            logMessage(`🔧 PRIMARY ARG DEBUG: config.analysisType="${config.analysisType}"`);
             // Run the analysis
-            const result = await this.executeBrutalistAnalysis(config.analysisType, primaryArg, config.systemPrompt, context, args.workingDirectory, args.enableSandbox, args.preferredCLI, args.verbose, args.models, progressToken);
+            const result = await this.executeBrutalistAnalysis(config.analysisType, primaryArg, config.systemPrompt, context, args.workingDirectory, args.preferredCLI, args.verbose, args.models, progressToken, sessionId, requestId);
             // Cache the result if successful
             let analysisId;
             if (result.success && result.responses.length > 0) {
@@ -312,9 +495,11 @@ export class BrutalistServer {
                             acc[field] = args[field];
                         return acc;
                     }, {});
-                    const { analysisId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey);
+                    const { analysisId: newId } = await this.responseCache.set(cacheData, fullContent, cacheKey, sessionId, // NEW: Bind to session
+                    requestId // NEW: Track request
+                    );
                     analysisId = newId;
-                    logger.info(`✅ Cached analysis result with ID: ${analysisId}`);
+                    logger.info(`✅ Cached analysis result with ID: ${analysisId} for session: ${sessionId?.substring(0, 8)}`);
                 }
             }
             return this.formatToolResponse(result, args.verbose, paginationParams, analysisId);
@@ -323,12 +508,11 @@ export class BrutalistServer {
             return this.formatErrorResponse(error);
         }
     }
-    async executeCLIDebate(targetPath, debateRounds, context, workingDirectory, enableSandbox, models) {
+    async executeCLIDebate(targetPath, debateRounds, context, workingDirectory, models) {
         logger.debug("Executing CLI debate", {
             targetPath,
             debateRounds,
             workingDirectory,
-            enableSandbox
         });
         try {
             // Get CLI context
@@ -372,13 +556,14 @@ Remember: You are ${agent.toUpperCase()}, the passionate champion of ${position.
                 logger.info(`🎭 ${agent.toUpperCase()} preparing initial position: ${position.split(':')[0]}`);
                 const response = await this.cliOrchestrator.executeSingleCLI(agent, assignedPrompt, assignedPrompt, {
                     workingDirectory: workingDirectory || this.config.workingDirectory,
-                    sandbox: enableSandbox ?? this.config.enableSandbox,
                     timeout: (this.config.defaultTimeout || 60000) * 2,
                     models: models ? { [agent]: models[agent] } : undefined
                 });
                 if (response.success) {
                     debateContext.push(response);
-                    fullDebateTranscript.get(agent)?.push(response.output);
+                    if (response.output) {
+                        fullDebateTranscript.get(agent)?.push(response.output);
+                    }
                 }
             }
             // Subsequent rounds: Turn-based responses attacking specific arguments
@@ -420,13 +605,14 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                     logger.info(`🔥 Round ${round}: ${currentAgent.toUpperCase()} responding to opponents (${assignedPosition.split(':')[0]})`);
                     const response = await this.cliOrchestrator.executeSingleCLI(currentAgent, confrontationalPrompt, confrontationalPrompt, {
                         workingDirectory: workingDirectory || this.config.workingDirectory,
-                        sandbox: enableSandbox ?? this.config.enableSandbox,
                         timeout: (this.config.defaultTimeout || 60000) * 2,
                         models: models ? { [currentAgent]: models[currentAgent] } : undefined
                     });
                     if (response.success) {
                         debateContext.push(response);
-                        fullDebateTranscript.get(currentAgent)?.push(response.output);
+                        if (response.output) {
+                            fullDebateTranscript.get(currentAgent)?.push(response.output);
+                        }
                     }
                 }
             }
@@ -469,7 +655,9 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             if (!agentOutputs.has(response.agent)) {
                 agentOutputs.set(response.agent, []);
             }
-            agentOutputs.get(response.agent)?.push(response.output);
+            if (response.output) {
+                agentOutputs.get(response.agent)?.push(response.output);
+            }
         });
         synthesis += `## Key Points of Conflict\n\n`;
         // Extract disagreements by looking for contradictory keywords
@@ -516,15 +704,14 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         }
         return synthesis;
     }
-    async executeBrutalistAnalysis(analysisType, targetPath, systemPromptSpec, context, workingDirectory, enableSandbox, preferredCLI, verbose, models, progressToken) {
+    async executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, workingDirectory, preferredCLI, verbose, models, progressToken, sessionId, requestId) {
         logger.info(`🏢 Starting brutalist analysis: ${analysisType}`);
-        logger.info(`🔧 DEBUG: preferredCLI=${preferredCLI}, targetPath=${targetPath}`);
+        logger.info(`🔧 DEBUG: preferredCLI=${preferredCLI}, primaryContent=${primaryContent}`);
         logger.debug("Executing brutalist analysis", {
-            targetPath,
+            primaryContent,
             analysisType,
             systemPromptSpec,
             workingDirectory,
-            enableSandbox,
             preferredCLI
         });
         try {
@@ -535,16 +722,18 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
             // Execute CLI agent analysis (single or multi-CLI based on preferences)
             logger.info(`🔍 Executing brutalist analysis with timeout: ${this.config.defaultTimeout}ms`);
             logger.info(`🔧 DEBUG: About to call cliOrchestrator.executeBrutalistAnalysis`);
-            const responses = await this.cliOrchestrator.executeBrutalistAnalysis(analysisType, targetPath, systemPromptSpec, context, {
+            const responses = await this.cliOrchestrator.executeBrutalistAnalysis(analysisType, primaryContent, systemPromptSpec, context, {
                 workingDirectory: workingDirectory || this.config.workingDirectory,
-                sandbox: enableSandbox ?? this.config.enableSandbox,
                 timeout: this.config.defaultTimeout,
                 preferredCLI,
                 analysisType: analysisType,
                 models,
                 onStreamingEvent: this.handleStreamingEvent,
                 progressToken,
-                onProgress: progressToken ? this.handleProgressUpdate.bind(this, progressToken) : undefined
+                onProgress: progressToken && sessionId ?
+                    (progress, total, message) => this.handleProgressUpdate(progressToken, progress, total, message, sessionId) : undefined,
+                sessionId,
+                requestId
             });
             logger.info(`🔧 DEBUG: cliOrchestrator.executeBrutalistAnalysis returned ${responses.length} responses`);
             const successfulResponses = responses.filter(r => r.success);
@@ -558,7 +747,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 responses,
                 synthesis,
                 analysisType,
-                targetPath,
+                targetPath: primaryContent,
                 executionSummary: {
                     totalCLIs: responses.length,
                     successfulCLIs: successfulResponses.length,
@@ -663,10 +852,13 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         const chunks = chunker.chunkText(content);
         // Find the appropriate chunk based on offset
         let targetChunk = chunks[0]; // Default to first chunk
+        let targetChunkIndex = 0;
         let currentOffset = 0;
-        for (const chunk of chunks) {
+        for (let i = 0; i < chunks.length; i++) {
+            const chunk = chunks[i];
             if (offset >= chunk.startOffset && offset < chunk.endOffset) {
                 targetChunk = chunk;
+                targetChunkIndex = i;
                 break;
             }
             currentOffset = chunk.endOffset;
@@ -674,47 +866,58 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
         const chunkContent = targetChunk.content;
         const actualOffset = targetChunk.startOffset;
         const endOffset = targetChunk.endOffset;
-        // Create pagination metadata
-        const pagination = createPaginationMetadata(content.length, paginationParams, limit);
+        // Create pagination metadata using actual chunk boundaries
+        const pagination = createPaginationMetadata(content.length, paginationParams, limit, chunks, targetChunkIndex);
         const statusLine = formatPaginationStatus(pagination);
         // Estimate token usage for user awareness
         const chunkTokens = estimateTokenCount(chunkContent);
         const totalTokens = estimateTokenCount(content);
         // Format response with pagination info
         let paginatedText = '';
-        // Add pagination header with analysis ID
+        // Add header
         paginatedText += `# Brutalist Analysis Results\n\n`;
-        paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
-        if (analysisId) {
+        // Show pagination metadata
+        const needsPagination = pagination.totalChunks > 1 || pagination.hasMore;
+        const isFirstRequest = offset === 0;
+        // Always show analysis_id on first request for future pagination
+        if (isFirstRequest && analysisId) {
             paginatedText += `**🔑 Analysis ID:** ${analysisId}\n`;
+            paginatedText += `**🔢 Token Estimate:** ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
         }
-        paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
-        if (pagination.hasMore) {
-            if (analysisId) {
-                paginatedText += `**⏭️ Continue Reading:** Use \`analysis_id: "${analysisId}", offset: ${endOffset}\`\n\n`;
+        if (needsPagination) {
+            paginatedText += `**📊 Pagination Status:** ${statusLine}\n`;
+            if (!isFirstRequest && analysisId) {
+                paginatedText += `**🔑 Analysis ID:** ${analysisId}\n`;
             }
-            else {
-                paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
+            paginatedText += `**🔢 Token Estimate:** ~${chunkTokens.toLocaleString()} tokens (chunk) / ~${totalTokens.toLocaleString()} tokens (total)\n\n`;
+            if (pagination.hasMore) {
+                if (analysisId) {
+                    paginatedText += `**⏭️ Continue Reading:** Use \`analysis_id: "${analysisId}", offset: ${endOffset}\`\n\n`;
+                }
+                else {
+                    paginatedText += `**⏭️ Continue Reading:** Use \`offset: ${endOffset}\` for next chunk\n\n`;
+                }
             }
         }
         paginatedText += `---\n\n`;
         // Add the actual content chunk
         paginatedText += chunkContent;
-        // Add footer for continuation
-        if (pagination.hasMore) {
+        // Add footer
+        if (needsPagination) {
             paginatedText += `\n\n---\n\n`;
-            paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
-            if (analysisId) {
-                paginatedText += `🔄 To continue: Include \`analysis_id: "${analysisId}"\` with \`offset: ${endOffset}\` in next request`;
+            if (pagination.hasMore) {
+                paginatedText += `📖 **End of chunk ${pagination.chunkIndex}/${pagination.totalChunks}**\n`;
+                if (analysisId) {
+                    paginatedText += `🔄 To continue: Include \`analysis_id: "${analysisId}"\` with \`offset: ${endOffset}\` in next request`;
+                }
+                else {
+                    paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;
+                }
             }
             else {
-                paginatedText += `🔄 To continue: Use same tool with \`offset: ${endOffset}\``;
+                paginatedText += `✅ **Complete analysis shown** (${content.length.toLocaleString()} characters total)`;
             }
         }
-        else {
-            paginatedText += `\n\n---\n\n`;
-            paginatedText += `✅ **Complete analysis shown** (${content.length.toLocaleString()} characters total)`;
-        }
         // Add verbose execution details if requested
         if (verbose && result.executionSummary) {
             paginatedText += `\n\n### Execution Summary\n`;
@@ -742,7 +945,7 @@ Remember: You are ${currentAgent.toUpperCase()}, passionate advocate for ${assig
                 sanitizedMessage = "Analysis timed out - try reducing scope or increasing timeout";
             }
             else if (error.message.includes('ENOENT') || error.message.includes('no such file')) {
-                sanitizedMessage = "Target path not found";
+                sanitizedMessage = `DEBUG: Target path not found - Original error: ${error.message}`;
             }
             else if (error.message.includes('EACCES') || error.message.includes('permission denied')) {
                 sanitizedMessage = "Permission denied - check file access";