@supaku/agentfactory-cli 0.7.10 → 0.7.12

package/README.md

@@ -24,6 +24,15 @@ af-orchestrator --single PROJ-123
 # Dry run — preview what would be processed
 af-orchestrator --project MyProject --dry-run
 
+# Start the Workflow Governor (event-driven + poll sweep)
+af-governor --project MyProject --project OtherProject
+
+# Governor: single scan and exit (for cron jobs)
+af-governor --project MyProject --once
+
+# Governor: poll-only mode (no event bus)
+af-governor --project MyProject --mode poll-only
+
 # Start a remote worker
 af-worker --api-url https://your-app.vercel.app --api-key your-key
 
@@ -41,6 +50,30 @@ af-queue-admin drain
 af-analyze-logs --follow
 ```
 
+### Governor
+
+The Workflow Governor scans projects and decides what work to dispatch based on issue status, active sessions, cooldowns, and human overrides.
+
+**Modes:**
+- `event-driven` (default) — Listens to a GovernorEventBus for real-time webhook events, with a periodic poll sweep as safety net
+- `poll-only` — Periodic scan loop only
+
+**Options:**
+```
+--project <name>            Project to scan (repeatable)
+--scan-interval <ms>        Poll interval (default: 60000 for poll-only, 300000 for event-driven)
+--max-dispatches <n>        Max concurrent dispatches per scan (default: 3)
+--mode <mode>               poll-only or event-driven (default: event-driven)
+--once                      Single scan pass and exit
+--no-auto-research          Disable Icebox → research
+--no-auto-backlog-creation  Disable Icebox → backlog-creation
+--no-auto-development       Disable Backlog → development
+--no-auto-qa                Disable Finished → QA
+--no-auto-acceptance        Disable Delivered → acceptance
+```
+
+When `LINEAR_API_KEY` and `REDIS_URL` are set, the governor uses real dependencies (Linear SDK + Redis). Without them, it falls back to stub dependencies for testing.
+
 ## Programmatic Usage
 
 All CLI tools are available as importable functions via subpath exports:
@@ -72,10 +105,10 @@ Each function accepts a config object and returns a Promise — use them to buil
 
 | Variable | Used By | Description |
 |----------|---------|-------------|
-| `LINEAR_API_KEY` | orchestrator | Linear API key |
+| `LINEAR_API_KEY` | orchestrator, governor | Linear API key |
+| `REDIS_URL` | governor, queue-admin | Redis connection URL |
 | `WORKER_API_URL` | worker, fleet | Webhook server URL |
 | `WORKER_API_KEY` | worker, fleet | API key for authentication |
-| `REDIS_URL` | queue-admin | Redis connection URL |
 
 ## Related Packages
 

package/dist/src/governor.js

@@ -26,6 +26,10 @@ import { config } from 'dotenv';
 // Load environment variables from .env.local
 config({ path: path.resolve(process.cwd(), '.env.local') });
 import { parseGovernorArgs, runGovernor, } from './lib/governor-runner.js';
+import { createRealDependencies } from './lib/governor-dependencies.js';
+import { createLinearAgentClient } from '@supaku/agentfactory-linear';
+import { initTouchpointStorage } from '@supaku/agentfactory';
+import { RedisOverrideStorage } from '@supaku/agentfactory-server';
 // ---------------------------------------------------------------------------
 // Stub dependencies
 // ---------------------------------------------------------------------------
@@ -73,8 +77,32 @@ async function main() {
     console.log(`Projects: ${args.projects.join(', ')}`);
     console.log(`Scan interval: ${args.scanIntervalMs}ms`);
     console.log(`Max dispatches per scan: ${args.maxConcurrentDispatches}`);
+    console.log(`Execution mode: ${args.mode}`);
     console.log(`Mode: ${args.once ? 'single scan' : 'continuous'}`);
     console.log('');
+    // -----------------------------------------------------------------------
+    // Choose real or stub dependencies based on environment
+    // -----------------------------------------------------------------------
+    let dependencies;
+    const linearApiKey = process.env.LINEAR_API_KEY;
+    const redisUrl = process.env.REDIS_URL;
+    if (linearApiKey) {
+        console.log('LINEAR_API_KEY detected — using real dependencies');
+        const linearClient = createLinearAgentClient({ apiKey: linearApiKey });
+        // Initialize touchpoint storage (for isHeld / getOverridePriority) when Redis is available
+        if (redisUrl) {
+            console.log('REDIS_URL detected — initializing Redis-backed touchpoint storage');
+            initTouchpointStorage(new RedisOverrideStorage());
+        }
+        else {
+            console.warn('Warning: REDIS_URL not set — touchpoint overrides (HOLD, PRIORITY) will not persist');
+        }
+        dependencies = createRealDependencies({ linearClient });
+    }
+    else {
+        console.warn('Warning: LINEAR_API_KEY not set — using stub dependencies (no real work will be dispatched)');
+        dependencies = createStubDependencies();
+    }
     const runnerConfig = {
         projects: args.projects,
         scanIntervalMs: args.scanIntervalMs,
@@ -85,7 +113,8 @@ async function main() {
         enableAutoQA: args.enableAutoQA,
         enableAutoAcceptance: args.enableAutoAcceptance,
         once: args.once,
-        dependencies: createStubDependencies(),
+        mode: args.mode,
+        dependencies,
         callbacks: {
             onScanComplete: (results) => {
                 for (const result of results) {

package/dist/src/lib/governor-dependencies.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Real Governor Dependencies
+ *
+ * Maps each GovernorDependencies callback to its real implementation
+ * using the Linear SDK (via LinearAgentClient) and Redis storage
+ * (from @supaku/agentfactory-server).
+ */
+import type { LinearAgentClient } from '@supaku/agentfactory-linear';
+import type { GovernorDependencies } from '@supaku/agentfactory';
+export interface RealDependenciesConfig {
+    linearClient: LinearAgentClient;
+}
+/**
+ * Create real GovernorDependencies backed by the Linear SDK and Redis.
+ *
+ * Each callback wraps its implementation in a try/catch so that a single
+ * failing dependency does not crash the entire governor scan loop.
+ */
+export declare function createRealDependencies(config: RealDependenciesConfig): GovernorDependencies;
+//# sourceMappingURL=governor-dependencies.d.ts.map

package/dist/src/lib/governor-dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"governor-dependencies.d.ts","sourceRoot":"","sources":["../../../src/lib/governor-dependencies.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AACpE,OAAO,KAAK,EACV,oBAAoB,EAGrB,MAAM,sBAAsB,CAAA;AAgC7B,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,iBAAiB,CAAA;CAChC;AAmFD;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,sBAAsB,GAC7B,oBAAoB,CAsPtB"}

package/dist/src/lib/governor-dependencies.js

@@ -0,0 +1,327 @@
+/**
+ * Real Governor Dependencies
+ *
+ * Maps each GovernorDependencies callback to its real implementation
+ * using the Linear SDK (via LinearAgentClient) and Redis storage
+ * (from @supaku/agentfactory-server).
+ */
+import { isHeld as checkIsHeld, getOverridePriority as checkOverridePriority, } from '@supaku/agentfactory';
+import { getSessionStateByIssue, didJustFailQA, getWorkflowState, RedisProcessingStateStorage, queueWork, storeSessionState, } from '@supaku/agentfactory-server';
+// ---------------------------------------------------------------------------
+// Logging
+// ---------------------------------------------------------------------------
+const log = {
+    info: (msg, data) => console.log(`[governor-deps] ${msg}`, data ? JSON.stringify(data) : ''),
+    warn: (msg, data) => console.warn(`[governor-deps] ${msg}`, data ? JSON.stringify(data) : ''),
+    error: (msg, data) => console.error(`[governor-deps] ${msg}`, data ? JSON.stringify(data) : ''),
+};
+// ---------------------------------------------------------------------------
+// Action-to-WorkType mapping
+// ---------------------------------------------------------------------------
+function actionToWorkType(action) {
+    switch (action) {
+        case 'trigger-research':
+            return 'research';
+        case 'trigger-backlog-creation':
+            return 'backlog-creation';
+        case 'trigger-development':
+            return 'development';
+        case 'trigger-qa':
+            return 'qa';
+        case 'trigger-acceptance':
+            return 'acceptance';
+        case 'trigger-refinement':
+            return 'refinement';
+        case 'decompose':
+            return 'coordination';
+        case 'escalate-human':
+            return 'escalation';
+        default:
+            return 'development';
+    }
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// Terminal statuses (issues in these states are excluded from scans)
+// ---------------------------------------------------------------------------
+const TERMINAL_STATUSES = ['Accepted', 'Canceled', 'Duplicate'];
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Convert a Linear SDK Issue to a GovernorIssue.
+ * Resolves lazy-loaded relations (state, labels, parent, project).
+ *
+ * Uses `unknown` + explicit casts to avoid importing `Issue` from
+ * `@linear/sdk`, keeping the CLI package dependency graph clean.
+ */
+async function sdkIssueToGovernorIssue(issue) {
+    // The Linear SDK Issue type uses LinearFetch (thenable) for lazy-loaded relations.
+    // We cast to `any` to access these properties without importing the SDK types.
+    const i = issue;
+    const state = await i.state;
+    const labels = await i.labels();
+    const parent = await i.parent;
+    const project = await i.project;
+    return {
+        id: i.id,
+        identifier: i.identifier,
+        title: i.title,
+        description: i.description ?? undefined,
+        status: state?.name ?? 'Backlog',
+        labels: labels.nodes.map((l) => l.name),
+        createdAt: i.createdAt.getTime(),
+        parentId: parent?.id,
+        project: project?.name,
+    };
+}
+/**
+ * Create real GovernorDependencies backed by the Linear SDK and Redis.
+ *
+ * Each callback wraps its implementation in a try/catch so that a single
+ * failing dependency does not crash the entire governor scan loop.
+ */
+export function createRealDependencies(config) {
+    const processingState = new RedisProcessingStateStorage();
+    return {
+        // -----------------------------------------------------------------------
+        // 1. listIssues -- scan Linear project for non-terminal issues
+        // -----------------------------------------------------------------------
+        listIssues: async (project) => {
+            try {
+                const linearClient = config.linearClient.linearClient;
+                const issueConnection = await linearClient.issues({
+                    filter: {
+                        project: { name: { eq: project } },
+                        state: { name: { nin: [...TERMINAL_STATUSES] } },
+                    },
+                });
+                const results = [];
+                for (const issue of issueConnection.nodes) {
+                    results.push(await sdkIssueToGovernorIssue(issue));
+                }
+                return results;
+            }
+            catch (err) {
+                log.error('listIssues failed', {
+                    project,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return [];
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 2. hasActiveSession -- check Redis session storage
+        // -----------------------------------------------------------------------
+        hasActiveSession: async (issueId) => {
+            try {
+                const session = await getSessionStateByIssue(issueId);
+                if (!session)
+                    return false;
+                const activeStatuses = ['running', 'claimed', 'pending'];
+                return activeStatuses.includes(session.status);
+            }
+            catch (err) {
+                log.error('hasActiveSession failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 3. isWithinCooldown -- check if QA just failed for this issue
+        // -----------------------------------------------------------------------
+        isWithinCooldown: async (issueId) => {
+            try {
+                return await didJustFailQA(issueId);
+            }
+            catch (err) {
+                log.error('isWithinCooldown failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 4. isParentIssue -- check via Linear API
+        // -----------------------------------------------------------------------
+        isParentIssue: async (issueId) => {
+            try {
+                return await config.linearClient.isParentIssue(issueId);
+            }
+            catch (err) {
+                log.error('isParentIssue failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 5. isHeld -- check touchpoint override storage
+        // -----------------------------------------------------------------------
+        isHeld: async (issueId) => {
+            try {
+                return await checkIsHeld(issueId);
+            }
+            catch (err) {
+                log.error('isHeld failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 6. getOverridePriority -- check touchpoint override storage
+        // -----------------------------------------------------------------------
+        getOverridePriority: async (issueId) => {
+            try {
+                return await checkOverridePriority(issueId);
+            }
+            catch (err) {
+                log.error('getOverridePriority failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return null;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 7. getWorkflowStrategy -- check Redis workflow state
+        // -----------------------------------------------------------------------
+        getWorkflowStrategy: async (issueId) => {
+            try {
+                const workflowState = await getWorkflowState(issueId);
+                return workflowState?.strategy;
+            }
+            catch (err) {
+                log.error('getWorkflowStrategy failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return undefined;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 8. isResearchCompleted -- check Redis processing state
+        // -----------------------------------------------------------------------
+        isResearchCompleted: async (issueId) => {
+            try {
+                return await processingState.isPhaseCompleted(issueId, 'research');
+            }
+            catch (err) {
+                log.error('isResearchCompleted failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 9. isBacklogCreationCompleted -- check Redis processing state
+        // -----------------------------------------------------------------------
+        isBacklogCreationCompleted: async (issueId) => {
+            try {
+                return await processingState.isPhaseCompleted(issueId, 'backlog-creation');
+            }
+            catch (err) {
+                log.error('isBacklogCreationCompleted failed', {
+                    issueId,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                return false;
+            }
+        },
+        // -----------------------------------------------------------------------
+        // 10. dispatchWork -- create Linear session and queue work
+        // -----------------------------------------------------------------------
+        dispatchWork: async (issueId, action) => {
+            try {
+                const workType = actionToWorkType(action);
+                log.info('Dispatching work', { issueId, action, workType });
+                // Fetch the issue to get its identifier and project for the queue entry
+                let issueIdentifier = issueId;
+                let projectName;
+                try {
+                    const issue = await config.linearClient.getIssue(issueId);
+                    issueIdentifier = issue.identifier;
+                    const project = await issue.project;
+                    projectName = project?.name;
+                }
+                catch {
+                    log.warn('Could not fetch issue details, using issueId', { issueId });
+                }
+                // Create a Linear Agent Session on the issue so the UI shows activity
+                let sessionId;
+                try {
+                    const sessionResult = await config.linearClient.createAgentSessionOnIssue({
+                        issueId,
+                    });
+                    sessionId = sessionResult.sessionId;
+                }
+                catch (err) {
+                    log.warn('Could not create agent session, will queue without sessionId', {
+                        issueId,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+                const finalSessionId = sessionId ?? `governor-${issueId}-${Date.now()}`;
+                const now = Date.now();
+                // Register a pending session FIRST so hasActiveSession() returns true
+                // immediately, preventing re-dispatch on subsequent poll sweeps.
+                await storeSessionState(finalSessionId, {
+                    issueId,
+                    issueIdentifier,
+                    claudeSessionId: null,
+                    worktreePath: '',
+                    status: 'pending',
+                    workerId: null,
+                    queuedAt: now,
+                    priority: 3,
+                    workType: workType,
+                    projectName,
+                });
+                // Queue the work item for a worker to pick up
+                const queuedWork = {
+                    sessionId: finalSessionId,
+                    issueId,
+                    issueIdentifier,
+                    priority: 3,
+                    queuedAt: now,
+                    workType: workType,
+                    projectName,
+                };
+                const queued = await queueWork(queuedWork);
+                if (!queued) {
+                    log.warn('Failed to queue work (Redis may not be configured)', {
+                        issueId,
+                        action,
+                    });
+                }
+                else {
+                    log.info('Work queued successfully', {
+                        issueId,
+                        issueIdentifier,
+                        action,
+                        workType,
+                        projectName,
+                        sessionId: finalSessionId,
+                    });
+                }
+            }
+            catch (err) {
+                log.error('dispatchWork failed', {
+                    issueId,
+                    action,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+                throw err; // Re-throw so the governor can record the error
+            }
+        },
+    };
+}

package/dist/src/lib/governor-runner.d.ts

@@ -5,7 +5,7 @@
  * (e.g. Next.js route handlers, tests, or custom scripts) without going
  * through process.argv / process.env / process.exit.
  */
-import { WorkflowGovernor, type GovernorDependencies } from '@supaku/agentfactory';
+import { WorkflowGovernor, EventDrivenGovernor, type GovernorDependencies, type GovernorEventBus, type EventDeduplicator } from '@supaku/agentfactory';
 import type { ScanResult } from '@supaku/agentfactory';
 export interface GovernorRunnerConfig {
     /** Projects to scan */
@@ -14,9 +14,9 @@ export interface GovernorRunnerConfig {
     scanIntervalMs?: number;
     /** Maximum concurrent dispatches per scan (default: 3) */
     maxConcurrentDispatches?: number;
-    /** Enable auto-research from Icebox (default: true) */
+    /** Enable auto-research from Icebox (default: false) */
     enableAutoResearch?: boolean;
-    /** Enable auto-backlog-creation from Icebox (default: true) */
+    /** Enable auto-backlog-creation from Icebox (default: false) */
     enableAutoBacklogCreation?: boolean;
     /** Enable auto-development from Backlog (default: true) */
     enableAutoDevelopment?: boolean;
@@ -30,22 +30,34 @@ export interface GovernorRunnerConfig {
     dependencies: GovernorDependencies;
     /** Callbacks for governor lifecycle events */
     callbacks?: GovernorRunnerCallbacks;
+    /** Governor execution mode (default: 'poll-only') */
+    mode?: 'poll-only' | 'event-driven';
+    /** Event bus for event-driven mode (created automatically if not provided) */
+    eventBus?: GovernorEventBus;
+    /** Event deduplicator for event-driven mode (created automatically if not provided) */
+    deduplicator?: EventDeduplicator;
 }
 export interface GovernorRunnerCallbacks {
     onScanComplete?: (results: ScanResult[]) => void;
     onError?: (error: Error) => void;
 }
 export interface GovernorRunnerResult {
-    governor: WorkflowGovernor;
-    /** Only populated in --once mode */
+    governor: WorkflowGovernor | EventDrivenGovernor;
+    /** Only populated in --once mode (poll-only) */
     scanResults?: ScanResult[];
 }
 /**
  * Start the Workflow Governor with the given configuration.
  *
- * In `once` mode, runs a single scan pass and returns the results.
- * Otherwise, starts the scan loop and returns the governor instance
- * (caller is responsible for calling `governor.stop()` on shutdown).
+ * In `poll-only` mode (default):
+ *   - `once` mode: runs a single scan pass and returns the results.
+ *   - Otherwise: starts the scan loop and returns the governor instance
+ *     (caller is responsible for calling `governor.stop()` on shutdown).
+ *
+ * In `event-driven` mode:
+ *   - Creates an EventDrivenGovernor with an event bus and optional deduplicator.
+ *   - Starts the event loop and periodic poll sweep.
+ *   - `once` mode is not supported in event-driven mode (falls back to poll-only).
  */
 export declare function runGovernor(config: GovernorRunnerConfig): Promise<GovernorRunnerResult>;
 export interface GovernorCLIArgs {
@@ -58,6 +70,7 @@ export interface GovernorCLIArgs {
     enableAutoQA: boolean;
     enableAutoAcceptance: boolean;
     once: boolean;
+    mode: 'poll-only' | 'event-driven';
 }
 /**
  * Parse CLI arguments for the governor command.
@@ -69,8 +82,10 @@ export interface GovernorCLIArgs {
  *   --project <name>            Project to scan (can be repeated)
  *   --scan-interval <ms>        Scan interval in milliseconds (default: 60000)
  *   --max-dispatches <n>        Maximum concurrent dispatches per scan (default: 3)
- *   --no-auto-research          Disable auto-research from Icebox
- *   --no-auto-backlog-creation  Disable auto-backlog-creation from Icebox
+ *   --auto-research              Enable auto-research from Icebox (default: off)
+ *   --auto-backlog-creation      Enable auto-backlog-creation from Icebox (default: off)
+ *   --no-auto-research           Disable auto-research (explicit override)
+ *   --no-auto-backlog-creation   Disable auto-backlog-creation (explicit override)
  *   --no-auto-development       Disable auto-development from Backlog
  *   --no-auto-qa                Disable auto-QA from Finished
  *   --no-auto-acceptance        Disable auto-acceptance from Delivered

package/dist/src/lib/governor-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"governor-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/governor-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,gBAAgB,EAChB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAIV,UAAU,EACX,MAAM,sBAAsB,CAAA;AAM7B,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,uDAAuD;IACvD,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,+DAA+D;IAC/D,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,2DAA2D;IAC3D,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uDAAuD;IACvD,YAAY,EAAE,oBAAoB,CAAA;IAClC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,uBAAuB,CAAA;CACpC;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,CAAA;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,CAAA;IAC1B,oCAAoC;IACpC,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;CAC3B;AAMD;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAwB/B;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,kBAAkB,EAAE,OAAO,CAAA;IAC3B,yBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,YAAY,EAAE,OAAO,CAAA;IACrB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,eAAe,CAmDzF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CAmCxC"}
+{"version":3,"file":"governor-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/governor-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EACL,gBAAgB,EAChB,mBAAmB,EAGnB,KAAK,oBAAoB,EACzB,KAAK,gBAAgB,EACrB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,KAAK,EAIV,UAAU,EACX,MAAM,sBAAsB,CAAA;AAM7B,MAAM,WAAW,oBAAoB;IACnC,uBAAuB;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,qDAAqD;IACrD,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC,wDAAwD;IACxD,kBAAkB,CAAC,EAAE,OAAO,CAAA;IAC5B,gEAAgE;IAChE,yBAAyB,CAAC,EAAE,OAAO,CAAA;IACnC,2DAA2D;IAC3D,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,mDAAmD;IACnD,YAAY,CAAC,EAAE,OAAO,CAAA;IACtB,4DAA4D;IAC5D,oBAAoB,CAAC,EAAE,OAAO,CAAA;IAC9B,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,uDAAuD;IACvD,YAAY,EAAE,oBAAoB,CAAA;IAClC,8CAA8C;IAC9C,SAAS,CAAC,EAAE,uBAAuB,CAAA;IACnC,qDAAqD;IACrD,IAAI,CAAC,EAAE,WAAW,GAAG,cAAc,CAAA;IACnC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,gBAAgB,CAAA;IAC3B,uFAAuF;IACvF,YAAY,CAAC,EAAE,iBAAiB,CAAA;CACjC;AAED,MAAM,WAAW,uBAAuB;IACtC,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,KAAK,IAAI,CAAA;IAChD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;CACjC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,gBAAgB,GAAG,mBAAmB,CAAA;IAChD,gDAAgD;IAChD,WAAW,CAAC,EAAE,UAAU,EAAE,CAAA;CAC3B;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,oBAAoB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAuD/B;AAMD,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,cAAc,EAAE,MAAM,CAAA;IACtB,uBAAuB,EAAE,MAAM,CAAA;IAC/B,kBAAkB,EAAE,OAAO,CAAA;IAC3B,yBAAyB,EAAE,OAAO,CAAA;IAClC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,YAAY,EAAE,OAAO,CAAA;IACrB,oBAAoB,EAAE,OAAO,CAAA;IAC7B,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,WAAW,GAAG,cAAc,CAAA;CACnC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,GAAE,MAAM,EAA0B,GAAG,eAAe,CA6DzF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,IAAI,CA6CxC"}

package/dist/src/lib/governor-runner.js

@@ -5,16 +5,22 @@
  * (e.g. Next.js route handlers, tests, or custom scripts) without going
  * through process.argv / process.env / process.exit.
  */
-import { WorkflowGovernor, } from '@supaku/agentfactory';
+import { WorkflowGovernor, EventDrivenGovernor, InMemoryEventBus, InMemoryEventDeduplicator, } from '@supaku/agentfactory';
 // ---------------------------------------------------------------------------
 // Runner
 // ---------------------------------------------------------------------------
 /**
  * Start the Workflow Governor with the given configuration.
  *
- * In `once` mode, runs a single scan pass and returns the results.
- * Otherwise, starts the scan loop and returns the governor instance
- * (caller is responsible for calling `governor.stop()` on shutdown).
+ * In `poll-only` mode (default):
+ *   - `once` mode: runs a single scan pass and returns the results.
+ *   - Otherwise: starts the scan loop and returns the governor instance
+ *     (caller is responsible for calling `governor.stop()` on shutdown).
+ *
+ * In `event-driven` mode:
+ *   - Creates an EventDrivenGovernor with an event bus and optional deduplicator.
+ *   - Starts the event loop and periodic poll sweep.
+ *   - `once` mode is not supported in event-driven mode (falls back to poll-only).
  */
 export async function runGovernor(config) {
     const governorConfig = {
@@ -27,6 +33,30 @@ export async function runGovernor(config) {
         enableAutoQA: config.enableAutoQA,
         enableAutoAcceptance: config.enableAutoAcceptance,
     };
+    const mode = config.mode ?? 'poll-only';
+    // -- Event-driven mode --
+    if (mode === 'event-driven' && !config.once) {
+        const eventBus = config.eventBus ?? new InMemoryEventBus();
+        const deduplicator = config.deduplicator ?? new InMemoryEventDeduplicator();
+        const governor = new EventDrivenGovernor({
+            ...governorConfig,
+            // Spread required GovernorConfig defaults so TypeScript is happy
+            projects: config.projects,
+            scanIntervalMs: config.scanIntervalMs ?? 60_000,
+            maxConcurrentDispatches: config.maxConcurrentDispatches ?? 3,
+            enableAutoResearch: config.enableAutoResearch ?? false,
+            enableAutoBacklogCreation: config.enableAutoBacklogCreation ?? false,
+            enableAutoDevelopment: config.enableAutoDevelopment ?? true,
+            enableAutoQA: config.enableAutoQA ?? true,
+            enableAutoAcceptance: config.enableAutoAcceptance ?? true,
+            humanResponseTimeoutMs: 4 * 60 * 60 * 1000,
+            eventBus,
+            deduplicator,
+        }, config.dependencies);
+        await governor.start();
+        return { governor };
+    }
+    // -- Poll-only mode (default) --
     const governor = new WorkflowGovernor(governorConfig, config.dependencies);
     // -- Single scan mode (--once) --
     if (config.once) {
@@ -48,8 +78,10 @@ export async function runGovernor(config) {
  *   --project <name>            Project to scan (can be repeated)
  *   --scan-interval <ms>        Scan interval in milliseconds (default: 60000)
  *   --max-dispatches <n>        Maximum concurrent dispatches per scan (default: 3)
- *   --no-auto-research          Disable auto-research from Icebox
- *   --no-auto-backlog-creation  Disable auto-backlog-creation from Icebox
+ *   --auto-research              Enable auto-research from Icebox (default: off)
+ *   --auto-backlog-creation      Enable auto-backlog-creation from Icebox (default: off)
+ *   --no-auto-research           Disable auto-research (explicit override)
+ *   --no-auto-backlog-creation   Disable auto-backlog-creation (explicit override)
  *   --no-auto-development       Disable auto-development from Backlog
  *   --no-auto-qa                Disable auto-QA from Finished
  *   --no-auto-acceptance        Disable auto-acceptance from Delivered
@@ -61,12 +93,13 @@ export function parseGovernorArgs(argv = process.argv.slice(2)) {
         projects: [],
         scanIntervalMs: 60_000,
         maxConcurrentDispatches: 3,
-        enableAutoResearch: true,
-        enableAutoBacklogCreation: true,
+        enableAutoResearch: false,
+        enableAutoBacklogCreation: false,
         enableAutoDevelopment: true,
         enableAutoQA: true,
         enableAutoAcceptance: true,
         once: false,
+        mode: 'poll-only',
     };
     for (let i = 0; i < argv.length; i++) {
         const arg = argv[i];
@@ -80,9 +113,15 @@ export function parseGovernorArgs(argv = process.argv.slice(2)) {
             case '--max-dispatches':
                 result.maxConcurrentDispatches = parseInt(argv[++i], 10);
                 break;
+            case '--auto-research':
+                result.enableAutoResearch = true;
+                break;
             case '--no-auto-research':
                 result.enableAutoResearch = false;
                 break;
+            case '--auto-backlog-creation':
+                result.enableAutoBacklogCreation = true;
+                break;
             case '--no-auto-backlog-creation':
                 result.enableAutoBacklogCreation = false;
                 break;
@@ -98,6 +137,9 @@ export function parseGovernorArgs(argv = process.argv.slice(2)) {
             case '--once':
                 result.once = true;
                 break;
+            case '--mode':
+                result.mode = argv[++i];
+                break;
             case '--help':
             case '-h':
                 printGovernorHelp();
@@ -120,16 +162,23 @@ Options:
   --project <name>            Project to scan (can be repeated for multiple projects)
   --scan-interval <ms>        Scan interval in milliseconds (default: 60000)
   --max-dispatches <n>        Maximum concurrent dispatches per scan (default: 3)
-  --no-auto-research          Disable auto-research from Icebox
-  --no-auto-backlog-creation  Disable auto-backlog-creation from Icebox
+  --mode <mode>               Execution mode: poll-only (default) or event-driven
+  --auto-research             Enable auto-research from Icebox (default: off)
+  --auto-backlog-creation     Enable auto-backlog-creation from Icebox (default: off)
   --no-auto-development       Disable auto-development from Backlog
   --no-auto-qa                Disable auto-QA from Finished
   --no-auto-acceptance        Disable auto-acceptance from Delivered
   --once                      Run a single scan pass and exit
   --help, -h                  Show this help message
 
+Modes:
+  poll-only      Periodic scan loop using WorkflowGovernor (default)
+  event-driven   Hybrid event-driven + poll sweep using EventDrivenGovernor.
+                 Reacts to events in real time with a periodic safety-net poll.
+
 Environment:
   LINEAR_API_KEY              Required API key for Linear authentication
+  REDIS_URL                   Redis connection URL (required for real dependencies)
 
 Examples:
   # Start the governor for a project
@@ -143,5 +192,8 @@ Examples:
 
   # Disable auto-QA (only scan for development work)
   agentfactory governor --project MyProject --no-auto-qa --no-auto-acceptance
+
+  # Use event-driven mode
+  agentfactory governor --project MyProject --mode event-driven
 `);
 }

