@devflow-tools/database 0.16.22 → 0.16.24

package/dist/workflow-workers.js

@@ -0,0 +1,90 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = exports.TERMINAL_WORKFLOW_WORKER_STATES = void 0;
+exports.mapWorkflowWorkerRow = mapWorkflowWorkerRow;
+exports.mapWorkflowWorkerEventRow = mapWorkflowWorkerEventRow;
+exports.mapWorkflowMergeRow = mapWorkflowMergeRow;
+exports.TERMINAL_WORKFLOW_WORKER_STATES = new Set([
+    'merged', 'failed', 'cancelled',
+]);
+exports.LEGAL_WORKFLOW_WORKER_TRANSITIONS = {
+    planned: ['leased', 'cancelled', 'hold', 'failed'],
+    leased: ['starting', 'hold', 'cancelled', 'failed'],
+    starting: ['running', 'reported', 'hold', 'cancelled', 'failed'],
+    running: ['reported', 'hold', 'cancelled', 'failed'],
+    reported: ['verifying', 'hold', 'cancelled', 'failed'],
+    verifying: ['merge_ready', 'hold', 'cancelled', 'failed'],
+    merge_ready: ['merged', 'hold', 'cancelled', 'failed'],
+    merged: [],
+    hold: ['leased', 'cancelled', 'failed'],
+    failed: [],
+    cancelled: [],
+};
+function mapWorkflowWorkerRow(row) {
+    return {
+        workerId: row.worker_id,
+        runId: row.run_id,
+        stepId: row.step_id,
+        projectRoot: row.project_root,
+        branch: row.branch,
+        worktreePath: row.worktree_path,
+        host: row.host,
+        state: row.state,
+        leaseOwner: row.lease_owner ?? undefined,
+        leaseExpiresAt: row.lease_expires_at ?? undefined,
+        heartbeatAt: row.heartbeat_at ?? undefined,
+        contextReceipt: row.context_receipt,
+        retrievalSessionId: row.retrieval_session_id ?? undefined,
+        sessionId: row.session_id ?? undefined,
+        executionId: row.execution_id ?? undefined,
+        baseRevision: row.base_revision,
+        finalRevision: row.final_revision ?? undefined,
+        allowedFiles: parseJson(row.allowed_files, []),
+        handoff: parseJson(row.handoff_json, {}),
+        holdReason: row.hold_reason ?? undefined,
+        failureReason: row.failure_reason ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        finishedAt: row.finished_at ?? undefined,
+    };
+}
+function mapWorkflowWorkerEventRow(row) {
+    return {
+        eventId: row.event_id,
+        workerId: row.worker_id,
+        projectRoot: row.project_root,
+        fromState: row.from_state ?? undefined,
+        toState: row.to_state,
+        reason: row.reason ?? undefined,
+        payload: parseJson(row.payload_json, {}),
+        createdAt: row.created_at,
+    };
+}
+function mapWorkflowMergeRow(row) {
+    return {
+        mergeId: row.merge_id,
+        workerId: row.worker_id,
+        projectRoot: row.project_root,
+        state: row.state,
+        baseRevision: row.base_revision,
+        parentRevision: row.parent_revision,
+        candidateRevision: row.candidate_revision,
+        graderReceipts: parseJson(row.grader_receipts, []),
+        simulationHash: row.simulation_hash ?? undefined,
+        mergeCommit: row.merge_commit ?? undefined,
+        reason: row.reason ?? undefined,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+        finishedAt: row.finished_at ?? undefined,
+    };
+}
+function parseJson(value, fallback) {
+    if (typeof value !== 'string' || value.length === 0)
+        return fallback;
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return fallback;
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devflow-tools/database",
-  "version": "0.16.22",
+  "version": "0.16.24",
   "description": "DevFlow SQLite database package",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,5 +13,5 @@
     "typescript": "^5.5.0",
     "vitest": "^2.0.0"
   },
-  "gitHead": "964af33767bf232606e63d973b3a29d7d53c8119"
+  "gitHead": "b21cfa5fadfa43922e724b49156645504b88be34"
 }

