watchfix 0.1.0

package/dist/fixer/index.js

@@ -0,0 +1,398 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import yaml from 'yaml';
+import { createAgent } from '../agents/index.js';
+import { getError, logActivity } from '../db/queries.js';
+import { UserError } from '../utils/errors.js';
+import { parseDuration } from '../utils/duration.js';
+import { Logger } from '../utils/logger.js';
+import { generateAnalyzeContext, generateFixContext } from './context.js';
+import { parseAnalysisOutput, parseFixOutput } from './output.js';
+import { runVerification } from './verifier.js';
+import { acquireLock, generateLockId, releaseLock, transitionStatus } from './lock.js';
+const FIXABLE_STATUSES = new Set(['pending', 'suggested']);
+const outputPathForContext = (contextPath) => {
+    if (contextPath.endsWith('-analyze.md')) {
+        return contextPath.replace(/-analyze\.md$/, '-analysis.yaml');
+    }
+    if (contextPath.endsWith('-fix.md')) {
+        return contextPath.replace(/-fix\.md$/, '-result.yaml');
+    }
+    return null;
+};
+const formatAgentDiagnostic = (result, expectedOutput) => {
+    const lines = [
+        `Agent did not produce valid output for ${expectedOutput}`,
+        typeof result.exitCode === 'number' ? `Exit code: ${result.exitCode}` : '',
+        result.timedOut ? 'Agent timed out' : '',
+        result.stdout.trim() ? `stdout:\n${result.stdout.trim()}` : '',
+        result.stderr.trim() ? `stderr:\n${result.stderr.trim()}` : '',
+    ];
+    return lines.filter(Boolean).join('\n');
+};
+const formatParseDiagnostic = (error, rawContent) => {
+    const message = error instanceof Error ? error.message : `Unknown error: ${String(error)}`;
+    return `Failed to parse output: ${message}\nRaw content:\n${rawContent}`;
+};
+const analysisToYaml = (analysis) => yaml.stringify(analysis).trimEnd();
+const parseSuggestion = (value) => {
+    const parsed = JSON.parse(value);
+    if (!parsed ||
+        typeof parsed.summary !== 'string' ||
+        typeof parsed.root_cause !== 'string' ||
+        typeof parsed.suggested_fix !== 'string' ||
+        !Array.isArray(parsed.files_to_modify) ||
+        typeof parsed.confidence !== 'string') {
+        throw new UserError('Stored analysis output is invalid');
+    }
+    return parsed;
+};
+export class FixOrchestrator {
+    db;
+    config;
+    logger;
+    agent;
+    terminalEnabled;
+    constructor(db, config, options) {
+        this.db = db;
+        this.config = config;
+        this.terminalEnabled = options?.terminalEnabled ?? true;
+        this.logger =
+            options?.logger ??
+                new Logger({
+                    rootDir: config.project.root,
+                    terminalEnabled: this.terminalEnabled,
+                });
+        this.agent =
+            options?.agent ??
+                createAgent({
+                    provider: config.agent.provider,
+                    command: config.agent.command,
+                    args: config.agent.args,
+                    stderrIsProgress: config.agent.stderr_is_progress,
+                    timeout: parseDuration(config.agent.timeout),
+                    retries: config.agent.retries,
+                }, {
+                    projectRoot: config.project.root,
+                    logger: this.logger,
+                    terminalEnabled: this.terminalEnabled,
+                });
+    }
+    async fixError(errorId, options) {
+        const initial = getError(this.db, errorId);
+        if (!initial) {
+            throw new UserError(`Error ${errorId} not found`);
+        }
+        const lockId = generateLockId();
+        const lockAcquired = await acquireLock(this.db, errorId, lockId);
+        if (!lockAcquired) {
+            return {
+                errorId,
+                status: initial.status,
+                lockAcquired: false,
+                attempts: initial.fixAttempts,
+                message: 'Lock already held',
+            };
+        }
+        this.logger.info(`Starting fix orchestrator for error ${errorId}`);
+        let lockHeld = true;
+        let attempts = initial.fixAttempts;
+        let analysisOutput;
+        let fixOutput;
+        let verificationResult;
+        try {
+            const error = getError(this.db, errorId);
+            if (!error) {
+                throw new UserError(`Error ${errorId} not found after locking`);
+            }
+            if (!FIXABLE_STATUSES.has(error.status)) {
+                await releaseLock(this.db, errorId, lockId);
+                lockHeld = false;
+                throw new UserError(`Error ${errorId} is not in a fixable state (status=${error.status})`);
+            }
+            const analyzeOnly = options?.analyzeOnly ?? false;
+            const reanalyze = options?.reanalyze ?? false;
+            const maxAttempts = this.config.limits.max_attempts_per_error;
+            const existingSuggestion = error.suggestion;
+            const shouldReanalyze = reanalyze && error.status === 'suggested' && existingSuggestion;
+            const suggestionMissing = error.status === 'suggested' && !existingSuggestion;
+            const needsAnalysis = error.status === 'pending' || reanalyze || suggestionMissing;
+            if (needsAnalysis) {
+                const expectedStatuses = [];
+                if (error.status === 'pending') {
+                    expectedStatuses.push('pending');
+                }
+                if (error.status === 'suggested') {
+                    expectedStatuses.push('suggested');
+                }
+                if (expectedStatuses.length === 0 ||
+                    !transitionStatus(this.db, errorId, expectedStatuses, 'analyzing', lockId)) {
+                    throw new UserError(`Failed to transition error ${errorId} into analyzing status`);
+                }
+                logActivity(this.db, 'analysis_start', errorId, JSON.stringify({ attempt: attempts, lockId }));
+                this.logger.info(`Analyzing error ${errorId} (attempt ${attempts})...`);
+                const context = generateAnalyzeContext(error, this.config, attempts);
+                const contextPath = path.resolve(this.config.project.root, context.path);
+                await fs.mkdir(path.dirname(contextPath), { recursive: true });
+                await fs.writeFile(contextPath, context.content, 'utf8');
+                const agentResult = await this.agent.analyze(context.path);
+                const outputPath = outputPathForContext(contextPath);
+                const analysisResult = await this.processAgentOutput(agentResult, outputPath, parseAnalysisOutput);
+                if (analysisResult.success) {
+                    analysisOutput = analysisResult.data;
+                    if (!transitionStatus(this.db, errorId, 'analyzing', 'suggested', lockId)) {
+                        throw new UserError(`Failed to transition error ${errorId} into suggested status`);
+                    }
+                    this.db.run('UPDATE errors SET suggestion = ?, updated_at = ? WHERE id = ?', [
+                        JSON.stringify(analysisOutput),
+                        new Date().toISOString(),
+                        errorId,
+                    ]);
+                    logActivity(this.db, 'analysis_complete', errorId, JSON.stringify({
+                        attempt: attempts,
+                        confidence: analysisOutput.confidence,
+                    }));
+                    if (analyzeOnly) {
+                        await releaseLock(this.db, errorId, lockId);
+                        lockHeld = false;
+                        return {
+                            errorId,
+                            status: 'suggested',
+                            lockAcquired: true,
+                            attempts,
+                            analysis: analysisOutput,
+                            message: 'Analysis complete (analyze-only)',
+                        };
+                    }
+                }
+                else {
+                    logActivity(this.db, agentResult.timedOut ? 'analysis_timeout' : 'analysis_failed', errorId, JSON.stringify({ attempt: attempts, diagnostic: analysisResult.diagnostic }));
+                    if (shouldReanalyze) {
+                        if (!transitionStatus(this.db, errorId, 'analyzing', 'suggested', lockId)) {
+                            throw new UserError(`Failed to transition error ${errorId} back to suggested status`);
+                        }
+                        await releaseLock(this.db, errorId, lockId);
+                        lockHeld = false;
+                        return {
+                            errorId,
+                            status: 'suggested',
+                            lockAcquired: true,
+                            attempts,
+                            message: 'Re-analysis failed; existing analysis preserved',
+                        };
+                    }
+                    const newAttempts = attempts + 1;
+                    attempts = newAttempts;
+                    const nextStatus = newAttempts >= maxAttempts ? 'failed' : 'pending';
+                    if (!transitionStatus(this.db, errorId, 'analyzing', nextStatus, lockId)) {
+                        throw new UserError(`Failed to transition error ${errorId} after analysis failure`);
+                    }
+                    this.db.run('UPDATE errors SET suggestion = ?, fix_attempts = ?, updated_at = ? WHERE id = ?', [
+                        JSON.stringify({ error: true, diagnostic: analysisResult.diagnostic }),
+                        newAttempts,
+                        new Date().toISOString(),
+                        errorId,
+                    ]);
+                    await releaseLock(this.db, errorId, lockId);
+                    lockHeld = false;
+                    return {
+                        errorId,
+                        status: nextStatus,
+                        lockAcquired: true,
+                        attempts,
+                        message: 'Analysis failed',
+                    };
+                }
+            }
+            else if (analyzeOnly) {
+                if (!error.suggestion) {
+                    throw new UserError(`Error ${errorId} has no stored analysis`);
+                }
+                analysisOutput = parseSuggestion(error.suggestion);
+                await releaseLock(this.db, errorId, lockId);
+                lockHeld = false;
+                return {
+                    errorId,
+                    status: 'suggested',
+                    lockAcquired: true,
+                    attempts,
+                    analysis: analysisOutput,
+                    message: 'Already analyzed (analyze-only)',
+                };
+            }
+            else {
+                if (!error.suggestion) {
+                    throw new UserError(`Error ${errorId} has no stored analysis`);
+                }
+                analysisOutput = parseSuggestion(error.suggestion);
+            }
+            if (!analysisOutput) {
+                throw new UserError('Missing analysis output for fix phase');
+            }
+            if (!transitionStatus(this.db, errorId, 'suggested', 'fixing', lockId)) {
+                throw new UserError(`Failed to transition error ${errorId} into fixing status`);
+            }
+            logActivity(this.db, 'fix_start', errorId, JSON.stringify({ attempt: attempts, lockId }));
+            this.logger.info(`Applying fix for error ${errorId} (attempt ${attempts})...`);
+            const analysisYaml = analysisToYaml(analysisOutput);
+            const fixContext = generateFixContext(error, analysisYaml, this.config, attempts);
+            const fixContextPath = path.resolve(this.config.project.root, fixContext.path);
+            await fs.mkdir(path.dirname(fixContextPath), { recursive: true });
+            await fs.writeFile(fixContextPath, fixContext.content, 'utf8');
+            const fixAgentResult = await this.agent.fix(fixContext.path);
+            const fixOutputPath = outputPathForContext(fixContextPath);
+            const fixResult = await this.processAgentOutput(fixAgentResult, fixOutputPath, parseFixOutput);
+            if (fixResult.success) {
+                fixOutput = fixResult.data;
+                this.db.run('UPDATE errors SET fix_result = ?, updated_at = ? WHERE id = ?', [
+                    JSON.stringify(fixOutput),
+                    new Date().toISOString(),
+                    errorId,
+                ]);
+                if (fixOutput.success) {
+                    logActivity(this.db, 'fix_complete', errorId, JSON.stringify({ attempt: attempts }));
+                }
+                else {
+                    logActivity(this.db, 'fix_failed', errorId, JSON.stringify({
+                        attempt: attempts,
+                        summary: fixOutput.summary,
+                        notes: fixOutput.notes ?? '',
+                    }));
+                }
+                if (!fixOutput.success) {
+                    const newAttempts = attempts + 1;
+                    attempts = newAttempts;
+                    const nextStatus = newAttempts >= maxAttempts ? 'failed' : 'pending';
+                    if (!transitionStatus(this.db, errorId, 'fixing', nextStatus, lockId)) {
+                        throw new UserError(`Failed to transition error ${errorId} after fix failure`);
+                    }
+                    this.db.run('UPDATE errors SET fix_attempts = ?, updated_at = ? WHERE id = ?', [newAttempts, new Date().toISOString(), errorId]);
+                    await releaseLock(this.db, errorId, lockId);
+                    lockHeld = false;
+                    return {
+                        errorId,
+                        status: nextStatus,
+                        lockAcquired: true,
+                        attempts,
+                        analysis: analysisOutput,
+                        fix: fixOutput,
+                        message: 'Fix reported failure',
+                    };
+                }
+            }
+            else {
+                logActivity(this.db, fixAgentResult.timedOut ? 'fix_timeout' : 'fix_failed', errorId, JSON.stringify({ attempt: attempts, diagnostic: fixResult.diagnostic }));
+                const newAttempts = attempts + 1;
+                attempts = newAttempts;
+                const nextStatus = newAttempts >= maxAttempts ? 'failed' : 'pending';
+                if (!transitionStatus(this.db, errorId, 'fixing', nextStatus, lockId)) {
+                    throw new UserError(`Failed to transition error ${errorId} after fix failure`);
+                }
+                this.db.run('UPDATE errors SET fix_result = ?, fix_attempts = ?, updated_at = ? WHERE id = ?', [
+                    JSON.stringify({ error: true, diagnostic: fixResult.diagnostic }),
+                    newAttempts,
+                    new Date().toISOString(),
+                    errorId,
+                ]);
+                await releaseLock(this.db, errorId, lockId);
+                lockHeld = false;
+                return {
+                    errorId,
+                    status: nextStatus,
+                    lockAcquired: true,
+                    attempts,
+                    analysis: analysisOutput,
+                    message: 'Fix failed',
+                };
+            }
+            logActivity(this.db, 'verification_start', errorId, JSON.stringify({ attempt: attempts }));
+            this.logger.info(`Verifying fix for error ${errorId}...`);
+            verificationResult = await runVerification(this.config, {
+                logger: this.logger,
+                terminalEnabled: this.terminalEnabled,
+            });
+            if (verificationResult.success) {
+                if (!transitionStatus(this.db, errorId, 'fixing', 'fixed', lockId)) {
+                    throw new UserError(`Failed to transition error ${errorId} into fixed status`);
+                }
+                logActivity(this.db, 'verification_pass', errorId, JSON.stringify({ attempt: attempts }));
+                await releaseLock(this.db, errorId, lockId);
+                lockHeld = false;
+                return {
+                    errorId,
+                    status: 'fixed',
+                    lockAcquired: true,
+                    attempts,
+                    analysis: analysisOutput,
+                    fix: fixOutput,
+                    verification: verificationResult,
+                    message: 'Fix verified',
+                };
+            }
+            const newAttempts = attempts + 1;
+            attempts = newAttempts;
+            const nextStatus = newAttempts >= maxAttempts ? 'failed' : 'pending';
+            if (!transitionStatus(this.db, errorId, 'fixing', nextStatus, lockId)) {
+                throw new UserError(`Failed to transition error ${errorId} after verification failure`);
+            }
+            this.db.run('UPDATE errors SET fix_attempts = ?, updated_at = ? WHERE id = ?', [newAttempts, new Date().toISOString(), errorId]);
+            logActivity(this.db, 'verification_fail', errorId, JSON.stringify({ attempt: attempts, failure: verificationResult.failure }));
+            await releaseLock(this.db, errorId, lockId);
+            lockHeld = false;
+            return {
+                errorId,
+                status: nextStatus,
+                lockAcquired: true,
+                attempts,
+                analysis: analysisOutput,
+                fix: fixOutput,
+                verification: verificationResult,
+                message: 'Verification failed',
+            };
+        }
+        finally {
+            if (lockHeld) {
+                await releaseLock(this.db, errorId, lockId);
+            }
+        }
+    }
+    async processAgentOutput(result, outputPath, parser) {
+        if (!result.success) {
+            const diagnostic = formatAgentDiagnostic(result, outputPath ?? 'output file');
+            return { success: false, diagnostic };
+        }
+        if (!outputPath) {
+            return {
+                success: false,
+                diagnostic: 'Unable to determine expected output path',
+            };
+        }
+        if (!result.outputFileExists) {
+            return {
+                success: false,
+                diagnostic: formatAgentDiagnostic(result, outputPath),
+            };
+        }
+        let content = '';
+        try {
+            content = await fs.readFile(outputPath, 'utf8');
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                diagnostic: `Failed to read output file ${outputPath}: ${message}`,
+            };
+        }
+        try {
+            const data = parser(content);
+            return { success: true, data, rawContent: content };
+        }
+        catch (error) {
+            return {
+                success: false,
+                diagnostic: formatParseDiagnostic(error, content),
+            };
+        }
+    }
+}

