@devflow-tools/database 0.16.9 → 0.16.10

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.10](https://github.com/shilongfeicool/dev-flow/compare/v0.16.9...v0.16.10) (2026-07-24)
+
+
+### Bug Fixes
+
+* **telemetry:** persist compliance failure facts ([fcb5a8b](https://github.com/shilongfeicool/dev-flow/commit/fcb5a8b4db37fc545927262ae841669395491b06))
+
+
+### Features
+
+* **memory:** add canonical turn and explicit receipts ([eb3e178](https://github.com/shilongfeicool/dev-flow/commit/eb3e1786e17f5dbc2c4e12e4fa788af7095d335e))
+
+
+
+
+
 ## [0.16.9](https://github.com/shilongfeicool/dev-flow/compare/v0.16.8...v0.16.9) (2026-07-23)
 
 **Note:** Version bump only for package @devflow-tools/database

package/__tests__/database.memory-turn-receipts.test.ts

@@ -0,0 +1,71 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database';
+
+describe('DevFlowDatabase memory turn receipts', () => {
+  let directory: string;
+  let database: DevFlowDatabase;
+
+  beforeEach(() => {
+    directory = mkdtempSync(join(tmpdir(), 'devflow-memory-turn-'));
+    database = new DevFlowDatabase(directory);
+  });
+
+  afterEach(() => {
+    database.close();
+    rmSync(directory, { recursive: true, force: true });
+  });
+
+  it('commits a pending turn with one canonical receipt', () => {
+    database.beginMemoryTurn({
+      turnId: 'turn:1',
+      projectRoot: '/project',
+      sessionId: 'session-1',
+      promptHash: 'hash',
+      eventId: 'event-1',
+      createdAt: 100,
+    });
+
+    const committed = database.commitMemoryTurn({
+      turnId: 'turn:1',
+      receiptId: 'memory-receipt:1',
+      memoryIds: ['memory-1'],
+      source: 'explicit_intent',
+      decidedAt: 200,
+    });
+
+    expect(committed).toMatchObject({
+      status: 'committed',
+      receiptId: 'memory-receipt:1',
+      memoryIds: ['memory-1'],
+      stopPromptedAt: undefined,
+    });
+    expect(database.getPendingMemoryTurn('/project', 'session-1')).toBeNull();
+  });
+
+  it('marks a pending Stop prompt only once and supports skip receipts', () => {
+    database.beginMemoryTurn({
+      turnId: 'turn:2',
+      projectRoot: '/project',
+      sessionId: 'session-1',
+      promptHash: 'hash-2',
+      eventId: 'event-2',
+      createdAt: 300,
+    });
+
+    expect(database.markMemoryTurnStopPrompted('turn:2', 350)).toBe(true);
+    expect(database.markMemoryTurnStopPrompted('turn:2', 360)).toBe(false);
+    expect(database.skipMemoryTurn({
+      turnId: 'turn:2',
+      receiptId: 'memory-receipt:2',
+      reason: 'transient request',
+      decidedAt: 400,
+    })).toMatchObject({
+      status: 'skipped',
+      reason: 'transient request',
+      stopPromptedAt: 350,
+    });
+  });
+});

package/__tests__/database.skill-executions.test.ts

@@ -154,19 +154,19 @@ describe('DevFlowDatabase - Skill Executions', () => {
       eventId: 'evt_context_1', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
       isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
-      mcpFallback: false, input: {}, duration: 20, blocked: false,
+      mcpFallback: false, input: {}, output: { files: ['src/App.tsx'] }, duration: 20, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_001', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__react_diagnose_bug', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-1' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_002', executionId: 'exec_001', timestamp: Date.now(),
       toolName: 'mcp__devflow__react_review_hooks', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-2' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_003', executionId: 'exec_001', timestamp: Date.now(),
@@ -186,13 +186,13 @@ describe('DevFlowDatabase - Skill Executions', () => {
       eventId: 'evt_context_2', executionId: 'exec_002', timestamp: Date.now(),
       toolName: 'mcp__devflow__get_project_context', toolType: 'mcp',
       isMcpTool: true, mcpToolName: 'get_project_context', mcpEnforced: true,
-      mcpFallback: false, input: {}, duration: 20, blocked: false,
+      mcpFallback: false, input: {}, output: { files: ['src/App.vue'] }, duration: 20, blocked: false,
     });
     db.insertToolCallEvent({
       eventId: 'evt_004', executionId: 'exec_002', timestamp: Date.now(),
       toolName: 'mcp__devflow__vue_diagnose_bug', toolType: 'mcp',
       isMcpTool: true, mcpEnforced: true, mcpFallback: false,
-      input: {}, tokensUsed: 100, duration: 500, blocked: false,
+      input: {}, output: { findings: [{ id: 'finding-vue' }] }, tokensUsed: 100, duration: 500, blocked: false,
     });
 
     const compliance = db.getMcpCompliance();
@@ -204,6 +204,61 @@ describe('DevFlowDatabase - Skill Executions', () => {
     expect(compliance.mcpCallShare).toBeCloseTo(83.33, 1);
   });
 
+  it('persists missed tools, actual failures, and fallback reasons on reconciliation', () => {
+    db.ensureSession({ id: 'session-facts', projectRoot: '/project', startedAt: 100 });
+    db.insertSkillExecution({
+      executionId: 'exec-facts',
+      sessionId: 'session-facts',
+      skillName: 'devflow:react',
+      startedAt: 100,
+      status: 'running',
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-failed', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 150,
+      toolName: 'mcp__devflow__get_project_context', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'get_project_context', mcpEnforced: true, mcpFallback: false,
+      input: {}, error: 'route failed', duration: 20, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-fallback', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 160,
+      toolName: 'Read', toolType: 'direct', isMcpTool: false, mcpEnforced: false,
+      mcpFallback: true, input: {}, output: { content: 'fallback' }, duration: 10, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-memory-receipt', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 165,
+      toolName: 'mcp__devflow__memory_commit_turn', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'memory_commit_turn', mcpEnforced: true, mcpFallback: false,
+      input: {}, output: { receiptId: 'memory-receipt:host-commit' }, duration: 5, blocked: false,
+    });
+    db.insertToolCallEvent({
+      eventId: 'event-distill-receipt', executionId: 'exec-facts', sessionId: 'session-facts', timestamp: 166,
+      toolName: 'mcp__devflow__memory_save_distilled', toolType: 'mcp', isMcpTool: true,
+      mcpToolName: 'memory_save_distilled', mcpEnforced: true, mcpFallback: false,
+      input: {}, output: { receipt: { receiptId: 'distill-receipt:batch-1' } }, duration: 5, blocked: false,
+    });
+    db.insertHookFallback({
+      id: 'hook-fallback-1', projectRoot: '/project', sessionId: 'session-facts',
+      requestType: 'post-tool-use', tool: 'Read', reason: 'timeout', durationMs: 1_000,
+      attempts: 1, createdAt: 170,
+    });
+
+    db.reconcileSkillExecution('exec-facts', 'completed', 200);
+
+    expect(db.getSkillExecution('exec-facts')).toMatchObject({
+      missedMcpTools: ['react:context', 'react:domain'],
+      failedToolCalls: 1,
+      blockedToolCalls: 0,
+      fallbackCount: 2,
+      fallbackReasons: ['direct_tool_during_context', 'daemon_timeout'],
+      metadata: expect.objectContaining({
+        actualFailureCount: 1,
+        fallbackCount: 2,
+        memoryReceiptIds: ['memory-receipt:host-commit'],
+        distillReceiptIds: ['distill-receipt:batch-1'],
+      }),
+    });
+  });
+
   it('aggregates an empty findings collection as an empty result', () => {
     db.insertSkillExecution({
       executionId: 'exec_empty_findings',

package/dist/database.d.ts

@@ -83,6 +83,34 @@ export interface MemoryDistillCheckpointRecord {
     releasedLeases: number;
     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 declare function getGlobalDevFlowDbPath(home?: string): string;
 export declare function openGlobalDevFlowDatabase(home?: string, options?: {
     busyTimeoutMs?: number;
@@ -145,6 +173,10 @@ export declare class DevFlowDatabase {
         totalDuration?: number;
         mcpComplianceRate?: number;
         missedMcpTools?: string[];
+        failedToolCalls?: number;
+        blockedToolCalls?: number;
+        fallbackCount?: number;
+        fallbackReasons?: string[];
         totalToolCalls?: number;
         mcpToolCalls?: number;
         directToolCalls?: number;
@@ -275,6 +307,34 @@ export declare class DevFlowDatabase {
     getContextReceipt(projectRoot: string, sessionId: string, executionId: string): ContextReceiptRecord | null;
     deleteContextReceipt(projectRoot: string, sessionId: string, executionId?: string): number;
     purgeExpiredContextReceipts(now?: number): number;
+    beginMemoryTurn(input: Omit<MemoryTurnRecord, 'status' | 'memoryIds'>): MemoryTurnRecord;
+    getMemoryTurn(turnId: string): MemoryTurnRecord | null;
+    getPendingMemoryTurn(projectRoot: string, sessionId: string): MemoryTurnRecord | null;
+    commitMemoryTurn(input: {
+        turnId: string;
+        receiptId: string;
+        memoryIds: string[];
+        source: string;
+        reason?: string;
+        decidedAt?: number;
+    }): MemoryTurnRecord;
+    skipMemoryTurn(input: {
+        turnId: string;
+        receiptId: string;
+        reason: string;
+        decidedAt?: number;
+    }): MemoryTurnRecord;
+    markMemoryTurnStopPrompted(turnId: string, promptedAt?: number): boolean;
+    listMemoryTurns(projectRoot: string, sessionId?: string, limit?: number): MemoryTurnRecord[];
+    insertHookFallback(record: HookFallbackRecord): boolean;
+    listHookFallbacks(filter?: {
+        projectRoot?: string;
+        sessionId?: string;
+        from?: number;
+        to?: number;
+        limit?: number;
+    }): HookFallbackRecord[];
+    private mapMemoryTurn;
     recordMemoryDistillCheckpoint(checkpoint: MemoryDistillCheckpointRecord): void;
     listMemoryDistillCheckpoints(projectRoot: string, limit?: number): MemoryDistillCheckpointRecord[];
     all(sql: string, ...params: unknown[]): unknown[];

package/dist/database.js

@@ -11,12 +11,22 @@ const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
 function toolNameMatches(event, expected) {
-    if (event.blocked || event.error)
+    if (!isEffectiveToolEvent(event))
         return false;
     const name = String(event.mcpToolName ?? event.toolName ?? '')
         .replace(/^mcp__[^_]+__/, '');
     return name === expected;
 }
+function isEffectiveToolEvent(event) {
+    if (event.blocked || event.error || event.output == null)
+        return false;
+    if (typeof event.output === 'object') {
+        const output = event.output;
+        if (output.error || output.isError === true || output.success === false || output.degraded === true)
+            return false;
+    }
+    return countTelemetryResults(event.output) > 0;
+}
 function obligationsForSkill(skillName, configured) {
     const configuredTools = Array.isArray(configured)
         ? configured.filter((tool) => typeof tool === 'string' && tool.length > 0)
@@ -145,6 +155,10 @@ 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)
       );
 
@@ -284,6 +298,43 @@ 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);
     `);
         // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
         try {
@@ -326,6 +377,22 @@ class DevFlowDatabase {
             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`);
@@ -765,6 +832,10 @@ 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,
         };
@@ -792,6 +863,22 @@ class DevFlowDatabase {
             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);
@@ -840,6 +927,11 @@ 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,
         }));
     }
@@ -948,9 +1040,39 @@ class DevFlowDatabase {
       FROM tool_call_events WHERE execution_id = ?
     `).get(executionId);
         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) => typeof id === 'string')
+            : [];
+        const suppliedDistillReceiptIds = Array.isArray(metadata?.distillReceiptIds)
+            ? metadata.distillReceiptIds.filter((id) => 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,
@@ -962,7 +1084,23 @@ 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,
+            },
         });
     }
     getExecutionObligationCompliance(executionId) {
@@ -979,7 +1117,7 @@ class DevFlowDatabase {
             if (obligation.endsWith(':domain')) {
                 const family = obligation.slice(0, -':domain'.length);
                 return events.some((event) => {
-                    if (event.blocked || event.error || !event.isMcpTool)
+                    if (!event.isMcpTool || !isEffectiveToolEvent(event))
                         return false;
                     const name = String(event.mcpToolName ?? event.toolName ?? '')
                         .replace(/^mcp__[^_]+__/, '');
@@ -1477,6 +1615,137 @@ class DevFlowDatabase {
         return this.db.prepare('DELETE FROM devflow_context_receipts WHERE expires_at <= ?')
             .run(now).changes;
     }
+    beginMemoryTurn(input) {
+        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) {
+        const row = this.db.prepare('SELECT * FROM devflow_memory_turns WHERE turn_id = ?').get(turnId);
+        return row ? this.mapMemoryTurn(row) : null;
+    }
+    getPendingMemoryTurn(projectRoot, sessionId) {
+        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);
+        return row ? this.mapMemoryTurn(row) : null;
+    }
+    commitMemoryTurn(input) {
+        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) {
+        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, promptedAt = Date.now()) {
+        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, sessionId, limit = 50) {
+        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));
+        return rows.map(row => this.mapMemoryTurn(row));
+    }
+    insertHookFallback(record) {
+        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 = {}) {
+        const conditions = [];
+        const values = [];
+        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, 5000)));
+        const rows = this.db.prepare(`
+      SELECT * FROM devflow_hook_fallbacks
+      ${conditions.length ? `WHERE ${conditions.join(' AND ')}` : ''}
+      ORDER BY created_at DESC LIMIT ?
+    `).all(...values);
+        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,
+        }));
+    }
+    mapMemoryTurn(row) {
+        let memoryIds = [];
+        try {
+            const parsed = JSON.parse(row.memory_ids ?? '[]');
+            if (Array.isArray(parsed))
+                memoryIds = parsed.filter((id) => 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) {
         this.db.prepare(`
       INSERT INTO devflow_memory_distill_checkpoints
@@ -1570,3 +1839,32 @@ function countTelemetryResults(value, depth = 0) {
         return 0;
     return Object.keys(record).length > 0 ? 1 : 0;
 }
+function collectCanonicalReceiptIds(values) {
+    const receiptIds = new Set();
+    const visit = (value, depth) => {
+        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 < 1000000) {
+                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).forEach(item => visit(item, depth + 1));
+        }
+    };
+    values.forEach(value => visit(value, 0));
+    return [...receiptIds];
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
-export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookReceiptRecord, MemoryDistillCheckpointRecord, TelemetryFailureRecord, } from './database';
+export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.9",
+  "version": "0.16.10",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/database.ts

@@ -76,12 +76,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 +133,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 +279,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 +422,43 @@ 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);
     `);
 
     // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
@@ -394,6 +475,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 +1010,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 +1025,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 +1043,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 +1085,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 +1278,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,7 +1322,23 @@ 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,
+      },
     });
   }
 
@@ -1214,7 +1362,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}_`);
@@ -1853,6 +2001,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 +2270,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];
+}

package/src/index.ts

@@ -9,7 +9,10 @@ export type {
   FeedbackRecord,
   GovernanceAuditRecord,
   GovernanceRuleRecord,
+  HookFallbackRecord,
   HookReceiptRecord,
   MemoryDistillCheckpointRecord,
+  MemoryTurnRecord,
+  MemoryTurnStatus,
   TelemetryFailureRecord,
 } from './database';