opencode-pilot 0.24.10 → 0.24.11

package/Formula/opencode-pilot.rb

@@ -1,8 +1,8 @@
 class OpencodePilot < Formula
   desc "Automation daemon for OpenCode - polls GitHub/Linear issues and spawns sessions"
   homepage "https://github.com/athal7/opencode-pilot"
-  url "https://github.com/athal7/opencode-pilot/archive/refs/tags/v0.24.9.tar.gz"
-  sha256 "b477a5677fb80456db3f4f6464dd2071d0efb56bdd29b8a8fc01e5d56638f588"
+  url "https://github.com/athal7/opencode-pilot/archive/refs/tags/v0.24.10.tar.gz"
+  sha256 "09c76da7756c11bfd192fb74c3b9d7e0335678258cfaebf8e7ef3473f7f74e55"
   license "MIT"
 
   depends_on "node"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-pilot",
-  "version": "0.24.10",
+  "version": "0.24.11",
   "type": "module",
   "main": "plugin/index.js",
   "description": "Automation daemon for OpenCode - polls for work and spawns sessions",

package/service/actions.js

@@ -3,6 +3,20 @@
  *
  * Starts OpenCode sessions with configurable prompts.
  * Supports prompt_template for custom prompts (e.g., to invoke /devcontainer).
+ *
+ * ## Session creation invariants
+ *
+ * Every session created by this module MUST satisfy all three invariants.
+ * See service/session-context.js for full documentation and rationale.
+ *
+ *   A. Project scoping  – session's projectID ≠ 'global' → visible in UI
+ *   B. Working directory – agent operates in the worktree, not the main repo
+ *   C. Session isolation – reuse never crosses PR/issue boundaries
+ *
+ * The SessionContext value object carries both directories together so no
+ * call site can accidentally pass the wrong one. When you change session
+ * creation logic, verify all three invariants in the integration tests under
+ * "session creation invariants".
  */
 
 import { execSync } from "child_process";
@@ -11,6 +25,7 @@ import { debug } from "./logger.js";
 import { getNestedValue } from "./utils.js";
 import { getServerPort } from "./repo-config.js";
 import { resolveWorktreeDirectory, getProjectInfo, getProjectInfoForDirectory } from "./worktree.js";
+import { SessionContext } from "./session-context.js";
 import path from "path";
 import os from "os";
 
