opencode-pilot 0.24.11 → 0.25.0

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.10.tar.gz"
-  sha256 "09c76da7756c11bfd192fb74c3b9d7e0335678258cfaebf8e7ef3473f7f74e55"
+  url "https://github.com/athal7/opencode-pilot/archive/refs/tags/v0.24.12.tar.gz"
+  sha256 "ea6f7ba7814225f9e312143f0222777bf4094da87cdbadad1e6589208c5323ab"
   license "MIT"
 
   depends_on "node"

package/bin/opencode-pilot

@@ -14,7 +14,7 @@
 import { fileURLToPath } from "url";
 import { dirname, join } from "path";
 import { existsSync, readFileSync, writeFileSync, unlinkSync, mkdirSync } from "fs";
-import { execSync } from "child_process";
+import { execSync, spawn } from "child_process";
 import os from "os";
 import YAML from "yaml";
 
@@ -179,6 +179,7 @@ Commands:
   status               Show service status and version
   config               Validate and show configuration
   clear                Clear processed state entries
+  logs                 Show debug log output
   test-source NAME     Test a source by fetching items and showing mappings
   test-mapping MCP     Test field mappings with sample JSON input
   help                 Show this help message
@@ -189,6 +190,11 @@ Clear options:
   --item ID            Clear a specific item
   --expired            Clear only expired entries (uses configured TTL)
 
+Logs options:
+  --path               Print the log file path and exit
+  --lines N            Print last N lines (default: 50)
+  --follow             Follow the log file (like tail -f)
+
 The service handles:
 - Polling for GitHub/Linear issues to work on
 - Spawning OpenCode sessions for ready items
@@ -200,6 +206,10 @@ Examples:
   opencode-pilot config                  # Validate and show config
   opencode-pilot clear --all             # Clear all processed state
   opencode-pilot clear --expired         # Clear expired entries
