canopycms 0.0.0

package/dist/settings-workspace.js

@@ -0,0 +1,137 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { GitManager } from './git-manager';
+import { createDebugLogger } from './utils/debug';
+import { isFileExistsError } from './utils/error';
+const log = createDebugLogger({ prefix: 'SettingsWorkspace' });
+// In-memory lock to prevent concurrent workspace initialization within the same process.
+// Settings only need one lock (not per-branch like content branches).
+let settingsInitLock = null;
+// Stale lock threshold — init should complete well within this window
+const LOCK_STALE_MS = 30_000;
+/**
+ * Acquire a file-based lock for cross-process synchronization.
+ * Uses O_CREAT|O_EXCL (wx flag) for atomic file creation.
+ * Stale locks (older than LOCK_STALE_MS) are cleaned up automatically.
+ *
+ * Returns true if lock was acquired, false if another process holds it.
+ */
+async function acquireFileLock(lockPath) {
+    const lockContent = JSON.stringify({
+        pid: process.pid,
+        timestamp: new Date().toISOString(),
+    });
+    await fs.mkdir(path.dirname(lockPath), { recursive: true });
+    try {
+        const handle = await fs.open(lockPath, 'wx');
+        await handle.writeFile(lockContent, 'utf-8');
+        await handle.close();
+        return true;
+    }
+    catch (err) {
+        if (!isFileExistsError(err))
+            throw err;
+    }
+    // Lock file exists — check if stale
+    try {
+        const stat = await fs.stat(lockPath);
+        const ageMs = Date.now() - stat.mtimeMs;
+        if (ageMs < LOCK_STALE_MS) {
+            // Lock is fresh — another process is initializing
+            return false;
+        }
+        // Stale lock — another process likely crashed during init
+        log.debug('workspace', 'Removing stale settings init lock', { ageMs });
+        await fs.unlink(lockPath).catch(() => { });
+    }
+    catch {
+        // Lock file vanished between check and stat — try again
+    }
+    // Retry lock acquisition after stale cleanup
+    try {
+        const handle = await fs.open(lockPath, 'wx');
+        await handle.writeFile(lockContent, 'utf-8');
+        await handle.close();
+        return true;
+    }
+    catch (retryErr) {
+        if (isFileExistsError(retryErr))
+            return false;
+        throw retryErr;
+    }
+}
+async function releaseFileLock(lockPath) {
+    await fs.unlink(lockPath).catch(() => { });
+}
+/**
+ * Manages settings filesystem workspace and git operations.
+ *
+ * Settings are stored separately from content branches:
+ * - prod/prod-sim: Orphan git branches (no shared history with content)
+ * - dev: Regular directory (no git)
+ *
+ * Unlike BranchWorkspaceManager, this does not:
+ * - Create or manage metadata files
+ * - Interact with the branch registry
+ * - Check for special cases (settings are always settings)
+ *
+ * Uses two layers of locking:
+ * - In-memory Promise lock for within-process serialization (Lambda request lifecycle)
+ * - File-based lock for cross-process synchronization (multiple Lambda instances on EFS)
+ */
+export class SettingsWorkspaceManager {
+    constructor(config) {
+        this.config = config;
+    }
+    async ensureGitWorkspace(options) {
+        return log.timed('workspace', 'ensureGitWorkspace', async () => {
+            // Layer 1: In-memory lock (prevents redundant async calls within same process)
+            if (settingsInitLock) {
+                await settingsInitLock;
+                return;
+            }
+            // Create new in-memory lock promise
+            settingsInitLock = (async () => {
+                try {
+                    log.debug('workspace', 'Ensuring settings git workspace', {
+                        branchName: options.branchName,
+                        mode: options.mode,
+                    });
+                    // Layer 2: File-based lock (prevents concurrent init across processes)
+                    // Lock file is placed OUTSIDE the settings root (as a sibling) so that
+                    // acquireFileLock's mkdir does not pre-create the settings directory,
+                    // which would cause git clone to fail ("already exists and is not empty").
+                    const lockPath = path.join(path.dirname(options.settingsRoot), '.settings-init.lock');
+                    const acquired = await acquireFileLock(lockPath);
+                    try {
+                        // GitManager.initializeWorkspace is idempotent (checks for .git),
+                        // so it's safe to call even if another process just finished init.
+                        await GitManager.initializeWorkspace({
+                            workspacePath: options.settingsRoot,
+                            branchName: options.branchName,
+                            mode: options.mode,
+                            baseBranch: this.config.defaultBaseBranch,
+                            sourceRoot: this.config.sourceRoot,
+                            defaultRemoteUrl: this.config.defaultRemoteUrl,
+                            remoteUrl: options.remoteUrl,
+                            remoteName: this.config.defaultRemoteName,
+                            branchType: 'orphan', // Key difference: orphan branch for settings
+                        });
+                    }
+                    finally {
+                        if (acquired) {
+                            await releaseFileLock(lockPath);
+                        }
+                    }
+                }
+                finally {
+                    // Always clean up the in-memory lock when done (success or failure)
+                    settingsInitLock = null;
+                }
+            })();
+            // Wait for initialization to complete
+            await settingsInitLock;
+        });
+    }
+}
+//# sourceMappingURL=settings-workspace.js.map

