opencastle 0.27.0 → 0.27.2

package/src/cli/convoy/knowledge.ts

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { scanForSecrets } from './gates.js'
+
+const KNOWLEDGE_PATH = '.opencastle/KNOWLEDGE-GRAPH.md'
+const TABLE_HEADER =
+  '| source | target | relationship | date | convoy_id |\n' +
+  '|--------|--------|--------------|------|-----------|\n'
+
+function extractChangedFiles(diffOutput: string): string[] {
+  const files: string[] = []
+  const re = /^diff --git a\/.+ b\/(.+)$/gm
+  let m: RegExpExecArray | null
+  while ((m = re.exec(diffOutput)) !== null) {
+    const fileName = m[1]
+    if (isTargetFile(fileName)) files.push(fileName)
+  }
+  return files
+}
+
+function isTargetFile(fileName: string): boolean {
+  if (!/\.(ts|js)$/.test(fileName)) return false
+  if (/\.(test|spec)\.(ts|js)$/.test(fileName)) return false
+  return true
+}
+
+function extractFileDiff(diffOutput: string, fileName: string): string {
+  const escaped = fileName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const re = new RegExp(
+    'diff --git a/' + escaped + ' b/' + escaped + '([\\s\\S]*?)(?=diff --git |$)',
+  )
+  const m = diffOutput.match(re)
+  return m ? m[0] : ''
+}
+
+function extractImports(diffContent: string): Array<{ source: string; target: string }> {
+  const imports: Array<{ source: string; target: string }> = []
+  const headerMatch = diffContent.match(/^diff --git a\/(.+) b\//)
+  if (!headerMatch) return []
+  const sourceFile = headerMatch[1]
+
+  for (const line of diffContent.split('\n')) {
+    if (!line.startsWith('+') || line.startsWith('+++')) continue
+    const content = line.slice(1)
+
+    const esmMatch = content.match(/import\s+.*\s+from\s+['"](\.[^'"]+)['"]/)
+    if (esmMatch) {
+      imports.push({ source: sourceFile, target: esmMatch[1] })
+      continue
+    }
+    const reqMatch = content.match(/require\s*\(\s*['"](\.[^'"]+)['"]\s*\)/)
+    if (reqMatch) {
+      imports.push({ source: sourceFile, target: reqMatch[1] })
+    }
+  }
+
+  return imports
+}
+
+function parseExistingRowKeys(content: string): Set<string> {
+  const keys = new Set<string>()
+  for (const line of content.split('\n')) {
+    const parts = line.split('|').map(p => p.trim()).filter(Boolean)
+    if (parts.length >= 2 && parts[0] !== 'source') {
+      keys.add(parts[0] + '|' + parts[1])
+    }
+  }
+  return keys
+}
+
+export function buildKnowledgeGraph(
+  diffOutput: string,
+  convoyId: string,
+  basePath?: string,
+): { added: number; skipped: number } {
+  const base = basePath ?? process.cwd()
+  const filePath = join(base, KNOWLEDGE_PATH)
+  const date = new Date().toISOString().slice(0, 10)
+
+  const changedFiles = extractChangedFiles(diffOutput)
+  const allImports: Array<{ source: string; target: string }> = []
+  for (const file of changedFiles) {
+    allImports.push(...extractImports(extractFileDiff(diffOutput, file)))
+  }
+
+  if (allImports.length === 0) return { added: 0, skipped: 0 }
+
+  const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  const existingKeys = parseExistingRowKeys(existingContent)
+
+  const newRows: string[] = []
+  let skipped = 0
+
+  for (const { source, target } of allImports) {
+    const key = source + '|' + target
+    if (existingKeys.has(key)) {
+      skipped++
+      continue
+    }
+    const row = '| ' + source + ' | ' + target + ' | imports | ' + date + ' | ' + convoyId + ' |'
+    const scan = scanForSecrets(row, 'knowledge-graph')
+    if (!scan.clean) {
+      skipped++
+      continue
+    }
+    newRows.push(row)
+    existingKeys.add(key)
+  }
+
+  if (newRows.length === 0) return { added: 0, skipped }
+
+  let fileContent: string
+  if (!existsSync(filePath)) {
+    fileContent =
+      '# Knowledge Graph\n\nFile dependency relationships discovered during convoy runs.\n\n' +
+      TABLE_HEADER +
+      newRows.join('\n') +
+      '\n'
+  } else {
+    const hasHeader = existingContent.includes('| source | target |')
+    fileContent =
+      (hasHeader
+        ? existingContent.trimEnd()
+        : existingContent.trimEnd() + '\n\n' + TABLE_HEADER.trimEnd()) +
+      '\n' +
+      newRows.join('\n') +
+      '\n'
+  }
+
+  writeFileSync(filePath, fileContent, 'utf8')
+  return { added: newRows.length, skipped }
+}

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

@@ -0,0 +1,188 @@
+import { mkdtempSync, rmSync, realpathSync, writeFileSync, mkdirSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { readLessons, captureLessons, consolidateLessons } from './lessons.js'
+
+vi.mock('./gates.js', () => ({
+  scanForSecrets: vi.fn(() => ({ clean: true, findings: [] })),
+}))
+
+const LESSONS_REL = '.opencastle/LESSONS-LEARNED.md'
+
+function makeBase(): string {
+  const dir = realpathSync(mkdtempSync(join(tmpdir(), 'lessons-test-')))
+  mkdirSync(join(dir, '.opencastle'), { recursive: true })
+  return dir
+}
+
+let tmpDir: string
+
+beforeEach(() => {
+  tmpDir = makeBase()
+  vi.clearAllMocks()
+})
+
+afterEach(() => {
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('readLessons', () => {
+  it('returns empty array when file does not exist', () => {
+    const result = readLessons('developer', [], tmpDir)
+    expect(result).toEqual([])
+  })
+
+  it('returns empty array when file has no LES entries', () => {
+    writeFileSync(join(tmpDir, LESSONS_REL), '# Lessons Learned\n\nNo entries yet.\n')
+    const result = readLessons('developer', [], tmpDir)
+    expect(result).toEqual([])
+  })
+
+  it('filters by agent name', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: Dev tip\n| **Category** | `general` |\n| **Added** | 2026-01-01 |\n| **Agent** | developer |\nText about developer agent.\n\n' +
+      '### LES-002: Other tip\n| **Category** | `git` |\n| **Added** | 2026-01-02 |\n| **Agent** | reviewer |\nText about reviewer agent.\n',
+    )
+    const result = readLessons('developer', [], tmpDir)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toContain('Dev tip')
+  })
+
+  it('filters by file paths', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: File tip\n| **Category** | `general` |\n| **Added** | 2026-01-01 |\nText about src/cli/engine.ts file.\n\n' +
+      '### LES-002: Unrelated\n| **Category** | `git` |\n| **Added** | 2026-01-02 |\nSome other content.\n',
+    )
+    const result = readLessons('unknown', ['src/cli/engine.ts'], tmpDir)
+    expect(result).toHaveLength(1)
+    expect(result[0]).toContain('File tip')
+  })
+
+  it('returns maximum 5 entries', () => {
+    let content = '# Lessons\n\n'
+    for (let i = 1; i <= 8; i++) {
+      content += `### LES-00${i}: Tip ${i}\n| **Category** | \`general\` |\n| **Added** | 2026-01-0${i} |\nText about developer agent.\n\n`
+    }
+    writeFileSync(join(tmpDir, LESSONS_REL), content)
+    const result = readLessons('developer', [], tmpDir)
+    expect(result.length).toBeLessThanOrEqual(5)
+  })
+
+  it('prioritizes agent+file matches over agent-only matches', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: Agent only\n| **Category** | `general` |\n| **Added** | 2026-01-01 |\nContent about developer.\n\n' +
+      '### LES-002: Agent and file\n| **Category** | `general` |\n| **Added** | 2026-01-02 |\nContent about developer and src/app.ts.\n',
+    )
+    const result = readLessons('developer', ['src/app.ts'], tmpDir)
+    expect(result[0]).toContain('Agent and file')
+  })
+})
+
+describe('captureLessons', () => {
+  it('appends an entry with correct format', () => {
+    const result = captureLessons(
+      { title: 'Test lesson', category: 'general', agent: 'developer', problem: 'A problem', solution: 'A solution' },
+      tmpDir,
+    )
+    expect(result.captured).toBe(true)
+    const content = readFileSync(join(tmpDir, LESSONS_REL), 'utf8')
+    expect(content).toContain('### LES-001: Test lesson')
+    expect(content).toContain('**Problem:** A problem')
+    expect(content).toContain('**Correct approach:** A solution')
+  })
+
+  it('creates file if it does not exist', () => {
+    captureLessons(
+      { title: 'First', category: 'general', agent: 'x', problem: 'p', solution: 's' },
+      tmpDir,
+    )
+    expect(readFileSync(join(tmpDir, LESSONS_REL), 'utf8')).toContain('### LES-001: First')
+  })
+
+  it('auto-increments LES number', () => {
+    writeFileSync(join(tmpDir, LESSONS_REL), '# Lessons\n\n### LES-007: Existing\n')
+    captureLessons(
+      { title: 'New', category: 'general', agent: 'x', problem: 'p', solution: 's' },
+      tmpDir,
+    )
+    const content = readFileSync(join(tmpDir, LESSONS_REL), 'utf8')
+    expect(content).toContain('### LES-008: New')
+  })
+
+  it('includes files note when files provided', () => {
+    captureLessons(
+      { title: 'With files', category: 'general', agent: 'x', problem: 'p', solution: 's', files: ['foo.ts', 'bar.ts'] },
+      tmpDir,
+    )
+    const content = readFileSync(join(tmpDir, LESSONS_REL), 'utf8')
+    expect(content).toContain('foo.ts')
+    expect(content).toContain('bar.ts')
+  })
+
+  it('rejects content with secrets', async () => {
+    const { scanForSecrets } = await import('./gates.js')
+    vi.mocked(scanForSecrets).mockReturnValueOnce({
+      clean: false,
+      findings: [{ pattern: 'Generic Secret', file: '', line: 1, snippet: 'x' }],
+    })
+    const result = captureLessons(
+      { title: 'Bad', category: 'general', agent: 'x', problem: 'p', solution: 's' },
+      tmpDir,
+    )
+    expect(result.captured).toBe(false)
+    expect(result.reason).toBe('secrets_detected')
+  })
+})
+
+describe('consolidateLessons', () => {
+  it('returns zeros when file does not exist', () => {
+    const result = consolidateLessons(tmpDir)
+    expect(result).toEqual({ merged: 0, remaining: 0 })
+  })
+
+  it('merges duplicate entries with same category and similar title', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: Git push rejected error\n| **Category** | `git` |\n| **Added** | 2026-01-01 |\nOld content.\n\n' +
+      '### LES-002: Git push rejected error fix\n| **Category** | `git` |\n| **Added** | 2026-01-05 |\nNewer content.\n',
+    )
+    const result = consolidateLessons(tmpDir)
+    expect(result.merged).toBe(1)
+    expect(result.remaining).toBe(1)
+    const content = readFileSync(join(tmpDir, LESSONS_REL), 'utf8')
+    expect(content).toContain('2026-01-05')
+  })
+
+  it('keeps the most recent entry when merging', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: Same title same\n| **Category** | `general` |\n| **Added** | 2026-01-01 |\nOld.\n\n' +
+      '### LES-002: Same title same\n| **Category** | `general` |\n| **Added** | 2026-03-01 |\nNew.\n',
+    )
+    consolidateLessons(tmpDir)
+    const content = readFileSync(join(tmpDir, LESSONS_REL), 'utf8')
+    expect(content).toContain('New.')
+    expect(content).not.toContain('Old.')
+  })
+
+  it('does not merge entries with different categories', () => {
+    writeFileSync(
+      join(tmpDir, LESSONS_REL),
+      '# Lessons\n\n' +
+      '### LES-001: Same title same\n| **Category** | `git` |\n| **Added** | 2026-01-01 |\nGit.\n\n' +
+      '### LES-002: Same title same\n| **Category** | `general` |\n| **Added** | 2026-01-02 |\nGeneral.\n',
+    )
+    const result = consolidateLessons(tmpDir)
+    expect(result.remaining).toBe(2)
+    expect(result.merged).toBe(0)
+  })
+})

