opencode-pilot 0.18.3 → 0.19.0

package/README.md

@@ -74,6 +74,23 @@ Session names for `my-prs-attention` indicate the condition: "Conflicts: {title}
 
 Create prompt templates as markdown files in `~/.config/opencode/pilot/templates/`. Templates support placeholders like `{title}`, `{body}`, `{number}`, `{html_url}`, etc.
 
+### Session and Sandbox Reuse
+
+By default, pilot reuses existing sessions and sandboxes to avoid duplicates:
+
+- **Session reuse**: If a non-archived session already exists for the target directory, pilot appends to it instead of creating a new session. Archived sessions are never reused.
+- **Sandbox reuse**: When `worktree: "new"` with a `worktree_name`, pilot first checks if a sandbox with that name already exists and reuses it.
+
+```yaml
+defaults:
+  # Disable session reuse (always create new sessions)
+  reuse_active_session: false
+  # Disable sandbox reuse (always create new worktrees)
+  prefer_existing_sandbox: false
+```
+
+When multiple sessions exist for the same directory, pilot prefers idle sessions over busy ones, then selects the most recently updated.
+
 ### Worktree Support
 
 Run sessions in isolated git worktrees instead of the main project directory. This uses OpenCode's built-in worktree management API to create and manage worktrees.
@@ -81,7 +98,7 @@ Run sessions in isolated git worktrees instead of the main project directory. Th
 ```yaml
 sources:
   - preset: github/my-issues
-    # Create a fresh worktree for each session
+    # Create a fresh worktree for each session (or reuse if name matches)
     worktree: "new"
     worktree_name: "issue-{number}"  # Optional: name template
     
@@ -91,9 +108,10 @@ sources:
 ```
 
 **Options:**
-- `worktree: "new"` - Create a new worktree via OpenCode's API
+- `worktree: "new"` - Create a new worktree via OpenCode's API (or reuse existing if name matches)
 - `worktree: "name"` - Look up existing worktree by name from project sandboxes
 - `worktree_name` - Template for naming new worktrees (only with `worktree: "new"`)
+- `prefer_existing_sandbox: false` - Disable sandbox reuse for this source
 
 ## CLI Commands
 

package/examples/config.yaml

@@ -1,5 +1,5 @@
 # Example config.yaml for opencode-pilot
-# Copy to ~/.config/opencode-pilot/config.yaml
+# Copy to ~/.config/opencode/pilot/config.yaml
 
 # Preferred OpenCode server port for attaching sessions
 # When multiple OpenCode instances are running, pilot will attach new sessions
@@ -19,6 +19,12 @@ repos_dir: ~/code
 defaults:
   agent: plan
   prompt: default
+  # Session reuse: append to existing non-archived session instead of creating new
+  # Default: true. Set to false to always create new sessions.
+  # reuse_active_session: true
+  # Sandbox reuse: reuse existing worktree/sandbox with matching name
+  # Default: true. Set to false to always create new sandboxes.
+  # prefer_existing_sandbox: true
 
 sources:
   # Presets - common patterns with sensible defaults

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-pilot",
-  "version": "0.18.3",
+  "version": "0.19.0",
   "type": "module",
   "main": "plugin/index.js",
   "description": "Automation daemon for OpenCode - polls for work and spawns sessions",
