pm-orchestrator-runner 1.0.7 → 1.0.9

package/dist/prompt/prompt-assembler.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * Prompt Assembler
+ * Per spec/17_PROMPT_TEMPLATE.md
+ *
+ * Assembles prompts in fixed order (no caching, no omission):
+ * 1. global prelude
+ * 2. project prelude
+ * 3. task group prelude (dynamic)
+ * 4. user input
+ * 5. output format epilogue
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptAssembler = exports.PromptAssemblerError = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * PromptAssembler Error
+ */
+class PromptAssemblerError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'PromptAssemblerError';
+    }
+}
+exports.PromptAssemblerError = PromptAssemblerError;
+/**
+ * Prompt Assembler
+ *
+ * Per spec/17_PROMPT_TEMPLATE.md:
+ * - Always assemble in fixed order
+ * - No caching (rebuild every time)
+ * - No omission
+ */
+class PromptAssembler {
+    projectPath;
+    templateDir;
+    constructor(config) {
+        this.projectPath = config.projectPath;
+        this.templateDir = config.templateDir || '.claude/prompt-templates';
+    }
+    /**
+     * Assemble the prompt from all sections
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * Order is fixed and non-negotiable:
+     * 1. global prelude
+     * 2. project prelude
+     * 3. task group prelude
+     * 4. user input
+     * 5. output format epilogue
+     *
+     * @param userInput - The user's input (task.naturalLanguageTask)
+     * @param taskGroupContext - Optional task group context for prelude generation
+     * @returns AssemblyResult with assembled prompt and sections
+     * @throws PromptAssemblerError if user input is empty
+     */
+    assemble(userInput, taskGroupContext) {
+        // Fail-closed: user input must not be empty
+        if (!userInput || userInput.trim().length === 0) {
+            throw new PromptAssemblerError('User input is required (fail-closed: empty input not allowed)');
+        }
+        // Load/build each section (no caching per spec)
+        const sections = {
+            globalPrelude: this.loadGlobalPrelude(),
+            projectPrelude: this.loadProjectPrelude(),
+            taskGroupPrelude: taskGroupContext ? this.buildTaskGroupPrelude(taskGroupContext) : '',
+            userInput: userInput.trim(),
+            outputEpilogue: this.loadOutputEpilogue(),
+        };
+        // Assemble in fixed order
+        const parts = [];
+        if (sections.globalPrelude) {
+            parts.push(sections.globalPrelude);
+        }
+        if (sections.projectPrelude) {
+            parts.push(sections.projectPrelude);
+        }
+        if (sections.taskGroupPrelude) {
+            parts.push(sections.taskGroupPrelude);
+        }
+        // User input is always included (already validated non-empty)
+        parts.push(sections.userInput);
+        if (sections.outputEpilogue) {
+            parts.push(sections.outputEpilogue);
+        }
+        return {
+            prompt: parts.join('\n\n'),
+            sections,
+        };
+    }
+    /**
+     * Load global prelude from template file
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * - File: .claude/prompt-templates/global-prelude.md
+     * - Contains: rules, prohibitions, output format assumptions
+     *
+     * @returns Global prelude content (empty string if file not found)
+     */
+    loadGlobalPrelude() {
+        return this.loadTemplateFile('global-prelude.md');
+    }
+    /**
+     * Load project prelude from template file
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * - File: .claude/prompt-templates/project-prelude.md
+     * - Contains: project-specific constraints, file structure, tech constraints
+     *
+     * @returns Project prelude content (empty string if file not found)
+     */
+    loadProjectPrelude() {
+        return this.loadTemplateFile('project-prelude.md');
+    }
+    /**
+     * Build task group prelude dynamically
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * - Dynamically generated from TaskGroupContext
+     * - Contains: conversation thread purpose, prerequisites, context summary
+     *
+     * Per spec/16_TASK_GROUP.md L100-106:
+     * - task_group_id: for context isolation
+     * - conversation_history: for context continuity
+     * - working_files: current working set
+     * - last_task_result: for building on previous work
+     *
+     * @param context - Task group context
+     * @returns Task group prelude content
+     */
+    buildTaskGroupPrelude(context) {
+        const lines = [];
+        lines.push(`## Task Group Context`);
+        lines.push(`Task Group ID: ${context.task_group_id}`);
+        lines.push('');
+        // Working files
+        if (context.working_files.length > 0) {
+            lines.push('### Working Files');
+            for (const file of context.working_files) {
+                lines.push(`- ${file}`);
+            }
+            lines.push('');
+        }
+        // Last task result
+        if (context.last_task_result) {
+            lines.push('### Previous Task Result');
+            lines.push(`- Task: ${context.last_task_result.task_id}`);
+            lines.push(`- Status: ${context.last_task_result.status}`);
+            lines.push(`- Summary: ${context.last_task_result.summary}`);
+            if (context.last_task_result.files_modified.length > 0) {
+                lines.push(`- Files Modified: ${context.last_task_result.files_modified.join(', ')}`);
+            }
+            if (context.last_task_result.error) {
+                lines.push(`- Error: ${context.last_task_result.error}`);
+            }
+            lines.push('');
+        }
+        // Conversation history summary (last 5 entries to keep prelude manageable)
+        if (context.conversation_history.length > 0) {
+            lines.push('### Recent Conversation');
+            const recentEntries = context.conversation_history.slice(-5);
+            for (const entry of recentEntries) {
+                const preview = entry.content.length > 100
+                    ? entry.content.substring(0, 100) + '...'
+                    : entry.content;
+                lines.push(`- [${entry.role}] ${preview}`);
+            }
+            lines.push('');
+        }
+        return lines.join('\n');
+    }
+    /**
+     * Load output format epilogue from template file
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * - File: .claude/prompt-templates/output-epilogue.md
+     * - Contains: required report format, evidence output format, completion conditions
+     *
+     * @returns Output epilogue content (empty string if file not found)
+     */
+    loadOutputEpilogue() {
+        return this.loadTemplateFile('output-epilogue.md');
+    }
+    /**
+     * Load template file content
+     *
+     * Per spec/17_PROMPT_TEMPLATE.md:
+     * - Template files are in .claude/prompt-templates/
+     * - If file doesn't exist, return empty string (not an error)
+     *
+     * @param filename - Template filename
+     * @returns File content or empty string
+     */
+    loadTemplateFile(filename) {
+        const templatePath = path.join(this.projectPath, this.templateDir, filename);
+        try {
+            if (fs.existsSync(templatePath)) {
+                return fs.readFileSync(templatePath, 'utf-8').trim();
+            }
+        }
+        catch {
+            // File read error - treat as non-existent
+        }
+        return '';
+    }
+}
+exports.PromptAssembler = PromptAssembler;
+//# sourceMappingURL=prompt-assembler.js.map

