@devflow-tools/database 0.16.22 → 0.16.23

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [0.16.23](https://github.com/shilongfeicool/dev-flow/compare/v0.16.22...v0.16.23) (2026-07-28)
+
+
+### Features
+
+* **database:** persist workflow worker lifecycle ([6f57fc7](https://github.com/shilongfeicool/dev-flow/commit/6f57fc7d7f13915b4f9b7faaa5e37c1a04182cad))
+* **workflow:** execute durable worker lifecycle ([799cc9d](https://github.com/shilongfeicool/dev-flow/commit/799cc9d341b6d4251717e20665654809ed84e29d))
+
+
+
+
+
 ## [0.16.22](https://github.com/shilongfeicool/dev-flow/compare/v0.16.21...v0.16.22) (2026-07-28)
 
 

package/__tests__/database.workflow-workers.test.ts

@@ -0,0 +1,60 @@
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { DevFlowDatabase } from '../src/database.js';
+
+const roots: string[] = [];
+
+function open(): { db: DevFlowDatabase; root: string } {
+  const root = mkdtempSync(join(tmpdir(), 'devflow-workers-'));
+  roots.push(root);
+  return { db: new DevFlowDatabase(root), root };
+}
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true });
+});
+
+describe('workflow worker persistence', () => {
+  it('persists legal transitions and refuses terminal mutation', () => {
+    const { db, root } = open();
+    const worker = db.createWorkflowWorker({
+      runId: 'run-1', stepId: 'step-1', projectRoot: root,
+      branch: 'devflow/run-1/step-1', worktreePath: join(root, '.worker'),
+      host: 'codex', contextReceipt: 'receipt-1', baseRevision: 'a'.repeat(40),
+    });
+    db.leaseWorkflowWorker(root, worker.workerId, 'owner', 1_000, 100);
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'starting', leaseOwner: 'owner', now: 110 });
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'running', leaseOwner: 'owner', now: 120 });
+    db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'failed', leaseOwner: 'owner', reason: 'test', now: 130 });
+    expect(() => db.transitionWorkflowWorker({ projectRoot: root, workerId: worker.workerId, target: 'hold' }))
+      .toThrow(/TERMINAL_CONFLICT/);
+    expect(db.listWorkflowWorkerEvents(root, worker.workerId)).toHaveLength(5);
+    db.close();
+  });
+
+  it('recovers expired leases to hold without retrying the worktree', () => {
+    const { db, root } = open();
+    const worker = db.createWorkflowWorker({
+      runId: 'run-2', stepId: 'step-2', projectRoot: root,
+      branch: 'devflow/run-2/step-2', worktreePath: join(root, '.worker-2'),
+      host: 'claude-code', contextReceipt: 'receipt-2', baseRevision: 'b'.repeat(40),
+    });
+    db.leaseWorkflowWorker(root, worker.workerId, 'owner', 10, 100);
+    expect(db.recoverExpiredWorkflowWorkers(root, 111)[0]?.state).toBe('hold');
+    db.close();
+  });
+
+  it('keeps merge queue insertion idempotent', () => {
+    const { db, root } = open();
+    const input = {
+      workerId: 'worker-3', projectRoot: root, baseRevision: 'a', parentRevision: 'b',
+      candidateRevision: 'c', graderReceipts: ['grader:1'], simulationHash: 'sha256:1',
+    };
+    const first = db.enqueueWorkflowMerge(input);
+    expect(db.enqueueWorkflowMerge(input).mergeId).toBe(first.mergeId);
+    expect(db.transitionWorkflowMerge(root, first.mergeId, 'ready').state).toBe('ready');
+    db.close();
+  });
+});

package/dist/database.d.ts

