@cleocode/core 2026.4.9 → 2026.4.12

package/dist/store/json.js

@@ -0,0 +1,208 @@
+/**
+ * JSON read/write with schema validation, locking, and backup.
+ * This is the primary data access layer for CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+import { createHash } from 'node:crypto';
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+import { atomicWrite, atomicWriteJson, safeReadFile } from './atomic.js';
+import { createBackup } from './backup.js';
+import { withLock } from './lock.js';
+/**
+ * Read and parse a JSON file.
+ * Returns null if the file does not exist.
+ */
+export async function readJson(filePath) {
+    const content = await safeReadFile(filePath);
+    if (content === null)
+        return null;
+    try {
+        return JSON.parse(content);
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, `Invalid JSON in: ${filePath}`, { cause: err });
+    }
+}
+/**
+ * Read a JSON file, throwing if it doesn't exist.
+ */
+export async function readJsonRequired(filePath) {
+    const data = await readJson(filePath);
+    if (data === null) {
+        throw new CleoError(ExitCode.NOT_FOUND, `Required file not found: ${filePath}`);
+    }
+    return data;
+}
+/**
+ * Compute a truncated SHA-256 checksum of a value.
+ * Used for integrity verification (matches Bash CLI's 16-char hex format).
+ */
+export function computeChecksum(data) {
+    const json = JSON.stringify(data);
+    const hash = createHash('sha256').update(json).digest('hex');
+    return hash.substring(0, 16);
+}
+/**
+ * Save JSON data with optional locking, backup, and validation.
+ * Follows the CLEO atomic write pattern:
+ *   1. Acquire lock
+ *   2. Validate data
+ *   3. Create backup of existing file
+ *   4. Atomic write (temp file -> rename)
+ *   5. Release lock
+ */
+export async function saveJson(filePath, data, options) {
+    await withLock(filePath, async () => {
+        // Validate before write
+        if (options?.validate) {
+            try {
+                await options.validate(data);
+            }
+            catch (err) {
+                throw new CleoError(ExitCode.VALIDATION_ERROR, `Validation failed before write: ${filePath}`, { cause: err });
+            }
+        }
+        // Create backup if configured
+        if (options?.backupDir) {
+            try {
+                await createBackup(filePath, options.backupDir, options.maxBackups);
+            }
+            catch {
+                // Backup failure is non-fatal for first write (file may not exist yet)
+            }
+        }
+        // Atomic write
+        await atomicWriteJson(filePath, data, { indent: options?.indent });
+        // Dispatch Notification hook (best-effort, fire-and-forget)
+        import('../hooks/registry.js')
+            .then(({ hooks: h }) => h.dispatch('Notification', process.cwd(), {
+            timestamp: new Date().toISOString(),
+            filePath,
+            changeType: 'write',
+        }))
+            .catch(() => {
+            /* hook errors are non-fatal */
+        });
+    });
+}
+/**
+ * Append a line to a JSONL file atomically.
+ * Used for manifest entries and audit logs.
+ */
+export async function appendJsonl(filePath, entry) {
+    const existing = await safeReadFile(filePath);
+    const line = JSON.stringify(entry);
+    const content = existing ? existing.trimEnd() + '\n' + line + '\n' : line + '\n';
+    await atomicWrite(filePath, content);
+}
+/**
+ * Read log entries from a hybrid JSON/JSONL file.
+ * Handles three formats:
+ *   1. Pure JSON: `{ "entries": [...] }` (legacy bash format)
+ *   2. Pure JSONL: one JSON object per line (new TS format)
+ *   3. Hybrid: JSON object followed by JSONL lines (migration state)
+ * Returns a flat array of all entries found.
+ * @task T4622
+ */
+export async function readLogEntries(filePath) {
+    const content = await safeReadFile(filePath);
+    if (content === null)
+        return [];
+    const trimmed = content.trim();
+    if (!trimmed)
+        return [];
+    // Fast path: try parsing as a single JSON object
+    try {
+        const parsed = JSON.parse(trimmed);
+        if (Array.isArray(parsed))
+            return parsed;
+        if (parsed && typeof parsed === 'object' && Array.isArray(parsed.entries)) {
+            return parsed.entries;
+        }
+        // Single object, wrap in array
+        return [parsed];
+    }
+    catch {
+        // Not valid JSON - handle hybrid format
+    }
+    // Hybrid format: find where the initial JSON object ends, then parse JSONL after it
+    const entries = [];
+    if (trimmed.startsWith('{')) {
+        // Find the matching closing brace for the initial JSON object
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+        let jsonEnd = -1;
+        for (let i = 0; i < trimmed.length; i++) {
+            const ch = trimmed[i];
+            if (escaped) {
+                escaped = false;
+                continue;
+            }
+            if (ch === '\\' && inString) {
+                escaped = true;
+                continue;
+            }
+            if (ch === '"') {
+                inString = !inString;
+                continue;
+            }
+            if (inString)
+                continue;
+            if (ch === '{')
+                depth++;
+            else if (ch === '}') {
+                depth--;
+                if (depth === 0) {
+                    jsonEnd = i + 1;
+                    break;
+                }
+            }
+        }
+        if (jsonEnd > 0) {
+            // Parse the initial JSON object
+            try {
+                const initialJson = JSON.parse(trimmed.substring(0, jsonEnd));
+                if (initialJson && Array.isArray(initialJson.entries)) {
+                    entries.push(...initialJson.entries);
+                }
+            }
+            catch {
+                // Corrupted initial JSON - skip it
+            }
+            // Parse remaining lines as JSONL
+            const remainder = trimmed.substring(jsonEnd).trim();
+            if (remainder) {
+                for (const line of remainder.split('\n')) {
+                    const l = line.trim();
+                    if (!l || !l.startsWith('{'))
+                        continue;
+                    try {
+                        entries.push(JSON.parse(l));
+                    }
+                    catch {
+                        // Skip unparseable lines
+                    }
+                }
+            }
+        }
+    }
+    else {
+        // Pure JSONL (no initial JSON object)
+        for (const line of trimmed.split('\n')) {
+            const l = line.trim();
+            if (!l || !l.startsWith('{'))
+                continue;
+            try {
+                entries.push(JSON.parse(l));
+            }
+            catch {
+                // Skip unparseable lines
+            }
+        }
+    }
+    return entries;
+}
+//# sourceMappingURL=json.js.map