package/dist/fixer/lock.d.ts

@@ -0,0 +1,7 @@
+import type { ErrorStatus } from '../utils/errors.js';
+import type { Database } from '../db/index.js';
+export declare const LOCK_TIMEOUT_MS: number;
+export declare function generateLockId(): string;
+export declare function acquireLock(db: Database, errorId: number, lockId: string): Promise<boolean>;
+export declare function releaseLock(db: Database, errorId: number, lockId: string): Promise<void>;
+export declare function transitionStatus(db: Database, errorId: number, expected: ErrorStatus | ErrorStatus[], newStatus: ErrorStatus, lockId: string): boolean;

package/dist/fixer/lock.js

@@ -0,0 +1,49 @@
+import os from 'node:os';
+import { logActivity } from '../db/queries.js';
+export const LOCK_TIMEOUT_MS = 10 * 60 * 1000;
+export function generateLockId() {
+    return `${os.hostname()}:${process.pid}:${Date.now()}`;
+}
+export async function acquireLock(db, errorId, lockId) {
+    const now = new Date().toISOString();
+    const expiryThreshold = new Date(Date.now() - LOCK_TIMEOUT_MS).toISOString();
+    const existing = db.get('SELECT locked_by, locked_at FROM errors WHERE id = ?', [errorId]);
+    const result = db.run(`UPDATE errors
+     SET locked_by = ?, locked_at = ?, updated_at = ?
+     WHERE id = ?
+       AND (
+         locked_by IS NULL
+         OR locked_at < ?
+       )`, [lockId, now, now, errorId, expiryThreshold]);
+    if (result.changes === 0) {
+        return false;
+    }
+    if (existing?.locked_by &&
+        existing.locked_at &&
+        existing.locked_at < expiryThreshold) {
+        logActivity(db, 'lock_expired', errorId, JSON.stringify({
+            previousLockId: existing.locked_by,
+            acquiredBy: lockId,
+        }));
+    }
+    logActivity(db, 'lock_acquired', errorId, JSON.stringify({ lockId }));
+    return true;
+}
+export async function releaseLock(db, errorId, lockId) {
+    const result = db.run(`UPDATE errors
+     SET locked_by = NULL, locked_at = NULL, updated_at = ?
+     WHERE id = ? AND locked_by = ?`, [new Date().toISOString(), errorId, lockId]);
+    if (result.changes > 0) {
+        logActivity(db, 'lock_released', errorId, JSON.stringify({ lockId }));
+    }
+}
+export function transitionStatus(db, errorId, expected, newStatus, lockId) {
+    const expectedStatuses = Array.isArray(expected) ? expected : [expected];
+    const placeholders = expectedStatuses.map(() => '?').join(', ');
+    const result = db.run(`UPDATE errors
+     SET status = ?, updated_at = ?
+     WHERE id = ?
+       AND locked_by = ?
+       AND status IN (${placeholders})`, [newStatus, new Date().toISOString(), errorId, lockId, ...expectedStatuses]);
+    return result.changes > 0;
+}