+  opencode-pilot logs                    # Show last 50 log lines
+  opencode-pilot logs --lines 100        # Show last 100 log lines
+  opencode-pilot logs --follow           # Follow the log in real time
+  opencode-pilot logs --path             # Print the log file path
   opencode-pilot test-source my-issues   # Test a source
   echo '{"url":"https://linear.app/team/issue/PROJ-123/title"}' | opencode-pilot test-mapping linear
 `);
@@ -812,6 +822,87 @@ async function clearCommand(flags) {
   }
 }
 
+// ============================================================================
+// Logs Command
+// ============================================================================
+
+// Default log path (mirrors service/logger.js)
+const DEFAULT_LOG_PATH = join(os.homedir(), ".local", "share", "opencode-pilot", "debug.log");
+
+/**
+ * Resolve the debug log file path.
+ * Can be overridden via PILOT_LOG_PATH env var (used in tests).
+ */
+function getLogPath() {
+  return process.env.PILOT_LOG_PATH || DEFAULT_LOG_PATH;
+}
+
+/**
+ * Read the last `n` lines from a file synchronously.
+ * Returns an empty array if the file does not exist.
+ */
+function tailLines(filePath, n) {
+  if (!existsSync(filePath)) return [];
+  const content = readFileSync(filePath, "utf8");
+  const lines = content.split("\n");
+  // Remove trailing empty line produced by a file ending with \n
+  if (lines[lines.length - 1] === "") lines.pop();
+  return lines.slice(-n);
+}
+
+/**
+ * Parse a --lines flag value, falling back to `defaultN` for missing/invalid input.
+ */
+function parseLineCount(value, defaultN) {
+  if (value === undefined || value === true || value === false) return defaultN;
+  const n = parseInt(value, 10);
+  return Number.isFinite(n) && n > 0 ? n : defaultN;
+}
+
+async function logsCommand(flags) {
+  const logPath = getLogPath();
+
+  // --path: just print the path and exit
+  if (flags.path) {
+    console.log(logPath);
+    return;
+  }
+
+  // --follow: stream the file using tail -f
+  if (flags.follow) {
+    if (!existsSync(logPath)) {
+      console.log(`No log file yet. Enable debug logging with PILOT_DEBUG=true.`);
+      console.log(`Log path: ${logPath}`);
+      return;
+    }
+    const lineCount = parseLineCount(flags.lines, 50);
+    // Use system `tail -f` for reliable follow behaviour
+    const tail = spawn("tail", ["-f", "-n", String(lineCount), logPath], {
+      stdio: ["ignore", "inherit", "inherit"],
+    });
+    await new Promise((resolve, reject) => {
+      tail.on("error", reject);
+      tail.on("close", resolve);
+    });
+    return;
+  }
+
+  // Default: print last N lines
+  const n = parseLineCount(flags.lines, 50);
+  if (!existsSync(logPath)) {
+    console.log(`No log file found. Debug logging is enabled via PILOT_DEBUG=true.`);
+    console.log(`Log path: ${logPath}`);
+    return;
+  }
+
+  const lines = tailLines(logPath, n);
+  if (lines.length === 0) {
+    console.log(`Log file is empty: ${logPath}`);
+    return;
+  }
+  console.log(lines.join("\n"));
+}
+
 // ============================================================================
 // Main
 // ============================================================================
@@ -846,6 +937,10 @@ async function main() {
       await clearCommand(parseArgs(args).flags);
       break;
 
+    case "logs":
+      await logsCommand(parseArgs(args).flags);
+      break;
+
     case "test-source":
       await testSourceCommand(subcommand);
       break;

package/package.json

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

package/service/actions.js

@@ -4,19 +4,19 @@
  * Starts OpenCode sessions with configurable prompts.
  * Supports prompt_template for custom prompts (e.g., to invoke /devcontainer).
  *
- * ## Session creation invariants
+ * ## Session directory handling
  *
- * Every session created by this module MUST satisfy all three invariants.
- * See service/session-context.js for full documentation and rationale.
+ * POST /session?directory=X sets both session.directory (working dir) and
+ * session.projectID (derived from the git root of X). Sandbox directories
+ * are git worktrees of the parent repo — they share the same root commit,
+ * so OpenCode resolves the correct projectID automatically.
  *
- *   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
+ * This means we always POST with the workingDirectory. No PATCH-based
+ * "project re-scoping" is needed. See test/integration/real-server.test.js
+ * for verification against a real OpenCode server.
  *
- * 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".
+ * Session isolation: worktree sessions skip findReusableSession entirely
+ * to prevent cross-PR contamination (each PR gets its own session).
  */
 
 import { execSync } from "child_process";
@@ -688,11 +688,12 @@ 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.
+ * Creates the session with sessionCtx.workingDirectory. OpenCode resolves
+ * the correct projectID from the git root of that directory — sandbox dirs
+ * (git worktrees) resolve to the same project as the parent repo, so no
+ * separate "project scoping" step is needed.
+ *
+ * Verified against real OpenCode server in test/integration/real-server.test.js.
  *
  * @param {string} serverUrl - Server URL (e.g., "http://localhost:4096")
  * @param {SessionContext} sessionCtx - Carries both directories (see session-context.js)
@@ -707,17 +708,24 @@ export async function findReusableSession(serverUrl, directory, options = {}) {
 export async function createSessionViaApi(serverUrl, sessionCtx, prompt, options = {}) {
   const fetchFn = options.fetch || fetch;
   const headerTimeout = options.headerTimeout || HEADER_TIMEOUT_MS;
-  // 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;
+  // POST /session?directory=X sets both session.directory and projectID.
+  // OpenCode resolves projectID from the git root of X — sandbox directories
+  // (git worktrees) share the same root commit as the parent repo, so they
+  // get the correct projectID automatically. No PATCH re-scoping needed.
+  //
+  // PATCH /session/:id only updates title/archived — the ?directory param
+  // is a routing parameter (determines which project to look in), NOT a
+  // mutation of session.directory.
   const directory = sessionCtx.workingDirectory;
   
   let session = null;
   
   try {
-    // Step 1: Create session scoped to the project directory
+    // Step 1: Create session with the working directory.
+    // This is what determines where the agent actually operates (file reads,
+    // writes, tool execution). For worktree sessions this is the sandbox path.
     const sessionUrl = new URL('/session', serverUrl);
-    sessionUrl.searchParams.set('directory', projectDir);
+    sessionUrl.searchParams.set('directory', directory);
     
     const createResponse = await fetchFn(sessionUrl.toString(), {
       method: 'POST',
@@ -733,10 +741,12 @@ export async function createSessionViaApi(serverUrl, sessionCtx, prompt, options
     session = await createResponse.json();
     debug(`createSessionViaApi: created session ${session.id} in ${directory}`);
     
-    // Step 2: Update session title if provided
+    // Step 2: Set session title if provided.
+    // PATCH ?directory must match the session's directory so the server can
+    // find it (it's a routing param, not a mutation).
     if (options.title) {
       const updateUrl = new URL(`/session/${session.id}`, serverUrl);
-      updateUrl.searchParams.set('directory', projectDir);
+      updateUrl.searchParams.set('directory', directory);
       await fetchFn(updateUrl.toString(), {
         method: 'PATCH',
         headers: { 'Content-Type': 'application/json' },

package/service/session-context.js

@@ -1,49 +1,36 @@
 /**
  * session-context.js - SessionContext value object
  *
- * Encapsulates the two-directory problem that repeatedly caused session
- * creation regressions (v0.24.7 through v0.24.10).
+ * Tracks both the project directory (main git repo) and the working directory
+ * (which may be a sandbox/worktree) for session creation.
  *
- * ## The Problem
+ * ## How OpenCode's API actually works
  *
- * OpenCode's POST /session API accepts a single `directory` parameter that
- * conflates two distinct concerns:
+ * Verified against a real OpenCode server (see test/integration/real-server.test.js):
  *
- *   1. **Project scoping** (projectID) — which project the session belongs to
- *      in the desktop UI. Requires the *project directory* (the main git repo).
+ *   - POST /session?directory=X sets `session.directory = X` and derives
+ *     `session.projectID` from the git root of X. Sandbox directories are
+ *     git worktrees that share the same root commit as the parent repo, so
+ *     they get the correct projectID automatically. There is NO need to
+ *     create with the project directory for "project scoping".
  *
- *   2. **Working directory** — where the agent executes file operations.
- *      Requires the *worktree directory* when using git worktrees.
+ *   - PATCH /session/:id only updates title/archived. The ?directory param
+ *     is a routing parameter (determines which project to look in), NOT a
+ *     mutation of session.directory.
  *
- * When a worktree is active, these directories differ. Passing the wrong one
- * satisfies one requirement but silently breaks the other.
+ *   - GET /session?directory=X uses ?directory for both project routing
+ *     (middleware) and as an exact filter on session.directory (route handler).
+ *     This means sessions created with a sandbox dir are only visible when
+ *     querying with that sandbox dir — natural isolation per worktree.
  *
- * ## The Three Invariants
+ * ## Why SessionContext still carries both directories
  *
- * 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.
+ * Even though createSessionViaApi only needs workingDirectory, the project
+ * directory is still needed for:
+ *   - Worktree detection (isWorktree) — to skip session reuse for sandbox
+ *     sessions and prevent cross-PR contamination
+ *   - resolveWorktreeDirectory — needs the base project dir to create/list
+ *     worktrees via GET/POST /experimental/worktree?directory=<projectDir>
  *
  * ## Worktree Detection
  *
@@ -54,13 +41,13 @@
 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)
+   *   - Worktree detection (isWorktree check for session isolation)
+   *   - Worktree API calls (GET/POST /experimental/worktree?directory=...)
    *
    * @param {string} workingDirectory - Directory where the agent does work. Used for:
+   *   - POST /session?directory=... (sets session.directory AND projectID)
    *   - POST /session/:id/message?directory=... (file operations)
-   *   - POST /session/:id/command?directory=... (slash commands)
+   *   - PATCH /session/:id?directory=... (routing for title updates)
    *   Equals projectDirectory when not using worktrees.
    */
   constructor(projectDirectory, workingDirectory) {
@@ -73,9 +60,8 @@ export class SessionContext {
 
   /**
    * 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
+   * Worktree sessions skip findReusableSession to prevent cross-PR
+   * contamination — each PR/issue in its own sandbox gets its own session.
    */
   get isWorktree() {
     return this.projectDirectory !== this.workingDirectory;

package/test/integration/real-server.test.js

@@ -0,0 +1,274 @@
+/**
+ * Integration tests against a REAL OpenCode server.
+ *
+ * These tests verify actual API behavior — not mocked assumptions.
+ * They require a running OpenCode instance (the desktop app) with access
+ * to this repo's project. Tests are skipped when no server is available.
+ *
+ * What these tests prove:
+ *
+ *   1. Creating a session with a sandbox directory sets `session.directory`
+ *      to the sandbox path AND resolves the correct `projectID` (same as
+ *      the parent repo). This disproves the assumption that sandbox
+ *      directories produce `projectID = 'global'`.
+ *
+ *   2. PATCH /session/:id does NOT change `session.directory`. The
+ *      `?directory` query param on PATCH is a routing parameter only.
+ *
+ * These facts mean createSessionViaApi only needs to POST with the
+ * working directory — no PATCH-based "re-scoping" is needed.
+ */
+import { describe, it, before, after } from "node:test";
+import assert from "node:assert";
+import path from "node:path";
+
+// ─── Server discovery ───────────────────────────────────────────────────────
+
+const PROJECT_DIR = path.resolve(import.meta.dirname, "../..");
+const SERVER_URL = "http://localhost:4096";
+const SANDBOX_NAME = "test-real-server";
+
+let serverAvailable = false;
+let projectID = null;
+let sandboxDir = null;
+const createdSessionIds = [];
+
+async function checkServer() {
+  try {
+    const encoded = encodeURIComponent(PROJECT_DIR);
+    const res = await fetch(`${SERVER_URL}/session?directory=${encoded}`);
+    if (!res.ok) return false;
+
+    // Also verify this project is known
+    const projRes = await fetch(`${SERVER_URL}/project`);
+    if (!projRes.ok) return false;
+    const projects = await projRes.json();
+    const match = projects.find((p) => p.worktree === PROJECT_DIR);
+    if (!match) return false;
+    projectID = match.id;
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function createSandbox() {
+  const encoded = encodeURIComponent(PROJECT_DIR);
+  const res = await fetch(
+    `${SERVER_URL}/experimental/worktree?directory=${encoded}`,
+    {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ name: SANDBOX_NAME }),
+    }
+  );
+  if (!res.ok) return null;
+  const wt = await res.json();
+  return wt.directory;
+}
+
+async function findOrCreateSandbox() {
+  const encoded = encodeURIComponent(PROJECT_DIR);
+  const res = await fetch(
+    `${SERVER_URL}/experimental/worktree?directory=${encoded}`
+  );
+  if (res.ok) {
+    const worktrees = await res.json();
+    const existing = worktrees.find((w) => w.endsWith(`/${SANDBOX_NAME}`));
+    if (existing) return existing;
+  }
+  return createSandbox();
+}
+
+async function archiveSession(id, directory) {
+  const encoded = encodeURIComponent(directory);
+  await fetch(`${SERVER_URL}/session/${id}?directory=${encoded}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ time: { archived: Date.now() } }),
+  }).catch(() => {});
+}
+
+// ─── Test suite ─────────────────────────────────────────────────────────────
+
+describe("real server: session directory behavior", { skip: false }, () => {
+  before(async () => {
+    serverAvailable = await checkServer();
+    if (!serverAvailable) return;
+    sandboxDir = await findOrCreateSandbox();
+  });
+
+  after(async () => {
+    if (!serverAvailable) return;
+    // Archive test sessions so they don't clutter the UI
+    for (const { id, directory } of createdSessionIds) {
+      await archiveSession(id, directory);
+    }
+  });
+
+  it("skip: no OpenCode server running", { skip: !false }, function () {
+    // This is a sentinel — replaced dynamically in before()
+  });
+
+  it("POST /session with sandbox dir → correct directory AND projectID", async (t) => {
+    if (!serverAvailable) return t.skip("no OpenCode server");
+    if (!sandboxDir) return t.skip("could not create sandbox");
+
+    const encoded = encodeURIComponent(sandboxDir);
+    const res = await fetch(`${SERVER_URL}/session?directory=${encoded}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+
+    assert.ok(res.ok, `POST /session should succeed (got ${res.status})`);
+    const session = await res.json();
+    createdSessionIds.push({ id: session.id, directory: sandboxDir });
+
+    // The session's directory must be the sandbox path — this is where the
+    // agent will operate. This was the bug: prior code created with the
+    // project dir, so the agent worked in the wrong directory.
+    assert.strictEqual(
+      session.directory,
+      sandboxDir,
+      "session.directory must be the sandbox path (where agent operates)"
+    );
+
+    // The projectID must match the parent repo's project — NOT 'global'.
+    // This disproves the assumption that led to 4 regression-fix cycles.
+    assert.strictEqual(
+      session.projectID,
+      projectID,
+      "session.projectID must match the parent repo (sandbox is a git worktree of the same repo)"
+    );
+  });
+
+  it("POST /session with project dir → project directory and same projectID", async (t) => {
+    if (!serverAvailable) return t.skip("no OpenCode server");
+
+    const encoded = encodeURIComponent(PROJECT_DIR);
+    const res = await fetch(`${SERVER_URL}/session?directory=${encoded}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+
+    assert.ok(res.ok, `POST /session should succeed (got ${res.status})`);
+    const session = await res.json();
+    createdSessionIds.push({ id: session.id, directory: PROJECT_DIR });
+
+    assert.strictEqual(
+      session.directory,
+      PROJECT_DIR,
+      "session.directory must be the project path"
+    );
+
+    assert.strictEqual(
+      session.projectID,
+      projectID,
+      "session.projectID must be the same whether created from sandbox or project dir"
+    );
+  });
+
+  it("PATCH /session/:id does NOT change session.directory", async (t) => {
+    if (!serverAvailable) return t.skip("no OpenCode server");
+    if (!sandboxDir) return t.skip("could not create sandbox");
+
+    // Create session with sandbox dir
+    const encoded = encodeURIComponent(sandboxDir);
+    const createRes = await fetch(
+      `${SERVER_URL}/session?directory=${encoded}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+      }
+    );
+    const session = await createRes.json();
+    createdSessionIds.push({ id: session.id, directory: sandboxDir });
+
+    // PATCH with project dir (this is what the "re-scoping" code tried to do)
+    const projectEncoded = encodeURIComponent(PROJECT_DIR);
+    const patchRes = await fetch(
+      `${SERVER_URL}/session/${session.id}?directory=${projectEncoded}`,
+      {
+        method: "PATCH",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ title: "patched-test" }),
+      }
+    );
+    assert.ok(patchRes.ok, `PATCH should succeed (got ${patchRes.status})`);
+    const patched = await patchRes.json();
+
+    // The directory must NOT have changed — PATCH only updates title/archived
+    assert.strictEqual(
+      patched.directory,
+      sandboxDir,
+      "PATCH must NOT change session.directory (it only updates title/archived)"
+    );
+
+    // Title should have been updated
+    assert.strictEqual(patched.title, "patched-test", "title should be updated");
+
+    // Read it back to be sure
+    const readRes = await fetch(
+      `${SERVER_URL}/session?directory=${encoded}`
+    );
+    const sessions = await readRes.json();
+    const readBack = sessions.find((s) => s.id === session.id);
+    assert.ok(readBack, "session should be readable from sandbox dir");
+    assert.strictEqual(
+      readBack.directory,
+      sandboxDir,
+      "read-back confirms directory unchanged after PATCH"
+    );
+  });
+
+  it("GET /session?directory filters by exact session.directory match", async (t) => {
+    if (!serverAvailable) return t.skip("no OpenCode server");
+    if (!sandboxDir) return t.skip("could not create sandbox");
+
+    // Create session with sandbox dir
+    const encoded = encodeURIComponent(sandboxDir);
+    const createRes = await fetch(
+      `${SERVER_URL}/session?directory=${encoded}`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({}),
+      }
+    );
+    const session = await createRes.json();
+    createdSessionIds.push({ id: session.id, directory: sandboxDir });
+
+    // Query with sandbox dir — should find it (exact match on session.directory)
+    const fromSandbox = await fetch(
+      `${SERVER_URL}/session?directory=${encoded}`
+    );
+    const sandboxSessions = await fromSandbox.json();
+    const foundFromSandbox = sandboxSessions.find((s) => s.id === session.id);
+    assert.ok(
+      foundFromSandbox,
+      "session should be found when querying with sandbox dir (exact match)"
+    );
+
+    // Query with project dir — should NOT find it because session.directory
+    // is the sandbox path, not the project path. The ?directory param on
+    // GET /session is both a project-routing param (middleware) AND an exact
+    // filter on session.directory (route handler). Since session.directory
+    // is the sandbox path, it won't match the project path filter.
+    // This is actually correct behavior: it means session reuse via
+    // findReusableSession naturally isolates sandbox sessions from project
+    // sessions — each sandbox only sees its own sessions.
+    const projectEncoded = encodeURIComponent(PROJECT_DIR);
+    const fromProject = await fetch(
+      `${SERVER_URL}/session?directory=${projectEncoded}`
+    );
+    const projectSessions = await fromProject.json();
+    const foundFromProject = projectSessions.find((s) => s.id === session.id);
+    assert.ok(
+      !foundFromProject,
+      "session should NOT appear in project dir listing (directory filter is an exact match on session.directory)"
+    );
+  });
+});

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 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");
+    // Session creation uses the worktree directory (sets actual working dir)
+    // PATCH with project dir handles UI scoping (best-effort)
+    assert.strictEqual(sessionDirectory, "/worktree/pr-42", "Session should be created with worktree as working 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 project directory (for correct projectID scoping)
-    assert.strictEqual(sessionDirectory, "/proj", "Session should be scoped to project directory");
+    // Session creation uses the worktree directory (sets actual working dir)
+    assert.strictEqual(sessionDirectory, existingWorktreeDir, "Session should be created with worktree as working directory");
   });
 
   it("skips session reuse when working in a worktree", async () => {
@@ -674,10 +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 scoped to the project directory
+    // Should create a new session with the worktree as working directory
     assert.ok(sessionCreated, "Should create a new session");
-    assert.strictEqual(sessionCreateDirectory, "/proj",
-      "New session should be scoped to project directory");
+    assert.strictEqual(sessionCreateDirectory, existingWorktreeDir,
+      "New session should be created with worktree as working directory");
   });
 });
 
@@ -1032,6 +1032,10 @@ describe("session creation invariants", () => {
         calls.sessionCreateDirectory = u.searchParams.get("directory");
         calls.sessionCreated = true;
       }
+      if (method === "PATCH" && /^\/session\/[^/]+$/.test(u.pathname)) {
+        calls.patchDirectory = u.searchParams.get("directory");
+        calls.patchSessionId = u.pathname.split("/")[2];
+      }
       if (method === "GET" && u.pathname === "/session") {
         calls.sessionListQueried = true;
       }
@@ -1039,11 +1043,11 @@ describe("session creation invariants", () => {
     };
   }
 
-  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
+  it("session created with worktree directory, message sent to worktree", async () => {
+    // POST /session must use the worktree directory — this sets session.directory
+    // and determines where the agent operates. OpenCode derives the correct
+    // projectID from the git root (sandbox worktrees share the same root commit).
+    // Verified against a real server in test/integration/real-server.test.js.
 
     const calls = {};
 
@@ -1069,22 +1073,18 @@ describe("session creation invariants", () => {
 
     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");
+    // Session creation uses the worktree directory
+    assert.strictEqual(calls.sessionCreateDirectory, "/worktree/pr-99",
+      "POST /session must use workingDirectory so agent operates in worktree");
 
-    // Invariant B: message uses the worktree directory
+    // Message also 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");
+      "POST /message must use workingDirectory for correct file operations");
   });
 
-  it("invariant A+B hold when reprocessing with existing_directory", async () => {
+  it("reprocessing uses existing worktree directory for session and message", async () => {
     // When reprocessing an item (e.g., new feedback on a PR), the existing worktree
-    // directory is passed. The same invariants must still hold.
+    // directory is passed. Session creation and messages must both use it.
 
     const calls = {};
 
@@ -1111,13 +1111,13 @@ describe("session creation invariants", () => {
 
     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");
+    // Session creation uses the existing worktree directory
+    assert.strictEqual(calls.sessionCreateDirectory, "/worktree/calm-wizard",
+      "POST /session must use workingDirectory for correct session directory");
 
-    // Invariant B: message uses the existing worktree directory
+    // 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");
+      "POST /message must use workingDirectory for correct file operations");
   });
 
   it("invariant C: second PR in same project gets its own session", async () => {

package/test/unit/actions.test.js

@@ -982,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 project directory (for correct projectID scoping)
-      assert.strictEqual(sessionDirectory, '/data/proj', 
-        'Session creation should use project directory, not worktree');
+      // Session creation uses worktree directory (sets actual working dir)
+      assert.strictEqual(sessionDirectory, '/data/worktree/calm-wizard', 
+        'Session creation should use worktree as working directory');
       // Result directory is the worktree (where file operations happen)
       assert.strictEqual(result.directory, '/data/worktree/calm-wizard',
         'Result should include worktree directory');
@@ -1043,11 +1043,12 @@ Check for bugs and security issues.`;
       assert.ok(messageUrl.includes('%2Fpath%2Fto%2Fproject'), 'Message URL should include encoded directory path');
     });
 
-    test('uses projectDirectory for session creation, working directory for messages', async () => {
+    test('uses workingDirectory for session creation, no PATCH when no title', async () => {
       const { createSessionViaApi } = await import('../../service/actions.js');
       
       const mockSessionId = 'ses_test_proj';
       let createUrl = null;
+      let patchCalled = false;
       let messageUrl = null;
       
       const mockFetch = async (url, opts) => {
@@ -1058,6 +1059,11 @@ Check for bugs and security issues.`;
           return { ok: true, json: async () => ({ id: mockSessionId }) };
         }
         
+        if (opts?.method === 'PATCH') {
+          patchCalled = true;
+          return { ok: true, json: async () => ({}) };
+        }
+        
         if (urlObj.pathname.includes('/message') && opts?.method === 'POST') {
           messageUrl = url;
           return { ok: true, json: async () => ({ success: true }) };
@@ -1076,13 +1082,17 @@ Check for bugs and security issues.`;
         { fetch: mockFetch }
       );
       
-      // 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');
+      // Session creation should use the worktree directory
+      assert.ok(createUrl.includes('worktree'), 
+        'Session creation should use workingDirectory (worktree path)');
+      assert.ok(createUrl.includes('pr-415'), 
+        'Session creation should use workingDirectory (worktree path)');
+      
+      // No PATCH when no title is provided — no "project re-scoping" needed
+      assert.strictEqual(patchCalled, false, 
+        'PATCH should NOT be called when no title (no project re-scoping needed)');
       
-      // Message should use the working directory (for file operations in the worktree)
+      // Message should use the working directory
       assert.ok(messageUrl.includes('worktree'), 
         'Message should use the worktree working directory');
       assert.ok(messageUrl.includes('pr-415'), 

package/test/unit/logs.test.js

@@ -0,0 +1,120 @@
+/**
+ * Tests for the `logs` CLI command.
+ *
+ * The command prints the debug log path and optionally tails/follows it.
+ * Flags:
+ *   --path     Print only the log file path
+ *   --lines N  Print last N lines (default 50)
+ *   --follow   Follow the log file (tail -f)
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert";
+import { spawnSync } from "child_process";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  writeFileSync,
+  mkdirSync,
+  rmSync,
+  existsSync,
+} from "fs";
+import { tmpdir } from "os";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CLI = join(__dirname, "..", "..", "bin", "opencode-pilot");
+
+// Helper: run opencode-pilot with overridden log path via env
+function runLogs(args = [], env = {}) {
+  return spawnSync(process.execPath, [CLI, "logs", ...args], {
+    encoding: "utf8",
+    timeout: 5000,
+    env: { ...process.env, ...env },
+  });
+}
+
+describe("logs command", () => {
+  let tmpDir;
+  let logFile;
+
+  // Create a temp log file for each test group
+  function setupLogFile(lines = []) {
+    tmpDir = join(tmpdir(), `opencode-pilot-test-${Date.now()}`);
+    mkdirSync(tmpDir, { recursive: true });
+    logFile = join(tmpDir, "debug.log");
+    if (lines.length) {
+      writeFileSync(logFile, lines.join("\n") + "\n");
+    }
+    return logFile;
+  }
+
+  function cleanup() {
+    if (tmpDir && existsSync(tmpDir)) {
+      rmSync(tmpDir, { recursive: true, force: true });
+    }
+  }
+
+  describe("--path flag", () => {
+    test("prints the log file path", () => {
+      const path = setupLogFile();
+      const result = runLogs(["--path"], { PILOT_LOG_PATH: path });
+      cleanup();
+      assert.strictEqual(result.status, 0);
+      assert.match(result.stdout.trim(), /debug\.log/);
+    });
+
+    test("prints path even when log file does not exist", () => {
+      const nonExistentPath = join(tmpdir(), "no-such-dir", "debug.log");
+      const result = runLogs(["--path"], { PILOT_LOG_PATH: nonExistentPath });
+      assert.strictEqual(result.status, 0);
+      assert.match(result.stdout.trim(), /debug\.log/);
+    });
+  });
+
+  describe("default output (last N lines)", () => {
+    test("prints last 50 lines by default when log exists", () => {
+      const lines = Array.from({ length: 60 }, (_, i) => `line ${i + 1}`);
+      const path = setupLogFile(lines);
+      const result = runLogs([], { PILOT_LOG_PATH: path });
+      cleanup();
+      assert.strictEqual(result.status, 0);
+      // Should contain lines 11-60 (last 50)
+      assert.match(result.stdout, /line 60/);
+      // Lines 1-10 should be excluded (only last 50 of 60 are shown)
+      assert.doesNotMatch(result.stdout, /^line [1-9]\b/m);
+    });
+
+    test("--lines N prints last N lines", () => {
+      const lines = Array.from({ length: 20 }, (_, i) => `entry ${i + 1}`);
+      const path = setupLogFile(lines);
+      const result = runLogs(["--lines", "5"], { PILOT_LOG_PATH: path });
+      cleanup();
+      assert.strictEqual(result.status, 0);
+      assert.match(result.stdout, /entry 20/);
+      assert.doesNotMatch(result.stdout, /entry 1\n/);
+    });
+
+    test("exits 0 with informational message when log does not exist", () => {
+      const nonExistentPath = join(
+        tmpdir(),
+        `no-log-${Date.now()}`,
+        "debug.log"
+      );
+      const result = runLogs([], { PILOT_LOG_PATH: nonExistentPath });
+      assert.strictEqual(result.status, 0);
+      assert.match(result.stdout, /no log/i);
+    });
+  });
+
+  describe("help text", () => {
+    test("opencode-pilot help includes logs command", () => {
+      const result = spawnSync(process.execPath, [CLI, "help"], {
+        encoding: "utf8",
+        timeout: 5000,
+      });
+      assert.strictEqual(result.status, 0);
+      assert.match(result.stdout, /logs/);
+    });
+  });
+});