package/dist/store/json.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.js","sourceRoot":"","sources":["../../src/store/json.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AACzC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAErC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAc,QAAgB;IAC1D,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IAElC,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAM,CAAC;IAClC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,gBAAgB,EAAE,oBAAoB,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;IACjG,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAc,QAAgB;IAClE,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAI,QAAQ,CAAC,CAAC;IACzC,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,4BAA4B,QAAQ,EAAE,CAAC,CAAC;IAClF,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,IAAa;IAC3C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IAClC,MAAM,IAAI,GAAG,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAC7D,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAC/B,CAAC;AAcD;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,IAAa,EACb,OAAyB;IAEzB,MAAM,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;QAClC,wBAAwB;QACxB,IAAI,OAAO,EAAE,QAAQ,EAAE,CAAC;YACtB,IAAI,CAAC;gBACH,MAAM,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YAC/B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,SAAS,CACjB,QAAQ,CAAC,gBAAgB,EACzB,mCAAmC,QAAQ,EAAE,EAC7C,EAAE,KAAK,EAAE,GAAG,EAAE,CACf,CAAC;YACJ,CAAC;QACH,CAAC;QAED,8BAA8B;QAC9B,IAAI,OAAO,EAAE,SAAS,EAAE,CAAC;YACvB,IAAI,CAAC;gBACH,MAAM,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,SAAS,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC;YACtE,CAAC;YAAC,MAAM,CAAC;gBACP,uEAAuE;YACzE,CAAC;QACH,CAAC;QAED,eAAe;QACf,MAAM,eAAe,CAAC,QAAQ,EAAE,IAAI,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC;QAEnE,4DAA4D;QAC5D,MAAM,CAAC,sBAAsB,CAAC;aAC3B,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,EAAE,CACrB,CAAC,CAAC,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE;YACxC,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;YACnC,QAAQ;YACR,UAAU,EAAE,OAAgB;SAC7B,CAAC,CACH;aACA,KAAK,CAAC,GAAG,EAAE;YACV,+BAA+B;QACjC,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,QAAgB,EAAE,KAAc;IAChE,MAAM,QAAQ,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC9C,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,EAAE,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,GAAG,IAAI,CAAC;IACjF,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,QAAgB;IACnD,MAAM,OAAO,GAAG,MAAM,YAAY,CAAC,QAAQ,CAAC,CAAC;IAC7C,IAAI,OAAO,KAAK,IAAI;QAAE,OAAO,EAAE,CAAC;IAEhC,MAAM,OAAO,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAC/B,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IAExB,iDAAiD;IACjD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACnC,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAAE,OAAO,MAAmC,CAAC;QACtE,IAAI,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;YAC1E,OAAO,MAAM,CAAC,OAAoC,CAAC;QACrD,CAAC;QACD,+BAA+B;QAC/B,OAAO,CAAC,MAAiC,CAAC,CAAC;IAC7C,CAAC;IAAC,MAAM,CAAC;QACP,wCAAwC;IAC1C,CAAC;IAED,oFAAoF;IACpF,MAAM,OAAO,GAA8B,EAAE,CAAC;IAE9C,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;QAC5B,8DAA8D;QAC9D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC;QAEjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACxC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAE,CAAC;YACvB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,GAAG,KAAK,CAAC;gBAChB,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,IAAI,IAAI,QAAQ,EAAE,CAAC;gBAC5B,OAAO,GAAG,IAAI,CAAC;gBACf,SAAS;YACX,CAAC;YACD,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACf,QAAQ,GAAG,CAAC,QAAQ,CAAC;gBACrB,SAAS;YACX,CAAC;YACD,IAAI,QAAQ;gBAAE,SAAS;YACvB,IAAI,EAAE,KAAK,GAAG;gBAAE,KAAK,EAAE,CAAC;iBACnB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;gBACpB,KAAK,EAAE,CAAC;gBACR,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;oBAChB,OAAO,GAAG,CAAC,GAAG,CAAC,CAAC;oBAChB,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC;QAED,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;YAChB,gCAAgC;YAChC,IAAI,CAAC;gBACH,MAAM,WAAW,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;gBAC9D,IAAI,WAAW,IAAI,KAAK,CAAC,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC;oBACtD,OAAO,CAAC,IAAI,CAAC,GAAI,WAAW,CAAC,OAAqC,CAAC,CAAC;gBACtE,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,mCAAmC;YACrC,CAAC;YAED,iCAAiC;YACjC,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;YACpD,IAAI,SAAS,EAAE,CAAC;gBACd,KAAK,MAAM,IAAI,IAAI,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;oBACzC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;oBACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;wBAAE,SAAS;oBACvC,IAAI,CAAC;wBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;oBACzD,CAAC;oBAAC,MAAM,CAAC;wBACP,yBAAyB;oBAC3B,CAAC;gBACH,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,sCAAsC;QACtC,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACvC,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;YACtB,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC;gBAAE,SAAS;YACvC,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAA4B,CAAC,CAAC;YACzD,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/store/lifecycle-store.js

