onbuzz 3.4.0 → 3.6.2

package/src/core/agentPool.js

@@ -400,6 +400,10 @@ class AgentPool {
             newConversation.compactizationStrategy = oldConversation.compactizationStrategy;
             newConversation.originalTokenCount = oldConversation.originalTokenCount;
             newConversation.compactedTokenCount = oldConversation.compactedTokenCount;
+            // CRITICAL: Copy the sync watermark too — without this, getMessagesForAI
+            // cannot sync new messages to compactizedMessages after a model switch,
+            // causing the AI to only see the compacted summary and repeat itself endlessly.
+            newConversation.originalMessageCountAtCompaction = oldConversation.originalMessageCountAtCompaction;
           }
 
           newConversation.lastUpdated = new Date().toISOString();
@@ -829,7 +833,17 @@ class AgentPool {
       }
     } catch (error) {
       this.logger.warn(`Failed to clean up visual editor for agent: ${error.message}`, { agentId });
-      // Continue with agent deletion even if visual editor cleanup fails
+    }
+
+    // Kill any running terminal processes for this agent
+    try {
+      const terminalTool = this.toolsRegistry?.getTool?.('terminal');
+      if (terminalTool && typeof terminalTool.cleanupAgent === 'function') {
+        await terminalTool.cleanupAgent(agentId);
+        this.logger.info(`Terminal processes cleaned up for agent: ${agentId}`);
+      }
+    } catch (error) {
+      this.logger.warn(`Failed to clean up terminal processes for agent: ${error.message}`, { agentId });
     }
 
     // Clean up agent resources
@@ -1554,7 +1568,11 @@ class AgentPool {
     // vs which ones were already included in the compaction (sandwich strategy)
     const compactedLength = conversation.compactizedMessages.length;
     const originalLength = conversation.messages.length;
-    const originalCountAtCompaction = conversation.originalMessageCountAtCompaction || originalLength;
+    // SAFETY: If watermark is null/undefined (bug, migration, or cleared state),
+    // fall back to compactedLength — NOT originalLength. Using originalLength silently
+    // drops all unsynced messages because (originalLength > originalLength) is always false.
+    // Using compactedLength ensures any messages beyond what's in the compacted array get synced.
+    const originalCountAtCompaction = conversation.originalMessageCountAtCompaction ?? compactedLength;
 
     // Only sync if NEW messages were added after compaction
     // (i.e., current original length > original length when compaction happened)
@@ -1721,7 +1739,10 @@ class AgentPool {
     if (!conversation || !conversation.compactizedMessages) return { synced: 0 };
 
     const originalLength = conversation.messages.length;
-    const originalCountAtCompaction = conversation.originalMessageCountAtCompaction || originalLength;
+    const compactedLength = conversation.compactizedMessages.length;
+    // SAFETY: Use ?? compactedLength instead of || originalLength to prevent silent message loss
+    // when watermark is null (see getMessagesForAI for detailed explanation)
+    const originalCountAtCompaction = conversation.originalMessageCountAtCompaction ?? compactedLength;
 
     if (originalLength > originalCountAtCompaction) {
       const newCount = originalLength - originalCountAtCompaction;
@@ -1734,7 +1755,8 @@ class AgentPool {
         modelId,
         synced: newCount,
         newMessageRoles: newMessages.map(m => m.role),
-        compactizedMessagesLength: conversation.compactizedMessages.length
+        compactizedMessagesLength: conversation.compactizedMessages.length,
+        watermarkWasNull: conversation.originalMessageCountAtCompaction === null
       });
 
       return { synced: newCount };

package/src/core/agentScheduler.js

@@ -664,11 +664,11 @@ class AgentScheduler {
       });
     }
 
-    // Add tool results as context, grouped by the AI turn that triggered them
+    // Build tool results as a SEPARATE message (role: 'user' with tool-result type marker)
+    // so they are distinguishable from actual user messages in the conversation history.
     const toolResults = allMessages.filter(m => m.queueType === 'toolResults');
