@renseiai/agentfactory 0.8.7 → 0.8.9

package/dist/src/workflow/gates/signal-gate.js

@@ -0,0 +1,216 @@
+/**
+ * Signal Gate Executor
+ *
+ * Evaluates whether comments or directives satisfy a signal gate.
+ * Signal gates pause workflow execution until a matching comment or
+ * directive is detected. This module is backward compatible with
+ * existing HOLD/RESUME directives from the override-parser system.
+ *
+ * All evaluator functions are pure (no I/O) — they take inputs and
+ * return results without side effects.
+ */
+const log = {
+    info: (msg, data) => console.log(`[signal-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[signal-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[signal-gate] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// ============================================
+// Type Guards
+// ============================================
+/**
+ * Type guard to validate that a trigger object has the correct shape
+ * for a signal gate trigger.
+ *
+ * A valid SignalGateTrigger must have:
+ * - `source`: either 'comment' or 'directive'
+ * - `match`: a non-empty string
+ *
+ * @param trigger - The trigger record to validate
+ * @returns True if the trigger is a valid SignalGateTrigger
+ */
+export function isSignalGateTrigger(trigger) {
+    if (typeof trigger.source !== 'string')
+        return false;
+    if (trigger.source !== 'comment' && trigger.source !== 'directive')
+        return false;
+    if (typeof trigger.match !== 'string')
+        return false;
+    if (trigger.match.length === 0)
+        return false;
+    return true;
+}
+// ============================================
+// Signal Gate Evaluator
+// ============================================
+/**
+ * Extract the first non-empty line from a comment body.
+ * Mirrors the directive extraction logic in override-parser.ts.
+ *
+ * @param body - The full comment body text
+ * @returns The trimmed first non-empty line, or empty string if none
+ */
+function extractDirectiveLine(body) {
+    const lines = body.split('\n');
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0) {
+            return trimmed;
+        }
+    }
+    return '';
+}
+/**
+ * Evaluate whether a comment satisfies a signal gate trigger.
+ *
+ * This is a pure function (no I/O) that checks if a comment matches
+ * the signal gate's trigger configuration.
+ *
+ * Matching rules:
+ * - Bot comments are always skipped (returns { matched: false })
+ * - When `trigger.source` is 'directive', only the first non-empty line
+ *   of the comment is checked (consistent with override-parser.ts)
+ * - When `trigger.source` is 'comment', the full trimmed comment text is checked
+ * - The `trigger.match` string is first tried as an exact case-insensitive match,
+ *   then as a regex pattern (case-insensitive)
+ *
+ * @param gate - The gate definition containing a signal trigger
+ * @param comment - The full comment body text
+ * @param isBot - Whether the comment was authored by a bot
+ * @returns A SignalGateResult indicating whether the comment matched
+ */
+export function evaluateSignalGate(gate, comment, isBot) {
+    // Bot comments are always ignored
+    if (isBot) {
+        log.debug('Skipping bot comment for signal gate', { gateName: gate.name });
+        return { matched: false };
+    }
+    // Validate trigger shape
+    if (!isSignalGateTrigger(gate.trigger)) {
+        log.warn('Gate has invalid signal trigger configuration', { gateName: gate.name, trigger: gate.trigger });
+        return { matched: false };
+    }
+    const trigger = gate.trigger;
+    // Determine the text to match against based on trigger source
+    let textToMatch;
+    if (trigger.source === 'directive') {
+        textToMatch = extractDirectiveLine(comment);
+    }
+    else {
+        textToMatch = comment.trim();
+    }
+    // Empty text cannot match
+    if (textToMatch.length === 0) {
+        return { matched: false };
+    }
+    // Try exact case-insensitive match first
+    if (textToMatch.toLowerCase() === trigger.match.toLowerCase()) {
+        log.debug('Signal gate matched (exact)', { gateName: gate.name, source: textToMatch });
+        return { matched: true, source: textToMatch };
+    }
+    // Try regex match (case-insensitive)
+    try {
+        const regex = new RegExp(trigger.match, 'i');
+        const match = textToMatch.match(regex);
+        if (match) {
+            log.debug('Signal gate matched (regex)', { gateName: gate.name, source: textToMatch });
+            return { matched: true, source: textToMatch };
+        }
+    }
+    catch {
+        // Invalid regex pattern — treat as exact match only (already tried above)
+        log.warn('Invalid regex in signal gate trigger match', { gateName: gate.name, match: trigger.match });
+    }
+    return { matched: false };
+}
+// ============================================
+// Workflow Query Helpers
+// ============================================
+/**
+ * Get all signal gates from a workflow definition that apply to a given phase.
+ *
+ * Filters gates by:
+ * 1. `type === 'signal'`
+ * 2. `appliesTo` includes the given phase name, OR `appliesTo` is not defined
+ *    (gate applies to all phases)
+ *
+ * @param workflow - The workflow definition containing gate configurations
+ * @param phase - The phase name to filter by
+ * @returns Array of GateDefinition objects that are signal gates applicable to the phase
+ */
+export function getApplicableSignalGates(workflow, phase) {
+    if (!workflow.gates || workflow.gates.length === 0) {
+        return [];
+    }
+    return workflow.gates.filter((gate) => {
+        // Must be a signal gate
+        if (gate.type !== 'signal')
+            return false;
+        // If appliesTo is defined, the phase must be in the list
+        if (gate.appliesTo && gate.appliesTo.length > 0) {
+            return gate.appliesTo.includes(phase);
+        }
+        // No appliesTo restriction — applies to all phases
+        return true;
+    });
+}
+// ============================================
+// HOLD/RESUME Backward Compatibility
+// ============================================
+/**
+ * Name used for the implicit HOLD gate created for backward compatibility
+ */
+export const IMPLICIT_HOLD_GATE_NAME = '__implicit-hold';
+/**
+ * Name used for the implicit RESUME gate created for backward compatibility
+ */
+export const IMPLICIT_RESUME_GATE_NAME = '__implicit-resume';
+/**
+ * Create an implicit signal gate definition that matches the HOLD directive.
+ *
+ * This provides backward compatibility with the existing HOLD/RESUME system.
+ * When a HOLD directive is detected and no explicit signal gate is defined,
+ * this creates a gate that will pause the workflow until a RESUME directive
+ * is received.
+ *
+ * The created gate matches:
+ * - Directive source: first line of comment
+ * - Pattern: `^hold(?:\s*[---]\s*(.+))?$` (matches HOLD or HOLD -- reason)
+ *
+ * @returns A GateDefinition representing the implicit HOLD gate
+ */
+export function createImplicitHoldGate() {
+    return {
+        name: IMPLICIT_HOLD_GATE_NAME,
+        description: 'Implicit gate created for backward-compatible HOLD directive',
+        type: 'signal',
+        trigger: {
+            source: 'directive',
+            match: '^hold(?:\\s*[\\u2014\\u2013-]\\s*(.+))?$',
+        },
+    };
+}
+/**
+ * Create an implicit signal gate definition that matches the RESUME directive.
+ *
+ * This is the counterpart to the implicit HOLD gate. When a workflow is
+ * paused by a HOLD directive, this gate defines the condition that will
+ * release the hold — receiving a RESUME directive.
+ *
+ * The created gate matches:
+ * - Directive source: first line of comment
+ * - Pattern: `^resume$` (exact match for RESUME directive)
+ *
+ * @returns A GateDefinition representing the implicit RESUME gate
+ */
+export function createImplicitResumeGate() {
+    return {
+        name: IMPLICIT_RESUME_GATE_NAME,
+        description: 'Implicit gate created for backward-compatible RESUME directive',
+        type: 'signal',
+        trigger: {
+            source: 'directive',
+            match: '^resume$',
+        },
+    };
+}

package/dist/src/workflow/gates/signal-gate.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=signal-gate.test.d.ts.map

package/dist/src/workflow/gates/signal-gate.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signal-gate.test.d.ts","sourceRoot":"","sources":["../../../../src/workflow/gates/signal-gate.test.ts"],"names":[],"mappings":""}

package/dist/src/workflow/gates/signal-gate.test.js

@@ -0,0 +1,199 @@
+import { describe, it, expect } from 'vitest';
+import { evaluateSignalGate, isSignalGateTrigger, getApplicableSignalGates, createImplicitHoldGate, createImplicitResumeGate, IMPLICIT_HOLD_GATE_NAME, IMPLICIT_RESUME_GATE_NAME, } from './signal-gate.js';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makeGateDefinition(overrides = {}) {
+    return {
+        name: 'test-gate',
+        type: 'signal',
+        trigger: { source: 'comment', match: 'APPROVE' },
+        ...overrides,
+    };
+}
+function makeWorkflow(gates = []) {
+    return {
+        apiVersion: 'v1.1',
+        kind: 'WorkflowDefinition',
+        metadata: { name: 'test-workflow' },
+        phases: [{ name: 'development', template: 'dev' }],
+        transitions: [{ from: 'Backlog', to: 'development' }],
+        gates,
+    };
+}
+// ---------------------------------------------------------------------------
+// evaluateSignalGate
+// ---------------------------------------------------------------------------
+describe('evaluateSignalGate', () => {
+    it('matches exact comment text (case-insensitive)', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, 'approve', false);
+        expect(result.matched).toBe(true);
+        expect(result.source).toBe('approve');
+    });
+    it('matches exact comment text (exact case)', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, 'APPROVE', false);
+        expect(result.matched).toBe(true);
+        expect(result.source).toBe('APPROVE');
+    });
+    it('matches regex pattern', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: '^LGTM.*$' } });
+        const result = evaluateSignalGate(gate, 'LGTM looks good', false);
+        expect(result.matched).toBe(true);
+        expect(result.source).toBe('LGTM looks good');
+    });
+    it('handles directive-only mode (first non-empty line)', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'directive', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, 'APPROVE\nsome other text', false);
+        expect(result.matched).toBe(true);
+        expect(result.source).toBe('APPROVE');
+    });
+    it('skips bot comments', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, 'APPROVE', true);
+        expect(result.matched).toBe(false);
+    });
+    it('handles invalid regex gracefully (falls back to exact match only)', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: '[invalid(' } });
+        const result = evaluateSignalGate(gate, 'something else', false);
+        expect(result.matched).toBe(false);
+    });
+    it('is case-insensitive for regex matching', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: '^approve$' } });
+        const result = evaluateSignalGate(gate, 'APPROVE', false);
+        expect(result.matched).toBe(true);
+    });
+    it('returns not matched for empty comment with directive source', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'directive', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, '', false);
+        expect(result.matched).toBe(false);
+    });
+    it('returns not matched for non-matching comment', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, 'I reject this', false);
+        expect(result.matched).toBe(false);
+    });
+    it('returns not matched for invalid trigger configuration', () => {
+        const gate = makeGateDefinition({ trigger: { invalid: true } });
+        const result = evaluateSignalGate(gate, 'APPROVE', false);
+        expect(result.matched).toBe(false);
+    });
+    it('trims whitespace from comment when source is comment', () => {
+        const gate = makeGateDefinition({ trigger: { source: 'comment', match: 'APPROVE' } });
+        const result = evaluateSignalGate(gate, '  APPROVE  ', false);
+        expect(result.matched).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// isSignalGateTrigger
+// ---------------------------------------------------------------------------
+describe('isSignalGateTrigger', () => {
+    it('returns true for valid signal trigger', () => {
+        expect(isSignalGateTrigger({ source: 'comment', match: 'APPROVE' })).toBe(true);
+    });
+    it('returns true for directive source', () => {
+        expect(isSignalGateTrigger({ source: 'directive', match: 'HOLD' })).toBe(true);
+    });
+    it('returns false for missing source', () => {
+        expect(isSignalGateTrigger({ match: 'APPROVE' })).toBe(false);
+    });
+    it('returns false for invalid source type', () => {
+        expect(isSignalGateTrigger({ source: 'webhook', match: 'APPROVE' })).toBe(false);
+    });
+    it('returns false for missing match', () => {
+        expect(isSignalGateTrigger({ source: 'comment' })).toBe(false);
+    });
+    it('returns false for empty match', () => {
+        expect(isSignalGateTrigger({ source: 'comment', match: '' })).toBe(false);
+    });
+});
+// ---------------------------------------------------------------------------
+// getApplicableSignalGates
+// ---------------------------------------------------------------------------
+describe('getApplicableSignalGates', () => {
+    it('filters by type=signal and appliesTo', () => {
+        const gates = [
+            makeGateDefinition({ name: 'signal-1', type: 'signal', appliesTo: ['development'] }),
+            makeGateDefinition({ name: 'timer-1', type: 'timer', appliesTo: ['development'] }),
+            makeGateDefinition({ name: 'signal-2', type: 'signal', appliesTo: ['qa'] }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableSignalGates(workflow, 'development');
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe('signal-1');
+    });
+    it('handles no gates', () => {
+        const workflow = makeWorkflow([]);
+        const result = getApplicableSignalGates(workflow, 'development');
+        expect(result).toEqual([]);
+    });
+    it('handles undefined gates', () => {
+        const workflow = makeWorkflow();
+        delete workflow.gates;
+        const result = getApplicableSignalGates(workflow, 'development');
+        expect(result).toEqual([]);
+    });
+    it('returns gates with no appliesTo (applies to all phases)', () => {
+        const gates = [
+            makeGateDefinition({ name: 'global-gate', type: 'signal' }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableSignalGates(workflow, 'any-phase');
+        expect(result).toHaveLength(1);
+        expect(result[0].name).toBe('global-gate');
+    });
+    it('returns gates with empty appliesTo array (applies to all phases)', () => {
+        const gates = [
+            makeGateDefinition({ name: 'global-gate', type: 'signal', appliesTo: [] }),
+        ];
+        const workflow = makeWorkflow(gates);
+        const result = getApplicableSignalGates(workflow, 'any-phase');
+        expect(result).toHaveLength(1);
+    });
+});
+// ---------------------------------------------------------------------------
+// createImplicitHoldGate
+// ---------------------------------------------------------------------------
+describe('createImplicitHoldGate', () => {
+    it('creates a gate matching HOLD directive', () => {
+        const gate = createImplicitHoldGate();
+        expect(gate.name).toBe(IMPLICIT_HOLD_GATE_NAME);
+        expect(gate.type).toBe('signal');
+        // Should match "HOLD"
+        const result = evaluateSignalGate(gate, 'HOLD', false);
+        expect(result.matched).toBe(true);
+    });
+    it('matches HOLD with reason (HOLD -- reason)', () => {
+        const gate = createImplicitHoldGate();
+        const result = evaluateSignalGate(gate, 'HOLD -- waiting for design review', false);
+        expect(result.matched).toBe(true);
+    });
+    it('matches HOLD with em-dash', () => {
+        const gate = createImplicitHoldGate();
+        const result = evaluateSignalGate(gate, 'HOLD \u2014 some reason', false);
+        expect(result.matched).toBe(true);
+    });
+});
+// ---------------------------------------------------------------------------
+// createImplicitResumeGate
+// ---------------------------------------------------------------------------
+describe('createImplicitResumeGate', () => {
+    it('creates a gate matching RESUME directive', () => {
+        const gate = createImplicitResumeGate();
+        expect(gate.name).toBe(IMPLICIT_RESUME_GATE_NAME);
+        expect(gate.type).toBe('signal');
+        const result = evaluateSignalGate(gate, 'RESUME', false);
+        expect(result.matched).toBe(true);
+    });
+    it('matches case-insensitively', () => {
+        const gate = createImplicitResumeGate();
+        const result = evaluateSignalGate(gate, 'resume', false);
+        expect(result.matched).toBe(true);
+    });
+    it('does not match RESUME with extra text', () => {
+        const gate = createImplicitResumeGate();
+        const result = evaluateSignalGate(gate, 'RESUME now please', false);
+        expect(result.matched).toBe(false);
+    });
+});

package/dist/src/workflow/gates/timeout-engine.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Gate Timeout Engine
+ *
+ * Cross-cutting timeout engine that monitors active gates and determines
+ * what action to take when deadlines expire. Every gate type (signal, timer,
+ * webhook) can have an optional timeout with an action of 'escalate', 'skip',
+ * or 'fail'. This engine is the shared component that checks deadlines and
+ * returns the action to take.
+ *
+ * The main entry point is `processGateTimeouts()`, which is called by the
+ * governor on each poll cycle. The lower-level functions (`checkGateTimeout`,
+ * `checkAllGateTimeouts`, `resolveTimeoutAction`) are pure and exported for
+ * direct use and testability.
+ */
+import type { GateState, GateStorage } from '../gate-state.js';
+/**
+ * Result of checking a single gate for timeout.
+ * If `timedOut` is false, no action field is present.
+ * If `timedOut` is true, `action` indicates what should happen.
+ */
+export interface TimeoutCheckResult {
+    timedOut: boolean;
+    action?: 'escalate' | 'skip' | 'fail';
+}
+/**
+ * A gate that has been determined to have timed out, paired with
+ * the action that should be taken.
+ */
+export interface TimedOutGate {
+    gateState: GateState;
+    action: 'escalate' | 'skip' | 'fail';
+}
+/**
+ * The resolution produced for a timed-out gate, containing all the
+ * information the governor needs to act on the timeout.
+ */
+export interface TimeoutResolution {
+    type: 'escalate' | 'skip' | 'fail';
+    issueId: string;
+    gateName: string;
+    reason: string;
+}
+/**
+ * Check whether a single gate has timed out.
+ *
+ * Pure function that compares the current time against the gate's
+ * `timeoutDeadline`. Returns `{ timedOut: false }` if no deadline
+ * exists or the deadline has not yet passed.
+ *
+ * @param gateState - The gate state to check
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns The timeout check result
+ */
+export declare function checkGateTimeout(gateState: GateState, now?: number): TimeoutCheckResult;
+/**
+ * Check multiple gates for timeouts.
+ *
+ * Pure function that filters a list of gate states down to only those
+ * that have timed out, returning each with its configured timeout action.
+ *
+ * @param gates - Array of gate states to check
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns Array of gates that have timed out, with their actions
+ */
+export declare function checkAllGateTimeouts(gates: GateState[], now?: number): TimedOutGate[];
+/**
+ * Determine the resolution for a timeout action.
+ *
+ * Pure function that maps a timeout action to a structured resolution
+ * containing the action type, issue context, and a human-readable reason.
+ *
+ * - `escalate` - The governor should advance the escalation strategy
+ * - `skip` - The governor should skip the gate and continue the workflow
+ * - `fail` - The governor should fail the workflow
+ *
+ * @param action - The timeout action to resolve
+ * @param issueId - The issue identifier associated with the gate
+ * @param gateName - The name of the gate that timed out
+ * @returns The structured timeout resolution
+ */
+export declare function resolveTimeoutAction(action: 'escalate' | 'skip' | 'fail', issueId: string, gateName: string): TimeoutResolution;
+/**
+ * Process gate timeouts for a set of active gates.
+ *
+ * This is the main entry point called by the governor on each poll cycle.
+ * It checks all provided gates for timeouts, marks timed-out gates via
+ * the storage adapter (using `timeoutGate()` from gate-state.ts), and
+ * returns an array of timeout resolutions for the caller to act on.
+ *
+ * @param activeGates - Array of currently active gate states to check
+ * @param storage - The gate storage adapter for persisting state changes
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns Array of timeout resolutions for the governor to process
+ */
+export declare function processGateTimeouts(activeGates: GateState[], storage: GateStorage, now?: number): Promise<TimeoutResolution[]>;
+//# sourceMappingURL=timeout-engine.d.ts.map

package/dist/src/workflow/gates/timeout-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout-engine.d.ts","sourceRoot":"","sources":["../../../../src/workflow/gates/timeout-engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAqB9D;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,OAAO,CAAA;IACjB,MAAM,CAAC,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;CACtC;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,SAAS,CAAA;IACpB,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;IAClC,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAA;CACf;AAMD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,kBAAkB,CAkBvF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,YAAY,EAAE,CAYrF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,UAAU,GAAG,MAAM,GAAG,MAAM,EACpC,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,MAAM,GACf,iBAAiB,CAwBnB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,SAAS,EAAE,EACxB,OAAO,EAAE,WAAW,EACpB,GAAG,CAAC,EAAE,MAAM,GACX,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAsC9B"}

package/dist/src/workflow/gates/timeout-engine.js

@@ -0,0 +1,162 @@
+/**
+ * Gate Timeout Engine
+ *
+ * Cross-cutting timeout engine that monitors active gates and determines
+ * what action to take when deadlines expire. Every gate type (signal, timer,
+ * webhook) can have an optional timeout with an action of 'escalate', 'skip',
+ * or 'fail'. This engine is the shared component that checks deadlines and
+ * returns the action to take.
+ *
+ * The main entry point is `processGateTimeouts()`, which is called by the
+ * governor on each poll cycle. The lower-level functions (`checkGateTimeout`,
+ * `checkAllGateTimeouts`, `resolveTimeoutAction`) are pure and exported for
+ * direct use and testability.
+ */
+import { timeoutGate } from '../gate-state.js';
+// ============================================
+// Logger
+// ============================================
+const log = {
+    info: (msg, data) => console.log(`[timeout-engine] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[timeout-engine] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[timeout-engine] ${msg}`, data ? JSON.stringify(data) : ''),
+    debug: (_msg, _data) => { },
+};
+// ============================================
+// Pure Functions
+// ============================================
+/**
+ * Check whether a single gate has timed out.
+ *
+ * Pure function that compares the current time against the gate's
+ * `timeoutDeadline`. Returns `{ timedOut: false }` if no deadline
+ * exists or the deadline has not yet passed.
+ *
+ * @param gateState - The gate state to check
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns The timeout check result
+ */
+export function checkGateTimeout(gateState, now) {
+    const currentTime = now ?? Date.now();
+    // No deadline configured — cannot time out
+    if (gateState.timeoutDeadline == null) {
+        return { timedOut: false };
+    }
+    // Deadline has not passed yet
+    if (currentTime < gateState.timeoutDeadline) {
+        return { timedOut: false };
+    }
+    // Deadline has expired — return the configured action (default to 'fail')
+    return {
+        timedOut: true,
+        action: gateState.timeoutAction ?? 'fail',
+    };
+}
+/**
+ * Check multiple gates for timeouts.
+ *
+ * Pure function that filters a list of gate states down to only those
+ * that have timed out, returning each with its configured timeout action.
+ *
+ * @param gates - Array of gate states to check
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns Array of gates that have timed out, with their actions
+ */
+export function checkAllGateTimeouts(gates, now) {
+    const currentTime = now ?? Date.now();
+    const timedOut = [];
+    for (const gateState of gates) {
+        const result = checkGateTimeout(gateState, currentTime);
+        if (result.timedOut && result.action) {
+            timedOut.push({ gateState, action: result.action });
+        }
+    }
+    return timedOut;
+}
+/**
+ * Determine the resolution for a timeout action.
+ *
+ * Pure function that maps a timeout action to a structured resolution
+ * containing the action type, issue context, and a human-readable reason.
+ *
+ * - `escalate` - The governor should advance the escalation strategy
+ * - `skip` - The governor should skip the gate and continue the workflow
+ * - `fail` - The governor should fail the workflow
+ *
+ * @param action - The timeout action to resolve
+ * @param issueId - The issue identifier associated with the gate
+ * @param gateName - The name of the gate that timed out
+ * @returns The structured timeout resolution
+ */
+export function resolveTimeoutAction(action, issueId, gateName) {
+    switch (action) {
+        case 'escalate':
+            return {
+                type: 'escalate',
+                issueId,
+                gateName,
+                reason: `Gate ${gateName} timed out — escalating`,
+            };
+        case 'skip':
+            return {
+                type: 'skip',
+                issueId,
+                gateName,
+                reason: `Gate ${gateName} timed out — skipping gate`,
+            };
+        case 'fail':
+            return {
+                type: 'fail',
+                issueId,
+                gateName,
+                reason: `Gate ${gateName} timed out — failing workflow`,
+            };
+    }
+}
+// ============================================
+// I/O Function
+// ============================================
+/**
+ * Process gate timeouts for a set of active gates.
+ *
+ * This is the main entry point called by the governor on each poll cycle.
+ * It checks all provided gates for timeouts, marks timed-out gates via
+ * the storage adapter (using `timeoutGate()` from gate-state.ts), and
+ * returns an array of timeout resolutions for the caller to act on.
+ *
+ * @param activeGates - Array of currently active gate states to check
+ * @param storage - The gate storage adapter for persisting state changes
+ * @param now - Current time in epoch ms (defaults to Date.now() for testability)
+ * @returns Array of timeout resolutions for the governor to process
+ */
+export async function processGateTimeouts(activeGates, storage, now) {
+    const timedOutGates = checkAllGateTimeouts(activeGates, now);
+    if (timedOutGates.length === 0) {
+        return [];
+    }
+    log.info('Processing gate timeouts', {
+        count: timedOutGates.length,
+        gates: timedOutGates.map(g => g.gateState.gateName),
+    });
+    const resolutions = [];
+    for (const { gateState, action } of timedOutGates) {
+        // Mark the gate as timed-out in storage
+        const updated = await timeoutGate(gateState.issueId, gateState.gateName, storage);
+        if (!updated) {
+            log.warn('Failed to mark gate as timed-out (gate not found or not active)', {
+                issueId: gateState.issueId,
+                gateName: gateState.gateName,
+            });
+            continue;
+        }
+        const resolution = resolveTimeoutAction(action, gateState.issueId, gateState.gateName);
+        resolutions.push(resolution);
+        log.info('Gate timeout resolved', {
+            issueId: gateState.issueId,
+            gateName: gateState.gateName,
+            action,
+            reason: resolution.reason,
+        });
+    }
+    return resolutions;
+}