@@ -3,6 +3,7 @@ import { type SessionObligationRecord, type SessionObligationState } from './obl
 import { type FailHostActionInput, type HostActionRecord, type ReportHostActionInput, type RequestHostActionInput, type StartHostActionInput, type VerifyHostActionInput } from './host-actions';
 import { type AppendRetrievalCycleInput, type CreateRetrievalSessionInput, type RetrievalCycleRecord, type RetrievalSessionRecord, type RetrievalSessionState } from './retrieval-sessions';
 import { type AddLearningCandidateEvidenceInput, type LearningCandidateEvidenceRecord, type LearningCandidateRecord, type LearningCandidateState, type LearningCandidateVersionRecord, type TransitionLearningCandidateInput, type UpsertLearningCandidateInput } from './learning-candidates';
+import { type CreateWorkflowWorkerInput, type EnqueueWorkflowMergeInput, type TransitionWorkflowWorkerInput, type WorkflowMergeRecord, type WorkflowMergeState, type WorkflowWorkerEventRecord, type WorkflowWorkerRecord } from './workflow-workers';
 export interface BenchmarkReportRecord {
     runId: string;
     suiteId: string;
@@ -350,6 +351,7 @@ export declare class DevFlowDatabase {
     listSessionClosures(projectRoot: string, limit?: number): SessionClosureRecord[];
     leaseWork(input: LeaseWorkInput): WorkItemRecord[];
     completeWork(id: string, owner: string, now?: number): boolean;
+    heartbeatWork(id: string, owner: string, leaseMs: number, now?: number): boolean;
     retryWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean;
     deferWork(id: string, owner: string, error: WorkError, nextAttemptAt: number): boolean;
     deadLetterWork(id: string, owner: string, error: WorkError): boolean;
@@ -448,6 +450,29 @@ export declare class DevFlowDatabase {
     private withImmediateTransaction;
     private isTerminalHostActionState;
     private isLegalHostActionTransition;
+    createWorkflowWorker(input: CreateWorkflowWorkerInput): WorkflowWorkerRecord;
+    getWorkflowWorker(projectRoot: string, workerId: string): WorkflowWorkerRecord | null;
+    listWorkflowWorkers(projectRoot: string, options?: {
+        states?: WorkflowWorkerRecord['state'][];
+        runId?: string;
+        limit?: number;
+    }): WorkflowWorkerRecord[];
+    listWorkflowWorkerEvents(projectRoot: string, workerId: string): WorkflowWorkerEventRecord[];
+    leaseWorkflowWorker(projectRoot: string, workerId: string, owner: string, leaseMs: number, now?: number): WorkflowWorkerRecord;
+    heartbeatWorkflowWorker(projectRoot: string, workerId: string, owner: string, leaseMs: number, now?: number): WorkflowWorkerRecord;
+    transitionWorkflowWorker(input: TransitionWorkflowWorkerInput): WorkflowWorkerRecord;
+    recoverExpiredWorkflowWorkers(projectRoot: string, now?: number): WorkflowWorkerRecord[];
+    enqueueWorkflowMerge(input: EnqueueWorkflowMergeInput): WorkflowMergeRecord;
+    getWorkflowMerge(projectRoot: string, mergeId: string): WorkflowMergeRecord | null;
+    getWorkflowMergeByWorker(projectRoot: string, workerId: string): WorkflowMergeRecord | null;
+    listWorkflowMerges(projectRoot: string, limit?: number): WorkflowMergeRecord[];
+    transitionWorkflowMerge(projectRoot: string, mergeId: string, target: WorkflowMergeState, update?: {
+        parentRevision?: string;
+        simulationHash?: string;
+        mergeCommit?: string;
+        reason?: string;
+    }, now?: number): WorkflowMergeRecord;
+    private appendWorkflowWorkerEvent;
     all(sql: string, ...params: unknown[]): unknown[];
     get(sql: string, ...params: unknown[]): unknown;
     close(): void;

package/dist/database.js

@@ -12,6 +12,7 @@ const obligation_ledger_1 = require("./obligation-ledger");
 const host_actions_1 = require("./host-actions");
 const retrieval_sessions_1 = require("./retrieval-sessions");
 const learning_candidates_1 = require("./learning-candidates");
+const workflow_workers_1 = require("./workflow-workers");
 const CONTEXT_REQUIRED_SKILLS = new Set([
     'react', 'vue', 'nest', 'nextjs', 'graphql', 'typescript',
 ]);
@@ -618,6 +619,85 @@ 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)
         try {
@@ -2340,6 +2420,15 @@ class DevFlowDatabase {
         }
         return completed;
     }
+    heartbeatWork(id, owner, leaseMs, now = Date.now()) {
+        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, owner, error, nextAttemptAt) {
         const updatedAt = Date.now();
         return this.db.prepare(`
@@ -3306,6 +3395,232 @@ class DevFlowDatabase {
         }
         return false;
     }
+    // ---- Isolated Workflow Workers ----
+    createWorkflowWorker(input) {
+        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],
+        ]) {
+            if (!value.trim())
+                throw new Error(`Workflow worker requires a ${name}`);
+        }
+        const workerId = input.workerId ?? (0, crypto_1.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);
+            if (rows.length !== 1)
+                throw new Error(`WORKFLOW_WORKER_IDENTITY_CONFLICT:${input.runId}:${input.stepId}`);
+            const record = (0, workflow_workers_1.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, workerId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_workflow_workers WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId);
+        return row ? (0, workflow_workers_1.mapWorkflowWorkerRow)(row) : null;
+    }
+    listWorkflowWorkers(projectRoot, options = {}) {
+        const conditions = ['project_root = ?'];
+        const values = [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, 2000)));
+        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);
+        return rows.map(workflow_workers_1.mapWorkflowWorkerRow);
+    }
+    listWorkflowWorkerEvents(projectRoot, workerId) {
+        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).map(workflow_workers_1.mapWorkflowWorkerEventRow);
+    }
+    leaseWorkflowWorker(projectRoot, workerId, owner, leaseMs, now = Date.now()) {
+        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, workerId, owner, leaseMs, now = Date.now()) {
+        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) {
+        return this.withImmediateTransaction(() => {
+            const existing = this.getWorkflowWorker(input.projectRoot, input.workerId);
+            if (!existing)
+                throw new Error(`WORKFLOW_WORKER_NOT_FOUND:${input.workerId}`);
+            if (workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES.has(existing.state)) {
+                if (existing.state === input.target)
+                    return existing;
+                throw new Error(`WORKFLOW_WORKER_TERMINAL_CONFLICT:${input.workerId}`);
+            }
+            if (!workflow_workers_1.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 = workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES.has(input.target);
+            const clearLease = terminal || input.target === 'hold';
+            const reason = input.reason?.trim().slice(0, 1000);
+            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, now = Date.now()) {
+        const expired = this.listWorkflowWorkers(projectRoot, {
+            states: ['leased', 'starting', 'running', 'reported', 'verifying', 'merge_ready'],
+            limit: 2000,
+        }).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) {
+        const now = Date.now();
+        const mergeId = input.mergeId ?? (0, crypto_1.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, mergeId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND merge_id = ?
+    `).get(projectRoot, mergeId);
+        return row ? (0, workflow_workers_1.mapWorkflowMergeRow)(row) : null;
+    }
+    getWorkflowMergeByWorker(projectRoot, workerId) {
+        const row = this.db.prepare(`
+      SELECT * FROM devflow_merge_queue WHERE project_root = ? AND worker_id = ?
+    `).get(projectRoot, workerId);
+        return row ? (0, workflow_workers_1.mapWorkflowMergeRow)(row) : null;
+    }
+    listWorkflowMerges(projectRoot, limit = 200) {
+        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, 2000))).map(workflow_workers_1.mapWorkflowMergeRow);
+    }
+    transitionWorkflowMerge(projectRoot, mergeId, target, update = {}, now = Date.now()) {
+        const existing = this.getWorkflowMerge(projectRoot, mergeId);
+        if (!existing)
+            throw new Error(`WORKFLOW_MERGE_NOT_FOUND:${mergeId}`);
+        const legal = {
+            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, 1000) ?? 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);
+    }
+    appendWorkflowWorkerEvent(record, fromState, toState, reason, payload, createdAt) {
+        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((0, crypto_1.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, ...params) {
         return this.db.prepare(sql).all(...params);

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { RETRIEVAL_MAX_CYCLES, isRetrievalSessionState } from './retrieval-sessi
 export type { AppendRetrievalCycleInput, CreateRetrievalSessionInput, RetrievalCycleRecord, RetrievalGapKind, RetrievalGapRecord, RetrievalSessionRecord, RetrievalSessionState, } from './retrieval-sessions';
 export type { FailHostActionInput, HostActionRecord, HostActionState, ReportHostActionInput, RequestHostActionInput, StartHostActionInput, VerifyHostActionInput, } from './host-actions';
 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, mapLearningVersionRow, stableLearningJson, } from './learning-candidates';
 export type { AddLearningCandidateEvidenceInput, LearningCandidateEvidenceRecord, LearningCandidateKind, LearningCandidateRecord, LearningCandidateState, LearningCandidateVersionRecord, LearningEvidencePolarity, LearningOutcomeState, TransitionLearningCandidateInput, UpsertLearningCandidateInput, } from './learning-candidates';
 export type { SessionObligationKind, SessionObligationRecord, SessionObligationState, } from './obligation-ledger';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.stableLearningJson = exports.mapLearningVersionRow = exports.mapLearningEvidenceRow = exports.mapLearningCandidateRow = 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.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;
 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; } });