package/dist/prompt/prompt-assembler.js.map

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

package/dist/queue/index.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Queue Module
+ * Per spec/20_QUEUE_STORE.md
+ *
+ * Exports:
+ * - QueueStore: DynamoDB-backed queue storage
+ * - QueuePoller: Polling and task execution
+ * - createNamespacedQueueStore: Factory for namespace-separated QueueStore
+ */
+export { QueueStore, QueueStoreConfig, QueueItem, QueueItemStatus, ClaimResult, TaskGroupSummary, } from './queue-store';
+export { QueuePoller, QueuePollerConfig, QueuePollerState, QueuePollerEvents, TaskExecutor, } from './queue-poller';
+import { QueueStore, QueueStoreConfig } from './queue-store';
+/**
+ * Namespace configuration for QueueStore
+ * Per spec/21_STABLE_DEV.md
+ */
+export interface NamespaceQueueConfig {
+    /** Namespace name (e.g., 'stable', 'dev') */
+    namespace: string;
+    /** Table name derived from namespace */
+    tableName: string;
+}
+/**
+ * Create a QueueStore instance with namespace separation
+ * Per spec/21_STABLE_DEV.md
+ *
+ * @param namespaceConfig - Namespace configuration with tableName
+ * @param storeConfig - Optional additional QueueStore configuration
+ * @returns Configured QueueStore instance
+ *
+ * @example
+ * ```typescript
+ * const namespaceConfig = buildNamespaceConfig({ namespace: 'dev', projectRoot: '/path' });
+ * const store = createNamespacedQueueStore({
+ *   namespace: namespaceConfig.namespace,
+ *   tableName: namespaceConfig.tableName,
+ * });
+ * ```
+ */
+export declare function createNamespacedQueueStore(namespaceConfig: NamespaceQueueConfig, storeConfig?: Omit<QueueStoreConfig, 'tableName'>): QueueStore;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,SAAS,EACT,eAAe,EACf,WAAW,EACX,gBAAgB,GACjB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,WAAW,EACX,iBAAiB,EACjB,gBAAgB,EAChB,iBAAiB,EACjB,YAAY,GACb,MAAM,gBAAgB,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,0BAA0B,CACxC,eAAe,EAAE,oBAAoB,EACrC,WAAW,CAAC,EAAE,IAAI,CAAC,gBAAgB,EAAE,WAAW,CAAC,GAChD,UAAU,CAKZ"}

