@winspan/claude-forge 8.41.0 → 8.51.0

package/tests/unit/handlers.test.ts

@@ -0,0 +1,171 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { UserPromptHandler } from '../../src/daemon/handlers/user-prompt.js';
+import { PostToolUseHandler } from '../../src/daemon/handlers/post-tool-use.js';
+import { StopHandler } from '../../src/daemon/handlers/stop.js';
+import type { ForgeEvent } from '../../src/core/types.js';
+import type { HistoryExporter } from '../../src/daemon/handlers/history-exporter.js';
+
+describe('Handlers', () => {
+  let mockExporter: HistoryExporter;
+
+  beforeEach(() => {
+    mockExporter = {
+      export: vi.fn().mockResolvedValue(undefined),
+    } as unknown as HistoryExporter;
+  });
+
+  describe('UserPromptHandler', () => {
+    it('returns allow:true for prompts', async () => {
+      const handler = new UserPromptHandler();
+      const event: ForgeEvent = {
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: new Date().toISOString(),
+        hook_type: 'UserPromptSubmit',
+        user_prompt: 'test prompt',
+      };
+
+      const result = await handler.handle(event);
+      expect(result.allow).toBe(true);
+    });
+
+    it('returns allow:true for empty prompts', async () => {
+      const handler = new UserPromptHandler();
+      const event: ForgeEvent = {
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: new Date().toISOString(),
+        hook_type: 'UserPromptSubmit',
+      };
+
+      const result = await handler.handle(event);
+      expect(result.allow).toBe(true);
+    });
+
+    it('second call for same session does not re-inject resume/convention', async () => {
+      // Create a mock resume and convention that track how many times they're called
+      const mockResume = {
+        load: vi.fn().mockReturnValue('resume content'),
+        clear: vi.fn(),
+      };
+      const mockConvention = {
+        extract: vi.fn().mockReturnValue('convention content'),
+      };
+
+      const handler = new UserPromptHandler(
+        mockResume as any,
+        mockConvention as any,
+        null,
+        null,
+      );
+
+      const event: ForgeEvent = {
+        session_id: 'session-abc',
+        project_path: '/proj',
+        timestamp: new Date().toISOString(),
+        hook_type: 'UserPromptSubmit',
+        user_prompt: 'first prompt',
+      };
+
+      // First call: should inject
+      const result1 = await handler.handle(event);
+      expect(result1.additionalContext).toBeTruthy();
+      expect(mockResume.load).toHaveBeenCalledTimes(1);
+      expect(mockConvention.extract).toHaveBeenCalledTimes(1);
+
+      // Second call for the same session: should NOT inject again
+      const result2 = await handler.handle({ ...event, user_prompt: 'second prompt' });
+      expect(result2.additionalContext).toBeUndefined();
+      expect(mockResume.load).toHaveBeenCalledTimes(1); // still 1, not called again
+      expect(mockConvention.extract).toHaveBeenCalledTimes(1); // still 1
+    });
+
+    it('re-injects after clearSession is called', async () => {
+      const mockResume = {
+        load: vi.fn().mockReturnValue('resume content'),
+        clear: vi.fn(),
+      };
+      const mockConvention = {
+        extract: vi.fn().mockReturnValue('convention content'),
+      };
+
+      const handler = new UserPromptHandler(
+        mockResume as any,
+        mockConvention as any,
+        null,
+        null,
+      );
+
+      const event: ForgeEvent = {
+        session_id: 'session-xyz',
+        project_path: '/proj',
+        timestamp: new Date().toISOString(),
+        hook_type: 'UserPromptSubmit',
+        user_prompt: 'first prompt',
+      };
+
+      // First call: inject
+      await handler.handle(event);
+      expect(mockResume.load).toHaveBeenCalledTimes(1);
+
+      // clearSession
+      handler.clearSession('session-xyz:/proj');
+
+      // Next call: should inject again
+      const result = await handler.handle({ ...event, user_prompt: 'after clear' });
+      expect(result.additionalContext).toBeTruthy();
+      expect(mockResume.load).toHaveBeenCalledTimes(2);
+    });
+
+    it('handles more than MAX_INJECTION_KEYS different sessions without crashing (LRU cap)', async () => {
+      const handler = new UserPromptHandler();
+
+      // Inject 1001 different session keys (> MAX_INJECTION_KEYS=1000)
+      for (let i = 0; i < 1001; i++) {
+        const event: ForgeEvent = {
+          session_id: `session-${i}`,
+          project_path: `/proj/${i}`,
+          timestamp: new Date().toISOString(),
+          hook_type: 'UserPromptSubmit',
+          user_prompt: `prompt ${i}`,
+        };
+        const result = await handler.handle(event);
+        expect(result.allow).toBe(true);
+      }
+      // Should reach here without throwing or OOM
+    });
+  });
+
+  describe('PostToolUseHandler', () => {
+    it('returns allow:true', async () => {
+      const handler = new PostToolUseHandler(null);
+      const event: ForgeEvent = {
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: new Date().toISOString(),
+        hook_type: 'PostToolUse',
+        tool_name: 'Write',
+        tool_input: { file_path: 'test.ts', content: 'code' },
+      };
+
+      const result = await handler.handle(event);
+      expect(result.allow).toBe(true);
+    });
+  });
+
+  describe('StopHandler', () => {
+    it('calls exporter', async () => {
+      const handler = new StopHandler(mockExporter);
+      const event: ForgeEvent = {
+        session_id: 'test',
+        project_path: '/test',
+        timestamp: new Date().toISOString(),
+        hook_type: 'Stop',
+      };
+
+      const result = await handler.handle(event);
+      expect(result.allow).toBe(true);
+      expect(mockExporter.export).toHaveBeenCalledWith(event);
+    });
+  });
+});