@@ -16,6 +16,12 @@ Object.defineProperty(exports, "isRetrievalSessionState", { enumerable: true, ge
 var obligation_ledger_1 = require("./obligation-ledger");
 Object.defineProperty(exports, "mapSessionObligationRow", { enumerable: true, get: function () { return obligation_ledger_1.mapSessionObligationRow; } });
 Object.defineProperty(exports, "normalizeTurnId", { enumerable: true, get: function () { return obligation_ledger_1.normalizeTurnId; } });
+var workflow_workers_1 = require("./workflow-workers");
+Object.defineProperty(exports, "LEGAL_WORKFLOW_WORKER_TRANSITIONS", { enumerable: true, get: function () { return workflow_workers_1.LEGAL_WORKFLOW_WORKER_TRANSITIONS; } });
+Object.defineProperty(exports, "TERMINAL_WORKFLOW_WORKER_STATES", { enumerable: true, get: function () { return workflow_workers_1.TERMINAL_WORKFLOW_WORKER_STATES; } });
+Object.defineProperty(exports, "mapWorkflowMergeRow", { enumerable: true, get: function () { return workflow_workers_1.mapWorkflowMergeRow; } });
+Object.defineProperty(exports, "mapWorkflowWorkerEventRow", { enumerable: true, get: function () { return workflow_workers_1.mapWorkflowWorkerEventRow; } });
+Object.defineProperty(exports, "mapWorkflowWorkerRow", { enumerable: true, get: function () { return workflow_workers_1.mapWorkflowWorkerRow; } });
 var learning_candidates_1 = require("./learning-candidates");
 Object.defineProperty(exports, "mapLearningCandidateRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningCandidateRow; } });
 Object.defineProperty(exports, "mapLearningEvidenceRow", { enumerable: true, get: function () { return learning_candidates_1.mapLearningEvidenceRow; } });

package/dist/work-queue.d.ts

@@ -1,4 +1,4 @@
-export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | 'memory.vector_backfill' | 'context.prefetch' | 'learning.analyze_session' | 'session.bootstrap' | 'session.finalize' | 'telemetry.reconcile';
+export type WorkKind = 'memory.explicit_commit' | 'memory.explicit_enrichment' | 'memory.turn_capture' | 'memory.turn_distill' | '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';
 export type WorkState = 'pending' | 'leased' | 'completed' | 'failed' | 'dead_letter';
 export interface WorkError {
     category: string;

package/dist/workflow-workers.d.ts

@@ -0,0 +1,97 @@
+export type WorkflowWorkerState = 'planned' | 'leased' | 'starting' | 'running' | 'reported' | 'verifying' | 'merge_ready' | 'merged' | 'hold' | 'failed' | 'cancelled';
+export type WorkflowMergeState = 'waiting' | 'ready' | 'conflict' | 'merged' | 'rejected';
+export interface WorkflowWorkerRecord {
+    workerId: string;
+    runId: string;
+    stepId: string;
+    projectRoot: string;
+    branch: string;
+    worktreePath: string;
+    host: string;
+    state: WorkflowWorkerState;
+    leaseOwner?: string;
+    leaseExpiresAt?: number;
+    heartbeatAt?: number;
+    contextReceipt: string;
+    retrievalSessionId?: string;
+    sessionId?: string;
+    executionId?: string;
+    baseRevision: string;
+    finalRevision?: string;
+    allowedFiles: string[];
+    handoff: Record<string, unknown>;
+    holdReason?: string;
+    failureReason?: string;
+    createdAt: number;
+    updatedAt: number;
+    finishedAt?: number;
+}
+export interface CreateWorkflowWorkerInput {
+    workerId?: string;
+    runId: string;
+    stepId: string;
+    projectRoot: string;
+    branch: string;
+    worktreePath: string;
+    host: string;
+    contextReceipt: string;
+    retrievalSessionId?: string;
+    sessionId?: string;
+    executionId?: string;
+    baseRevision: string;
+    allowedFiles?: string[];
+    handoff?: Record<string, unknown>;
+}
+export interface TransitionWorkflowWorkerInput {
+    projectRoot: string;
+    workerId: string;
+    target: WorkflowWorkerState;
+    leaseOwner?: string;
+    leaseExpiresAt?: number;
+    heartbeatAt?: number;
+    finalRevision?: string;
+    handoff?: Record<string, unknown>;
+    reason?: string;
+    now?: number;
+}
+export interface WorkflowWorkerEventRecord {
+    eventId: string;
+    workerId: string;
+    projectRoot: string;
+    fromState?: WorkflowWorkerState;
+    toState: WorkflowWorkerState;
+    reason?: string;
+    payload: Record<string, unknown>;
+    createdAt: number;
+}
+export interface WorkflowMergeRecord {
+    mergeId: string;
+    workerId: string;
+    projectRoot: string;
+    state: WorkflowMergeState;
+    baseRevision: string;
+    parentRevision: string;
+    candidateRevision: string;
+    graderReceipts: string[];
+    simulationHash?: string;
+    mergeCommit?: string;
+    reason?: string;
+    createdAt: number;
+    updatedAt: number;
+    finishedAt?: number;
+}
+export interface EnqueueWorkflowMergeInput {
+    mergeId?: string;
+    workerId: string;
+    projectRoot: string;
+    baseRevision: string;
+    parentRevision: string;
+    candidateRevision: string;
+    graderReceipts?: string[];
+    simulationHash?: string;
+}
+export declare const TERMINAL_WORKFLOW_WORKER_STATES: Set<WorkflowWorkerState>;
+export declare const LEGAL_WORKFLOW_WORKER_TRANSITIONS: Record<WorkflowWorkerState, WorkflowWorkerState[]>;
+export declare function mapWorkflowWorkerRow(row: any): WorkflowWorkerRecord;
+export declare function mapWorkflowWorkerEventRow(row: any): WorkflowWorkerEventRecord;
+export declare function mapWorkflowMergeRow(row: any): WorkflowMergeRecord;