@@ -672,32 +687,37 @@ export async function findReusableSession(serverUrl, directory, options = {}) {
 
 /**
  * Create a session via the OpenCode HTTP API
- * 
+ *
+ * Satisfies session creation invariants A and B (see module header):
+ *   A. Creates the session scoped to sessionCtx.projectDirectory so OpenCode
+ *      assigns the correct projectID (session visible in desktop UI).
+ *   B. Sends the first message with sessionCtx.workingDirectory so the agent
+ *      operates in the worktree, not the main repo.
+ *
  * @param {string} serverUrl - Server URL (e.g., "http://localhost:4096")
- * @param {string} directory - Working directory for file operations (may be a worktree)
+ * @param {SessionContext} sessionCtx - Carries both directories (see session-context.js)
  * @param {string} prompt - The prompt/message to send
  * @param {object} [options] - Options
- * @param {string} [options.projectDirectory] - Project directory for session scoping (defaults to directory)
  * @param {string} [options.title] - Session title
  * @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 createSessionViaApi(serverUrl, directory, prompt, options = {}) {
+export async function createSessionViaApi(serverUrl, sessionCtx, prompt, options = {}) {
   const fetchFn = options.fetch || fetch;
   const headerTimeout = options.headerTimeout || HEADER_TIMEOUT_MS;
-  const projectDir = options.projectDirectory || directory;
+  // Invariant A: use projectDirectory so OpenCode assigns the correct projectID.
+  // Invariant B: use workingDirectory for messages so the agent operates in the worktree.
+  const projectDir = sessionCtx.projectDirectory;
+  const directory = sessionCtx.workingDirectory;
   
   let session = null;
   
   try {
-    // Step 1: Create session with the working directory (may be a worktree).
-    // This sets the session's working directory so the agent operates in the
-    // correct location. For worktree sessions, the server may assign
-    // projectID 'global' since sandbox paths don't match project worktrees.
+    // Step 1: Create session scoped to the project directory
     const sessionUrl = new URL('/session', serverUrl);
-    sessionUrl.searchParams.set('directory', directory);
+    sessionUrl.searchParams.set('directory', projectDir);
     
     const createResponse = await fetchFn(sessionUrl.toString(), {
       method: 'POST',
@@ -713,20 +733,14 @@ export async function createSessionViaApi(serverUrl, directory, prompt, options
     session = await createResponse.json();
     debug(`createSessionViaApi: created session ${session.id} in ${directory}`);
     
-    // Step 2: Update session - always PATCH with project directory when it
-    // differs from the working directory (worktree case). This re-associates
-    // the session with the correct project so it appears in the UI.
-    // Also set the title if provided.
-    const needsProjectScoping = projectDir !== directory;
-    if (options.title || needsProjectScoping) {
+    // Step 2: Update session title if provided
+    if (options.title) {
       const updateUrl = new URL(`/session/${session.id}`, serverUrl);
       updateUrl.searchParams.set('directory', projectDir);
-      const patchBody = {};
-      if (options.title) patchBody.title = options.title;
       await fetchFn(updateUrl.toString(), {
         method: 'PATCH',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify(patchBody),
+        body: JSON.stringify({ title: options.title }),
       });
     }
     
@@ -839,17 +853,25 @@ export async function createSessionViaApi(serverUrl, directory, prompt, options
 }
 
 /**
- * Execute session creation/reuse in a specific directory
- * Internal helper for executeAction - handles prompt building, session reuse, and API calls
- * 
+ * Execute session creation/reuse for the given session context.
+ * Internal helper for executeAction - handles prompt building, session reuse, and API calls.
+ *
+ * Enforces invariant C (session isolation): session reuse is skipped entirely
+ * when sessionCtx.isWorktree is true. Each PR/issue running in a worktree must
+ * get its own session because:
+ *   - Querying by workingDirectory finds old sessions with projectID='global'
+ *   - Querying by projectDirectory finds sessions for unrelated PRs in the same project
+ *
  * @param {string} serverUrl - OpenCode server URL
- * @param {string} cwd - Working directory for the session
+ * @param {SessionContext} sessionCtx - Carries both directories
  * @param {object} item - Item to create session for
  * @param {object} config - Repo config with action settings
  * @param {object} [options] - Execution options
  * @returns {Promise<object>} Result with command, success, sessionId, etc.
  */
-async function executeInDirectory(serverUrl, cwd, item, config, options = {}, projectDirectory = null) {
+async function executeInDirectory(serverUrl, sessionCtx, item, config, options = {}) {
+  const cwd = sessionCtx.workingDirectory;
+
   // Build prompt from template
   const prompt = buildPromptFromTemplate(config.prompt || "default", item);
   
@@ -889,15 +911,12 @@ async function executeInDirectory(serverUrl, cwd, item, config, options = {}, pr
     }
   }
   
-  // Check if we should try to reuse an existing session.
-  // Skip reuse when working in a worktree (projectDirectory differs from cwd),
-  // because querying by worktree dir finds old sessions with projectID "global",
-  // and querying by project dir finds unrelated sessions for other PRs.
-  // Each worktree should get its own correctly-scoped session.
+  // Invariant C: skip findReusableSession when in a worktree.
+  // Each worktree (= each PR/issue) must get its own session to prevent
+  // cross-PR contamination. See session-context.js for full rationale.
   const reuseActiveSession = config.reuse_active_session !== false; // default true
-  const inWorktree = projectDirectory && projectDirectory !== cwd;
   
-  if (reuseActiveSession && !inWorktree && !options.dryRun) {
+  if (reuseActiveSession && !sessionCtx.isWorktree && !options.dryRun) {
     const existingSession = await findReusableSession(serverUrl, cwd, { fetch: options.fetch });
     
     if (existingSession) {
@@ -934,8 +953,7 @@ async function executeInDirectory(serverUrl, cwd, item, config, options = {}, pr
     };
   }
   
-  const result = await createSessionViaApi(serverUrl, cwd, prompt, {
-    projectDirectory: projectDirectory || cwd,
+  const result = await createSessionViaApi(serverUrl, sessionCtx, prompt, {
     title: sessionTitle,
     agent: config.agent,
     model: config.model,
@@ -994,27 +1012,29 @@ export async function executeAction(item, config, options = {}) {
     };
   }
   
-  // If existing_directory is provided (reprocessing same item), use it directly
-  // This preserves the worktree from the previous run even if its name doesn't match the template
+  // If existing_directory is provided (reprocessing same item), use it directly.
+  // This preserves the worktree from the previous run even if its name doesn't match the template.
+  // Build a worktree SessionContext since existing_directory is a worktree path.
   if (config.existing_directory) {
     debug(`executeAction: using existing_directory=${config.existing_directory}`);
     const cwd = expandPath(config.existing_directory);
-    return await executeInDirectory(serverUrl, cwd, item, config, options, baseCwd);
+    const sessionCtx = SessionContext.forWorktree(baseCwd, cwd);
+    return await executeInDirectory(serverUrl, sessionCtx, item, config, options);
   }
   
-  // Resolve worktree directory if configured
-  // This allows creating sessions in isolated worktrees instead of the main project
+  // Resolve worktree directory if configured.
+  // This allows creating sessions in isolated worktrees instead of the main project.
   let worktreeMode = config.worktree;
   
-  // If worktree_name is configured, enable worktree mode (explicit configuration)
-  // This allows presets to specify worktree isolation without requiring existing sandboxes
+  // If worktree_name is configured, enable worktree mode (explicit configuration).
+  // This allows presets to specify worktree isolation without requiring existing sandboxes.
   if (!worktreeMode && config.worktree_name) {
     debug(`executeAction: worktree_name configured, enabling worktree mode`);
     worktreeMode = 'new';
   }
   
-  // Auto-detect worktree support: check if the project has sandboxes
-  // This is a fallback for when worktree isn't explicitly configured
+  // Auto-detect worktree support: check if the project has sandboxes.
+  // This is a fallback for when worktree isn't explicitly configured.
   if (!worktreeMode) {
     // Look up project info for this specific directory (not just /project/current)
     const projectInfo = await getProjectInfoForDirectory(serverUrl, baseCwd, { fetch: options.fetch });
@@ -1051,5 +1071,8 @@ export async function executeAction(item, config, options = {}) {
   
   debug(`executeAction: using cwd=${cwd}`);
   
-  return await executeInDirectory(serverUrl, cwd, item, config, options, baseCwd);
+  // Build a SessionContext so downstream functions always have both directories.
+  // forWorktree correctly sets isWorktree=true when cwd differs from baseCwd.
+  const sessionCtx = SessionContext.forWorktree(baseCwd, cwd);
+  return await executeInDirectory(serverUrl, sessionCtx, item, config, options);
 }

package/service/session-context.js

@@ -0,0 +1,97 @@
+/**
+ * session-context.js - SessionContext value object
+ *
+ * Encapsulates the two-directory problem that repeatedly caused session
+ * creation regressions (v0.24.7 through v0.24.10).
+ *
+ * ## The Problem
+ *
+ * OpenCode's POST /session API accepts a single `directory` parameter that
+ * conflates two distinct concerns:
+ *
+ *   1. **Project scoping** (projectID) — which project the session belongs to
+ *      in the desktop UI. Requires the *project directory* (the main git repo).
+ *
+ *   2. **Working directory** — where the agent executes file operations.
+ *      Requires the *worktree directory* when using git worktrees.
+ *
+ * When a worktree is active, these directories differ. Passing the wrong one
+ * satisfies one requirement but silently breaks the other.
+ *
+ * ## The Three Invariants
+ *
+ * Any correct session creation MUST satisfy all three:
+ *
+ *   A. **Project scoping**: Session's projectID matches the project (not
+ *      'global'). The session is visible in the desktop app.
+ *      → Requires POST /session?directory=<projectDirectory>
+ *
+ *   B. **Working directory**: Agent operates in the correct location.
+ *      In worktree mode the session's working dir must be the worktree path,
+ *      so file reads/writes go to the right branch.
+ *      → Requires per-message directory=<workingDirectory>
+ *        (or PATCH /session/:id to update the session working dir)
+ *
+ *   C. **Session isolation**: Session reuse only finds sessions for the
+ *      *same work item* (same PR/issue), not other PRs sharing the project.
+ *      → Worktree sessions must NOT be reused across items; each PR gets
+ *        its own session.
+ *
+ * ## The Solution
+ *
+ * - Create sessions with `projectDirectory` (satisfies A).
+ * - Send messages with `workingDirectory` (satisfies B).
+ * - Skip `findReusableSession` entirely when in a worktree (satisfies C),
+ *   because neither the worktree path nor the project path can safely scope
+ *   reuse to a single PR.
+ *
+ * ## Worktree Detection
+ *
+ * A session is "in a worktree" when `workingDirectory !== projectDirectory`.
+ * Non-worktree sessions have both set to the same value.
+ */
+
+export class SessionContext {
+  /**
+   * @param {string} projectDirectory - Base git repo path. Used for:
+   *   - POST /session?directory=... (sets projectID for UI visibility)
+   *   - PATCH /session/:id?directory=... (if post-creation re-scoping needed)
+   *   - listSessions query (for session reuse lookup in non-worktree mode)
+   *
+   * @param {string} workingDirectory - Directory where the agent does work. Used for:
+   *   - POST /session/:id/message?directory=... (file operations)
+   *   - POST /session/:id/command?directory=... (slash commands)
+   *   Equals projectDirectory when not using worktrees.
+   */
+  constructor(projectDirectory, workingDirectory) {
+    if (!projectDirectory) throw new Error('SessionContext: projectDirectory is required');
+    if (!workingDirectory) throw new Error('SessionContext: workingDirectory is required');
+    this.projectDirectory = projectDirectory;
+    this.workingDirectory = workingDirectory;
+    Object.freeze(this);
+  }
+
+  /**
+   * True when the session runs in a worktree separate from the main repo.
+   * Worktree sessions must NOT participate in findReusableSession (invariant C):
+   * - Querying by workingDirectory finds old sessions scoped to 'global' (wrong projectID)
+   * - Querying by projectDirectory finds sessions for other PRs in the same project
+   */
+  get isWorktree() {
+    return this.projectDirectory !== this.workingDirectory;
+  }
+
+  /**
+   * Factory: use this when there is no worktree (single-directory case).
+   */
+  static forProject(directory) {
+    return new SessionContext(directory, directory);
+  }
+
+  /**
+   * Factory: use this when a worktree has been resolved.
+   */
+  static forWorktree(projectDirectory, worktreeDirectory) {
+    return new SessionContext(projectDirectory, worktreeDirectory);
+  }
+}

package/test/integration/poll-once.test.js

@@ -0,0 +1,308 @@
+/**
+ * Integration tests for pollOnce end-to-end orchestration
+ *
+ * Tests the full wiring: config → source → readiness → dedup → executeAction.
+ * Uses executeAction + createPoller directly (simulating what pollOnce does
+ * after fetching items) with a mock OpenCode server to capture API calls.
+ *
+ * These tests verify two properties NOT covered by the invariant tests:
+ *
+ *   1. Two PRs in the same project each get their own session (dedup does not
+ *      collapse them — they have different IDs).
+ *
+ *   2. A PR already processed in a previous poll cycle is skipped on the next
+ *      call (dedup state persists across pollOnce calls).
+ *
+ * The invariant tests (session-reuse.test.js "session creation invariants")
+ * cover WHICH directories are used. These tests cover WHETHER sessions are
+ * created at all.
+ */
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert";
+import { createServer } from "node:http";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { executeAction } from "../../service/actions.js";
+import { createPoller } from "../../service/poller.js";
+
+// ─── Mock server ────────────────────────────────────────────────────────────
+
+/**
+ * Create a mock OpenCode server for testing.
+ * Handlers are keyed by "METHOD /path" (e.g., "POST /session").
+ * A `default` handler catches anything without an exact match.
+ */
+function createMockServer(handlers = {}) {
+  const server = createServer((req, res) => {
+    const url = new URL(req.url, `http://${req.headers.host}`);
+    const pathname = url.pathname;
+    const method = req.method;
+
+    let body = "";
+    req.on("data", (chunk) => (body += chunk));
+    req.on("end", () => {
+      const request = {
+        method,
+        path: pathname,
+        directory: url.searchParams.get("directory"),
+        query: Object.fromEntries(url.searchParams),
+        body: body ? JSON.parse(body) : null,
+      };
+
+      // Find matching handler — try exact match first, then wildcard
+      const exactKey = `${method} ${pathname}`;
+      let handler = handlers[exactKey];
+
+      if (!handler) {
+        for (const [key, h] of Object.entries(handlers)) {
+          if (key === "default") continue;
+          const regexStr = "^" + key.replace(/\*/g, "[^/]+") + "$";
+          if (new RegExp(regexStr).test(exactKey)) {
+            handler = h;
+            break;
+          }
+        }
+      }
+
+      if (!handler) handler = 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: `No handler for ${exactKey}` }));
+      }
+    });
+  });
+
+  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)),
+      });
+    });
+  });
+}
+
+// ─── Fetch interceptor ───────────────────────────────────────────────────────
+
+/**
+ * Build a fetch interceptor that:
+ *  - Records which sessions were created and which directories were used
+ *  - Short-circuits POST /session/:id/message and /command to avoid
+ *    AbortController race with the mock server (see session-reuse.test.js
+ *    for the full explanation of this race condition)
+ *  - Forwards everything else to the real mock server
+ */
+function makeFetchInterceptor(calls) {
+  return async (url, opts) => {
+    const u = new URL(url);
+    const method = opts?.method || "GET";
+
+    // Short-circuit message/command — return mock 200 directly
+    if (method === "POST" && /^\/session\/[^/]+\/(message|command)$/.test(u.pathname)) {
+      const sessionId = u.pathname.split("/")[2];
+      calls.messages = calls.messages || [];
+      calls.messages.push({
+        sessionId,
+        directory: u.searchParams.get("directory"),
+      });
+      return new Response(JSON.stringify({ success: true }), {
+        status: 200,
+        headers: { "Content-Type": "application/json" },
+      });
+    }
+
+    if (method === "POST" && u.pathname === "/session") {
+      calls.sessionsCreated = (calls.sessionsCreated || 0) + 1;
+    }
+
+    return fetch(url, opts);
+  };
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+let sessionCounter = 0;
+
+/**
+ * Build a minimal mock server that handles the OpenCode API calls made by
+ * executeAction for a worktree-based PR source.
+ */
+async function buildWorktreeMockServer(calls) {
+  return createMockServer({
+    "GET /project": () => ({
+      body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+    }),
+    "GET /experimental/worktree": () => ({ body: [] }),
+    "POST /experimental/worktree": (req) => ({
+      body: { name: req.body?.name, directory: `/worktree/${req.body?.name}` },
+    }),
+    "GET /session": () => ({ body: [] }),
+    "GET /session/status": () => ({ body: {} }),
+    "POST /session": () => {
+      const id = `ses_poll_${++sessionCounter}`;
+      calls.createdSessionIds = calls.createdSessionIds || [];
+      calls.createdSessionIds.push(id);
+      return { body: { id } };
+    },
+    default: (req) => {
+      // PATCH /session/:id — title update
+      if (req.method === "PATCH" && req.path.startsWith("/session/")) {
+        return { body: {} };
+      }
+      return { status: 404, body: { error: `Unhandled: ${req.method} ${req.path}` } };
+    },
+  });
+}
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("integration: pollOnce end-to-end", () => {
+  let mockServer;
+  let tmpDir;
+  let stateFile;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "pilot-poll-test-"));
+    stateFile = join(tmpDir, "poll-state.json");
+    sessionCounter = 0;
+  });
+
+  afterEach(async () => {
+    if (mockServer) {
+      await mockServer.close();
+      mockServer = null;
+    }
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+      // ignore
+    }
+  });
+
+  it("two PRs in the same project each get their own session", async () => {
+    // Two PRs, same project, worktree_name configured.
+    // Both are ready (no readiness filter). Each must get a separate session.
+    // This exercises: source → readiness → executeAction × 2 → two sessions.
+
+    const calls = {};
+    mockServer = await buildWorktreeMockServer(calls);
+    const serverUrl = mockServer.url;
+
+    const items = [
+      { id: "pr-101", number: 101, title: "PR #101", state: "open" },
+      { id: "pr-102", number: 102, title: "PR #102", state: "open" },
+    ];
+
+    const poller = createPoller({ stateFile });
+    const fetchFn = makeFetchInterceptor(calls);
+    const results = [];
+
+    for (const item of items) {
+      if (poller.isProcessed(item.id)) continue;
+
+      const actionConfig = {
+        path: "/proj",
+        prompt: "review",
+        worktree_name: "pr-{number}",
+      };
+
+      const result = await executeAction(item, actionConfig, {
+        discoverServer: async () => serverUrl,
+        fetch: fetchFn,
+      });
+
+      results.push({ item, result });
+
+      if (result.success) {
+        poller.markProcessed(item.id, {
+          source: "test-prs",
+          sessionId: result.sessionId,
+          directory: result.directory,
+        });
+      }
+    }
+
+    // Both PRs should succeed
+    assert.strictEqual(results.length, 2, "Both PRs should be processed");
+    assert.ok(results[0].result.success, "PR #101 should succeed");
+    assert.ok(results[1].result.success, "PR #102 should succeed");
+
+    // Each PR must get its own session
+    assert.strictEqual(
+      calls.createdSessionIds?.length,
+      2,
+      "Two separate sessions must be created — one per PR"
+    );
+    assert.notStrictEqual(
+      results[0].result.sessionId,
+      results[1].result.sessionId,
+      "Session IDs must differ between PRs"
+    );
+
+    // Both are now marked as processed
+    assert.ok(poller.isProcessed("pr-101"), "PR #101 should be marked processed");
+    assert.ok(poller.isProcessed("pr-102"), "PR #102 should be marked processed");
+  });
+
+  it("already-processed PR is skipped on second poll cycle", async () => {
+    // One PR, processed in cycle 1. On cycle 2 it must be skipped.
+    // This exercises the dedup path: poller.isProcessed() → continue.
+
+    const calls = {};
+    mockServer = await buildWorktreeMockServer(calls);
+    const serverUrl = mockServer.url;
+
+    const item = { id: "pr-200", number: 200, title: "PR #200", state: "open" };
+    const poller = createPoller({ stateFile });
+    const fetchFn = makeFetchInterceptor(calls);
+
+    const actionConfig = {
+      path: "/proj",
+      prompt: "review",
+      worktree_name: "pr-{number}",
+    };
+
+    // ── Cycle 1: process the PR ──────────────────────────────────────────
+    const result1 = await executeAction(item, actionConfig, {
+      discoverServer: async () => serverUrl,
+      fetch: fetchFn,
+    });
+
+    assert.ok(result1.success, "Cycle 1: PR should be processed successfully");
+    poller.markProcessed(item.id, {
+      source: "test-prs",
+      sessionId: result1.sessionId,
+      directory: result1.directory,
+    });
+
+    const sessionsAfterCycle1 = calls.createdSessionIds?.length || 0;
+    assert.strictEqual(sessionsAfterCycle1, 1, "Cycle 1: exactly one session created");
+
+    // ── Cycle 2: same PR appears again — must be skipped ─────────────────
+    let cycle2Executed = false;
+
+    if (!poller.isProcessed(item.id)) {
+      cycle2Executed = true;
+      await executeAction(item, actionConfig, {
+        discoverServer: async () => serverUrl,
+        fetch: fetchFn,
+      });
+    }
+
+    assert.strictEqual(cycle2Executed, false, "Cycle 2: PR must be skipped (already processed)");
+    assert.strictEqual(
+      calls.createdSessionIds?.length || 0,
+      1,
+      "Cycle 2: no new session must be created"
+    );
+  });
+});

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