@@ -0,0 +1,249 @@
+/**
+ * SQLite-backed lifecycle store operations.
+ *
+ * Query and mutation functions for lifecycle pipeline tables:
+ * lifecycle_pipelines, lifecycle_stages, lifecycle_gate_results,
+ * lifecycle_evidence, lifecycle_transitions.
+ *
+ * Used by src/core/lifecycle/resume.ts to avoid direct store-layer imports.
+ *
+ * @task T4832
+ * @epic T4454
+ */
+import { and, asc, desc, eq, inArray, sql } from 'drizzle-orm';
+import { getDb } from './sqlite.js';
+import * as schema from './tasks-schema.js';
+// =============================================================================
+// PIPELINE QUERIES
+// =============================================================================
+/**
+ * Find active pipelines joined with their stages and tasks.
+ * Optionally filters by specific task IDs.
+ *
+ * @param taskIds - Optional list of task IDs to filter by
+ * @param cwd - Working directory for database
+ * @returns Rows with pipeline, stage, and task data
+ */
+export async function findActivePipelinesWithStagesAndTasks(taskIds, cwd) {
+    const db = await getDb(cwd);
+    const conditions = [eq(schema.lifecyclePipelines.status, 'active')];
+    if (taskIds && taskIds.length > 0) {
+        conditions.push(inArray(schema.lifecyclePipelines.taskId, taskIds));
+    }
+    return db
+        .select({
+        pipeline: schema.lifecyclePipelines,
+        stage: schema.lifecycleStages,
+        task: schema.tasks,
+    })
+        .from(schema.lifecyclePipelines)
+        .innerJoin(schema.lifecycleStages, eq(schema.lifecycleStages.pipelineId, schema.lifecyclePipelines.id))
+        .innerJoin(schema.tasks, eq(schema.tasks.id, schema.lifecyclePipelines.taskId))
+        .where(and(...conditions))
+        .orderBy(asc(schema.tasks.priority), desc(schema.lifecyclePipelines.startedAt))
+        .all();
+}
+/**
+ * Find a pipeline with its current stage and task by taskId.
+ * Matches stages where stageName equals the pipeline's currentStageId.
+ *
+ * @param taskId - Task ID to look up
+ * @param cwd - Working directory for database
+ * @returns Matching rows (typically 0 or 1)
+ */
+export async function findPipelineWithCurrentStageAndTask(taskId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select({
+        pipeline: schema.lifecyclePipelines,
+        stage: schema.lifecycleStages,
+        task: schema.tasks,
+    })
+        .from(schema.lifecyclePipelines)
+        .innerJoin(schema.lifecycleStages, eq(schema.lifecycleStages.pipelineId, schema.lifecyclePipelines.id))
+        .innerJoin(schema.tasks, eq(schema.tasks.id, schema.lifecyclePipelines.taskId))
+        .where(and(eq(schema.lifecyclePipelines.taskId, taskId), eq(schema.lifecycleStages.stageName, sql `${schema.lifecyclePipelines.currentStageId}`)))
+        .limit(1)
+        .all();
+}
+/**
+ * Find a pipeline and a specific stage by taskId and stageName.
+ *
+ * @param taskId - Task ID
+ * @param stageName - Stage name to match
+ * @param cwd - Working directory for database
+ * @returns Matching rows (typically 0 or 1)
+ */
+export async function findPipelineWithStage(taskId, stageName, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select({
+        pipeline: schema.lifecyclePipelines,
+        stageRecord: schema.lifecycleStages,
+    })
+        .from(schema.lifecyclePipelines)
+        .innerJoin(schema.lifecycleStages, and(eq(schema.lifecycleStages.pipelineId, schema.lifecyclePipelines.id), eq(schema.lifecycleStages.stageName, stageName)))
+        .where(eq(schema.lifecyclePipelines.taskId, taskId))
+        .limit(1)
+        .all();
+}
+/**
+ * Update pipeline's currentStageId.
+ *
+ * @param pipelineId - Pipeline ID to update
+ * @param currentStageId - New current stage identifier
+ * @param cwd - Working directory for database
+ */
+export async function updatePipelineCurrentStage(pipelineId, currentStageId, cwd) {
+    const db = await getDb(cwd);
+    await db
+        .update(schema.lifecyclePipelines)
+        .set({ currentStageId })
+        .where(eq(schema.lifecyclePipelines.id, pipelineId))
+        .run();
+}
+// =============================================================================
+// STAGE QUERIES
+// =============================================================================
+/**
+ * Get all stages for a pipeline, ordered by sequence.
+ *
+ * @param pipelineId - Pipeline ID
+ * @param cwd - Working directory for database
+ * @returns All stage rows for the pipeline
+ */
+export async function getStagesByPipelineId(pipelineId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select()
+        .from(schema.lifecycleStages)
+        .where(eq(schema.lifecycleStages.pipelineId, pipelineId))
+        .orderBy(asc(schema.lifecycleStages.sequence))
+        .all();
+}
+/**
+ * Update a stage's status to 'in_progress' and clear block fields.
+ *
+ * @param stageId - Stage ID to update
+ * @param startedAt - ISO timestamp for when the stage started
+ * @param cwd - Working directory for database
+ */
+export async function activateStage(stageId, startedAt, cwd) {
+    const db = await getDb(cwd);
+    await db
+        .update(schema.lifecycleStages)
+        .set({
+        status: 'in_progress',
+        startedAt,
+        blockedAt: null,
+        blockReason: null,
+    })
+        .where(eq(schema.lifecycleStages.id, stageId))
+        .run();
+}
+/**
+ * Find pipeline with current stage (no task join) by taskId.
+ * Used by checkBlockedStageDetails.
+ *
+ * @param taskId - Task ID
+ * @param cwd - Working directory for database
+ * @returns Matching rows
+ */
+export async function findPipelineWithCurrentStage(taskId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select({
+        pipeline: schema.lifecyclePipelines,
+        stageRecord: schema.lifecycleStages,
+    })
+        .from(schema.lifecyclePipelines)
+        .innerJoin(schema.lifecycleStages, eq(schema.lifecycleStages.pipelineId, schema.lifecyclePipelines.id))
+        .where(and(eq(schema.lifecyclePipelines.taskId, taskId), eq(schema.lifecycleStages.stageName, sql `${schema.lifecyclePipelines.currentStageId}`)))
+        .limit(1)
+        .all();
+}
+// =============================================================================
+// GATE RESULT QUERIES
+// =============================================================================
+/**
+ * Get gate results for a stage, ordered by checkedAt descending.
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Gate result rows
+ */
+export async function getGateResultsByStageId(stageId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select()
+        .from(schema.lifecycleGateResults)
+        .where(eq(schema.lifecycleGateResults.stageId, stageId))
+        .orderBy(desc(schema.lifecycleGateResults.checkedAt))
+        .all();
+}
+/**
+ * Get gate results for a stage without ordering (for simple checks).
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Gate result rows
+ */
+export async function getGateResultsByStageIdUnordered(stageId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select()
+        .from(schema.lifecycleGateResults)
+        .where(eq(schema.lifecycleGateResults.stageId, stageId))
+        .all();
+}
+// =============================================================================
+// EVIDENCE QUERIES
+// =============================================================================
+/**
+ * Get evidence for a stage, ordered by recordedAt descending.
+ *
+ * @param stageId - Stage ID
+ * @param cwd - Working directory for database
+ * @returns Evidence rows
+ */
+export async function getEvidenceByStageId(stageId, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select()
+        .from(schema.lifecycleEvidence)
+        .where(eq(schema.lifecycleEvidence.stageId, stageId))
+        .orderBy(desc(schema.lifecycleEvidence.recordedAt))
+        .all();
+}
+// =============================================================================
+// TRANSITION QUERIES & MUTATIONS
+// =============================================================================
+/**
+ * Get recent transitions for a pipeline, ordered by createdAt descending.
+ *
+ * @param pipelineId - Pipeline ID
+ * @param limit - Max rows to return (default: 10)
+ * @param cwd - Working directory for database
+ * @returns Transition rows
+ */
+export async function getRecentTransitions(pipelineId, limit = 10, cwd) {
+    const db = await getDb(cwd);
+    return db
+        .select()
+        .from(schema.lifecycleTransitions)
+        .where(eq(schema.lifecycleTransitions.pipelineId, pipelineId))
+        .orderBy(desc(schema.lifecycleTransitions.createdAt))
+        .limit(limit)
+        .all();
+}
+/**
+ * Insert a new transition record.
+ *
+ * @param transition - Transition data to insert
+ * @param cwd - Working directory for database
+ */
+export async function insertTransition(transition, cwd) {
+    const db = await getDb(cwd);
+    await db.insert(schema.lifecycleTransitions).values(transition).run();
+}
+//# sourceMappingURL=lifecycle-store.js.map

