@devflow-tools/database 0.16.9 → 0.16.11

package/src/database.ts

@@ -2,6 +2,17 @@ import { NodeSqliteDatabase } from './node-sqlite';
 import { join, dirname } from 'path';
 import { existsSync, mkdirSync } from 'fs';
 import { homedir } from 'os';
+import { randomUUID } from 'crypto';
+import type {
+  EnqueueWorkInput,
+  LeaseWorkInput,
+  RequestSessionClosureInput,
+  SessionClosureRecord,
+  WorkError,
+  WorkItemRecord,
+  WorkQueueHealth,
+  WorkState,
+} from './work-queue';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -76,12 +87,21 @@ const CONTEXT_REQUIRED_SKILLS = new Set([
 ]);
 
 function toolNameMatches(event: any, expected: string): boolean {
-  if (event.blocked || event.error) return false;
+  if (!isEffectiveToolEvent(event)) return false;
   const name = String(event.mcpToolName ?? event.toolName ?? '')
     .replace(/^mcp__[^_]+__/, '');
   return name === expected;
 }
 
+function isEffectiveToolEvent(event: any): boolean {
+  if (event.blocked || event.error || event.output == null) return false;
+  if (typeof event.output === 'object') {
+    const output = event.output as Record<string, unknown>;
+    if (output.error || output.isError === true || output.success === false || output.degraded === true) return false;
+  }
+  return countTelemetryResults(event.output) > 0;
+}
+
 function obligationsForSkill(skillName: string, configured: unknown): string[] {
   const configuredTools = Array.isArray(configured)
     ? configured.filter((tool): tool is string => typeof tool === 'string' && tool.length > 0)
@@ -124,6 +144,37 @@ export interface MemoryDistillCheckpointRecord {
   createdAt: number;
 }
 
+export type MemoryTurnStatus = 'pending' | 'committed' | 'skipped';
+
+export interface MemoryTurnRecord {
+  turnId: string;
+  projectRoot: string;
+  sessionId: string;
+  promptHash: string;
+  eventId: string;
+  status: MemoryTurnStatus;
+  receiptId?: string;
+  memoryIds: string[];
+  source?: string;
+  reason?: string;
+  stopPromptedAt?: number;
+  createdAt: number;
+  decidedAt?: number;
+}
+
+export interface HookFallbackRecord {
+  id: string;
+  projectRoot: string;
+  sessionId?: string;
+  toolUseId?: string;
+  requestType: string;
+  tool: string;
+  reason: 'timeout' | 'unreachable' | 'protocol' | 'unknown';
+  durationMs: number;
+  attempts: number;
+  createdAt: number;
+}
+
 export function getGlobalDevFlowDbPath(home = homedir()): string {
   const stateDir = process.env.DEVFLOW_STATE_DIR ?? join(home, '.devflow', 'global');
   return join(stateDir, 'devflow.db');
@@ -239,6 +290,10 @@ export class DevFlowDatabase {
         total_duration INTEGER DEFAULT 0,
         mcp_compliance_rate REAL DEFAULT 0,
         missed_mcp_tools TEXT,
+        failed_tool_calls INTEGER DEFAULT 0,
+        blocked_tool_calls INTEGER DEFAULT 0,
+        fallback_count INTEGER DEFAULT 0,
+        fallback_reasons TEXT,
         created_at INTEGER DEFAULT (strftime('%s', 'now') * 1000)
       );
 
@@ -378,6 +433,89 @@ export class DevFlowDatabase {
 
       CREATE INDEX IF NOT EXISTS idx_distill_checkpoints_project
         ON devflow_memory_distill_checkpoints(project_root, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_memory_turns (
+        turn_id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        prompt_hash TEXT NOT NULL,
+        event_id TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'pending'
+          CHECK(status IN ('pending', 'committed', 'skipped')),
+        receipt_id TEXT,
+        memory_ids TEXT NOT NULL DEFAULT '[]',
+        source TEXT,
+        reason TEXT,
+        stop_prompted_at INTEGER,
+        created_at INTEGER NOT NULL,
+        decided_at INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_memory_turns_pending
+        ON devflow_memory_turns(project_root, session_id, status, created_at DESC);
+      CREATE UNIQUE INDEX IF NOT EXISTS idx_memory_turns_receipt
+        ON devflow_memory_turns(receipt_id) WHERE receipt_id IS NOT NULL;
+
+      CREATE TABLE IF NOT EXISTS devflow_hook_fallbacks (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        session_id TEXT,
+        tool_use_id TEXT,
+        request_type TEXT NOT NULL,
+        tool TEXT NOT NULL,
+        reason TEXT NOT NULL CHECK(reason IN ('timeout', 'unreachable', 'protocol', 'unknown')),
+        duration_ms INTEGER NOT NULL,
+        attempts INTEGER NOT NULL,
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_hook_fallbacks_session
+        ON devflow_hook_fallbacks(project_root, session_id, created_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_work_items (
+        id TEXT PRIMARY KEY,
+        idempotency_key TEXT NOT NULL UNIQUE,
+        kind TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT,
+        turn_id TEXT,
+        payload TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'pending'
+          CHECK(state IN ('pending', 'leased', 'completed', 'failed', 'dead_letter')),
+        attempts INTEGER NOT NULL DEFAULT 0 CHECK(attempts >= 0),
+        max_attempts INTEGER NOT NULL DEFAULT 5 CHECK(max_attempts > 0),
+        lease_owner TEXT,
+        lease_expires_at INTEGER,
+        next_attempt_at INTEGER NOT NULL,
+        error_category TEXT,
+        error_message TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        completed_at INTEGER
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_work_items_ready
+        ON devflow_work_items(project_root, state, next_attempt_at, created_at);
+      CREATE INDEX IF NOT EXISTS idx_work_items_expired_leases
+        ON devflow_work_items(project_root, state, lease_expires_at);
+      CREATE INDEX IF NOT EXISTS idx_work_items_completed
+        ON devflow_work_items(project_root, completed_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_session_closures (
+        session_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'active'
+          CHECK(state IN ('active', 'closing', 'closed', 'closed_with_pending_work')),
+        receipt_id TEXT NOT NULL UNIQUE,
+        work_item_id TEXT,
+        pending_work_count INTEGER NOT NULL DEFAULT 0 CHECK(pending_work_count >= 0),
+        requested_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        closed_at INTEGER,
+        PRIMARY KEY (project_root, session_id)
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_session_closures_state
+        ON devflow_session_closures(project_root, state, updated_at DESC);
     `);
 
     // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
@@ -394,6 +532,10 @@ export class DevFlowDatabase {
     try { this.db.exec('ALTER TABLE tool_call_events ADD COLUMN tool_use_id TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE sessions ADD COLUMN metadata TEXT'); } catch {}
     try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN metadata TEXT'); } catch {}
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN failed_tool_calls INTEGER DEFAULT 0'); } catch {}
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN blocked_tool_calls INTEGER DEFAULT 0'); } catch {}
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN fallback_count INTEGER DEFAULT 0'); } catch {}
+    try { this.db.exec('ALTER TABLE skill_executions ADD COLUMN fallback_reasons TEXT'); } catch {}
     try {
       this.db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_events_session_tool_use
         ON tool_call_events(session_id, tool_use_id) WHERE tool_use_id IS NOT NULL`);
@@ -925,6 +1067,10 @@ export class DevFlowDatabase {
       totalDuration: row.total_duration,
       mcpComplianceRate: row.mcp_compliance_rate,
       missedMcpTools: row.missed_mcp_tools ? JSON.parse(row.missed_mcp_tools) : null,
+      failedToolCalls: row.failed_tool_calls ?? 0,
+      blockedToolCalls: row.blocked_tool_calls ?? 0,
+      fallbackCount: row.fallback_count ?? 0,
+      fallbackReasons: row.fallback_reasons ? JSON.parse(row.fallback_reasons) : [],
       createdAt: row.created_at,
       metadata: row.metadata ? JSON.parse(row.metadata) : null,
     };
@@ -936,6 +1082,10 @@ export class DevFlowDatabase {
     totalDuration?: number;
     mcpComplianceRate?: number;
     missedMcpTools?: string[];
+    failedToolCalls?: number;
+    blockedToolCalls?: number;
+    fallbackCount?: number;
+    fallbackReasons?: string[];
     totalToolCalls?: number;
     mcpToolCalls?: number;
     directToolCalls?: number;
@@ -950,6 +1100,10 @@ export class DevFlowDatabase {
     if (updates.totalDuration !== undefined) { sets.push('total_duration = ?'); values.push(updates.totalDuration); }
     if (updates.mcpComplianceRate !== undefined) { sets.push('mcp_compliance_rate = ?'); values.push(updates.mcpComplianceRate); }
     if (updates.missedMcpTools !== undefined) { sets.push('missed_mcp_tools = ?'); values.push(JSON.stringify(updates.missedMcpTools)); }
+    if (updates.failedToolCalls !== undefined) { sets.push('failed_tool_calls = ?'); values.push(updates.failedToolCalls); }
+    if (updates.blockedToolCalls !== undefined) { sets.push('blocked_tool_calls = ?'); values.push(updates.blockedToolCalls); }
+    if (updates.fallbackCount !== undefined) { sets.push('fallback_count = ?'); values.push(updates.fallbackCount); }
+    if (updates.fallbackReasons !== undefined) { sets.push('fallback_reasons = ?'); values.push(JSON.stringify(updates.fallbackReasons)); }
     if (updates.totalToolCalls !== undefined) { sets.push('total_tool_calls = ?'); values.push(updates.totalToolCalls); }
     if (updates.mcpToolCalls !== undefined) { sets.push('mcp_tool_calls = ?'); values.push(updates.mcpToolCalls); }
     if (updates.directToolCalls !== undefined) { sets.push('direct_tool_calls = ?'); values.push(updates.directToolCalls); }
@@ -988,6 +1142,11 @@ export class DevFlowDatabase {
       subagentCount: row.subagent_count,
       totalDuration: row.total_duration,
       mcpComplianceRate: row.mcp_compliance_rate,
+      missedMcpTools: row.missed_mcp_tools ? JSON.parse(row.missed_mcp_tools) : [],
+      failedToolCalls: row.failed_tool_calls ?? 0,
+      blockedToolCalls: row.blocked_tool_calls ?? 0,
+      fallbackCount: row.fallback_count ?? 0,
+      fallbackReasons: row.fallback_reasons ? JSON.parse(row.fallback_reasons) : [],
       metadata: row.metadata ? JSON.parse(row.metadata) : null,
     }));
   }
@@ -1176,9 +1335,39 @@ export class DevFlowDatabase {
       FROM tool_call_events WHERE execution_id = ?
     `).get(executionId) as any;
     const execution = this.getSkillExecution(executionId);
+    const events = this.listToolCallEvents(executionId);
     const total = Number(row?.total ?? 0);
     const mcp = Number(row?.mcp ?? 0);
     const obligation = this.getExecutionObligationCompliance(executionId);
+    const failures = events.filter(event => Boolean(event.error) && !event.blocked);
+    const blocked = events.filter(event => event.blocked);
+    const directFallbacks = events.filter(event => event.mcpFallback);
+    const hookFallbacks = execution?.sessionId
+      ? this.listHookFallbacks({
+          sessionId: execution.sessionId,
+          from: execution.startedAt,
+          to: finishedAt,
+        })
+      : [];
+    const fallbackReasons = [...new Set([
+      ...directFallbacks.map(() => 'direct_tool_during_context'),
+      ...hookFallbacks.map(fallback => `daemon_${fallback.reason}`),
+    ])];
+    const eventReceiptIds = collectCanonicalReceiptIds(events.map(event => event.output));
+    const suppliedMemoryReceiptIds = Array.isArray(metadata?.memoryReceiptIds)
+      ? metadata.memoryReceiptIds.filter((id): id is string => typeof id === 'string')
+      : [];
+    const suppliedDistillReceiptIds = Array.isArray(metadata?.distillReceiptIds)
+      ? metadata.distillReceiptIds.filter((id): id is string => typeof id === 'string')
+      : [];
+    const memoryReceiptIds = [...new Set([
+      ...suppliedMemoryReceiptIds,
+      ...eventReceiptIds.filter(id => id.startsWith('memory-receipt:')),
+    ])];
+    const distillReceiptIds = [...new Set([
+      ...suppliedDistillReceiptIds,
+      ...eventReceiptIds.filter(id => id.startsWith('distill-receipt:')),
+    ])];
     this.updateSkillExecution(executionId, {
       status,
       finishedAt,
@@ -1190,10 +1379,46 @@ export class DevFlowDatabase {
         ? Math.max(0, finishedAt - execution.startedAt)
         : row?.first_at != null && row?.last_at != null ? row.last_at - row.first_at : 0,
       mcpComplianceRate: obligation.rate,
-      metadata,
+      missedMcpTools: obligation.missedTools,
+      failedToolCalls: failures.length,
+      blockedToolCalls: blocked.length,
+      fallbackCount: directFallbacks.length + hookFallbacks.length,
+      fallbackReasons,
+      metadata: {
+        ...(metadata ?? {}),
+        applicableObligations: obligation.applicable,
+        satisfiedObligations: obligation.satisfied,
+        missedTools: obligation.missedTools,
+        actualFailureCount: failures.length,
+        blockedCount: blocked.length,
+        fallbackCount: directFallbacks.length + hookFallbacks.length,
+        fallbackReasons,
+        memoryReceiptIds,
+        distillReceiptIds,
+      },
     });
   }
 
+  reconcileRunningSkillExecutionsForSession(
+    sessionId: string,
+    finishedAt = Date.now(),
+    metadata?: Record<string, unknown>,
+  ): any[] {
+    const rows = this.db.prepare(`
+      SELECT execution_id
+      FROM skill_executions
+      WHERE session_id = ? AND status = 'running'
+      ORDER BY started_at ASC
+    `).all(sessionId) as Array<{ execution_id: string }>;
+    const reconciled: any[] = [];
+    for (const row of rows) {
+      this.reconcileSkillExecution(row.execution_id, 'completed', finishedAt, metadata);
+      const execution = this.getSkillExecution(row.execution_id);
+      if (execution) reconciled.push(execution);
+    }
+    return reconciled;
+  }
+
   getExecutionObligationCompliance(executionId: string): {
     rate: number;
     applicable: number;
@@ -1214,7 +1439,7 @@ export class DevFlowDatabase {
       if (obligation.endsWith(':domain')) {
         const family = obligation.slice(0, -':domain'.length);
         return events.some((event) => {
-          if (event.blocked || event.error || !event.isMcpTool) return false;
+          if (!event.isMcpTool || !isEffectiveToolEvent(event)) return false;
           const name = String(event.mcpToolName ?? event.toolName ?? '')
             .replace(/^mcp__[^_]+__/, '');
           return name.startsWith(`${family}_`);
@@ -1742,6 +1967,403 @@ export class DevFlowDatabase {
     };
   }
 
+  // ---- Durable Work Queue ----
+
+  enqueueWork(input: EnqueueWorkInput): WorkItemRecord {
+    if (!input.idempotencyKey.trim()) throw new Error('Work idempotency key is required');
+    if (!input.projectRoot.trim()) throw new Error('Work project root is required');
+    const maxAttempts = input.maxAttempts ?? 5;
+    if (!Number.isSafeInteger(maxAttempts) || maxAttempts <= 0) {
+      throw new Error('Work maxAttempts must be a positive safe integer');
+    }
+
+    const createdAt = Date.now();
+    const nextAttemptAt = input.nextAttemptAt ?? createdAt;
+    if (!Number.isSafeInteger(nextAttemptAt)) {
+      throw new Error('Work nextAttemptAt must be a safe integer');
+    }
+
+    const row = this.db.prepare(`
+      INSERT INTO devflow_work_items (
+        id, idempotency_key, kind, project_root, session_id, turn_id, payload,
+        state, attempts, max_attempts, lease_owner, lease_expires_at,
+        next_attempt_at, error_category, error_message, created_at, updated_at, completed_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, 'pending', 0, ?, NULL, NULL, ?, NULL, NULL, ?, ?, NULL)
+      ON CONFLICT(idempotency_key) DO UPDATE SET
+        state = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN 'failed'
+          ELSE devflow_work_items.state
+        END,
+        max_attempts = MAX(devflow_work_items.max_attempts, excluded.max_attempts),
+        next_attempt_at = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN excluded.next_attempt_at
+          ELSE devflow_work_items.next_attempt_at
+        END,
+        error_category = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN NULL
+          ELSE devflow_work_items.error_category
+        END,
+        error_message = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN NULL
+          ELSE devflow_work_items.error_message
+        END,
+        updated_at = CASE
+          WHEN devflow_work_items.state = 'dead_letter'
+            AND excluded.max_attempts > devflow_work_items.attempts
+          THEN excluded.updated_at
+          ELSE devflow_work_items.updated_at
+        END
+      RETURNING *
+    `).get(
+      randomUUID(),
+      input.idempotencyKey,
+      input.kind,
+      input.projectRoot,
+      input.sessionId ?? null,
+      input.turnId ?? null,
+      JSON.stringify(input.payload ?? null),
+      maxAttempts,
+      nextAttemptAt,
+      createdAt,
+      createdAt,
+    ) as any;
+
+    return this.mapWorkItem(row);
+  }
+
+  getWorkByIdempotencyKey(idempotencyKey: string): WorkItemRecord | null {
+    const row = this.db.prepare(
+      'SELECT * FROM devflow_work_items WHERE idempotency_key = ?',
+    ).get(idempotencyKey) as any;
+    return row ? this.mapWorkItem(row) : null;
+  }
+
+  requestSessionClosure(input: RequestSessionClosureInput): SessionClosureRecord {
+    if (!input.sessionId.trim()) throw new Error('Session closure requires a session ID');
+    if (!input.projectRoot.trim()) throw new Error('Session closure requires a project root');
+    if (!input.receiptId.trim()) throw new Error('Session closure requires a receipt ID');
+
+    return this.db.transaction(() => {
+      const now = Date.now();
+      this.db.prepare(`
+        INSERT INTO devflow_session_closures (
+          session_id, project_root, state, receipt_id, pending_work_count,
+          requested_at, updated_at
+        ) VALUES (?, ?, 'active', ?, 0, ?, ?)
+        ON CONFLICT(project_root, session_id) DO NOTHING
+      `).run(input.sessionId, input.projectRoot, input.receiptId, now, now);
+
+      const work = this.enqueueWork({
+        idempotencyKey: input.receiptId,
+        kind: 'session.finalize',
+        projectRoot: input.projectRoot,
+        sessionId: input.sessionId,
+        payload: input.payload,
+        maxAttempts: input.maxAttempts,
+      });
+      const pending = this.db.prepare(`
+        SELECT COUNT(*) AS count
+        FROM devflow_work_items
+        WHERE project_root = ? AND session_id = ?
+          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+      `).get(input.projectRoot, input.sessionId) as { count?: number };
+      const pendingWorkCount = Number(pending?.count ?? 0);
+      this.db.prepare(`
+        UPDATE devflow_session_closures
+        SET state = CASE
+              WHEN state IN ('closed', 'closed_with_pending_work')
+                THEN CASE WHEN ? > 0 THEN 'closed_with_pending_work' ELSE 'closed' END
+              WHEN ? = 'completed'
+                THEN CASE WHEN ? > 0 THEN 'closed_with_pending_work' ELSE 'closed' END
+              WHEN ? = 'dead_letter' THEN 'closed_with_pending_work'
+              ELSE 'closing'
+            END,
+            work_item_id = COALESCE(work_item_id, ?),
+            pending_work_count = ?,
+            closed_at = CASE WHEN ? = 'completed' THEN ? ELSE closed_at END,
+            updated_at = ?
+        WHERE project_root = ? AND session_id = ?
+      `).run(
+        pendingWorkCount,
+        work.state,
+        pendingWorkCount,
+        work.state,
+        work.id,
+        pendingWorkCount,
+        work.state,
+        now,
+        now,
+        input.projectRoot,
+        input.sessionId,
+      );
+      return this.getSessionClosure(input.projectRoot, input.sessionId)!;
+    });
+  }
+
+  getSessionClosure(projectRoot: string, sessionId: string): SessionClosureRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_session_closures
+      WHERE project_root = ? AND session_id = ?
+    `).get(projectRoot, sessionId) as any;
+    return row ? this.mapSessionClosure(row) : null;
+  }
+
+  completeSessionClosure(
+    projectRoot: string,
+    sessionId: string,
+    excludingWorkItemId?: string,
+    closedAt = Date.now(),
+  ): SessionClosureRecord {
+    const pending = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_work_items
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND (? IS NULL OR id <> ?)
+    `).get(projectRoot, sessionId, excludingWorkItemId ?? null, excludingWorkItemId ?? null) as { count?: number };
+    const pendingWorkCount = Number(pending?.count ?? 0);
+    const state = pendingWorkCount > 0 ? 'closed_with_pending_work' : 'closed';
+    this.db.prepare(`
+      UPDATE devflow_session_closures
+      SET state = ?, pending_work_count = ?, closed_at = ?, updated_at = ?
+      WHERE project_root = ? AND session_id = ? AND state = 'closing'
+    `).run(state, pendingWorkCount, closedAt, closedAt, projectRoot, sessionId);
+    const closure = this.getSessionClosure(projectRoot, sessionId);
+    if (!closure) throw new Error(`Session closure ${sessionId} does not exist`);
+    return closure;
+  }
+
+  listSessionClosures(projectRoot: string, limit = 100): SessionClosureRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_session_closures
+      WHERE project_root = ?
+      ORDER BY updated_at DESC
+      LIMIT ?
+    `).all(projectRoot, Math.max(1, Math.min(limit, 1_000))) as any[];
+    return rows.map(row => this.mapSessionClosure(row));
+  }
+
+  leaseWork(input: LeaseWorkInput): WorkItemRecord[] {
+    if (!input.owner.trim()) throw new Error('Work lease owner is required');
+    if (!Number.isFinite(input.limit) || input.limit <= 0) return [];
+    if (!Number.isSafeInteger(input.leaseMs) || input.leaseMs <= 0) {
+      throw new Error('Work leaseMs must be a positive safe integer');
+    }
+    if (input.kinds?.length === 0) return [];
+
+    const now = input.now ?? Date.now();
+    const leaseExpiresAt = now + input.leaseMs;
+    if (!Number.isSafeInteger(now) || !Number.isSafeInteger(leaseExpiresAt)) {
+      throw new Error('Work lease timestamps must be safe integers');
+    }
+    const limit = Math.min(Math.floor(input.limit), 1_000);
+    const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+    const kindClause = kinds
+      ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
+      : '';
+
+    this.db.exec('BEGIN IMMEDIATE');
+    try {
+      const candidates = this.db.prepare(`
+        SELECT id, state
+        FROM devflow_work_items
+        WHERE project_root = ?
+          AND state IN ('pending', 'failed')
+          AND lease_owner IS NULL
+          AND lease_expires_at IS NULL
+          AND next_attempt_at <= ?
+          AND attempts < max_attempts
+          ${kindClause}
+        ORDER BY next_attempt_at ASC, created_at ASC, id ASC
+        LIMIT ?
+      `).all(input.projectRoot, now, ...(kinds ?? []), limit) as Array<{
+        id: string;
+        state: WorkState;
+      }>;
+
+      const leased: WorkItemRecord[] = [];
+      for (const candidate of candidates) {
+        const result = this.db.prepare(`
+          UPDATE devflow_work_items
+          SET state = 'leased', attempts = attempts + 1, lease_owner = ?,
+              lease_expires_at = ?, updated_at = ?
+          WHERE id = ? AND project_root = ? AND state = ?
+            AND lease_owner IS NULL AND lease_expires_at IS NULL
+            AND next_attempt_at <= ? AND attempts < max_attempts
+        `).run(
+          input.owner,
+          leaseExpiresAt,
+          now,
+          candidate.id,
+          input.projectRoot,
+          candidate.state,
+          now,
+        );
+        if (result.changes === 1) {
+          const row = this.db.prepare('SELECT * FROM devflow_work_items WHERE id = ?')
+            .get(candidate.id) as any;
+          leased.push(this.mapWorkItem(row));
+        }
+      }
+
+      this.db.exec('COMMIT');
+      return leased;
+    } catch (error) {
+      try { this.db.exec('ROLLBACK'); } catch {}
+      throw error;
+    }
+  }
+
+  completeWork(id: string, owner: string, now = Date.now()): boolean {
+    const work = this.db.prepare(`
+      SELECT project_root, session_id FROM devflow_work_items WHERE id = ?
+    `).get(id) as { project_root?: string; session_id?: string } | undefined;
+    const completed = this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'completed', lease_owner = NULL, lease_expires_at = NULL,
+          updated_at = ?, completed_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(now, now, id, owner).changes === 1;
+    if (completed && work?.project_root && work.session_id) {
+      this.refreshClosedSessionClosure(work.project_root, work.session_id, now);
+    }
+    return completed;
+  }
+
+  retryWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean {
+    const updatedAt = Date.now();
+    return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = CASE WHEN attempts >= max_attempts THEN 'dead_letter' ELSE 'failed' END,
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(
+      nextAttemptAt,
+      error.category,
+      error.message,
+      updatedAt,
+      id,
+      owner,
+    ).changes === 1;
+  }
+
+  deadLetterWork(id: string, owner: string, error: WorkError): boolean {
+    return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = 'dead_letter', lease_owner = NULL, lease_expires_at = NULL,
+          error_category = ?, error_message = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(error.category, error.message, Date.now(), id, owner).changes === 1;
+  }
+
+  recoverExpiredWork(projectRoot: string, now = Date.now()): number {
+    return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET state = CASE WHEN attempts >= max_attempts THEN 'dead_letter' ELSE 'failed' END,
+          lease_owner = NULL, lease_expires_at = NULL, next_attempt_at = ?,
+          error_category = 'lease_expired',
+          error_message = 'Work lease expired before completion',
+          updated_at = ?
+      WHERE project_root = ? AND state = 'leased' AND lease_expires_at <= ?
+    `).run(now, now, projectRoot, now).changes;
+  }
+
+  getWorkQueueHealth(projectRoot: string, now = Date.now()): WorkQueueHealth {
+    const row = this.db.prepare(`
+      SELECT
+        COALESCE(SUM(CASE WHEN state IN ('pending', 'leased', 'failed') THEN 1 ELSE 0 END), 0) AS queue_depth,
+        COALESCE(SUM(CASE WHEN state = 'pending' THEN 1 ELSE 0 END), 0) AS pending,
+        COALESCE(SUM(CASE WHEN state = 'leased' THEN 1 ELSE 0 END), 0) AS leased,
+        COALESCE(SUM(CASE WHEN state = 'failed' THEN 1 ELSE 0 END), 0) AS failed,
+        COALESCE(SUM(CASE WHEN state = 'leased' AND lease_expires_at <= ? THEN 1 ELSE 0 END), 0) AS expired_leases,
+        COALESCE(SUM(CASE WHEN state = 'dead_letter' THEN 1 ELSE 0 END), 0) AS dead_letters,
+        MIN(CASE WHEN state IN ('pending', 'leased', 'failed') THEN created_at END) AS oldest_pending_at,
+        MAX(CASE WHEN state = 'completed' THEN completed_at END) AS last_successful_drain_at
+      FROM devflow_work_items
+      WHERE project_root = ?
+    `).get(now, projectRoot) as any;
+    const oldestPendingAt = row.oldest_pending_at == null
+      ? undefined
+      : Number(row.oldest_pending_at);
+
+    return {
+      projectRoot,
+      queueDepth: Number(row.queue_depth),
+      pending: Number(row.pending),
+      leased: Number(row.leased),
+      failed: Number(row.failed),
+      expiredLeases: Number(row.expired_leases),
+      deadLetters: Number(row.dead_letters),
+      oldestPendingAgeMs: oldestPendingAt === undefined ? 0 : Math.max(0, now - oldestPendingAt),
+      lastSuccessfulDrainAt: row.last_successful_drain_at == null
+        ? undefined
+        : Number(row.last_successful_drain_at),
+    };
+  }
+
+  private mapWorkItem(row: any): WorkItemRecord {
+    return {
+      id: row.id,
+      idempotencyKey: row.idempotency_key,
+      kind: row.kind,
+      projectRoot: row.project_root,
+      sessionId: row.session_id ?? undefined,
+      turnId: row.turn_id ?? undefined,
+      payload: parseJson(row.payload),
+      state: row.state,
+      attempts: Number(row.attempts),
+      maxAttempts: Number(row.max_attempts),
+      leaseOwner: row.lease_owner ?? undefined,
+      leaseExpiresAt: row.lease_expires_at == null ? undefined : Number(row.lease_expires_at),
+      nextAttemptAt: Number(row.next_attempt_at),
+      errorCategory: row.error_category ?? undefined,
+      errorMessage: row.error_message ?? undefined,
+      createdAt: Number(row.created_at),
+      updatedAt: Number(row.updated_at),
+      completedAt: row.completed_at == null ? undefined : Number(row.completed_at),
+    };
+  }
+
+  private mapSessionClosure(row: any): SessionClosureRecord {
+    return {
+      sessionId: row.session_id,
+      projectRoot: row.project_root,
+      state: row.state,
+      receiptId: row.receipt_id,
+      workItemId: row.work_item_id ?? undefined,
+      pendingWorkCount: Number(row.pending_work_count),
+      requestedAt: Number(row.requested_at),
+      updatedAt: Number(row.updated_at),
+      closedAt: row.closed_at == null ? undefined : Number(row.closed_at),
+    };
+  }
+
+  private refreshClosedSessionClosure(projectRoot: string, sessionId: string, now: number): void {
+    const pending = this.db.prepare(`
+      SELECT COUNT(*) AS count
+      FROM devflow_work_items
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+    `).get(projectRoot, sessionId) as { count?: number };
+    const pendingWorkCount = Number(pending?.count ?? 0);
+    this.db.prepare(`
+      UPDATE devflow_session_closures
+      SET state = CASE WHEN ? = 0 THEN 'closed' ELSE 'closed_with_pending_work' END,
+          pending_work_count = ?, updated_at = ?
+      WHERE project_root = ? AND session_id = ?
+        AND state IN ('closed', 'closed_with_pending_work')
+    `).run(pendingWorkCount, pendingWorkCount, now, projectRoot, sessionId);
+  }
+
   // ---- Hook Lifecycle ----
 
   getHookReceipt(projectRoot: string): HookReceiptRecord | null {
@@ -1853,6 +2475,183 @@ export class DevFlowDatabase {
       .run(now).changes;
   }
 
+  beginMemoryTurn(input: Omit<MemoryTurnRecord, 'status' | 'memoryIds'>): MemoryTurnRecord {
+    this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_memory_turns
+        (turn_id, project_root, session_id, prompt_hash, event_id, status, memory_ids, created_at)
+      VALUES (?, ?, ?, ?, ?, 'pending', '[]', ?)
+    `).run(
+      input.turnId,
+      input.projectRoot,
+      input.sessionId,
+      input.promptHash,
+      input.eventId,
+      input.createdAt,
+    );
+    return this.getMemoryTurn(input.turnId)!;
+  }
+
+  getMemoryTurn(turnId: string): MemoryTurnRecord | null {
+    const row = this.db.prepare(
+      'SELECT * FROM devflow_memory_turns WHERE turn_id = ?',
+    ).get(turnId) as any;
+    return row ? this.mapMemoryTurn(row) : null;
+  }
+
+  getPendingMemoryTurn(projectRoot: string, sessionId: string): MemoryTurnRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_memory_turns
+      WHERE project_root = ? AND session_id = ? AND status = 'pending'
+      ORDER BY created_at DESC LIMIT 1
+    `).get(projectRoot, sessionId) as any;
+    return row ? this.mapMemoryTurn(row) : null;
+  }
+
+  commitMemoryTurn(input: {
+    turnId: string;
+    receiptId: string;
+    memoryIds: string[];
+    source: string;
+    reason?: string;
+    decidedAt?: number;
+  }): MemoryTurnRecord {
+    this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET status = 'committed', receipt_id = ?, memory_ids = ?, source = ?, reason = ?, decided_at = ?
+      WHERE turn_id = ? AND status = 'pending'
+    `).run(
+      input.receiptId,
+      JSON.stringify([...new Set(input.memoryIds)]),
+      input.source,
+      input.reason ?? null,
+      input.decidedAt ?? Date.now(),
+      input.turnId,
+    );
+    const turn = this.getMemoryTurn(input.turnId);
+    if (!turn || turn.status !== 'committed') {
+      throw new Error(`Memory turn ${input.turnId} is not pending or does not exist`);
+    }
+    return turn;
+  }
+
+  skipMemoryTurn(input: {
+    turnId: string;
+    receiptId: string;
+    reason: string;
+    decidedAt?: number;
+  }): MemoryTurnRecord {
+    this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET status = 'skipped', receipt_id = ?, memory_ids = '[]', source = 'host_skip',
+          reason = ?, decided_at = ?
+      WHERE turn_id = ? AND status = 'pending'
+    `).run(
+      input.receiptId,
+      input.reason,
+      input.decidedAt ?? Date.now(),
+      input.turnId,
+    );
+    const turn = this.getMemoryTurn(input.turnId);
+    if (!turn || turn.status !== 'skipped') {
+      throw new Error(`Memory turn ${input.turnId} is not pending or does not exist`);
+    }
+    return turn;
+  }
+
+  markMemoryTurnStopPrompted(turnId: string, promptedAt = Date.now()): boolean {
+    return this.db.prepare(`
+      UPDATE devflow_memory_turns SET stop_prompted_at = ?
+      WHERE turn_id = ? AND status = 'pending' AND stop_prompted_at IS NULL
+    `).run(promptedAt, turnId).changes === 1;
+  }
+
+  listMemoryTurns(projectRoot: string, sessionId?: string, limit = 50): MemoryTurnRecord[] {
+    const rows = (sessionId
+      ? this.db.prepare(`SELECT * FROM devflow_memory_turns
+          WHERE project_root = ? AND session_id = ? ORDER BY created_at DESC LIMIT ?`)
+        .all(projectRoot, sessionId, limit)
+      : this.db.prepare(`SELECT * FROM devflow_memory_turns
+          WHERE project_root = ? ORDER BY created_at DESC LIMIT ?`)
+        .all(projectRoot, limit)) as any[];
+    return rows.map(row => this.mapMemoryTurn(row));
+  }
+
+  insertHookFallback(record: HookFallbackRecord): boolean {
+    return this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_hook_fallbacks
+        (id, project_root, session_id, tool_use_id, request_type, tool, reason,
+         duration_ms, attempts, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      record.id,
+      record.projectRoot,
+      record.sessionId ?? null,
+      record.toolUseId ?? null,
+      record.requestType,
+      record.tool,
+      record.reason,
+      record.durationMs,
+      record.attempts,
+      record.createdAt,
+    ).changes === 1;
+  }
+
+  listHookFallbacks(filter: {
+    projectRoot?: string;
+    sessionId?: string;
+    from?: number;
+    to?: number;
+    limit?: number;
+  } = {}): HookFallbackRecord[] {
+    const conditions: string[] = [];
+    const values: unknown[] = [];
+    if (filter.projectRoot) { conditions.push('project_root = ?'); values.push(filter.projectRoot); }
+    if (filter.sessionId) { conditions.push('session_id = ?'); values.push(filter.sessionId); }
+    if (filter.from !== undefined) { conditions.push('created_at >= ?'); values.push(filter.from); }
+    if (filter.to !== undefined) { conditions.push('created_at <= ?'); values.push(filter.to); }
+    values.push(Math.max(1, Math.min(filter.limit ?? 500, 5_000)));
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_hook_fallbacks
+      ${conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''}
+      ORDER BY created_at DESC LIMIT ?
+    `).all(...values) as any[];
+    return rows.map(row => ({
+      id: row.id,
+      projectRoot: row.project_root,
+      sessionId: row.session_id ?? undefined,
+      toolUseId: row.tool_use_id ?? undefined,
+      requestType: row.request_type,
+      tool: row.tool,
+      reason: row.reason,
+      durationMs: row.duration_ms,
+      attempts: row.attempts,
+      createdAt: row.created_at,
+    }));
+  }
+
+  private mapMemoryTurn(row: any): MemoryTurnRecord {
+    let memoryIds: string[] = [];
+    try {
+      const parsed: unknown = JSON.parse(row.memory_ids ?? '[]');
+      if (Array.isArray(parsed)) memoryIds = parsed.filter((id): id is string => typeof id === 'string');
+    } catch {}
+    return {
+      turnId: row.turn_id,
+      projectRoot: row.project_root,
+      sessionId: row.session_id,
+      promptHash: row.prompt_hash,
+      eventId: row.event_id,
+      status: row.status,
+      receiptId: row.receipt_id ?? undefined,
+      memoryIds,
+      source: row.source ?? undefined,
+      reason: row.reason ?? undefined,
+      stopPromptedAt: row.stop_prompted_at ?? undefined,
+      createdAt: row.created_at,
+      decidedAt: row.decided_at ?? undefined,
+    };
+  }
+
   recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void {
     this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints
@@ -1945,3 +2744,29 @@ function countTelemetryResults(value: unknown, depth = 0): number {
   if (record.error) return 0;
   return Object.keys(record).length > 0 ? 1 : 0;
 }
+
+function collectCanonicalReceiptIds(values: unknown[]): string[] {
+  const receiptIds = new Set<string>();
+  const visit = (value: unknown, depth: number): void => {
+    if (depth > 5 || value == null) return;
+    if (typeof value === 'string') {
+      if (value.startsWith('memory-receipt:') || value.startsWith('distill-receipt:')) {
+        receiptIds.add(value);
+        return;
+      }
+      if ((value.startsWith('{') || value.startsWith('[')) && value.length < 1_000_000) {
+        try { visit(JSON.parse(value), depth + 1); } catch {}
+      }
+      return;
+    }
+    if (Array.isArray(value)) {
+      value.forEach(item => visit(item, depth + 1));
+      return;
+    }
+    if (typeof value === 'object') {
+      Object.values(value as Record<string, unknown>).forEach(item => visit(item, depth + 1));
+    }
+  };
+  values.forEach(value => visit(value, 0));
+  return [...receiptIds];
+}