package/dist/settings-workspace.js.map

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

package/dist/task-queue/index.d.ts

@@ -0,0 +1,3 @@
+export type { Task, TaskStatus, QueueStats, TaskQueueLogger } from './types';
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, } from './task-queue';
+//# sourceMappingURL=index.d.ts.map

package/dist/task-queue/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/task-queue/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE5E,OAAO,EACL,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,oBAAoB,EACpB,eAAe,EACf,OAAO,EACP,SAAS,EACT,aAAa,GACd,MAAM,cAAc,CAAA"}

package/dist/task-queue/index.js

@@ -0,0 +1,2 @@
+export { enqueueTask, dequeueTask, completeTask, failTask, retryTask, recoverOrphanedTasks, cleanupOldTasks, getTask, listTasks, getQueueStats, } from './task-queue';
+//# sourceMappingURL=index.js.map

package/dist/task-queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/task-queue/index.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,WAAW,EACX,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,oBAAoB,EACpB,eAAe,EACf,OAAO,EACP,SAAS,EACT,aAAa,GACd,MAAM,cAAc,CAAA"}

package/dist/task-queue/task-queue.d.ts

@@ -0,0 +1,81 @@
+/**
+ * File-based persistent task queue.
+ *
+ * Tasks are JSON files organized in subdirectories by status:
+ *   pending/      — ready to be picked up
+ *   processing/   — currently being executed
+ *   completed/    — finished successfully
+ *   failed/       — permanently failed (exhausted retries)
+ *   corrupt/      — unreadable files moved here for inspection
+ *
+ * Designed for shared filesystems (EFS/NFS) where one process enqueues
+ * and another dequeues. No external dependencies — only Node.js stdlib.
+ *
+ * IMPORTANT: Single-consumer only. The dequeue operation is not atomic across
+ * processes — the worker lock (acquireLock) ensures only one consumer runs at
+ * a time. Do not run multiple dequeue consumers concurrently.
+ */
+import type { Task, TaskStatus, QueueStats, TaskQueueLogger } from './types';
+/**
+ * Enqueue a task. Writes a JSON file to pending/{id}.json.
+ * Returns the generated task ID.
+ */
+export declare function enqueueTask(taskDir: string, task: {
+    action: string;
+    payload: Record<string, unknown>;
+    maxRetries?: number;
+}, logger?: TaskQueueLogger): Promise<string>;
+/**
+ * Dequeue the next pending task (oldest first).
+ * Moves the task file from pending/ to processing/.
+ * Returns null if no tasks are ready.
+ *
+ * - Skips tasks whose `retryAfter` is in the future.
+ * - Moves corrupt JSON files to corrupt/.
+ * - Skips tasks that already exist in completed/ or failed/ (crash dedup).
+ */
+export declare function dequeueTask(taskDir: string, logger?: TaskQueueLogger): Promise<Task | null>;
+/**
+ * Mark a task as completed. Moves from processing/ to completed/.
+ */
+export declare function completeTask(taskDir: string, taskId: string, result: Record<string, unknown>, logger?: TaskQueueLogger): Promise<void>;
+/**
+ * Mark a task as permanently failed. Moves from processing/ to failed/.
+ */
+export declare function failTask(taskDir: string, taskId: string, error: string, logger?: TaskQueueLogger): Promise<void>;
+/**
+ * Retry a task with exponential backoff.
+ * Moves from processing/ back to pending/ with incremented retryCount
+ * and a retryAfter timestamp. Backoff: 5s → 10s → 20s → 40s → 60s cap.
+ */
+export declare function retryTask(taskDir: string, taskId: string, error: string, logger?: TaskQueueLogger): Promise<void>;
+/**
+ * Recover orphaned tasks stuck in processing/.
+ * Moves tasks whose file mtime is older than maxAgeMs back to pending/.
+ * Call on worker startup to handle crash recovery.
+ *
+ * Skips tasks that already exist in completed/ or failed/ — these are
+ * leftovers from a crash between writing the result and unlinking the
+ * processing copy.
+ */
+export declare function recoverOrphanedTasks(taskDir: string, maxAgeMs?: number, logger?: TaskQueueLogger): Promise<number>;
+/**
+ * Delete old task files from completed/ and failed/.
+ * Default retention: 30 days.
+ */
+export declare function cleanupOldTasks(taskDir: string, maxAgeMs?: number, logger?: TaskQueueLogger): Promise<number>;
+/**
+ * Get a specific task by ID. Searches all status directories.
+ */
+export declare function getTask(taskDir: string, taskId: string): Promise<Task | null>;
+/**
+ * List tasks in a specific status directory.
+ * Returns tasks sorted by createdAt (oldest first).
+ * Use `limit` to cap the number of results.
+ */
+export declare function listTasks(taskDir: string, status: TaskStatus | 'corrupt', limit?: number): Promise<Task[]>;
+/**
+ * Get counts of tasks in each status directory.
+ */
+export declare function getQueueStats(taskDir: string): Promise<QueueStats>;
+//# sourceMappingURL=task-queue.d.ts.map