package/dist/fixer/output.d.ts

@@ -0,0 +1,21 @@
+type ConfidenceLevel = 'high' | 'medium' | 'low';
+type AnalysisOutput = {
+    summary: string;
+    root_cause: string;
+    suggested_fix: string;
+    files_to_modify: string[];
+    confidence: ConfidenceLevel;
+};
+type FixOutput = {
+    success: boolean;
+    summary: string;
+    files_changed?: Array<{
+        path: string;
+        change: string;
+    }>;
+    notes?: string;
+};
+declare const parseAnalysisOutput: (content: string) => AnalysisOutput;
+declare const parseFixOutput: (content: string) => FixOutput;
+export type { AnalysisOutput, FixOutput, ConfidenceLevel };
+export { parseAnalysisOutput, parseFixOutput };

package/dist/fixer/output.js

@@ -0,0 +1,108 @@
+import yaml from 'yaml';
+import { UserError } from '../utils/errors.js';
+const parseYaml = (content) => {
+    try {
+        return yaml.parse(content);
+    }
+    catch (error) {
+        const err = error;
+        throw new UserError(`Failed to parse YAML output: ${err.message ?? String(err)}`);
+    }
+};
+const assertRecord = (value) => {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new UserError('Invalid agent output: expected a YAML object');
+    }
+    return value;
+};
+const requireStringField = (data, field) => {
+    const value = data[field];
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new UserError(`Missing required field: ${field}`);
+    }
+    return value;
+};
+const requireBooleanField = (data, field) => {
+    const value = data[field];
+    if (typeof value !== 'boolean') {
+        throw new UserError(`Missing required field: ${field}`);
+    }
+    return value;
+};
+const requireStringArrayField = (data, field) => {
+    const value = data[field];
+    if (!Array.isArray(value)) {
+        throw new UserError(`Missing required field: ${field}`);
+    }
+    const strings = value.filter((entry) => typeof entry === 'string');
+    if (strings.length !== value.length) {
+        throw new UserError(`Invalid field: ${field} must be an array of strings`);
+    }
+    return strings;
+};
+const validateFilesChanged = (value) => {
+    if (!Array.isArray(value)) {
+        throw new UserError('Invalid field: files_changed must be an array of { path, change }');
+    }
+    const mapped = value.map((entry) => {
+        if (typeof entry !== 'object' ||
+            entry === null ||
+            Array.isArray(entry)) {
+            throw new UserError('Invalid field: files_changed must be an array of { path, change }');
+        }
+        const record = entry;
+        const path = record.path;
+        const change = record.change;
+        if (typeof path !== 'string' || typeof change !== 'string') {
+            throw new UserError('Invalid field: files_changed must be an array of { path, change }');
+        }
+        return { path, change };
+    });
+    return mapped.length > 0 ? mapped : undefined;
+};
+const validateConfidence = (value) => {
+    if (value === 'high' || value === 'medium' || value === 'low') {
+        return value;
+    }
+    throw new UserError(`Invalid confidence value: ${value ?? 'undefined'} (expected high|medium|low)`);
+};
+const parseAnalysisOutput = (content) => {
+    const raw = parseYaml(content);
+    const data = assertRecord(raw);
+    const summary = requireStringField(data, 'summary');
+    const root_cause = requireStringField(data, 'root_cause');
+    const suggested_fix = requireStringField(data, 'suggested_fix');
+    const files_to_modify = requireStringArrayField(data, 'files_to_modify');
+    const confidence = validateConfidence(data.confidence);
+    return {
+        summary,
+        root_cause,
+        suggested_fix,
+        files_to_modify,
+        confidence,
+    };
+};
+const parseFixOutput = (content) => {
+    const raw = parseYaml(content);
+    const data = assertRecord(raw);
+    const success = requireBooleanField(data, 'success');
+    const summary = requireStringField(data, 'summary');
+    let files_changed;
+    if (data.files_changed !== undefined) {
+        files_changed = validateFilesChanged(data.files_changed);
+    }
+    let notes;
+    if (data.notes !== undefined) {
+        if (typeof data.notes !== 'string') {
+            throw new UserError('Invalid field: notes must be a string');
+        }
+        notes = data.notes;
+    }
+    return {
+        success,
+        summary,
+        files_changed,
+        notes,
+    };
+};
+export { parseAnalysisOutput, parseFixOutput };