@@ -564,9 +564,9 @@ describe("integration: worktree creation with worktree_name", () => {
     assert.ok(worktreeCreateCalled, "Should create worktree when worktree_name is configured");
     assert.strictEqual(createdWorktreeName, "pr-42", "Should expand worktree_name template");
     assert.ok(sessionCreated, "Should create session");
-    // Session creation uses the worktree directory (sets working directory)
-    // The PATCH with project directory re-associates it with the correct project
-    assert.strictEqual(sessionDirectory, "/worktree/pr-42", "Session should be created in worktree directory");
+    // Session creation uses the project directory (for correct projectID scoping)
+    // The worktree path is used for messages/commands (file operations)
+    assert.strictEqual(sessionDirectory, "/proj", "Session should be scoped to project directory");
   });
 
   it("reuses stored directory when reprocessing same item", async () => {
@@ -618,8 +618,8 @@ describe("integration: worktree creation with worktree_name", () => {
     assert.ok(result.success, "Action should succeed");
     // Should NOT create a new worktree since we have existing_directory
     assert.strictEqual(worktreeCreateCalled, false, "Should NOT create new worktree when existing_directory provided");
-    // Session creation uses the existing worktree directory (sets working directory)
-    assert.strictEqual(sessionDirectory, existingWorktreeDir, "Session should be created in existing worktree directory");
+    // Session creation uses the project directory (for correct projectID scoping)
+    assert.strictEqual(sessionDirectory, "/proj", "Session should be scoped to project directory");
   });
 
   it("skips session reuse when working in a worktree", async () => {
@@ -631,7 +631,6 @@ describe("integration: worktree creation with worktree_name", () => {
     let sessionListQueried = false;
     let sessionCreated = false;
     let sessionCreateDirectory = null;
-    let patchDirectory = null;
     
     const existingWorktreeDir = "/worktree/calm-wizard";
     
@@ -655,10 +654,7 @@ describe("integration: worktree creation with worktree_name", () => {
         sessionCreateDirectory = req.query?.directory;
         return { body: { id: "ses_new" } };
       },
-      "PATCH /session/ses_new": (req) => {
-        patchDirectory = req.query?.directory;
-        return { body: {} };
-      },
+      "PATCH /session/ses_new": () => ({ body: {} }),
       "POST /session/ses_new/message": () => ({ body: { success: true } }),
       "POST /session/ses_new/command": () => ({ body: { success: true } }),
     });
@@ -678,13 +674,10 @@ describe("integration: worktree creation with worktree_name", () => {
     // Should NOT query for existing sessions when in a worktree
     assert.strictEqual(sessionListQueried, false,
       "Should skip session reuse entirely when in a worktree");
-    // Should create a new session with the worktree directory (correct working dir)
+    // Should create a new session scoped to the project directory
     assert.ok(sessionCreated, "Should create a new session");
-    assert.strictEqual(sessionCreateDirectory, existingWorktreeDir,
-      "Session should be created in worktree directory");
-    // PATCH re-associates the session with the correct project
-    assert.strictEqual(patchDirectory, "/proj",
-      "PATCH should use project directory for correct project scoping");
+    assert.strictEqual(sessionCreateDirectory, "/proj",
+      "New session should be scoped to project directory");
   });
 });
 
@@ -974,3 +967,275 @@ describe("integration: stacked PR session reuse", () => {
     }
   });
 });
