opencastle 0.11.0 → 0.13.0

package/src/cli/convoy/store.ts

@@ -0,0 +1,308 @@
+import { DatabaseSync } from 'node:sqlite'
+import type {
+  ConvoyRecord,
+  ConvoyStatus,
+  TaskRecord,
+  ConvoyTaskStatus,
+  WorkerRecord,
+  WorkerStatus,
+  EventRecord,
+} from './types.js'
+
+const SCHEMA_VERSION = 1
+
+export interface ConvoyStore {
+  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at'>): void
+  getConvoy(id: string): ConvoyRecord | undefined
+  updateConvoyStatus(
+    id: string,
+    status: ConvoyStatus,
+    extra?: { started_at?: string; finished_at?: string },
+  ): void
+  insertTask(
+    record: Omit<
+      TaskRecord,
+      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at'
+    >,
+  ): void
+  getTask(id: string, convoyId: string): TaskRecord | undefined
+  getTasksByConvoy(convoyId: string): TaskRecord[]
+  updateTaskStatus(
+    id: string,
+    convoyId: string,
+    status: ConvoyTaskStatus,
+    extra?: Partial<
+      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries'>
+    >,
+  ): void
+  getReadyTasks(convoyId: string): TaskRecord[]
+  insertWorker(record: Omit<WorkerRecord, 'finished_at' | 'last_heartbeat'>): void
+  getWorker(id: string): WorkerRecord | undefined
+  updateWorkerStatus(
+    id: string,
+    status: WorkerStatus,
+    extra?: Partial<Pick<WorkerRecord, 'finished_at' | 'last_heartbeat' | 'pid'>>,
+  ): void
+  insertEvent(record: Omit<EventRecord, 'id'>): void
+  getEvents(convoyId: string): EventRecord[]
+  withTransaction<T>(fn: () => T): T
+  close(): void
+}
+
+class ConvoyStoreImpl implements ConvoyStore {
+  private db: DatabaseSync
+
+  constructor(dbPath: string) {
+    this.db = new DatabaseSync(dbPath)
+    this.db.exec('PRAGMA journal_mode = WAL')
+    this.db.exec('PRAGMA synchronous = NORMAL')
+    this.initSchema()
+  }
+
+  private initSchema(): void {
+    const row = this.db.prepare('PRAGMA user_version').get() as { user_version: number }
+    if (row.user_version === 0) {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS convoy (
+          id          TEXT PRIMARY KEY,
+          name        TEXT NOT NULL,
+          spec_hash   TEXT NOT NULL,
+          status      TEXT NOT NULL DEFAULT 'pending',
+          branch      TEXT,
+          created_at  TEXT NOT NULL,
+          started_at  TEXT,
+          finished_at TEXT,
+          spec_yaml   TEXT NOT NULL
+        );
+
+        CREATE TABLE IF NOT EXISTS task (
+          id          TEXT PRIMARY KEY,
+          convoy_id   TEXT NOT NULL REFERENCES convoy(id),
+          phase       INTEGER NOT NULL,
+          prompt      TEXT NOT NULL,
+          agent       TEXT NOT NULL DEFAULT 'developer',
+          model       TEXT,
+          timeout_ms  INTEGER NOT NULL DEFAULT 1800000,
+          status      TEXT NOT NULL DEFAULT 'pending',
+          worker_id   TEXT,
+          worktree    TEXT,
+          output      TEXT,
+          exit_code   INTEGER,
+          started_at  TEXT,
+          finished_at TEXT,
+          retries     INTEGER NOT NULL DEFAULT 0,
+          max_retries INTEGER NOT NULL DEFAULT 1,
+          files       TEXT,
+          depends_on  TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS worker (
+          id             TEXT PRIMARY KEY,
+          task_id        TEXT REFERENCES task(id),
+          adapter        TEXT NOT NULL,
+          pid            INTEGER,
+          session_id     TEXT,
+          status         TEXT NOT NULL DEFAULT 'spawned',
+          worktree       TEXT,
+          created_at     TEXT NOT NULL,
+          finished_at    TEXT,
+          last_heartbeat TEXT
+        );
+
+        CREATE TABLE IF NOT EXISTS event (
+          id         INTEGER PRIMARY KEY AUTOINCREMENT,
+          convoy_id  TEXT REFERENCES convoy(id),
+          task_id    TEXT,
+          worker_id  TEXT,
+          type       TEXT NOT NULL,
+          data       TEXT,
+          created_at TEXT NOT NULL
+        );
+      `)
+      this.db.exec(`PRAGMA user_version = ${SCHEMA_VERSION}`)
+    }
+  }
+
+  insertConvoy(record: Omit<ConvoyRecord, 'started_at' | 'finished_at'>): void {
+    this.db
+      .prepare(
+        `INSERT INTO convoy (id, name, spec_hash, status, branch, created_at, started_at, finished_at, spec_yaml)
+         VALUES (:id, :name, :spec_hash, :status, :branch, :created_at, NULL, NULL, :spec_yaml)`,
+      )
+      .run(record)
+  }
+
+  getConvoy(id: string): ConvoyRecord | undefined {
+    return this.db
+      .prepare('SELECT * FROM convoy WHERE id = :id')
+      .get({ id }) as ConvoyRecord | undefined
+  }
+
+  updateConvoyStatus(
+    id: string,
+    status: ConvoyStatus,
+    extra?: { started_at?: string; finished_at?: string },
+  ): void {
+    const sets = ['status = :status']
+    const params: Record<string, string | null> = { id, status }
+
+    if (extra?.started_at !== undefined) {
+      sets.push('started_at = :started_at')
+      params.started_at = extra.started_at
+    }
+    if (extra?.finished_at !== undefined) {
+      sets.push('finished_at = :finished_at')
+      params.finished_at = extra.finished_at
+    }
+
+    this.db.prepare(`UPDATE convoy SET ${sets.join(', ')} WHERE id = :id`).run(params)
+  }
+
+  insertTask(
+    record: Omit<
+      TaskRecord,
+      'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at'
+    >,
+  ): void {
+    this.db
+      .prepare(
+        `INSERT INTO task
+           (id, convoy_id, phase, prompt, agent, model, timeout_ms, status,
+            worker_id, worktree, output, exit_code, started_at, finished_at,
+            retries, max_retries, files, depends_on)
+         VALUES
+           (:id, :convoy_id, :phase, :prompt, :agent, :model, :timeout_ms, :status,
+            NULL, NULL, NULL, NULL, NULL, NULL,
+            :retries, :max_retries, :files, :depends_on)`,
+      )
+      .run(record)
+  }
+
+  getTask(id: string, convoyId: string): TaskRecord | undefined {
+    return this.db
+      .prepare('SELECT * FROM task WHERE id = :id AND convoy_id = :convoy_id')
+      .get({ id, convoy_id: convoyId }) as TaskRecord | undefined
+  }
+
+  getTasksByConvoy(convoyId: string): TaskRecord[] {
+    return this.db
+      .prepare('SELECT * FROM task WHERE convoy_id = :convoy_id ORDER BY phase, id')
+      .all({ convoy_id: convoyId }) as unknown as TaskRecord[]
+  }
+
+  updateTaskStatus(
+    id: string,
+    convoyId: string,
+    status: ConvoyTaskStatus,
+    extra?: Partial<
+      Pick<TaskRecord, 'worker_id' | 'worktree' | 'output' | 'exit_code' | 'started_at' | 'finished_at' | 'retries'>
+    >,
+  ): void {
+    const sets = ['status = :status']
+    const params: Record<string, string | number | null> = { id, convoy_id: convoyId, status }
+    const extraFields = ['worker_id', 'worktree', 'output', 'exit_code', 'started_at', 'finished_at', 'retries'] as const
+
+    if (extra) {
+      for (const field of extraFields) {
+        if (field in extra && extra[field] !== undefined) {
+          sets.push(`${field} = :${field}`)
+          params[field] = extra[field] as string | number | null
+        }
+      }
+    }
+
+    this.db
+      .prepare(`UPDATE task SET ${sets.join(', ')} WHERE id = :id AND convoy_id = :convoy_id`)
+      .run(params)
+  }
+
+  getReadyTasks(convoyId: string): TaskRecord[] {
+    const allTasks = this.getTasksByConvoy(convoyId)
+    const doneTaskIds = new Set(allTasks.filter(t => t.status === 'done').map(t => t.id))
+
+    return allTasks.filter(task => {
+      if (task.status !== 'pending') return false
+      if (!task.depends_on) return true
+      const deps = JSON.parse(task.depends_on) as string[]
+      return deps.length === 0 || deps.every(depId => doneTaskIds.has(depId))
+    })
+  }
+
+  insertWorker(record: Omit<WorkerRecord, 'finished_at' | 'last_heartbeat'>): void {
+    this.db
+      .prepare(
+        `INSERT INTO worker
+           (id, task_id, adapter, pid, session_id, status, worktree, created_at,
+            finished_at, last_heartbeat)
+         VALUES
+           (:id, :task_id, :adapter, :pid, :session_id, :status, :worktree, :created_at,
+            NULL, NULL)`,
+      )
+      .run(record)
+  }
+
+  getWorker(id: string): WorkerRecord | undefined {
+    return this.db
+      .prepare('SELECT * FROM worker WHERE id = :id')
+      .get({ id }) as WorkerRecord | undefined
+  }
+
+  updateWorkerStatus(
+    id: string,
+    status: WorkerStatus,
+    extra?: Partial<Pick<WorkerRecord, 'finished_at' | 'last_heartbeat' | 'pid'>>,
+  ): void {
+    const sets = ['status = :status']
+    const params: Record<string, string | number | null> = { id, status }
+
+    if (extra?.finished_at !== undefined) {
+      sets.push('finished_at = :finished_at')
+      params.finished_at = extra.finished_at
+    }
+    if (extra?.last_heartbeat !== undefined) {
+      sets.push('last_heartbeat = :last_heartbeat')
+      params.last_heartbeat = extra.last_heartbeat
+    }
+    if (extra?.pid !== undefined) {
+      sets.push('pid = :pid')
+      params.pid = extra.pid
+    }
+
+    this.db.prepare(`UPDATE worker SET ${sets.join(', ')} WHERE id = :id`).run(params)
+  }
+
+  insertEvent(record: Omit<EventRecord, 'id'>): void {
+    this.db
+      .prepare(
+        `INSERT INTO event (convoy_id, task_id, worker_id, type, data, created_at)
+         VALUES (:convoy_id, :task_id, :worker_id, :type, :data, :created_at)`,
+      )
+      .run(record)
+  }
+
+  getEvents(convoyId: string): EventRecord[] {
+    return this.db
+      .prepare('SELECT * FROM event WHERE convoy_id = :convoy_id ORDER BY id')
+      .all({ convoy_id: convoyId }) as unknown as EventRecord[]
+  }
+
+  withTransaction<T>(fn: () => T): T {
+    this.db.exec('BEGIN')
+    try {
+      const result = fn()
+      this.db.exec('COMMIT')
+      return result
+    } catch (err) {
+      this.db.exec('ROLLBACK')
+      throw err
+    }
+  }
+
+  close(): void {
+    this.db.close()
+  }
+}
+
+export function createConvoyStore(dbPath: string): ConvoyStore {
+  return new ConvoyStoreImpl(dbPath)
+}

package/src/cli/convoy/types.ts

@@ -0,0 +1,68 @@
+export type ConvoyStatus = 'pending' | 'running' | 'done' | 'failed' | 'gate-failed'
+
+export type ConvoyTaskStatus =
+  | 'pending'
+  | 'assigned'
+  | 'running'
+  | 'done'
+  | 'failed'
+  | 'timed-out'
+  | 'skipped'
+
+export type WorkerStatus = 'spawned' | 'running' | 'done' | 'failed' | 'killed'
+
+export interface ConvoyRecord {
+  id: string
+  name: string
+  spec_hash: string
+  status: ConvoyStatus
+  branch: string | null
+  created_at: string
+  started_at: string | null
+  finished_at: string | null
+  spec_yaml: string
+}
+
+export interface TaskRecord {
+  id: string
+  convoy_id: string
+  phase: number
+  prompt: string
+  agent: string
+  model: string | null
+  timeout_ms: number
+  status: ConvoyTaskStatus
+  worker_id: string | null
+  worktree: string | null
+  output: string | null
+  exit_code: number | null
+  started_at: string | null
+  finished_at: string | null
+  retries: number
+  max_retries: number
+  files: string | null
+  depends_on: string | null
+}
+
+export interface WorkerRecord {
+  id: string
+  task_id: string | null
+  adapter: string
+  pid: number | null
+  session_id: string | null
+  status: WorkerStatus
+  worktree: string | null
+  created_at: string
+  finished_at: string | null
+  last_heartbeat: string | null
+}
+
+export interface EventRecord {
+  id?: number
+  convoy_id: string | null
+  task_id: string | null
+  worker_id: string | null
+  type: string
+  data: string | null
+  created_at: string
+}

package/src/cli/convoy/worktree.test.ts

@@ -0,0 +1,177 @@
+import { mkdtempSync, rmSync, realpathSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { execFile as execFileCb } from 'node:child_process'
+import { promisify } from 'node:util'
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { createWorktreeManager } from './worktree.js'
+import type { WorktreeManager } from './worktree.js'
+
+const execFile = promisify(execFileCb)
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+let tmpDir: string
+let manager: WorktreeManager
+
+async function initGitRepo(dir: string): Promise<void> {
+  await execFile('git', ['init'], { cwd: dir })
+  await execFile('git', ['config', 'user.email', 'test@test.com'], { cwd: dir })
+  await execFile('git', ['config', 'user.name', 'Test User'], { cwd: dir })
+  await execFile('git', ['commit', '--allow-empty', '-m', 'Initial commit'], { cwd: dir })
+}
+
+beforeEach(async () => {
+  tmpDir = realpathSync(mkdtempSync(join(tmpdir(), 'convoy-worktree-test-')))
+  await initGitRepo(tmpDir)
+  manager = createWorktreeManager(tmpDir)
+})
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+// ── create ────────────────────────────────────────────────────────────────────
+
+describe('create', () => {
+  it('creates a worktree and returns its absolute path', async () => {
+    const worktreePath = await manager.create('worker1', 'HEAD')
+    expect(worktreePath).toBe(join(tmpDir, '.opencastle', 'worktrees', 'worker1'))
+  })
+
+  it('creates the .opencastle/worktrees directory when it does not exist', async () => {
+    const { existsSync } = await import('node:fs')
+    const worktreePath = await manager.create('worker1', 'HEAD')
+    expect(existsSync(worktreePath)).toBe(true)
+  })
+
+  it('creates the new branch in the worktree', async () => {
+    await manager.create('worker1', 'HEAD')
+    const { stdout } = await execFile('git', ['branch', '--list', 'convoy-worker1'], { cwd: tmpDir })
+    // git prefixes branches checked out in a worktree with '+ '
+    expect(stdout.trim().replace(/^[*+]\s+/, '')).toBe('convoy-worker1')
+  })
+
+  it('throws when featureBranch does not exist', async () => {
+    await expect(manager.create('worker1', 'nonexistent-branch')).rejects.toThrow()
+  })
+
+  it('throws when workerId is already in use', async () => {
+    await manager.create('worker1', 'HEAD')
+    await expect(manager.create('worker1', 'HEAD')).rejects.toThrow()
+  })
+
+  it('throws for workerId with path traversal characters', async () => {
+    await expect(manager.create('../escape', 'HEAD')).rejects.toThrow(/Invalid workerId/)
+  })
+
+  it('throws for workerId with slashes', async () => {
+    await expect(manager.create('a/b', 'HEAD')).rejects.toThrow(/Invalid workerId/)
+  })
+})
+
+// ── remove ────────────────────────────────────────────────────────────────────
+
+describe('remove', () => {
+  it('removes the worktree so it no longer appears in list()', async () => {
+    const path = await manager.create('worker1', 'HEAD')
+    await manager.remove(path)
+    const worktrees = await manager.list()
+    expect(worktrees).toHaveLength(0)
+  })
+
+  it('deletes the convoy branch after removing the worktree', async () => {
+    const path = await manager.create('worker1', 'HEAD')
+    await manager.remove(path)
+    const { stdout } = await execFile('git', ['branch', '--list', 'convoy-worker1'], { cwd: tmpDir })
+    expect(stdout.trim()).toBe('')
+  })
+
+  it('is idempotent — does not throw for a non-existent worktree path', async () => {
+    const nonExistent = join(tmpDir, '.opencastle', 'worktrees', 'ghost')
+    await expect(manager.remove(nonExistent)).resolves.toBeUndefined()
+  })
+
+  it('re-throws git errors that are not "not a working tree"', async () => {
+    const path = await manager.create('worker1', 'HEAD')
+    // Lock the worktree so that single --force removal fails
+    await execFile('git', ['worktree', 'lock', path], { cwd: tmpDir })
+    await expect(manager.remove(path)).rejects.toThrow()
+    // Cleanup: unlock and remove manually
+    await execFile('git', ['worktree', 'unlock', path], { cwd: tmpDir })
+  })
+
+  it('throws when path is outside the managed worktrees directory', async () => {
+    await expect(manager.remove('/some/arbitrary/path')).rejects.toThrow(
+      /outside the managed worktrees directory/,
+    )
+  })
+})
+
+// ── list ──────────────────────────────────────────────────────────────────────
+
+describe('list', () => {
+  it('returns an empty array when no convoy worktrees exist', async () => {
+    const worktrees = await manager.list()
+    expect(worktrees).toHaveLength(0)
+  })
+
+  it('does not include the main worktree', async () => {
+    const worktrees = await manager.list()
+    for (const wt of worktrees) {
+      expect(wt.path).toContain('.opencastle/worktrees')
+    }
+  })
+
+  it('returns the correct WorktreeInfo for a created worktree', async () => {
+    await manager.create('worker1', 'HEAD')
+    const worktrees = await manager.list()
+    expect(worktrees).toHaveLength(1)
+    expect(worktrees[0].path).toBe(join(tmpDir, '.opencastle', 'worktrees', 'worker1'))
+    expect(worktrees[0].branch).toBe('refs/heads/convoy-worker1')
+    expect(worktrees[0].head).toMatch(/^[0-9a-f]{40}$/)
+  })
+
+  it('returns multiple worktrees when several have been created', async () => {
+    await manager.create('worker1', 'HEAD')
+    await manager.create('worker2', 'HEAD')
+    const worktrees = await manager.list()
+    expect(worktrees).toHaveLength(2)
+    const paths = worktrees.map(w => w.path)
+    expect(paths).toContain(join(tmpDir, '.opencastle', 'worktrees', 'worker1'))
+    expect(paths).toContain(join(tmpDir, '.opencastle', 'worktrees', 'worker2'))
+  })
+
+  it('handles detached HEAD worktrees by returning empty branch string', async () => {
+    // git worktree list --porcelain outputs 'detached' (not 'branch refs/...') for
+    // detached-HEAD worktrees — this exercises the else-if fallthrough in parseWorktreeList
+    const { existsSync, mkdirSync } = await import('node:fs')
+    const detachedPath = join(tmpDir, '.opencastle', 'worktrees', 'detached-test')
+    if (!existsSync(join(tmpDir, '.opencastle', 'worktrees'))) {
+      mkdirSync(join(tmpDir, '.opencastle', 'worktrees'), { recursive: true })
+    }
+    const { stdout: sha } = await execFile('git', ['rev-parse', 'HEAD'], { cwd: tmpDir })
+    await execFile('git', ['worktree', 'add', '--detach', detachedPath, sha.trim()], { cwd: tmpDir })
+    const worktrees = await manager.list()
+    const detached = worktrees.find(w => w.path === detachedPath)
+    expect(detached).toBeDefined()
+    expect(detached!.branch).toBe('')
+    expect(detached!.head).toMatch(/^[0-9a-f]{40}$/)
+  })
+})
+
+// ── removeAll ─────────────────────────────────────────────────────────────────
+
+describe('removeAll', () => {
+  it('removes all convoy worktrees', async () => {
+    await manager.create('worker1', 'HEAD')
+    await manager.create('worker2', 'HEAD')
+    await manager.removeAll()
+    const worktrees = await manager.list()
+    expect(worktrees).toHaveLength(0)
+  })
+
+  it('is a no-op when no convoy worktrees exist', async () => {
+    await expect(manager.removeAll()).resolves.toBeUndefined()
+  })
+})

package/src/cli/convoy/worktree.ts

@@ -0,0 +1,116 @@
+import { execFile as execFileCb } from 'node:child_process'
+import { mkdir } from 'node:fs/promises'
+import { realpathSync } from 'node:fs'
+import { join, basename, resolve, sep } from 'node:path'
+import { promisify } from 'node:util'
+
+const execFile = promisify(execFileCb)
+
+export interface WorktreeInfo {
+  path: string
+  branch: string
+  head: string
+}
+
+export interface WorktreeManager {
+  create(workerId: string, featureBranch: string): Promise<string>
+  remove(worktreePath: string): Promise<void>
+  list(): Promise<WorktreeInfo[]>
+  removeAll(): Promise<void>
+}
+
+export function createWorktreeManager(basePath: string): WorktreeManager {
+  const resolvedBase = realpathSync(resolve(basePath))
+  const worktreesDir = join(resolvedBase, '.opencastle', 'worktrees')
+
+  async function create(workerId: string, featureBranch: string): Promise<string> {
+    if (!/^[a-zA-Z0-9_-]+$/.test(workerId)) {
+      throw new Error(
+        `Invalid workerId "${workerId}": must only contain alphanumeric characters, hyphens, and underscores`,
+      )
+    }
+    const worktreePath = join(worktreesDir, workerId)
+    await mkdir(worktreesDir, { recursive: true })
+    await execFile(
+      'git',
+      ['worktree', 'add', worktreePath, '-b', `convoy-${workerId}`, featureBranch],
+      { cwd: resolvedBase },
+    )
+    return worktreePath
+  }
+
+  async function remove(worktreePath: string): Promise<void> {
+    let resolved: string
+    try {
+      resolved = realpathSync(worktreePath)
+    } catch {
+      resolved = resolve(worktreePath)
+    }
+    if (!resolved.startsWith(worktreesDir + sep)) {
+      throw new Error(`Path "${worktreePath}" is outside the managed worktrees directory`)
+    }
+    const workerId = basename(resolved)
+    try {
+      await execFile('git', ['worktree', 'remove', resolved, '--force'], {
+        cwd: resolvedBase,
+      })
+    } catch (err) {
+      const stderr = (err as { stderr?: string }).stderr ?? ''
+      if (stderr.includes('is not a working tree')) {
+        return
+      }
+      throw err
+    }
+    try {
+      await execFile('git', ['branch', '-D', `convoy-${workerId}`], { cwd: resolvedBase })
+    } catch {
+      // Branch may already be deleted — ignore
+    }
+  }
+
+
+  async function list(): Promise<WorktreeInfo[]> {
+    const { stdout } = await execFile('git', ['worktree', 'list', '--porcelain'], {
+      cwd: resolvedBase,
+    })
+    return parseWorktreeList(stdout, worktreesDir)
+  }
+
+  async function removeAll(): Promise<void> {
+    const worktrees = await list()
+    for (const wt of worktrees) {
+      await remove(wt.path)
+    }
+  }
+
+  return { create, remove, list, removeAll }
+}
+
+function parseWorktreeList(output: string, worktreesDir: string): WorktreeInfo[] {
+  const results: WorktreeInfo[] = []
+  const blocks = output.trim().split(/\n\n+/).filter(Boolean)
+
+  for (const block of blocks) {
+    const lines = block.split('\n')
+    let path = ''
+    let head = ''
+    let branch = ''
+
+    for (const line of lines) {
+      if (line.startsWith('worktree ')) {
+        path = line.slice('worktree '.length)
+      } else if (line.startsWith('HEAD ')) {
+        head = line.slice('HEAD '.length)
+      } else if (line.startsWith('branch ')) {
+        branch = line.slice('branch '.length)
+      }
+    }
+
+    // Only include worktrees that live under .opencastle/worktrees/
+    if (path.startsWith(worktreesDir + sep)) {
+      results.push({ path, branch, head })
+    }
+  }
+
+  return results
+}

package/src/cli/run/adapters/claude-code.ts

@@ -38,7 +38,7 @@ export async function execute(task: Task, options: ExecuteOptions = {}): Promise
     const proc = spawn('claude', args, {
       stdio: ['ignore', 'pipe', 'pipe'],
       env: { ...process.env },
-      cwd: process.cwd(),
+      cwd: options?.cwd ?? process.cwd(),
     })
 
     let stdout = ''

package/src/cli/run/adapters/copilot.ts

@@ -61,6 +61,11 @@ async function getClient(): Promise<CopilotClientType> {
  *   - Streaming enabled in verbose mode for live output
  */
 export async function execute(task: Task, options: ExecuteOptions = {}): Promise<ExecuteResult> {
+  // NOTE: The Copilot SDK CopilotClient is a shared singleton. Per-task cwd
+  // isolation requires SDK support for per-session workingDirectory, which is
+  // not yet available. When running in convoy mode with worktrees, prefer
+  // subprocess-based adapters (claude-code, cursor) that support options.cwd
+  // natively. Copilot SDK per-session cwd support is tracked for Phase 3.
   let prompt = `You are a ${task.agent}. ${task.prompt}`
 
   if (task.files && task.files.length > 0) {