package/src/database.ts

@@ -1,6 +1,6 @@
 import { NodeSqliteDatabase } from './node-sqlite';
-import { join, dirname } from 'path';
-import { existsSync, mkdirSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { existsSync, mkdirSync, realpathSync } from 'fs';
 import { homedir } from 'os';
 import { randomUUID } from 'crypto';
 import type {
@@ -55,6 +55,20 @@ import {
   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;
@@ -808,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)
@@ -2926,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(`
@@ -4166,6 +4268,338 @@ export class DevFlowDatabase {
     return false;
   }
 
+  // ---- Isolated Workflow Workers ----
+
+  createWorkflowWorker(input: CreateWorkflowWorkerInput): WorkflowWorkerRecord {
+    const projectRoot = canonicalWorkflowProjectRoot(input.projectRoot);
+    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,
+        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 !== 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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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[] {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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[] {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 {
+    const projectRoot = canonicalWorkflowProjectRoot(input.projectRoot);
+    return this.withImmediateTransaction(() => {
+      const existing = this.getWorkflowWorker(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,
+        projectRoot,
+        input.workerId,
+        existing.state,
+      );
+      if (result.changes !== 1) throw new Error(`WORKFLOW_WORKER_UPDATE_CONFLICT:${input.workerId}`);
+      const updated = this.getWorkflowWorker(projectRoot, input.workerId)!;
+      this.appendWorkflowWorkerEvent(updated, existing.state, input.target, reason, input.handoff ?? {}, now);
+      return updated;
+    });
+  }
+
+  recoverExpiredWorkflowWorkers(projectRoot: string, now = Date.now()): WorkflowWorkerRecord[] {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 projectRoot = canonicalWorkflowProjectRoot(input.projectRoot);
+    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,
+      projectRoot,
+      input.baseRevision,
+      input.parentRevision,
+      input.candidateRevision,
+      JSON.stringify([...new Set(input.graderReceipts ?? [])].sort()),
+      input.simulationHash ?? null,
+      now,
+      now,
+    );
+    const record = this.getWorkflowMergeByWorker(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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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[] {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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 {
+    projectRoot = canonicalWorkflowProjectRoot(projectRoot);
+    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);
@@ -4293,3 +4727,8 @@ function mergeExecutionMetadata(
   }
   return merged;
 }
+
+function canonicalWorkflowProjectRoot(projectRoot: string): string {
+  const resolved = resolve(projectRoot);
+  try { return realpathSync(resolved); } catch { return resolved; }
+}

package/src/index.ts

@@ -59,6 +59,23 @@ export {
   mapSessionObligationRow,
   normalizeTurnId,
 } from './obligation-ledger';
+export {
+  LEGAL_WORKFLOW_WORKER_TRANSITIONS,
+  TERMINAL_WORKFLOW_WORKER_STATES,
+  mapWorkflowMergeRow,
+  mapWorkflowWorkerEventRow,
+  mapWorkflowWorkerRow,
+} from './workflow-workers';
+export type {
+  CreateWorkflowWorkerInput,
+  EnqueueWorkflowMergeInput,
+  TransitionWorkflowWorkerInput,
+  WorkflowMergeRecord,
+  WorkflowMergeState,
+  WorkflowWorkerEventRecord,
+  WorkflowWorkerRecord,
+  WorkflowWorkerState,
+} from './workflow-workers';
 export {
   mapLearningCandidateRow,
   mapLearningEvidenceRow,

package/src/work-queue.ts

@@ -6,6 +6,11 @@ export type WorkKind =
   | 'memory.vector_backfill'
   | 'context.prefetch'
   | 'learning.analyze_session'
+  | 'workflow.worker_start'
+  | 'workflow.worker_monitor'
+  | 'workflow.worker_verify'
+  | 'workflow.worker_merge'
+  | 'workflow.worker_cleanup'
   | 'session.bootstrap'
   | 'session.finalize'
   | 'telemetry.reconcile';