@@ -25,7 +25,9 @@
     "opencode-pilot": "./bin/opencode-pilot"
   },
   "scripts": {
-    "test": "node --test test/unit/*.test.js"
+    "test": "node --test test/unit/*.test.js",
+    "test:integration": "node --test test/integration/*.test.js",
+    "test:all": "node --test test/unit/*.test.js test/integration/*.test.js"
   },
   "devDependencies": {
     "@semantic-release/git": "^10.0.1",

package/service/actions.js

@@ -306,6 +306,258 @@ export function buildCommand(item, config) {
   return `[API] POST /session?directory=${cwd} (title: "${sessionName}")`;
 }
 
+/**
+ * List sessions from the OpenCode server
+ * 
+ * @param {string} serverUrl - Server URL (e.g., "http://localhost:4096")
+ * @param {object} [options] - Options
+ * @param {string} [options.directory] - Filter by directory
+ * @param {function} [options.fetch] - Custom fetch function (for testing)
+ * @returns {Promise<Array>} Array of session objects
+ */
+export async function listSessions(serverUrl, options = {}) {
+  const fetchFn = options.fetch || fetch;
+  
+  try {
+    const url = new URL('/session', serverUrl);
+    if (options.directory) {
+      url.searchParams.set('directory', options.directory);
+    }
+    // Only get root sessions (not child/forked sessions)
+    url.searchParams.set('roots', 'true');
+    
+    const response = await fetchFn(url.toString());
+    
+    if (!response.ok) {
+      debug(`listSessions: ${serverUrl} returned ${response.status}`);
+      return [];
+    }
+    
+    const sessions = await response.json();
+    return Array.isArray(sessions) ? sessions : [];
+  } catch (err) {
+    debug(`listSessions: error - ${err.message}`);
+    return [];
+  }
+}
+
+/**
+ * Check if a session is archived
+ * A session is archived if time.archived is set (it's a timestamp)
+ * 
+ * @param {object} session - Session object from API
+ * @returns {boolean} True if session is archived
+ */
+export function isSessionArchived(session) {
+  return session?.time?.archived !== undefined;
+}
+
+/**
+ * Get session statuses from the OpenCode server
+ * Returns a map of sessionId -> status (idle, busy, retry)
+ * Sessions not in the map are considered idle
+ * 
+ * @param {string} serverUrl - Server URL
+ * @param {object} [options] - Options
+ * @param {function} [options.fetch] - Custom fetch function (for testing)
+ * @returns {Promise<object>} Map of sessionId -> status object
+ */
+export async function getSessionStatuses(serverUrl, options = {}) {
+  const fetchFn = options.fetch || fetch;
+  
+  try {
+    const response = await fetchFn(`${serverUrl}/session/status`);
+    
+    if (!response.ok) {
+      debug(`getSessionStatuses: ${serverUrl} returned ${response.status}`);
+      return {};
+    }
+    
+    return await response.json();
+  } catch (err) {
+    debug(`getSessionStatuses: error - ${err.message}`);
+    return {};
+  }
+}
+
+/**
+ * Find the best session to reuse from a list of candidates
+ * Prefers idle sessions, then most recently updated
+ * 
+ * @param {Array} sessions - Array of non-archived sessions
+ * @param {object} statuses - Map of sessionId -> status from /session/status
+ * @returns {object|null} Best session to reuse, or null if none
+ */
+export function selectBestSession(sessions, statuses) {
+  if (!sessions || sessions.length === 0) {
+    return null;
+  }
+  
+  // Separate idle vs busy/retry sessions
+  const idle = [];
+  const other = [];
+  
+  for (const session of sessions) {
+    const status = statuses[session.id];
+    // Sessions not in statuses map are idle (per OpenCode behavior)
+    if (!status || status.type === 'idle') {
+      idle.push(session);
+    } else {
+      other.push(session);
+    }
+  }
+  
+  // Sort by most recently updated (highest time.updated first)
+  const sortByUpdated = (a, b) => (b.time?.updated || 0) - (a.time?.updated || 0);
+  
+  // Prefer idle sessions
+  if (idle.length > 0) {
+    idle.sort(sortByUpdated);
+    return idle[0];
+  }
+  
+  // Fall back to busy/retry sessions (sorted by most recent)
+  if (other.length > 0) {
+    other.sort(sortByUpdated);
+    return other[0];
+  }
+  
+  return null;
+}
+
+/**
+ * Send a message to an existing session
+ * 
+ * @param {string} serverUrl - Server URL
+ * @param {string} sessionId - Session ID to send message to
+ * @param {string} directory - Working directory
+ * @param {string} prompt - The prompt/message to send
+ * @param {object} [options] - Options
+ * @param {string} [options.title] - Update session title (optional)
+ * @param {string} [options.agent] - Agent to use
+ * @param {string} [options.model] - Model to use
+ * @param {function} [options.fetch] - Custom fetch function (for testing)
+ * @returns {Promise<object>} Result with sessionId, success, error
+ */
+export async function sendMessageToSession(serverUrl, sessionId, directory, prompt, options = {}) {
+  const fetchFn = options.fetch || fetch;
+  
+  try {
+    // Step 1: Update session title if provided
+    if (options.title) {
+      const updateUrl = new URL(`/session/${sessionId}`, serverUrl);
+      updateUrl.searchParams.set('directory', directory);
+      await fetchFn(updateUrl.toString(), {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ title: options.title }),
+      });
+      debug(`sendMessageToSession: updated title for session ${sessionId}`);
+    }
+    
+    // Step 2: Send the message
+    const messageUrl = new URL(`/session/${sessionId}/message`, serverUrl);
+    messageUrl.searchParams.set('directory', directory);
+    
+    const messageBody = {
+      parts: [{ type: 'text', text: prompt }],
+    };
+    
+    if (options.agent) {
+      messageBody.agent = options.agent;
+    }
+    
+    if (options.model) {
+      const [providerID, modelID] = options.model.includes('/') 
+        ? options.model.split('/', 2) 
+        : ['anthropic', options.model];
+      messageBody.providerID = providerID;
+      messageBody.modelID = modelID;
+    }
+    
+    // Use AbortController with timeout (same pattern as createSessionViaApi)
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 10000);
+    
+    try {
+      const messageResponse = await fetchFn(messageUrl.toString(), {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(messageBody),
+        signal: controller.signal,
+      });
+      
+      clearTimeout(timeoutId);
+      
+      if (!messageResponse.ok) {
+        const errorText = await messageResponse.text();
+        throw new Error(`Failed to send message: ${messageResponse.status} ${errorText}`);
+      }
+      
+      debug(`sendMessageToSession: sent message to session ${sessionId}`);
+    } catch (abortErr) {
+      clearTimeout(timeoutId);
+      if (abortErr.name === 'AbortError') {
+        debug(`sendMessageToSession: message request started for session ${sessionId} (response aborted as expected)`);
+      } else {
+        throw abortErr;
+      }
+    }
+    
+    return {
+      success: true,
+      sessionId,
+      directory,
+      reused: true,
+    };
+  } catch (err) {
+    debug(`sendMessageToSession: error - ${err.message}`);
+    return {
+      success: false,
+      error: err.message,
+    };
+  }
+}
+
+/**
+ * Find an existing session to reuse for the given directory
+ * Returns null if no suitable session found (archived sessions are excluded)
+ * 
+ * @param {string} serverUrl - Server URL
+ * @param {string} directory - Working directory to match
+ * @param {object} [options] - Options
+ * @param {function} [options.fetch] - Custom fetch function (for testing)
+ * @returns {Promise<object|null>} Session to reuse, or null
+ */
+export async function findReusableSession(serverUrl, directory, options = {}) {
+  // Get sessions for this directory
+  const sessions = await listSessions(serverUrl, { 
+    directory, 
+    fetch: options.fetch 
+  });
+  
+  if (sessions.length === 0) {
+    debug(`findReusableSession: no sessions found for ${directory}`);
+    return null;
+  }
+  
+  // Filter out archived sessions
+  const activeSessions = sessions.filter(s => !isSessionArchived(s));
+  
+  if (activeSessions.length === 0) {
+    debug(`findReusableSession: all ${sessions.length} sessions are archived for ${directory}`);
+    return null;
+  }
+  
+  debug(`findReusableSession: found ${activeSessions.length} active sessions for ${directory}`);
+  
+  // Get statuses to prefer idle sessions
+  const statuses = await getSessionStatuses(serverUrl, { fetch: options.fetch });
+  
+  // Select the best session
+  return selectBestSession(activeSessions, statuses);
+}
+
 /**
  * Create a session via the OpenCode HTTP API
  * 
@@ -500,6 +752,8 @@ export async function executeAction(item, config, options = {}) {
     worktree: worktreeMode,
     // Expand worktree_name template with item fields (e.g., "issue-{number}")
     worktreeName: config.worktree_name ? expandTemplate(config.worktree_name, item) : undefined,
+    // Config flag to control sandbox reuse (default true)
+    preferExistingSandbox: config.prefer_existing_sandbox,
   };
   
   const worktreeResult = await resolveWorktreeDirectory(
@@ -513,6 +767,8 @@ export async function executeAction(item, config, options = {}) {
   
   if (worktreeResult.worktreeCreated) {
     debug(`executeAction: created new worktree at ${cwd}`);
+  } else if (worktreeResult.worktreeReused) {
+    debug(`executeAction: reusing existing sandbox at ${cwd}`);
   } else if (worktreeResult.error) {
     debug(`executeAction: worktree resolution warning - ${worktreeResult.error}`);
   }
@@ -527,6 +783,34 @@ export async function executeAction(item, config, options = {}) {
     ? buildSessionName(config.session.name, item)
     : (item.title || `session-${Date.now()}`);
   
+  // Check if we should try to reuse an existing session
+  const reuseActiveSession = config.reuse_active_session !== false; // default true
+  
+  if (reuseActiveSession && !options.dryRun) {
+    const existingSession = await findReusableSession(serverUrl, cwd, { fetch: options.fetch });
+    
+    if (existingSession) {
+      debug(`executeAction: found reusable session ${existingSession.id} for ${cwd}`);
+      
+      const reuseCommand = `[API] POST ${serverUrl}/session/${existingSession.id}/message (reusing session)`;
+      
+      const result = await sendMessageToSession(serverUrl, existingSession.id, cwd, prompt, {
+        title: sessionTitle,
+        agent: config.agent,
+        model: config.model,
+        fetch: options.fetch,
+      });
+      
+      return {
+        command: reuseCommand,
+        success: result.success,
+        sessionId: result.sessionId,
+        sessionReused: true,
+        error: result.error,
+      };
+    }
+  }
+  
   const apiCommand = `[API] POST ${serverUrl}/session?directory=${cwd}`;
   debug(`executeAction: using HTTP API - ${apiCommand}`);
   

package/service/worktree.js

@@ -8,18 +8,26 @@
 import { debug } from "./logger.js";
 
 /**
- * List available worktrees/sandboxes for a project
+ * List existing worktrees from the OpenCode server
  * 
  * @param {string} serverUrl - OpenCode server URL (e.g., "http://localhost:4096")
  * @param {object} [options] - Options
+ * @param {string} [options.directory] - Project directory (required for global server)
  * @param {function} [options.fetch] - Custom fetch function (for testing)
- * @returns {Promise<string[]>} Array of worktree directory paths
+ * @returns {Promise<string[]>} Array of worktree paths
  */
 export async function listWorktrees(serverUrl, options = {}) {
   const fetchFn = options.fetch || fetch;
   
   try {
-    const response = await fetchFn(`${serverUrl}/experimental/worktree`);
+    // Build URL with directory parameter if provided
+    // This tells the global server which project to list worktrees for
+    let url = `${serverUrl}/experimental/worktree`;
+    if (options.directory) {
+      url += `?directory=${encodeURIComponent(options.directory)}`;
+    }
+    
+    const response = await fetchFn(url);
     
     if (!response.ok) {
       debug(`listWorktrees: ${serverUrl} returned ${response.status}`);
@@ -162,6 +170,25 @@ export async function getProjectInfoForDirectory(serverUrl, directory, options =
   }
 }
 
+/**
+ * Find an existing worktree by exact name match
+ * 
+ * @param {string[]} worktrees - List of worktree paths
+ * @param {string} name - Name to match (final path component)
+ * @returns {string|null} Matching worktree path or null
+ */
+function findWorktreeByName(worktrees, name) {
+  for (const wt of worktrees) {
+    // Match exact final path component
+    const parts = wt.split('/');
+    const finalComponent = parts[parts.length - 1];
+    if (finalComponent === name) {
+      return wt;
+    }
+  }
+  return null;
+}
+
 /**
  * Resolve the working directory based on worktree configuration
  * 
@@ -174,9 +201,10 @@ export async function getProjectInfoForDirectory(serverUrl, directory, options =
  * @param {object} worktreeConfig - Worktree configuration
  * @param {string} [worktreeConfig.worktree] - Worktree mode: "new" or worktree name
  * @param {string} [worktreeConfig.worktreeName] - Name for new worktree (only with "new")
+ * @param {boolean} [worktreeConfig.preferExistingSandbox] - If true (default), reuse existing sandbox with matching name
  * @param {object} [options] - Options
  * @param {function} [options.fetch] - Custom fetch function (for testing)
- * @returns {Promise<object>} Result with { directory, worktreeCreated?, error? }
+ * @returns {Promise<object>} Result with { directory, worktreeCreated?, worktreeReused?, error? }
  */
 export async function resolveWorktreeDirectory(serverUrl, baseDir, worktreeConfig, options = {}) {
   // No worktree config - use base directory
@@ -193,9 +221,25 @@ export async function resolveWorktreeDirectory(serverUrl, baseDir, worktreeConfi
   }
   
   const worktreeValue = worktreeConfig.worktree;
+  const preferExisting = worktreeConfig.preferExistingSandbox !== false; // default true
   
-  // "new" - create a fresh worktree via OpenCode API
+  // "new" - create a fresh worktree via OpenCode API (or reuse if matching name exists)
   if (worktreeValue === "new") {
+    // If worktreeName is provided and preferExisting is true, try to reuse existing
+    if (worktreeConfig.worktreeName && preferExisting) {
+      const worktrees = await listWorktrees(serverUrl, { ...options, directory: baseDir });
+      const existingMatch = findWorktreeByName(worktrees, worktreeConfig.worktreeName);
+      
+      if (existingMatch) {
+        debug(`resolveWorktreeDirectory: reusing existing sandbox "${worktreeConfig.worktreeName}" at ${existingMatch}`);
+        return {
+          directory: existingMatch,
+          worktreeReused: true,
+        };
+      }
+    }
+    
+    // No existing match found (or not looking), create new
     const result = await createWorktree(serverUrl, {
       directory: baseDir,
       name: worktreeConfig.worktreeName,
@@ -217,7 +261,7 @@ export async function resolveWorktreeDirectory(serverUrl, baseDir, worktreeConfi
   }
   
   // Named worktree - look it up from available sandboxes via OpenCode API
-  const worktrees = await listWorktrees(serverUrl, options);
+  const worktrees = await listWorktrees(serverUrl, { ...options, directory: baseDir });
   const match = worktrees.find(w => w.includes(worktreeValue));
   if (match) {
     return { directory: match };

package/test/integration/session-reuse.test.js

@@ -0,0 +1,347 @@
+/**
+ * Integration tests for session and sandbox reuse
+ * 
+ * These tests verify the actual API interactions work correctly.
+ * They use a mock server that simulates OpenCode's behavior.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { createServer } from "node:http";
+
+import {
+  listSessions,
+  findReusableSession,
+  isSessionArchived,
+  sendMessageToSession,
+  executeAction,
+} from "../../service/actions.js";
+
+import {
+  listWorktrees,
+  resolveWorktreeDirectory,
+} from "../../service/worktree.js";
+
+/**
+ * Create a mock OpenCode server for testing
+ */
+function createMockServer(handlers = {}) {
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const path = url.pathname;
+    const method = req.method;
+    const directory = url.searchParams.get("directory");
+
+    // Collect request body
+    let body = "";
+    req.on("data", (chunk) => (body += chunk));
+    req.on("end", () => {
+      const request = {
+        method,
+        path,
+        directory,
+        query: Object.fromEntries(url.searchParams),
+        body: body ? JSON.parse(body) : null,
+      };
+
+      // Find matching handler
+      const handlerKey = `${method} ${path}`;
+      const handler = handlers[handlerKey] || handlers.default;
+
+      if (handler) {
+        const result = handler(request);
+        res.writeHead(result.status || 200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify(result.body));
+      } else {
+        res.writeHead(404, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "Not found" }));
+      }
+    });
+  });
+
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const { port } = server.address();
+      resolve({
+        url: `http://127.0.0.1:${port}`,
+        server,
+        close: () => new Promise((r) => server.close(r)),
+      });
+    });
+  });
+}
+
+describe("integration: session reuse", () => {
+  let mockServer;
+
+  afterEach(async () => {
+    if (mockServer) {
+      await mockServer.close();
+      mockServer = null;
+    }
+  });
+
+  it("listSessions passes directory parameter to server", async () => {
+    let receivedDirectory = null;
+
+    mockServer = await createMockServer({
+      "GET /session": (req) => {
+        receivedDirectory = req.directory;
+        return {
+          body: [
+            { id: "ses_1", directory: "/path/to/project", time: { created: 1000, updated: 2000 } },
+          ],
+        };
+      },
+    });
+
+    const sessions = await listSessions(mockServer.url, { directory: "/path/to/project" });
+
+    assert.strictEqual(sessions.length, 1);
+    assert.strictEqual(receivedDirectory, "/path/to/project", "Server should receive directory parameter");
+  });
+
+  it("findReusableSession filters out archived sessions", async () => {
+    mockServer = await createMockServer({
+      "GET /session": () => ({
+        body: [
+          { id: "ses_archived", directory: "/proj", time: { created: 1000, updated: 3000, archived: 4000 } },
+          { id: "ses_active", directory: "/proj", time: { created: 2000, updated: 2500 } },
+        ],
+      }),
+      "GET /session/status": () => ({ body: {} }),
+    });
+
+    const session = await findReusableSession(mockServer.url, "/proj");
+
+    assert.ok(session, "Should find a session");
+    assert.strictEqual(session.id, "ses_active", "Should return the active session, not archived");
+  });
+
+  it("findReusableSession prefers idle sessions over busy", async () => {
+    mockServer = await createMockServer({
+      "GET /session": () => ({
+        body: [
+          { id: "ses_busy", directory: "/proj", time: { created: 1000, updated: 3000 } },
+          { id: "ses_idle", directory: "/proj", time: { created: 2000, updated: 2000 } },
+        ],
+      }),
+      "GET /session/status": () => ({
+        body: { ses_busy: { type: "busy" } },
+      }),
+    });
+
+    const session = await findReusableSession(mockServer.url, "/proj");
+
+    assert.strictEqual(session.id, "ses_idle", "Should prefer idle session even with older update time");
+  });
+
+  it("sendMessageToSession updates title and posts message", async () => {
+    let titleUpdated = false;
+    let messagePosted = false;
+    let postedBody = null;
+
+    mockServer = await createMockServer({
+      "PATCH /session/ses_123": (req) => {
+        titleUpdated = req.body?.title === "New Title";
+        return { body: {} };
+      },
+      "POST /session/ses_123/message": (req) => {
+        messagePosted = true;
+        postedBody = req.body;
+        return { body: { success: true } };
+      },
+    });
+
+    const result = await sendMessageToSession(
+      mockServer.url,
+      "ses_123",
+      "/proj",
+      "Hello world",
+      { title: "New Title", agent: "plan" }
+    );
+
+    assert.ok(result.success);
+    assert.strictEqual(result.reused, true);
+    assert.ok(titleUpdated, "Should update session title");
+    assert.ok(messagePosted, "Should post message");
+    assert.strictEqual(postedBody.parts[0].text, "Hello world");
+    assert.strictEqual(postedBody.agent, "plan");
+  });
+
+  it("executeAction reuses existing session when available", async () => {
+    let sessionCreated = false;
+    let messageSessionId = null;
+
+    mockServer = await createMockServer({
+      "GET /session": () => ({
+        body: [{ id: "ses_existing", directory: "/proj", time: { created: 1000, updated: 2000 } }],
+      }),
+      "GET /session/status": () => ({ body: {} }),
+      "POST /session": () => {
+        sessionCreated = true;
+        return { body: { id: "ses_new" } };
+      },
+      "PATCH /session/ses_existing": () => ({ body: {} }),
+      "POST /session/ses_existing/message": (req) => {
+        messageSessionId = "ses_existing";
+        return { body: { success: true } };
+      },
+      "GET /project/current": () => ({
+        body: { id: "proj_1", worktree: "/proj", time: { created: 1000, updated: 2000 }, sandboxes: [] },
+      }),
+    });
+
+    const result = await executeAction(
+      { number: 123, title: "Test issue" },
+      { path: "/proj", prompt: "default" },
+      { discoverServer: async () => mockServer.url }
+    );
+
+    assert.ok(result.success);
+    assert.strictEqual(result.sessionReused, true, "Should indicate session was reused");
+    assert.strictEqual(sessionCreated, false, "Should NOT create new session");
+    assert.strictEqual(messageSessionId, "ses_existing", "Should post to existing session");
+  });
+
+  it("executeAction creates new session when all existing are archived", async () => {
+    let sessionCreated = false;
+
+    mockServer = await createMockServer({
+      "GET /session": () => ({
+        body: [{ id: "ses_archived", directory: "/proj", time: { created: 1000, archived: 2000 } }],
+      }),
+      "GET /session/status": () => ({ body: {} }),
+      "POST /session": () => {
+        sessionCreated = true;
+        return { body: { id: "ses_new" } };
+      },
+      "PATCH /session/ses_new": () => ({ body: {} }),
+      "POST /session/ses_new/message": () => ({ body: { success: true } }),
+      "GET /project/current": () => ({
+        body: { id: "proj_1", worktree: "/proj", time: { created: 1000, updated: 2000 }, sandboxes: [] },
+      }),
+    });
+
+    const result = await executeAction(
+      { number: 456, title: "Test" },
+      { path: "/proj", prompt: "default" },
+      { discoverServer: async () => mockServer.url }
+    );
+
+    assert.ok(result.success);
+    assert.strictEqual(result.sessionReused, undefined, "Should NOT indicate session was reused");
+    assert.ok(sessionCreated, "Should create new session when existing is archived");
+  });
+});
+
+describe("integration: sandbox reuse", () => {
+  let mockServer;
+
+  afterEach(async () => {
+    if (mockServer) {
+      await mockServer.close();
+      mockServer = null;
+    }
+  });
+
+  it("listWorktrees passes directory parameter to server", async () => {
+    let receivedDirectory = null;
+
+    mockServer = await createMockServer({
+      "GET /experimental/worktree": (req) => {
+        receivedDirectory = req.directory;
+        return { body: ["/worktree/branch-1"] };
+      },
+    });
+
+    const worktrees = await listWorktrees(mockServer.url, { directory: "/path/to/project" });
+
+    assert.strictEqual(worktrees.length, 1);
+    assert.strictEqual(receivedDirectory, "/path/to/project", "Server should receive directory parameter");
+  });
+
+  it("resolveWorktreeDirectory reuses existing sandbox when name matches", async () => {
+    let postCalled = false;
+    let listDirectory = null;
+
+    mockServer = await createMockServer({
+      "GET /experimental/worktree": (req) => {
+        listDirectory = req.directory;
+        return {
+          body: [
+            "/worktree/other-branch",
+            "/worktree/my-feature",
+          ],
+        };
+      },
+      "POST /experimental/worktree": () => {
+        postCalled = true;
+        return { body: { name: "my-feature", directory: "/worktree/my-feature-new" } };
+      },
+    });
+
+    const result = await resolveWorktreeDirectory(
+      mockServer.url,
+      "/path/to/project",
+      { worktree: "new", worktreeName: "my-feature" }
+    );
+
+    assert.strictEqual(result.directory, "/worktree/my-feature");
+    assert.strictEqual(result.worktreeReused, true);
+    assert.strictEqual(postCalled, false, "Should NOT create new worktree");
+    assert.strictEqual(listDirectory, "/path/to/project", "Should pass directory to list worktrees");
+  });
+
+  it("resolveWorktreeDirectory creates new sandbox when name doesn't match", async () => {
+    let postCalled = false;
+    let postDirectory = null;
+
+    mockServer = await createMockServer({
+      "GET /experimental/worktree": () => ({
+        body: ["/worktree/other-branch"],
+      }),
+      "POST /experimental/worktree": (req) => {
+        postCalled = true;
+        postDirectory = req.directory;
+        return {
+          body: {
+            name: "new-feature",
+            branch: "opencode/new-feature",
+            directory: "/worktree/new-feature",
+          },
+        };
+      },
+    });
+
+    const result = await resolveWorktreeDirectory(
+      mockServer.url,
+      "/path/to/project",
+      { worktree: "new", worktreeName: "new-feature" }
+    );
+
+    assert.strictEqual(result.directory, "/worktree/new-feature");
+    assert.strictEqual(result.worktreeCreated, true);
+    assert.ok(postCalled, "Should create new worktree");
+    assert.strictEqual(postDirectory, "/path/to/project", "Should pass directory to create worktree");
+  });
+
+  it("resolveWorktreeDirectory passes directory when looking up named worktree", async () => {
+    let listDirectory = null;
+
+    mockServer = await createMockServer({
+      "GET /experimental/worktree": (req) => {
+        listDirectory = req.directory;
+        return { body: ["/worktree/my-branch"] };
+      },
+    });
+
+    const result = await resolveWorktreeDirectory(
+      mockServer.url,
+      "/path/to/project",
+      { worktree: "my-branch" }
+    );
+
+    assert.strictEqual(result.directory, "/worktree/my-branch");
+    assert.strictEqual(listDirectory, "/path/to/project", "Should pass directory when looking up named worktree");
+  });
+});