package/tests/unit/hooks/resolve-project-path.test.ts

@@ -0,0 +1,122 @@
+/**
+ * Safety-net unit tests for the bash function `resolve_project_path` in
+ * `src/hooks/hook-lib.sh`.
+ *
+ * We invoke bash directly through `child_process.execSync`, sourcing the lib
+ * and calling the function with various inputs. Each fixture is created under
+ * a per-test scratch directory in $TMPDIR (or /tmp) and cleaned up afterwards.
+ */
+
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { execSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const HOOK_LIB = path.resolve(__dirname, '../../../src/hooks/hook-lib.sh');
+
+/**
+ * Invoke `resolve_project_path` and return its stdout (the resolved path).
+ * Throws if the bash invocation itself fails.
+ */
+function callResolve(input: string, options: { cwd?: string } = {}): string {
+  // Use a single-quoted bash command body to avoid shell quoting hell;
+  // pass the input as $1 to the inner function so we don't need to escape it.
+  const cmd = `bash -c 'source "$1" && resolve_project_path "$2"' _ "${HOOK_LIB}" "${input}"`;
+  return execSync(cmd, {
+    cwd: options.cwd ?? process.cwd(),
+    encoding: 'utf-8',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).toString();
+}
+
+describe('hook-lib.sh :: resolve_project_path', () => {
+  let scratch: string;
+  let repoRoot: string;
+  let nestedDir: string;
+  let worktreeRoot: string;
+  let nonGitDir: string;
+
+  beforeAll(() => {
+    scratch = fs.mkdtempSync(path.join(os.tmpdir(), 'forge-resolve-'));
+
+    // Fixture 1: standard git repo with .git as a directory
+    repoRoot = path.join(scratch, 'repo');
+    nestedDir = path.join(repoRoot, 'a', 'b', 'c');
+    fs.mkdirSync(nestedDir, { recursive: true });
+    fs.mkdirSync(path.join(repoRoot, '.git'));
+
+    // Fixture 2: git worktree where .git is a regular file
+    worktreeRoot = path.join(scratch, 'worktree');
+    fs.mkdirSync(path.join(worktreeRoot, 'src'), { recursive: true });
+    fs.writeFileSync(
+      path.join(worktreeRoot, '.git'),
+      'gitdir: /tmp/somewhere/else\n',
+    );
+
+    // Fixture 3: a plain directory with no git ancestor anywhere up to scratch
+    nonGitDir = path.join(scratch, 'plain', 'x', 'y');
+    fs.mkdirSync(nonGitDir, { recursive: true });
+  });
+
+  afterAll(() => {
+    fs.rmSync(scratch, { recursive: true, force: true });
+  });
+
+  it('case 1: resolves a deeply nested git child dir to repo root', () => {
+    const out = callResolve(nestedDir);
+    expect(out).toBe(repoRoot);
+  });
+
+  it('case 2: returns input cwd unchanged when no .git is found upstream', () => {
+    // To make this test robust we point HOME-ish ancestor away from any real
+    // repo by passing the fixture directly. Even if /tmp ancestors had .git
+    // somewhere, the guard caps at 64 levels. Here scratch lives in /tmp and
+    // has no .git, so the function should fall back to the input.
+    const out = callResolve(nonGitDir);
+    expect(out).toBe(nonGitDir);
+  });
+
+  it('case 3: empty input falls back to $PWD of the invoking shell', () => {
+    // We invoke bash with cwd=repoRoot/a so $PWD is that path and there IS a
+    // git ancestor — it should still resolve to repoRoot because empty input
+    // triggers `dir=$PWD` and then upstream search succeeds.
+    // Note: on macOS /tmp and /var are symlinked to /private/tmp /private/var,
+    // and bash's $PWD reflects the resolved path. We compare against realpath
+    // so the test is portable.
+    const startCwd = path.join(repoRoot, 'a');
+    const out = callResolve('', { cwd: startCwd });
+    expect(out).toBe(fs.realpathSync(repoRoot));
+  });
+
+  it('case 4: recognises git worktree (.git is a file, not a directory)', () => {
+    const sub = path.join(worktreeRoot, 'src');
+    const out = callResolve(sub);
+    expect(out).toBe(worktreeRoot);
+  });
+
+  it('case 5: walking all the way up without finding .git returns the original input', () => {
+    // /nonexistent/deeply/nested has no .git anywhere up to /
+    const out = callResolve('/nonexistent/deeply/nested');
+    expect(out).toBe('/nonexistent/deeply/nested');
+  });
+
+  it('case 6: simulates hook INPUT JSON with cwd pointing to nested dir', () => {
+    // Mirrors what a real hook does:
+    //   RAW_CWD=$(echo "$INPUT" | jq -r '.cwd // ""')
+    //   PROJECT_PATH=$(resolve_project_path "${RAW_CWD:-$PWD}")
+    // We just test resolve_project_path with the cwd extracted from such JSON.
+    const extractedCwd = nestedDir; // simulates jq result for cwd in fixture repo
+    const out = callResolve(extractedCwd);
+    expect(out).toBe(repoRoot);
+  });
+
+  it('case 7: hook INPUT with empty cwd field falls back to shell $PWD (repoRoot)', () => {
+    // When jq returns "" for .cwd, bash sets RAW_CWD="" and calls
+    // resolve_project_path "${RAW_CWD:-$PWD}" — effectively resolve_project_path ""
+    // with bash cwd=repoRoot/a, so $PWD-based lookup should find repoRoot.
+    const startCwd = path.join(repoRoot, 'a');
+    const out = callResolve('', { cwd: startCwd });
+    expect(out).toBe(fs.realpathSync(repoRoot));
+  });
+});

package/tests/unit/invocation-guard.test.ts

@@ -0,0 +1,125 @@
+/**
+ * Unit tests for InvocationGuard
+ *
+ * 覆盖：
+ * - 首次调用允许
+ * - 幂等拦截（重复调用）
+ * - 总次数上限
+ * - 深度上限（先记录后完成）
+ * - complete 递减深度
+ * - clear 重置状态
+ * - 不同 session 相互隔离
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+import { InvocationGuard } from '../../src/skills/invocation-guard.js';
+
+describe('InvocationGuard', () => {
+  let guard: InvocationGuard;
+
+  beforeEach(() => {
+    guard = new InvocationGuard();
+  });
+
+  it('allows first invocation', () => {
+    const result = guard.check('session-1', 'official-tdd');
+    expect(result.allowed).toBe(true);
+    expect(result.reason).toBeUndefined();
+  });
+
+  it('blocks duplicate invocations (idempotent)', () => {
+    guard.record('session-1', 'official-tdd');
+    const result = guard.check('session-1', 'official-tdd');
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain('already invoked');
+  });
+
+  it('blocks when total exceeds limit', () => {
+    for (let i = 0; i < 10; i++) {
+      guard.record('session-1', `skill-${i}`);
+      guard.complete('session-1'); // 释放深度，确保触发的是 total 上限
+    }
+    const result = guard.check('session-1', 'new-skill');
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain('max invocations');
+  });
+
+  it('blocks when depth exceeds limit', () => {
+    // 连续 record 而不 complete，积累 depth
+    guard.record('session-1', 'skill-a');
+    guard.record('session-1', 'skill-b');
+    guard.record('session-1', 'skill-c');
+    const result = guard.check('session-1', 'skill-d');
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain('max invocation depth');
+  });
+
+  it('complete decrements depth so new skill can be invoked', () => {
+    guard.record('session-1', 'skill-a');
+    guard.record('session-1', 'skill-b');
+    guard.record('session-1', 'skill-c');
+    // depth = 3，已达上限
+    guard.complete('session-1');
+    // depth = 2，重新允许
+    const result = guard.check('session-1', 'skill-d');
+    expect(result.allowed).toBe(true);
+  });
+
+  it('complete does not go below zero', () => {
+    guard.complete('session-1'); // 不存在的 session 不应抛错
+    guard.record('session-1', 'skill-a');
+    guard.complete('session-1');
+    guard.complete('session-1'); // 第二次 complete，不应使 depth 变成 -1
+    const stats = guard.getStats('session-1');
+    expect(stats?.depth).toBe(0);
+  });
+
+  it('clear removes session state and allows previously-called skill', () => {
+    guard.record('session-1', 'official-tdd');
+    guard.clear('session-1');
+    const result = guard.check('session-1', 'official-tdd');
+    expect(result.allowed).toBe(true);
+    expect(guard.getStats('session-1')).toBeNull();
+  });
+
+  it('isolates state across sessions', () => {
+    guard.record('session-a', 'official-tdd');
+    // session-b 未调用过，可以用
+    const result = guard.check('session-b', 'official-tdd');
+    expect(result.allowed).toBe(true);
+  });
+
+  it('getStats returns null for unknown session', () => {
+    expect(guard.getStats('nonexistent')).toBeNull();
+  });
+
+  it('getStats reflects recorded invocations', () => {
+    guard.record('session-1', 'skill-a');
+    guard.record('session-1', 'skill-b');
+    const stats = guard.getStats('session-1');
+    expect(stats?.total).toBe(2);
+    expect(stats?.depth).toBe(2);
+    expect(stats?.calledSkills.has('skill-a')).toBe(true);
+    expect(stats?.calledSkills.has('skill-b')).toBe(true);
+  });
+
+  it('total limit takes precedence over depth in check order', () => {
+    // 用 record+complete 把 total 拉到 10，depth 归零
+    for (let i = 0; i < 10; i++) {
+      guard.record('session-1', `skill-${i}`);
+      guard.complete('session-1');
+    }
+    const result = guard.check('session-1', 'new-skill');
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain('max invocations');
+  });
+
+  it('idempotent block triggers even when under total/depth limits', () => {
+    guard.record('session-1', 'official-tdd');
+    guard.complete('session-1');
+    // total=1, depth=0，远低于上限，但 skill 已调用过
+    const result = guard.check('session-1', 'official-tdd');
+    expect(result.allowed).toBe(false);
+    expect(result.reason).toContain('already invoked');
+  });
+});

package/tests/unit/queue.test.ts

@@ -0,0 +1,272 @@
+/**
+ * Unit tests for src/core/queue/index.ts
+ *
+ * All filesystem operations use a temp directory so tests are hermetic.
+ * We monkey-patch the QUEUE_DIR / DEAD_DIR constants via module internals
+ * by pointing the OS homedir to a temp dir through env injection, or by
+ * calling the functions directly with the temp dir substituted.
+ *
+ * Since the module computes QUEUE_DIR at import time from os.homedir(), we
+ * instead test the exported functions by redirecting them to a temp dir
+ * via environment manipulation, OR we restructure to accept a dir parameter.
+ *
+ * For simplicity and correctness: we use the actual exported constants and
+ * temporarily redirect by overriding the module. Instead of that complexity,
+ * we'll test the functions with real temp dirs by using the SQLiteStorage
+ * integration path. For pure prune/enqueue tests we temporarily substitute
+ * the real QUEUE_DIR by setting HOME.
+ */
+
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync, utimesSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+// ── We test the queue module with HOME overridden ──────────────────────────
+// Reset the module registry for each test block to pick up the new HOME.
+
+describe('Queue module', () => {
+  let tempHome: string;
+  let queueDir: string;
+  let deadDir: string;
+  let originalHome: string | undefined;
+
+  beforeEach(async () => {
+    // Override HOME so that the queue module uses our temp dir
+    originalHome = process.env['HOME'];
+    tempHome = mkdtempSync(join(tmpdir(), 'forge-queue-test-'));
+    process.env['HOME'] = tempHome;
+
+    queueDir = join(tempHome, '.claude-forge', 'queue');
+    deadDir = join(queueDir, 'dead');
+    mkdirSync(queueDir, { recursive: true });
+    mkdirSync(deadDir, { recursive: true });
+
+    // Clear module cache so QUEUE_DIR / DEAD_DIR picks up new HOME
+    vi.resetModules();
+  });
+
+  afterEach(() => {
+    process.env['HOME'] = originalHome;
+    rmSync(tempHome, { recursive: true, force: true });
+    vi.resetModules();
+  });
+
+  // ── enqueueEvent ─────────────────────────────────────────────────────────
+
+  it('enqueueEvent writes a file that can be parsed as JSON', async () => {
+    const { enqueueEvent } = await import('../../src/core/queue/index.js');
+
+    const event = {
+      session_id: 'test-001',
+      project_path: '/tmp/proj',
+      timestamp: new Date().toISOString(),
+      hook_type: 'UserPromptSubmit' as const,
+      user_prompt: 'hello',
+    };
+
+    enqueueEvent(event);
+
+    const files = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    expect(files).toHaveLength(1);
+
+    const raw = await import('node:fs/promises').then((m) =>
+      m.readFile(join(queueDir, files[0]!), 'utf8'),
+    );
+    const parsed = JSON.parse(raw);
+    expect(parsed.session_id).toBe('test-001');
+    expect(parsed.event_id).toBeDefined(); // auto-assigned
+  });
+
+  it('enqueueEvent preserves existing event_id', async () => {
+    const { enqueueEvent } = await import('../../src/core/queue/index.js');
+
+    const event = {
+      session_id: 'test-002',
+      project_path: '/tmp',
+      timestamp: new Date().toISOString(),
+      hook_type: 'PreToolUse' as const,
+      event_id: '33333333-3333-4333-8333-333333333333',
+    };
+
+    enqueueEvent(event);
+
+    const files = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    const raw = await import('node:fs/promises').then((m) =>
+      m.readFile(join(queueDir, files[0]!), 'utf8'),
+    );
+    const parsed = JSON.parse(raw);
+    expect(parsed.event_id).toBe('33333333-3333-4333-8333-333333333333');
+  });
+
+  // ── pruneQueue ────────────────────────────────────────────────────────────
+
+  it('pruneQueue removes oldest files when >= MAX_FILES', async () => {
+    const { pruneQueue, MAX_FILES } = await import('../../src/core/queue/index.js');
+
+    // Write MAX_FILES + 10 dummy files
+    const total = MAX_FILES + 10;
+    for (let i = 0; i < total; i++) {
+      const ts = new Date(Date.now() + i * 1000).toISOString().replace(/[:.]/g, '-').replace('Z', 'Z');
+      writeFileSync(join(queueDir, `${ts}-event-${i}.json`), '{}');
+    }
+
+    pruneQueue();
+
+    const remaining = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    expect(remaining.length).toBeLessThanOrEqual(MAX_FILES);
+  });
+
+  it('pruneQueue keeps oldest files below MAX_FILES', async () => {
+    const { pruneQueue, MAX_FILES } = await import('../../src/core/queue/index.js');
+
+    // Write MAX_FILES - 1 files: prune should NOT remove any
+    for (let i = 0; i < MAX_FILES - 1; i++) {
+      const ts = new Date(Date.now() + i * 1000).toISOString().replace(/[:.]/g, '-').replace('Z', 'Z');
+      writeFileSync(join(queueDir, `${ts}-event-${i}.json`), '{}');
+    }
+
+    pruneQueue();
+
+    const remaining = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    expect(remaining.length).toBe(MAX_FILES - 1);
+  });
+
+  // ── replayQueue ───────────────────────────────────────────────────────────
+
+  it('replayQueue replays events into storage and deletes queue files', async () => {
+    const { replayQueue, enqueueEvent } = await import('../../src/core/queue/index.js');
+    const { SQLiteStorage } = await import('../../src/core/storage/sqlite.js');
+
+    const dbPath = join(tempHome, 'test.db');
+    const storage = new SQLiteStorage(dbPath);
+
+    const event = {
+      session_id: 'replay-session-1',
+      project_path: '/tmp/proj',
+      timestamp: new Date().toISOString(),
+      hook_type: 'UserPromptSubmit' as const,
+      user_prompt: 'replayed',
+      event_id: '11111111-1111-4111-8111-111111111111',
+    };
+    enqueueEvent(event);
+
+    const result = await replayQueue(storage);
+
+    expect(result.replayed).toBe(1);
+    expect(result.skipped).toBe(0);
+    expect(result.dead).toBe(0);
+
+    const files = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    expect(files).toHaveLength(0);
+
+    const events = storage.queryEvents({ session_id: 'replay-session-1' });
+    expect(events).toHaveLength(1);
+    expect(events[0]!.user_prompt).toBe('replayed');
+
+    storage.close();
+  });
+
+  it('replayQueue silently skips duplicate event_id (UNIQUE constraint)', async () => {
+    const { replayQueue, enqueueEvent } = await import('../../src/core/queue/index.js');
+    const { SQLiteStorage } = await import('../../src/core/storage/sqlite.js');
+
+    const dbPath = join(tempHome, 'dedup.db');
+    const storage = new SQLiteStorage(dbPath);
+
+    const event = {
+      session_id: 'dedup-session',
+      project_path: '/tmp',
+      timestamp: new Date().toISOString(),
+      hook_type: 'PreToolUse' as const,
+      event_id: '22222222-2222-4222-8222-222222222222',
+    };
+
+    // Pre-write event into DB directly
+    storage.writeEvent(event);
+
+    // Enqueue the same event
+    enqueueEvent(event);
+
+    const result = await replayQueue(storage);
+
+    expect(result.skipped).toBe(1);
+    expect(result.replayed).toBe(0);
+    expect(result.dead).toBe(0);
+
+    // Queue file should be removed
+    const files = readdirSync(queueDir).filter((f) => f.endsWith('.json'));
+    expect(files).toHaveLength(0);
+
+    // DB still has exactly one copy
+    const events = storage.queryEvents({ session_id: 'dedup-session' });
+    expect(events).toHaveLength(1);
+
+    storage.close();
+  });
+
+  it('replayQueue moves corrupt JSON to dead-letter dir', async () => {
+    const { replayQueue } = await import('../../src/core/queue/index.js');
+    const { SQLiteStorage } = await import('../../src/core/storage/sqlite.js');
+
+    const dbPath = join(tempHome, 'corrupt.db');
+    const storage = new SQLiteStorage(dbPath);
+
+    writeFileSync(join(queueDir, '2020-01-01T00-00-00-000Z-bad.json'), 'NOT_JSON{{{');
+
+    const result = await replayQueue(storage);
+
+    expect(result.dead).toBe(1);
+    expect(result.replayed).toBe(0);
+
+    const deadFiles = readdirSync(deadDir).filter((f) => f.endsWith('.json'));
+    expect(deadFiles).toHaveLength(1);
+
+    storage.close();
+  });
+
+  it('replayQueue moves TTL-expired files to dead-letter dir', async () => {
+    const { replayQueue, TTL_DAYS } = await import('../../src/core/queue/index.js');
+    const { SQLiteStorage } = await import('../../src/core/storage/sqlite.js');
+
+    const dbPath = join(tempHome, 'ttl.db');
+    const storage = new SQLiteStorage(dbPath);
+
+    const filename = '2000-01-01T00-00-00-000Z-old-event.json';
+    const filePath = join(queueDir, filename);
+    writeFileSync(filePath, JSON.stringify({
+      session_id: 'old',
+      project_path: '/tmp',
+      timestamp: '2000-01-01T00:00:00.000Z',
+      hook_type: 'Notification',
+      event_id: '44444444-4444-4444-8444-444444444444',
+    }));
+
+    // Set mtime to TTL_DAYS + 1 days ago
+    const oldTime = new Date(Date.now() - (TTL_DAYS + 1) * 24 * 60 * 60 * 1000);
+    utimesSync(filePath, oldTime, oldTime);
+
+    const result = await replayQueue(storage);
+
+    expect(result.dead).toBe(1);
+    expect(result.replayed).toBe(0);
+
+    const deadFiles = readdirSync(deadDir).filter((f) => f.endsWith('.json'));
+    expect(deadFiles).toHaveLength(1);
+
+    storage.close();
+  });
+
+  it('replayQueue returns zeros when queue is empty', async () => {
+    const { replayQueue } = await import('../../src/core/queue/index.js');
+    const { SQLiteStorage } = await import('../../src/core/storage/sqlite.js');
+
+    const dbPath = join(tempHome, 'empty.db');
+    const storage = new SQLiteStorage(dbPath);
+
+    const result = await replayQueue(storage);
+    expect(result).toEqual({ replayed: 0, skipped: 0, dead: 0 });
+
+    storage.close();
+  });
+});