package/dist/task-queue/task-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task-queue.d.ts","sourceRoot":"","sources":["../../src/task-queue/task-queue.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,IAAI,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAiB5E;;;GAGG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAChC,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,EACD,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,MAAM,CAAC,CAmBjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAkEtB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAChC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,IAAI,CAAC,CAgCf;AAMD;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,MAAM,EACf,QAAQ,SAAa,EACrB,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,MAAM,CAAC,CAyDjB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,QAAQ,SAAwB,EAChC,MAAM,GAAE,eAA4B,GACnC,OAAO,CAAC,MAAM,CAAC,CA+BjB;AAMD;;GAEG;AACH,wBAAsB,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAWnF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAC7B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,UAAU,GAAG,SAAS,EAC9B,KAAK,SAAM,GACV,OAAO,CAAC,IAAI,EAAE,CAAC,CAuBjB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoBxE"}

package/dist/task-queue/task-queue.js

@@ -0,0 +1,434 @@
+/**
+ * File-based persistent task queue.
+ *
+ * Tasks are JSON files organized in subdirectories by status:
+ *   pending/      — ready to be picked up
+ *   processing/   — currently being executed
+ *   completed/    — finished successfully
+ *   failed/       — permanently failed (exhausted retries)
+ *   corrupt/      — unreadable files moved here for inspection
+ *
+ * Designed for shared filesystems (EFS/NFS) where one process enqueues
+ * and another dequeues. No external dependencies — only Node.js stdlib.
+ *
+ * IMPORTANT: Single-consumer only. The dequeue operation is not atomic across
+ * processes — the worker lock (acquireLock) ensures only one consumer runs at
+ * a time. Do not run multiple dequeue consumers concurrently.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+const DEFAULT_MAX_RETRIES = 3;
+// Silent no-op logger
+const nullLogger = { debug: () => { } };
+// Intentionally local — the task-queue module has zero Canopy dependencies
+// to support eventual extraction as a standalone package.
+function isNotFoundError(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ENOENT';
+}
+// ============================================================================
+// Core queue operations
+// ============================================================================
+/**
+ * Enqueue a task. Writes a JSON file to pending/{id}.json.
+ * Returns the generated task ID.
+ */
+export async function enqueueTask(taskDir, task, logger = nullLogger) {
+    const id = crypto.randomUUID();
+    const pendingDir = path.join(taskDir, 'pending');
+    await fs.mkdir(pendingDir, { recursive: true });
+    const queuedTask = {
+        id,
+        action: task.action,
+        payload: task.payload,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        retryCount: 0,
+        maxRetries: task.maxRetries ?? DEFAULT_MAX_RETRIES,
+    };
+    const filePath = path.join(pendingDir, `${id}.json`);
+    await fs.writeFile(filePath, JSON.stringify(queuedTask, null, 2), 'utf-8');
+    logger.debug('Enqueued task', { id, action: task.action });
+    return id;
+}
+/**
+ * Dequeue the next pending task (oldest first).
+ * Moves the task file from pending/ to processing/.
+ * Returns null if no tasks are ready.
+ *
+ * - Skips tasks whose `retryAfter` is in the future.
+ * - Moves corrupt JSON files to corrupt/.
+ * - Skips tasks that already exist in completed/ or failed/ (crash dedup).
+ */
+export async function dequeueTask(taskDir, logger = nullLogger) {
+    const pendingDir = path.join(taskDir, 'pending');
+    const processingDir = path.join(taskDir, 'processing');
+    let files;
+    try {
+        files = await fs.readdir(pendingDir);
+    }
+    catch {
+        return null;
+    }
+    const jsonFiles = files.filter((f) => f.endsWith('.json'));
+    if (jsonFiles.length === 0)
+        return null;
+    const now = Date.now();
+    const tasks = [];
+    for (const fileName of jsonFiles) {
+        try {
+            const content = await fs.readFile(path.join(pendingDir, fileName), 'utf-8');
+            const task = parseTaskJson(content);
+            if (!task) {
+                await moveToCorrupt(taskDir, pendingDir, fileName, 'Invalid JSON', logger);
+                continue;
+            }
+            if (task.retryAfter && new Date(task.retryAfter).getTime() > now) {
+                continue;
+            }
+            tasks.push({ fileName, task });
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                continue;
+            throw err;
+        }
+    }
+    if (tasks.length === 0)
+        return null;
+    // FIFO with stable tiebreaker (task ID) to prevent indeterminate order
+    // when tasks share the same millisecond timestamp
+    tasks.sort((a, b) => a.task.createdAt.localeCompare(b.task.createdAt) || a.task.id.localeCompare(b.task.id));
+    const { fileName, task } = tasks[0];
+    // Dedup: if this task already finished (crash between write-result and unlink-processing),
+    // just clean up the stale pending copy
+    if (await taskExistsIn(taskDir, task.id, ['completed', 'failed'])) {
+        await fs.unlink(path.join(pendingDir, fileName)).catch(() => { });
+        logger.debug('Skipped already-finished task', { id: task.id });
+        return null;
+    }
+    const sourcePath = path.join(pendingDir, fileName);
+    const destPath = path.join(processingDir, fileName);
+    try {
+        task.status = 'processing';
+        await fs.mkdir(processingDir, { recursive: true });
+        await fs.writeFile(destPath, JSON.stringify(task, null, 2), 'utf-8');
+        await fs.unlink(sourcePath);
+        logger.debug('Dequeued task', { id: task.id, action: task.action });
+        return task;
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return null;
+        throw err;
+    }
+}
+/**
+ * Mark a task as completed. Moves from processing/ to completed/.
+ */
+export async function completeTask(taskDir, taskId, result, logger = nullLogger) {
+    const processingPath = path.join(taskDir, 'processing', `${taskId}.json`);
+    const completedDir = path.join(taskDir, 'completed');
+    const completedPath = path.join(completedDir, `${taskId}.json`);
+    let task;
+    try {
+        const content = await fs.readFile(processingPath, 'utf-8');
+        const parsed = parseTaskJson(content);
+        if (!parsed) {
+            logger.debug('Corrupt task file in processing, removing', { id: taskId });
+            await fs.unlink(processingPath).catch(() => { });
+            return;
+        }
+        task = parsed;
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return;
+        throw err;
+    }
+    task.status = 'completed';
+    task.completedAt = new Date().toISOString();
+    task.result = result;
+    await fs.mkdir(completedDir, { recursive: true });
+    await fs.writeFile(completedPath, JSON.stringify(task, null, 2), 'utf-8');
+    await fs.unlink(processingPath).catch(() => { });
+    logger.debug('Completed task', { id: taskId });
+}
+/**
+ * Mark a task as permanently failed. Moves from processing/ to failed/.
+ */
+export async function failTask(taskDir, taskId, error, logger = nullLogger) {
+    const processingPath = path.join(taskDir, 'processing', `${taskId}.json`);
+    const failedDir = path.join(taskDir, 'failed');
+    const failedPath = path.join(failedDir, `${taskId}.json`);
+    let task;
+    try {
+        const content = await fs.readFile(processingPath, 'utf-8');
+        const parsed = parseTaskJson(content);
+        if (!parsed) {
+            logger.debug('Corrupt task file in processing, removing', { id: taskId });
+            await fs.unlink(processingPath).catch(() => { });
+            return;
+        }
+        task = parsed;
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return;
+        throw err;
+    }
+    task.status = 'failed';
+    task.completedAt = new Date().toISOString();
+    task.error = error;
+    await fs.mkdir(failedDir, { recursive: true });
+    await fs.writeFile(failedPath, JSON.stringify(task, null, 2), 'utf-8');
+    await fs.unlink(processingPath).catch(() => { });
+    logger.debug('Failed task', { id: taskId, error });
+}
+/**
+ * Retry a task with exponential backoff.
+ * Moves from processing/ back to pending/ with incremented retryCount
+ * and a retryAfter timestamp. Backoff: 5s → 10s → 20s → 40s → 60s cap.
+ */
+export async function retryTask(taskDir, taskId, error, logger = nullLogger) {
+    const processingPath = path.join(taskDir, 'processing', `${taskId}.json`);
+    const pendingDir = path.join(taskDir, 'pending');
+    const pendingPath = path.join(pendingDir, `${taskId}.json`);
+    let task;
+    try {
+        const content = await fs.readFile(processingPath, 'utf-8');
+        const parsed = parseTaskJson(content);
+        if (!parsed) {
+            logger.debug('Corrupt task file in processing, removing', { id: taskId });
+            await fs.unlink(processingPath).catch(() => { });
+            return;
+        }
+        task = parsed;
+    }
+    catch (err) {
+        if (isNotFoundError(err))
+            return;
+        throw err;
+    }
+    const retryCount = (task.retryCount ?? 0) + 1;
+    const backoffMs = Math.min(5000 * Math.pow(2, retryCount - 1), 60_000);
+    task.status = 'pending';
+    task.retryCount = retryCount;
+    task.retryAfter = new Date(Date.now() + backoffMs).toISOString();
+    task.error = error;
+    await fs.mkdir(pendingDir, { recursive: true });
+    await fs.writeFile(pendingPath, JSON.stringify(task, null, 2), 'utf-8');
+    await fs.unlink(processingPath).catch(() => { });
+    logger.debug('Retrying task', { id: taskId, retryCount, backoffMs });
+}
+// ============================================================================
+// Recovery & maintenance
+// ============================================================================
+/**
+ * Recover orphaned tasks stuck in processing/.
+ * Moves tasks whose file mtime is older than maxAgeMs back to pending/.
+ * Call on worker startup to handle crash recovery.
+ *
+ * Skips tasks that already exist in completed/ or failed/ — these are
+ * leftovers from a crash between writing the result and unlinking the
+ * processing copy.
+ */
+export async function recoverOrphanedTasks(taskDir, maxAgeMs = 5 * 60_000, logger = nullLogger) {
+    const processingDir = path.join(taskDir, 'processing');
+    const pendingDir = path.join(taskDir, 'pending');
+    let files;
+    try {
+        files = await fs.readdir(processingDir);
+    }
+    catch {
+        return 0;
+    }
+    const now = Date.now();
+    let recovered = 0;
+    for (const fileName of files.filter((f) => f.endsWith('.json'))) {
+        const filePath = path.join(processingDir, fileName);
+        try {
+            const stat = await fs.stat(filePath);
+            if (now - stat.mtimeMs >= maxAgeMs) {
+                const content = await fs.readFile(filePath, 'utf-8');
+                const task = parseTaskJson(content);
+                if (!task) {
+                    await moveToCorrupt(taskDir, processingDir, fileName, 'Invalid JSON during recovery', logger);
+                    continue;
+                }
+                if (await taskExistsIn(taskDir, task.id, ['completed', 'failed'])) {
+                    await fs.unlink(filePath).catch(() => { });
+                    logger.debug('Cleaned up orphaned task (already finished)', {
+                        id: task.id,
+                    });
+                    continue;
+                }
+                task.status = 'pending';
+                await fs.mkdir(pendingDir, { recursive: true });
+                await fs.writeFile(path.join(pendingDir, fileName), JSON.stringify(task, null, 2), 'utf-8');
+                await fs.unlink(filePath);
+                logger.debug('Recovered orphaned task', {
+                    id: task.id,
+                    action: task.action,
+                });
+                recovered++;
+            }
+        }
+        catch (err) {
+            if (isNotFoundError(err))
+                continue;
+            logger.debug('Failed to recover task', { fileName });
+        }
+    }
+    return recovered;
+}
+/**
+ * Delete old task files from completed/ and failed/.
+ * Default retention: 30 days.
+ */
+export async function cleanupOldTasks(taskDir, maxAgeMs = 30 * 24 * 60 * 60_000, logger = nullLogger) {
+    const now = Date.now();
+    let cleaned = 0;
+    for (const subdir of ['completed', 'failed']) {
+        const dir = path.join(taskDir, subdir);
+        let files;
+        try {
+            files = await fs.readdir(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const fileName of files.filter((f) => f.endsWith('.json'))) {
+            try {
+                const filePath = path.join(dir, fileName);
+                const stat = await fs.stat(filePath);
+                if (now - stat.mtimeMs >= maxAgeMs) {
+                    await fs.unlink(filePath);
+                    cleaned++;
+                }
+            }
+            catch {
+                // File already gone or unreadable
+            }
+        }
+    }
+    if (cleaned > 0) {
+        logger.debug('Cleaned up old tasks', { cleaned });
+    }
+    return cleaned;
+}
+// ============================================================================
+// Query operations (for status UIs, monitoring)
+// ============================================================================
+/**
+ * Get a specific task by ID. Searches all status directories.
+ */
+export async function getTask(taskDir, taskId) {
+    for (const subdir of ['completed', 'failed', 'processing', 'pending']) {
+        const filePath = path.join(taskDir, subdir, `${taskId}.json`);
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            return parseTaskJson(content);
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * List tasks in a specific status directory.
+ * Returns tasks sorted by createdAt (oldest first).
+ * Use `limit` to cap the number of results.
+ */
+export async function listTasks(taskDir, status, limit = 100) {
+    const dir = path.join(taskDir, status);
+    let files;
+    try {
+        files = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const tasks = [];
+    for (const fileName of files.filter((f) => f.endsWith('.json'))) {
+        if (tasks.length >= limit)
+            break;
+        try {
+            const content = await fs.readFile(path.join(dir, fileName), 'utf-8');
+            const task = parseTaskJson(content);
+            if (task)
+                tasks.push(task);
+        }
+        catch {
+            continue;
+        }
+    }
+    tasks.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    return tasks;
+}
+/**
+ * Get counts of tasks in each status directory.
+ */
+export async function getQueueStats(taskDir) {
+    const stats = {
+        pending: 0,
+        processing: 0,
+        completed: 0,
+        failed: 0,
+        corrupt: 0,
+    };
+    for (const status of ['pending', 'processing', 'completed', 'failed', 'corrupt']) {
+        const dir = path.join(taskDir, status);
+        try {
+            const files = await fs.readdir(dir);
+            stats[status] = files.filter((f) => f.endsWith('.json')).length;
+        }
+        catch {
+            // Directory doesn't exist — count stays 0
+        }
+    }
+    return stats;
+}
+// ============================================================================
+// Internal helpers
+// ============================================================================
+/** Parse JSON into a Task, returning null if invalid. */
+function parseTaskJson(content) {
+    try {
+        const parsed = JSON.parse(content);
+        if (typeof parsed.id !== 'string' || typeof parsed.action !== 'string') {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Check if a task file exists in any of the specified subdirectories. */
+async function taskExistsIn(taskDir, taskId, subdirs) {
+    for (const subdir of subdirs) {
+        try {
+            await fs.stat(path.join(taskDir, subdir, `${taskId}.json`));
+            return true;
+        }
+        catch {
+            // Not in this subdir
+        }
+    }
+    return false;
+}
+/** Move a corrupt file to corrupt/ for inspection. */
+async function moveToCorrupt(taskDir, sourceDir, fileName, reason, logger) {
+    const corruptDir = path.join(taskDir, 'corrupt');
+    try {
+        await fs.mkdir(corruptDir, { recursive: true });
+        await fs.rename(path.join(sourceDir, fileName), path.join(corruptDir, fileName));
+        logger.debug('Moved corrupt task file', { fileName, reason });
+    }
+    catch {
+        await fs.unlink(path.join(sourceDir, fileName)).catch(() => { });
+    }
+}
+//# sourceMappingURL=task-queue.js.map