package/test/unit/actions.test.js

@@ -567,9 +567,9 @@ describe('actions.js', () => {
       // Mock server discovery
       const mockDiscoverServer = async () => 'http://localhost:4096';
       
-      // Mock worktree list lookup
+      // Mock worktree list lookup - now includes directory param
       const mockFetch = async (url) => {
-        if (url === 'http://localhost:4096/experimental/worktree') {
+        if (url.includes('/experimental/worktree')) {
           return {
             ok: true,
             json: async () => [
@@ -904,4 +904,297 @@ describe('actions.js', () => {
       assert.ok(result.warning.includes('Failed to send message'), 'Warning should mention message failure');
     });
   });
+
+  describe('session reuse', () => {
+    test('isSessionArchived returns true when time.archived is set', async () => {
+      const { isSessionArchived } = await import('../../service/actions.js');
+      
+      // Archived session (time.archived is a timestamp)
+      const archivedSession = { id: 'ses_1', time: { created: 1000, updated: 2000, archived: 3000 } };
+      assert.strictEqual(isSessionArchived(archivedSession), true);
+      
+      // Active session (no time.archived)
+      const activeSession = { id: 'ses_2', time: { created: 1000, updated: 2000 } };
+      assert.strictEqual(isSessionArchived(activeSession), false);
+      
+      // Handle edge cases
+      assert.strictEqual(isSessionArchived(null), false);
+      assert.strictEqual(isSessionArchived({}), false);
+      assert.strictEqual(isSessionArchived({ time: {} }), false);
+    });
+
+    test('selectBestSession prefers idle sessions', async () => {
+      const { selectBestSession } = await import('../../service/actions.js');
+      
+      const sessions = [
+        { id: 'ses_busy', time: { updated: 3000 } },
+        { id: 'ses_idle', time: { updated: 2000 } },
+        { id: 'ses_retry', time: { updated: 1000 } },
+      ];
+      
+      const statuses = {
+        'ses_busy': { type: 'busy' },
+        'ses_retry': { type: 'retry', attempt: 1, message: 'error', next: 5000 },
+        // ses_idle not in statuses = idle
+      };
+      
+      const best = selectBestSession(sessions, statuses);
+      assert.strictEqual(best.id, 'ses_idle', 'Should prefer idle session even with older updated time');
+    });
+
+    test('selectBestSession falls back to most recently updated when all busy', async () => {
+      const { selectBestSession } = await import('../../service/actions.js');
+      
+      const sessions = [
+        { id: 'ses_1', time: { updated: 1000 } },
+        { id: 'ses_2', time: { updated: 3000 } },  // most recent
+        { id: 'ses_3', time: { updated: 2000 } },
+      ];
+      
+      const statuses = {
+        'ses_1': { type: 'busy' },
+        'ses_2': { type: 'busy' },
+        'ses_3': { type: 'busy' },
+      };
+      
+      const best = selectBestSession(sessions, statuses);
+      assert.strictEqual(best.id, 'ses_2', 'Should select most recently updated when all busy');
+    });
+
+    test('selectBestSession returns null for empty array', async () => {
+      const { selectBestSession } = await import('../../service/actions.js');
+      
+      assert.strictEqual(selectBestSession([], {}), null);
+      assert.strictEqual(selectBestSession(null, {}), null);
+    });
+
+    test('listSessions fetches sessions filtered by directory', async () => {
+      const { listSessions } = await import('../../service/actions.js');
+      
+      let calledUrl = null;
+      const mockFetch = async (url) => {
+        calledUrl = url;
+        return {
+          ok: true,
+          json: async () => [
+            { id: 'ses_1', directory: '/path/to/project', time: { created: 1000 } },
+          ],
+        };
+      };
+      
+      const sessions = await listSessions('http://localhost:4096', { 
+        directory: '/path/to/project',
+        fetch: mockFetch 
+      });
+      
+      assert.ok(calledUrl.includes('directory='), 'Should include directory param');
+      assert.ok(calledUrl.includes('roots=true'), 'Should only get root sessions');
+      assert.strictEqual(sessions.length, 1);
+    });
+
+    test('findReusableSession filters out archived sessions', async () => {
+      const { findReusableSession } = await import('../../service/actions.js');
+      
+      const mockFetch = async (url) => {
+        if (url.includes('/session/status')) {
+          return { ok: true, json: async () => ({}) };
+        }
+        // GET /session
+        return {
+          ok: true,
+          json: async () => [
+            { id: 'ses_archived', directory: '/path', time: { created: 1000, updated: 3000, archived: 4000 } },
+            { id: 'ses_active', directory: '/path', time: { created: 2000, updated: 2500 } },
+          ],
+        };
+      };
+      
+      const session = await findReusableSession('http://localhost:4096', '/path', { fetch: mockFetch });
+      
+      assert.ok(session, 'Should find a session');
+      assert.strictEqual(session.id, 'ses_active', 'Should return the active session, not archived');
+    });
+
+    test('findReusableSession returns null when all sessions are archived', async () => {
+      const { findReusableSession } = await import('../../service/actions.js');
+      
+      const mockFetch = async (url) => {
+        if (url.includes('/session/status')) {
+          return { ok: true, json: async () => ({}) };
+        }
+        return {
+          ok: true,
+          json: async () => [
+            { id: 'ses_1', directory: '/path', time: { created: 1000, archived: 2000 } },
+            { id: 'ses_2', directory: '/path', time: { created: 1500, archived: 2500 } },
+          ],
+        };
+      };
+      
+      const session = await findReusableSession('http://localhost:4096', '/path', { fetch: mockFetch });
+      
+      assert.strictEqual(session, null, 'Should return null when all sessions are archived');
+    });
+
+    test('executeAction reuses existing session instead of creating new', async () => {
+      const { executeAction } = await import('../../service/actions.js');
+      
+      const item = { number: 123, title: 'Fix bug' };
+      const config = {
+        path: tempDir,
+        prompt: 'default',
+      };
+      
+      let sessionCreated = false;
+      let messagePosted = false;
+      let messageSessionId = null;
+      
+      const mockFetch = async (url, opts) => {
+        // GET /session - return existing active session
+        if (url.includes('/session') && !url.includes('/message') && !url.includes('/status') && (!opts || opts.method !== 'POST' && opts.method !== 'PATCH')) {
+          return {
+            ok: true,
+            json: async () => [
+              { id: 'ses_existing', directory: tempDir, time: { created: 1000, updated: 2000 } },
+            ],
+          };
+        }
+        // GET /session/status
+        if (url.includes('/session/status')) {
+          return { ok: true, json: async () => ({}) };  // session is idle
+        }
+        // POST /session (create) - should NOT be called
+        if (url.endsWith('/session') && opts?.method === 'POST') {
+          sessionCreated = true;
+          return { ok: true, json: async () => ({ id: 'ses_new' }) };
+        }
+        // PATCH /session/:id (update title)
+        if (opts?.method === 'PATCH') {
+          return { ok: true, json: async () => ({}) };
+        }
+        // POST /session/:id/message
+        if (url.includes('/message') && opts?.method === 'POST') {
+          messagePosted = true;
+          messageSessionId = url.match(/session\/([^/]+)\/message/)?.[1];
+          return { ok: true, json: async () => ({ success: true }) };
+        }
+        return { ok: false, text: async () => 'Not found' };
+      };
+      
+      const mockDiscoverServer = async () => 'http://localhost:4096';
+      
+      const result = await executeAction(item, config, { 
+        discoverServer: mockDiscoverServer,
+        fetch: mockFetch
+      });
+      
+      assert.ok(result.success, 'Should succeed');
+      assert.strictEqual(result.sessionId, 'ses_existing', 'Should use existing session ID');
+      assert.strictEqual(result.sessionReused, true, 'Should indicate session was reused');
+      assert.strictEqual(sessionCreated, false, 'Should NOT create a new session');
+      assert.strictEqual(messagePosted, true, 'Should post message to existing session');
+      assert.strictEqual(messageSessionId, 'ses_existing', 'Should post to the existing session');
+    });
+
+    test('executeAction creates new session when existing is archived', async () => {
+      const { executeAction } = await import('../../service/actions.js');
+      
+      const item = { number: 456, title: 'New feature' };
+      const config = {
+        path: tempDir,
+        prompt: 'default',
+      };
+      
+      let sessionCreated = false;
+      
+      const mockFetch = async (url, opts) => {
+        // GET /session - return only archived session
+        if (url.includes('/session') && !url.includes('/message') && !url.includes('/status') && (!opts || opts.method !== 'POST' && opts.method !== 'PATCH')) {
+          return {
+            ok: true,
+            json: async () => [
+              { id: 'ses_archived', directory: tempDir, time: { created: 1000, updated: 2000, archived: 3000 } },
+            ],
+          };
+        }
+        // GET /session/status
+        if (url.includes('/session/status')) {
+          return { ok: true, json: async () => ({}) };
+        }
+        // POST /session (create) - should be called since archived session can't be reused
+        if (url.includes('/session') && !url.includes('/message') && opts?.method === 'POST') {
+          sessionCreated = true;
+          return { ok: true, json: async () => ({ id: 'ses_new' }) };
+        }
+        // PATCH /session/:id
+        if (opts?.method === 'PATCH') {
+          return { ok: true, json: async () => ({}) };
+        }
+        // POST /session/:id/message
+        if (url.includes('/message') && opts?.method === 'POST') {
+          return { ok: true, json: async () => ({ success: true }) };
+        }
+        return { ok: false, text: async () => 'Not found' };
+      };
+      
+      const mockDiscoverServer = async () => 'http://localhost:4096';
+      
+      const result = await executeAction(item, config, { 
+        discoverServer: mockDiscoverServer,
+        fetch: mockFetch
+      });
+      
+      assert.ok(result.success, 'Should succeed');
+      assert.strictEqual(result.sessionId, 'ses_new', 'Should create new session');
+      assert.strictEqual(result.sessionReused, undefined, 'Should NOT indicate session was reused');
+      assert.strictEqual(sessionCreated, true, 'Should create a new session when existing is archived');
+    });
+
+    test('executeAction skips session reuse when reuse_active_session is false', async () => {
+      const { executeAction } = await import('../../service/actions.js');
+      
+      const item = { number: 789, title: 'Forced new' };
+      const config = {
+        path: tempDir,
+        prompt: 'default',
+        reuse_active_session: false,  // disable reuse
+      };
+      
+      let sessionListCalled = false;
+      let sessionCreated = false;
+      
+      const mockFetch = async (url, opts) => {
+        // GET /session - should NOT be called
+        if (url.includes('/session') && !url.includes('/message') && !url.includes('/status') && (!opts || opts.method !== 'POST' && opts.method !== 'PATCH')) {
+          sessionListCalled = true;
+          return { ok: true, json: async () => [] };
+        }
+        // POST /session
+        if (url.includes('/session') && !url.includes('/message') && opts?.method === 'POST') {
+          sessionCreated = true;
+          return { ok: true, json: async () => ({ id: 'ses_forced_new' }) };
+        }
+        // PATCH
+        if (opts?.method === 'PATCH') {
+          return { ok: true, json: async () => ({}) };
+        }
+        // POST message
+        if (url.includes('/message') && opts?.method === 'POST') {
+          return { ok: true, json: async () => ({ success: true }) };
+        }
+        return { ok: false, text: async () => 'Not found' };
+      };
+      
+      const mockDiscoverServer = async () => 'http://localhost:4096';
+      
+      const result = await executeAction(item, config, { 
+        discoverServer: mockDiscoverServer,
+        fetch: mockFetch
+      });
+      
+      assert.ok(result.success, 'Should succeed');
+      assert.strictEqual(sessionListCalled, false, 'Should NOT list sessions when reuse disabled');
+      assert.strictEqual(sessionCreated, true, 'Should create new session directly');
+    });
+  });
 });

package/test/unit/worktree.test.js

@@ -22,6 +22,22 @@ describe("worktree", () => {
       assert.strictEqual(mockFetch.mock.calls[0].arguments[0], "http://localhost:4096/experimental/worktree");
     });
 
+    it("passes directory parameter when provided", async () => {
+      const mockFetch = mock.fn(async () => ({
+        ok: true,
+        json: async () => ["/path/to/worktree"],
+      }));
+
+      await listWorktrees("http://localhost:4096", { 
+        fetch: mockFetch,
+        directory: "/path/to/project"
+      });
+
+      const calledUrl = mockFetch.mock.calls[0].arguments[0];
+      assert.ok(calledUrl.includes("directory="), "Should include directory param");
+      assert.ok(calledUrl.includes(encodeURIComponent("/path/to/project")), "Should encode directory path");
+    });
+
     it("returns empty array on error", async () => {
       const mockFetch = mock.fn(async () => ({
         ok: false,
@@ -189,14 +205,24 @@ describe("worktree", () => {
     });
 
     it("passes worktreeName when creating new worktree", async () => {
-      const mockFetch = mock.fn(async () => ({
-        ok: true,
-        json: async () => ({
-          name: "my-feature",
-          branch: "opencode/my-feature",
-          directory: "/data/worktree/abc123/my-feature",
-        }),
-      }));
+      const mockFetch = mock.fn(async (url, opts) => {
+        // First call: GET /experimental/worktree (list) - return empty to trigger creation
+        if (!opts || opts.method !== 'POST') {
+          return {
+            ok: true,
+            json: async () => [],
+          };
+        }
+        // Second call: POST /experimental/worktree (create)
+        return {
+          ok: true,
+          json: async () => ({
+            name: "my-feature",
+            branch: "opencode/my-feature",
+            directory: "/data/worktree/abc123/my-feature",
+          }),
+        };
+      });
 
       await resolveWorktreeDirectory(
         "http://localhost:4096",
@@ -205,7 +231,11 @@ describe("worktree", () => {
         { fetch: mockFetch }
       );
 
-      const body = JSON.parse(mockFetch.mock.calls[0].arguments[1].body);
+      // Should have called both list (GET) and create (POST)
+      assert.strictEqual(mockFetch.mock.calls.length, 2);
+      // Second call should be POST with the worktree name
+      const postCall = mockFetch.mock.calls[1];
+      const body = JSON.parse(postCall.arguments[1].body);
       assert.strictEqual(body.name, "my-feature");
     });
 
@@ -250,6 +280,117 @@ describe("worktree", () => {
       assert.strictEqual(result.directory, "/data/worktree/abc123/my-feature");
     });
 
+    it("reuses existing sandbox when worktree='new' and worktreeName matches", async () => {
+      let postCalled = false;
+      let listUrl = null;
+      const mockFetch = mock.fn(async (url, opts) => {
+        // GET /experimental/worktree (list) - returns existing sandbox with matching name
+        if (!opts || opts.method !== 'POST') {
+          listUrl = url;
+          return {
+            ok: true,
+            json: async () => [
+              "/data/worktree/abc123/other-branch",
+              "/data/worktree/abc123/my-feature",  // matches worktreeName
+            ],
+          };
+        }
+        // POST /experimental/worktree (create) - should NOT be called
+        postCalled = true;
+        return { ok: true, json: async () => ({}) };
+      });
+
+      const result = await resolveWorktreeDirectory(
+        "http://localhost:4096",
+        "/path/to/project",
+        { worktree: "new", worktreeName: "my-feature" },
+        { fetch: mockFetch }
+      );
+
+      // Should reuse existing sandbox
+      assert.strictEqual(result.directory, "/data/worktree/abc123/my-feature");
+      assert.strictEqual(result.worktreeReused, true);
+      assert.strictEqual(result.worktreeCreated, undefined);
+      // POST should NOT have been called
+      assert.strictEqual(postCalled, false, "Should not call POST when reusing existing sandbox");
+      // listWorktrees should be called with directory parameter
+      assert.ok(listUrl.includes("directory="), "Should pass directory to listWorktrees");
+      assert.ok(listUrl.includes(encodeURIComponent("/path/to/project")), "Should pass correct project directory");
+    });
+
+    it("creates new sandbox when worktree='new' and no matching name exists", async () => {
+      let getCalled = false;
+      let postCalled = false;
+      const mockFetch = mock.fn(async (url, opts) => {
+        // GET /experimental/worktree (list) - no matching name
+        if (!opts || opts.method !== 'POST') {
+          getCalled = true;
+          return {
+            ok: true,
+            json: async () => ["/data/worktree/abc123/other-branch"],
+          };
+        }
+        // POST /experimental/worktree (create)
+        postCalled = true;
+        return {
+          ok: true,
+          json: async () => ({
+            name: "new-feature",
+            branch: "opencode/new-feature",
+            directory: "/data/worktree/abc123/new-feature",
+          }),
+        };
+      });
+
+      const result = await resolveWorktreeDirectory(
+        "http://localhost:4096",
+        "/path/to/project",
+        { worktree: "new", worktreeName: "new-feature" },
+        { fetch: mockFetch }
+      );
+
+      // Should create new sandbox
+      assert.strictEqual(result.directory, "/data/worktree/abc123/new-feature");
+      assert.strictEqual(result.worktreeCreated, true);
+      assert.strictEqual(result.worktreeReused, undefined);
+      // Both GET and POST should have been called
+      assert.strictEqual(getCalled, true, "Should call GET to list existing worktrees");
+      assert.strictEqual(postCalled, true, "Should call POST to create new worktree");
+    });
+
+    it("skips sandbox reuse when preferExistingSandbox is false", async () => {
+      let getCalled = false;
+      const mockFetch = mock.fn(async (url, opts) => {
+        // GET /experimental/worktree - should NOT be called
+        if (!opts || opts.method !== 'POST') {
+          getCalled = true;
+          return { ok: true, json: async () => ["/data/worktree/abc123/my-feature"] };
+        }
+        // POST /experimental/worktree (create)
+        return {
+          ok: true,
+          json: async () => ({
+            name: "my-feature",
+            branch: "opencode/my-feature",
+            directory: "/data/worktree/abc123/my-feature-new",
+          }),
+        };
+      });
+
+      const result = await resolveWorktreeDirectory(
+        "http://localhost:4096",
+        "/path/to/project",
+        { worktree: "new", worktreeName: "my-feature", preferExistingSandbox: false },
+        { fetch: mockFetch }
+      );
+
+      // Should create new sandbox, not reuse
+      assert.strictEqual(result.directory, "/data/worktree/abc123/my-feature-new");
+      assert.strictEqual(result.worktreeCreated, true);
+      // GET should NOT have been called (skipped reuse check)
+      assert.strictEqual(getCalled, false, "Should skip GET when preferExistingSandbox is false");
+    });
+
     it("returns error when named worktree not found", async () => {
       const mockFetch = mock.fn(async () => ({
         ok: true,