package/src/cli/convoy/lessons.ts

@@ -0,0 +1,164 @@
+import { existsSync, readFileSync, appendFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { scanForSecrets } from './gates.js'
+
+const LESSONS_PATH = '.opencastle/LESSONS-LEARNED.md'
+
+function parseLessonEntries(content: string): string[] {
+  const parts = content.split(/(?=### LES-\d+:)/)
+  return parts.filter(p => p.trim().startsWith('### LES-'))
+}
+
+function getNextLessonNumber(entries: string[]): number {
+  let max = 0
+  for (const entry of entries) {
+    const m = entry.match(/### LES-(\d+):/)
+    if (m) {
+      const n = parseInt(m[1], 10)
+      if (n > max) max = n
+    }
+  }
+  return max + 1
+}
+
+export function readLessons(agentName: string, filePaths: string[], basePath?: string): string[] {
+  const base = basePath ?? process.cwd()
+  const filePath = join(base, LESSONS_PATH)
+  if (!existsSync(filePath)) return []
+  const content = readFileSync(filePath, 'utf8')
+  const entries = parseLessonEntries(content)
+  if (entries.length === 0) return []
+  const agentLower = agentName.toLowerCase()
+  const scored: Array<{ entry: string; score: number }> = []
+  for (const entry of entries) {
+    const entryLower = entry.toLowerCase()
+    const matchesAgent = entryLower.includes(agentLower)
+    const matchesFiles =
+      filePaths.length > 0 && filePaths.some(fp => entryLower.includes(fp.toLowerCase()))
+    if (matchesAgent && matchesFiles) {
+      scored.push({ entry, score: 2 })
+    } else if (matchesAgent) {
+      scored.push({ entry, score: 1 })
+    } else if (matchesFiles) {
+      scored.push({ entry, score: 0.5 })
+    }
+  }
+  scored.sort((a, b) => b.score - a.score)
+  return scored.slice(0, 5).map(s => s.entry.trim())
+}
+
+export function captureLessons(
+  lesson: {
+    title: string
+    category: string
+    agent: string
+    problem: string
+    solution: string
+    files?: string[]
+  },
+  basePath?: string,
+): { captured: boolean; reason?: string } {
+  const base = basePath ?? process.cwd()
+  const filePath = join(base, LESSONS_PATH)
+  const existingContent = existsSync(filePath) ? readFileSync(filePath, 'utf8') : ''
+  const entries = parseLessonEntries(existingContent)
+  const nextNum = getNextLessonNumber(entries)
+  const lesNum = String(nextNum).padStart(3, '0')
+  const date = new Date().toISOString().slice(0, 10)
+  const filesNote =
+    lesson.files && lesson.files.length > 0
+      ? `\n**Files:** ${lesson.files.join(', ')}`
+      : ''
+  const entry =
+    `\n### LES-${lesNum}: ${lesson.title}\n\n` +
+    '| Field | Value |\n|-------|-------|\n' +
+    `| **Category** | \`${lesson.category}\` |\n` +
+    `| **Added** | ${date} |\n` +
+    `| **Agent** | ${lesson.agent} |\n` +
+    '| **Severity** | `medium` |\n\n' +
+    `**Problem:** ${lesson.problem}\n\n` +
+    `**Correct approach:** ${lesson.solution}${filesNote}\n`
+  const scanResult = scanForSecrets(entry, 'lessons')
+  if (!scanResult.clean) {
+    return { captured: false, reason: 'secrets_detected' }
+  }
+  if (!existsSync(filePath)) {
+    writeFileSync(
+      filePath,
+      '# Lessons Learned\n\nStructured log of pitfalls and correct approaches.\n\n## Lessons\n',
+      'utf8',
+    )
+  }
+  appendFileSync(filePath, entry, 'utf8')
+  return { captured: true }
+}
+
+function extractDate(entry: string): string {
+  const m = entry.match(/\*\*Added\*\*\s*\|\s*(\d{4}-\d{2}-\d{2})/)
+  return m ? m[1] : '0000-00-00'
+}
+
+function extractCategory(entry: string): string {
+  const m = entry.match(/\*\*Category\*\*\s*\|\s*`([^`]+)`/)
+  return m ? m[1] : ''
+}
+
+function extractTitle(entry: string): string {
+  const m = entry.match(/### LES-\d+:\s*(.+)/)
+  return m ? m[1].trim() : ''
+}
+
+function normalizeTitle(title: string): string {
+  return title.toLowerCase().replace(/[^a-z0-9\s]/g, '').trim()
+}
+
+function wordOverlap(a: string, b: string): number {
+  const wordsA = new Set(a.split(/\s+/).filter(Boolean))
+  const wordsB = new Set(b.split(/\s+/).filter(Boolean))
+  if (wordsA.size === 0 || wordsB.size === 0) return 0
+  let overlap = 0
+  for (const w of wordsA) {
+    if (wordsB.has(w)) overlap++
+  }
+  return overlap / Math.max(wordsA.size, wordsB.size)
+}
+
+export function consolidateLessons(basePath?: string): { merged: number; remaining: number } {
+  const base = basePath ?? process.cwd()
+  const filePath = join(base, LESSONS_PATH)
+  if (!existsSync(filePath)) return { merged: 0, remaining: 0 }
+  const content = readFileSync(filePath, 'utf8')
+  const entries = parseLessonEntries(content)
+  if (entries.length === 0) return { merged: 0, remaining: 0 }
+  const firstLessonIdx = content.indexOf('### LES-')
+  const header = firstLessonIdx > 0 ? content.slice(0, firstLessonIdx) : ''
+  const kept: string[] = []
+  let mergedCount = 0
+  const processed = new Set<number>()
+  for (let i = 0; i < entries.length; i++) {
+    if (processed.has(i)) continue
+    const catI = extractCategory(entries[i])
+    const titleI = normalizeTitle(extractTitle(entries[i]))
+    let bestIdx = i
+    let bestDate = extractDate(entries[i])
+    for (let j = i + 1; j < entries.length; j++) {
+      if (processed.has(j)) continue
+      const catJ = extractCategory(entries[j])
+      if (catI !== catJ) continue
+      const titleJ = normalizeTitle(extractTitle(entries[j]))
+      if (wordOverlap(titleI, titleJ) >= 0.8) {
+        const dateJ = extractDate(entries[j])
+        if (dateJ > bestDate) {
+          bestDate = dateJ
+          bestIdx = j
+        }
+        processed.add(j)
+        mergedCount++
+      }
+    }
+    processed.add(i)
+    kept.push(entries[bestIdx])
+  }
+  writeFileSync(filePath, header + kept.join('\n'), 'utf8')
+  return { merged: mergedCount, remaining: kept.length }
+}

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

@@ -0,0 +1,181 @@
+import { mkdtempSync, rmSync } from 'node:fs'
+import { realpathSync } from 'node:fs'
+import { tmpdir, hostname } from 'node:os'
+import { join } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import {
+  acquireEngineLock,
+  EngineAlreadyRunningError,
+  isLockStale,
+  releaseEngineLock,
+} from './lock.js'
+
+const LOCK_TABLE_SQL = `
+  CREATE TABLE IF NOT EXISTS engine_lock (
+    id INTEGER PRIMARY KEY CHECK (id = 1),
+    pid INTEGER NOT NULL,
+    hostname TEXT NOT NULL,
+    started_at TEXT NOT NULL,
+    last_heartbeat TEXT NOT NULL
+  )
+`
+
+let tmpDir: string
+let dbPath: string
+let db: DatabaseSync
+
+beforeEach(() => {
+  tmpDir = realpathSync(mkdtempSync(join(tmpdir(), 'lock-test-')))
+  dbPath = join(tmpDir, 'test.db')
+  db = new DatabaseSync(dbPath)
+  db.exec('PRAGMA journal_mode = WAL')
+  db.exec(LOCK_TABLE_SQL)
+})
+
+afterEach(() => {
+  try {
+    db.close()
+  } catch {
+    // already closed
+  }
+  rmSync(tmpDir, { recursive: true, force: true })
+})
+
+describe('engine lock', () => {
+  it('takes over a stale lock when heartbeat is expired and PID is dead', () => {
+    const staleTime = new Date(Date.now() - 60_000).toISOString()
+    const deadPid = 999999
+
+    // Verify the PID is actually dead on this machine
+    expect(() => process.kill(deadPid, 0)).toThrow()
+
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(deadPid, hostname(), staleTime, staleTime)
+
+    const lock = acquireEngineLock(db, dbPath)
+    const row = db
+      .prepare('SELECT pid FROM engine_lock WHERE id = 1')
+      .get() as { pid: number }
+    expect(row.pid).toBe(process.pid)
+    lock.release()
+  })
+
+  it('throws EngineAlreadyRunningError when lock is held by a live process', () => {
+    const now = new Date().toISOString()
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(process.pid, hostname(), now, now)
+
+    expect(() => acquireEngineLock(db, dbPath)).toThrow(EngineAlreadyRunningError)
+  })
+
+  it('takes over when hostname differs (treated as stale regardless of PID)', () => {
+    const staleTime = new Date(Date.now() - 60_000).toISOString()
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(process.pid, 'other-host.example.com', staleTime, staleTime)
+
+    const lock = acquireEngineLock(db, dbPath)
+    const row = db
+      .prepare('SELECT hostname FROM engine_lock WHERE id = 1')
+      .get() as { hostname: string }
+    expect(row.hostname).toBe(hostname())
+    lock.release()
+  })
+
+  it('release deletes the lock row', () => {
+    const lock = acquireEngineLock(db, dbPath)
+    lock.release()
+    const row = db.prepare('SELECT * FROM engine_lock WHERE id = 1').get()
+    expect(row).toBeUndefined()
+  })
+
+  it('startHeartbeat updates last_heartbeat after 10 seconds', () => {
+    vi.useFakeTimers()
+    try {
+      const lock = acquireEngineLock(db, dbPath)
+      const before = (
+        db
+          .prepare('SELECT last_heartbeat FROM engine_lock WHERE id = 1')
+          .get() as { last_heartbeat: string }
+      ).last_heartbeat
+
+      lock.startHeartbeat()
+      vi.advanceTimersByTime(10_000)
+
+      const after = (
+        db
+          .prepare('SELECT last_heartbeat FROM engine_lock WHERE id = 1')
+          .get() as { last_heartbeat: string }
+      ).last_heartbeat
+
+      expect(after).not.toBe(before)
+      lock.release()
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('throws EngineAlreadyRunningError when SQLITE_BUSY from a concurrent write lock', () => {
+    // Hold a BEGIN IMMEDIATE transaction on a second connection so the first
+    // connection's BEGIN IMMEDIATE will return SQLITE_BUSY.
+    const db2 = new DatabaseSync(dbPath)
+    db2.exec('PRAGMA journal_mode = WAL')
+    db2.exec(LOCK_TABLE_SQL)
+    db2.exec('BEGIN IMMEDIATE')
+
+    try {
+      expect(() => acquireEngineLock(db, dbPath)).toThrow(EngineAlreadyRunningError)
+    } finally {
+      db2.exec('ROLLBACK')
+      db2.close()
+    }
+  })
+
+  it('takes over lock from different hostname when heartbeat expired', () => {
+    const staleTime = new Date(Date.now() - 60_000).toISOString()
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(process.pid, 'ci-runner-42.example.com', staleTime, staleTime)
+
+    const lock = acquireEngineLock(db, dbPath)
+    const row = db
+      .prepare('SELECT hostname, pid FROM engine_lock WHERE id = 1')
+      .get() as { hostname: string; pid: number }
+    expect(row.hostname).toBe(hostname())
+    expect(row.pid).toBe(process.pid)
+    lock.release()
+  })
+
+  it('does NOT take over lock from different hostname when heartbeat is fresh', () => {
+    const freshTime = new Date().toISOString()
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(12345, 'other-host.example.com', freshTime, freshTime)
+
+    expect(() => acquireEngineLock(db, dbPath)).toThrow(EngineAlreadyRunningError)
+  })
+
+  it('isLockStale returns true when no lock exists', () => {
+    expect(isLockStale(db)).toBe(true)
+  })
+
+  it('isLockStale returns false for fresh lock on same host', () => {
+    const now = new Date().toISOString()
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(process.pid, hostname(), now, now)
+    expect(isLockStale(db)).toBe(false)
+  })
+
+  it('isLockStale returns true for expired lock with dead PID on same host', () => {
+    const staleTime = new Date(Date.now() - 60_000).toISOString()
+    const deadPid = 999999
+    db.prepare(
+      'INSERT INTO engine_lock (id, pid, hostname, started_at, last_heartbeat) VALUES (1, ?, ?, ?, ?)',
+    ).run(deadPid, hostname(), staleTime, staleTime)
+    expect(isLockStale(db)).toBe(true)
+  })
+})