package/dist/fixer/queue.d.ts

@@ -0,0 +1,15 @@
+import type { Database } from '../db/index.js';
+import { type ErrorRecord } from '../db/queries.js';
+type FixQueueOptions = {
+    onProcess?: (error: ErrorRecord) => Promise<void> | void;
+};
+export declare class FixQueue {
+    private readonly db;
+    private readonly onProcess?;
+    private fixInProgress;
+    private processingPromise;
+    constructor(db: Database, options?: FixQueueOptions);
+    getNext(): ErrorRecord | null;
+    processQueueIfReady(): Promise<void>;
+}
+export {};

package/dist/fixer/queue.js

@@ -0,0 +1,53 @@
+import { getErrorsByStatus } from '../db/queries.js';
+export class FixQueue {
+    db;
+    onProcess;
+    fixInProgress = false;
+    processingPromise = null;
+    constructor(db, options) {
+        this.db = db;
+        this.onProcess = options?.onProcess;
+    }
+    getNext() {
+        if (this.fixInProgress) {
+            return null;
+        }
+        const errors = getErrorsByStatus(this.db, ['pending', 'suggested']);
+        return errors[0] ?? null;
+    }
+    async processQueueIfReady() {
+        if (!this.onProcess) {
+            return;
+        }
+        if (this.processingPromise) {
+            // If already processing, wait for the current loop to finish and then
+            // trigger a new check to ensure no items were missed in the window
+            // between getNext() returning null and the promise resolving.
+            await this.processingPromise;
+            return this.processQueueIfReady();
+        }
+        this.processingPromise = (async () => {
+            try {
+                for (let next = this.getNext(); next; next = this.getNext()) {
+                    this.fixInProgress = true;
+                    try {
+                        await this.onProcess?.(next);
+                    }
+                    finally {
+                        this.fixInProgress = false;
+                    }
+                }
+            }
+            catch (err) {
+                // We catch here to ensure the promise resolves and processingPromise is cleared
+                // The error should ideally be logged by a real logger if available.
+            }
+        })();
+        try {
+            await this.processingPromise;
+        }
+        finally {
+            this.processingPromise = null;
+        }
+    }
+}