@devflow-tools/database 0.16.21 → 0.16.23

package/src/database.ts

@@ -42,6 +42,33 @@ import {
   type RetrievalSessionRecord,
   type RetrievalSessionState,
 } from './retrieval-sessions';
+import {
+  mapLearningCandidateRow,
+  mapLearningEvidenceRow,
+  mapLearningVersionRow,
+  stableLearningJson,
+  type AddLearningCandidateEvidenceInput,
+  type LearningCandidateEvidenceRecord,
+  type LearningCandidateRecord,
+  type LearningCandidateState,
+  type LearningCandidateVersionRecord,
+  type TransitionLearningCandidateInput,
+  type UpsertLearningCandidateInput,
+} from './learning-candidates';
+import {
+  LEGAL_WORKFLOW_WORKER_TRANSITIONS,
+  TERMINAL_WORKFLOW_WORKER_STATES,
+  mapWorkflowMergeRow,
+  mapWorkflowWorkerEventRow,
+  mapWorkflowWorkerRow,
+  type CreateWorkflowWorkerInput,
+  type EnqueueWorkflowMergeInput,
+  type TransitionWorkflowWorkerInput,
+  type WorkflowMergeRecord,
+  type WorkflowMergeState,
+  type WorkflowWorkerEventRecord,
+  type WorkflowWorkerRecord,
+} from './workflow-workers';
 
 export interface BenchmarkReportRecord {
   runId: string;
@@ -655,6 +682,74 @@ export class DevFlowDatabase {
       CREATE INDEX IF NOT EXISTS idx_session_closures_state
         ON devflow_session_closures(project_root, state, updated_at DESC);
 
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidates (
+        id TEXT PRIMARY KEY,
+        project_root TEXT NOT NULL,
+        scope TEXT NOT NULL CHECK(scope IN ('project', 'global')),
+        state TEXT NOT NULL DEFAULT 'observed'
+          CHECK(state IN ('observed', 'candidate', 'shadow', 'evaluated', 'active', 'rejected', 'retired')),
+        kind TEXT NOT NULL CHECK(kind IN ('convention', 'workflow', 'tool_preference', 'correction')),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        confidence REAL NOT NULL CHECK(confidence BETWEEN 0 AND 1),
+        overlay_version INTEGER NOT NULL DEFAULT 1 CHECK(overlay_version > 0),
+        supporting_sessions INTEGER NOT NULL DEFAULT 0 CHECK(supporting_sessions >= 0),
+        successful_outcomes INTEGER NOT NULL DEFAULT 0 CHECK(successful_outcomes >= 0),
+        contradictions INTEGER NOT NULL DEFAULT 0 CHECK(contradictions >= 0),
+        manual_only INTEGER NOT NULL DEFAULT 0 CHECK(manual_only IN (0, 1)),
+        risk TEXT NOT NULL DEFAULT 'low' CHECK(risk IN ('low', 'medium', 'high')),
+        grader_receipt TEXT,
+        expires_at INTEGER,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_candidates_project
+        ON devflow_learning_candidates(project_root, state, kind, updated_at DESC);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_versions (
+        candidate_id TEXT NOT NULL,
+        version INTEGER NOT NULL CHECK(version > 0),
+        trigger_json TEXT NOT NULL,
+        instruction TEXT NOT NULL,
+        created_at INTEGER NOT NULL,
+        PRIMARY KEY(candidate_id, version)
+      );
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_candidate_evidence (
+        id TEXT PRIMARY KEY,
+        candidate_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        session_id TEXT NOT NULL,
+        execution_id TEXT,
+        memory_observation_id TEXT,
+        outcome_id TEXT,
+        source_type TEXT NOT NULL
+          CHECK(source_type IN ('memory', 'correction', 'workflow_outcome', 'tool_preference', 'convention', 'grader', 'manual')),
+        polarity TEXT NOT NULL CHECK(polarity IN ('supporting', 'contradicting')),
+        outcome TEXT NOT NULL DEFAULT 'unknown' CHECK(outcome IN ('positive', 'negative', 'unknown')),
+        evidence_hash TEXT NOT NULL,
+        receipt TEXT,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL,
+        resolved_at INTEGER,
+        UNIQUE(candidate_id, evidence_hash)
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_evidence_candidate
+        ON devflow_learning_candidate_evidence(candidate_id, polarity, resolved_at, created_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_learning_activation_history (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        candidate_id TEXT NOT NULL,
+        from_state TEXT NOT NULL,
+        to_state TEXT NOT NULL,
+        reason TEXT NOT NULL,
+        grader_receipt TEXT,
+        manual_approval INTEGER NOT NULL DEFAULT 0 CHECK(manual_approval IN (0, 1)),
+        changed_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_learning_activation_candidate
+        ON devflow_learning_activation_history(candidate_id, changed_at DESC);
+
       CREATE TABLE IF NOT EXISTS devflow_host_actions (
         action_id TEXT PRIMARY KEY,
         run_id TEXT NOT NULL,
@@ -727,6 +822,85 @@ export class DevFlowDatabase {
       BEGIN
         SELECT RAISE(ABORT, 'devflow_host_action_events is append-only');
       END;
+
+      CREATE TABLE IF NOT EXISTS devflow_workflow_workers (
+        worker_id TEXT PRIMARY KEY,
+        run_id TEXT NOT NULL,
+        step_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        branch TEXT NOT NULL,
+        worktree_path TEXT NOT NULL,
+        host TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'planned'
+          CHECK(state IN ('planned','leased','starting','running','reported','verifying','merge_ready','merged','hold','failed','cancelled')),
+        lease_owner TEXT,
+        lease_expires_at INTEGER,
+        heartbeat_at INTEGER,
+        context_receipt TEXT NOT NULL,
+        retrieval_session_id TEXT,
+        session_id TEXT,
+        execution_id TEXT,
+        base_revision TEXT NOT NULL,
+        final_revision TEXT,
+        allowed_files TEXT NOT NULL DEFAULT '[]',
+        handoff_json TEXT NOT NULL DEFAULT '{}',
+        hold_reason TEXT,
+        failure_reason TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        finished_at INTEGER,
+        UNIQUE(run_id, step_id),
+        UNIQUE(worktree_path),
+        CHECK(
+          (state IN ('merged','failed','cancelled') AND finished_at IS NOT NULL)
+          OR (state NOT IN ('merged','failed','cancelled') AND finished_at IS NULL)
+        )
+      );
+      CREATE INDEX IF NOT EXISTS idx_workflow_workers_project
+        ON devflow_workflow_workers(project_root, state, updated_at DESC);
+      CREATE INDEX IF NOT EXISTS idx_workflow_workers_lease
+        ON devflow_workflow_workers(project_root, state, lease_expires_at);
+
+      CREATE TABLE IF NOT EXISTS devflow_worker_events (
+        event_id TEXT PRIMARY KEY,
+        worker_id TEXT NOT NULL,
+        project_root TEXT NOT NULL,
+        from_state TEXT,
+        to_state TEXT NOT NULL,
+        reason TEXT,
+        payload_json TEXT NOT NULL DEFAULT '{}',
+        created_at INTEGER NOT NULL
+      );
+      CREATE INDEX IF NOT EXISTS idx_worker_events_worker
+        ON devflow_worker_events(worker_id, created_at, event_id);
+      CREATE TRIGGER IF NOT EXISTS prevent_worker_event_update
+      BEFORE UPDATE ON devflow_worker_events BEGIN
+        SELECT RAISE(ABORT, 'devflow_worker_events is append-only');
+      END;
+      CREATE TRIGGER IF NOT EXISTS prevent_worker_event_delete
+      BEFORE DELETE ON devflow_worker_events BEGIN
+        SELECT RAISE(ABORT, 'devflow_worker_events is append-only');
+      END;
+
+      CREATE TABLE IF NOT EXISTS devflow_merge_queue (
+        merge_id TEXT PRIMARY KEY,
+        worker_id TEXT NOT NULL UNIQUE,
+        project_root TEXT NOT NULL,
+        state TEXT NOT NULL DEFAULT 'waiting'
+          CHECK(state IN ('waiting','ready','conflict','merged','rejected')),
+        base_revision TEXT NOT NULL,
+        parent_revision TEXT NOT NULL,
+        candidate_revision TEXT NOT NULL,
+        grader_receipts TEXT NOT NULL DEFAULT '[]',
+        simulation_hash TEXT,
+        merge_commit TEXT,
+        reason TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL,
+        finished_at INTEGER
+      );
+      CREATE INDEX IF NOT EXISTS idx_merge_queue_project
+        ON devflow_merge_queue(project_root, state, created_at, merge_id);
     `);
 
     // Migration: add session_id to skill_executions (SQLite compat — ignore if exists)
@@ -2231,6 +2405,352 @@ export class DevFlowDatabase {
     };
   }
 
+  // ---- Governed Learning ----
+
+  upsertLearningCandidate(input: UpsertLearningCandidateInput): LearningCandidateRecord {
+    if (!input.id.trim()) throw new Error('Learning candidate requires an ID');
+    if (!input.projectRoot.trim()) throw new Error('Learning candidate requires a project root');
+    if (!input.instruction.trim()) throw new Error('Learning candidate requires an instruction');
+    if (!Number.isFinite(input.confidence) || input.confidence < 0 || input.confidence > 1) {
+      throw new Error('Learning candidate confidence must be between 0 and 1');
+    }
+
+    return this.db.transaction(() => {
+      const now = Date.now();
+      const existing = this.getLearningCandidate(input.id);
+      const triggerJson = stableLearningJson(input.trigger);
+      const instruction = input.instruction.trim().slice(0, 2_000);
+      if (!existing) {
+        this.db.prepare(`
+          INSERT INTO devflow_learning_candidates (
+            id, project_root, scope, state, kind, trigger_json, instruction,
+            confidence, overlay_version, supporting_sessions, successful_outcomes,
+            contradictions, manual_only, risk, expires_at, created_at, updated_at
+          ) VALUES (?, ?, ?, 'observed', ?, ?, ?, ?, 1, 0, 0, 0, ?, ?, ?, ?, ?)
+        `).run(
+          input.id,
+          input.projectRoot,
+          input.scope,
+          input.kind,
+          triggerJson,
+          instruction,
+          input.confidence,
+          input.manualOnly ? 1 : 0,
+          input.risk ?? 'low',
+          input.expiresAt ?? null,
+          now,
+          now,
+        );
+        this.insertLearningCandidateVersion(input.id, 1, triggerJson, instruction, now);
+        return this.getLearningCandidate(input.id)!;
+      }
+      if (existing.projectRoot !== input.projectRoot || existing.scope !== input.scope || existing.kind !== input.kind) {
+        throw new Error(`Learning candidate identity mismatch for ${input.id}`);
+      }
+
+      const contentChanged = stableLearningJson(existing.trigger) !== triggerJson
+        || existing.instruction !== instruction;
+      const nextVersion = contentChanged ? existing.overlayVersion + 1 : existing.overlayVersion;
+      const nextState = contentChanged && (existing.state === 'active' || existing.state === 'evaluated')
+        ? 'shadow'
+        : existing.state;
+      this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET trigger_json = ?, instruction = ?, confidence = ?, overlay_version = ?,
+            state = ?, manual_only = MAX(manual_only, ?),
+            risk = CASE
+              WHEN risk = 'high' OR ? = 'high' THEN 'high'
+              WHEN risk = 'medium' OR ? = 'medium' THEN 'medium'
+              ELSE 'low'
+            END,
+            expires_at = ?, updated_at = ?
+        WHERE id = ?
+      `).run(
+        triggerJson,
+        instruction,
+        Math.max(existing.confidence, input.confidence),
+        nextVersion,
+        nextState,
+        input.manualOnly ? 1 : 0,
+        input.risk ?? 'low',
+        input.risk ?? 'low',
+        input.expiresAt ?? existing.expiresAt ?? null,
+        now,
+        input.id,
+      );
+      if (contentChanged) {
+        this.insertLearningCandidateVersion(input.id, nextVersion, triggerJson, instruction, now);
+        if (nextState !== existing.state) {
+          this.insertLearningActivation(input.id, existing.state, nextState, 'candidate_content_changed', undefined, false, now);
+        }
+      }
+      return this.getLearningCandidate(input.id)!;
+    });
+  }
+
+  getLearningCandidate(id: string): LearningCandidateRecord | null {
+    const row = this.db.prepare('SELECT * FROM devflow_learning_candidates WHERE id = ?')
+      .get(id) as Record<string, unknown> | undefined;
+    return row ? mapLearningCandidateRow(row) : null;
+  }
+
+  listLearningCandidates(options: {
+    projectRoot?: string;
+    states?: LearningCandidateState[];
+    limit?: number;
+  } = {}): LearningCandidateRecord[] {
+    const predicates: string[] = [];
+    const params: unknown[] = [];
+    if (options.projectRoot) {
+      predicates.push('(project_root = ? OR scope = \'global\')');
+      params.push(options.projectRoot);
+    }
+    const states = [...new Set(options.states ?? [])];
+    if (states.length > 0) {
+      predicates.push(`state IN (${states.map(() => '?').join(',')})`);
+      params.push(...states);
+    }
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidates
+      ${predicates.length > 0 ? `WHERE ${predicates.join(' AND ')}` : ''}
+      ORDER BY updated_at DESC, id ASC
+      LIMIT ?
+    `).all(...params, Math.max(1, Math.min(options.limit ?? 200, 2_000))) as Array<Record<string, unknown>>;
+    return rows.map(mapLearningCandidateRow);
+  }
+
+  addLearningCandidateEvidence(input: AddLearningCandidateEvidenceInput): LearningCandidateRecord {
+    if (!input.evidenceHash.trim()) throw new Error('Learning evidence requires a hash');
+    if (!input.sessionId.trim()) throw new Error('Learning evidence requires a session ID');
+    return this.db.transaction(() => {
+      const candidate = this.getLearningCandidate(input.candidateId);
+      if (!candidate) throw new Error(`Learning candidate ${input.candidateId} does not exist`);
+      if (candidate.projectRoot !== input.projectRoot && candidate.scope !== 'global') {
+        throw new Error(`Learning evidence project mismatch for ${input.candidateId}`);
+      }
+      const createdAt = input.createdAt ?? Date.now();
+      const inserted = this.db.prepare(`
+        INSERT OR IGNORE INTO devflow_learning_candidate_evidence (
+          id, candidate_id, project_root, session_id, execution_id,
+          memory_observation_id, outcome_id, source_type, polarity, outcome,
+          evidence_hash, receipt, payload_json, created_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+      `).run(
+        input.id,
+        input.candidateId,
+        input.projectRoot,
+        input.sessionId,
+        input.executionId ?? null,
+        input.memoryObservationId ?? null,
+        input.outcomeId ?? null,
+        input.sourceType,
+        input.polarity,
+        input.outcome ?? 'unknown',
+        input.evidenceHash,
+        input.receipt ?? null,
+        stableLearningJson(input.payload ?? {}),
+        createdAt,
+      ).changes === 1;
+      if (!inserted) return candidate;
+
+      const previousState = candidate.state;
+      const aggregates = this.getLearningEvidenceAggregates(input.candidateId);
+      let state = previousState;
+      if (state === 'observed' && aggregates.supportingSessions > 0) state = 'candidate';
+      if (aggregates.contradictions > 0 && (state === 'active' || state === 'evaluated')) state = 'shadow';
+      this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, supporting_sessions = ?, successful_outcomes = ?,
+            contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(
+        state,
+        aggregates.supportingSessions,
+        aggregates.successfulOutcomes,
+        aggregates.contradictions,
+        createdAt,
+        input.candidateId,
+      );
+      if (state !== previousState) {
+        this.insertLearningActivation(
+          input.candidateId,
+          previousState,
+          state,
+          aggregates.contradictions > 0 ? 'unresolved_contradiction' : 'first_supporting_evidence',
+          undefined,
+          false,
+          createdAt,
+        );
+      }
+      return this.getLearningCandidate(input.candidateId)!;
+    });
+  }
+
+  listLearningCandidateEvidence(candidateId: string): LearningCandidateEvidenceRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_evidence
+      WHERE candidate_id = ? ORDER BY created_at ASC, id ASC
+    `).all(candidateId) as Array<Record<string, unknown>>;
+    return rows.map(mapLearningEvidenceRow);
+  }
+
+  resolveLearningContradiction(candidateId: string, evidenceId: string, resolvedAt = Date.now()): LearningCandidateRecord {
+    return this.db.transaction(() => {
+      this.db.prepare(`
+        UPDATE devflow_learning_candidate_evidence
+        SET resolved_at = ?
+        WHERE id = ? AND candidate_id = ? AND polarity = 'contradicting' AND resolved_at IS NULL
+      `).run(resolvedAt, evidenceId, candidateId);
+      const aggregates = this.getLearningEvidenceAggregates(candidateId);
+      this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET supporting_sessions = ?, successful_outcomes = ?, contradictions = ?, updated_at = ?
+        WHERE id = ?
+      `).run(
+        aggregates.supportingSessions,
+        aggregates.successfulOutcomes,
+        aggregates.contradictions,
+        resolvedAt,
+        candidateId,
+      );
+      const candidate = this.getLearningCandidate(candidateId);
+      if (!candidate) throw new Error(`Learning candidate ${candidateId} does not exist`);
+      return candidate;
+    });
+  }
+
+  transitionLearningCandidate(
+    candidateId: string,
+    input: TransitionLearningCandidateInput,
+  ): LearningCandidateRecord {
+    return this.db.transaction(() => {
+      const candidate = this.getLearningCandidate(candidateId);
+      if (!candidate) throw new Error(`Learning candidate ${candidateId} does not exist`);
+      if (candidate.state === input.target) return candidate;
+      this.assertLearningTransition(candidate, input);
+      const changedAt = input.changedAt ?? Date.now();
+      const graderReceipt = input.graderReceipt ?? candidate.graderReceipt;
+      this.db.prepare(`
+        UPDATE devflow_learning_candidates
+        SET state = ?, grader_receipt = COALESCE(?, grader_receipt), updated_at = ?
+        WHERE id = ?
+      `).run(input.target, graderReceipt ?? null, changedAt, candidateId);
+      this.insertLearningActivation(
+        candidateId,
+        candidate.state,
+        input.target,
+        input.reason,
+        graderReceipt,
+        input.manualApproval === true,
+        changedAt,
+      );
+      return this.getLearningCandidate(candidateId)!;
+    });
+  }
+
+  listLearningCandidateVersions(candidateId: string): LearningCandidateVersionRecord[] {
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_learning_candidate_versions
+      WHERE candidate_id = ? ORDER BY version ASC
+    `).all(candidateId) as Array<Record<string, unknown>>;
+    return rows.map(mapLearningVersionRow);
+  }
+
+  private assertLearningTransition(
+    candidate: LearningCandidateRecord,
+    input: TransitionLearningCandidateInput,
+  ): void {
+    const terminal = input.target === 'rejected' || input.target === 'retired';
+    const rollback = input.target === 'shadow'
+      && (candidate.state === 'active' || candidate.state === 'evaluated');
+    const legal: Record<LearningCandidateState, LearningCandidateState[]> = {
+      observed: ['candidate', 'rejected', 'retired'],
+      candidate: ['shadow', 'rejected', 'retired'],
+      shadow: ['evaluated', 'rejected', 'retired'],
+      evaluated: ['active', 'shadow', 'rejected', 'retired'],
+      active: ['shadow', 'retired'],
+      rejected: ['retired'],
+      retired: [],
+    };
+    if (!terminal && !rollback && !legal[candidate.state].includes(input.target)) {
+      throw new Error(`Illegal learning transition ${candidate.state} -> ${input.target}`);
+    }
+    if (input.target === 'shadow') {
+      if (candidate.supportingSessions < 3 || candidate.successfulOutcomes < 2) {
+        throw new Error('Learning candidate requires three sessions and two verified outcomes before shadow');
+      }
+    }
+    if (input.target === 'evaluated' && candidate.contradictions > 0) {
+      throw new Error('Learning candidate has unresolved contradictions');
+    }
+    if (input.target === 'active') {
+      const receipt = input.graderReceipt ?? candidate.graderReceipt;
+      if (!receipt) throw new Error('Learning candidate activation requires a grader receipt');
+      if (candidate.contradictions > 0) throw new Error('Learning candidate has unresolved contradictions');
+      const manualRequired = candidate.scope === 'global' || candidate.manualOnly || candidate.risk === 'high';
+      if (manualRequired && input.manualApproval !== true) {
+        throw new Error('Learning candidate requires manual approval');
+      }
+    }
+  }
+
+  private getLearningEvidenceAggregates(candidateId: string): {
+    supportingSessions: number;
+    successfulOutcomes: number;
+    contradictions: number;
+  } {
+    const row = this.db.prepare(`
+      SELECT
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' THEN session_id END) AS supporting_sessions,
+        COUNT(DISTINCT CASE WHEN polarity = 'supporting' AND outcome = 'positive' THEN session_id END) AS successful_outcomes,
+        SUM(CASE WHEN polarity = 'contradicting' AND resolved_at IS NULL THEN 1 ELSE 0 END) AS contradictions
+      FROM devflow_learning_candidate_evidence WHERE candidate_id = ?
+    `).get(candidateId) as Record<string, unknown> | undefined;
+    return {
+      supportingSessions: Number(row?.supporting_sessions ?? 0),
+      successfulOutcomes: Number(row?.successful_outcomes ?? 0),
+      contradictions: Number(row?.contradictions ?? 0),
+    };
+  }
+
+  private insertLearningCandidateVersion(
+    candidateId: string,
+    version: number,
+    triggerJson: string,
+    instruction: string,
+    createdAt: number,
+  ): void {
+    this.db.prepare(`
+      INSERT OR IGNORE INTO devflow_learning_candidate_versions
+        (candidate_id, version, trigger_json, instruction, created_at)
+      VALUES (?, ?, ?, ?, ?)
+    `).run(candidateId, version, triggerJson, instruction, createdAt);
+  }
+
+  private insertLearningActivation(
+    candidateId: string,
+    fromState: LearningCandidateState,
+    toState: LearningCandidateState,
+    reason: string,
+    graderReceipt: string | undefined,
+    manualApproval: boolean,
+    changedAt: number,
+  ): void {
+    this.db.prepare(`
+      INSERT INTO devflow_learning_activation_history
+        (candidate_id, from_state, to_state, reason, grader_receipt, manual_approval, changed_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      candidateId,
+      fromState,
+      toState,
+      reason.trim().slice(0, 500),
+      graderReceipt ?? null,
+      manualApproval ? 1 : 0,
+      changedAt,
+    );
+  }
+
   // ---- Durable Work Queue ----
 
   enqueueWork(input: EnqueueWorkInput): WorkItemRecord {
@@ -2499,6 +3019,15 @@ export class DevFlowDatabase {
     return completed;
   }
 
+  heartbeatWork(id: string, owner: string, leaseMs: number, now = Date.now()): boolean {
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0) return false;
+    return this.db.prepare(`
+      UPDATE devflow_work_items
+      SET lease_expires_at = ?, updated_at = ?
+      WHERE id = ? AND state = 'leased' AND lease_owner = ?
+    `).run(now + leaseMs, now, id, owner).changes === 1;
+  }
+
   retryWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean {
     const updatedAt = Date.now();
     return this.db.prepare(`
@@ -3739,6 +4268,325 @@ export class DevFlowDatabase {
     return false;
   }
 
+  // ---- Isolated Workflow Workers ----
+
+  createWorkflowWorker(input: CreateWorkflowWorkerInput): WorkflowWorkerRecord {
+    for (const [name, value] of [
+      ['run ID', input.runId],
+      ['step ID', input.stepId],
+      ['project root', input.projectRoot],
+      ['branch', input.branch],
+      ['worktree path', input.worktreePath],
+      ['host', input.host],
+      ['context receipt', input.contextReceipt],
+      ['base revision', input.baseRevision],
+    ] as Array<[string, string]>) {
+      if (!value.trim()) throw new Error(`Workflow worker requires a ${name}`);
+    }
+    const workerId = input.workerId ?? randomUUID();
+    const now = Date.now();
+    return this.withImmediateTransaction(() => {
+      this.db.prepare(`
+        INSERT INTO devflow_workflow_workers (
+          worker_id, run_id, step_id, project_root, branch, worktree_path, host,
+          state, context_receipt, retrieval_session_id, session_id, execution_id,
+          base_revision, allowed_files, handoff_json, created_at, updated_at
+        ) VALUES (?, ?, ?, ?, ?, ?, ?, 'planned', ?, ?, ?, ?, ?, ?, ?, ?, ?)
+        ON CONFLICT DO NOTHING
+      `).run(
+        workerId,
+        input.runId,
+        input.stepId,
+        input.projectRoot,
+        input.branch,
+        input.worktreePath,
+        input.host,
+        input.contextReceipt,
+        input.retrievalSessionId ?? null,
+        input.sessionId ?? null,
+        input.executionId ?? null,
+        input.baseRevision,
+        JSON.stringify([...new Set(input.allowedFiles ?? [])].sort()),
+        JSON.stringify(input.handoff ?? {}),
+        now,
+        now,
+      );
+      const rows = this.db.prepare(`
+        SELECT * FROM devflow_workflow_workers
+        WHERE worker_id = ? OR (run_id = ? AND step_id = ?)
+      `).all(workerId, input.runId, input.stepId) as any[];
+      if (rows.length !== 1) throw new Error(`WORKFLOW_WORKER_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+      const record = mapWorkflowWorkerRow(rows[0]);
+      if (record.workerId !== workerId
+        || record.projectRoot !== input.projectRoot
+        || record.worktreePath !== input.worktreePath
+        || record.contextReceipt !== input.contextReceipt) {
+        throw new Error(`WORKFLOW_WORKER_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+      }
+      if (record.createdAt === now) this.appendWorkflowWorkerEvent(record, undefined, 'planned', undefined, {}, now);
+      return record;
+    });
+  }
+
+  getWorkflowWorker(projectRoot: string, workerId: string): WorkflowWorkerRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_workflow_workers WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId) as any;
+    return row ? mapWorkflowWorkerRow(row) : null;
+  }
+
+  listWorkflowWorkers(projectRoot: string, options: {
+    states?: WorkflowWorkerRecord['state'][];
+    runId?: string;
+    limit?: number;
+  } = {}): WorkflowWorkerRecord[] {
+    const conditions = ['project_root = ?'];
+    const values: unknown[] = [projectRoot];
+    if (options.runId) {
+      conditions.push('run_id = ?');
+      values.push(options.runId);
+    }
+    if (options.states?.length) {
+      conditions.push(`state IN (${options.states.map(() => '?').join(',')})`);
+      values.push(...options.states);
+    }
+    values.push(Math.max(1, Math.min(options.limit ?? 200, 2_000)));
+    const rows = this.db.prepare(`
+      SELECT * FROM devflow_workflow_workers
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY updated_at DESC, worker_id ASC LIMIT ?
+    `).all(...values) as any[];
+    return rows.map(mapWorkflowWorkerRow);
+  }
+
+  listWorkflowWorkerEvents(projectRoot: string, workerId: string): WorkflowWorkerEventRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_worker_events
+      WHERE project_root = ? AND worker_id = ?
+      ORDER BY created_at ASC, event_id ASC
+    `).all(projectRoot, workerId) as any[]).map(mapWorkflowWorkerEventRow);
+  }
+
+  leaseWorkflowWorker(
+    projectRoot: string,
+    workerId: string,
+    owner: string,
+    leaseMs: number,
+    now = Date.now(),
+  ): WorkflowWorkerRecord {
+    if (!owner.trim()) throw new Error('Workflow worker lease owner is required');
+    if (!Number.isSafeInteger(leaseMs) || leaseMs <= 0) throw new Error('Workflow worker lease must be positive');
+    return this.transitionWorkflowWorker({
+      projectRoot,
+      workerId,
+      target: 'leased',
+      leaseOwner: owner,
+      leaseExpiresAt: now + leaseMs,
+      heartbeatAt: now,
+      now,
+    });
+  }
+
+  heartbeatWorkflowWorker(
+    projectRoot: string,
+    workerId: string,
+    owner: string,
+    leaseMs: number,
+    now = Date.now(),
+  ): WorkflowWorkerRecord {
+    const result = this.db.prepare(`
+      UPDATE devflow_workflow_workers
+      SET heartbeat_at = ?, lease_expires_at = ?, updated_at = ?
+      WHERE project_root = ? AND worker_id = ? AND lease_owner = ?
+        AND state IN ('leased','starting','running','reported','verifying','merge_ready')
+    `).run(now, now + leaseMs, now, projectRoot, workerId, owner);
+    if (result.changes !== 1) throw new Error(`WORKFLOW_WORKER_HEARTBEAT_REJECTED:${workerId}`);
+    return this.getWorkflowWorker(projectRoot, workerId)!;
+  }
+
+  transitionWorkflowWorker(input: TransitionWorkflowWorkerInput): WorkflowWorkerRecord {
+    return this.withImmediateTransaction(() => {
+      const existing = this.getWorkflowWorker(input.projectRoot, input.workerId);
+      if (!existing) throw new Error(`WORKFLOW_WORKER_NOT_FOUND:${input.workerId}`);
+      if (TERMINAL_WORKFLOW_WORKER_STATES.has(existing.state)) {
+        if (existing.state === input.target) return existing;
+        throw new Error(`WORKFLOW_WORKER_TERMINAL_CONFLICT:${input.workerId}`);
+      }
+      if (!LEGAL_WORKFLOW_WORKER_TRANSITIONS[existing.state].includes(input.target)) {
+        throw new Error(`WORKFLOW_WORKER_INVALID_TRANSITION:${existing.state}->${input.target}`);
+      }
+      if (existing.leaseOwner && input.leaseOwner && existing.leaseOwner !== input.leaseOwner) {
+        throw new Error(`WORKFLOW_WORKER_LEASE_CONFLICT:${input.workerId}`);
+      }
+      const now = input.now ?? Date.now();
+      const terminal = TERMINAL_WORKFLOW_WORKER_STATES.has(input.target);
+      const clearLease = terminal || input.target === 'hold';
+      const reason = input.reason?.trim().slice(0, 1_000);
+      const result = this.db.prepare(`
+        UPDATE devflow_workflow_workers SET
+          state = ?,
+          lease_owner = CASE WHEN ? THEN NULL ELSE COALESCE(?, lease_owner) END,
+          lease_expires_at = CASE WHEN ? THEN NULL ELSE COALESCE(?, lease_expires_at) END,
+          heartbeat_at = COALESCE(?, heartbeat_at),
+          final_revision = COALESCE(?, final_revision),
+          handoff_json = CASE WHEN ? IS NULL THEN handoff_json ELSE ? END,
+          hold_reason = CASE WHEN ? = 'hold' THEN ? ELSE hold_reason END,
+          failure_reason = CASE WHEN ? = 'failed' THEN ? ELSE failure_reason END,
+          updated_at = ?, finished_at = ?
+        WHERE project_root = ? AND worker_id = ? AND state = ?
+      `).run(
+        input.target,
+        clearLease ? 1 : 0,
+        input.leaseOwner ?? null,
+        clearLease ? 1 : 0,
+        input.leaseExpiresAt ?? null,
+        input.heartbeatAt ?? null,
+        input.finalRevision ?? null,
+        input.handoff === undefined ? null : 1,
+        JSON.stringify(input.handoff ?? {}),
+        input.target,
+        reason ?? null,
+        input.target,
+        reason ?? null,
+        now,
+        terminal ? now : null,
+        input.projectRoot,
+        input.workerId,
+        existing.state,
+      );
+      if (result.changes !== 1) throw new Error(`WORKFLOW_WORKER_UPDATE_CONFLICT:${input.workerId}`);
+      const updated = this.getWorkflowWorker(input.projectRoot, input.workerId)!;
+      this.appendWorkflowWorkerEvent(updated, existing.state, input.target, reason, input.handoff ?? {}, now);
+      return updated;
+    });
+  }
+
+  recoverExpiredWorkflowWorkers(projectRoot: string, now = Date.now()): WorkflowWorkerRecord[] {
+    const expired = this.listWorkflowWorkers(projectRoot, {
+      states: ['leased', 'starting', 'running', 'reported', 'verifying', 'merge_ready'],
+      limit: 2_000,
+    }).filter(worker => worker.leaseExpiresAt !== undefined && worker.leaseExpiresAt <= now);
+    return expired.map(worker => this.transitionWorkflowWorker({
+      projectRoot,
+      workerId: worker.workerId,
+      target: 'hold',
+      leaseOwner: worker.leaseOwner,
+      reason: 'lease_expired_dirty_worktree_requires_inspection',
+      now,
+    }));
+  }
+
+  enqueueWorkflowMerge(input: EnqueueWorkflowMergeInput): WorkflowMergeRecord {
+    const now = Date.now();
+    const mergeId = input.mergeId ?? randomUUID();
+    this.db.prepare(`
+      INSERT INTO devflow_merge_queue (
+        merge_id, worker_id, project_root, state, base_revision, parent_revision,
+        candidate_revision, grader_receipts, simulation_hash, created_at, updated_at
+      ) VALUES (?, ?, ?, 'waiting', ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(worker_id) DO NOTHING
+    `).run(
+      mergeId,
+      input.workerId,
+      input.projectRoot,
+      input.baseRevision,
+      input.parentRevision,
+      input.candidateRevision,
+      JSON.stringify([...new Set(input.graderReceipts ?? [])].sort()),
+      input.simulationHash ?? null,
+      now,
+      now,
+    );
+    const record = this.getWorkflowMergeByWorker(input.projectRoot, input.workerId);
+    if (!record
+      || record.baseRevision !== input.baseRevision
+      || record.candidateRevision !== input.candidateRevision) {
+      throw new Error(`WORKFLOW_MERGE_IDENTITY_CONFLICT:${input.workerId}`);
+    }
+    return record;
+  }
+
+  getWorkflowMerge(projectRoot: string, mergeId: string): WorkflowMergeRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND merge_id = ?
+    `).get(projectRoot, mergeId) as any;
+    return row ? mapWorkflowMergeRow(row) : null;
+  }
+
+  getWorkflowMergeByWorker(projectRoot: string, workerId: string): WorkflowMergeRecord | null {
+    const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId) as any;
+    return row ? mapWorkflowMergeRow(row) : null;
+  }
+
+  listWorkflowMerges(projectRoot: string, limit = 200): WorkflowMergeRecord[] {
+    return (this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ?
+      ORDER BY created_at ASC, merge_id ASC LIMIT ?
+    `).all(projectRoot, Math.max(1, Math.min(limit, 2_000))) as any[]).map(mapWorkflowMergeRow);
+  }
+
+  transitionWorkflowMerge(
+    projectRoot: string,
+    mergeId: string,
+    target: WorkflowMergeState,
+    update: { parentRevision?: string; simulationHash?: string; mergeCommit?: string; reason?: string } = {},
+    now = Date.now(),
+  ): WorkflowMergeRecord {
+    const existing = this.getWorkflowMerge(projectRoot, mergeId);
+    if (!existing) throw new Error(`WORKFLOW_MERGE_NOT_FOUND:${mergeId}`);
+    const legal: Record<WorkflowMergeState, WorkflowMergeState[]> = {
+      waiting: ['ready', 'conflict', 'rejected'],
+      ready: ['conflict', 'merged', 'rejected'],
+      conflict: ['waiting', 'rejected'],
+      merged: [],
+      rejected: [],
+    };
+    if (!legal[existing.state].includes(target)) {
+      if (existing.state === target) return existing;
+      throw new Error(`WORKFLOW_MERGE_INVALID_TRANSITION:${existing.state}->${target}`);
+    }
+    const terminal = target === 'merged' || target === 'rejected';
+    const result = this.db.prepare(`
+      UPDATE devflow_merge_queue SET state = ?, parent_revision = COALESCE(?, parent_revision),
+        simulation_hash = COALESCE(?, simulation_hash), merge_commit = COALESCE(?, merge_commit),
+        reason = COALESCE(?, reason), updated_at = ?, finished_at = ?
+      WHERE project_root = ? AND merge_id = ? AND state = ?
+    `).run(
+      target,
+      update.parentRevision ?? null,
+      update.simulationHash ?? null,
+      update.mergeCommit ?? null,
+      update.reason?.trim().slice(0, 1_000) ?? null,
+      now,
+      terminal ? now : null,
+      projectRoot,
+      mergeId,
+      existing.state,
+    );
+    if (result.changes !== 1) throw new Error(`WORKFLOW_MERGE_UPDATE_CONFLICT:${mergeId}`);
+    return this.getWorkflowMerge(projectRoot, mergeId)!;
+  }
+
+  private appendWorkflowWorkerEvent(
+    record: WorkflowWorkerRecord,
+    fromState: WorkflowWorkerRecord['state'] | undefined,
+    toState: WorkflowWorkerRecord['state'],
+    reason: string | undefined,
+    payload: Record<string, unknown>,
+    createdAt: number,
+  ): void {
+    this.db.prepare(`
+      INSERT INTO devflow_worker_events (
+        event_id, worker_id, project_root, from_state, to_state, reason, payload_json, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      randomUUID(), record.workerId, record.projectRoot, fromState ?? null, toState,
+      reason ?? null, JSON.stringify(payload), createdAt,
+    );
+  }
+
   // Convenience methods for raw SQL queries (used by AutoChecker)
   all(sql: string, ...params: unknown[]): unknown[] {
     return this.db.prepare(sql).all(...params);