+    let toolResultContent = '';
     if (toolResults.length > 0) {
-      if (consolidatedContent) consolidatedContent += '\n\n';
-
       // Group results by responseTurnId (the AI message that triggered them)
       const turnGroups = new Map();
       for (const msg of toolResults) {
@@ -681,20 +681,20 @@ class AgentScheduler {
       const turnCount = turnGroups.size;
       const toolCount = toolResults.length;
       const toolIds = [...new Set(toolResults.map(m => m.toolId).filter(Boolean))];
-      consolidatedContent += `[Tool Results — ${toolCount} result${toolCount > 1 ? 's' : ''} from ${turnCount} tool batch${turnCount > 1 ? 'es' : ''}: ${toolIds.join(', ')}]\n`;
+      toolResultContent += `[Tool Results — ${toolCount} result${toolCount > 1 ? 's' : ''} from ${turnCount} tool batch${turnCount > 1 ? 'es' : ''}: ${toolIds.join(', ')}]\n`;
 
       if (turnCount === 1) {
         // Single batch — flat list (no sub-headers needed)
         toolResults.forEach(msg => {
-          consolidatedContent += `${this.formatToolResult(msg)}\n`;
+          toolResultContent += `${this.formatToolResult(msg)}\n`;
         });
       } else {
         // Multiple batches — group with labeled sub-headers
         let batchIndex = 1;
         for (const [, group] of turnGroups) {
-          consolidatedContent += `\n--- Batch ${batchIndex} of ${turnCount} ---\n`;
+          toolResultContent += `\n--- Batch ${batchIndex} of ${turnCount} ---\n`;
           group.forEach(msg => {
-            consolidatedContent += `${this.formatToolResult(msg)}\n`;
+            toolResultContent += `${this.formatToolResult(msg)}\n`;
           });
           batchIndex++;
         }
@@ -709,18 +709,49 @@ class AgentScheduler {
     // PHASE 2: Auto-create tasks for incoming messages
     await this.autoCreateTasksForMessages(agentId, userMessages, interAgentMessages);
 
-    // Create single consolidated user message for AI processing
-    const consolidatedMessage = {
-      id: `consolidated-${Date.now()}`,
-      role: MESSAGE_ROLES.USER,
-      content: consolidatedContent.trim(),
-      timestamp: new Date().toISOString(),
-      type: 'consolidated-input',
-      originalMessageCount: allMessages.length
-    };
+    // Decide message strategy based on what's queued:
+    // - Tool results only → single message with type: 'tool-result' (most common in agent loops)
+    // - User/inter-agent only → single message with type: 'consolidated-input'
+    // - Both → must merge into single user message (API requires alternating user/assistant)
+    const hasNonToolContent = consolidatedContent.trim().length > 0;
 
-    // Add to conversation history (don't broadcast - this is internal)
-    await this.addMessageToConversation(agentId, consolidatedMessage, false);
+    if (toolResultContent && !hasNonToolContent) {
+      // TOOL RESULTS ONLY — add as dedicated tool-result message
+      const toolMessage = {
+        id: `tool-result-${Date.now()}`,
+        role: MESSAGE_ROLES.USER,
+        content: toolResultContent.trim(),
+        timestamp: new Date().toISOString(),
+        type: 'tool-result',
+        originalMessageCount: toolResults.length
+      };
+      await this.addMessageToConversation(agentId, toolMessage, false);
+    } else if (!toolResultContent && hasNonToolContent) {
+      // USER/INTER-AGENT ONLY — add as user message
+      const userMessage = {
+        id: `consolidated-${Date.now()}`,
+        role: MESSAGE_ROLES.USER,
+        content: consolidatedContent.trim(),
+        timestamp: new Date().toISOString(),
+        type: 'consolidated-input',
+        originalMessageCount: userMessages.length + interAgentMessages.length
+      };
+      await this.addMessageToConversation(agentId, userMessage, false);
+    } else if (toolResultContent && hasNonToolContent) {
+      // BOTH — merge into single message to avoid consecutive user messages
+      // (API requires strict user/assistant alternation)
+      // Put tool results first, then user content (user content is higher priority context)
+      const mergedContent = toolResultContent.trim() + '\n\n' + consolidatedContent.trim();
+      const mergedMessage = {
+        id: `consolidated-${Date.now()}`,
+        role: MESSAGE_ROLES.USER,
+        content: mergedContent,
+        timestamp: new Date().toISOString(),
+        type: 'consolidated-input',
+        originalMessageCount: allMessages.length
+      };
+      await this.addMessageToConversation(agentId, mergedMessage, false);
+    }
 
     // CRITICAL: Update conversation tracking when inter-agent messages are processed
     if (agent && interAgentMessages.length > 0) {
@@ -1604,9 +1635,12 @@ class AgentScheduler {
           sessionId: sessionId,
           platformProvided: platformProvided,
           onChunk: (chunk) => {
+            // Normalize chunk to string — some providers (Ollama) send {content, type} objects
+            const chunkText = typeof chunk === 'string' ? chunk : (chunk?.content || chunk?.text || String(chunk));
+
             // Update flow progress if in flow execution
             if (flowProgress) {
-              flowProgress.charactersStreamed += chunk.length;
+              flowProgress.charactersStreamed += chunkText.length;
               flowProgress.chunkCount++;
 
               // Broadcast flow progress every 500ms or 50 chunks
@@ -1622,7 +1656,7 @@ class AgentScheduler {
               type: 'stream_chunk',
               agentId,
               messageId: streamMessageId,
-              content: chunk,
+              content: chunkText,
               timestamp: new Date().toISOString(),
               // Include flow context if present
               ...(flowContext && {
@@ -2089,7 +2123,10 @@ class AgentScheduler {
       // The scheduler's addMessageToConversation only pushes to conversation.messages.
       if (modelConversation.compactizedMessages) {
         const originalLength = modelConversation.messages.length;
-        const originalCount = modelConversation.originalMessageCountAtCompaction || originalLength;
+        const compactedLength = modelConversation.compactizedMessages.length;
+        // SAFETY: Use ?? compactedLength instead of || originalLength to prevent silent message loss
+        // when watermark is null (see agentPool.getMessagesForAI for detailed explanation)
+        const originalCount = modelConversation.originalMessageCountAtCompaction ?? compactedLength;
         if (originalLength > originalCount) {
           const newCount = originalLength - originalCount;
           const newMessages = modelConversation.messages.slice(-newCount);
@@ -2446,6 +2483,27 @@ class AgentScheduler {
         toolCount: toolExecutions.length,
         hasError: !!error
       });
+
+      // If any filesystem tool ran, broadcast updated artifacts to UI
+      const hasFilesystemOps = toolExecutions.some(t => t.toolId === 'filesystem');
+      if (hasFilesystemOps && !error) {
+        try {
+          const agent = this.agentPool.agents?.get(agentId);
+          if (agent?.artifacts && Object.keys(agent.artifacts).length > 0) {
+            this.webSocketManager.broadcastToSession(sessionId, {
+              type: 'artifacts_updated',
+              data: {
+                agentId,
+                artifacts: agent.artifacts,
+                workingDirectory: agent.directoryAccess?.workingDirectory || ''
+              }
+            });
+            console.log('[Artifacts] Broadcast to session:', sessionId, Object.keys(agent.artifacts).length, 'files');
+          }
+        } catch (e) {
+          // Non-fatal — UI can still fetch via API
+        }
+      }
     }
   }
 

package/src/core/messageProcessor.js

@@ -412,12 +412,12 @@ class MessageProcessor {
         });
         
         let result;
+        let toolInput = command.parameters; // Hoisted for artifact tracking access
         if (command.isAsync) {
           result = await this.executeAsyncTool(command, tool, context);
         } else {
           // Synchronous tool execution
           // If we have parameters object, use it. Otherwise parse the content.
-          let toolInput = command.parameters;
 
           if (!toolInput && command.content) {
             // Content is a string, need to parse it using tool's parseParameters method
@@ -475,7 +475,16 @@ class MessageProcessor {
         }
         
         results.push(result);
-        
+
+        // ── Artifact tracking (fire-and-forget) ─────────────────────
+        // After successful filesystem writes, persist artifact metadata
+        // on the agent object so the UI can display version history.
+        // Non-blocking: uses .catch() to avoid disrupting the tool pipeline.
+        if (result.status === 'completed' && command.toolId === TOOL_IDS.FILESYSTEM) {
+          this._trackArtifacts({ ...command, parameters: toolInput }, result, context)
+            .catch(e => this.logger?.warn?.('[Artifacts] tracking failed:', e.message));
+        }
+
         // Store in execution history
         const historyKey = `${context.agentId}-${Date.now()}`;
         this.executionHistory.set(historyKey, {
@@ -502,6 +511,105 @@ class MessageProcessor {
     return results;
   }
 
+  /**
+   * Track filesystem write/append operations as artifacts on the agent.
+   * Persists lightweight metadata (path, size, timestamp) and the content
+   * so the UI can show version history without re-parsing message content.
+   *
+   * The agent.artifacts map is persisted via the normal persistAgentState flow
+   * that already runs after tool execution in AgentScheduler.
+   *
+   * @param {Object} command - Tool command with parameters
+   * @param {Object} result - Execution result
+   * @param {Object} context - Execution context (agentId, projectDir)
+   * @private
+   */
+  async _trackArtifacts(command, result, context) {
+    try {
+      const agent = await this.agentPool?.getAgent?.(context.agentId);
+      if (!agent) {
+        console.log('[Artifacts] No agent found for', context.agentId);
+        return;
+      }
+
+      // Initialize artifacts map if needed: { [filePath]: { versions: [...] } }
+      if (!agent.artifacts) agent.artifacts = {};
+
+      const toolResult = result.result;
+      if (!toolResult?.success) {
+        console.log('[Artifacts] Tool result not successful:', { success: toolResult?.success, keys: Object.keys(toolResult || {}) });
+        return;
+      }
+
+      // Get the actions from the command parameters
+      // The AI may send actions at different levels depending on format:
+      //   { parameters: { actions: [...] } }  — parsed format
+      //   { actions: [...] }                   — top-level format (common)
+      //   { parameters: { type: 'write', ... } } — single action
+      const params = command.parameters || {};
+      const actions = params.actions || command.actions || (params.type ? [params] : []);
+      console.log('[Artifacts] Processing', actions.length, 'actions. Param keys:', Object.keys(params), 'cmd keys:', Object.keys(command));
+      const resultActions = toolResult.actions || [toolResult];
+
+      for (let i = 0; i < actions.length; i++) {
+        const action = actions[i];
+        const actionResult = resultActions[i] || {};
+        const type = action.type || action.action;
+
+        console.log(`[Artifacts] Action[${i}]:`, { type, filePath: action.filePath || action['file-path'], hasContent: !!action.content, contentLen: action.content?.length, actionKeys: Object.keys(action) });
+
+        if ((type === 'write' || type === 'append') && actionResult.success !== false) {
+          // AI uses various field names: filePath, file-path, outputPath, path
+          const rawPath = action.filePath || action['file-path'] || action.outputPath || action.path;
+          const content = action.content;
+          if (!rawPath || !content) {
+            console.log('[Artifacts] Skipped: missing filePath or content', { filePath: !!rawPath, content: !!content, actionKeys: Object.keys(action) });
+            continue;
+          }
+
+          // Use the resolved absolute path as key (prevents collisions for same-name files in different dirs)
+          // Fall back to raw path if fullPath not available
+          const absolutePath = actionResult.fullPath || rawPath;
+          const artifactKey = absolutePath.replace(/\\/g, '/');
+
+          // Relative display path (strip working directory prefix)
+          const wd = (context.projectDir || '').replace(/\\/g, '/');
+          const displayPath = wd && artifactKey.startsWith(wd + '/')
+            ? artifactKey.slice(wd.length + 1)
+            : artifactKey;
+
+          const version = {
+            id: `v-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`,
+            content,
+            timestamp: result.timestamp || new Date().toISOString(),
+            action: type,
+            size: Buffer.byteLength(content, 'utf8'),
+            fullPath: absolutePath,
+          };
+
+          if (!agent.artifacts[artifactKey]) {
+            agent.artifacts[artifactKey] = { displayPath, versions: [] };
+          }
+
+          // Deduplicate: skip if content identical to latest
+          const versions = agent.artifacts[artifactKey].versions;
+          const latest = versions[versions.length - 1];
+          if (latest && latest.content === content) continue;
+
+          versions.push(version);
+          console.log('[Artifacts] Tracked:', displayPath, 'v' + versions.length, '(' + version.size + ' bytes)');
+
+          // Cap at 50 versions per file to keep state reasonable
+          if (versions.length > 50) {
+            versions.splice(0, versions.length - 50);
+          }
+        }
+      }
+    } catch (e) {
+      this.logger?.warn?.('Artifact tracking failed (non-fatal):', e.message);
+    }
+  }
+
   /**
    * Execute async tool
    * @param {Object} command - Tool command

package/src/index.js

@@ -32,8 +32,6 @@ import { ToolsRegistry } from './tools/baseTool.js';
 import AgentDelayTool from './tools/agentDelayTool.js';
 import TerminalTool from './tools/terminalTool.js';
 import FileSystemTool from './tools/fileSystemTool.js';
-// BrowserTool is DEPRECATED - use WebTool instead
-// import BrowserTool from './tools/browserTool.js';
 import JobDoneTool from './tools/jobDoneTool.js';
 import AgentCommunicationTool from './tools/agentCommunicationTool.js';
 import TaskManagerTool from './tools/taskManagerTool.js';
@@ -486,11 +484,6 @@ class LoxiaApplication {
       this.logger.info('ToolsRegistry set for Help Tool');
     }
 
-    // NOTE: BrowserTool is DEPRECATED as of December 2024
-    // Use WebTool (toolId: "web") for all browser automation tasks
-    // The Browser tool registration has been removed - WebTool provides
-    // equivalent functionality with better architecture (singleton browser instance)
-    
     // Set AgentPool dependency for AgentDelayTool
     const agentDelayTool = this.toolsRegistry.getTool('agentdelay');
     if (agentDelayTool && typeof agentDelayTool.setAgentPool === 'function') {
@@ -611,8 +604,8 @@ class LoxiaApplication {
     if (interfaceConfig.web?.enabled !== false) {
       // Read port from environment variables (set by CLI) or use config defaults
       const webPort = parseInt(process.env.LOXIA_PORT || process.env.PORT, 10) || 8080;
-      // Use env var, then config, then 127.0.0.1 (avoid 'localhost' due to IPv6 issues)
-      const webHost = process.env.LOXIA_HOST || interfaceConfig.web?.host || '127.0.0.1';
+      // Use env var, then config, then 0.0.0.0 (accept connections from all interfaces)
+      const webHost = process.env.LOXIA_HOST || interfaceConfig.web?.host || '0.0.0.0';
 
       const webConfig = {
         ...interfaceConfig.web,
@@ -848,9 +841,9 @@ class LoxiaApplication {
         this.logger?.info('Models service retries cancelled');
       }
 
-      // Close Puppeteer browsers (webTool, browserTool) — they hold DevTools ports
+      // Close Puppeteer browser (webTool) — it holds DevTools ports
       if (this.toolsRegistry) {
-        for (const toolId of ['web', 'browser']) {
+        for (const toolId of ['web']) {
           try {
             const tool = this.toolsRegistry.getTool(toolId);
             if (tool?.cleanup) {
@@ -863,6 +856,29 @@ class LoxiaApplication {
         }
       }
 
+      // Kill ALL running terminal processes across all agents
+      if (this.toolsRegistry) {
+        try {
+          const terminalTool = this.toolsRegistry.getTool('terminal');
+          if (terminalTool?.commandTracker) {
+            let killed = 0;
+            for (const [cmdId, cmdInfo] of terminalTool.commandTracker) {
+              if (cmdInfo.process && cmdInfo.state === 'RUNNING') {
+                try {
+                  cmdInfo.process.kill('SIGTERM');
+                  killed++;
+                } catch { /* already dead */ }
+              }
+            }
+            if (killed > 0) {
+              this.logger?.info(`Killed ${killed} running terminal process(es) on shutdown`);
+            }
+          }
+        } catch (error) {
+          this.logger?.warn('Failed to cleanup terminal processes', { error: error.message });
+        }
+      }
+
       // Shutdown interfaces (web server, visual editor, WS connections)
       for (const [type, interface_] of this.interfaces) {
         try {

package/src/interfaces/__tests__/imageServing.test.js

@@ -0,0 +1,228 @@
+/**
+ * Unit tests for the /api/images/:sessionId/:filename endpoint.
+ *
+ * Covers:
+ *  - Path traversal rejection
+ *  - Serving images from project dir (with and without active session)
+ *  - Serving images from OS temp dir
+ *  - Serving images from agent working directories
+ *  - 404 when image doesn't exist anywhere
+ *  - Content-type correctness for different extensions
+ */
+
+import { describe, it, expect, beforeAll, afterAll, beforeEach } from '@jest/globals';
+import express from 'express';
+import { createServer } from 'http';
+import path from 'path';
+import fs from 'fs/promises';
+import os from 'os';
+
+// ── Minimal WebServer stand-in ──────────────────────────────────
+// We only mount the single route under test so the full webServer
+// dependency tree isn't required.
+
+const HTTP_STATUS = { BAD_REQUEST: 400, NOT_FOUND: 404, INTERNAL_SERVER_ERROR: 500, FORBIDDEN: 403 };
+
+function buildApp({ sessions, orchestrator, projectDir, logger }) {
+  const app = express();
+
+  // Replicate the exact route from webServer.js
+  app.get('/api/images/:sessionId/:filename', async (req, res) => {
+    try {
+      const { sessionId, filename } = req.params;
+
+      const normalizedFilename = path.basename(filename);
+      if (normalizedFilename !== filename || filename.includes('..') || filename.includes('/') || filename.includes('\\')) {
+        return res.status(HTTP_STATUS.BAD_REQUEST).json({ success: false, error: 'Invalid filename' });
+      }
+
+      const session = sessions.get(sessionId);
+      const effectiveProjectDir = session?.projectDir || projectDir || process.cwd();
+
+      let imagePath = null;
+      const searchPaths = [
+        path.join(effectiveProjectDir, 'images', normalizedFilename),
+        path.join('/tmp/loxia-images', sessionId, normalizedFilename),
+        path.join('/tmp/loxia-images', normalizedFilename),
+        path.join(process.env.TEMP || process.env.TMP || '/tmp', 'loxia-images', sessionId, normalizedFilename),
+        path.join(process.env.TEMP || process.env.TMP || '/tmp', 'loxia-images', normalizedFilename)
+      ];
+
+      if (orchestrator?.agentPool) {
+        try {
+          const agents = await orchestrator.agentPool.getAllAgents();
+          for (const agent of agents) {
+            if (agent.directoryAccess?.workingDirectory) {
+              searchPaths.push(path.join(agent.directoryAccess.workingDirectory, 'images', normalizedFilename));
+            }
+          }
+        } catch (_) { /* ignore */ }
+      }
+
+      for (const sp of searchPaths) {
+        try {
+          const stats = await fs.stat(sp);
+          if (stats.isFile()) { imagePath = sp; break; }
+        } catch (_) { continue; }
+      }
+
+      if (!imagePath) {
+        return res.status(HTTP_STATUS.NOT_FOUND).json({ success: false, error: 'Image not found' });
+      }
+
+      res.sendFile(imagePath, (err) => {
+        if (err && !res.headersSent) {
+          res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: 'Failed to serve image' });
+        }
+      });
+    } catch (error) {
+      if (!res.headersSent) {
+        res.status(HTTP_STATUS.INTERNAL_SERVER_ERROR).json({ success: false, error: error.message });
+      }
+    }
+  });
+
+  return app;
+}
+
+// ── Helpers ─────────────────────────────────────────────────────
+
+async function fetch(url) {
+  const resp = await globalThis.fetch(url);
+  const body = resp.headers.get('content-type')?.includes('json')
+    ? await resp.json()
+    : await resp.text();
+  return { status: resp.status, body, headers: resp.headers };
+}
+
+// ── Test suite ──────────────────────────────────────────────────
+
+describe('/api/images/:sessionId/:filename', () => {
+  let server, baseUrl;
+  let tmpProjectDir;
+  let tmpAgentDir;
+  const sessions = new Map();
+  const sessionId = 'test-session-abc123';
+
+  beforeAll(async () => {
+    // Create temp directories that simulate project and agent dirs
+    tmpProjectDir = path.join(os.tmpdir(), `loxia-img-test-proj-${Date.now()}`);
+    tmpAgentDir = path.join(os.tmpdir(), `loxia-img-test-agent-${Date.now()}`);
+    await fs.mkdir(path.join(tmpProjectDir, 'images'), { recursive: true });
+    await fs.mkdir(path.join(tmpAgentDir, 'images'), { recursive: true });
+
+    // Also create the OS temp search path
+    const osTempPath = path.join(process.env.TEMP || process.env.TMP || '/tmp', 'loxia-images', sessionId);
+    await fs.mkdir(osTempPath, { recursive: true });
+
+    // Write test images
+    const pngHeader = Buffer.from([0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]); // PNG magic bytes
+    await fs.writeFile(path.join(tmpProjectDir, 'images', 'project-image.png'), pngHeader);
+    await fs.writeFile(path.join(tmpAgentDir, 'images', 'agent-image.png'), pngHeader);
+    await fs.writeFile(path.join(osTempPath, 'temp-image.png'), pngHeader);
+
+    // Register session
+    sessions.set(sessionId, { projectDir: tmpProjectDir });
+
+    const orchestrator = {
+      agentPool: {
+        getAllAgents: async () => [
+          { directoryAccess: { workingDirectory: tmpAgentDir } }
+        ]
+      }
+    };
+
+    const app = buildApp({
+      sessions,
+      orchestrator,
+      projectDir: tmpProjectDir,
+      logger: { info() {}, warn() {}, error() {}, debug() {} }
+    });
+
+    server = createServer(app);
+    await new Promise(resolve => server.listen(0, resolve));
+    const port = server.address().port;
+    baseUrl = `http://localhost:${port}`;
+  });
+
+  afterAll(async () => {
+    server?.close();
+    await fs.rm(tmpProjectDir, { recursive: true, force: true }).catch(() => {});
+    await fs.rm(tmpAgentDir, { recursive: true, force: true }).catch(() => {});
+    const osTempPath = path.join(process.env.TEMP || process.env.TMP || '/tmp', 'loxia-images', sessionId);
+    await fs.rm(osTempPath, { recursive: true, force: true }).catch(() => {});
+  });
+
+  // ── Security ──────────────────────────────────────────────
+
+  it('rejects path traversal with ..', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/images/${sessionId}/..%2F..%2Fetc%2Fpasswd`);
+    expect(status).toBe(400);
+    expect(body.error).toBe('Invalid filename');
+  });
+
+  it('rejects filenames with slashes', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/images/${sessionId}/sub%2Ffile.png`);
+    expect(status).toBe(400);
+    expect(body.error).toBe('Invalid filename');
+  });
+
+  it('rejects filenames with backslashes', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/images/${sessionId}/sub%5Cfile.png`);
+    expect(status).toBe(400);
+    expect(body.error).toBe('Invalid filename');
+  });
+
+  // ── Serving from project directory (session active) ───────
+
+  it('serves image from project/images/ when session is active', async () => {
+    const { status, headers } = await fetch(`${baseUrl}/api/images/${sessionId}/project-image.png`);
+    expect(status).toBe(200);
+    expect(headers.get('content-type')).toMatch(/image|octet/);
+  });
+
+  // ── Serving without active session (session expired) ──────
+
+  it('still serves image when session has expired (falls back to cwd)', async () => {
+    // Use a sessionId that doesn't exist in the map
+    // Image is in the OS temp dir under the expired sessionId
+    const expiredSessionId = sessionId; // temp image was created under this id
+    // Remove session temporarily
+    sessions.delete(sessionId);
+
+    // The image is in OS temp: $TEMP/loxia-images/test-session-abc123/temp-image.png
+    const { status } = await fetch(`${baseUrl}/api/images/${expiredSessionId}/temp-image.png`);
+    expect(status).toBe(200);
+
+    // Restore session for other tests
+    sessions.set(sessionId, { projectDir: tmpProjectDir });
+  });
+
+  // ── Serving from agent working directory ──────────────────
+
+  it('finds image in agent working directory', async () => {
+    const { status } = await fetch(`${baseUrl}/api/images/${sessionId}/agent-image.png`);
+    expect(status).toBe(200);
+  });
+
+  // ── Serving from OS temp directory ────────────────────────
+
+  it('finds image in OS temp loxia-images directory', async () => {
+    const { status } = await fetch(`${baseUrl}/api/images/${sessionId}/temp-image.png`);
+    expect(status).toBe(200);
+  });
+
+  // ── 404 for missing images ────────────────────────────────
+
+  it('returns 404 for non-existent image', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/images/${sessionId}/does-not-exist.png`);
+    expect(status).toBe(404);
+    expect(body.error).toBe('Image not found');
+  });
+
+  it('returns 404 for unknown session + missing file', async () => {
+    const { status, body } = await fetch(`${baseUrl}/api/images/unknown-session-xyz/nope.png`);
+    expect(status).toBe(404);
+    expect(body.error).toBe('Image not found');
+  });
+});