+
+/**
+ * Session creation invariants
+ *
+ * These tests encode the three correctness requirements for every session
+ * created by pilot. They assert OUTCOMES (which directory was used for which
+ * API call), not implementation details (which function was called or how
+ * parameters were threaded).
+ *
+ * DO NOT CHANGE these tests when refactoring session creation internals.
+ * They should only change if the desired behavior changes.
+ *
+ * See service/session-context.js for the full invariant documentation.
+ *
+ *   A. Project scoping  – POST /session uses projectDirectory
+ *   B. Working directory – messages use workingDirectory (the worktree path)
+ *   C. Session isolation – worktree sessions are never reused across PRs
+ *
+ * Implementation note: these tests use a fetch interceptor (options.fetch)
+ * to capture which URL parameters were used for each API call. This is more
+ * reliable than reading the directory inside the mock server's request
+ * handler, because the AbortController in createSessionViaApi aborts the
+ * connection after receiving response headers — which can race with the mock
+ * server's body-buffering. The interceptor captures the URL synchronously
+ * before the request is sent, avoiding the race entirely.
+ */
+describe("session creation invariants", () => {
+  let mockServer;
+
+  afterEach(async () => {
+    if (mockServer) {
+      await mockServer.close();
+      mockServer = null;
+    }
+  });
+
+  /**
+   * Build a fetch interceptor that records which directory was used for
+   * POST /session (session creation) and POST /session/:id/message or
+   * POST /session/:id/command (message delivery), then forwards to the
+   * real mock server.
+   */
+  function makeFetchInterceptor(calls) {
+    return async (url, opts) => {
+      const u = new URL(url);
+      const method = opts?.method || "GET";
+
+      // Short-circuit message/command: return mock 200 directly.
+      // The AbortController in sendMessageToSession/createSessionViaApi aborts
+      // the connection after response headers arrive, which races with the mock
+      // server's body-buffering (req.on("end") never fires). Returning a
+      // synthetic Response here avoids the race entirely.
+      if (method === "POST" && /^\/session\/[^/]+\/(message|command)$/.test(u.pathname)) {
+        calls.messageDirectory = u.searchParams.get("directory");
+        calls.messageSessionId = u.pathname.split("/")[2];
+        return new Response(JSON.stringify({ success: true }), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        });
+      }
+
+      if (method === "POST" && u.pathname === "/session") {
+        calls.sessionCreateDirectory = u.searchParams.get("directory");
+        calls.sessionCreated = true;
+      }
+      if (method === "GET" && u.pathname === "/session") {
+        calls.sessionListQueried = true;
+      }
+      return fetch(url, opts);
+    };
+  }
+
+  it("invariant A+B: session scoped to project, message sent to worktree", async () => {
+    // This is THE test that would have caught every regression in v0.24.7–v0.24.10.
+    // It asserts both invariants simultaneously:
+    //   A. POST /session directory = project path (not worktree) → correct projectID
+    //   B. POST /session/:id/message directory = worktree path → correct working dir
+
+    const calls = {};
+
+    mockServer = await createMockServer({
+      "GET /project": () => ({
+        body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+      }),
+      "GET /experimental/worktree": () => ({ body: [] }),
+      "POST /experimental/worktree": (req) => ({
+        body: { name: req.body?.name, directory: `/worktree/${req.body?.name}` },
+      }),
+      "GET /session": () => ({ body: [] }),
+      "GET /session/status": () => ({ body: {} }),
+      "POST /session": () => ({ body: { id: "ses_inv" } }),
+      "PATCH /session/ses_inv": () => ({ body: {} }),
+    });
+
+    const result = await executeAction(
+      { number: 99, title: "Invariant test PR" },
+      { path: "/proj", prompt: "review", worktree_name: "pr-{number}" },
+      { discoverServer: async () => mockServer.url, fetch: makeFetchInterceptor(calls) }
+    );
+
+    assert.ok(result.success, `Action should succeed (warning: ${result.warning || "none"})`);
+
+    // Invariant A: session creation uses the project directory
+    assert.strictEqual(calls.sessionCreateDirectory, "/proj",
+      "INVARIANT A VIOLATED: POST /session must use projectDirectory for correct projectID");
+
+    // Invariant B: message uses the worktree directory
+    assert.strictEqual(calls.messageDirectory, "/worktree/pr-99",
+      "INVARIANT B VIOLATED: POST /message must use workingDirectory for correct file operations");
+
+    // Sanity: the two directories must be different in the worktree case
+    assert.notStrictEqual(calls.sessionCreateDirectory, calls.messageDirectory,
+      "In worktree mode, session creation dir and message dir must differ");
+  });
+
+  it("invariant A+B hold when reprocessing with existing_directory", async () => {
+    // When reprocessing an item (e.g., new feedback on a PR), the existing worktree
+    // directory is passed. The same invariants must still hold.
+
+    const calls = {};
+
+    mockServer = await createMockServer({
+      "GET /project": () => ({
+        body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+      }),
+      "GET /session": () => ({ body: [] }),
+      "GET /session/status": () => ({ body: {} }),
+      "POST /session": () => ({ body: { id: "ses_reprocess_inv" } }),
+      "PATCH /session/ses_reprocess_inv": () => ({ body: {} }),
+    });
+
+    const result = await executeAction(
+      { number: 42, title: "Reprocessed PR" },
+      {
+        path: "/proj",
+        prompt: "review",
+        worktree_name: "pr-{number}",
+        existing_directory: "/worktree/calm-wizard",
+      },
+      { discoverServer: async () => mockServer.url, fetch: makeFetchInterceptor(calls) }
+    );
+
+    assert.ok(result.success, `Action should succeed (warning: ${result.warning || "none"})`);
+
+    // Invariant A: session creation uses the project directory, not the worktree
+    assert.strictEqual(calls.sessionCreateDirectory, "/proj",
+      "INVARIANT A VIOLATED: reprocessing must still use projectDirectory for POST /session");
+
+    // Invariant B: message uses the existing worktree directory
+    assert.strictEqual(calls.messageDirectory, "/worktree/calm-wizard",
+      "INVARIANT B VIOLATED: reprocessing must send messages to the existing worktree path");
+  });
+
+  it("invariant C: second PR in same project gets its own session", async () => {
+    // Two PRs in the same project (/proj). PR #1 already has an active session.
+    // PR #2 works in a different worktree. Session reuse must NOT return PR #1's
+    // session — each PR must get its own session.
+
+    const calls = { sessionListQueried: false, sessionCreated: false };
+
+    mockServer = await createMockServer({
+      "GET /project": () => ({
+        body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+      }),
+      "GET /experimental/worktree": () => ({ body: ["/worktree/pr-200"] }),
+      "GET /session": () => ({
+        // Return PR #1's session — this should NOT be reused for PR #2
+        body: [{ id: "ses_pr1", time: { created: 1, updated: 2 } }],
+      }),
+      "GET /session/status": () => ({ body: { ses_pr1: { type: "idle" } } }),
+      "POST /session": () => ({ body: { id: "ses_pr2" } }),
+      "PATCH /session/ses_pr2": () => ({ body: {} }),
+    });
+
+    const result = await executeAction(
+      { number: 200, title: "PR #200" },
+      {
+        path: "/proj",
+        prompt: "review",
+        worktree_name: "pr-{number}",
+        existing_directory: "/worktree/pr-200",
+      },
+      { discoverServer: async () => mockServer.url, fetch: makeFetchInterceptor(calls) }
+    );
+
+    assert.ok(result.success, `Action should succeed (warning: ${result.warning || "none"})`);
+
+    // Invariant C: session reuse is skipped entirely when in a worktree
+    assert.strictEqual(calls.sessionListQueried, false,
+      "INVARIANT C VIOLATED: worktree sessions must not query for reusable sessions");
+
+    // A new session must be created for this PR
+    assert.ok(calls.sessionCreated,
+      "INVARIANT C VIOLATED: each worktree PR must get its own new session");
+
+    // The returned session must be the new one, not PR #1's
+    assert.strictEqual(result.sessionId, "ses_pr2",
+      "INVARIANT C VIOLATED: result must reference the newly created session, not PR #1's");
+  });
+
+  it("invariant C exception: non-worktree sessions ARE reused", async () => {
+    // Session reuse should still work for items NOT running in a worktree.
+    // A non-worktree item (path == cwd) should find and reuse an existing session.
+
+    const calls = { sessionListQueried: false, sessionCreated: false };
+
+    mockServer = await createMockServer({
+      "GET /project": () => ({
+        body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+      }),
+      "GET /session": () => ({
+        body: [{ id: "ses_existing", time: { created: 1, updated: 2 } }],
+      }),
+      "GET /session/status": () => ({ body: { ses_existing: { type: "idle" } } }),
+      "POST /session": () => ({ body: { id: "ses_should_not_create" } }),
+      "PATCH /session/ses_existing": () => ({ body: {} }),
+    });
+
+    const result = await executeAction(
+      { number: 1, title: "Non-worktree item" },
+      {
+        path: "/proj",
+        prompt: "review",
+        // No worktree_name, no existing_directory → non-worktree mode
+      },
+      { discoverServer: async () => mockServer.url, fetch: makeFetchInterceptor(calls) }
+    );
+
+    assert.ok(result.success, `Action should succeed (warning: ${result.warning || "none"})`);
+
+    // Non-worktree: session reuse SHOULD work
+    assert.ok(calls.sessionListQueried,
+      "Non-worktree items should query for reusable sessions");
+    assert.strictEqual(calls.sessionCreated, false,
+      "Should reuse existing session, not create a new one");
+    assert.strictEqual(result.sessionId, "ses_existing",
+      "Should return the reused session ID");
+    assert.ok(result.sessionReused,
+      "Should flag the session as reused");
+  });
+
+  it("invariants A+B hold for non-worktree sessions (degenerate case)", async () => {
+    // When there is no worktree, both directories are the same.
+    // POST /session and POST /message should both use the project directory.
+
+    const calls = {};
+
+    mockServer = await createMockServer({
+      "GET /project": () => ({
+        body: [{ id: "proj_1", worktree: "/proj", sandboxes: [], time: { created: 1 } }],
+      }),
+      "GET /session": () => ({ body: [] }),
+      "GET /session/status": () => ({ body: {} }),
+      "POST /session": () => ({ body: { id: "ses_nwt" } }),
+      "PATCH /session/ses_nwt": () => ({ body: {} }),
+    });
+
+    const result = await executeAction(
+      { number: 1, title: "No worktree" },
+      { path: "/proj", prompt: "review" },
+      { discoverServer: async () => mockServer.url, fetch: makeFetchInterceptor(calls) }
+    );
+
+    assert.ok(result.success, `Action should succeed (warning: ${result.warning || "none"})`);
+
+    // Both should be the project directory when no worktree is involved
+    assert.strictEqual(calls.sessionCreateDirectory, "/proj",
+      "Non-worktree: session creation should use project directory");
+    assert.strictEqual(calls.messageDirectory, "/proj",
+      "Non-worktree: message should use project directory");
+  });
+});

