opencastle 0.27.1 → 0.27.2

package/src/cli/convoy/TELEMETRY.md

@@ -0,0 +1,203 @@
+# Convoy Telemetry Model
+
+How Convoy concepts map to [OpenTelemetry](https://opentelemetry.io/) semantics.
+
+## Conceptual Mapping
+
+| Convoy Concept | OTel Concept | ID Field | Description |
+|---------------|-------------|----------|-------------|
+| **Convoy** | Trace | `convoy_id` → `trace_id` | A single execution run of a `.convoy.yml` spec |
+| **Task** | Span | `task_id` → `span_id` | One unit of work within a convoy |
+| **TaskStep** | Sub-span | `step_index` | Sequential steps within a multi-step task |
+| **Event** | Log / SpanEvent | `type` | Structured occurrence during execution |
+| **Metrics** | Derived aggregates | — | Computed from events (tokens, cost, duration) |
+
+### ID Correlation
+
+```
+trace_id  = convoy_id   (globally unique, set at convoy creation)
+span_id   = task_id      (unique within convoy, from spec)
+worker_id = worker trace (ephemeral, tied to adapter process)
+```
+
+Every event carries `convoy_id`, `task_id`, and `worker_id` (all nullable) to enable correlation across the trace hierarchy.
+
+## Storage
+
+- **Primary**: SQLite (`convoy.db`) — durable, queryable, crash-safe
+- **Supplementary**: NDJSON (`convoy-events.ndjson`) — append-only log for streaming/grep
+
+SQLite is the source of truth. NDJSON is replayed from SQLite on crash recovery via `recoverNdjson()`.
+
+### Write Strategy (v1)
+
+NDJSON writes use synchronous `appendFileSync` + `fsyncSync` per event. This ensures crash-safety — every event is durable before the engine proceeds. Trade-offs:
+
+- **Latency**: ~1-2ms per event (sync I/O). For convoys with <10,000 events this is negligible.
+- **Throughput**: Not suitable for >10,000 events/second workloads.
+- **Crash-safety**: Every event is fsynced before the engine continues, so a crash never loses the last event.
+
+An async buffered writer is deferred as an optimization for Phase 5 if profiling shows sync writes become a bottleneck.
+
+## Event Type Reference
+
+All 39 canonical event types emitted by the convoy engine.
+
+### Convoy Lifecycle
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `convoy_started` | engine.ts | `name?: string` |
+| `convoy_finished` | engine.ts | `status: string` |
+| `convoy_failed` | engine.ts | `status: string; reason?: string` |
+| `convoy_guard` | engine.ts | `checks?: string[]` |
+
+### Task Lifecycle
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `task_started` | engine.ts | `worker_id?: string` |
+| `task_done` | engine.ts | `status?: string; retries?: number; worker_id?: string` |
+| `task_failed` | engine.ts | `reason: string; worker_id?: string; gate?: string; hook?: string` |
+| `task_skipped` | engine.ts | `reason: string` |
+| `task_retried` | engine.ts | `previous_status: string` |
+| `task_waiting_input` | engine.ts | `task_id?: string; reason?: string` |
+
+### Review & Disputes
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `review_started` | engine.ts | `level: string; task_id?: string; model?: string` |
+| `review_verdict` | engine.ts | `level: string; verdict: string; tokens: number; model?: string; feedback_length?: number; budget_exceeded?: boolean; budget_downgrade?: boolean; budget_skip?: boolean; passes?: number; blocks?: number` |
+| `dispute_opened` | engine.ts | `dispute_id: string; task_id: string; agent?: string; reason?: string` |
+| `dlq_entry_created` | engine.ts | `dlq_id: string; task_id: string; agent?: string; attempts?: number` |
+
+### Drift Detection
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `drift_check_result` | engine.ts | `score?: number; threshold?: number; passed?: boolean` |
+| `drift_detected` | engine.ts | `score?: number; files?: string[]` |
+
+### Circuit Breaker
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `circuit_breaker_tripped` | engine.ts | `agent?: string; failure_count?: number; threshold?: number` |
+| `circuit_breaker_fallback` | engine.ts | `original_agent?: string; fallback_agent?: string; task_id?: string` |
+| `circuit_breaker_blocked` | engine.ts | `agent?: string; task_id?: string` |
+
+### Merge & Worktree
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `merge_conflict_detected` | engine.ts | `task_id?: string; files?: string[]` |
+| `merge_conflict_failed` | engine.ts | `task_id?: string; error?: string` |
+
+### Artifacts & Injection
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `file_injection_received` | engine.ts | `task_id?: string; from_task?: string; name?: string` |
+| `artifact_limit_reached` | engine.ts | `task_id?: string; limit?: number; current?: number` |
+
+### Agent Intelligence
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `agent_identity_captured` | engine.ts | `agent?: string; task_id?: string` |
+| `agent_identity_rejected` | engine.ts | `agent?: string; task_id?: string; reason?: string` |
+| `weak_area_skipped` | engine.ts | `agent?: string; weak_areas?: string[]; task_files?: string[]` |
+| `swarm_concurrency_update` | engine.ts | `new_concurrency?: number; reason?: string` |
+
+### Hooks
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `post_convoy_hook_failed` | engine.ts | `hook?: string; error?: string` |
+
+### Observability / Session
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `session` | engine.ts | `agent?: string; model?: string; task?: string; outcome?: string; duration_min?: number` |
+| `delegation` | engine.ts | `agent?: string; model?: string; tier?: string; mechanism?: string; outcome?: string` |
+
+### Security & Reliability
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `secret_leak_prevented` | engine.ts, events.ts | `original_type?: string; patterns?: string[]; task_id?: string; findings_count?: number; context?: string` |
+| `ndjson_write_failed` | events.ts | `original_type?: string` |
+
+### Built-in Gates
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `built_in_gate_result` | engine.ts | `gate: string; passed: boolean; output?: string; level?: string` |
+
+### Watch Mode
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `watch_started` | watch.ts | `trigger_type?: string; pid?: number` |
+| `watch_cycle_start` | watch.ts | `cycle_number?: number; triggered_by?: string` |
+| `watch_cycle_end` | watch.ts | `cycle_number?: number; status?: string` |
+| `watch_stopped` | watch.ts | `reason?: string` |
+
+### Worker Health
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `worker_killed` | health.ts | `reason?: string; worker_id?: string; task_id?: string` |
+
+### Discovered Issues
+
+| Event Type | Source | Data Fields |
+|-----------|--------|-------------|
+| `discovered_issue` | issues.ts | `task_id?: string; title?: string; file?: string; description?: string; severity?: string` |
+
+## Derived Metrics
+
+These are computed from raw events, not emitted directly.
+
+| Metric | Derivation |
+|--------|-----------|
+| Task duration | `task_done.timestamp - task_started.timestamp` |
+| Convoy duration | `convoy_finished.timestamp - convoy_started.timestamp` |
+| Retry rate | `COUNT(task_retried) / COUNT(task_started)` |
+| Gate failure rate | `COUNT(built_in_gate_result WHERE !passed) / COUNT(built_in_gate_result)` |
+| Review pass rate | `COUNT(review_verdict WHERE verdict='pass') / COUNT(review_verdict)` |
+| Token usage | `SUM(review_verdict.tokens)` per convoy |
+| Circuit breaker trips | `COUNT(circuit_breaker_tripped)` per agent |
+
+## Runtime Validation
+
+- `validateEventType(type)` — checks membership in `KNOWN_EVENT_TYPES` (a `Set<string>` exported from [`types.ts`](types.ts)). Unknown types trigger a `console.warn` but do not throw, preserving extensibility for custom event types.
+- `validateEventData(type, data)` — validates the `data` payload shape for known event types. Defined in [`event-schemas.ts`](event-schemas.ts). Returns `{ valid: boolean; issues?: string[] }`. Invalid payloads trigger a `console.warn` but do not block emission.
+
+Both validators are called at emit time in [`events.ts`](events.ts).
+
+## Dashboard Build Pipeline
+
+To build the dashboard with real convoy data:
+
+```sh
+# 1. Run ETL to extract data from SQLite → JSON
+npm run dashboard:etl
+
+# 2. Build the Astro dashboard (reads from public/data/*.json)
+npx astro build --root src/dashboard
+
+# 3. Serve locally (optional)
+npx astro preview --root src/dashboard
+```
+
+In CI, add these steps after tests pass:
+
+```yaml
+- run: npm run dashboard:etl
+- run: npx astro build --root src/dashboard
+```
+
+The ETL script gracefully handles missing databases — it produces empty JSON files so the dashboard renders an empty state instead of crashing.

package/src/cli/convoy/dashboard-types.ts

@@ -0,0 +1,141 @@
+export interface DashboardOverallStats {
+  total_convoys: number
+  running_convoys: number
+  successful_convoys: number
+  failed_convoys: number
+  avg_convoy_duration_sec: number | null
+  p95_convoy_duration_sec: number | null
+  total_tokens: number
+  total_cost_usd: number
+  top_agents: Array<{ agent: string; task_count: number; total_tokens: number }>
+  top_models: Array<{ model: string; task_count: number; total_tokens: number }>
+  retry_queue_count: number
+  disputed_tasks: number
+}
+
+export interface DashboardConvoySummary {
+  id: string
+  name: string
+  status: string
+  branch: string | null
+  created_at: string
+  started_at: string | null
+  finished_at: string | null
+  duration_sec: number | null
+  total_tokens: number | null
+  total_cost_usd: number | null
+  tasks_total: number
+  tasks_done: number
+  tasks_running: number
+  tasks_waiting: number
+  tasks_failed: number
+  tasks_retrying: number
+}
+
+export interface DashboardTaskSummary {
+  id: string
+  phase: number
+  agent: string
+  model: string | null
+  status: string
+  duration_sec: number | null
+  retries: number
+  files: string[]
+  total_tokens: number | null
+  cost_usd: number | null
+  review_level: string | null
+  review_verdict: string | null
+  drift_score: number | null
+}
+
+export interface DashboardConvoyDetail {
+  convoy: {
+    id: string
+    name: string
+    status: string
+    created_at: string
+    finished_at: string | null
+    branch: string | null
+    total_tokens: number | null
+    total_cost_usd: number | null
+  }
+  taskSummary: {
+    total: number
+    done: number
+    running: number
+    failed: number
+    review_blocked: number
+    disputed: number
+    reviewed: number
+    panel_reviewed: number
+    tasks_with_drift: number
+    max_drift_score: number | null
+    drift_retried: number
+  }
+  quality: {
+    reviewed_tasks: number
+    review_blocked_tasks: number
+    disputed_tasks: number
+    panel_reviews: number
+  }
+  drift: {
+    tasks_with_drift: number
+    max_drift_score: number | null
+    drift_retried_tasks: number
+  }
+  dlq_count: number
+  dlq_entries: Array<{
+    id: string
+    task_id: string
+    agent: string
+    failure_type: string
+    attempts: number
+    resolved: number
+  }>
+  artifact_count: number
+  artifacts: Array<{
+    id: string
+    name: string
+    type: string
+    task_id: string
+    created_at: string
+  }>
+  has_more_events: boolean
+  events: Array<{
+    type: string
+    task_id: string | null
+    data: unknown
+    created_at: string
+  }>
+  tasks: Array<{
+    id: string
+    phase: number
+    agent: string
+    model: string | null
+    status: string
+    retries: number
+    started_at: string | null
+    finished_at: string | null
+    total_tokens: number | null
+    cost_usd: number | null
+    review_level: string | null
+    review_verdict: string | null
+    review_tokens: number | null
+    review_model: string | null
+    panel_attempts: number | null
+    dispute_id: string | null
+    drift_score: number | null
+    drift_retried: number | null
+    files: string[] | null
+  }>
+}
+
+export interface DashboardTimelineEvent {
+  id: number
+  timestamp: string
+  type: string
+  convoy_id: string | null
+  task_id: string | null
+  worker_id: string | null
+  summary: string
+}

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

@@ -2,7 +2,8 @@ import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
-import { createConvoyEngine, evaluateReviewLevel, recoverNdjson, runConvoyGuard } from './engine.js'
+import { createConvoyEngine, evaluateReviewLevel, runConvoyGuard } from './engine.js'
+import { recoverNdjson, createEventEmitter } from './events.js'
 import type { ConvoyEngineOptions, DiffStats } from './engine.js'
 import { createConvoyStore } from './store.js'
 import type { AgentAdapter, Task, TaskSpec, ExecuteResult, ExecuteOptions } from '../types.js'
@@ -3658,3 +3659,100 @@ describe('circuit breaker', () => {
     store.close()
   })
 })