package/dist/store/lifecycle-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle-store.js","sourceRoot":"","sources":["../../src/store/lifecycle-store.ts"],"names":[],"mappings":"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"}

package/dist/store/lock.js

@@ -0,0 +1,70 @@
+/**
+ * File locking using proper-lockfile.
+ * Prevents concurrent modifications to CLEO data files.
+ * @epic T4454
+ * @task T4457
+ */
+import { ExitCode } from '@cleocode/contracts';
+import lockfile from 'proper-lockfile';
+import { CleoError } from '../errors.js';
+/** Default lock options. */
+const DEFAULT_LOCK_OPTIONS = {
+    retries: {
+        retries: 3,
+        minTimeout: 100,
+        maxTimeout: 1000,
+        factor: 2,
+    },
+    stale: 10_000,
+    realpath: false,
+};
+/**
+ * Acquire an exclusive lock on a file.
+ * Returns a release function that must be called when done.
+ */
+export async function acquireLock(filePath, options) {
+    try {
+        const release = await lockfile.lock(filePath, {
+            ...DEFAULT_LOCK_OPTIONS,
+            ...(options?.stale !== undefined && { stale: options.stale }),
+            ...(options?.retries !== undefined && {
+                retries: {
+                    ...DEFAULT_LOCK_OPTIONS.retries,
+                    retries: options.retries,
+                },
+            }),
+        });
+        return release;
+    }
+    catch (err) {
+        throw new CleoError(ExitCode.LOCK_TIMEOUT, `Failed to acquire lock: ${filePath}`, {
+            fix: `Another process may be writing to this file. Wait and retry.`,
+            cause: err,
+        });
+    }
+}
+/**
+ * Check if a file is currently locked.
+ */
+export async function isLocked(filePath) {
+    try {
+        return await lockfile.check(filePath, { realpath: false });
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Execute a function while holding an exclusive lock on a file.
+ * The lock is automatically released when the function completes (or throws).
+ */
+export async function withLock(filePath, fn, options) {
+    const release = await acquireLock(filePath, options);
+    try {
+        return await fn();
+    }
+    finally {
+        await release();
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/store/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../src/store/lock.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,QAAQ,MAAM,iBAAiB,CAAC;AACvC,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzC,4BAA4B;AAC5B,MAAM,oBAAoB,GAAG;IAC3B,OAAO,EAAE;QACP,OAAO,EAAE,CAAC;QACV,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,IAAI;QAChB,MAAM,EAAE,CAAC;KACV;IACD,KAAK,EAAE,MAAM;IACb,QAAQ,EAAE,KAAK;CAChB,CAAC;AAKF;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,QAAgB,EAChB,OAA8C;IAE9C,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,QAAQ,EAAE;YAC5C,GAAG,oBAAoB;YACvB,GAAG,CAAC,OAAO,EAAE,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;YAC7D,GAAG,CAAC,OAAO,EAAE,OAAO,KAAK,SAAS,IAAI;gBACpC,OAAO,EAAE;oBACP,GAAG,oBAAoB,CAAC,OAAO;oBAC/B,OAAO,EAAE,OAAO,CAAC,OAAO;iBACzB;aACF,CAAC;SACH,CAAC,CAAC;QACH,OAAO,OAAO,CAAC;IACjB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,2BAA2B,QAAQ,EAAE,EAAE;YAChF,GAAG,EAAE,8DAA8D;YACnE,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;IACL,CAAC;AACH,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,QAAgB;IAC7C,IAAI,CAAC;QACH,OAAO,MAAM,QAAQ,CAAC,KAAK,CAAC,QAAQ,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAC;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAC5B,QAAgB,EAChB,EAAoB,EACpB,OAA8C;IAE9C,MAAM,OAAO,GAAG,MAAM,WAAW,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,MAAM,EAAE,EAAE,CAAC;IACpB,CAAC;YAAS,CAAC;QACT,MAAM,OAAO,EAAE,CAAC;IAClB,CAAC;AACH,CAAC"}

package/dist/store/migrate-signaldock-to-conduit.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Automatic first-run migration executor: project-tier signaldock.db → conduit.db.
+ *
+ * Implements ADR-037 §8 — on the first cleo invocation after upgrading to
+ * v2026.4.12, if a project-tier `.cleo/signaldock.db` exists and
+ * `.cleo/conduit.db` does not, this module migrates all project-local data to
+ * conduit.db and copies global-identity rows to the global-tier signaldock.db.
+ *
+ * Key properties:
+ *   - Idempotent: `needsSignaldockToConduitMigration` returns false once conduit.db exists.
+ *   - Atomic per file: transactions are used for conduit.db and global signaldock.db writes.
+ *   - Non-destructive: legacy signaldock.db is renamed to `.pre-t310.bak`, not deleted.
+ *   - Multi-project safe: `INSERT OR IGNORE` prevents duplicate global rows when multiple
+ *     projects migrate the same agent.
+ *   - Migrated agents flagged `requires_reauth=1` (new KDF scheme, ADR-037 §5).
+ *
+ * @task T358
+ * @epic T310
+ * @why ADR-037 §8 — automatic first-run migration from the pre-T310 project-tier
+ *      signaldock.db to the new T310 topology (conduit.db + global signaldock.db
+ *      + global-salt). Runs once per project on first cleo invocation after upgrade.
+ */
+/**
+ * Result returned by `migrateSignaldockToConduit`.
+ *
+ * @task T358
+ * @epic T310
+ */
+export interface MigrationResult {
+    /** `migrated` = migration ran and succeeded; `no-op` = not needed; `failed` = error occurred. */
+    status: 'migrated' | 'no-op' | 'failed';
+    /** Absolute path to the project root that was migrated. */
+    projectRoot: string;
+    /** Number of agents copied to global signaldock.db. */
+    agentsCopied: number;
+    /** Absolute path to the conduit.db that was created. */
+    conduitPath: string;
+    /** Absolute path to the global signaldock.db. */
+    globalSignaldockPath: string;
+    /** Absolute path to the legacy `.pre-t310.bak` file, or null if rename did not complete. */
+    bakPath: string | null;
+    /** Errors encountered during migration steps. Never thrown — always captured here. */
+    errors: Array<{
+        step: string;
+        error: string;
+    }>;
+}
+/**
+ * Returns true when the legacy migration is needed for the given project.
+ *
+ * Detection heuristic (ADR-037 §8):
+ *   - `.cleo/signaldock.db` EXISTS AND `.cleo/conduit.db` DOES NOT EXIST
+ *
+ * Idempotent: returns false once conduit.db is present, regardless of .bak state.
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns True if migration is needed; false otherwise.
+ *
+ * @task T358
+ * @epic T310
+ */
+export declare function needsSignaldockToConduitMigration(projectRoot: string): boolean;
+/**
+ * Runs the signaldock.db → conduit.db migration for the given project.
+ *
+ * The migration is atomic per file (SQLite transactions for DB writes, atomic
+ * rename for the backup step). Failures are captured in `result.errors` and
+ * the function never throws — callers receive a `MigrationResult` with
+ * `status: 'failed'` on error.
+ *
+ * Safe to call when no migration is needed (returns `{status: 'no-op', ...}`).
+ * Safe to call on a partially-migrated install (idempotent via needsMigration check).
+ *
+ * @param projectRoot - Absolute path to the project root directory.
+ * @returns A `MigrationResult` describing what was done and any errors encountered.
+ *
+ * @task T358
+ * @epic T310
+ */
+export declare function migrateSignaldockToConduit(projectRoot: string): MigrationResult;
+//# sourceMappingURL=migrate-signaldock-to-conduit.d.ts.map

package/dist/store/migrate-signaldock-to-conduit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-signaldock-to-conduit.d.ts","sourceRoot":"","sources":["../../src/store/migrate-signaldock-to-conduit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsBH;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,MAAM,EAAE,UAAU,GAAG,OAAO,GAAG,QAAQ,CAAC;IACxC,2DAA2D;IAC3D,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,WAAW,EAAE,MAAM,CAAC;IACpB,iDAAiD;IACjD,oBAAoB,EAAE,MAAM,CAAC;IAC7B,4FAA4F;IAC5F,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sFAAsF;IACtF,MAAM,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAwCD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iCAAiC,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI9E;AA8GD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CAAC,WAAW,EAAE,MAAM,GAAG,eAAe,CAma/E"}