@devflow-tools/database 0.17.1 → 0.17.2

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.17.2](https://github.com/shilongfeicool/dev-flow/compare/v0.17.1...v0.17.2) (2026-08-01)
+
+
+### Bug Fixes
+
+* **reliability:** close semantic lifecycle gaps ([08bae87](https://github.com/shilongfeicool/dev-flow/commit/08bae8742c5907dffdd476679e70c86cc373a7e8))
+
+
+### Features
+
+* **reliability:** strengthen semantic retrieval closure ([b979ab3](https://github.com/shilongfeicool/dev-flow/commit/b979ab3ec790e3d7119db512902db90a9567667d))
+
+
+
+
+
 ## [0.17.1](https://github.com/shilongfeicool/dev-flow/compare/v0.16.28...v0.17.1) (2026-07-31)
 
 

package/dist/database.d.ts

@@ -174,12 +174,17 @@ export interface HookFallbackRecord {
 export declare function getGlobalDevFlowDbPath(home?: string): string;
 export declare function openGlobalDevFlowDatabase(home?: string, options?: {
     busyTimeoutMs?: number;
+    readonly?: boolean;
+}): DevFlowDatabase;
+export declare function openGlobalDevFlowReadOnlyDatabase(home?: string, options?: {
+    busyTimeoutMs?: number;
 }): DevFlowDatabase;
 export declare class DevFlowDatabase {
     private db;
     constructor(projectRoot: string, opts?: {
         dbPath?: string;
         busyTimeoutMs?: number;
+        readonly?: boolean;
     });
     private initializeSchema;
     insertRun(run: any): void;
@@ -213,8 +218,10 @@ export declare class DevFlowDatabase {
     listToolCallEventsBySession(sessionId: string): any[];
     getToolCallEventByToolUseId(sessionId: string, toolUseId: string): {
         eventId: string;
+        executionId: string;
         timestamp: number;
         duration: number;
+        input: Record<string, unknown>;
     } | null;
     listToolCallEventsBySessions(sessionIds: string[]): Record<string, any[]>;
     insertSkillExecution(params: {
@@ -499,6 +506,11 @@ export declare class DevFlowDatabase {
         reason?: string;
         decidedAt?: number;
     }): MemoryTurnRecord;
+    updateCommittedMemoryTurnProjection(input: {
+        turnId: string;
+        memoryIds: string[];
+        reason?: string;
+    }): MemoryTurnRecord;
     skipMemoryTurn(input: {
         turnId: string;
         receiptId: string;

package/dist/database.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DevFlowDatabase = void 0;
 exports.getGlobalDevFlowDbPath = getGlobalDevFlowDbPath;
 exports.openGlobalDevFlowDatabase = openGlobalDevFlowDatabase;
+exports.openGlobalDevFlowReadOnlyDatabase = openGlobalDevFlowReadOnlyDatabase;
 const node_sqlite_1 = require("./node-sqlite");
 const path_1 = require("path");
 const fs_1 = require("fs");
@@ -62,28 +63,59 @@ function openGlobalDevFlowDatabase(home = (0, os_1.homedir)(), options) {
     return new DevFlowDatabase(home, {
         dbPath: getGlobalDevFlowDbPath(home),
         busyTimeoutMs: options?.busyTimeoutMs,
+        readonly: options?.readonly,
     });
 }
+function openGlobalDevFlowReadOnlyDatabase(home = (0, os_1.homedir)(), options) {
+    return openGlobalDevFlowDatabase(home, { ...options, readonly: true });
+}
+// Schema setup is process-owned. Hook daemons open short-lived connections for
+// bounded transactions, but replaying the full idempotent DDL on every open is
+// still expensive and serializes concurrent host requests. An inode identity
+// keeps the cache safe when a test, repair, or user replaces the database file.
+const initializedDatabaseFiles = new Map();
+function getDatabaseIdentity(path) {
+    try {
+        const stats = (0, fs_1.statSync)(path);
+        return { dev: stats.dev, ino: stats.ino };
+    }
+    catch {
+        return null;
+    }
+}
 class DevFlowDatabase {
     constructor(projectRoot, opts) {
         let dbPath;
         if (opts?.dbPath) {
             const dir = (0, path_1.dirname)(opts.dbPath);
-            if (!(0, fs_1.existsSync)(dir))
+            if (!(0, fs_1.existsSync)(dir) && !opts.readonly)
                 (0, fs_1.mkdirSync)(dir, { recursive: true });
             dbPath = opts.dbPath;
         }
         else {
             const devflowDir = (0, path_1.join)(projectRoot, '.devflow');
-            if (!(0, fs_1.existsSync)(devflowDir))
+            if (!(0, fs_1.existsSync)(devflowDir) && !opts?.readonly)
                 (0, fs_1.mkdirSync)(devflowDir, { recursive: true });
             dbPath = (0, path_1.join)(devflowDir, 'devflow.db');
         }
-        this.db = new node_sqlite_1.NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs);
-        this.db.exec('PRAGMA journal_mode = WAL');
+        if (opts?.readonly && !(0, fs_1.existsSync)(dbPath))
+            throw new Error(`DEVFLOW_DATABASE_NOT_FOUND:${dbPath}`);
+        this.db = new node_sqlite_1.NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs, opts?.readonly === true);
         this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts?.busyTimeoutMs ?? 5000))}`);
+        if (opts?.readonly)
+            return;
         this.db.exec('PRAGMA foreign_keys = OFF');
-        this.initializeSchema();
+        const databaseIdentity = getDatabaseIdentity(dbPath);
+        const initializedIdentity = initializedDatabaseFiles.get(dbPath);
+        const schemaInitialized = databaseIdentity !== null
+            && initializedIdentity?.dev === databaseIdentity.dev
+            && initializedIdentity.ino === databaseIdentity.ino;
+        if (!schemaInitialized) {
+            this.initializeSchema();
+            const currentIdentity = getDatabaseIdentity(dbPath);
+            if (currentIdentity)
+                initializedDatabaseFiles.set(dbPath, currentIdentity);
+        }
     }
     initializeSchema() {
         this.db.exec(`
@@ -1294,14 +1326,20 @@ class DevFlowDatabase {
     }
     getToolCallEventByToolUseId(sessionId, toolUseId) {
         const row = this.db.prepare(`
-      SELECT event_id, timestamp, duration
+      SELECT event_id, execution_id, timestamp, duration, input
       FROM tool_call_events
       WHERE session_id = ? AND tool_use_id = ?
       ORDER BY timestamp DESC
       LIMIT 1
     `).get(sessionId, toolUseId);
         return row
-            ? { eventId: row.event_id, timestamp: row.timestamp, duration: row.duration ?? 0 }
+            ? {
+                eventId: row.event_id,
+                executionId: row.execution_id,
+                timestamp: row.timestamp,
+                duration: row.duration ?? 0,
+                input: parseJsonObject(row.input) ?? {},
+            }
             : null;
     }
     listToolCallEventsBySessions(sessionIds) {
@@ -2457,7 +2495,8 @@ class DevFlowDatabase {
         SELECT COUNT(*) AS count
         FROM devflow_work_items
         WHERE project_root = ? AND session_id = ?
-          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+          AND state IN ('pending', 'leased', 'failed')
+          AND attempts < max_attempts
       `).get(input.projectRoot, input.sessionId);
             const pendingWorkCount = Number(pending?.count ?? 0);
             this.db.prepare(`
@@ -2518,6 +2557,8 @@ class DevFlowDatabase {
         }
         if (input.kinds?.length === 0)
             return [];
+        if (input.workItemIds?.length === 0)
+            return [];
         const now = input.now ?? Date.now();
         const leaseExpiresAt = now + input.leaseMs;
         if (!Number.isSafeInteger(now) || !Number.isSafeInteger(leaseExpiresAt)) {
@@ -2525,9 +2566,13 @@ class DevFlowDatabase {
         }
         const limit = Math.min(Math.floor(input.limit), 1000);
         const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+        const workItemIds = input.workItemIds ? [...new Set(input.workItemIds)] : undefined;
         const kindClause = kinds
             ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
             : '';
+        const workItemClause = workItemIds
+            ? `AND id IN (${workItemIds.map(() => '?').join(', ')})`
+            : '';
         this.db.exec('BEGIN IMMEDIATE');
         try {
             const candidates = this.db.prepare(`
@@ -2540,9 +2585,10 @@ class DevFlowDatabase {
           AND next_attempt_at <= ?
           AND attempts < max_attempts
           ${kindClause}
+          ${workItemClause}
         ORDER BY next_attempt_at ASC, created_at ASC, id ASC
         LIMIT ?
-      `).all(input.projectRoot, now, ...(kinds ?? []), limit);
+      `).all(input.projectRoot, now, ...(kinds ?? []), ...(workItemIds ?? []), limit);
             const leased = [];
             for (const candidate of candidates) {
                 const result = this.db.prepare(`
@@ -2714,28 +2760,11 @@ class DevFlowDatabase {
       SELECT COUNT(*) AS count
       FROM devflow_work_items
       WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND state IN ('pending', 'leased', 'failed')
+        AND attempts < max_attempts
         AND (? IS NULL OR id <> ?)
     `).get(projectRoot, sessionId, excludingWorkItemId ?? null, excludingWorkItemId ?? null);
-        const obligations = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_session_obligations
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('open', 'degraded')
-    `).get(projectRoot, sessionId);
-        const legacyTurns = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_memory_turns t
-      WHERE t.project_root = ? AND t.session_id = ? AND t.status = 'pending'
-        AND NOT EXISTS (
-          SELECT 1 FROM devflow_session_obligations o
-          WHERE o.project_root = t.project_root AND o.session_id = t.session_id
-            AND o.obligation_id = 'memory:' || t.turn_id
-        )
-    `).get(projectRoot, sessionId);
-        return Number(work?.count ?? 0)
-            + Number(obligations?.count ?? 0)
-            + Number(legacyTurns?.count ?? 0);
+        return Number(work?.count ?? 0);
     }
     // ---- Hook Lifecycle ----
     getHookReceipt(projectRoot) {
@@ -3459,6 +3488,15 @@ class DevFlowDatabase {
             if (!existing)
                 throw new Error(`Session obligation ${input.obligationId} does not exist`);
             if (existing.state !== 'open') {
+                if (existing.state === 'degraded' && input.state === 'satisfied' && input.receiptId) {
+                    const resolvedAt = input.resolvedAt ?? Date.now();
+                    this.db.prepare(`
+            UPDATE devflow_session_obligations
+            SET state = 'satisfied', receipt_id = ?, reason = ?, resolved_at = ?, updated_at = ?
+            WHERE project_root = ? AND session_id = ? AND obligation_id = ? AND state = 'degraded'
+          `).run(input.receiptId, input.reason ?? 'superseded_by_corrected_evidence', resolvedAt, resolvedAt, input.projectRoot, input.sessionId, input.obligationId);
+                    return this.getSessionObligation(input.projectRoot, input.sessionId, input.obligationId);
+                }
                 const sameResolution = existing.state === input.state
                     && (input.receiptId === undefined || existing.receiptId === input.receiptId);
                 if (sameResolution)
@@ -3517,6 +3555,19 @@ class DevFlowDatabase {
         });
         return turn;
     }
+    updateCommittedMemoryTurnProjection(input) {
+        const turnId = (0, obligation_ledger_1.normalizeTurnId)(input.turnId);
+        this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET memory_ids = ?, reason = COALESCE(?, reason)
+      WHERE turn_id = ? AND status = 'committed' AND source = 'explicit_intent'
+    `).run(JSON.stringify([...new Set(input.memoryIds)]), input.reason ?? null, turnId);
+        const turn = this.getMemoryTurn(turnId);
+        if (!turn || turn.status !== 'committed') {
+            throw new Error(`Committed explicit memory turn ${turnId} does not exist`);
+        }
+        return turn;
+    }
     skipMemoryTurn(input) {
         const turnId = (0, obligation_ledger_1.normalizeTurnId)(input.turnId);
         this.db.prepare(`

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, } from './database';
+export { DevFlowDatabase, getGlobalDevFlowDbPath, openGlobalDevFlowDatabase, openGlobalDevFlowReadOnlyDatabase, } from './database';
 export type { BenchmarkReportMetaRecord, BenchmarkReportRecord, FeedbackRecord, GovernanceAuditRecord, GovernanceRuleRecord, HookFallbackRecord, HookReceiptRecord, ContextReceiptRecord, ContextSelectionEventRecord, PolicyVerificationBaselineRecord, MemoryDistillCheckpointRecord, MemoryTurnRecord, MemoryTurnStatus, TelemetryFailureRecord, } from './database';
 export type { EnqueueWorkInput, LeaseWorkInput, RequestSessionClosureInput, SessionClosureRecord, SessionClosureState, WorkError, WorkItemRecord, WorkKind, WorkQueueHealth, WorkState, } from './work-queue';
 export type { RetrievalLedgerEventRecord, RetrievalLedgerSourceType, RetrievalLedgerStage, } from './retrieval-ledger';

package/dist/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.stableSemanticJson = exports.mapTranscriptCheckpointRow = exports.mapToolNameResolutionRow = exports.mapTerminalTransitionRow = exports.mapTaskIntentArtifactRow = exports.mapChannelQueryPlanRow = exports.assertTaskIdentity = exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
+exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = exports.mapWorkflowWorkerRow = exports.mapWorkflowWorkerEventRow = exports.mapWorkflowMergeRow = exports.TERMINAL_WORKFLOW_WORKER_STATES = exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.stableSemanticJson = exports.mapTranscriptCheckpointRow = exports.mapToolNameResolutionRow = exports.mapTerminalTransitionRow = exports.mapTaskIntentArtifactRow = exports.mapChannelQueryPlanRow = exports.assertTaskIdentity = exports.normalizeTurnId = exports.mapSessionObligationRow = exports.isRetrievalSessionState = exports.RETRIEVAL_MAX_CYCLES = exports.serializeHostActionReport = exports.mapHostActionRow = exports.isHostActionState = exports.hostActionReportsEqual = exports.openGlobalDevFlowReadOnlyDatabase = exports.openGlobalDevFlowDatabase = exports.getGlobalDevFlowDbPath = exports.DevFlowDatabase = void 0;
 var database_1 = require("./database");
 Object.defineProperty(exports, "DevFlowDatabase", { enumerable: true, get: function () { return database_1.DevFlowDatabase; } });
 Object.defineProperty(exports, "getGlobalDevFlowDbPath", { enumerable: true, get: function () { return database_1.getGlobalDevFlowDbPath; } });
 Object.defineProperty(exports, "openGlobalDevFlowDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowDatabase; } });
+Object.defineProperty(exports, "openGlobalDevFlowReadOnlyDatabase", { enumerable: true, get: function () { return database_1.openGlobalDevFlowReadOnlyDatabase; } });
 var host_actions_1 = require("./host-actions");
 Object.defineProperty(exports, "hostActionReportsEqual", { enumerable: true, get: function () { return host_actions_1.hostActionReportsEqual; } });
 Object.defineProperty(exports, "isHostActionState", { enumerable: true, get: function () { return host_actions_1.isHostActionState; } });

package/dist/node-sqlite.d.ts

@@ -1,7 +1,7 @@
 import type { Database, Statement } from './types';
 export declare class NodeSqliteDatabase implements Database {
     private db;
-    constructor(path: string, busyTimeoutMs?: number);
+    constructor(path: string, busyTimeoutMs?: number, readOnly?: boolean);
     exec(sql: string): void;
     prepare(sql: string): Statement;
     transaction<T>(fn: () => T): T;

package/dist/node-sqlite.js

@@ -3,11 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.NodeSqliteDatabase = void 0;
 const node_sqlite_1 = require("node:sqlite");
 class NodeSqliteDatabase {
-    constructor(path, busyTimeoutMs = 10000) {
-        this.db = new node_sqlite_1.DatabaseSync(path);
+    constructor(path, busyTimeoutMs = 10000, readOnly = false) {
+        this.db = readOnly
+            ? new node_sqlite_1.DatabaseSync(path, { readOnly: true })
+            : new node_sqlite_1.DatabaseSync(path);
         this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
-        this.db.exec('PRAGMA journal_mode = WAL');
-        this.db.exec('PRAGMA synchronous = NORMAL');
+        if (!readOnly) {
+            this.db.exec('PRAGMA journal_mode = WAL');
+            this.db.exec('PRAGMA synchronous = NORMAL');
+        }
     }
     exec(sql) {
         this.db.exec(sql);

package/dist/work-queue.d.ts

@@ -38,6 +38,7 @@ export interface LeaseWorkInput {
     projectRoot: string;
     owner: string;
     kinds?: WorkKind[];
+    workItemIds?: string[];
     limit: number;
     leaseMs: number;
     now?: number;

package/package.json

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

package/src/database.ts

@@ -1,6 +1,6 @@
 import { NodeSqliteDatabase } from './node-sqlite';
 import { join, dirname, resolve } from 'path';
-import { existsSync, mkdirSync, realpathSync } from 'fs';
+import { existsSync, mkdirSync, realpathSync, statSync } from 'fs';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import type {
@@ -305,35 +305,72 @@ export function getGlobalDevFlowDbPath(home = homedir()): string {
 
 export function openGlobalDevFlowDatabase(
   home = homedir(),
-  options?: { busyTimeoutMs?: number },
+  options?: { busyTimeoutMs?: number; readonly?: boolean },
 ): DevFlowDatabase {
   return new DevFlowDatabase(home, {
     dbPath: getGlobalDevFlowDbPath(home),
     busyTimeoutMs: options?.busyTimeoutMs,
+    readonly: options?.readonly,
   });
 }
 
+export function openGlobalDevFlowReadOnlyDatabase(
+  home = homedir(),
+  options?: { busyTimeoutMs?: number },
+): DevFlowDatabase {
+  return openGlobalDevFlowDatabase(home, { ...options, readonly: true });
+}
+
+interface InitializedDatabaseIdentity {
+  dev: number;
+  ino: number;
+}
+
+// Schema setup is process-owned. Hook daemons open short-lived connections for
+// bounded transactions, but replaying the full idempotent DDL on every open is
+// still expensive and serializes concurrent host requests. An inode identity
+// keeps the cache safe when a test, repair, or user replaces the database file.
+const initializedDatabaseFiles = new Map<string, InitializedDatabaseIdentity>();
+
+function getDatabaseIdentity(path: string): InitializedDatabaseIdentity | null {
+  try {
+    const stats = statSync(path);
+    return { dev: stats.dev, ino: stats.ino };
+  } catch {
+    return null;
+  }
+}
+
 export class DevFlowDatabase {
   private db: NodeSqliteDatabase;
 
-  constructor(projectRoot: string, opts?: { dbPath?: string; busyTimeoutMs?: number }) {
+  constructor(projectRoot: string, opts?: { dbPath?: string; busyTimeoutMs?: number; readonly?: boolean }) {
     let dbPath: string;
     if (opts?.dbPath) {
       const dir = dirname(opts.dbPath);
-      if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+      if (!existsSync(dir) && !opts.readonly) mkdirSync(dir, { recursive: true });
       dbPath = opts.dbPath;
     } else {
       const devflowDir = join(projectRoot, '.devflow');
-      if (!existsSync(devflowDir)) mkdirSync(devflowDir, { recursive: true });
+      if (!existsSync(devflowDir) && !opts?.readonly) mkdirSync(devflowDir, { recursive: true });
       dbPath = join(devflowDir, 'devflow.db');
     }
-    this.db = new NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs);
+    if (opts?.readonly && !existsSync(dbPath)) throw new Error(`DEVFLOW_DATABASE_NOT_FOUND:${dbPath}`);
+    this.db = new NodeSqliteDatabase(dbPath, opts?.busyTimeoutMs, opts?.readonly === true);
 
-    this.db.exec('PRAGMA journal_mode = WAL');
     this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(opts?.busyTimeoutMs ?? 5000))}`);
+    if (opts?.readonly) return;
     this.db.exec('PRAGMA foreign_keys = OFF');
-
-    this.initializeSchema();
+    const databaseIdentity = getDatabaseIdentity(dbPath);
+    const initializedIdentity = initializedDatabaseFiles.get(dbPath);
+    const schemaInitialized = databaseIdentity !== null
+      && initializedIdentity?.dev === databaseIdentity.dev
+      && initializedIdentity.ino === databaseIdentity.ino;
+    if (!schemaInitialized) {
+      this.initializeSchema();
+      const currentIdentity = getDatabaseIdentity(dbPath);
+      if (currentIdentity) initializedDatabaseFiles.set(dbPath, currentIdentity);
+    }
   }
 
   private initializeSchema() {
@@ -1550,16 +1587,30 @@ export class DevFlowDatabase {
     }));
   }
 
-  getToolCallEventByToolUseId(sessionId: string, toolUseId: string): { eventId: string; timestamp: number; duration: number } | null {
+  getToolCallEventByToolUseId(sessionId: string, toolUseId: string): {
+    eventId: string;
+    executionId: string;
+    timestamp: number;
+    duration: number;
+    input: Record<string, unknown>;
+  } | null {
     const row = this.db.prepare(`
-      SELECT event_id, timestamp, duration
+      SELECT event_id, execution_id, timestamp, duration, input
       FROM tool_call_events
       WHERE session_id = ? AND tool_use_id = ?
       ORDER BY timestamp DESC
       LIMIT 1
-    `).get(sessionId, toolUseId) as { event_id: string; timestamp: number; duration: number } | undefined;
+    `).get(sessionId, toolUseId) as {
+      event_id: string; execution_id: string; timestamp: number; duration: number; input: string | null;
+    } | undefined;
     return row
-      ? { eventId: row.event_id, timestamp: row.timestamp, duration: row.duration ?? 0 }
+      ? {
+          eventId: row.event_id,
+          executionId: row.execution_id,
+          timestamp: row.timestamp,
+          duration: row.duration ?? 0,
+          input: parseJsonObject(row.input) ?? {},
+        }
       : null;
   }
 
@@ -3060,7 +3111,8 @@ export class DevFlowDatabase {
         SELECT COUNT(*) AS count
         FROM devflow_work_items
         WHERE project_root = ? AND session_id = ?
-          AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+          AND state IN ('pending', 'leased', 'failed')
+          AND attempts < max_attempts
       `).get(input.projectRoot, input.sessionId) as { count?: number };
       const pendingWorkCount = Number(pending?.count ?? 0);
       this.db.prepare(`
@@ -3142,6 +3194,7 @@ export class DevFlowDatabase {
       throw new Error('Work leaseMs must be a positive safe integer');
     }
     if (input.kinds?.length === 0) return [];
+    if (input.workItemIds?.length === 0) return [];
 
     const now = input.now ?? Date.now();
     const leaseExpiresAt = now + input.leaseMs;
@@ -3150,9 +3203,13 @@ export class DevFlowDatabase {
     }
     const limit = Math.min(Math.floor(input.limit), 1_000);
     const kinds = input.kinds ? [...new Set(input.kinds)] : undefined;
+    const workItemIds = input.workItemIds ? [...new Set(input.workItemIds)] : undefined;
     const kindClause = kinds
       ? `AND kind IN (${kinds.map(() => '?').join(', ')})`
       : '';
+    const workItemClause = workItemIds
+      ? `AND id IN (${workItemIds.map(() => '?').join(', ')})`
+      : '';
 
     this.db.exec('BEGIN IMMEDIATE');
     try {
@@ -3166,9 +3223,10 @@ export class DevFlowDatabase {
           AND next_attempt_at <= ?
           AND attempts < max_attempts
           ${kindClause}
+          ${workItemClause}
         ORDER BY next_attempt_at ASC, created_at ASC, id ASC
         LIMIT ?
-      `).all(input.projectRoot, now, ...(kinds ?? []), limit) as Array<{
+      `).all(input.projectRoot, now, ...(kinds ?? []), ...(workItemIds ?? []), limit) as Array<{
         id: string;
         state: WorkState;
       }>;
@@ -3378,7 +3436,8 @@ export class DevFlowDatabase {
       SELECT COUNT(*) AS count
       FROM devflow_work_items
       WHERE project_root = ? AND session_id = ?
-        AND state IN ('pending', 'leased', 'failed', 'dead_letter')
+        AND state IN ('pending', 'leased', 'failed')
+        AND attempts < max_attempts
         AND (? IS NULL OR id <> ?)
     `).get(
       projectRoot,
@@ -3386,25 +3445,7 @@ export class DevFlowDatabase {
       excludingWorkItemId ?? null,
       excludingWorkItemId ?? null,
     ) as { count?: number };
-    const obligations = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_session_obligations
-      WHERE project_root = ? AND session_id = ?
-        AND state IN ('open', 'degraded')
-    `).get(projectRoot, sessionId) as { count?: number };
-    const legacyTurns = this.db.prepare(`
-      SELECT COUNT(*) AS count
-      FROM devflow_memory_turns t
-      WHERE t.project_root = ? AND t.session_id = ? AND t.status = 'pending'
-        AND NOT EXISTS (
-          SELECT 1 FROM devflow_session_obligations o
-          WHERE o.project_root = t.project_root AND o.session_id = t.session_id
-            AND o.obligation_id = 'memory:' || t.turn_id
-        )
-    `).get(projectRoot, sessionId) as { count?: number };
-    return Number(work?.count ?? 0)
-      + Number(obligations?.count ?? 0)
-      + Number(legacyTurns?.count ?? 0);
+    return Number(work?.count ?? 0);
   }
 
   // ---- Hook Lifecycle ----
@@ -4330,6 +4371,23 @@ export class DevFlowDatabase {
       );
       if (!existing) throw new Error(`Session obligation ${input.obligationId} does not exist`);
       if (existing.state !== 'open') {
+        if (existing.state === 'degraded' && input.state === 'satisfied' && input.receiptId) {
+          const resolvedAt = input.resolvedAt ?? Date.now();
+          this.db.prepare(`
+            UPDATE devflow_session_obligations
+            SET state = 'satisfied', receipt_id = ?, reason = ?, resolved_at = ?, updated_at = ?
+            WHERE project_root = ? AND session_id = ? AND obligation_id = ? AND state = 'degraded'
+          `).run(
+            input.receiptId,
+            input.reason ?? 'superseded_by_corrected_evidence',
+            resolvedAt,
+            resolvedAt,
+            input.projectRoot,
+            input.sessionId,
+            input.obligationId,
+          );
+          return this.getSessionObligation(input.projectRoot, input.sessionId, input.obligationId)!;
+        }
         const sameResolution = existing.state === input.state
           && (input.receiptId === undefined || existing.receiptId === input.receiptId);
         if (sameResolution) return existing;
@@ -4417,6 +4475,28 @@ export class DevFlowDatabase {
     return turn;
   }
 
+  updateCommittedMemoryTurnProjection(input: {
+    turnId: string;
+    memoryIds: string[];
+    reason?: string;
+  }): MemoryTurnRecord {
+    const turnId = normalizeTurnId(input.turnId);
+    this.db.prepare(`
+      UPDATE devflow_memory_turns
+      SET memory_ids = ?, reason = COALESCE(?, reason)
+      WHERE turn_id = ? AND status = 'committed' AND source = 'explicit_intent'
+    `).run(
+      JSON.stringify([...new Set(input.memoryIds)]),
+      input.reason ?? null,
+      turnId,
+    );
+    const turn = this.getMemoryTurn(turnId);
+    if (!turn || turn.status !== 'committed') {
+      throw new Error(`Committed explicit memory turn ${turnId} does not exist`);
+    }
+    return turn;
+  }
+
   skipMemoryTurn(input: {
     turnId: string;
     receiptId: string;

package/src/index.ts

@@ -2,6 +2,7 @@ export {
   DevFlowDatabase,
   getGlobalDevFlowDbPath,
   openGlobalDevFlowDatabase,
+  openGlobalDevFlowReadOnlyDatabase,
 } from './database';
 export type {
   BenchmarkReportMetaRecord,

package/src/node-sqlite.ts

@@ -4,11 +4,15 @@ import type { Database, Statement, RunResult } from './types';
 export class NodeSqliteDatabase implements Database {
   private db: DatabaseSync;
 
-  constructor(path: string, busyTimeoutMs = 10000) {
-    this.db = new DatabaseSync(path);
+  constructor(path: string, busyTimeoutMs = 10000, readOnly = false) {
+    this.db = readOnly
+      ? new DatabaseSync(path, { readOnly: true })
+      : new DatabaseSync(path);
     this.db.exec(`PRAGMA busy_timeout = ${Math.max(0, Math.floor(busyTimeoutMs))}`);
-    this.db.exec('PRAGMA journal_mode = WAL');
-    this.db.exec('PRAGMA synchronous = NORMAL');
+    if (!readOnly) {
+      this.db.exec('PRAGMA journal_mode = WAL');
+      this.db.exec('PRAGMA synchronous = NORMAL');
+    }
   }
 
   exec(sql: string): void {

package/src/work-queue.ts

@@ -59,6 +59,7 @@ export interface LeaseWorkInput {
   projectRoot: string;
   owner: string;
   kinds?: WorkKind[];
+  workItemIds?: string[];
   limit: number;
   leaseMs: number;
   now?: number;