+
+describe('convoy lifecycle events', () => {
+  it('emits convoy_finished event on successful run', async () => {
+    const adapter = makeAdapter()
+    const engine = makeEngine({
+      spec: makeSpec(),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+    const result = await engine.run()
+    expect(result.status).toBe('done')
+
+    const store = createConvoyStore(dbPath)
+    const events = store.getEvents(result.convoyId)
+    store.close()
+
+    const finishedEvent = events.find(e => e.type === 'convoy_finished')
+    expect(finishedEvent).toBeDefined()
+    expect(finishedEvent!.convoy_id).toBe(result.convoyId)
+    expect(JSON.parse(finishedEvent!.data as string).status).toBe('done')
+  })
+
+  it('emits convoy_failed event when a task fails', async () => {
+    const adapter = makeAdapter()
+    adapter.execute.mockResolvedValue({
+      success: false,
+      output: 'error',
+      exitCode: 1,
+    })
+    const engine = makeEngine({
+      spec: makeSpec({}, [{ id: 'fail-task', max_retries: 0 }]),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+    const result = await engine.run()
+    expect(result.status).toBe('failed')
+
+    const store = createConvoyStore(dbPath)
+    const events = store.getEvents(result.convoyId)
+    store.close()
+
+    const failedEvent = events.find(e => e.type === 'convoy_failed')
+    expect(failedEvent).toBeDefined()
+    expect(failedEvent!.convoy_id).toBe(result.convoyId)
+    expect(JSON.parse(failedEvent!.data as string).status).toBe('failed')
+  })
+
+  it('emits convoy_failed with gate-failed status when gates fail', async () => {
+    const adapter = makeAdapter()
+    const engine = makeEngine({
+      spec: makeSpec({ gates: ['false'] }),
+      specYaml: 'name: test',
+      adapter,
+      dbPath,
+      _worktreeManager: makeWorktreeManager(),
+      _mergeQueue: makeMergeQueue(),
+    })
+    const result = await engine.run()
+    expect(result.status).toBe('gate-failed')
+
+    const store = createConvoyStore(dbPath)
+    const events = store.getEvents(result.convoyId)
+    store.close()
+
+    const failedEvent = events.find(e => e.type === 'convoy_failed')
+    expect(failedEvent).toBeDefined()
+    expect(JSON.parse(failedEvent!.data as string).status).toBe('gate-failed')
+  })
+})
+
+describe('createEventEmitter callsite safety', () => {
+  it('rejects a raw string argument', () => {
+    const testStore = createConvoyStore(dbPath)
+    expect(() => {
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      createEventEmitter(testStore, 'some-path' as any)
+    }).toThrow('createEventEmitter options must be an object, not a string')
+    testStore.close()
+  })
+
+  it('accepts an options object with ndjsonPath', () => {
+    const testStore = createConvoyStore(dbPath)
+    const testNdjsonPath = join(tmpDir, 'callsite-test.ndjson')
+    const emitter = createEventEmitter(testStore, { ndjsonPath: testNdjsonPath })
+    expect(emitter).toBeDefined()
+    expect(typeof emitter.emit).toBe('function')
+    expect(typeof emitter.close).toBe('function')
+    emitter.close()
+    testStore.close()
+  })
+})

package/src/cli/convoy/engine.ts

@@ -18,7 +18,7 @@ import { promisify } from 'node:util'
 import type { Task, TaskSpec, AgentAdapter, ExecuteResult, ReviewHeuristics } from '../types.js'
 import { createConvoyStore, ConvoyArtifactLimitError, type ConvoyStore } from './store.js'
 import { acquireEngineLock } from './lock.js'
-import { createEventEmitter, type ConvoyEventEmitter } from './events.js'
+import { createEventEmitter, ndjsonPathForConvoy, recoverNdjson, type ConvoyEventEmitter } from './events.js'
 import { createWorktreeManager, type WorktreeManager } from './worktree.js'
 import { createMergeQueue, MergeConflictError, type MergeQueue } from './merge.js'
 import { createHealthMonitor, detectDrift } from './health.js'
@@ -222,84 +222,6 @@ export async function ensureBranch(branchName: string, basePath: string): Promis
   }
 }
 
-// ── Internal helpers ──────────────────────────────────────────────────────────
-
-/**
- * Truncate any trailing partial line in the NDJSON file, then replay any SQLite
- * events for the given convoy that are missing from the file.
- * Exported for unit testing.
- */
-function safeJsonParse(raw: string): Record<string, unknown> {
-  try {
-    return JSON.parse(raw) as Record<string, unknown>
-  } catch {
-    return {}
-  }
-}
-
-export function recoverNdjson(store: ConvoyStore, convoyId: string, ndjsonPath: string): void {
-  // 1. Read the NDJSON file (if it exists)
-  let fileContent: string
-  try {
-    fileContent = readFileSync(ndjsonPath, 'utf8')
-  } catch {
-    fileContent = ''
-  }
-
-  // 2. Truncate any partial trailing line (no \n terminator)
-  if (fileContent.length > 0 && !fileContent.endsWith('\n')) {
-    const lastNewline = fileContent.lastIndexOf('\n')
-    if (lastNewline === -1) {
-      writeFileSync(ndjsonPath, '')
-      fileContent = ''
-    } else {
-      writeFileSync(ndjsonPath, fileContent.slice(0, lastNewline + 1))
-      fileContent = fileContent.slice(0, lastNewline + 1)
-    }
-  }
-
-  // 3. Count valid NDJSON event IDs for this convoy
-  const ndjsonIds = new Set<number>()
-  for (const line of fileContent.split('\n')) {
-    if (!line.trim()) continue
-    try {
-      const parsed = JSON.parse(line) as Record<string, unknown>
-      if (parsed.convoy_id === convoyId && parsed._event_id != null) {
-        ndjsonIds.add(parsed._event_id as number)
-      }
-    } catch {
-      // Skip unparseable lines
-    }
-  }
-
-  // 4. Get all SQLite events for this convoy
-  const sqliteEvents = store.getEvents(convoyId)
-
-  // 5. Replay missing events (those in SQLite but not in NDJSON)
-  const missing = sqliteEvents.filter(e => e.id != null && !ndjsonIds.has(e.id!))
-  if (missing.length > 0) {
-    const fd = openSync(ndjsonPath, 'a')
-    try {
-      for (const event of missing) {
-        const parsedData = event.data ? safeJsonParse(event.data) : {}
-        const record = {
-          ...parsedData,
-          _event_id: event.id,
-          timestamp: event.created_at,
-          type: event.type,
-          convoy_id: event.convoy_id,
-          task_id: event.task_id,
-          worker_id: event.worker_id,
-        }
-        appendFileSync(fd, JSON.stringify(record) + '\n')
-      }
-      fsyncSync(fd)
-    } finally {
-      closeSync(fd)
-    }
-  }
-}
-
 // ── Convoy guard ──────────────────────────────────────────────────────────────
 
 export interface ConvoyGuardResult {
@@ -336,12 +258,10 @@ export function runConvoyGuard(
   try {
     const content = readFileSync(ndjsonPath, 'utf8')
     const lines = content.split('\n').filter(l => l.trim())
-    const convoyLines = lines.filter(l => {
-      try { return (JSON.parse(l) as Record<string, unknown>).convoy_id === convoyId } catch { return false }
-    })
-    if (convoyLines.length < completedTasks.length) {
+    // Per-convoy file — all records belong to this convoy, no need to filter by convoy_id
+    if (lines.length < completedTasks.length) {
       warnings.push(
-        `NDJSON record count (${convoyLines.length}) < completed tasks (${completedTasks.length})`,
+        `NDJSON record count (${lines.length}) < completed tasks (${completedTasks.length})`,
       )
     }
   } catch {
@@ -365,9 +285,16 @@ export function runConvoyGuard(
   }
 
   // Check 4: Gate results recorded for all gates that ran
-  const gateEvents = events.filter(e =>
-    e.type === 'built_in_gate_result' || (e.data != null && e.data.includes('gate')),
-  )
+  const gateEvents = events.filter(e => {
+    if (e.type === 'built_in_gate_result') return true
+    if (e.data == null) return false
+    try {
+      const parsed = JSON.parse(e.data) as Record<string, unknown>
+      return 'gate' in parsed
+    } catch {
+      return false
+    }
+  })
   const tasksWithGates = tasks.filter(t => t.gates)
   if (tasksWithGates.length > 0 && gateEvents.length === 0) {
     warnings.push('Tasks have gates configured but no gate result events found')
@@ -1065,6 +992,7 @@ async function runConvoy(
         skipTask(t.id, `on_exhausted: stop — task "${taskRecord.id}" exhausted retries`)
       }
       store.updateConvoyStatus(convoyId, 'failed')
+      events.emit('convoy_failed', { status: 'failed', reason: `on_exhausted: stop — task "${taskRecord.id}" exhausted retries` }, { convoy_id: convoyId })
     } else if (exhausted === 'dlq' || exhausted === 'skip') {
       // Default behavior: cascade failure to dependents only
       cascadeFailure(taskRecord.id)
@@ -2603,6 +2531,12 @@ async function runConvoy(
     total_tokens: convoyTotalTokens,
   })
 
+  if (finalStatus === 'done') {
+    events.emit('convoy_finished', { status: 'done' }, { convoy_id: convoyId })
+  } else {
+    events.emit('convoy_failed', { status: finalStatus, reason: finalStatus === 'gate-failed' ? 'Gate check failed' : 'One or more tasks failed' }, { convoy_id: convoyId })
+  }
+
   // Run convoy guard checks
   const guardResult = runConvoyGuard(store, convoyId, wtManager, ndjsonPath, spec.guard)
   if (guardResult.warnings.length > 0) {
@@ -2690,9 +2624,8 @@ export function createConvoyEngine(options: ConvoyEngineOptions): ConvoyEngine {
 
     const store = createConvoyStore(dbPath)
     const ndjsonPath = options.logsDir
-      ? join(options.logsDir, 'convoy-events.ndjson')
-      : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson')
-    mkdirSync(dirname(ndjsonPath), { recursive: true })
+      ? join(options.logsDir, 'convoys', `${convoyId}.ndjson`)
+      : ndjsonPathForConvoy(convoyId, basePath)
     const events = createEventEmitter(store, { ndjsonPath })
     const wtManager = options._worktreeManager ?? createWorktreeManager(basePath)
     const mergeQueue = options._mergeQueue ?? createMergeQueue(basePath)
@@ -2807,9 +2740,8 @@ export function createConvoyEngine(options: ConvoyEngineOptions): ConvoyEngine {
 
     const store = createConvoyStore(dbPath)
     const ndjsonPath = options.logsDir
-      ? join(options.logsDir, 'convoy-events.ndjson')
-      : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson')
-    mkdirSync(dirname(ndjsonPath), { recursive: true })
+      ? join(options.logsDir, 'convoys', `${convoyId}.ndjson`)
+      : ndjsonPathForConvoy(convoyId, basePath)
     const events = createEventEmitter(store, { ndjsonPath })
     const wtManager = options._worktreeManager ?? createWorktreeManager(basePath)
     const mergeQueue = options._mergeQueue ?? createMergeQueue(basePath)
@@ -2876,9 +2808,8 @@ export function createConvoyEngine(options: ConvoyEngineOptions): ConvoyEngine {
     mkdirSync(dirname(dbPath), { recursive: true })
     const store = createConvoyStore(dbPath)
     const ndjsonPath = options.logsDir
-      ? join(options.logsDir, 'convoy-events.ndjson')
-      : join(basePath, '.opencastle', 'logs', 'convoy-events.ndjson')
-    mkdirSync(dirname(ndjsonPath), { recursive: true })
+      ? join(options.logsDir, 'convoys', `${convoyId}.ndjson`)
+      : ndjsonPathForConvoy(convoyId, basePath)
     const events = createEventEmitter(store, { ndjsonPath })
     try {
       const allTasks = store.getTasksByConvoy(convoyId)