package/test/unit/actions.test.js

@@ -7,6 +7,7 @@ import assert from 'node:assert';
 import { mkdtempSync, writeFileSync, mkdirSync, rmSync } from 'fs';
 import { join } from 'path';
 import { tmpdir, homedir } from 'os';
+import { SessionContext } from '../../service/session-context.js';
 
 describe('actions.js', () => {
   let tempDir;
@@ -981,9 +982,9 @@ Check for bugs and security issues.`;
       // Should NOT call worktree endpoints when existing_directory is provided
       assert.strictEqual(worktreeListCalled, false, 'Should NOT list worktrees');
       assert.strictEqual(worktreeCreateCalled, false, 'Should NOT create worktree');
-      // Session creation uses the worktree directory (sets correct working directory)
-      assert.strictEqual(sessionDirectory, '/data/worktree/calm-wizard', 
-        'Session creation should use worktree directory for correct working dir');
+      // Session creation uses project directory (for correct projectID scoping)
+      assert.strictEqual(sessionDirectory, '/data/proj', 
+        'Session creation should use project directory, not worktree');
       // Result directory is the worktree (where file operations happen)
       assert.strictEqual(result.directory, '/data/worktree/calm-wizard',
         'Result should include worktree directory');
@@ -1026,7 +1027,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { fetch: mockFetch }
       );
@@ -1042,12 +1043,11 @@ Check for bugs and security issues.`;
       assert.ok(messageUrl.includes('%2Fpath%2Fto%2Fproject'), 'Message URL should include encoded directory path');
     });
 