package/dist/src/lib/orchestrator-runner.d.ts

@@ -25,6 +25,8 @@ export interface OrchestratorRunnerConfig {
     callbacks?: OrchestratorCallbacks;
     /** Custom workflow template directory path */
     templateDir?: string;
+    /** Git repository URL for worktree cloning */
+    repository?: string;
 }
 export interface OrchestratorCallbacks {
     onIssueSelected?: (issue: OrchestratorIssue) => void;

package/dist/src/lib/orchestrator-runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/orchestrator-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAA;AAM7B,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,qBAAqB,CAAA;IACjC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5C,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC/C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAC1D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IAChD,SAAS,EAAE,YAAY,EAAE,CAAA;CAC1B;AAMD,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAYjD;AA0CD,wBAAsB,eAAe,CACnC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CA0FnC"}
+{"version":3,"file":"orchestrator-runner.d.ts","sourceRoot":"","sources":["../../../src/lib/orchestrator-runner.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,EAEL,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAA;AAM7B,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAA;IACpB,oCAAoC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,kDAAkD;IAClD,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,qBAAqB,CAAA;IACjC,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,iBAAiB,KAAK,IAAI,CAAA;IACpD,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC5C,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IAC/C,YAAY,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAA;IAC1D,iBAAiB,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;CAClD;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAA;IACrB,MAAM,EAAE,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,KAAK,CAAA;KAAE,CAAC,CAAA;IAChD,SAAS,EAAE,YAAY,EAAE,CAAA;CAC1B;AAMD,wBAAgB,UAAU,IAAI,MAAM,CASnC;AAED,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAYjD;AA0CD,wBAAsB,eAAe,CACnC,MAAM,EAAE,wBAAwB,GAC/B,OAAO,CAAC,wBAAwB,CAAC,CA6FnC"}

package/dist/src/lib/orchestrator-runner.js

@@ -86,6 +86,9 @@ export async function runOrchestrator(config) {
     if (config.templateDir) {
         orchestratorConfig.templateDir = config.templateDir;
     }
+    if (config.repository) {
+        orchestratorConfig.repository = config.repository;
+    }
     const orchestrator = createOrchestrator(orchestratorConfig, {
         onIssueSelected: cb.onIssueSelected,
         onAgentStart: cb.onAgentStart,

package/dist/src/orchestrator.js

@@ -31,6 +31,7 @@ function parseArgs() {
         wait: true,
         dryRun: false,
         templates: undefined,
+        repo: undefined,
     };
     for (let i = 0; i < args.length; i++) {
         const arg = args[i];
@@ -53,6 +54,9 @@ function parseArgs() {
             case '--templates':
                 result.templates = args[++i];
                 break;
+            case '--repo':
+                result.repo = args[++i];
+                break;
             case '--help':
             case '-h':
                 printHelp();
@@ -75,6 +79,7 @@ Options:
   --no-wait           Don't wait for agents to complete
   --dry-run           Show what would be done without executing
   --templates <path>  Custom workflow template directory
+  --repo <url>        Git repository URL for worktree cloning
   --help, -h          Show this help message
 
 Environment:
@@ -101,6 +106,7 @@ async function main() {
     console.log('========================');
     console.log(`Project: ${args.project ?? 'All'}`);
     console.log(`Max concurrent: ${args.max}`);
+    console.log(`Repo: ${args.repo ?? 'Any'}`);
     console.log(`Dry run: ${args.dryRun}`);
     console.log('');
     if (args.single) {
@@ -119,6 +125,7 @@ async function main() {
             wait: args.wait,
             dryRun: args.dryRun,
             templateDir: args.templates,
+            repository: args.repo,
         });
         if (!args.single && !args.dryRun) {
             console.log('');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supaku/agentfactory-cli",
-  "version": "0.7.10",
+  "version": "0.7.12",
   "type": "module",
   "description": "CLI tools for AgentFactory — local orchestrator, remote worker, queue admin",
   "author": "Supaku (https://supaku.com)",
@@ -89,9 +89,9 @@
   ],
   "dependencies": {
     "dotenv": "^17.2.3",
-    "@supaku/agentfactory": "0.7.10",
-    "@supaku/agentfactory-linear": "0.7.10",
-    "@supaku/agentfactory-server": "0.7.10"
+    "@supaku/agentfactory-server": "0.7.12",
+    "@supaku/agentfactory": "0.7.12",
+    "@supaku/agentfactory-linear": "0.7.12"
   },
   "devDependencies": {
     "@types/node": "^22.5.4",