package/dist/queue/index.js

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * Queue Module
+ * Per spec/20_QUEUE_STORE.md
+ *
+ * Exports:
+ * - QueueStore: DynamoDB-backed queue storage
+ * - QueuePoller: Polling and task execution
+ * - createNamespacedQueueStore: Factory for namespace-separated QueueStore
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueuePoller = exports.QueueStore = void 0;
+exports.createNamespacedQueueStore = createNamespacedQueueStore;
+var queue_store_1 = require("./queue-store");
+Object.defineProperty(exports, "QueueStore", { enumerable: true, get: function () { return queue_store_1.QueueStore; } });
+var queue_poller_1 = require("./queue-poller");
+Object.defineProperty(exports, "QueuePoller", { enumerable: true, get: function () { return queue_poller_1.QueuePoller; } });
+const queue_store_2 = require("./queue-store");
+/**
+ * Create a QueueStore instance with namespace separation
+ * Per spec/21_STABLE_DEV.md
+ *
+ * @param namespaceConfig - Namespace configuration with tableName
+ * @param storeConfig - Optional additional QueueStore configuration
+ * @returns Configured QueueStore instance
+ *
+ * @example
+ * ```typescript
+ * const namespaceConfig = buildNamespaceConfig({ namespace: 'dev', projectRoot: '/path' });
+ * const store = createNamespacedQueueStore({
+ *   namespace: namespaceConfig.namespace,
+ *   tableName: namespaceConfig.tableName,
+ * });
+ * ```
+ */
+function createNamespacedQueueStore(namespaceConfig, storeConfig) {
+    return new queue_store_2.QueueStore({
+        ...storeConfig,
+        tableName: namespaceConfig.tableName,
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/queue/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/queue/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;;AAiDH,gEAQC;AAvDD,6CAOuB;AANrB,yGAAA,UAAU,OAAA;AAQZ,+CAMwB;AALtB,2GAAA,WAAW,OAAA;AAOb,+CAA6D;AAa7D;;;;;;;;;;;;;;;;GAgBG;AACH,SAAgB,0BAA0B,CACxC,eAAqC,EACrC,WAAiD;IAEjD,OAAO,IAAI,wBAAU,CAAC;QACpB,GAAG,WAAW;QACd,SAAS,EAAE,eAAe,CAAC,SAAS;KACrC,CAAC,CAAC;AACL,CAAC"}

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

@@ -0,0 +1,107 @@
+/**
+ * Queue Poller - Polls queue and executes tasks
+ * Per spec/20_QUEUE_STORE.md
+ *
+ * Features:
+ * - Polling interval configurable (default 1000ms)
+ * - 1 task per tick
+ * - In-flight limit: 1 (no concurrent execution)
+ * - Fail-closed error handling
+ */
+import { EventEmitter } from 'events';
+import { QueueStore, QueueItem } from './queue-store';
+/**
+ * Task executor function type
+ * Returns status and optional error message
+ */
+export type TaskExecutor = (item: QueueItem) => Promise<{
+    status: 'COMPLETE' | 'ERROR';
+    errorMessage?: string;
+}>;
+/**
+ * Poller configuration
+ */
+export interface QueuePollerConfig {
+    /** Polling interval in milliseconds (default: 1000) */
+    pollIntervalMs?: number;
+    /** Max stale task age in milliseconds (default: 5 minutes) */
+    maxStaleTaskAgeMs?: number;
+    /** Recover stale tasks on startup (default: true) */
+    recoverOnStartup?: boolean;
+}
+/**
+ * Poller state
+ */
+export interface QueuePollerState {
+    isRunning: boolean;
+    inFlight: QueueItem | null;
+    lastPollAt: string | null;
+    tasksProcessed: number;
+    errors: number;
+}
+/**
+ * Poller events
+ */
+export interface QueuePollerEvents {
+    started: [];
+    stopped: [];
+    poll: [{
+        queuedCount: number;
+    }];
+    claimed: [QueueItem];
+    completed: [QueueItem];
+    error: [QueueItem, Error];
+    'no-task': [];
+    'already-claimed': [string];
+    'stale-recovered': [number];
+}
+/**
+ * Queue Poller
+ * Polls the queue store and executes tasks
+ */
+export declare class QueuePoller extends EventEmitter {
+    private readonly store;
+    private readonly executor;
+    private readonly pollIntervalMs;
+    private readonly maxStaleTaskAgeMs;
+    private readonly recoverOnStartup;
+    private pollTimer;
+    private inFlight;
+    private isRunning;
+    private lastPollAt;
+    private tasksProcessed;
+    private errors;
+    constructor(store: QueueStore, executor: TaskExecutor, config?: QueuePollerConfig);
+    /**
+     * Start polling
+     */
+    start(): Promise<void>;
+    /**
+     * Stop polling
+     */
+    stop(): void;
+    /**
+     * Single poll iteration
+     * - Skip if task in-flight
+     * - Claim oldest QUEUED task
+     * - Execute and update status
+     */
+    poll(): Promise<void>;
+    /**
+     * Get current state
+     */
+    getState(): QueuePollerState;
+    /**
+     * Check if poller is running
+     */
+    isActive(): boolean;
+    /**
+     * Check if task is in-flight
+     */
+    hasInFlight(): boolean;
+    /**
+     * Get in-flight task
+     */
+    getInFlight(): QueueItem | null;
+}
+//# sourceMappingURL=queue-poller.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"queue-poller.d.ts","sourceRoot":"","sources":["../../src/queue/queue-poller.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,SAAS,EAAmB,MAAM,eAAe,CAAC;AAEvE;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,CACzB,IAAI,EAAE,SAAS,KACZ,OAAO,CAAC;IAAE,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEtE;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8DAA8D;IAC9D,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,qDAAqD;IACrD,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,OAAO,CAAC;IACnB,QAAQ,EAAE,SAAS,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,EAAE,CAAC;IACZ,OAAO,EAAE,EAAE,CAAC;IACZ,IAAI,EAAE,CAAC;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAChC,OAAO,EAAE,CAAC,SAAS,CAAC,CAAC;IACrB,SAAS,EAAE,CAAC,SAAS,CAAC,CAAC;IACvB,KAAK,EAAE,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IAC1B,SAAS,EAAE,EAAE,CAAC;IACd,iBAAiB,EAAE,CAAC,MAAM,CAAC,CAAC;IAC5B,iBAAiB,EAAE,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;GAGG;AACH,qBAAa,WAAY,SAAQ,YAAY;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAa;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;IAE3C,OAAO,CAAC,SAAS,CAA+C;IAChE,OAAO,CAAC,QAAQ,CAA0B;IAC1C,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,cAAc,CAAa;IACnC,OAAO,CAAC,MAAM,CAAa;gBAGzB,KAAK,EAAE,UAAU,EACjB,QAAQ,EAAE,YAAY,EACtB,MAAM,GAAE,iBAAsB;IAUhC;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAmC5B;;OAEG;IACH,IAAI,IAAI,IAAI;IAeZ;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAoE3B;;OAEG;IACH,QAAQ,IAAI,gBAAgB;IAU5B;;OAEG;IACH,QAAQ,IAAI,OAAO;IAInB;;OAEG;IACH,WAAW,IAAI,OAAO;IAItB;;OAEG;IACH,WAAW,IAAI,SAAS,GAAG,IAAI;CAGhC"}

package/dist/queue/queue-poller.js

@@ -0,0 +1,181 @@
+"use strict";
+/**
+ * Queue Poller - Polls queue and executes tasks
+ * Per spec/20_QUEUE_STORE.md
+ *
+ * Features:
+ * - Polling interval configurable (default 1000ms)
+ * - 1 task per tick
+ * - In-flight limit: 1 (no concurrent execution)
+ * - Fail-closed error handling
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueuePoller = void 0;
+const events_1 = require("events");
+/**
+ * Queue Poller
+ * Polls the queue store and executes tasks
+ */
+class QueuePoller extends events_1.EventEmitter {
+    store;
+    executor;
+    pollIntervalMs;
+    maxStaleTaskAgeMs;
+    recoverOnStartup;
+    pollTimer = null;
+    inFlight = null;
+    isRunning = false;
+    lastPollAt = null;
+    tasksProcessed = 0;
+    errors = 0;
+    constructor(store, executor, config = {}) {
+        super();
+        this.store = store;
+        this.executor = executor;
+        this.pollIntervalMs = config.pollIntervalMs ?? 1000;
+        this.maxStaleTaskAgeMs = config.maxStaleTaskAgeMs ?? 5 * 60 * 1000;
+        this.recoverOnStartup = config.recoverOnStartup ?? true;
+    }
+    /**
+     * Start polling
+     */
+    async start() {
+        if (this.isRunning) {
+            return;
+        }
+        this.isRunning = true;
+        // Recover stale tasks on startup (fail-closed)
+        if (this.recoverOnStartup) {
+            try {
+                const recovered = await this.store.recoverStaleTasks(this.maxStaleTaskAgeMs);
+                if (recovered > 0) {
+                    this.emit('stale-recovered', recovered);
+                }
+            }
+            catch (error) {
+                // Log but don't fail startup
+                // eslint-disable-next-line no-console
+                console.error('[QueuePoller] Failed to recover stale tasks:', error);
+            }
+        }
+        this.emit('started');
+        // Start polling loop
+        this.pollTimer = setInterval(() => {
+            this.poll().catch(error => {
+                // eslint-disable-next-line no-console
+                console.error('[QueuePoller] Poll error:', error);
+            });
+        }, this.pollIntervalMs);
+        // Immediate first poll
+        await this.poll();
+    }
+    /**
+     * Stop polling
+     */
+    stop() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.isRunning = false;
+        if (this.pollTimer) {
+            clearInterval(this.pollTimer);
+            this.pollTimer = null;
+        }
+        this.emit('stopped');
+    }
+    /**
+     * Single poll iteration
+     * - Skip if task in-flight
+     * - Claim oldest QUEUED task
+     * - Execute and update status
+     */
+    async poll() {
+        if (!this.isRunning) {
+            return;
+        }
+        this.lastPollAt = new Date().toISOString();
+        // In-flight limit: 1
+        if (this.inFlight) {
+            return;
+        }
+        // Try to claim a task
+        const claimResult = await this.store.claim();
+        if (!claimResult.success) {
+            if (claimResult.error) {
+                // Task was claimed by another process
+                this.emit('already-claimed', claimResult.error);
+            }
+            else {
+                // No tasks in queue
+                this.emit('no-task');
+            }
+            return;
+        }
+        const item = claimResult.item;
+        this.inFlight = item;
+        this.emit('claimed', item);
+        try {
+            // Execute the task
+            const result = await this.executor(item);
+            // Update status
+            await this.store.updateStatus(item.task_id, result.status, result.errorMessage);
+            if (result.status === 'COMPLETE') {
+                this.tasksProcessed++;
+                this.emit('completed', item);
+            }
+            else {
+                this.errors++;
+                this.emit('error', item, new Error(result.errorMessage || 'Task failed'));
+            }
+        }
+        catch (error) {
+            // Fail-closed: mark as ERROR
+            this.errors++;
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            try {
+                await this.store.updateStatus(item.task_id, 'ERROR', errorMessage);
+            }
+            catch (updateError) {
+                // Log but don't throw - we've already failed
+                // eslint-disable-next-line no-console
+                console.error('[QueuePoller] Failed to update error status:', updateError);
+            }
+            this.emit('error', item, error instanceof Error ? error : new Error(String(error)));
+        }
+        finally {
+            this.inFlight = null;
+        }
+    }
+    /**
+     * Get current state
+     */
+    getState() {
+        return {
+            isRunning: this.isRunning,
+            inFlight: this.inFlight,
+            lastPollAt: this.lastPollAt,
+            tasksProcessed: this.tasksProcessed,
+            errors: this.errors,
+        };
+    }
+    /**
+     * Check if poller is running
+     */
+    isActive() {
+        return this.isRunning;
+    }
+    /**
+     * Check if task is in-flight
+     */
+    hasInFlight() {
+        return this.inFlight !== null;
+    }
+    /**
+     * Get in-flight task
+     */
+    getInFlight() {
+        return this.inFlight;
+    }
+}
+exports.QueuePoller = QueuePoller;
+//# sourceMappingURL=queue-poller.js.map

package/dist/queue/queue-poller.js.map

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