-    test('creates session with worktree directory, patches with project directory for scoping', async () => {
+    test('uses projectDirectory for session creation, working directory for messages', async () => {
       const { createSessionViaApi } = await import('../../service/actions.js');
       
       const mockSessionId = 'ses_test_proj';
       let createUrl = null;
-      let patchUrl = null;
       let messageUrl = null;
       
       const mockFetch = async (url, opts) => {
@@ -1058,11 +1058,6 @@ Check for bugs and security issues.`;
           return { ok: true, json: async () => ({ id: mockSessionId }) };
         }
         
-        if (urlObj.pathname.includes(`/session/${mockSessionId}`) && opts?.method === 'PATCH') {
-          patchUrl = url;
-          return { ok: true, json: async () => ({}) };
-        }
-        
         if (urlObj.pathname.includes('/message') && opts?.method === 'POST') {
           messageUrl = url;
           return { ok: true, json: async () => ({ success: true }) };
@@ -1073,26 +1068,21 @@ Check for bugs and security issues.`;
       
       await createSessionViaApi(
         'http://localhost:4096',
-        '/home/user/.local/share/opencode/worktree/abc123/pr-415',
+        SessionContext.forWorktree(
+          '/home/user/code/odin',
+          '/home/user/.local/share/opencode/worktree/abc123/pr-415'
+        ),
         'Fix the bug',
-        { 
-          fetch: mockFetch,
-          projectDirectory: '/home/user/code/odin',
-        }
+        { fetch: mockFetch }
       );
       
-      // Session creation should use the worktree directory (sets working directory)
-      assert.ok(createUrl.includes('worktree'), 
-        'Session creation should use the worktree path');
-      assert.ok(createUrl.includes('pr-415'), 
-        'Session creation should use the worktree path');
+      // Session creation should use the project directory (for correct projectID scoping)
+      assert.ok(createUrl.includes('%2Fhome%2Fuser%2Fcode%2Fodin'), 
+        'Session creation should use projectDirectory');
+      assert.ok(!createUrl.includes('worktree'), 
+        'Session creation should NOT use the worktree path');
       
-      // PATCH should use the project directory (re-associates with correct project)
-      assert.ok(patchUrl, 'PATCH should be called for project scoping');
-      assert.ok(patchUrl.includes('%2Fhome%2Fuser%2Fcode%2Fodin'), 
-        'PATCH should use projectDirectory for project scoping');
-      
-      // Message should use the working directory (worktree)
+      // Message should use the working directory (for file operations in the worktree)
       assert.ok(messageUrl.includes('worktree'), 
         'Message should use the worktree working directory');
       assert.ok(messageUrl.includes('pr-415'), 
@@ -1110,7 +1100,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { fetch: mockFetch }
       );
@@ -1152,7 +1142,7 @@ Check for bugs and security issues.`;
       
       await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { 
           fetch: mockFetch,
@@ -1197,7 +1187,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { fetch: mockFetch }
       );
@@ -1256,7 +1246,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         '/review https://github.com/org/repo/pull/123',
         { fetch: mockFetch }
       );
@@ -1309,7 +1299,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug in the login page',
         { fetch: mockFetch }
       );
@@ -1360,7 +1350,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { fetch: mockFetch, title: 'Test Session', headerTimeout: 100 }
       );
@@ -1407,7 +1397,7 @@ Check for bugs and security issues.`;
       
       const result = await createSessionViaApi(
         'http://localhost:4096',
-        '/path/to/project',
+        SessionContext.forProject('/path/to/project'),
         'Fix the bug',
         { fetch: mockFetch }
       );